Skip to content

Commit b000a2c

Browse files
alliscodeCopilot
alliscode
and
Copilot
authored
Python: Adding AgentFileStore and FileAccessProvider to support file access operations. (#6099)
* Adding AgentFileStore and FileAccessProvider to support file ased operations for agents. * Address PR review feedback on FileAccessProvider - Probe symlinks on the unresolved candidate path so in-root symlinks cannot silently pass and out-of-root symlinks surface the correct error message. - Validate matching_lines elements in FileSearchResult.from_dict and raise a clean ValueError for non-mapping entries. - Cap search regex pattern length (256 chars) via a new _compile_search_regex helper to mitigate ReDoS, and surface the cap in the file_access_search_files tool description. - Skip non-UTF-8 files during filesystem search instead of aborting the entire directory walk. - Replace the module-scope trailing string in the data-processing sample with comments to avoid Ruff B018. - Remove the checked-in working/region_totals.md sample artifact so the save flow works from a clean checkout. - Expand the Windows stdout reconfiguration comment in task_runner.py for clarity. - Add tests for invalid/oversize regex, non-UTF-8 file search, and in-root symlink rejection. Co-authored-by: Copilot <[email protected]> * Fix mypy redundant-cast in FileSearchResult.from_dict Use cast(list[object], ...) instead of cast(list[Any], ...) so the cast represents a real type change (lists are invariant) and is no longer flagged by mypy as redundant, while still satisfying pyright's reportUnknownVariableType. Matches the existing pattern in _memory.py. Co-authored-by: Copilot <[email protected]> * Tighten path normalization and directory resolution in FileAccess - _normalize_relative_path now strips surrounding whitespace up front so leading/trailing spaces never leak into file segments, and rejects trailing path separators for file paths so 'foo/' is no longer silently coerced to 'foo'. - FileSystemAgentFileStore._resolve_safe_directory_path normalizes with is_directory=True and maps an empty normalized result to the root. This matches InMemoryAgentFileStore so whitespace-only directory inputs resolve to the root instead of raising. - Added tests for whitespace stripping, trailing-separator rejection, and whitespace-only directory listing on the filesystem store. Co-authored-by: Copilot <[email protected]> * Harden FileAccess search and atomic save in store API - Add wall-clock timeout (10s) around regex scans so a pathological pattern (e.g. `(a+)+`) below the length cap cannot stall the event loop. - Offload the InMemoryAgentFileStore regex scan to a worker thread, matching the filesystem store. - Fail closed when `Path.is_symlink` raises during the safe-path probe so a permission error cannot silently bypass the symlink/reparse-point rejection. - Add `overwrite: bool = True` to `AgentFileStore.write_file`; the in-memory store performs the check under the existing lock and the filesystem store uses `open(mode='x')` so concurrent callers cannot race past `overwrite=False`. - `file_access_save_file` now relies on the atomic store call instead of a separate `file_exists` round-trip. Co-authored-by: Copilot <[email protected]> * Fix Python 3.10 timeout handling and add directory arg to list/search tools - Catch asyncio.TimeoutError in _run_search_with_timeout. In Python 3.10 asyncio.wait_for raises asyncio.exceptions.TimeoutError, which is distinct from the builtin TimeoutError (the two were unified in 3.11). Catching the asyncio alias works on every supported version. - Add an optional directory parameter to file_access_list_files and file_access_search_files so agents can enumerate / scope searches to nested folders, not just the store root. Co-authored-by: Copilot <[email protected]> * Address FileAccess review feedback: case, errors, signal, TOCTOU - InMemoryAgentFileStore now stores (display_name, content) so list_files and search_files return the original-case names callers wrote, matching the behaviour of FileSystemAgentFileStore on case-preserving filesystems and removing the silent in-memory vs. on-disk contract divergence. - FileSystemAgentFileStore.read_file raises ValueError instead of letting UnicodeDecodeError bubble for binary / non-UTF-8 input, restoring symmetry with search_files (which still skips) and giving the tool layer a recoverable type to translate. - Tool wrappers now catch ValueError and OSError around every operation and surface them as readable strings, so 'you used ..' and 'the file already exists' are both reported to the model the same way instead of the former crashing out as an unhandled exception. - _search_files_sync logs per skipped non-UTF-8 file at WARNING and an aggregate INFO summary so operators can distinguish 'no matches' from 'half the corpus was unreadable'. - FileSystemAgentFileStore softens its docstrings to acknowledge the inherent probe-then-open TOCTOU window. On POSIX both read and write now pass O_NOFOLLOW so the kernel refuses if the leaf segment becomes a symlink between the probe and the open. Windows has no equivalent flag; the limitation is documented. - Tests cover: case preservation on list/search, ValueError on non-UTF-8 read at the store and tool layer, tool-layer string responses for path-traversal and oversized-regex inputs, search-skip log output, symlink rejection on delete/search/list, and symlinked intermediate directory rejection. Co-authored-by: Copilot <[email protected]> * Address FileAccess nit comments: docstrings, enumerate, opt-in delete approval - Expand FileSearchMatch/FileSearchResult.to_dict docstrings to explain why the override is needed (__slots__ defeats the mixin's __dict__ iteration) and why exclude/exclude_none are accepted-but-ignored (mixin signature compatibility for callers like to_json). - Use enumerate(lines, start=1) in _search_file_content so the +1 below is no longer needed; rename loop variable to line_number for clarity. - Add opt-in require_delete_approval: bool = False on FileAccessProvider. When True, file_access_delete_file is registered with approval_mode 'always_require' so the host must approve every delete. Default False preserves current behaviour and matches the .NET reference, but deployments that want a safer-by-default posture can enable it. - Add tests covering both delete approval modes. Co-authored-by: Copilot <[email protected]> * FileAccess: require delete approval by default Flip the default for FileAccessProvider(require_delete_approval=...) from False to True so destructive deletes are gated by host approval out of the box. Callers that want the previous autonomous behaviour (which matches the .NET reference) can pass require_delete_approval=False. Tests updated accordingly. Co-authored-by: Copilot <[email protected]> * Fixing linkinspector by installing Chrome for puppeteer first. --------- Co-authored-by: Ben Thomas <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 0578f4c commit b000a2c

