files— the bytes plus content metadata (mimeType, sizeBytes, filename).fileBindings— what each file is for — workflow output, run scratch, worker-scoped reference material, chat attachment.
putFile— persist bytes to platform storage and create a binding in the right domain.getFile— read a file the dispatch has access to, either as extracted text, copied into a sandbox VM, or as metadata only.
type: "file" / "file[]". The orchestrator pre-resolves an authorization struct at injection time; every tool call is checked against that struct. An agent cannot use putFile to write under an output key the node did not declare, nor getFile to read a file outside the dispatch’s input set.
This model replaces the retired writeArtifact, readArtifact, copyFileToSandbox, and importFileFromSandbox tools. New code uses putFile and getFile.
When the tools are available
putFile and getFile are not in any named tool set. They are injected per-node by the orchestrator at dispatch time:
- A node with at least one
type: "file"/"file[]"output declaration receivesputFile, bound to the declared output keys. - A node with at least one
type: "file"/"file[]"input receivesgetFile, bound to the inboundfileIdset resolved from upstream.
putFile: the writer
putFile is the canonical writer for the unified model. Its surface is agnostic to how the bytes were produced — the agent picks a source (where the bytes come from) and a bind (what domain the resulting binding belongs to). The platform persists the bytes via the file_hosting capability, inserts a files row, inserts a fileBindings row, and returns a fileId the agent places into its structured output.
source — where the bytes come from
bind — what domain the file belongs to
Outputs
The tool returns a JSON string. On success:ProcedureApiError; author code should branch on its code rather than message text.
The current agent tool names are file_put and file_get; putFile and getFile remain deprecated aliases used by the examples below.
The fileId contract
A workflowfile output is structurally a string (file[] is an array of strings). After structural parsing, validateFileOutputBindings verifies that every returned id matches an authorized binding produced for that dispatch. A plausible-looking identifier is insufficient. The agent satisfies this contract by:
- Calling
putFile({ source, bind: { kind: "workflow_output", outputKey }, … }). - Reading
fileIdfrom the tool’s JSON result. - Placing that
fileIdinto the corresponding field in its structured output.
generateObject call occurs only when the structured turn needs repair. The validator rejects raw content — the fileId is the only legitimate way to satisfy the schema.
getFile: the reader
getFile reads a file the dispatch has access to. It has three modes — text, sandbox, meta — that cover the three things an agent needs to do with an inbound file: read the content, hand it to a script, or check whether it’s worth reading at all.
Modes
Authorization
The injection-timeGetFileBinding carries the exact fileId set the dispatch may read. A getFile call with a fileId not in that set fails with an authorization error before any storage call is issued. Inbound fileIds are pre-resolved from upstream node outputs by the orchestrator — the agent never has to know how upstream files reached its input set.
End-to-end flow
A workflow with two file-bound nodes — aproduce node that emits a PDF report, then a downstream node that summarises it.
Isolation guarantees
- Per-node authorization. Both tools are bound at injection time to the executing node’s
runId,stepId, and the exact set of declared file inputs/outputs. An agent cannot useputFileto write under a key the node did not declare; it cannot usegetFileto read afileIdoutside its dispatch’s input set. - Skill-constraint exemption. Both tools are added after agent composition, so they are not subject to skill allowlist narrowing. Their own per-call authorization (outputKey ∈ writableOutputKeys, fileId ∈ readableFileIds) is stricter than any skill allowlist could express.
load_skillfollows the same pattern. - Capability-routed. Both tools resolve the active
file_hostingandsandboxcapabilities at call time via the capability registry (see Capability Architecture). The tool surface is unchanged regardless of which underlying provider holds the bytes.
Direct transfer and retention
Direct transfer specifications report the provider’s actual URL expiry and which requested restrictions it enforces. The internal provider has a fixed upload-URL lifetime and download URLs without expiry. Consumers enforce their own byte and time limits and verify measured size and content digest before publishing a file binding. A dispatched upload whose result is unknown is recorded as unknown; it does not automatically mint another URL and upload a second copy. Upload and download bearer URLs and headers travel through private, cleaned-up curl configuration files inside the sandbox. They stay out of process arguments and ordinary error diagnostics. File evidence follows its owning workflow or debug attempt. Existing run retention keeps completed and failed runs for 180 days and cancelled runs for 30 days, and waits for step-result cleanup. Declaredfile and file[] launch inputs acquire consumer-owned run_scratch retention leases
in the run-creation transaction, including draft and replay launches. A prepared debug attempt
acquires its debug_input bindings in the preparation transaction. Each lease reads canonical
file existence, so producer expiry either preserves the admitted consumer’s input or wins first
and causes admission to fail. These references retain bytes; existing typed-input and file-read
authorization still govern access. File-shaped strings inside JSON do not create leases.
Inputs of runs and debug attempts that existed before these leases are given leases in the
background. Run and debug cleanup stay paused until that backfill has finished for both. Until
then, nothing is deleted: runs, attempts, bindings, metadata, and bytes are all kept, and an
interrupted backfill resumes where it stopped. New runs and debug attempts acquire their leases
as usual while the backfill runs.
The run backfill uses the recorded immutable version’s input schema, including terminal runs still
inside retention. Historical draft runs have no frozen input schema. For those runs, or when the
recorded version/schema cannot be recovered, it conservatively retains existing canonical file IDs
anywhere in persisted arguments, including JSON. This fallback grants no read authority. Hard bounds
on argument traversal and canonical lookups fail the page rather than silently skipping dependencies.
Debug backfill uses frozen typed resolved inputs, recovering IDs from their stored values when the
optional projection is absent. After both passes succeed, the existing retention periods and bounded
cleanup release leases normally. Bindings whose producer run already disappeared remain unowned
unknown references; this rollout does not perform historical orphan collection.
At expiry, bounded cleanup drains that run’s output and scratch bindings before removing the run.
Debug-attempt expiry removes its own bindings under its existing policy. After the final binding
disappears, cleanup deletes unowned internal-provider bytes and metadata in the same transaction.
Any surviving binding or independent external owner keeps the file alive. A binding writer checks
the canonical file still exists, so a stale writer cannot reattach already deleted evidence.
This owner-driven cleanup does not identify arbitrary orphan objects after an upload response is
lost. Failed or unacknowledged uploads stay unresolved when atomic, reference-safe deletion cannot
be proven. Each upload attempt has a distinct claim identity; replaying a previously claimed object
cannot adopt or delete it. A returned object ID, matching size, or digest alone never authorizes
cleanup of storage bytes.
Migration from the legacy quartet
The legacy tools —writeArtifact, readArtifact, copyFileToSandbox, importFileFromSandbox — were deleted in PR-8h. The mapping is straightforward:
Each legacy operation maps cleanly to one
putFile or getFile call. The unified surface adds three things the legacy quartet did not have:
rendersource — server-side document/table/workbook rendering without the agent having to materialize bytes in-thread.bind: "run_scratch" | "worker_scope" | "chat_attachment"— first-class binding domains the legacy quartet did not express.mode: "meta"— an agent can decide whether to open a file before paying the extraction cost.

