Artifacts

Artifact writes from TypeScript tools use ctx.artifacts. A tool can call read(path), write(path, content, { mimeType }), and list(). Writes accept text or Uint8Array content and are staged with the durable tool step, so a recovered run reuses its recorded write rather than executing it twice.

Plico stores content bytes once per SHA-256 hash in SQLite. Text stays readable as text, and binary event content uses a tagged base64 value on JSON surfaces. A Uint8Array returned from a tool is encoded as tagged base64 in its result event.

Workspaces and versionsCopy Anchor Link

Workspace responses expose the latest files and an ordered version receipt history for each run. Thread runs share one ordered workspace: GET /v1/threads/<thread-id>/workspace returns its current files and versions, and every version identifies the writing run. A run workspace includes files inherited from earlier turns and shows the state as of that run.

Diffs and exportsCopy Anchor Link

Compare two writes with GET /v1/runs/<run-id>/workspace/diffs?path=<path>&fromVersion=1&toVersion=2. Diffs accept text, JSON, and XML artifacts up to 1 MiB per version; binary or larger versions are rejected.

Download a file with GET /v1/runs/<run-id>/workspace/exports?path=<path>. The response is an attachment with the stored content and media type. Binary files can be written and exported byte for byte.

Model-facing toolsCopy Anchor Link

Provider-backed runs have four built-in tools for this workspace: list_files, read_file, write_file, and edit_file. The names are reserved. Set artifacts.access in plico.config.ts to read-write, read-only, or off; it defaults to read-write. Read-only mode offers listing and reading. Off hides all four tools while leaving ctx.artifacts available to trusted project tools.

• list_files accepts *, **, ?, and comma-separated brace alternatives (for example reports/*.{md,txt}). It returns paths in sorted, paginated order, 100 files per page by default.
• read_file uses a 1-indexed line offset, defaults to 200 lines, and limits text output to 32 KiB per call. Binary files return metadata without their bytes.
• write_file creates or overwrites text, infers the MIME type from the extension, and allows an explicit mimeType override.
• edit_file replaces exact text and requires one match unless replaceAll is true.

Both write tools use the staged workspace path and enforce the 1 MiB content limit.