10 files changed

Lines changed: 2040 additions & 2 deletions

File tree

‎.github/workflows/markdown-link-check.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ jobs:
2323
with:
2424
persist-credentials: false
2525

26+
- name: Set up Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: 20
30+
31+
- name: Install Chrome for Puppeteer
32+
run: npx puppeteer browsers install chrome
33+
2634
# Checks the status of hyperlinks in all files
2735
- name: Run linkspector
2836
uses: umbrelladocs/action-linkspector@963b6264d7de32c904942a70b488d3407453049e # v1

‎python/packages/core/AGENTS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,14 @@ agent_framework/
7676
- **`SkillScriptRunner`** - Protocol for file-based script execution. Any callable matching `(skill, script, args) -> Any` satisfies it. Code-defined scripts do not use a runner.
7777
- **`SkillsProvider`** - Context provider (extends `ContextProvider`) that discovers file-based skills from `SKILL.md` files and/or accepts code-defined `Skill` instances. Follows progressive disclosure: advertise → load → read resources / run scripts.
7878

79+
### File Access Harness (`_harness/_file_access.py`)
80+
81+
- **`AgentFileStore`** - Abstract async store backing the file-access harness. Implementations expose `write_file`, `read_file`, `delete_file`, `list_files`, `file_exists`, `search_files`, and `create_directory` over forward-slash relative paths.
82+
- **`InMemoryAgentFileStore`** - Dict-backed store suitable for tests and lightweight scenarios.
83+
- **`FileSystemAgentFileStore`** - Disk-backed store rooted under a configurable directory. Enforces relative-path normalization, root containment, and rejects symlink/reparse-point segments to prevent escape.
84+
- **`FileSearchResult`** / **`FileSearchMatch`** - `SerializationMixin` DTOs returned by `search_files`, carrying the matching file name, a context snippet, and the matching lines with 1-based line numbers.
85+
- **`FileAccessProvider`** - `ContextProvider` that adds shared file-access tools (`file_access_save_file`, `file_access_read_file`, `file_access_delete_file`, `file_access_list_files`, `file_access_search_files`) plus default usage instructions to each invocation. Unlike `MemoryContextProvider`, the store is intentionally shared across sessions and agents.
86+
7987
### Workflows (`_workflows/`)
8088

8189
- **`Workflow`** - Graph-based workflow definition

‎python/packages/core/agent_framework/__init__.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,16 @@
9090
BackgroundTaskInfo,
9191
BackgroundTaskStatus,
9292
)
93+
from ._harness._file_access import (
94+
DEFAULT_FILE_ACCESS_INSTRUCTIONS,
95+
DEFAULT_FILE_ACCESS_SOURCE_ID,
96+
AgentFileStore,
97+
FileAccessProvider,
98+
FileSearchMatch,
99+
FileSearchResult,
100+
FileSystemAgentFileStore,
101+
InMemoryAgentFileStore,
102+
)
93103
from ._harness._memory import (
94104
DEFAULT_MEMORY_SOURCE_ID,
95105
MemoryContextProvider,
@@ -309,6 +319,8 @@
309319
"APP_INFO",
310320
"COMPACTION_STATE_KEY",
311321
"DEFAULT_BACKGROUND_AGENTS_SOURCE_ID",
322+
"DEFAULT_FILE_ACCESS_INSTRUCTIONS",
323+
"DEFAULT_FILE_ACCESS_SOURCE_ID",
312324
"DEFAULT_HARNESS_INSTRUCTIONS",
313325
"DEFAULT_MAX_ITERATIONS",
314326
"DEFAULT_MEMORY_SOURCE_ID",
@@ -334,6 +346,7 @@
334346
"AgentExecutor",
335347
"AgentExecutorRequest",
336348
"AgentExecutorResponse",
349+
"AgentFileStore",
337350
"AgentFrameworkException",
338351
"AgentMiddleware",
339352
"AgentMiddlewareLayer",
@@ -393,11 +406,15 @@
393406
"ExperimentalFeature",
394407
"FanInEdgeGroup",
395408
"FanOutEdgeGroup",
409+
"FileAccessProvider",
396410
"FileCheckpointStorage",
397411
"FileHistoryProvider",
412+
"FileSearchMatch",
413+
"FileSearchResult",
398414
"FileSkill",
399415
"FileSkillScript",
400416
"FileSkillsSource",
417+
"FileSystemAgentFileStore",
401418
"FilteringSkillsSource",
402419
"FinalT",
403420
"FinishReason",
@@ -414,6 +431,7 @@
414431
"GeneratedEmbeddings",
415432
"GraphConnectivityError",
416433
"HistoryProvider",
434+
"InMemoryAgentFileStore",
417435
"InMemoryCheckpointStorage",
418436
"InMemoryHistoryProvider",
419437
"InMemorySkillsSource",

0 commit comments

Comments
 (0)