@opensoftware/contracts 0.0.0-stage → 1.4.0

package/typespec/factory-definition.tsp

@@ -0,0 +1,193 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+// Every object in the factory definition is closed: people write it by hand, so an unknown field is a typo
+// and is rejected with its path.
+
+/**
+ * `factory.yaml`: the desired state of one factory (P3). Paths are relative to the file.
+ * Realizes SCN-FACTORY-CODE-001: agents and prompts; MCP servers, skills and secrets per agent;
+ * repositories; model and runtime; automations; scorers and benchmarks.
+ */
+@extension("additionalProperties", Json<false>)
+model FactoryDefinition {
+  /** Editors may point at this schema. Ignored by every tool. */
+  `$schema`?: string;
+
+  /** Version of this format. A new major version of the format gets a new value. */
+  version: FormatVersion;
+
+  /** Name of the factory. */
+  factory: Name;
+
+  description?: string;
+
+  /** Adapters per port with a version range, pinned in `factory.lock` by `factory plan`. */
+  providers?: Providers;
+
+  /** Agents by name. */
+  @minProperties(1)
+  agents: Record<Agent>;
+
+  /** Stages in order. Each stage runs one agent; the agent defaults to the stage name. */
+  workflow?: Stage[];
+
+  /** What starts work without a person asking. */
+  automations?: Automation[];
+
+  /** Scorers by name. */
+  scorers?: Record<Scorer>;
+
+  /** Benchmark suites by name. */
+  benchmarks?: Record<Benchmark>;
+}
+
+/** A semver range of an adapter, for example "^2". */
+@minLength(1)
+scalar VersionRange extends string;
+
+/** The adapters a factory uses, per port (docs/architecture/internals.md). Keys are adapter names. */
+@extension("additionalProperties", Json<false>)
+model Providers {
+  harness?: Record<VersionRange>;
+  sandbox?: Record<VersionRange>;
+  channel?: Record<VersionRange>;
+  tracker?: Record<VersionRange>;
+  forge?: Record<VersionRange>;
+  inference?: Record<VersionRange>;
+  secrets?: Record<VersionRange>;
+  telemetry?: Record<VersionRange>;
+  policy?: Record<VersionRange>;
+}
+
+/** 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;
+
+@extension("additionalProperties", Json<false>)
+model Agent {
+  description?: string;
+
+  /** Harness adapter, declared under `providers.harness`, for example "claude-code". */
+  harness: Name;
+
+  /** A model ID or a routing alias of the inference gateway, for example "routes/triage". */
+  @minLength(1)
+  `model`: string;
+
+  /** Path to the Markdown prompt. */
+  @minLength(1)
+  prompt: string;
+
+  /** Repositories the agent operates on, as clone URLs or "<owner>/<name>". */
+  repositories?: string[];
+
+  /** MCP servers: `registry:<name>@<version>` or `<name>@<version>`. */
+  mcp?: string[];
+
+  /** Paths to skill folders. */
+  skills?: string[];
+
+  secrets?: SecretReference[];
+
+  /** Runtime of the agent. */
+  sandbox?: Sandbox;
+}
+
+@extension("additionalProperties", Json<false>)
+model Sandbox {
+  /** Sandbox template name, for example "node-24". */
+  @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. Everything else is blocked. */
+  egress?: string[];
+}
+
+@extension("additionalProperties", Json<false>)
+model Stage {
+  stage: Name;
+
+  /** Agent that runs the stage. Defaults to the agent with the stage's name. */
+  agent?: Name;
+
+  /** The stage waits for a decision before it starts. */
+  gate?: Gate;
+
+  /** Whether the stage must produce an evidence bundle. */
+  evidence?: EvidenceRequirement;
+}
+
+enum EvidenceRequirement {
+  required,
+  optional,
+}
+
+@extension("additionalProperties", Json<false>)
+model Gate {
+  /** Path to the Rego policy that decides or picks the approvers. */
+  @minLength(1)
+  policy: string;
+
+  /** Approver groups. The policy may narrow them. */
+  approvers?: Name[];
+}
+
+/**
+ * Starts the workflow, or the named job, on an event (`on`) or a schedule (`cron`). Exactly one of the two; a
+ * schedule names its job. One model rather than a union, so every generated client reads it without guessing.
+ */
+@extension("additionalProperties", Json<false>)
+@extension(
+  "oneOf",
+  #[
+    #{ required: #["on"], not: #{ required: #["cron"] } },
+    #{ required: #["cron", "run"], not: #{ required: #["on"] } }
+  ]
+)
+model Automation {
+  /** Event filter, for example "github.issue.labeled(auto-implement)" or "sentry.fatal". */
+  @minLength(1)
+  on?: string;
+
+  /** Five-field cron expression in UTC. */
+  @minLength(1)
+  cron?: string;
+
+  /** Job to run. Required with `cron`; without it an event starts the workflow. */
+  run?: Name;
+}
+
+@extension("additionalProperties", Json<false>)
+model Scorer {
+  /** Path to the Markdown judge prompt. */
+  @minLength(1)
+  judge: string;
+
+  /** Share of runs to score, 0 to 1. Default 1. */
+  @minValue(0)
+  @maxValue(1)
+  sample?: float64;
+}
+
+@extension("additionalProperties", Json<false>)
+model Benchmark {
+  /** Path to the Harbor task suite. */
+  @minLength(1)
+  suite: string;
+
+  /** Five-field cron expression in UTC. Without it the suite runs on request. */
+  schedule?: string;
+}

