@opensoftware/contracts 1.7.0 → 1.9.0

package/README.md

@@ -53,7 +53,7 @@ first is gatekeeper's: `POST /v1/gates` and `GET /v1/gates/{gateId}` with the mo
 `ApiProblem` (RFC 9457). The second is intake's (ADR 0063): `POST /v1/work-items` and
 `GET /v1/work-items/{workItemId}` with the models `WorkSubmission`, `WorkItemView` and `WorkRequest`. The third is the
 foreman's (ADR 0067): `POST /v1/runs`, `GET /v1/runs/{runId}` and `POST /v1/runs/{runId}/signals` with the models
-`RunView`, `StageView` and `RunSignal`. `pnpm build` compiles the operations with the TypeSpec OpenAPI 3 emitter and copies their
+`RunView`, `StageView`, `CheckView` (ADR 0069) and `RunSignal`. `pnpm build` compiles the operations with the TypeSpec OpenAPI 3 emitter and copies their
 paths next to the named models; an operation that uses a type that is no model fails the build. The package exports
 the type `paths`, which types a client such as openapi-fetch.
 

package/dist/generated/types.d.ts

@@ -193,6 +193,18 @@ export type components = {
         };
         /** @description A path inside the bundle: relative, forward slashes, no "..". */
         BundlePath: string;
+        /** @description The name of a check on the forge: a commit status context. */
+        CheckName: string;
+        /**
+         * @description foreman: the state of a check on the forge (forge port).
+         * @enum {string}
+         */
+        CheckState: "pending" | "success" | "failure" | "error";
+        /** @description foreman: a check that a stage waits for, as the foreman last read it on the run's pull request (ADR 0069). */
+        CheckView: {
+            name: components["schemas"]["CheckName"];
+            state: components["schemas"]["CheckState"];
+        };
         /** @description A Git commit hash, abbreviated (7+) or full. The factory version is the commit of the factory definition. */
         CommitHash: string;
         /**
@@ -240,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"];
@@ -418,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 */
@@ -695,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". */
@@ -705,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 */
@@ -790,6 +814,13 @@ export type components = {
             /** @description The commit of the factory definition the run started with. */
             factoryVersion: components["schemas"]["CommitHash"];
             state: components["schemas"]["RunState"];
+            /**
+             * Format: uri
+             * @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 */
@@ -931,6 +962,11 @@ export type components = {
             agent?: components["schemas"]["Name"];
             /** @description The stage waits for a decision before it starts. */
             gate?: components["schemas"]["Gate"];
+            /**
+             * @description Checks that must succeed on the run's pull request before the stage starts, by their names on the forge, for
+             *     example "verify" (ADR 0069).
+             */
+            checks?: components["schemas"]["CheckName"][];
             /** @description Whether the stage must produce an evidence bundle. */
             evidence?: components["schemas"]["EvidenceRequirement"];
         };
@@ -949,6 +985,15 @@ export type components = {
             sessionId?: string;
             /** @description The gate that decides whether the stage starts, once it was requested. */
             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 */
             startedAt?: string;
             /** Format: date-time */

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export type WorkItemView = Schemas["WorkItemView"];
 export type WorkRequest = Schemas["WorkRequest"];
 export type RunView = Schemas["RunView"];
 export type StageView = Schemas["StageView"];
+export type CheckView = Schemas["CheckView"];
 export type RunSignal = Schemas["RunSignal"];
 export type SandboxSpec = Schemas["SandboxSpec"];
 /** One reason a document does not match its format. `path` is a JSON Pointer into the document. */

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

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": {},
@@ -247,6 +267,15 @@
             "additionalProperties": false,
             "description": "The stage waits for a decision before it starts."
           },
+          "checks": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The name of a check on the forge: a commit status context."
+            },
+            "description": "Checks that must succeed on the run's pull request before the stage starts, by their names on the forge, for\nexample \"verify\" (ADR 0069)."
+          },
           "evidence": {
             "type": "string",
             "enum": [

package/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Open Software Factory contracts",
-    "version": "1.7.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",
@@ -696,6 +696,37 @@
         "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$",
         "description": "A path inside the bundle: relative, forward slashes, no \"..\"."
       },
+      "CheckName": {
+        "type": "string",
+        "minLength": 1,
+        "description": "The name of a check on the forge: a commit status context."
+      },
+      "CheckState": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "success",
+          "failure",
+          "error"
+        ],
+        "description": "foreman: the state of a check on the forge (forge port)."
+      },
+      "CheckView": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "$ref": "#/components/schemas/CheckName"
+          },
+          "state": {
+            "$ref": "#/components/schemas/CheckState"
+          }
+        },
+        "required": [
+          "name",
+          "state"
+        ],
+        "description": "foreman: a check that a stage waits for, as the foreman last read it on the run's pull request (ADR 0069)."
+      },
       "CommitHash": {
         "type": "string",
         "pattern": "^[0-9a-f]{7,40}$",
@@ -807,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": {},
@@ -1301,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": {
@@ -2038,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."
       },
