state-hub/skills/state-hub/references/tool-signatures.md

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("infotech") inside State Hub work. It returns the domain topic, active workplans, 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.

Workplans and Tasks

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

MCP: create_task(workplan_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}

For repository-owned work, write the workplan/task files and sync with Repo Manager; the create signatures above describe the projection API. Read using GET /workplans/{id} and GET /tasks/?workplan_id=<id>. Send X-StateHub-Component: <repo-slug> on direct HTTP requests for caller attribution. The removed workstream tools and /workstreams/ routes are not fallbacks.

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?, workplan_id?, task_id?, detail?)
REST: POST /progress/

MCP: record_decision(title, decision_type="pending", topic_id?, workplan_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.