Sessions

A session is the durable logical unit CompozyOS manages. Creation returns it active and unbound: it has a workspace, permission policy, event store, and attach record under one stable CompozyOS session ID, but no ACP process. The first prompt binds a provider runtime snapshot and starts ACP.

Live session events are written to events.db while the session runs. After the session stops, CompozyOS materializes a read-only forensic JSONL ledger at $COMPOZY_HOME/sessions/<workspace_id>/<session_id>/ledger.jsonl (or $COMPOZY_HOME/sessions/_unbound/<session_id>/ledger.jsonl when no workspace is resolved). The ledger is content-addressed and idempotent on rerun, never accepted as a memory scope, and never read by the recall pipeline — it is operator-readable history only.

Session-scoped Vault refs use vault:sessions/<session_id>/<name>. They are ordinary encrypted Vault records filtered by the session prefix, and the session inspector shows only redacted metadata for those refs.

Attach files to prompts

Upload a file with compozy session attachments upload <session-id> <file> -o json. The response returns an opaque att_... ID and attachment metadata. HTTP and UDS prompt requests send that returned metadata as a PromptAttachmentRef in attachments; the native compozy__session_prompt tool accepts the att_... ID or a file path under the resolved workspace root or configured additional_dirs. Attachment bytes remain in the workspace/session-scoped store and are opened only when the bound ACP agent advertises the negotiated capability for that attachment kind.

The v1 store accepts PNG, JPEG, WebP, PDF, Markdown, and plain text. Each file is limited to 10 MiB and each prompt to 10 files by default. CompozyOS ignores client-supplied Content-Type and detects MIME from file bytes. For valid UTF-8 text, a .md, .markdown, or .mdown name selects Markdown; otherwise CompozyOS uses plain text. Image bytes are preserved as received, including EXIF metadata. Images require ACP image input and PDFs require embedded context. Markdown and plain text fall back to text blocks when embedded context is unavailable.

Attachment metadata is durable in user-message events, so transcript and event reads can render the reference without embedding file contents. Archive and conversation clear keep files for the same session. compozy session remove removes that session's attachments, and compozy workspace remove removes the complete workspace attachment tree. Support bundles never include attachment bytes or paths.

Use this section when a live run needs supervision or forensic detail: why it started, what state it entered, which events were persisted, whether it can be attached, and which permission checks apply while the agent works. If the problem is choosing an agent definition, use Agents first. If the problem is the daemon or database itself, use Operations after you identify the affected session.

Browse the session catalog

compozy session list -o json returns a counted page owned by the daemon. Filter by workspace, exact agent, state, or session type; filter by resumability or a text query; choose recent or last_activity ordering; and add --include-health only when the caller needs the metadata-only health projection. For example, --type user --state active --sort last_activity returns active operator-created sessions ordered by their latest runtime activity. The response keeps rows under sessions and reports exact total, applied limit, has_more, and next_cursor values under page.

Archived sessions are omitted by default. Use --archived to return only archived sessions, or --include-archived to return archived and unarchived sessions together. Archiving changes catalog visibility, not the runtime state, and preserves the complete session record.

Use --cursor to continue with the same filters and sort. A cursor from another workspace or query is rejected instead of crossing catalog boundaries. See the generated compozy session list reference for every flag.

Find sessions that need attention

Session badges come from one daemon-owned precedence order. waiting-for-auth, waiting-for-input, and failed mean the session needs you. done means a turn settled while no operator client was visibly focused on the session, and the result has not been seen yet. Starting a new turn or entering a terminal lifecycle state outranks done; reading a session through the CLI or API never clears it.

Use compozy session list --attention for sessions that need you, or --badge done for finished sessions with unseen results. --all-workspaces removes the workspace filter, while --summary returns exact needs-you and finished totals for every workspace. Attention results use attention_changed_at for stable newest-first ordering. The generated compozy session list and Sessions API references own the exact flags, paths, and response schemas.

Questions and permission requests are durable interaction records. List the actionable projection with compozy session interactions <session-id> or GET /api/workspaces/{workspace_id}/sessions/{session_id}/interactions. Titles, choices, and resolutions are redacted and bounded before they reach a response. Pending records survive daemon restart; a request whose provider turn no longer exists is returned as orphaned and keeps the same interaction ID for explicit resolution.

Resolution outcomes distinguish the live and restart paths. A live permission decision reports applied, and a live clarification answer reports answered. Resolving an orphaned request reports resolved-after-restart; a repeat returns already-resolved with the original winning decision or answer. queue-full leaves the interaction pending and is safe to retry. Structured session status returns the canonical badge and the same bounded interaction projection.

Visible operator clients keep a per-client lease through POST /api/workspaces/{workspace_id}/sessions/{session_id}/presence. A live lease makes a settling turn seen, so it remains idle instead of becoming done. Each client renews and releases only its own opaque lease_id; abandoned leases expire after 15 seconds. Presence, attention summaries, and cross-workspace catalog reads are operator surfaces and reject agent identity with 403 agent_scope_denied. Interaction discovery accepts a validated agent identity only for that agent's workspace.

Browser clients can subscribe once to GET /api/sessions/catalog-stream. Each session_catalog_changed event identifies an upserted or deleted session and includes its authoritative workspace_id. The event is a wake signal, not a row delta: reconcile the counted catalog page for that workspace after every event. Catalog caches remain workspace-scoped, so an event must invalidate only keys owned by its workspace_id.

The same stream emits session_attention_changed after a committed badge edge. Its payload carries the old and new badge, the new attention class, workspace_id, and the canonical transition time. Extensions can observe the matching async-only session.attention.changed hook; observer failure does not roll back session state.

The reading order follows the lifecycle. Start with lifecycle for state names and stop classification, move to events when you need the durable record, then use resume attach and permissions for the two most common operator questions: "can I re-enter this live session?" and "why did CompozyOS ask before acting?"

In this section