Autonomy
Explicit operator control, coordinator handoff, task leases, optional Live coordination conversations, and safe spawn.
- Audience
- Operators running durable agent work
- Focus
- Autonomy guidance shaped for scanability, day-two clarity, and operator context.
Autonomy in Compozy lets managed agent sessions discover work, coordinate when a run explicitly resolves Live, and delegate bounded child sessions. Task execution is independent from Network participation: Local remains the default and uses the same task, lease, review, and spawn authority.
In this section
Coordinator handoff and configuration
Understand when the daemon starts one workspace coordinator, how provider/model settings resolve, and where manual control remains explicit.
Claim, heartbeat, complete, fail, and release
Use the session-bound task API correctly and keep raw lease credentials out of read models, logs, and channels.
Typed task execution profiles
Steer coordinator guidance, worker selection, reviewer routing, participant policy, and sandbox mode through one typed task-owned overlay.
Post-terminal review gate
Request reviews after terminal runs, route reviewers, persist typed verdicts, and create bounded continuation runs with missing-work guidance.
Bridge terminal notifications and cursor diagnostics
Deliver accepted-final terminal task notifications, advance durable cursors, surface delivery diagnostics, and seed SSE reconnects.
Notification Presets
Manage SQLite-backed fanout presets, cursor replay, filters, and bridge suppression.
Task-run coordination conversations
Opt future coordinated runs into bounded Live conversation while keeping task ownership and terminal status in the task service.
Bounded child sessions
Spawn workers with TTL, lineage, caps, and permission narrowing through the daemon-owned safe spawn contract.
The MVP flow
| Step | What happens | Starts execution? | Starts a coordinator? |
|---|---|---|---|
compozy task create or API create | Stores durable task intent. The task can be draft, blocked, or ready. | No | No |
compozy task publish, compozy task start, compozy task approve, UI start, or equivalent API | Enqueues a run and persists its resolved Local or Live participation snapshot. | Yes | Yes, if coordinator auto-start is enabled and no healthy workspace coordinator exists |
compozy task next | A managed agent session atomically claims one eligible queued run and receives a safe lease summary. | It owns the claimed run | No |
| Live Network conversation surfaces | Addressed participants exchange requests, blockers, handoffs, results, and review evidence. | May admit a bounded wake | No |
compozy spawn | A validated parent session asks the daemon to create a bounded child session. | Creates a child session only | No coordinator child sessions in the MVP |
The durable execution boundary is the run enqueue boundary, not task creation. The same boundary is used by manual operator starts, publish/approval flows, automation approvals, and coordinator-created follow-up tasks.
Which command owns what
The autonomy surface is exposed both as the dedicated compozy__autonomy tool family and as the
parallel compozy task CLI. Both routes call the same task service writers.
| Surface | Use it for | Do not use it for |
|---|---|---|
compozy me and compozy me context | Inspect the caller session, workspace, capabilities, active leases, and resolved participation. | Claiming or changing task-run state. |
compozy__task_run_claim_next (CLI: compozy task next) | Atomically claim the next eligible run for the current managed session. | Listing arbitrary tasks or announcing progress to peers. |
compozy__task_run_heartbeat, compozy__task_run_complete, compozy__task_run_fail, compozy__task_run_release | Extend or finish the current session-bound claim by run_id. | Conversation, review requests, or handoffs. |
| Live Network tools or audited CLI | Conversation for an explicitly participating session. | Enrolling a Local execution or changing task status. |
compozy spawn | Create a narrowed child session with TTL and lineage. | Starting a second coordinator or widening parent permissions. |
Manual and autonomous work coexist
Operators can still create tasks, start sessions, prompt sessions directly, and run counter-checks without involving autonomy. User-started sessions are normal root sessions. They may claim work when their capabilities match, but they can also be prompted directly through the session surface.
Coordinator sessions and spawned worker sessions are normal managed sessions with additional lineage and TTL metadata. They do not bypass task-run leases, hooks, permissions, workspace boundaries, or the immutable participation snapshot.
What is not in the MVP
The autonomy docs describe only the implemented local MVP. They do not promise:
- cross-daemon swarm coordination or leader election
- broad peer/channel memory extraction
- autonomy dashboards, lease dashboards, or spawn lineage trees in the web UI
- eval/replay harnesses
- a separate autonomous task queue
- relaxing the one-active-lease-per-session invariant
Related pages
- Task CLI Reference lists exact task commands and flags for the parallel CLI surface.
- Tool CLI Reference documents the operator commands that inspect the registry and the
compozy__autonomytool family. - Sessions explains session types, state, stop behavior, and persistence.
- Network Channels explains channel and peer behavior.
- config.toml documents
[roles.coordinator]and[task.orchestration]. - Task Execution Profiles documents the typed task-owned overlay used for coordinator guidance, worker selection, reviewer routing, participant policy, and sandbox mode.
- Review Gate documents the post-terminal review gate, reviewer routing, verdict semantics, and continuation runs.
- Notification Cursors documents bridge terminal notifications, durable cursor diagnostics, and SSE resume seeding.
- Hook Event Catalog lists
coordinator.*,task.run.*, andspawn.*hook events.