@opensoftware/contracts 1.5.0 → 1.7.0

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.5.0",
+    "version": "1.7.0",
     "description": "The shared formats as named models, and the HTTP APIs of the modules. Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
     "license": {
       "name": "Apache-2.0",
@@ -116,6 +116,355 @@
           }
         }
       }
+    },
+    "/v1/runs": {
+      "post": {
+        "operationId": "ForemanApi_startRun",
+        "description": "Start a run of the factory's workflow for a work item. The same work item again answers the run it started.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WorkItem"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{runId}": {
+      "get": {
+        "operationId": "ForemanApi_getRun",
+        "description": "A run: its state and the state of each stage.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/runs/{runId}/signals": {
+      "post": {
+        "operationId": "ForemanApi_signalRun",
+        "description": "Steer the running stage's agent, or cancel the run.",
+        "parameters": [
+          {
+            "name": "runId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "202": {
+            "description": "The request has been accepted for processing, but processing has not yet completed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The request conflicts with the current state of the server.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RunSignal"
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items": {
+      "post": {
+        "operationId": "IntakeApi_submitWork",
+        "description": "Put work into the inbox. A submission with the dedupe key of a work item answers that work item.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "The request has succeeded and a new resource has been created as a result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/WorkSubmission"
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "operationId": "IntakeApi_findWorkItem",
+        "description": "The work item with this dedupe key, such as an issue's link (ADR 0065).",
+        "parameters": [
+          {
+            "name": "dedupeKey",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "explode": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The server could not understand the request due to invalid syntax.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/work-items/{workItemId}": {
+      "get": {
+        "operationId": "IntakeApi_getWorkItem",
+        "description": "A work item, its status and every request that asked for it.",
+        "parameters": [
+          {
+            "name": "workItemId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/WorkItemView"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Access is unauthorized.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "The server cannot find the requested resource.",
+            "content": {
+              "application/problem+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiProblem"
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "security": [
@@ -941,12 +1290,119 @@
         ],
         "description": "gatekeeper: a gate as the HTTP API shows it (ADR 0048)."
       },
+      "Hostname": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$",
+        "description": "A hostname without scheme or port, for example \"api.linear.app\"."
+      },
       "Identifier": {
         "type": "string",
         "minLength": 1,
         "maxLength": 128,
         "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
       },
+      "IssueLabeled": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "issue.labeled@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/IssueLabeledData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "forge adapters: a label was added to an issue."
+      },
+      "IssueLabeledData": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The issue."
+          },
+          "repository": {
+            "type": "string",
+            "format": "uri"
+          },
+          "number": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "body": {
+            "type": "string"
+          },
+          "author": {
+            "$ref": "#/components/schemas/Actor",
+            "description": "The person who opened the issue."
+          },
+          "labels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Every label of the issue after the change."
+          },
+          "label": {
+            "type": "string",
+            "description": "The label that was added, when the forge names it."
+          }
+        },
+        "required": [
+          "url",
+          "repository",
+          "number",
+          "title",
+          "author",
+          "labels"
+        ]
+      },
       "Link": {
         "type": "object",
         "properties": {
@@ -1551,119 +2007,363 @@
             "$ref": "#/components/schemas/Name",
             "description": "Harness adapter, for example \"claude-code\"."
           },
-          "osf.harness.version": {
-            "type": "string"
+          "osf.harness.version": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "service.name",
+          "osf.run.id",
+          "osf.work_item.id",
+          "osf.factory.version",
+          "osf.requester.kind",
+          "osf.requester.id",
+          "osf.source",
+          "osf.harness.name"
+        ],
+        "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+      },
+      "RunSignal": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/RunSignalType"
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The steering message. Required with \"steer\"."
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "description": "foreman: a signal to a run: \"steer\" with a message for the running stage's agent, or \"cancel\"."
+      },
+      "RunSignalType": {
+        "type": "string",
+        "enum": [
+          "steer",
+          "cancel"
+        ],
+        "description": "foreman: what a person tells a run."
+      },
+      "RunSpan": {
+        "type": "object",
+        "properties": {
+          "gen_ai.operation.name": {
+            "type": "string",
+            "const": "invoke_agent"
+          },
+          "gen_ai.provider.name": {
+            "type": "string"
+          },
+          "gen_ai.agent.name": {
+            "type": "string"
+          },
+          "gen_ai.conversation.id": {
+            "type": "string",
+            "description": "The harness session ID."
+          },
+          "gen_ai.request.model": {
+            "type": "string"
+          },
+          "gen_ai.response.model": {
+            "type": "string"
+          },
+          "gen_ai.usage.input_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "gen_ai.usage.output_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "gen_ai.usage.cache_read.input_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "gen_ai.usage.cache_write.input_tokens": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "osf.outcome": {
+            "$ref": "#/components/schemas/RunOutcome"
+          },
+          "osf.cost.usd": {
+            "type": "number",
+            "minimum": 0,
+            "description": "Cost of all model calls of the run, from the inference gateway."
+          },
+          "osf.transcript.uri": {
+            "type": "string",
+            "format": "uri",
+            "description": "Full transcript, stored when the run ends."
+          },
+          "osf.artifact.uris": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Artifacts of the run: reports, screenshots, videos."
+          },
+          "osf.pull_request.urls": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "osf.issue.urls": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "osf.evidence_bundle.uri": {
+            "type": "string",
+            "format": "uri"
+          },
+          "osf.agent_trace.uri": {
+            "type": "string",
+            "format": "uri",
+            "description": "Agent Trace record with line attribution of the run's changes."
+          }
+        },
+        "required": [
+          "gen_ai.operation.name",
+          "osf.outcome"
+        ],
+        "description": "Attributes of the root span of the run. GenAI names where a convention exists."
+      },
+      "RunStarted": {
+        "type": "object",
+        "properties": {
+          "specversion": {
+            "type": "string",
+            "const": "1.0"
+          },
+          "id": {
+            "$ref": "#/components/schemas/Identifier",
+            "description": "Unique per source. A consumer that sees the same source and id twice handles the event once."
+          },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The producing module, for example \"/osf/intake\"."
+          },
+          "type": {
+            "type": "string",
+            "const": "run.started@v1"
+          },
+          "time": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "subject": {
+            "type": "string",
+            "description": "The ID of the thing the event is about: work item, gate, run, score or pull request."
+          },
+          "datacontenttype": {
+            "type": "string",
+            "const": "application/json"
+          },
+          "dataschema": {
+            "type": "string",
+            "format": "uri"
+          },
+          "traceparent": {
+            "type": "string",
+            "description": "W3C trace context (CloudEvents distributed tracing extension)."
+          },
+          "data": {
+            "$ref": "#/components/schemas/RunStartedData"
+          }
+        },
+        "required": [
+          "specversion",
+          "id",
+          "source",
+          "type",
+          "time",
+          "data"
+        ],
+        "description": "foreman: a run started (ADR 0067)."
+      },
+      "RunStartedData": {
+        "type": "object",
+        "properties": {
+          "runId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "workItemId": {
+            "$ref": "#/components/schemas/Identifier"
+          },
+          "factory": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name of the factory."
+          },
+          "factoryVersion": {
+            "$ref": "#/components/schemas/CommitHash"
+          },
+          "stages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Name"
+            },
+            "description": "The stages of the run's workflow, in order."
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "source": {
+            "$ref": "#/components/schemas/Name"
+          }
+        },
+        "required": [
+          "runId",
+          "workItemId",
+          "factory",
+          "factoryVersion",
+          "stages",
+          "startedAt",
+          "requester",
+          "source"
+        ]
+      },
+      "RunState": {
+        "type": "string",
+        "enum": [
+          "running",
+          "blocked",
+          "complete",
+          "failed",
+          "cancelled"
+        ],
+        "description": "foreman: where a run stands (vision scenario ORCH-008)."
+      },
+      "RunView": {
+        "type": "object",
+        "properties": {
+          "runId": {
+            "type": "string",
+            "pattern": "^run_[0-9a-f]{20}$",
+            "description": "\"run_\" and 20 hex digits of the SHA-256 of the work item's ID."
+          },
+          "workItem": {
+            "$ref": "#/components/schemas/WorkItem"
+          },
+          "factory": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name of the factory."
+          },
+          "factoryVersion": {
+            "$ref": "#/components/schemas/CommitHash",
+            "description": "The commit of the factory definition the run started with."
+          },
+          "state": {
+            "$ref": "#/components/schemas/RunState"
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "endedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "stages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/StageView"
+            },
+            "description": "The stages of the workflow, in order."
           }
         },
         "required": [
-          "service.name",
-          "osf.run.id",
-          "osf.work_item.id",
-          "osf.factory.version",
-          "osf.requester.kind",
-          "osf.requester.id",
-          "osf.source",
-          "osf.harness.name"
+          "runId",
+          "workItem",
+          "factory",
+          "factoryVersion",
+          "state",
+          "startedAt",
+          "stages"
         ],
