{"openapi":"3.1.0","info":{"title":"Forge Orchestrator API","version":"1.0.0","description":"DDAA Forge orchestrator Worker. Control/orchestration front door: task status, inference planning, deterministic assembly, capsule run loop, and pipeline observability endpoints."},"servers":[{"url":"https://forge.mvrx.app","description":"Production (forge.mvrx.app)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"secret","description":"Wrangler secret (SMOKE_TOKEN, SYNC_TOKEN, RUN_TOKEN, PLAN_TOKEN). Set per-route; /observe/* endpoints are unauthenticated."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"detail":{"type":"string"}}},"TaskCountsByState":{"type":"object","description":"Map of status -> count","additionalProperties":{"type":"number"}},"RecentRun":{"type":"object","properties":{"key":{"type":"string","description":"R2 object key"},"uploaded":{"type":"string","format":"date-time"}}},"TaskEventRow":{"type":"object","properties":{"id":{"type":"integer"},"task_id":{"type":"string"},"from_state":{"type":["string","null"]},"to_state":{"type":"string"},"reason":{"type":["string","null"]},"cost_usd":{"type":["number","null"]},"tokens":{"type":["integer","null"]},"ts":{"type":"string","format":"date-time"}}},"RunResult":{"type":"object","description":"Parsed JSON body of a runs/*/result.json object, with an added ref field.","properties":{"ref":{"type":"string","description":"r2://forge-artifacts/<key>"},"taskId":{"type":"string"},"status":{"type":"string"},"gateOk":{"type":"boolean"},"tier":{"type":"string"},"attempts":{"type":"integer"}},"additionalProperties":true},"TransitionMetric":{"type":"object","properties":{"to_state":{"type":"string"},"count":{"type":"integer"},"total_cost_usd":{"type":["number","null"]},"total_tokens":{"type":["integer","null"]}}},"MetricsResponse":{"type":"object","properties":{"total_tasks":{"type":"integer"},"tasks_by_state":{"$ref":"#/components/schemas/TaskCountsByState"},"recent_transitions":{"type":"array","items":{"$ref":"#/components/schemas/TransitionMetric"}}}},"ObserveTaskRow":{"type":"object","description":"D1 task row for agent console inbox/plan views.","properties":{"id":{"type":"string"},"parentId":{"type":["string","null"]},"title":{"type":"string"},"status":{"type":"string"},"capsuleId":{"type":["string","null"]},"ownerAgent":{"type":["string","null"]},"deps":{"type":"array","items":{"type":"string"}},"attempts":{"type":"integer"},"complexity":{"type":"string","enum":["trivial","simple","moderate","complex"]},"modelTier":{"type":["string","null"],"enum":["deterministic","small","mid","frontier",null]},"resultRef":{"type":["string","null"]},"budget":{"type":"object","properties":{"maxTurns":{"type":"integer"},"maxTokens":{"type":"integer"},"maxUsd":{"type":"number"}}},"createdAt":{"type":"integer"},"updatedAt":{"type":"integer"}}},"AuditEventRow":{"type":"object","description":"Row from task_event_audit (pipeline seam trace for Build stepper).","properties":{"trace_id":{"type":"string"},"span_id":{"type":"string"},"parent_span_id":{"type":["string","null"]},"tenant_id":{"type":"string"},"task_id":{"type":"string"},"capsule_id":{"type":["string","null"]},"event":{"type":"string"},"tier":{"type":["string","null"]},"attempt":{"type":["integer","null"]},"result":{"type":["string","null"]},"payload_json":{"type":"object","additionalProperties":true},"ts":{"type":"string","format":"date-time"}}},"TopologyNode":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"deps":{"type":"array","items":{"type":"string"}},"modelTier":{"type":["string","null"]},"attempts":{"type":"integer"}}},"TaskGraphEdge":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"}}},"SloIndicator":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail"]},"target":{"type":"string"}}}}},"paths":{"/":{"get":{"summary":"Health check","description":"Returns service name and status. No auth required.","operationId":"getRoot","responses":{"200":{"description":"Service is running","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","example":"forge-orchestrator"},"status":{"type":"string","example":"ok"}}}}}}}}},"/status":{"get":{"summary":"Task graph status (via Orchestrator DO)","description":"Returns counts of ready/running/blocked/integrated tasks from the D1 task store. Routes through the singleton OrchestratorAgent Durable Object.","operationId":"getStatus","responses":{"200":{"description":"Status summary","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"integer"},"running":{"type":"integer"},"blocked":{"type":"integer"},"integrated":{"type":"integer"}}}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/smoke":{"post":{"summary":"Live inference smoke test","description":"Runs one Workers AI generation through AI Gateway (cap-cloudflare-037). Guarded by SMOKE_TOKEN bearer.","operationId":"postSmoke","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Inference result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"model":{"type":"string"},"gatewayId":{"type":"string"},"text":{"type":"string"},"tokens":{"type":"integer"},"usd":{"type":"number"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Smoke disabled (SMOKE_TOKEN unset)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/plan":{"post":{"summary":"Inference planning boundary — intent -> BuildUnitSpec","description":"The single top-of-funnel model call (docs/ddaa/03, docs/ddaa/06 §5.1). Accepts an intent string; returns a BuildUnitSpec ref persisted in R2 + D1. Guarded by PLAN_TOKEN bearer.","operationId":"postPlan","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["intent"],"properties":{"intent":{"type":"string","description":"The intent / objective to decompose."}}}}}},"responses":{"200":{"description":"BuildUnitSpec persisted","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"specId":{"type":"string"},"ref":{"type":"string","description":"r2:// or mem:// ref"},"summary":{"type":"string"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assemble":{"post":{"summary":"Deterministic capsule assembly in sandbox","description":"Loads a persisted BuildUnitSpec by specId; clones the repo into the sandbox container; runs buildCapsule against the checked-out tree; returns a schema-valid capsule. Zero model calls. Guarded by PLAN_TOKEN bearer.","operationId":"postAssemble","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["specId"],"properties":{"specId":{"type":"string","description":"The BuildUnitSpec id returned by POST /plan."}}}}}},"responses":{"200":{"description":"Capsule assembled","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"capsuleRef":{"type":"string"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/run":{"post":{"summary":"Capsule run loop","description":"Drives the micro-loop (loadCapsule → route → runCapsule → persist result ref) for a given taskId via the OrchestratorAgent DO. Guarded by RUN_TOKEN bearer.","operationId":"postRun","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taskId"],"properties":{"taskId":{"type":"string"}}}}}},"responses":{"200":{"description":"Run result (references-not-transcripts summary)","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"taskId":{"type":"string"},"gateOk":{"type":"boolean"},"ref":{"type":"string"},"summary":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Run disabled or capsule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/create":{"post":{"summary":"Cloud-native single-task creation","description":"Accepts a TaskCapsule body and writes D1 task row + R2 capsule body via createTaskInCloud. Guarded by PLAN_TOKEN bearer.","operationId":"postCreate","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"capsule":{"type":"object","description":"TaskCapsule JSON body"},"capsuleRef":{"type":"string","description":"r2:// ref to existing capsule body"}}}}}},"responses":{"200":{"description":"Task created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"taskId":{"type":"string"},"capsuleRef":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/reset-bootstrap":{"post":{"summary":"Destructive bootstrap reset (ack-gated)","description":"Deletes all D1 task rows and R2 capsule bodies. Requires JSON body { ack: 'RESET_BOOTSTRAP_STATE' }. Guarded by SYNC_TOKEN.","operationId":"postAdminResetBootstrap","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Reset complete"},"401":{"description":"Unauthorized"},"404":{"description":"Disabled or bad ack"}}}},"/admin/reconcile":{"post":{"summary":"Read-only drift detection vs embedded bootstrap snapshot","description":"Compares live D1/R2 against embedded snapshot. Never mutates. Guarded by SYNC_TOKEN.","operationId":"postAdminReconcile","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"PASS or DRIFT","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"string","enum":["PASS","DRIFT"]},"drift":{"type":"array","items":{"type":"object"}}}}}}}}}},"/admin/sync":{"post":{"summary":"Sync bootstrap task graph to D1 + R2","description":"Populates the hosted task graph from the embedded snapshot (cap-cloudflare-060). Guarded by SYNC_TOKEN bearer.","operationId":"postAdminSync","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Sync result","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"synced":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Sync disabled (SYNC_TOKEN unset)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/graph":{"get":{"summary":"List executable capsules from the hosted task graph","description":"Returns the set of tasks that are currently executable (status ready or pending with all deps done) per the hosted D1 store. Guarded by SYNC_TOKEN bearer.","operationId":"getAdminGraph","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Executable task list","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer"},"executable":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/status":{"get":{"summary":"Live task counts by status + recent R2 run refs","description":"Unauthenticated. Queries D1 tasks table for counts by status; lists the 10 most-recent R2 objects under the runs/ prefix.","operationId":"getObserveStatus","responses":{"200":{"description":"Status snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"taskCounts":{"$ref":"#/components/schemas/TaskCountsByState"},"recentRuns":{"type":"array","items":{"$ref":"#/components/schemas/RecentRun"}}}}}}},"500":{"description":"D1 or R2 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/events":{"get":{"summary":"Paginated state-transition event log","description":"Unauthenticated. Returns rows from D1 task_events, newest first. All query params are optional.","operationId":"getObserveEvents","parameters":[{"name":"task_id","in":"query","description":"Filter events to a specific task.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum rows to return (default 50, max 200).","schema":{"type":"integer","default":50,"minimum":1,"maximum":200}},{"name":"since","in":"query","description":"ISO8601 datetime; only events at or after this instant.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Event list","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/TaskEventRow"}},"total":{"type":"integer"}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/runs":{"get":{"summary":"Recent run result summaries from R2","description":"Unauthenticated. Lists up to 20 objects under runs/ in the forge-artifacts R2 bucket; fetches each /result.json body and inlines it with an r2:// reference.","operationId":"getObserveRuns","responses":{"200":{"description":"Run result list","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/RunResult"}}}}}}},"500":{"description":"R2 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/metrics":{"get":{"summary":"Aggregated pipeline metrics","description":"Unauthenticated. Returns total task count, task counts by status, and the top 20 state transitions by frequency with cost/token sums — all from D1.","operationId":"getObserveMetrics","responses":{"200":{"description":"Metrics snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsResponse"}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/tasks":{"get":{"summary":"Task rows for agent console inbox/plan","description":"Unauthenticated. Lists D1 task rows, newest updated first. Optional status filter and limit (default 200, max 500).","operationId":"getObserveTasks","parameters":[{"name":"status","in":"query","description":"Filter to a single task status.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum rows after filter (default 200, max 500).","schema":{"type":"integer","default":200,"minimum":1,"maximum":500}}],"responses":{"200":{"description":"Task list","content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/ObserveTaskRow"}},"total":{"type":"integer"}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/capsule/{taskId}":{"get":{"summary":"Capsule body for a task","description":"Unauthenticated. Returns the TaskCapsule JSON from R2 for the given task id.","operationId":"getObserveCapsule","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capsule body","content":{"application/json":{"schema":{"type":"object","properties":{"capsule":{"type":"object","additionalProperties":true}}}}}},"404":{"description":"No capsule in R2 for this task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"R2 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/trace/{taskId}":{"get":{"summary":"Pipeline audit trace for Build stepper","description":"Unauthenticated. Returns task_event_audit rows for one task, ordered by ts.","operationId":"getObserveTrace","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Audit event list","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventRow"}},"total":{"type":"integer"}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/live":{"get":{"summary":"Live pipeline slice for topology view","description":"Unauthenticated. Returns active task rows (running, decomposing, ready, etc.) plus the 100 most recent task_event_audit events.","operationId":"getObserveLive","responses":{"200":{"description":"Live snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"activeTasks":{"type":"array","items":{"$ref":"#/components/schemas/ObserveTaskRow"}},"recentEvents":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventRow"}},"totalTasks":{"type":"integer"}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/replay":{"get":{"summary":"Chronological audit timeline for replay","description":"Unauthenticated. Returns task_event_audit rows in ascending timestamp order for scrubbable pipeline replay.","operationId":"getObserveReplay","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":2000,"default":1000}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"trace_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Replay timeline","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AuditEventRow"}},"total":{"type":"integer"}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/graph":{"get":{"summary":"Task DAG for topology canvas","description":"Unauthenticated. Returns all D1 task rows as nodes plus dependency edges.","operationId":"getObserveGraph","responses":{"200":{"description":"Graph topology","content":{"application/json":{"schema":{"type":"object","properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/TopologyNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/TaskGraphEdge"}}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/aggregates":{"get":{"summary":"Advisor metrics grouped by tier or task_class","operationId":"getObserveAggregates","parameters":[{"name":"groupBy","in":"query","schema":{"type":"string","enum":["tier","task_class"]}},{"name":"tenant","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Metric rows","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object"}},"groupBy":{"type":"string"}}}}}}}}},"/observe/queue-series":{"get":{"summary":"Queue depth time series (24h)","operationId":"getObserveQueueSeries","parameters":[{"name":"tenant","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Hourly ready/running transition counts","content":{"application/json":{"schema":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"hour":{"type":"string"},"count":{"type":"integer"}}}},"currentDepth":{"type":"integer"},"ready":{"type":"integer"},"running":{"type":"integer"}}}}}}}}},"/observe/diff/{taskId}":{"get":{"summary":"Bounded gate/generate diff lines for Build stream","operationId":"getObserveDiff","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Diff lines","content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string"},"lines":{"type":"array","items":{"type":"string"}}}}}}}}}},"/observe/promotions":{"get":{"summary":"Capability promotion records","operationId":"getObservePromotions","parameters":[{"name":"tenant","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Promotion list","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/observe/audit-export":{"get":{"summary":"Tenant audit export bundle","operationId":"getObserveAuditExport","parameters":[{"name":"tenant","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Audit export JSON","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/observe/slo":{"get":{"summary":"SLO traffic-light strip","description":"Unauthenticated. Returns gate pass, escalation, queue, and blocked indicators from live D1 aggregates (docs/ddaa/21 §21.6.2).","operationId":"getObserveSlo","parameters":[{"name":"tenant","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"SLO indicators","content":{"application/json":{"schema":{"type":"object","properties":{"slos":{"type":"array","items":{"$ref":"#/components/schemas/SloIndicator"}}}}}}},"500":{"description":"D1 error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/observe/openapi.json":{"get":{"summary":"OpenAPI 3.1 spec for this Worker","description":"Unauthenticated. Returns this inline OpenAPI 3.1 document. Cached for 1 hour (public). Use with `npx openapi-typescript` to generate typed client code.","operationId":"getObserveOpenApi","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}