51 lines
2.1 KiB
Markdown
51 lines
2.1 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?, 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.
|
|
|
|
Filters:
|
|
|
|
- `path` — path prefix, e.g. `output/`.
|
|
- `sourceKind` — filter by source kind.
|
|
- `createdByTaskId` / `lastModifiedByTaskId` — filter by task.
|
|
- `includeUnknown` — set `false` to hide `unknown` / `imported_existing` files.
|
|
|
|
## 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.
|