-        "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+        "description": "foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067)."
       },
-      "RunSpan": {
+      "Sandbox": {
         "type": "object",
         "properties": {
-          "gen_ai.operation.name": {
-            "type": "string",
-            "const": "invoke_agent"
-          },
-          "gen_ai.provider.name": {
-            "type": "string"
-          },
-          "gen_ai.agent.name": {
-            "type": "string"
-          },
-          "gen_ai.conversation.id": {
+          "template": {
             "type": "string",
-            "description": "The harness session ID."
-          },
-          "gen_ai.request.model": {
-            "type": "string"
-          },
-          "gen_ai.response.model": {
-            "type": "string"
-          },
-          "gen_ai.usage.input_tokens": {
-            "type": "integer",
-            "minimum": 0
-          },
-          "gen_ai.usage.output_tokens": {
-            "type": "integer",
-            "minimum": 0
-          },
-          "gen_ai.usage.cache_read.input_tokens": {
-            "type": "integer",
-            "minimum": 0
-          },
-          "gen_ai.usage.cache_write.input_tokens": {
-            "type": "integer",
-            "minimum": 0
-          },
-          "osf.outcome": {
-            "$ref": "#/components/schemas/RunOutcome"
+            "minLength": 1,
+            "description": "Sandbox template name, for example \"node-24\"."
           },
-          "osf.cost.usd": {
+          "cpu": {
             "type": "number",
-            "minimum": 0,
-            "description": "Cost of all model calls of the run, from the inference gateway."
+            "minimum": 0.001,
+            "description": "CPU cores. The smallest unit is 0.001 (one millicore)."
           },
-          "osf.transcript.uri": {
+          "memory": {
             "type": "string",
-            "format": "uri",
-            "description": "Full transcript, stored when the run ends."
+            "pattern": "^[0-9]+(Ki|Mi|Gi|Ti)?$",
+            "description": "Kubernetes quantity, for example \"8Gi\"."
           },
-          "osf.artifact.uris": {
+          "egress": {
             "type": "array",
             "items": {
-              "type": "string",
-              "format": "uri"
+              "type": "string"
             },
-            "description": "Artifacts of the run: reports, screenshots, videos."
+            "description": "Hostnames the sandbox may reach. Everything else is blocked."
+          }
+        },
+        "required": [
+          "template"
+        ],
+        "additionalProperties": false
+      },
+      "SandboxMcpServer": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The name in the egress log, for example \"wiki\"."
           },
-          "osf.pull_request.urls": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "format": "uri"
-            }
+          "url": {
+            "type": "string",
+            "pattern": "^https?://[^/]+",
+            "description": "The server's endpoint, for example \"https://wiki.example.com/mcp\"."
           },
-          "osf.issue.urls": {
+          "tools": {
             "type": "array",
             "items": {
-              "type": "string",
-              "format": "uri"
-            }
-          },
-          "osf.evidence_bundle.uri": {
-            "type": "string",
-            "format": "uri"
-          },
-          "osf.agent_trace.uri": {
-            "type": "string",
-            "format": "uri",
-            "description": "Agent Trace record with line attribution of the run's changes."
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "The tools the sandbox may call. A call to any other tool is refused."
           }
         },
         "required": [
-          "gen_ai.operation.name",
-          "osf.outcome"
+          "name",
+          "url",
+          "tools"
         ],
-        "description": "Attributes of the root span of the run. GenAI names where a convention exists."
+        "description": "An MCP server that a sandbox may call over Streamable HTTP.",
+        "additionalProperties": false
       },
-      "Sandbox": {
+      "SandboxSpec": {
         "type": "object",
         "properties": {
           "template": {
             "type": "string",
             "minLength": 1,
-            "description": "Sandbox template name, for example \"node-24\"."
+            "description": "What the sandbox starts from: an image for the docker adapter, a SandboxTemplate for kubernetes, or a snapshot."
           },
           "cpu": {
             "type": "number",
@@ -1678,14 +2378,38 @@
           "egress": {
             "type": "array",
             "items": {
+              "$ref": "#/components/schemas/Hostname"
+            },
+            "description": "Hostnames the sandbox may reach through its egress proxy. Everything else is refused."
+          },
+          "env": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {
               "type": "string"
             },
-            "description": "Hostnames the sandbox may reach. Everything else is blocked."
+            "description": "Variables of the sandbox's environment that hold no secret."
+          },
+          "secrets": {
+            "type": "object",
+            "properties": {},
+            "unevaluatedProperties": {
+              "$ref": "#/components/schemas/SecretReference"
+            },
+            "description": "Secrets by the name of the variable that holds the placeholder in the sandbox. The egress proxy puts the real\nvalue in on the way out, for the hosts of `egress`."
+          },
+          "mcp": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SandboxMcpServer"
+            },
+            "description": "The MCP servers the sandbox may call. A call to any other MCP server is refused."
           }
         },
         "required": [
           "template"
         ],
+        "description": "The input of a sandbox adapter's `create` (ADR 0054): what one sandbox runs, how much it may use, and what it may\nreach. Realizes SCN-FACTORY-RUNTIME-004, -006 and -007.",
         "additionalProperties": false
       },
       "ScenarioEvidence": {
@@ -1942,6 +2666,57 @@
         ],
         "additionalProperties": false
       },
