# Orchestration: Phases & Orchestrator Sessions

**Page:** api/agent/orchestration/phases-sessions

[Download Raw Markdown](./api/agent/orchestration/phases-sessions.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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



```json
{
  "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

```typescript
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



```json
{
  "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

```typescript
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 |

```json
{
  "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



```json
{
  "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

```typescript
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



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


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


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



#### SDK usage

```typescript
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 |

```json
{
  "entryID": "ent_01HXYZENTRY03"
}
```

#### Response



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



#### SDK usage

```typescript
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



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



#### SDK usage

```typescript
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



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


```json
{
  "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

```typescript
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. |

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

#### Response



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



#### SDK usage

```typescript
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



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



#### SDK usage

```typescript
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



```json
{
  "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

```typescript
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



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


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


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


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



#### SDK usage

```typescript
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



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



#### SDK usage

```typescript
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) |

```json
{
  "phase_rounds": 12
}
```

#### Response



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



#### SDK usage

```typescript
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` |

```json
{
  "status": "active"
}
```

#### Response



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



#### SDK usage

```typescript
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



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



#### SDK usage

```typescript
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



```json
{
  "sessionID": "orc_01HXYZPLANNER"
}
```



#### SDK usage

```typescript
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



```json
{
  "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

```typescript
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



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



#### SDK usage

```typescript
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. |

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

#### Response



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



#### SDK usage

```typescript
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. |

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

#### Response



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



#### SDK usage

```typescript
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.",
  },
});
```


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.