Smart Agent TeamsStatuses and enums
Every status and enumerated value in SAT, what each one means, and what moves an object between them.
These are the exact values the API accepts and returns. They are defined in apps/api/company/schemas.py and apps/api/database/company_models.py, and the labels and order the web app and CLI show come from libs/api-client/src/vocabulary.ts.
Task status
TaskStatus. Default for new tasks: todo.
| Value | Label | Meaning | Set by |
|---|---|---|---|
backlog | Backlog | Captured, not ready to work on | A person or agent. Assigning a backlog task does not wake the agent. |
todo | Todo | Ready to start | Default on create; a person or agent |
in_progress | In progress | Being worked on. Moving here stamps started_at the first time. | The runner, when a run starts on a backlog or todo task; a person or agent |
in_review | In review | Work is done and waits for a person to check it | The runner, when a run succeeds (default --on-success in_review); a person or agent |
blocked | Blocked | Cannot continue without help | The runner, when the agent's reply starts with BLOCKED:; a person or agent |
done | Done | Finished. Moving here stamps completed_at; leaving done clears it. | A person or agent; the runner with --on-success done |
cancelled | Cancelled | Will not be done | A person or agent |
Board columns, in order: backlog, todo, in_progress, in_review, blocked, done. Any status can move to any other; there is no enforced workflow. Assigning (or reassigning) a task whose status is not backlog, done or cancelled to an available agent queues an assignment run.
Task priority
TaskPriority. Default: medium.
| Value | Label |
|---|---|
urgent | Urgent |
high | High |
medium | Medium |
low | Low |
none | No priority |
Goal status
GoalStatus. Default: active.
| Value | Meaning |
|---|---|
planned | Agreed but not started |
active | Being pursued |
achieved | Reached |
abandoned | Dropped |
Goal status is set only by people and agents; it does not change automatically when linked tasks finish. Progress (tasks_done of tasks_total) is computed separately.
Project status
Default: active. Accepted on update only (CompanyProjectUpdate).
| Value | Meaning |
|---|---|
active | In progress |
paused | On hold |
completed | Finished |
archived | Kept for history |
Project status is informational. It does not stop tasks, runs or spend in the project.
Agent status
AgentStatus. There is no endpoint to set it directly; it changes through actions and runs.
| Value | Label | Meaning | Entered when | Left when |
|---|---|---|---|---|
idle | Idle | Available for work | Hired without approval; a hire is approved; resumed; a run finishes (not failed) and no other run is running; a budget override is approved | A run is claimed or started, the agent is paused or terminated |
running | Running | Executing at least one run | A run is claimed, or a run is reported running | Its last running run finishes |
paused | Paused | Not woken and its runs are not claimed | POST /agents/{agent_id}/pause; the agent reaches its monthly budget (a budget_override approval is opened) | Resumed, or its budget override is approved |
pending_approval | Awaiting approval | Proposed hire waiting for a decision | Hired with request_approval: true | The hire_agent approval is approved (idle) or rejected (terminated) |
terminated | Terminated | Retired. Leaves the org chart; history stays. Its queued and running runs are cancelled. | POST /agents/{agent_id}/terminate; a hire is rejected | Never |
error | Error | Its last run failed | A run finishes failed (including lease expiry) and no other run is running | The next run is claimed (running) |
Dormant statuses are paused, pending_approval and terminated. Dormant agents are not woken by assignments, routines or heartbeats, wake answers 400 INVALID_STATE, and runners skip their queued runs. error is not dormant.
Run status
RunStatus.
| Value | Label | Meaning | Set by |
|---|---|---|---|
queued | Queued | Waiting for a runner | Created by a wake, an assignment or a routine trigger. A run cannot go back to queued. |
running | Running | Claimed by a runner, or reported running | POST /runs/claim (stamps runner_id, heartbeat_at, started_at) |
succeeded | Succeeded | Finished successfully | The runner's final PATCH /runs/{run_id} |
failed | Failed | Finished with an error, or its lease expired | The runner; lease expiry (error is "... stopped reporting (lease expired)") |
cancelled | Cancelled | Stopped by a person, or because its agent was terminated | POST /runs/{run_id}/cancel; terminating the agent |
succeeded, failed and cancelled are finished: ended_at is stamped, the agent's budget is checked, and any further report answers 400 RUN_FINISHED.
Run trigger
Why the run was queued (runs.trigger).
| Value | Meaning |
|---|---|
manual | POST /agents/{agent_id}/wake, from a person, sat agents wake, or the scheduler's agent heartbeats. The transcript's first entry gives the reason, for example heartbeat. |
assignment | A task was created for or reassigned to the agent |
routine | A routine was triggered (POST /routines/{routine_id}/trigger) |
heartbeat | Defined as an allowed value, but no endpoint creates runs with it today. Scheduler heartbeats are recorded as manual. |
Approval status
ApprovalStatus. Default: pending.
| Value | Meaning | Set by |
|---|---|---|
pending | Waiting for a decision | Created |
approved | Approved; decided_by_user_id, decided_at and an optional decision_note are recorded | POST /approvals/{approval_id}/approve |
rejected | Rejected; the same fields are recorded | POST /approvals/{approval_id}/reject |
A decided approval cannot be decided again (400 ALREADY_DECIDED). Any member can decide.
Approval type
| Value | Created when | Approve | Reject |
|---|---|---|---|
hire_agent | An agent is hired with request_approval: true | Agent becomes idle | Agent becomes terminated |
budget_override | A finished run brings an agent to its monthly budget; the agent is paused. At most one pending per agent. | Sets the budget to new_budget_cents if given, else raises a non-zero budget to this month's spend plus the original budget; a paused agent becomes idle | Agent stays paused |
action | No endpoint creates it today | Records the decision only | Records the decision only |
Member role
| Value | Meaning |
|---|---|
owner | Created the company. Same powers as admin. |
admin | May change the company (PATCH /api/companies/{company_id}). Not assignable through the API yet. |
member | Every other company action. Not assignable through the API yet. |
Comment kind
CommentCreate.kind. Default: comment.
| Value | Meaning |
|---|---|
comment | An ordinary message. The runner posts an agent's final reply as a comment. |
question | A question that needs an answer. The runner posts a BLOCKED: reply as a question. |
plan | A plan of work |
The task_comments.kind column is documented in the model as also allowing system, but the API does not accept or create it.
Audit actor type
audit_events.actor_type.
| Value | Meaning | actor_name |
|---|---|---|
user | A person made the change | The user's name |
agent | An agent made the change through a running run (run_id) | The agent's name |
system | SAT made the change: run claims and finishes, budget pauses, lease expiry | The agent's name when one is involved, otherwise system |
Transcript role
TranscriptEntry.role. Default: agent.
| Value | Meaning |
|---|---|
agent | The agent's own messages |
tool | Tool calls and their results (commands, file edits) |
system | Runner and API notes: queued, claimed, workspace, unparsed output |
user | Input addressed to the agent |
Roles and adapters
Agent roles
role is free text (up to 50 characters, default engineer). The web app and CLI offer these values (ROLES):
ceo, cto, cmo, cfo, engineer, designer, qa, devops, researcher, writer, support
Adapters
adapter is free text (up to 50 characters, default claude_code). The web app and CLI offer these values (ADAPTERS):
| Value | Label | In sat runner |
|---|---|---|
claude_code | Claude Code | Implemented (claude on PATH) |
codex | Codex | Implemented (codex on PATH) |
cursor | Cursor | Not implemented; runs fail |
gemini | Gemini CLI | Not implemented; runs fail |
opencode | OpenCode | Not implemented; runs fail |
http | HTTP webhook | Not implemented; runs fail |
The runner also has a built-in echo adapter, used for every agent with --simulate. See Adapters.
Preferences
Account preferences (PATCH /api/me/preferences) use these enumerations.
| Field | Values |
|---|---|
theme | light, dark, system |
density | comfortable, compact |
date_style | short, medium, long |
dashboard.range_days | 7, 14, 30 |
tasks.view | list, board |
accent, avatar_color | royal, sky, slate, ink |