+      "StageState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "blocked",
+          "running",
+          "succeeded",
+          "failed",
+          "rejected",
+          "cancelled"
+        ],
+        "description": "foreman: where a stage of a run stands."
+      },
+      "StageView": {
+        "type": "object",
+        "properties": {
+          "stage": {
+            "$ref": "#/components/schemas/Name"
+          },
+          "agent": {
+            "$ref": "#/components/schemas/Name",
+            "description": "The agent that runs the stage."
+          },
+          "state": {
+            "$ref": "#/components/schemas/StageState"
+          },
+          "sessionId": {
+            "type": "string",
+            "description": "The harness session of the stage's agent, once it started."
+          },
+          "gateId": {
+            "type": "string",
+            "pattern": "^g[0-9a-f]{16}$",
+            "description": "The gate that decides whether the stage starts, once it was requested."
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "endedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "stage",
+          "agent",
+          "state"
+        ],
+        "description": "foreman: one stage of a run (ADR 0067)."
+      },
       "TraceId": {
         "type": "string",
         "pattern": "^[0-9a-f]{32}$",
@@ -2015,6 +2790,13 @@
         ],
         "description": "One unit of requested work: the `data` of a `work.received@v1` CloudEvent."
       },
+      "WorkItemStatus": {
+        "type": "string",
+        "enum": [
+          "received"
+        ],
+        "description": "Where a work item stands."
+      },
       "WorkItemType": {
         "type": "string",
         "enum": [
@@ -2024,6 +2806,36 @@
           "automation"
         ]
       },
