@opensoftware/contracts 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "1.5.0",
+  "version": "1.7.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.12.0"
+    "@opensoftware/testkit": "0.23.0"
   },
   "scripts": {
     "build": "node scripts/build.ts",

package/sandbox-spec/sandbox-spec.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/sandbox-spec/sandbox-spec.schema.json",
+  "title": "SandboxSpec",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "template": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What the sandbox starts from: an image for the docker adapter, a SandboxTemplate for kubernetes, or a snapshot."
+    },
+    "cpu": {
+      "type": "number",
+      "minimum": 0.001,
+      "description": "CPU cores. The smallest unit is 0.001 (one millicore)."
+    },
+    "memory": {
+      "type": "string",
+      "pattern": "^[0-9]+(Ki|Mi|Gi|Ti)?$",
+      "description": "Kubernetes quantity, for example \"8Gi\"."
+    },
+    "egress": {
+      "type": "array",
+      "items": {
+        "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\"."
+      },
+      "description": "Hostnames the sandbox may reach through its egress proxy. Everything else is refused."
+    },
+    "env": {
+      "type": "object",
+      "properties": {},
+      "unevaluatedProperties": {
+        "type": "string"
+      },
+      "description": "Variables of the sandbox's environment that hold no secret."
+    },
+    "secrets": {
+      "type": "object",
+      "properties": {},
+      "unevaluatedProperties": {
+        "type": "string",
+        "pattern": "^ref:[a-z][a-z0-9-]*/[A-Za-z0-9_./-]+$",
+        "description": "A reference to a secret, resolved at the egress proxy, never in the sandbox: \"ref:<provider>/<name>\"."
+      },
+      "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": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,62}$",
+            "description": "The name in the egress log, for example \"wiki\"."
+          },
+          "url": {
+            "type": "string",
+            "pattern": "^https?://[^/]+",
+            "description": "The server's endpoint, for example \"https://wiki.example.com/mcp\"."
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "The tools the sandbox may call. A call to any other tool is refused."
+          }
+        },
+        "required": [
+          "name",
+          "url",
+          "tools"
+        ],
+        "description": "An MCP server that a sandbox may call over Streamable HTTP.",
+        "additionalProperties": false
+      },
+      "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
+}

package/typespec/events.tsp

