Managed Hermes file API

Authority: ADR-046 Architecture: Session file authority

This is the managed-session contract. Cloud AgentFS is the sole durable authority for inbound attachments, generated files, skills, memory, and workspace content. SessionDB is the sole transcript authority. R2, base64, local directories, host paths, and hermes-run file commands are not alternate managed transports.

Inbound

1. Authenticate the upload/channel source and authorize the target org, conversation, and Specialist.
2. Write exactly one object to the organization's cloud AgentFS under the authorized conversation's artifacts/inbound/ tree. Use a deterministic object locator so retry is idempotent; do not create a per-turn directory or a second attachment copy.
3. Fail the complete turn if any supplied object cannot be committed or verified. Do not silently continue as text-only.
4. Send the actual inbound message as native ACP content blocks without rewriting them. Text remains text. Each attachment is its own real ACP resource, image, audio, or embedded-resource message/block and references the AgentFS-visible object. Do not inline bytes, invent a descriptor or prose placeholder, or associate the file with a different transcript row.

An attachment-only turn is valid. No placeholder prose is invented.

Outbound

Hermes creates a generated file directly in AgentFS. ACP completion does not wrap, project, or transport a file manifest. The object is not copied to a shared dropbox, turn-completed path, R2 bucket, Postgres row, or inline response. The authorized download endpoint resolves the managed virtual file URI, checks access, reads a bounded regular object from cloud AgentFS, and streams it to the caller.

SessionDB stores canonical message prose, not file bytes or a synthetic attachment description. Access-controlled product metadata may reference the exact locator, never a signed URL, host path, base64 body, or second durable copy.

Synchronization and reads

• One supervisor-resident Bun machine owns the local writable overlay for the organization's AgentFS; conversation Hermes children receive scoped views of that same overlay.
• An AgentFS work boundary uses Turso's native plain sequence: pull, perform local work, pull again so remote changes are applied and unpushed local changes are replayed, then push only when native CDC is pending.
• Direct API cloud writes need no Redis, product event, application revision, ACP sync signal, timer, or long poll. Native conflict handling remains last-push-wins; Humanwork does not add a merge layer.
• Idle time performs no sync request. Explicit user open/download/refresh may make one bounded authorized API read.

Failure behavior

Malformed locators, traversal, unsupported object kinds, missing credentials, quota violations, read failures, revision conflicts, and scope mismatches fail closed. They do not fall back to R2, local storage, inline bytes, a fabricated message, or an empty success response.

Required evidence

• the exact native ACP content blocks accepted at the API boundary reach Hermes unchanged;
• the stored bytes have one AgentFS identity before and after reload;
• attachment-only input works without fabricated prose;
• a no-file/read-only turn performs no AgentFS sync or empty push;
• one API cloud mutation is observed after the next native plain pull without a product sync signal;
• one Hermes mutation produces native CDC and is pushed;
• download authorization rejects cross-org/cross-Specialist locators; and
• no managed payload contains content_base64, an R2 key, a host path, or a runner file command.