+      "WorkItemView": {
+        "type": "object",
+        "properties": {
+          "workItem": {
+            "$ref": "#/components/schemas/WorkItem",
+            "description": "Its ID is \"wi_\" and 20 hex digits of the SHA-256 of its dedupe key."
+          },
+          "status": {
+            "$ref": "#/components/schemas/WorkItemStatus"
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "requests": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/WorkRequest"
+            },
+            "description": "Every submission that asked for the work item, oldest first; one per origin."
+          }
+        },
+        "required": [
+          "workItem",
+          "status",
+          "receivedAt",
+          "requests"
+        ],
+        "description": "intake: a work item as the HTTP API shows it (ADR 0063)."
+      },
       "WorkReceived": {
         "type": "object",
         "properties": {
@@ -2077,6 +2889,70 @@
           "data"
         ],
         "description": "intake: a work item was accepted."
+      },
+      "WorkRequest": {
+        "type": "object",
+        "properties": {
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/Origin"
+          },
+          "receivedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        },
+        "required": [
+          "requester",
+          "origin",
+          "receivedAt"
+        ],
+        "description": "intake: one submission that asked for a work item."
+      },
+      "WorkSubmission": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/WorkItemType",
+            "description": "Default: task."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300
+          },
+          "description": {
+            "type": "string"
+          },
+          "requester": {
+            "$ref": "#/components/schemas/Actor"
+          },
+          "origin": {
+            "$ref": "#/components/schemas/Origin"
+          },
+          "dedupeKey": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Requests with the same key become one work item. Default: the origin's url, else \"<source>:<externalId>\"."
+          },
+          "surface": {
+            "type": "string"
+          },
+          "links": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Link"
+            }
+          }
+        },
+        "required": [
+          "title",
+          "requester",
+          "origin"
+        ],
+        "description": "intake: work to put into the inbox, a work item without its ID (ADR 0063)."
       }
     },
     "securitySchemes": {