@@ -39,6 +39,9 @@ model CloudEvent<Type extends string, Data> {
 /** intake: a work item was accepted. */
 model WorkReceived is CloudEvent<"work.received@v1", WorkItem>;
 
+/** foreman: a run started (ADR 0067). */
+model RunStarted is CloudEvent<"run.started@v1", RunStartedData>;
+
 /** foreman: a run ended. */
 model RunCompleted is CloudEvent<"run.completed@v1", RunCompletedData>;
 
@@ -60,6 +63,26 @@ model PrReviewed is CloudEvent<"pr.reviewed@v1", PrReviewedData>;
 /** forge adapters: a pull request was merged or closed without a merge. */
 model PrClosed is CloudEvent<"pr.closed@v1", PrClosedData>;
 
+/** forge adapters: a label was added to an issue. */
+model IssueLabeled is CloudEvent<"issue.labeled@v1", IssueLabeledData>;
+
+model RunStartedData {
+  runId: Identifier;
+  workItemId: Identifier;
+
+  /** The name of the factory. */
+  factory: Name;
+
+  factoryVersion: CommitHash;
+
+  /** The stages of the run's workflow, in order. */
+  stages: Name[];
+
+  startedAt: utcDateTime;
+  requester: Actor;
+  source: Name;
+}
+
 model RunCompletedData {
   runId: Identifier;
   workItemId: Identifier;
@@ -166,3 +189,27 @@ model PrClosedData {
 
   mergeCommit?: CommitHash;
 }
+
+model IssueLabeledData {
+  /** The issue. */
+  url: url;
+
+  repository: url;
+
+  @minValue(1)
+  number: safeint;
+
+  @minLength(1)
+  title: string;
+
+  body?: string;
+
+  /** The person who opened the issue. */
+  author: Actor;
+
+  /** Every label of the issue after the change. */
+  labels: string[];
+
+  /** The label that was added, when the forge names it. */
+  label?: string;
+}

package/typespec/foreman-api.tsp

@@ -0,0 +1,45 @@
+// The HTTP API of `foreman serve` (ADR 0067). `pnpm build` compiles it with the OpenAPI 3 emitter and copies its paths
+// into openapi/openapi.json, next to gatekeeper's and intake's; the models are the named models of the JSON Schema
+// bundle.
+import "@typespec/http";
+import "./foreman.tsp";
+import "./gatekeeper-api.tsp";
+
+using TypeSpec.Http;
+
+namespace Osf.Contracts;
+
+namespace ForemanApi {
+  /** Start a run of the factory's workflow for a work item. The same work item again answers the run it started. */
+  @route("/v1/runs")
+  @post
+  op startRun(@body workItem: WorkItem):
+    | {
+        @statusCode statusCode: 201;
+        @body run: RunView;
+      }
+    | {
+        @statusCode statusCode: 200;
+        @body run: RunView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>;
+
+  /** A run: its state and the state of each stage. */
+  @route("/v1/runs/{runId}")
+  @get
+  op getRun(@path runId: string): RunView | GatekeeperApi.Failure<401> | GatekeeperApi.Failure<404>;
+
+  /** Steer the running stage's agent, or cancel the run. */
+  @route("/v1/runs/{runId}/signals")
+  @post
+  op signalRun(@path runId: string, @body signal: RunSignal):
+    | {
+        @statusCode statusCode: 202;
+        @body run: RunView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>
+    | GatekeeperApi.Failure<404>
+    | GatekeeperApi.Failure<409>;
+}

package/typespec/foreman.tsp

@@ -0,0 +1,84 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./work-item.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** foreman: where a run stands (vision scenario ORCH-008). */
+enum RunState {
+  running,
+  blocked,
+  complete,
+  failed,
+  cancelled,
+}
+
+/** foreman: where a stage of a run stands. */
+enum StageState {
+  pending,
+  blocked,
+  running,
+  succeeded,
+  failed,
+  rejected,
+  cancelled,
+}
+
+/** foreman: one stage of a run (ADR 0067). */
+model StageView {
+  stage: Name;
+
+  /** The agent that runs the stage. */
+  agent: Name;
+
+  state: StageState;
+
+  /** The harness session of the stage's agent, once it started. */
+  sessionId?: string;
+
+  /** The gate that decides whether the stage starts, once it was requested. */
+  @pattern("^g[0-9a-f]{16}$")
+  gateId?: string;
+
+  startedAt?: utcDateTime;
+  endedAt?: utcDateTime;
+}
+
+/** foreman: a run of the factory's workflow for one work item, as the HTTP API shows it (ADR 0067). */
+model RunView {
+  /** "run_" and 20 hex digits of the SHA-256 of the work item's ID. */
+  @pattern("^run_[0-9a-f]{20}$")
+  runId: string;
+
+  workItem: WorkItem;
+
+  /** The name of the factory. */
+  factory: Name;
+
+  /** The commit of the factory definition the run started with. */
+  factoryVersion: CommitHash;
+
+  state: RunState;
+  startedAt: utcDateTime;
+  endedAt?: utcDateTime;
+
+  /** The stages of the workflow, in order. */
+  stages: StageView[];
+}
+
+/** foreman: what a person tells a run. */
+enum RunSignalType {
+  steer,
+  cancel,
+}
+
+/** foreman: a signal to a run: "steer" with a message for the running stage's agent, or "cancel". */
+model RunSignal {
+  type: RunSignalType;
+
+  /** The steering message. Required with "steer". */
+  @minLength(1)
+  message?: string;
+}

package/typespec/intake-api.tsp

@@ -0,0 +1,40 @@
+// The HTTP API of `intake serve` (ADR 0063). `pnpm build` compiles it with the OpenAPI 3 emitter and copies its paths
+// into openapi/openapi.json, next to gatekeeper's; the models are the named models of the JSON Schema bundle.
+import "@typespec/http";
+import "./intake.tsp";
+import "./gatekeeper-api.tsp";
+
+using TypeSpec.Http;
+
+namespace Osf.Contracts;
+
+namespace IntakeApi {
+  /** Put work into the inbox. A submission with the dedupe key of a work item answers that work item. */
+  @route("/v1/work-items")
+  @post
+  op submitWork(@body submission: WorkSubmission):
+    | {
+        @statusCode statusCode: 201;
+        @body workItem: WorkItemView;
+      }
+    | {
+        @statusCode statusCode: 200;
+        @body workItem: WorkItemView;
+      }
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>;
+
+  /** The work item with this dedupe key, such as an issue's link (ADR 0065). */
+  @route("/v1/work-items")
+  @get
+  op findWorkItem(@query dedupeKey: string):
+    | WorkItemView
+    | GatekeeperApi.Failure<400>
+    | GatekeeperApi.Failure<401>
+    | GatekeeperApi.Failure<404>;
+
+  /** A work item, its status and every request that asked for it. */
+  @route("/v1/work-items/{workItemId}")
+  @get
+  op getWorkItem(@path workItemId: string): WorkItemView | GatekeeperApi.Failure<401> | GatekeeperApi.Failure<404>;
+}

package/typespec/intake.tsp

@@ -0,0 +1,52 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./work-item.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** intake: work to put into the inbox, a work item without its ID (ADR 0063). */
+model WorkSubmission {
+  /** Default: task. */
+  type?: WorkItemType;
+
+  @minLength(1)
+  @maxLength(300)
+  title: string;
+
+  description?: string;
+  requester: Actor;
+  origin: Origin;
+
+  /** Requests with the same key become one work item. Default: the origin's url, else "<source>:<externalId>". */
+  @minLength(1)
+  dedupeKey?: string;
+
+  surface?: string;
+  links?: Link[];
+}
+
+/** Where a work item stands. */
+enum WorkItemStatus {
+  received,
+}
+
+/** intake: one submission that asked for a work item. */
+model WorkRequest {
+  requester: Actor;
+  origin: Origin;
+  receivedAt: utcDateTime;
+}
+
+/** intake: a work item as the HTTP API shows it (ADR 0063). */
+model WorkItemView {
+  /** Its ID is "wi_" and 20 hex digits of the SHA-256 of its dedupe key. */
+  workItem: WorkItem;
+
+  status: WorkItemStatus;
+  receivedAt: utcDateTime;
+
+  /** Every submission that asked for the work item, oldest first; one per origin. */
+  requests: WorkRequest[];
+}

package/typespec/main.tsp

@@ -10,3 +10,8 @@ import "./score.tsp";
 import "./events.tsp";
 import "./gatekeeper.tsp";
 import "./gatekeeper-api.tsp";
+import "./intake.tsp";
+import "./intake-api.tsp";
+import "./foreman.tsp";
+import "./foreman-api.tsp";
+import "./sandbox.tsp";

package/typespec/sandbox.tsp

@@ -0,0 +1,63 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./factory-definition.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+// The sandbox spec is written by a program (foreman) for a sandbox adapter, and a sandbox must never get more than
+// it asked for: every object is closed, so an unknown field is an error and not a silent grant.
+
+/**
+ * The input of a sandbox adapter's `create` (ADR 0054): what one sandbox runs, how much it may use, and what it may
+ * reach. Realizes SCN-FACTORY-RUNTIME-004, -006 and -007.
+ */
+@extension("additionalProperties", Json<false>)
+model SandboxSpec {
+  /** What the sandbox starts from: an image for the docker adapter, a SandboxTemplate for kubernetes, or a snapshot. */
+  @minLength(1)
+  template: string;
+
+  /** CPU cores. The smallest unit is 0.001 (one millicore). */
+  @minValue(0.001)
+  cpu?: float64;
+
+  /** Kubernetes quantity, for example "8Gi". */
+  @pattern("^[0-9]+(Ki|Mi|Gi|Ti)?$")
+  memory?: string;
+
+  /** Hostnames the sandbox may reach through its egress proxy. Everything else is refused. */
+  egress?: Hostname[];
+
+  /** Variables of the sandbox's environment that hold no secret. */
+  env?: Record<string>;
+
+  /**
+   * Secrets by the name of the variable that holds the placeholder in the sandbox. The egress proxy puts the real
+   * value in on the way out, for the hosts of `egress`.
+   */
+  secrets?: Record<SecretReference>;
+
+  /** The MCP servers the sandbox may call. A call to any other MCP server is refused. */
+  mcp?: SandboxMcpServer[];
+}
+
+/** A hostname without scheme or port, for example "api.linear.app". */
+@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])?)*$")
+scalar Hostname extends string;
+
+/** An MCP server that a sandbox may call over Streamable HTTP. */
+@extension("additionalProperties", Json<false>)
+model SandboxMcpServer {
+  /** The name in the egress log, for example "wiki". */
+  name: Name;
+
+  /** The server's endpoint, for example "https://wiki.example.com/mcp". */
+  @pattern("^https?://[^/]+")
+  url: string;
+
+  /** The tools the sandbox may call. A call to any other tool is refused. */
+  @minItems(1)
+  tools: string[];
+}