package/typespec/main.tsp

@@ -0,0 +1,10 @@
+// The single source of the shared formats (ADR 0006). `pnpm build` emits one JSON Schema per format into
+// contracts/<format>/<format>.schema.json and an OpenAPI 3.1 document for the generated clients.
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./factory-definition.tsp";
+import "./work-item.tsp";
+import "./run-record.tsp";
+import "./evidence-bundle.tsp";
+import "./score.tsp";
+import "./events.tsp";

package/typespec/run-record.tsp

@@ -0,0 +1,88 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+// Attribute names follow the OpenTelemetry semantic conventions v1.44.0 (resource) and the GenAI semantic
+// conventions at open-telemetry/semantic-conventions-genai@547934a (schema gen-ai-dev/1.42.0-dev, status
+// Development). Factory attributes use the `osf.` namespace so they never collide with future OTel names.
+
+/**
+ * The attributes of one run: the OTel resource of every span of the run, and the attributes of its root
+ * `invoke_agent` span. The run record travels as OTLP; this schema fixes the attribute names and types.
+ * Realizes SCN-FACTORY-DATA-001 (record shape) and SCN-FACTORY-RUNTIME-008 (attribution).
+ */
+model RunRecord {
+  resource: RunResource;
+  span: RunSpan;
+}
+
+/** Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run. */
+model RunResource {
+  `service.name`: string;
+  `osf.run.id`: Identifier;
+  `osf.work_item.id`: Identifier;
+
+  /** Commit of the factory definition the run used. */
+  `osf.factory.version`: CommitHash;
+
+  `osf.stage`?: Name;
+  `osf.requester.kind`: ActorKind;
+  `osf.requester.id`: string;
+
+  /** Where the run was started from, for example "slack", "github", "cli". */
+  `osf.source`: Name;
+
+  `osf.origin.url`?: url;
+
+  /** Harness adapter, for example "claude-code". */
+  `osf.harness.name`: Name;
+
+  `osf.harness.version`?: string;
+}
+
+/** Attributes of the root span of the run. GenAI names where a convention exists. */
+model RunSpan {
+  `gen_ai.operation.name`: "invoke_agent";
+  `gen_ai.provider.name`?: string;
+  `gen_ai.agent.name`?: string;
+
+  /** The harness session ID. */
+  `gen_ai.conversation.id`?: string;
+
+  `gen_ai.request.model`?: string;
+  `gen_ai.response.model`?: string;
+
+  @minValue(0)
+  `gen_ai.usage.input_tokens`?: safeint;
+
+  @minValue(0)
+  `gen_ai.usage.output_tokens`?: safeint;
+
+  @minValue(0)
+  `gen_ai.usage.cache_read.input_tokens`?: safeint;
+
+  @minValue(0)
+  `gen_ai.usage.cache_write.input_tokens`?: safeint;
+
+  `osf.outcome`: RunOutcome;
+
+  /** Cost of all model calls of the run, from the inference gateway. */
+  @minValue(0)
+  `osf.cost.usd`?: float64;
+
+  /** Full transcript, stored when the run ends. */
+  `osf.transcript.uri`?: url;
+
+  /** Artifacts of the run: reports, screenshots, videos. */
+  `osf.artifact.uris`?: url[];
+
+  `osf.pull_request.urls`?: url[];
+  `osf.issue.urls`?: url[];
+  `osf.evidence_bundle.uri`?: url;
+
+  /** Agent Trace record with line attribution of the run's changes. */
+  `osf.agent_trace.uri`?: url;
+}

package/typespec/score.tsp

