State Hub Tool Signatures

Load this reference when a session needs exact REST fallback paths or batched write payloads.

Orientation

MCP: get_domain_summary(domain_slug)
REST: GET /state/summary then filter by topic/domain when MCP is unavailable

Use get_domain_summary("custodian") inside State Hub work. It returns the domain topic, active workstreams, blocking decisions, recent progress, repos, and compact capability hints.

Agent Messages

MCP: get_messages(to_agent?, from_agent?, unread_only?, limit?)
REST: GET /messages/?to_agent=<repo>&unread_only=true

MCP: send_message(from_agent, to_agent, subject, body, thread_id?)
REST: POST /messages/

MCP: mark_message_read(message_id)
REST: PATCH /messages/{message_id}/read

Use repo slugs as agent names. Use broadcast only for genuinely shared coordination.

Workstreams and Tasks

MCP: create_workstream(topic_id, title, slug?, description?, owner?, due_date?, repo_id?, planning_priority?, planning_order?)
REST: POST /workstreams/

MCP: create_task(workstream_id, title, priority="medium", description?, assignee?, due_date?)
REST: POST /tasks/

MCP: update_task_status(task_id, status, blocking_reason?, tokens_in?, tokens_out?, workplan_tokens_in?, workplan_tokens_out?, note?, model?, agent?, session_id?)
REST: PATCH /tasks/{task_id}

Canonical task statuses are wait, todo, progress, done, and cancel. Legacy aliases are accepted during migration, but do not emit new workplan files with old vocabulary.

Bulk Task Status Sync

MCP: bulk_update_task_statuses(updates, author?, session_id?)
REST: POST /tasks/bulk-status-sync

Payload:

{
  "updates": [
    {"task_id": "uuid-1", "status": "progress"},
    {"task_id": "uuid-2", "status": "done"},
    {"task_id": "uuid-3", "status": "wait", "blocking_reason": "needs approval"}
  ],
  "author": "codex",
  "session_id": "optional-session-id"
}

Response:

{
  "updated": [
    {"id": "uuid-1", "status": "progress", "...": "..."}
  ],
  "progress_event_ids": ["event-uuid-1"]
}

The endpoint rejects duplicate task ids with 400 and missing task ids with 404 before changing any task. Each successful item emits one task_status_changed progress event with detail.bulk_status_sync = true.

Progress and Decisions

MCP: add_progress_event(summary, event_type="note", topic_id?, workstream_id?, task_id?, detail?)
REST: POST /progress/

MCP: record_decision(title, decision_type="pending", topic_id?, workstream_id?, description?, rationale?, decided_by?, deadline?)
REST: POST /decisions/

Prefer one progress event per checkpoint. A useful close event says what changed, which tests ran, whether consistency sync passed, and what remains.

2.7 KiB Raw Blame History