@opensoftware/contracts 1.8.0 → 1.10.0

package/dist/generated/types.d.ts

@@ -40,7 +40,8 @@ export type paths = {
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        /** @description The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071). */
+        get: operations["ForemanApi_listRuns"];
         put?: never;
         /** @description Start a run of the factory's workflow for a work item. The same work item again answers the run it started. */
         post: operations["ForemanApi_startRun"];
@@ -252,6 +253,8 @@ export type components = {
             description?: string;
             /** @description Adapters per port with a version range, pinned in `factory.lock` by `factory plan`. */
             providers?: components["schemas"]["Providers"];
+            /** @description The inference gateway of the adapter under `providers.inference` (ADR 0070). */
+            inference?: components["schemas"]["Inference"];
             /** @description Agents by name. */
             agents: {
                 [key: string]: components["schemas"]["Agent"];
@@ -430,6 +433,13 @@ export type components = {
         Hostname: string;
         /** @description An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque. */
         Identifier: string;
+        /** @description The inference gateway: the adapter's config and the most a run may spend (ADR 0070). */
+        Inference: {
+            /** @description Path to the inference adapter's config, for example a LiteLLM proxy config. */
+            config: string;
+            /** @description The most a run may spend on model calls, in USD. */
+            budget?: number;
+        };
         /** @description forge adapters: a label was added to an issue. */
         IssueLabeled: {
             /** @constant */
@@ -675,6 +685,10 @@ export type components = {
             /** Format: uri */
             evidenceBundle?: string;
         };
+        /** @description foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071). */
+        RunList: {
+            runs: components["schemas"]["RunView"][];
+        };
         /**
          * @description How a run ended.
          * @enum {string}
@@ -707,7 +721,10 @@ export type components = {
             "osf.harness.name": components["schemas"]["Name"];
             "osf.harness.version"?: string;
         };
-        /** @description foreman: a signal to a run: "steer" with a message for the running stage's agent, or "cancel". */
+        /**
+         * @description foreman: a signal to a run: "steer" with a message for the running stage's agent, "cancel", "take-over" of the running
+         *     stage by a person, or "hand-back" of that stage (ADR 0070).
+         */
         RunSignal: {
             type: components["schemas"]["RunSignalType"];
             /** @description The steering message. Required with "steer". */
@@ -717,7 +734,7 @@ export type components = {
          * @description foreman: what a person tells a run.
          * @enum {string}
          */
-        RunSignalType: "steer" | "cancel";
+        RunSignalType: "steer" | "cancel" | "take-over" | "hand-back";
         /** @description Attributes of the root span of the run. GenAI names where a convention exists. */
         RunSpan: {
             /** @constant */
@@ -807,6 +824,8 @@ export type components = {
              * @description The last pull request link that an agent of the run wrote (ADR 0069).
              */
             pullRequest?: string;
+            /** @description The run's folder on the foreman's machine, where a person who took over a stage goes on (ADR 0070). */
+            folder?: string;
             /** Format: date-time */
             startedAt: string;
             /** Format: date-time */
@@ -973,6 +992,11 @@ export type components = {
             gateId?: string;
             /** @description The checks the stage waits for, once the foreman read them (ADR 0069). */
             checks?: components["schemas"]["CheckView"][];
+            /**
+             * Format: date-time
+             * @description When a person took the stage over from its agent (ADR 0070).
+             */
+            takenOverAt?: string;
             /** @description Why the stage ended without success, when the foreman knows. */
             reason?: string;
             /** Format: date-time */
@@ -1006,10 +1030,10 @@ export type components = {
             links?: components["schemas"]["Link"][];
         };
         /**
-         * @description Where a work item stands.
+         * @description Where a work item stands: received, then as its run in the foreman goes (ADR 0071).
          * @enum {string}
          */
-        WorkItemStatus: "received";
+        WorkItemStatus: "received" | "running" | "complete" | "failed" | "cancelled";
         /** @enum {string} */
         WorkItemType: "idea" | "bug" | "task" | "automation";
         /** @description intake: a work item as the HTTP API shows it (ADR 0063). */
@@ -1017,6 +1041,8 @@ export type components = {
             /** @description Its ID is "wi_" and 20 hex digits of the SHA-256 of its dedupe key. */
             workItem: components["schemas"]["WorkItem"];
             status: components["schemas"]["WorkItemStatus"];
+            /** @description The foreman's run of the work item, once it started (ADR 0071). */
+            runId?: string;
             /** Format: date-time */
             receivedAt: string;
             /** @description Every submission that asked for the work item, oldest first; one per origin. */
@@ -1164,6 +1190,46 @@ export interface operations {
             };
         };
     };
+    ForemanApi_listRuns: {
+        parameters: {
+            query?: {
+                state?: components["schemas"]["RunState"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The request has succeeded. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RunList"];
+                };
+            };
+            /** @description The server could not understand the request due to invalid syntax. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+            /** @description Access is unauthorized. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["ApiProblem"];
+                };
+            };
+        };
+    };
     ForemanApi_startRun: {
         parameters: {
             query?: never;

package/factory-definition/factory-definition.schema.json

@@ -112,6 +112,26 @@
       "description": "Adapters per port with a version range, pinned in `factory.lock` by `factory plan`.",
       "additionalProperties": false
     },
+    "inference": {
+      "type": "object",
+      "properties": {
+        "config": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to the inference adapter's config, for example a LiteLLM proxy config."
+        },
+        "budget": {
+          "type": "number",
+          "minimum": 0,
+          "description": "The most a run may spend on model calls, in USD."
+        }
+      },
+      "required": [
+        "config"
+      ],
+      "description": "The inference gateway of the adapter under `providers.inference` (ADR 0070).",
+      "additionalProperties": false
+    },
     "agents": {
       "type": "object",
       "properties": {},

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.8.0",
+    "version": "1.10.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",
@@ -174,6 +174,53 @@
             }
           }
         }
+      },
+      "get": {
+        "operationId": "ForemanApi_listRuns",
+        "description": "The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071).",
+        "parameters": [
+          {
+            "name": "state",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "$ref": "#/components/schemas/RunState"
+            },
+            "explode": false
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RunList"
+                }
+              }
+            }
+          },
+          "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"
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/v1/runs/{runId}": {
@@ -838,6 +885,10 @@
             "$ref": "#/components/schemas/Providers",
             "description": "Adapters per port with a version range, pinned in `factory.lock` by `factory plan`."
           },
+          "inference": {
+            "$ref": "#/components/schemas/Inference",
+            "description": "The inference gateway of the adapter under `providers.inference` (ADR 0070)."
+          },
           "agents": {
             "type": "object",
             "properties": {},
@@ -1332,6 +1383,26 @@
         "maxLength": 128,
         "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
       },
+      "Inference": {
+        "type": "object",
+        "properties": {
+          "config": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Path to the inference adapter's config, for example a LiteLLM proxy config."
+          },
+          "budget": {
+            "type": "number",
+            "minimum": 0,
+            "description": "The most a run may spend on model calls, in USD."
+          }
+        },
+        "required": [
+          "config"
+        ],
+        "description": "The inference gateway: the adapter's config and the most a run may spend (ADR 0070).",
+        "additionalProperties": false
+      },
       "IssueLabeled": {
         "type": "object",
         "properties": {
@@ -1976,6 +2047,21 @@
           "source"
         ]
       },
+      "RunList": {
+        "type": "object",
+        "properties": {
+          "runs": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RunView"
+            }
+          }
+        },
+        "required": [
+          "runs"
+        ],
+        "description": "foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071)."
+      },
       "RunOutcome": {
         "type": "string",
         "enum": [
@@ -2069,13 +2155,15 @@
         "required": [
           "type"
         ],
-        "description": "foreman: a signal to a run: \"steer\" with a message for the running stage's agent, or \"cancel\"."
+        "description": "foreman: a signal to a run: \"steer\" with a message for the running stage's agent, \"cancel\", \"take-over\" of the running\nstage by a person, or \"hand-back\" of that stage (ADR 0070)."
       },
       "RunSignalType": {
         "type": "string",
         "enum": [
           "steer",
-          "cancel"
+          "cancel",
+          "take-over",
+          "hand-back"
         ],
         "description": "foreman: what a person tells a run."
       },
@@ -2306,6 +2394,11 @@
             "format": "uri",
             "description": "The last pull request link that an agent of the run wrote (ADR 0069)."
           },
+          "folder": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The run's folder on the foreman's machine, where a person who took over a stage goes on (ADR 0070)."
+          },
           "startedAt": {
             "type": "string",
             "format": "date-time"
@@ -2751,6 +2844,11 @@
             },
             "description": "The checks the stage waits for, once the foreman read them (ADR 0069)."
           },
+          "takenOverAt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When a person took the stage over from its agent (ADR 0070)."
+          },
           "reason": {
             "type": "string",
             "minLength": 1,
@@ -2848,9 +2946,13 @@
       "WorkItemStatus": {
         "type": "string",
         "enum": [
-          "received"
+          "received",
+          "running",
+          "complete",
+          "failed",
+          "cancelled"
         ],
-        "description": "Where a work item stands."
+        "description": "Where a work item stands: received, then as its run in the foreman goes (ADR 0071)."
       },
       "WorkItemType": {
         "type": "string",
@@ -2871,6 +2973,11 @@
           "status": {
             "$ref": "#/components/schemas/WorkItemStatus"
           },
+          "runId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The foreman's run of the work item, once it started (ADR 0071)."
+          },
           "receivedAt": {
             "type": "string",
             "format": "date-time"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
     "@typespec/openapi": "1.17.0",
     "@typespec/openapi3": "1.17.0",
     "openapi-typescript": "7.13.0",
-    "@opensoftware/testkit": "0.23.0"
+    "@opensoftware/testkit": "0.24.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/typespec/factory-definition.tsp

@@ -29,6 +29,9 @@ model FactoryDefinition {
   /** Adapters per port with a version range, pinned in `factory.lock` by `factory plan`. */
   providers?: Providers;
 
+  /** The inference gateway of the adapter under `providers.inference` (ADR 0070). */
+  inference?: Inference;
+
   /** Agents by name. */
   @minProperties(1)
   agents: Record<Agent>;
@@ -64,6 +67,18 @@ model Providers {
   policy?: Record<VersionRange>;
 }
 
+/** The inference gateway: the adapter's config and the most a run may spend (ADR 0070). */
+@extension("additionalProperties", Json<false>)
+model Inference {
+  /** Path to the inference adapter's config, for example a LiteLLM proxy config. */
+  @minLength(1)
+  config: string;
+
+  /** The most a run may spend on model calls, in USD. */
+  @minValue(0)
+  budget?: float64;
+}
+
 /** A reference to a secret, resolved at the egress proxy, never in the sandbox: "ref:<provider>/<name>". */
 @pattern("^ref:[a-z][a-z0-9-]*/[A-Za-z0-9_./-]+$")
 scalar SecretReference extends string;

package/typespec/foreman-api.tsp

@@ -25,6 +25,11 @@ namespace ForemanApi {
     | GatekeeperApi.Failure<400>
     | GatekeeperApi.Failure<401>;
 
+  /** The runs of the server, running runs first, then the runs that ended, the one that ended last first; with `state`, only the runs in that state (ADR 0071). */
+  @route("/v1/runs")
+  @get
+  op listRuns(@query state?: RunState): RunList | GatekeeperApi.Failure<400> | GatekeeperApi.Failure<401>;
+
   /** A run: its state and the state of each stage. */
   @route("/v1/runs/{runId}")
   @get

package/typespec/foreman.tsp

@@ -60,6 +60,9 @@ model StageView {
   /** The checks the stage waits for, once the foreman read them (ADR 0069). */
   checks?: CheckView[];
 
+  /** When a person took the stage over from its agent (ADR 0070). */
+  takenOverAt?: utcDateTime;
+
   /** Why the stage ended without success, when the foreman knows. */
   @minLength(1)
   reason?: string;
@@ -87,6 +90,10 @@ model RunView {
   /** The last pull request link that an agent of the run wrote (ADR 0069). */
   pullRequest?: url;
 
+  /** The run's folder on the foreman's machine, where a person who took over a stage goes on (ADR 0070). */
+  @minLength(1)
+  folder?: string;
+
   startedAt: utcDateTime;
   endedAt?: utcDateTime;
 
@@ -94,13 +101,23 @@ model RunView {
   stages: StageView[];
 }
 
+/** foreman: the runs of the server, running runs first, then the runs that ended, the one that ended last first, as `GET /v1/runs` answers them (ADR 0071). */
+model RunList {
+  runs: RunView[];
+}
+
 /** foreman: what a person tells a run. */
 enum RunSignalType {
   steer,
   cancel,
+  `take-over`,
+  `hand-back`,
 }
 
-/** foreman: a signal to a run: "steer" with a message for the running stage's agent, or "cancel". */
+/**
+ * foreman: a signal to a run: "steer" with a message for the running stage's agent, "cancel", "take-over" of the running
+ * stage by a person, or "hand-back" of that stage (ADR 0070).
+ */
 model RunSignal {
   type: RunSignalType;
 

package/typespec/intake.tsp

@@ -27,9 +27,13 @@ model WorkSubmission {
   links?: Link[];
 }
 
-/** Where a work item stands. */
+/** Where a work item stands: received, then as its run in the foreman goes (ADR 0071). */
 enum WorkItemStatus {
   received,
+  running,
+  complete,
+  failed,
+  cancelled,
 }
 
 /** intake: one submission that asked for a work item. */
@@ -45,6 +49,11 @@ model WorkItemView {
   workItem: WorkItem;
 
   status: WorkItemStatus;
+
+  /** The foreman's run of the work item, once it started (ADR 0071). */
+  @minLength(1)
+  runId?: string;
+
   receivedAt: utcDateTime;
 
   /** Every submission that asked for the work item, oldest first; one per origin. */