Phases & Orchestrator Sessions

A workspace’s master todo is decomposed into ordered phases, each grouping related entries into a sequential execution unit with its own rounds budget, memory notes, and orchestrator session. Orchestrator sessions drive the planning and per-phase execution flow: the top-level planning session coordinates across phases, and each phase has its own session that agents resume as rounds progress.

Use these endpoints to inspect phase state, manage memory notes, trigger review/verification cycles, update rounds budgets and status, and send prompts to the orchestrator or a specific phase’s session.

---

Phase Management

GET /api/v1/workspaces/{workspaceID}/orchestration/phases

Returns the full ordered list of phases defined in the workspace’s master todo. Phases are returned in seq order; the list is bounded by the workspace’s phase count (typically < 20) and is not paginated. Entries inside each phase are omitted — call GET /phases/{phaseID} to fetch them.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response

200

{
  "phases": [
    {
      "id": "phs_01HXYZABCDEF",
      "seq": 0,
      "name": "Scaffold project structure",
      "status": "pending",
      "phase_rounds": 3,
      "container_id": "ctr_01HXYZABCDEF"
    },
    {
      "id": "phs_01HXYZGHIJKL",
      "seq": 1,
      "name": "Implement core API endpoints",
      "status": "active",
      "phase_rounds": 8,
      "container_id": "ctr_01HXYZABCDEF"
    }
  ]
}

SDK usage

const result = await client.agent.orchestration.phasesList({
  workspaceID: "ws_01HXYZABCDEF",
});

---

GET /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}

Returns the full detail for a single phase, including its entries.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "id": "phs_01HXYZGHIJKL",
  "seq": 1,
  "name": "Implement core API endpoints",
  "description": "Build REST handlers for /containers and /tasks modules.",
  "status": "active",
  "phase_rounds": 8,
  "container_id": "ctr_01HXYZABCDEF",
  "entries": [
    {
      "id": "ent_01HXYZENTRY01",
      "seq": 0,
      "done": true
    },
    {
      "id": "ent_01HXYZENTRY02",
      "seq": 1,
      "done": false
    }
  ]
}

SDK usage

const phase = await client.agent.orchestration.phasesGet({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

POST /api/v1/workspaces/{workspaceID}/orchestration/phases

Creates one or more phases in the workspace’s master todo.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Request Body

Field	Type	Required	Description
phases	array	Yes	Array of phase objects to create
phases[].name	string	Yes	Human-readable phase name
phases[].description	string	Yes	Phase description
phases[].entry_ids	array of strings	No	IDs of existing todo entries to include in this phase
phases[].phase_rounds	number	No	Rounds budget for this phase
phases[].container_id	string	No	Execution container for this phase

{
  "phases": [
    {
      "name": "Scaffold project structure",
      "description": "Initialize repository, configure CI, and add base configuration files.",
      "phase_rounds": 3,
      "container_id": "ctr_01HXYZABCDEF"
    },
    {
      "name": "Implement core API endpoints",
      "description": "Build REST handlers for /containers and /tasks modules.",
      "entry_ids": ["ent_01HXYZENTRY01", "ent_01HXYZENTRY02"],
      "phase_rounds": 8
    }
  ]
}

Response

200

{
  "created": [
    {
      "id": "phs_01HXYZNEW001",
      "seq": 0,
      "name": "Scaffold project structure",
      "status": "pending",
      "phase_rounds": 3
    },
    {
      "id": "phs_01HXYZNEW002",
      "seq": 1,
      "name": "Implement core API endpoints",
      "status": "pending",
      "phase_rounds": 8
    }
  ]
}

SDK usage

const result = await client.agent.orchestration.phasesCreate({
  workspaceID: "ws_01HXYZABCDEF",
  data: {
    phases: [
      {
        name: "Scaffold project structure",
        description: "Initialize repository, configure CI, and add base configuration files.",
        phase_rounds: 3,
        container_id: "ctr_01HXYZABCDEF",
      },
    ],
  },
});

---

DELETE /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}

Deletes a phase. Entries that were assigned to the phase are unphased (returned to the unassigned pool), not deleted.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "deleted": true,
  "phaseID": "phs_01HXYZGHIJKL"
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Phase not found"
  }
}

409

{
  "error": "Phase is currently active and cannot be deleted",
  "code": "session_busy"
}

SDK usage

