Skip to main content

Session file authority

Status: binding companion to ADR-046

One authority​

Every file owned by managed Hermes is one object in the organization's cloud AgentFS database. Organization defaults and shared skills/memory live at the root; each conversation has a private configuration, state, work, artifacts, and logs subtree. There is no per-session AgentFS database.

Neither an execution sandbox nor the Humanwork API creates a second durable copy. R2/object storage may serve unrelated non-session product assets, but it is not a backing store, publication target, download authority, or compatibility fallback for managed-session files.

authenticated source
  -> one cloud AgentFS object
  -> authorized product metadata records its conversation-scoped file URI
  -> native ACP may carry that same structured locator for the actual turn
  -> Hermes/native tools see the same object through /workspace or /artifacts
  -> authorized API reads the same object for the client

Responsibility boundary​

  • Humanwork API: authenticates the caller/source, opens cloud AgentFS directly with runtime-only credentials, writes or reads the exact object, and enforces quotas and access. For a real attachment, it sends the exact native ACP image/audio/resource/embedded-resource block that upstream Hermes already accepts; it does not invent a prompt descriptor or transport bytes through hermes-run.
  • Resident Bun machine: owns one local organization AgentFS writable overlay, just-bash, and HyperSH Git. It gives each Hermes child a conversation-scoped merged filesystem view.
  • Hermes: receives only the exact user message, sees existing AgentFS files through normal filesystem paths, and creates outputs with normal tools.
  • hermes-run: supervises ACP only. It does not expose append, hydrate, flush, export, inspect, upload, download, or file-byte frames.
  • SessionDB: is one separate organization transcript database. Native session_id distinguishes conversations. It stores canonical messages, not file bytes or an AgentFS database file.

Identity and idempotency​

A canonical file:///artifacts/inbound/..., file:///artifacts/outbound/..., or file:///workspace/... URI is the file identity across authorization-scoped attachment metadata, native ACP resource blocks, API responses, and downloads. It is identity, not authority: every operation still authorizes the conversation. It is not replaced with an R2 key, signed URL, Postgres UUID, platform message UUID, host path, or a second AgentFS path.

There is no global outbound directory to clear or scan and no .humanwork/turns tree. Conversation isolation and deterministic object identity prevent concurrent turns from deleting or claiming one another's files.

Native Turso freshness​

The supervisor-resident Bun machine retains one organization AgentFS overlay. At an AgentFS work boundary it uses Turso's native sequence: plain pull, local work, a second plain pull that applies remote changes and replays unpushed local changes, then push only when native CDC is pending. Native last-push-wins conflict handling is authoritative. There is no Redis subscriber, application event, revision comparison, ACP control frame, prompt inspection, timer, held request, long poll, or Humanwork merge layer. Idle time performs no sync request, and read-only state produces no empty push.

Isolation​

Every read/write authorizes org, conversation, Specialist assignment, and session before opening AgentFS. Conversation Hermes children can access their private subtree plus deliberately exposed shared memory/skills, but not the organization's private root configuration or another conversation. Standard virtual file URIs are parsed and canonicalized strictly; path traversal, cross-session authority, symlinks/unsupported object kinds, size/count violations, missing credentials, and revision conflicts fail closed. Credentials never enter model content, client responses, logs, or persistent transcript prose.

Explicitly retired shapes​

  • host/container workspace staging and mounted session homes;
  • Python R2/local/base64 file exchange;
  • API-to-runner file commands or bytes;
  • shared outbound dropboxes and completed-turn copies;
  • R2 promotion followed by signed-URL transcript metadata;
  • fabricated [Media message] placeholders; and
  • periodic AgentFS/file-list polling.

The executable removal status is tracked by the ADR-046 remediation ledger. A green health endpoint or container start is not acceptance; verification must cover a real browser-visible attachment round trip and reload.

Last updated on by Degen