Skip to main content

Coordinator

Hosted coordinator brain — initiative-wide reasoning over Project Tracker state, with every consult persisted as a coordinator.consults row plus an audit entry.

📄️List the AGENT-STAGED coordinator pending actions anchored to a task (PLT-373)

List the AGENT-STAGED coordinator pending actions anchored to a task (PLT-373). An assignable-agent run that proposes a destructive action stages it as a confirm-gated `coordinator.pending_actions` row; this route is where an authorized human reviews everything staged against the task before confirming via `POST /api/coordinator/pending-actions/{id}/execute` or dismissing via `…/{id}/cancel`. Authorization is two-layered and matches the confirm surface: the task must be readable (project access) AND the caller must be a programme member of the staged row’s initiative — a task reader who is not a delegate gets an empty list (they still see the proposal via the task thread comment). Only ACTIONABLE rows (`pending` / `executing`) are listed; terminal outcomes live in the audit log.

📄️Agent-facing index-first knowledge-base retrieval (PLT-283)

Agent-facing index-first knowledge-base retrieval (PLT-283). Runs the same `queryKnowledgeBase` read the coordinator brain uses, under the calling agent’s own auth, so the wiki RLS + an UNCLASSIFIED classification cap scope every read to what the caller may see. Returns the rendered KB section (index + recent synthesis pages, capped to the coordinator context budget) plus a citations array. Backs the `query_knowledge_base` MCP tool and the `pt query-kb` CLI.

📄️Tenant-scoped forward to the wiki KB usage aggregation report (PLT-393): top queries, top-cited pages, miss rate, never-read pages (prune/merge candidates), and token trend over a rolling window

Tenant-scoped forward to the wiki KB usage aggregation report (PLT-393): top queries, top-cited pages, miss rate, never-read pages (prune/merge candidates), and token trend over a rolling window. The report itself is computed by the wiki over `wiki.kb_reads`; this route forwards the caller’s own auth so the wiki’s RLS + classification gating scope the result to what the caller may see. Backs the (follow-up) `kb_usage` MCP tool and `pt kb-usage` CLI.

📄️List the coordinator decision log for one initiative the caller belongs to — the persisted `coordinator.consults` rows, paginated and sortable by recency / cost / actor

List the coordinator decision log for one initiative the caller belongs to — the persisted `coordinator.consults` rows, paginated and sortable by recency / cost / actor. Backs the Directory decision-log feed (PLT-208 slice 2). Membership is enforced by RLS + an explicit check: a non-member receives 403, not an empty list. When the initiative classification exceeds the viewer clearance, entries are returned with `masked: true` and `questionExcerpt: null` (PLT-212). SECRET-classified reads are written to the audit log regardless of masking outcome.

📄️Month-to-date coordinator spend for an initiative — per-user and initiative-wide token + USD totals, aggregated from `coordinator.consults` (SUM of `tokens_in` / `tokens_out` / `usd_cents` since the start of the current month, grouped by user)

Month-to-date coordinator spend for an initiative — per-user and initiative-wide token + USD totals, aggregated from `coordinator.consults` (SUM of `tokens_in` / `tokens_out` / `usd_cents` since the start of the current month, grouped by user). Backs the cost tiles in Directory's coordinator chat header. Tenant + initiative isolation is enforced by the `consults_tenant_read` RLS policy, so a non-member reads all-zero totals.

📄️Staging step of the artifact-promotion ladder (PLT-210): writes a `coordinator.pending_actions` row from one of a persisted consult’s `suggestedActions` (referenced by `consultId` + `actionIndex`) and returns the staged id + preview for the confirm modal

Staging step of the artifact-promotion ladder (PLT-210): writes a `coordinator.pending_actions` row from one of a persisted consult’s `suggestedActions` (referenced by `consultId` + `actionIndex`) and returns the staged id + preview for the confirm modal. This is the ONLY route that creates pending actions; it never runs a side effect — execution is the separate `[id]/execute` step.

📄️Human-confirmation step: executes a staged coordinator pending action

Human-confirmation step: executes a staged coordinator pending action. A pending action is created when a user stages one of the coordinator brain’s suggested writes (via the prepare route) — artifact promotion (`create_task`, `link_to_existing`, and `draft_spec` — staged as the pending-action kind `draft_spec_pr`), a ticket-management mutation (`update_priority`, `transition_status`, `assign`, `update_due_date`, `edit_description`), or a cycle assignment (`assign_task_to_cycle`). This route is the ONLY write path — there is no direct-mutation bypass. The optional `mutationPolicyOverride` in the request body may tighten (never loosen) the code-declared `confirm-required` ceiling.