await client.agent.orchestration.phasesDelete({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

Phase Entries

POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/entries

Adds an existing todo entry to a phase. Entries remain globally addressable; this just assigns them to a phase’s execution group.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Request Body

Field	Type	Required	Description
entryID	string	Yes	Identifier of the entry to add

{
  "entryID": "ent_01HXYZENTRY03"
}

Response

200

{
  "phaseID": "phs_01HXYZGHIJKL",
  "entryID": "ent_01HXYZENTRY03",
  "added": true
}

SDK usage

await client.agent.orchestration.phasesAddEntry({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
  data: {
    entryID: "ent_01HXYZENTRY03",
  },
});

---

Phase Memory

Memory notes are short textual observations written by agents during execution (decisions, gotchas, follow-ups) and are carried across rounds so later agents can read the full context.

GET /api/v1/workspaces/{workspaceID}/orchestration/phases/memory

Returns memory notes for every phase in the workspace.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response

200

{
  "phases": [
    {
      "phaseID": "phs_01HXYZABCDEF",
      "notes": [
        {
          "text": "Chose Postgres over SQLite for multi-writer support."
        }
      ]
    },
    {
      "phaseID": "phs_01HXYZGHIJKL",
      "notes": []
    }
  ]
}

SDK usage

const result = await client.agent.orchestration.phasesGetAllMemory({
  workspaceID: "ws_01HXYZABCDEF",
});

---

GET /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory

Returns the accumulated memory notes for a single phase. Notes are returned in insertion order, bounded by the phase’s memory cap, and are not paginated.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "phaseID": "phs_01HXYZGHIJKL",
  "notes": [
    {
      "text": "Reuse validation helper from previous round."
    },
    {
      "text": "Auth module needs special container with network access."
    }
  ]
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Phase not found"
  }
}

Error Code	Title	Description	Resolution
PHASE_NOT_FOUND	Phase does not exist in this workspace	No phase with the supplied phaseID was found in the workspace’s materialized state. The phase may have been deleted, or the id belongs to a different workspace.	Call GET /orchestration/phases to list valid phase ids, or verify the workspace id in the URL.

SDK usage