@@ -2270,6 +2327,16 @@
           "state": {
             "$ref": "#/components/schemas/RunState"
           },
+          "pullRequest": {
+            "type": "string",
+            "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"
@@ -2656,6 +2723,13 @@
             "$ref": "#/components/schemas/Gate",
             "description": "The stage waits for a decision before it starts."
           },
+          "checks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CheckName"
+            },
+            "description": "Checks that must succeed on the run's pull request before the stage starts, by their names on the forge, for\nexample \"verify\" (ADR 0069)."
+          },
           "evidence": {
             "$ref": "#/components/schemas/EvidenceRequirement",
             "description": "Whether the stage must produce an evidence bundle."
@@ -2701,6 +2775,23 @@
             "pattern": "^g[0-9a-f]{16}$",
             "description": "The gate that decides whether the stage starts, once it was requested."
           },
+          "checks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CheckView"
+            },
+            "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,
+            "description": "Why the stage ended without success, when the foreman knows."
+          },
           "startedAt": {
             "type": "string",
             "format": "date-time"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.7.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;
@@ -126,10 +141,20 @@ model Stage {
   /** The stage waits for a decision before it starts. */
   gate?: Gate;
 
+  /**
+   * Checks that must succeed on the run's pull request before the stage starts, by their names on the forge, for
+   * example "verify" (ADR 0069).
+   */
+  checks?: CheckName[];
+
   /** Whether the stage must produce an evidence bundle. */
   evidence?: EvidenceRequirement;
 }
 
+/** The name of a check on the forge: a commit status context. */
+@minLength(1)
+scalar CheckName extends string;
+
 enum EvidenceRequirement {
   required,
   optional,

package/typespec/foreman.tsp

@@ -1,6 +1,7 @@
 import "@typespec/json-schema";
 import "./common.tsp";
 import "./work-item.tsp";
+import "./factory-definition.tsp";
 
 using TypeSpec.JsonSchema;
 
@@ -26,6 +27,20 @@ enum StageState {
   cancelled,
 }
 
+/** foreman: the state of a check on the forge (forge port). */
+enum CheckState {
+  pending,
+  success,
+  failure,
+  error,
+}
+
+/** foreman: a check that a stage waits for, as the foreman last read it on the run's pull request (ADR 0069). */
+model CheckView {
+  name: CheckName;
+  state: CheckState;
+}
+
 /** foreman: one stage of a run (ADR 0067). */
 model StageView {
   stage: Name;
@@ -42,6 +57,16 @@ model StageView {
   @pattern("^g[0-9a-f]{16}$")
   gateId?: string;
 
+  /** 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;
+
   startedAt?: utcDateTime;
   endedAt?: utcDateTime;
 }
@@ -61,6 +86,14 @@ model RunView {
   factoryVersion: CommitHash;
 
   state: RunState;
+
+  /** 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;
 
@@ -72,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;