66 lines
2.8 KiB
Markdown
66 lines
2.8 KiB
Markdown
# GetFileProvenance / ListWorkspaceFiles
|
|
|
|
Workspace file provenance tools. In a persistent (shared) workspace, files can
|
|
outlive a single task: an old task's inputs and outputs stay visible to later
|
|
tasks. These tools let you tell WHO a file belongs to before you edit or rely on
|
|
it.
|
|
|
|
Both are META tools — always available regardless of the workspace tool policy.
|
|
|
|
## When to use
|
|
|
|
- Before editing a file whose relevance to the current task is unclear.
|
|
- When you see a file in `input/` or `output/` that you did not create this run.
|
|
- To find which files the current task actually produced vs. inherited.
|
|
|
|
## GetFileProvenance({ path })
|
|
|
|
Returns a compact record for one file (workspace-relative path, e.g.
|
|
`output/report.md`):
|
|
|
|
- `source_kind` — one of `user_input`, `agent_output`, `agent_edit`,
|
|
`bash_generated`, `subtask_output`, `imported_existing`, `unknown`.
|
|
- `created_by_task_id` — the task that first created/uploaded the file.
|
|
- `created_by_piece` / movement — the piece + movement that created it.
|
|
- `last_modified_by_task_id` + `last_modified_at`.
|
|
|
|
If there is no record (a file that pre-dates the ledger), you get an
|
|
`unknown`-equivalent message — treat the file as possibly belonging to another
|
|
task and verify its contents before overwriting.
|
|
|
|
## ListWorkspaceFiles({ path?, sourceKind?, createdByTaskId?, lastModifiedByTaskId?, since?, until?, includeUnknown?, limit? })
|
|
|
|
Returns a bounded listing (default 50, max 200 rows) of known files with a
|
|
one-line provenance summary each. It never returns file contents. Each line
|
|
starts with the file's **date**.
|
|
|
|
Filters:
|
|
|
|
- `path` — path prefix, e.g. `output/`.
|
|
- `sourceKind` — filter by source kind.
|
|
- `createdByTaskId` / `lastModifiedByTaskId` — filter by task.
|
|
- `since` / `until` — date range, inclusive on both ends. Accepts `YYYY-MM-DD`
|
|
or a full ISO timestamp; a bare `until` date covers that whole day.
|
|
- `includeUnknown` — set `false` to hide `unknown` / `imported_existing` files.
|
|
|
|
### The date
|
|
|
|
A file's date is `last_modified_at`, falling back to `first_seen_at`. Display,
|
|
ordering and `since` / `until` all use that same one date, so a date you read
|
|
off a listing can be pasted straight back into a range filter.
|
|
|
|
### Selecting only this task's files
|
|
|
|
The job's context block carries `このタスクの番号: <id>`. Pass it as
|
|
`createdByTaskId` to see only what this task made, or use it to tell your own
|
|
files apart from ones that were already in the workspace.
|
|
|
|
## Guidance
|
|
|
|
- Do NOT blindly edit files whose `source_kind` is `user_input` or whose
|
|
`created_by_task_id` differs from the current task. Prefer creating a new file
|
|
under `output/`.
|
|
- These tools report task/job IDs only — never task titles or user identities.
|
|
- The tools are scoped to the current run's workspace; you cannot inspect other
|
|
workspaces.
|