@opensoftware/contracts 1.8.0 → 1.9.0

package/dist/generated/types.d.ts

@@ -252,6 +252,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 +432,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 */
@@ -707,7 +716,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 +729,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 +819,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 +987,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 */

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.9.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",
@@ -838,6 +838,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 +1336,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": {
@@ -2069,13 +2093,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 +2332,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 +2782,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.8.0",
+  "version": "1.9.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.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;
 
@@ -98,9 +105,14 @@ model RunView {
 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;