Tasks · Orbit Docs

Capture follow-up work

Tasks store intended work. Creating or assigning one does not launch an agent, schedule a wake-up, or authorise an external action.

{
  "title": "Prepare a partnership proposal draft",
  "description": "Use the research already linked to the project.",
  "due_at": "2026-10-10T09:00:00Z",
  "links": [
    {"type": "project", "id": "01900000-0000-7000-8000-000000000001"}
  ],
  "idempotency_key": "proposal-task-001"
}

Call tasks_create. title and idempotency_key are required. Optional fields are description, status, due_at (stored and returned in UTC), assigned_agent_id, custom_fields, and links. Task links can point to up to 20 unique active contacts, organisations, or projects in the same workspace.

Assign and update

assigned_agent_id must identify an active contributor in this workspace. Use the ID returned when issuing that agent's credential, or the current agent ID from workspace_context. Reader, revoked, or foreign agent IDs are rejected. Assignment expresses intended ownership, not an exclusive claim.

Call tasks_update with id, expected_revision, idempotency_key, and changes. Null clears assignment, due time, or description. Supplied links replace the previous list; an empty list removes all links. Omitted fields persist. Registered custom fields use explicit patches and removals.

Status and lifecycle

Statuses are open (default), in_progress, blocked, completed, and cancelled. Creation and ordinary updates accept only open, blocked, and cancelled. Claiming sets in_progress; only successful claim-based completion sets completed.

An in-progress task cannot be edited or archived through ordinary tools, even after expiry. Its owner must release it first; expired work must be reclaimed and then released. Completed tasks cannot be reopened; create a follow-up task. Other completed-task metadata remains editable with a revision check.

tasks_archive and tasks_restore retain history and require id, expected_revision, and idempotency_key. Archived tasks are hidden by default and must be restored before editing, claiming, or receiving new activity links.

Claim work

First retrieve the task and review its history. Call tasks_claim:

{
  "id": "01900000-0000-7000-8000-000000000001",
  "expected_revision": 1,
  "lease_seconds": 900,
  "idempotency_key": "proposal-attempt-001"
}

lease_seconds is optional: default 900 (15 minutes), minimum 60, maximum 3,600. Orbit atomically claims an open task or reclaims an in-progress task whose previous lease has expired. Blocked work must first be moved to open. Assignment is advisory: another contributor may claim unassigned or assigned work if no valid claim exists.

The result contains task, replayed, and current_claim_valid. The task includes claim_id, claim_owner_id, claim_expires_at, and its new revision. Two competing callers cannot both acquire a valid claim. A competing request may receive revision_conflict or claim_unavailable; read the current task before deciding what to do.

Claim ownership is not permission to send messages or take other external actions. Those still require your agent's normal authorisation.

Renew or release

tasks_claim_renew requires id, claim_id, expected_revision, and idempotency_key. Optional lease_seconds sets a new expiry measured from now with the same bounds. Renew before expiry; an expired claim cannot be revived. Renewal increments the task revision, so keep the latest response.

tasks_claim_release requires the same identity/revision/key fields plus status (open, blocked, or cancelled) and a nonempty reason of at most 2,000 characters. Only the current unexpired owner can release. The attempt retains its reason and is marked released, without recording completion. Release to open for a handoff, or blocked with an explanation when work cannot continue.

Complete with evidence

Append an activity of type task_outcome linked to this task using activity_append. Record what happened and any useful source references. Then call tasks_complete:

{
  "id": "01900000-0000-7000-8000-000000000001",
  "claim_id": "01900000-0000-7000-8000-000000000002",
  "expected_revision": 3,
  "outcome_id": "01900000-0000-7000-8000-000000000003",
  "idempotency_key": "proposal-complete-001"
}

Use returned IDs and revisions, not these placeholders. Only the owner of the current unexpired claim can complete. The outcome must be a non-redacted task_outcome in the same workspace, already linked to this task. Completion stores outcome_id and completed_at, clears the current claim, and closes the attempt as completed. Simply appending an outcome does not complete the task. No administrator override is exposed.

Retry and interrupted work

Every lifecycle mutation requires a new operation key for a new intent; an identical retry reuses the original key. Retries return the original task snapshot, which can have an old revision or expiry. current_claim_valid is checked again against current stored ownership and expiry; a replay of an expired or released claim cannot report it valid. Re-read the task for current metadata before continuing work. A lease can still expire after any response.

At expiry, ownership becomes invalid immediately without a worker or scheduled cleanup. The task remains in_progress to flag interrupted work, and claimable: true finds it. Reclaim creates a new claim ID and preserves the old attempt as expired. Never assume an expired attempt did nothing: inspect the external system before retrying a side effect. Orbit prevents simultaneous valid owners, not duplicate actions outside Orbit.

tasks_attempts requires id and accepts page, per_page (default 20, maximum 50), and include_archived. It returns attempts, page, per_page, has_more, and next_page, newest first. Each attempt includes its owner, claimed/expiry/end timestamps, release reason or outcome ID, and computed state (active, expired, released, completed). An expired attempt may have no stored ended_at until reclaimed; its computed state is already expired.

Find outstanding work

tasks_search supports:

Literal title/ID query, exact status, and assigned_agent_id.
unassigned: true for tasks with no intended owner; do not combine with assigned_agent_id.
claimable: true for non-archived open tasks or expired in-progress tasks.
due_from and due_to as inclusive UTC calendar dates.
overdue: true for open/in-progress/blocked tasks due before now.
outstanding: true for open/in-progress/blocked tasks, regardless of due date.
A paired record_type and record_id for directly linked work.
Registered scalar custom_fields equality filters, include_archived, and pagination.
sort: title (default), due_at, created_at, or updated_at; direction: asc (default) or desc. Undated values sort last; ID ascending breaks ties.

All filters combine with AND. Default page size is 20, maximum 50. tasks_get returns one task and its links. Briefs include directly linked outstanding tasks, excluding completed and cancelled tasks and indirectly related work.