@@ -0,0 +1,68 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/**
+ * The result of one scorer on one run. The fields are a subset of Langfuse's create-score request
+ * (POST /api/public/scores), so a score can be sent to Langfuse as is. Factory fields live in `metadata`.
+ */
+model Score {
+  id: Identifier;
+
+  /** Scorer name, for example "redundant-tests". */
+  @minLength(1)
+  name: string;
+
+  /** A number for NUMERIC, 0 or 1 for BOOLEAN, a string for CATEGORICAL. */
+  value: float64 | string;
+
+  dataType: ScoreDataType;
+
+  /** Trace of the run (the OTel trace ID). */
+  traceId: TraceId;
+
+  /** Span the score is about, when it is not the whole run. */
+  observationId?: string;
+
+  sessionId?: string;
+
+  /** The reason. */
+  comment?: string;
+
+  timestamp: utcDateTime;
+
+  /** API for scorers, ANNOTATION for scores a person reviews. */
+  source?: ScoreSource;
+
+  configId?: string;
+  environment?: string;
+  metadata: ScoreMetadata;
+}
+
+enum ScoreDataType {
+  NUMERIC,
+  BOOLEAN,
+  CATEGORICAL,
+}
+
+enum ScoreSource {
+  API,
+  ANNOTATION,
+}
+
+model ScoreMetadata {
+  `osf.run.id`: Identifier;
+  `osf.scorer.version`?: string;
+
+  /** Judge model of an LLM scorer. */
+  `osf.judge.model`?: string;
+
+  /** Cost of the judge call. */
+  @minValue(0)
+  `osf.judge.cost.usd`?: float64;
+
+  ...Record<unknown>;
+}

package/typespec/work-item.tsp

@@ -0,0 +1,65 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+// Wire formats (work item, run record, evidence manifest, score, events) are open: consumers ignore fields they
+// do not know, so producers can add optional fields in a minor version.
+
+/** One unit of requested work: the `data` of a `work.received@v1` CloudEvent. */
+model WorkItem {
+  id: Identifier;
+  type: WorkItemType;
+
+  @minLength(1)
+  @maxLength(300)
+  title: string;
+
+  description?: string;
+
+  /** The person or trigger that asked for the work. */
+  requester: Actor;
+
+  /** Where the work came from. */
+  origin: Origin;
+
+  /** Requests with the same key become one work item, for example "github:acme/web#42". */
+  @minLength(1)
+  dedupeKey: string;
+
+  /** Product surface the work is about, for example "checkout". */
+  surface?: string;
+
+  /** Set by triage. */
+  priority?: Priority;
+
+  /** Related material: an error report, a change, a document. */
+  links?: Link[];
+}
+
+enum WorkItemType {
+  idea,
+  bug,
+  task,
+  automation,
+}
+
+enum Priority {
+  urgent,
+  high,
+  normal,
+  low,
+}
+
+model Origin {
+  /** The channel or system, for example "slack", "github", "sentry", "cron", "mcp". */
+  source: Name;
+
+  /** Link back to the origin, for example the Slack thread. Absent for a schedule. */
+  url?: url;
+
+  /** ID in the source system. */
+  externalId?: string;
+}

package/work-item/work-item.schema.json

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/work-item/work-item.schema.json",
+  "title": "WorkItem",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+    },
+    "type": {
+      "type": "string",
+      "enum": [
+        "idea",
+        "bug",
+        "task",
+        "automation"
+      ]
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 300
+    },
+    "description": {
+      "type": "string"
+    },
+    "requester": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "person",
+            "trigger"
+          ],
+          "description": "Who caused something: a person, or an automated trigger such as a cron rule or an alert."
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable ID in the source system, prefixed with the source, for example \"slack:U024BE7LH\"."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Shown to people, for example \"Varun\"."
+        }
+      },
+      "required": [
+        "kind",
+        "id"
+      ],
+      "description": "The person or trigger that asked for the work."
+    },
+    "origin": {
+      "type": "object",
+      "properties": {
+        "source": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "The channel or system, for example \"slack\", \"github\", \"sentry\", \"cron\", \"mcp\"."
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Link back to the origin, for example the Slack thread. Absent for a schedule."
+        },
+        "externalId": {
+          "type": "string",
+          "description": "ID in the source system."
+        }
+      },
+      "required": [
+        "source"
+      ],
+      "description": "Where the work came from."
+    },
+    "dedupeKey": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Requests with the same key become one work item, for example \"github:acme/web#42\"."
+    },
+    "surface": {
+      "type": "string",
+      "description": "Product surface the work is about, for example \"checkout\"."
+    },
+    "priority": {
+      "type": "string",
+      "enum": [
+        "urgent",
+        "high",
+        "normal",
+        "low"
+      ],
+      "description": "Set by triage."
+    },
+    "links": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "title": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "description": "Related material: an error report, a change, a document."
+    }
+  },
+  "required": [
+    "id",
+    "type",
+    "title",
+    "requester",
+    "origin",
+    "dedupeKey"
+  ],
+  "description": "One unit of requested work: the `data` of a `work.received@v1` CloudEvent."
+}