ewilliams28/turnstone
1
0
Fork 0
mirror of https://github.com/turnstonelabs/turnstone.git synced 2026-08-12 23:12:23 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: update coord URL tree to post-Stage-2 unified /v1/api/workstreams

Browse Source 
The Stage 2 verb-shape lift converged coord and interactive on the
unified /v1/api/workstreams/{ws_id}/<verb> URL tree; the
/v1/api/coordinator/* tree was removed in P0. Two docs still
documented the pre-lift surface:

- coordinator-api-tour.md (the integrator's lifecycle walk-through):
  rewrites all 9 step URLs to the post-lift paths, keeps a one-block
  callout noting the historical /v1/api/coordinator/* tree and why
  it converged, and drops the operation-id column (operation ids
  shifted with the URL move and are now best looked up live via
  /openapi.json + Swagger UI rather than baked into prose).
- bulk-endpoints.md (the cascade-mutation shape contract): two table
  rows for stop_cascade / close_all_children fixed.

No code changes. CHANGELOG entry kept implicit since this is doc-only
and the URL convergence itself was already documented under the P0
verb-lift CHANGELOG block.
This commit is contained in:
Patrick Buckley
2026-04-26 17:53:31 -07:00
committed by Patrick Buckley
parent 6572437c5d
commit 059bbc3729
2 changed files with 44 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/bulk-endpoints.md
+2 -2
View File
@@ -12,8 +12,8 @@ Existing bulk endpoints at time of writing:
|---------------------------------------------------------|--------------------------|------------------------------------------|
| `GET /v1/api/cluster/ws/live?ids=a,b,c` | bulk read | `{results, denied, truncated}` |
| model tool `spawn_batch` | bulk create (per-item) | `{results, denied}` |
| `POST /v1/api/coordinator/{ws_id}/stop_cascade` | cascade mutation | `{cancelled, failed, skipped}` |
| `POST /v1/api/coordinator/{ws_id}/close_all_children` | cascade mutation | `{closed, failed, skipped}` |
| `POST /v1/api/workstreams/{ws_id}/stop_cascade` | cascade mutation | `{cancelled, failed, skipped}` |
| `POST /v1/api/workstreams/{ws_id}/close_all_children` | cascade mutation | `{closed, failed, skipped}` |
---
docs/coordinator-api-tour.md
+42 -27
View File
@@ -26,28 +26,43 @@ schema changes.
## The 9 steps
| # | Action | Operation | Operation id |
|---|------------------------------|-------------------------------------------------------------|-------------------------------------------------------------|
| 1 | Create | `POST /v1/api/coordinator/new` | `v1_api_coordinator_new_post` |
| 2 | Subscribe to events | `GET /v1/api/coordinator/{ws_id}/events` (SSE) | `v1_api_coordinator_{ws_id}_events_get` |
| 3 | Send a user message | `POST /v1/api/coordinator/{ws_id}/send` | `v1_api_coordinator_{ws_id}_send_post` |
| 4 | Inspect children | `GET /v1/api/coordinator/{ws_id}/children` | `v1_api_coordinator_{ws_id}_children_get` |
| 5 | Inspect one workstream | `GET /v1/api/cluster/ws/{ws_id}/detail` | `v1_api_cluster_ws_{ws_id}_detail_get` |
| 6 | Wait for fan-out | model-side tool `wait_for_workstream` | — (tool call, not HTTP) |
| 7 | Govern | `POST /v1/api/coordinator/{ws_id}/trust` | `v1_api_coordinator_{ws_id}_trust_post` |
| | | `POST /v1/api/coordinator/{ws_id}/restrict` | `v1_api_coordinator_{ws_id}_restrict_post` |
| | | `POST /v1/api/coordinator/{ws_id}/stop_cascade` | `v1_api_coordinator_{ws_id}_stop_cascade_post` |
| | | `POST /v1/api/coordinator/{ws_id}/close_all_children` | `v1_api_coordinator_{ws_id}_close_all_children_post` |
| 8 | Approve / cancel | `POST /v1/api/coordinator/{ws_id}/approve` | `v1_api_coordinator_{ws_id}_approve_post` |
| | | `POST /v1/api/coordinator/{ws_id}/cancel` | `v1_api_coordinator_{ws_id}_cancel_post` |
| 9 | Close | `POST /v1/api/coordinator/{ws_id}/close` | `v1_api_coordinator_{ws_id}_close_post` |
> **URL convergence (1.5.0).** Pre-1.5 coord-only endpoints lived
> under `/v1/api/coordinator/...`. The Stage 2 verb-shape lift
> consolidated coord and interactive onto the unified
> `/v1/api/workstreams/{ws_id}/<verb>` tree; coord still distinguishes
> itself via the `kind=coordinator` row classifier rather than a
> separate URL space. The endpoints below reflect the post-lift
> surface served by `turnstone-console`.
| # | Action | Operation |
|---|------------------------------|-------------------------------------------------------------|
| 1 | Create | `POST /v1/api/workstreams/new` |
| 2 | Subscribe to events | `GET /v1/api/workstreams/{ws_id}/events` (SSE) |
| 3 | Send a user message | `POST /v1/api/workstreams/{ws_id}/send` |
| 4 | Inspect children | `GET /v1/api/workstreams/{ws_id}/children` |
| 5 | Inspect one workstream | `GET /v1/api/cluster/ws/{ws_id}/detail` |
| 6 | Wait for fan-out | model-side tool `wait_for_workstream` |
| 7 | Govern | `POST /v1/api/workstreams/{ws_id}/trust` |
| | | `POST /v1/api/workstreams/{ws_id}/restrict` |
| | | `POST /v1/api/workstreams/{ws_id}/stop_cascade` |
| | | `POST /v1/api/workstreams/{ws_id}/close_all_children` |
| 8 | Approve / cancel | `POST /v1/api/workstreams/{ws_id}/approve` |
| | | `POST /v1/api/workstreams/{ws_id}/cancel` |
| 9 | Close | `POST /v1/api/workstreams/{ws_id}/close` |
Refer to `/openapi.json` (Swagger UI at `/docs`) on any
`turnstone-console` process for the authoritative operation ids and
schemas. Coordinator-only verbs (`/children`, `/trust`, `/restrict`,
`/stop_cascade`, `/close_all_children`) 404 against `kind=interactive`
rows; the shared verbs (`/send`, `/approve`, `/cancel`, `/events`,
`/history`, `/open`, `/close`, etc.) work on both kinds.
---
## 1. Create a coordinator
```http
POST /v1/api/coordinator/new
POST /v1/api/workstreams/new
Content-Type: application/json
Authorization: Bearer <token>
@@ -80,7 +95,7 @@ subscribers (step 2) see the session warm up as token traffic starts.
```http
GET /v1/api/workstreams/{ws_id}/events HTTP/1.1
Accept: text/event-stream
Accept: text/event-stream
Authorization: Bearer <token>
```
@@ -124,7 +139,7 @@ operator.
```http
POST /v1/api/workstreams/{ws_id}/send
Content-Type: application/json
Content-Type: application/json
{"message": "audit /auth for CSRF handling across all active routes"}
```
@@ -147,7 +162,7 @@ events, finishing with `state_change → idle` or an
```http
GET /v1/api/workstreams/{ws_id}/children HTTP/1.1
```
```
```json
{
@@ -244,7 +259,7 @@ burst can't starve audit writes.
```json
POST /v1/api/workstreams/{ws_id}/trust
{"send": true}
{"send": true}
```
Flips `trust_send=true` on the live session. Subsequent
@@ -258,7 +273,7 @@ second grants a service token the opt-in it otherwise wouldn't get).
```json
POST /v1/api/workstreams/{ws_id}/restrict
{"revoke": ["spawn_workstream", "delete_workstream"]}
{"revoke": ["spawn_workstream", "delete_workstream"]}
```
Unions the names into the session's revoked-tools set. Additive and
@@ -270,7 +285,7 @@ opt in per session. Cap 256 tool names per request, 128 chars each.
```json
POST /v1/api/workstreams/{ws_id}/stop_cascade
{}
{}
```
Cancels the coordinator's in-flight generation AND dispatches
@@ -292,7 +307,7 @@ propagate via the child's SSE stream.
```json
POST /v1/api/workstreams/{ws_id}/close_all_children
{"reason": "audit round complete"}
{"reason": "audit round complete"}
```
Response:
@@ -323,7 +338,7 @@ event. The coordinator's worker thread is blocked inside
```json
POST /v1/api/workstreams/{ws_id}/approve
{"approved": true, "feedback": null, "always": false}
{"approved": true, "feedback": null, "always": false}
{"approved": false, "feedback": "spawn count looks too high — try 3 not 10"}
{"approved": true, "feedback": null, "always": true} // always-approve this tool name
```
@@ -333,7 +348,7 @@ POST /v1/api/coordinator/{ws_id}/approve
```json
POST /v1/api/workstreams/{ws_id}/cancel
{}
{}
```
---
@@ -342,7 +357,7 @@ POST /v1/api/coordinator/{ws_id}/cancel
```json
POST /v1/api/workstreams/{ws_id}/close
{}
{}
```
Soft-closes the session — state persists, children keep running (use
@@ -350,7 +365,7 @@ Soft-closes the session — state persists, children keep running (use
worker thread exits, SSE streams send a final `stream_end` and
disconnect. The row is reopenable via
`POST /v1/api/workstreams/{ws_id}/open` so long as it hasn't been
deleted.
deleted.
---