Sidekicks and plans API

10 endpoints, split between sidekicks (5) and plans (5).

Sidekicks#

POST /v1/rooms/{room_id}/sidekicks#

1
2
3
4
5
6
7

{
  "task": "Read the last 30 commits on app/ai/ and write a summary",
  "context_mode": "task_only",
  "model_id": "<optional override>",
  "timeout_seconds": 300,
  "name": "<optional human-readable name>"
}

context_mode:

• task_only (default) — sidekick sees only its task description.
• full — gets the parent room's recent history.

Returns:

1
2
3
4
5
6
7
8
9

{
  "data": {
    "task_id": "task-…",
    "codename": "brave-penguin",
    "sidekick_room_id": "room-…",
    "agent_participant_id": "ai-…",
    "status": "spawning"
  }
}

Cancel#

POST .../cancel returns 200 with the updated task. Interrupting an in-flight ScaiGrid stream is best-effort; the task is marked terminated regardless.

Plans#

GET /v1/rooms/{room_id}/plan#

Returns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  "data": {
    "id": "plan-…",
    "room_id": "room-…",
    "participant_id": "ai-…",
    "state": "running",
    "mode": "sequential",
    "advance": "auto",
    "venue": "main",
    "sidekick_room_id": null,
    "goal": "Audit the auth module",
    "steps": [
      {
        "id": "abc12",
        "text": "List every route",
        "status": "done",
        "result": "Found 5 routes in app/api/v1/auth.py",
        "attempts": 1,
        "expected_tools": null
      },
      …
    ],
    "current_step_idx": 2,
    "consecutive_auto_steps": 1,
    "max_consecutive_auto_steps": 8,
    "finish_reason": null,
    "created_at": "...",
    "updated_at": "..."
  }
}

Pause / Resume / Cancel#

// POST .../pause
{ "reason": "lunch break" }

// POST .../cancel
{ "reason": "scope changed" }

/resume takes no body. It resets consecutive_auto_steps to 0 so the AI has fresh budget after a supervisor nudge.

/cancel is idempotent — cancelling a terminal plan returns it unchanged.

Permissions#

Any room member can pause / resume / cancel. The user is always a supervisor by project rule; no role gating.

Errors#

• SW_PLAN_NOT_FOUND — no active plan in this room.
• SW_PLAN_NOT_RUNNING — operation requires state=running.
• SW_PLAN_NOT_PAUSABLE — only running can be paused.
• SW_PLAN_NOT_RUNNABLE — only draft or paused can be run.
• SW_PLAN_TOO_MANY_STEPS — write tried to submit > 20 steps.
• SW_PLAN_EMPTY_STEPS / SW_PLAN_EMPTY_GOAL.
• SW_PLAN_UNKNOWN_STEP — step_id not in the plan.
• SW_PLAN_STEP_TERMINAL — step already done / failed / skipped.

Sidekick venue cancel propagation#

When plan.venue=sidekick and plan.sidekick_room_id is set, the cancel handler:

1. Looks up the AgentTask for the sidekick room.
2. Calls AIBridge.cancel_generation(...) to interrupt any active ScaiGrid stream.
3. Marks the task TERMINATED with a "plan supervisor: <reason>" summary.
4. Then sets the plan state to cancelled.

Order matters — the sidekick's record gets the supervisor reason in its result_summary, not a generic "plan cancelled".