const memory = await client.agent.orchestration.phasesListMemory({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory

Adds a note to the phase’s memory. Notes persist across rounds and are readable by all agents working on the phase.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Request Body

Field	Type	Required	Description
text	string	Yes	Note text. 1–10,000 characters.

{
  "text": "Auth module needs a special container with outbound network access for OAuth callbacks."
}

Response

200

{
  "added": true,
  "phaseID": "phs_01HXYZGHIJKL"
}

SDK usage

await client.agent.orchestration.phasesAddMemory({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
  data: {
    text: "Auth module needs a special container with outbound network access for OAuth callbacks.",
  },
});

---

DELETE /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/memory

Clears all memory notes for a phase.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "cleared": true,
  "phaseID": "phs_01HXYZGHIJKL"
}

SDK usage

await client.agent.orchestration.phasesClearMemory({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

Phase Lifecycle

GET /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/summary

Returns a condensed summary of the phase’s progress, useful for UIs and status checks without pulling the full entry list.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	workspaceID path parameter
phaseID	path	string	Yes	phaseID path parameter

Response

200

{
  "phaseID": "phs_01HXYZGHIJKL",
  "name": "Implement core API endpoints",
  "status": "active",
  "phase_rounds": 8,
  "rounds_used": 3,
  "entries_total": 7,
  "entries_done": 4,
  "memory_note_count": 2
}

SDK usage

const summary = await client.agent.orchestration.phasesGetSummary({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/review

Manually triggers a review pass for the phase. The orchestrator inspects current round output and either approves progress or schedules a fix round.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "phaseID": "phs_01HXYZGHIJKL",
  "review": "triggered"
}

400

{
  "success": false,
  "data": {},
  "errors": [
    {
      "message": "Phase has no entries to review"
    }
  ]
}

404

{
  "name": "NotFoundError",
  "data": {
    "message": "Phase not found"
  }
}

409

{
  "error": "A review is already in progress for this phase",
  "code": "session_busy"
}

SDK usage

await client.agent.orchestration.phasesReview({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

POST /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/verify

Manually triggers a verification pass for the phase. Verification checks that all phase entries satisfy their acceptance criteria before the phase can be marked done.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "phaseID": "phs_01HXYZGHIJKL",
  "verification": "triggered"
}

SDK usage

await client.agent.orchestration.phasesVerify({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

PATCH /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/rounds

Updates the rounds budget for a phase. The budget caps the total number of execution rounds before the phase must transition to done or failed.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	workspaceID path parameter
phaseID	path	string	Yes	phaseID path parameter

Request Body

Field	Type	Required	Description
phase_rounds	integer	Yes	New rounds budget (minimum 1, maximum 9007199254740991)

{
  "phase_rounds": 12
}

Response

200

{
  "id": "phs_01HXYZGHIJKL",
  "phase_rounds": 12
}

SDK usage

await client.agent.orchestration.phasesUpdateRounds({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
  data: {
    phase_rounds: 12,
  },
});

---

PATCH /api/v1/workspaces/{workspaceID}/orchestration/phases/{phaseID}/status

Manually updates a phase’s status. The state machine allows only the documented transitions; arbitrary values are rejected.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Request Body

Field	Type	Required	Description
status	string	Yes	New status. One of: pending, active, verifying, fixing, done, failed

{
  "status": "active"
}

Response

200

{
  "id": "phs_01HXYZGHIJKL",
  "status": "active"
}

SDK usage

await client.agent.orchestration.phasesUpdateStatus({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
  data: {
    status: "active",
  },
});

---

Orchestrator Sessions

The workspace has one top-level planning session and one session per phase. The planning session coordinates across phases; phase sessions are resumed by agents as rounds progress.

GET /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/session

Returns the top-level planning orchestrator session state, or null if no planning session exists yet.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response

200

{
  "session": {
    "id": "orc_01HXYZPLANNER",
    "active": true
  }
}

SDK usage

const result = await client.agent.orchestration.orchestratorGetSession({
  workspaceID: "ws_01HXYZABCDEF",
});

---

POST /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/session

Creates a new top-level planning orchestrator session, or resumes the existing one if one is already active.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	workspaceID path parameter

Response

200

{
  "sessionID": "orc_01HXYZPLANNER"
}

SDK usage

const result = await client.agent.orchestration.orchestratorCreateSession({
  workspaceID: "ws_01HXYZABCDEF",
});

---

GET /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/sessions

Returns every orchestrator session currently tracked for the workspace: the top-level planning session plus one session per phase. Used by the UI to render the orchestrator tree and by agents to resume work against an existing session id. The count is bounded by the number of phases (typically < 20); the endpoint is not paginated.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response

200

{
  "sessions": [
    {
      "id": "orc_01HXYZPLANNER",
      "kind": "planning",
      "active": true
    },
    {
      "id": "orc_01HXYZPHASE001",
      "kind": "phase",
      "phaseID": "phs_01HXYZABCDEF",
      "active": false
    },
    {
      "id": "orc_01HXYZPHASE002",
      "kind": "phase",
      "phaseID": "phs_01HXYZGHIJKL",
      "active": true
    }
  ]
}

SDK usage

const result = await client.agent.orchestration.orchestratorListSessions({
  workspaceID: "ws_01HXYZABCDEF",
});

---

Phase Orchestrator Session

GET /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/phases/{phaseID}/session

Returns the orchestrator session info for a single phase. Agents use the session id to resume execution against the phase’s running orchestrator state.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Response

200

{
  "phaseID": "phs_01HXYZGHIJKL",
  "session": {
    "id": "orc_01HXYZPHASE002",
    "active": true
  }
}

SDK usage

const result = await client.agent.orchestration.orchestratorGetPhaseSession({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
});

---

Orchestrator Prompts

POST /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/prompt

Sends a prompt to the top-level planning orchestrator. @todo mentions inside the prompt text are resolved against the workspace’s master todo before the message is delivered.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Request Body

Field	Type	Required	Description
text	string	Yes	Prompt text. 1–50,000 characters.

{
  "text": "Prioritize @todo[ent_01HXYZENTRY03] before scaffolding the auth module."
}

Response

200

{
  "sent": true,
  "sessionID": "orc_01HXYZPLANNER"
}

SDK usage

const result = await client.agent.orchestration.orchestratorSendPrompt({
  workspaceID: "ws_01HXYZABCDEF",
  data: {
    text: "Prioritize @todo[ent_01HXYZENTRY03] before scaffolding the auth module.",
  },
});

---

POST /api/v1/workspaces/{workspaceID}/orchestration/orchestrator/phases/{phaseID}/prompt

Sends a prompt to the orchestrator session driving a specific phase. Use this to inject directives, clarifications, or course-corrections directly into the phase’s running context.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
phaseID	path	string	Yes	Phase identifier

Request Body

Field	Type	Required	Description
text	string	Yes	Prompt text. 1–50,000 characters.

{
  "text": "Reuse the validation helper from the previous round — do not redefine it."
}

Response

200

{
  "sent": true,
  "sessionID": "orc_01HXYZPHASE002"
}

SDK usage

const result = await client.agent.orchestration.orchestratorPromptPhase({
  workspaceID: "ws_01HXYZABCDEF",
  phaseID: "phs_01HXYZGHIJKL",
  data: {
    text: "Reuse the validation helper from the previous round — do not redefine it.",
  },
});

Tip

Phase prompts are delivered into the running session and persist in its context. For ephemeral hints that should not survive across rounds, consider adding a memory note with phasesAddMemory instead.