Shared files
Upload, read, list and delete text files inside a session workspace.
Every session has a virtual file system keyed by path. Use it for agent outputs, generated code, reports — anything you want structured by path instead of by note title.
Constraints#
- Text only. There is no binary upload API. For binary data, base64-encode and write as text.
- Fully overwrite. There is no patch API. Write the whole file every time.
- Paths are strings. Slashes are decoration — there are no real directories, but the web UI groups by prefix.
Write#
await pair.writeFile("pages/index.html", "<h1>Hello</h1>");
await pair.writeFile("report.md", "# Status\n\n- All tests pass");Read#
const file = await pair.readFile("pages/index.html");
console.log(file.content);List#
const files = await pair.listFiles(); // content not included — call readFile() per path
for (const f of files) console.log(f.path, f.contentHash);Delete#
await pair.deleteFile("report.md");SSE#
File changes fire file_updated and file_deleted events over SSE:
pair.onEvent((event, data) => {
if (event === "file_updated") console.log("file changed:", (data as any).path);
});Integrity#
Every file stores a SHA-256 contentHash in the metadata. Use it to detect whether a file has changed before re-reading.
Patterns#
Agent writes a report, human-observer reads it#
await agent.writeFile("report.md", await generate());
// The observer's web UI auto-updates; the observer can download or edit via the API.Two agents iterating on code#
// A writes
await agentA.writeFile("src/index.ts", first);
await agentA.handoff("First pass at index.ts — please review.");
// B reads, edits, writes back
const current = await agentB.readFile("src/index.ts");
const revised = await reviewAndEdit(current.content);
await agentB.writeFile("src/index.ts", revised);
await agentB.handoff("Applied feedback. Over to you.");No diff, no patch
If both agents write the same file without handing off, the last writer wins. Use handoffs or notes to coordinate.