@cat-factory/contracts 0.232.0 → 0.233.0

package/dist/run-provenance.js

@@ -0,0 +1,140 @@
+import * as v from 'valibot';
+// A run's PROVENANCE: how it entered the system, whether it may land its work, and where it
+// actually executed. Three small vocabularies that answer questions about the run rather than
+// about the work, all of them riding the run's `detail` JSON rather than a column, and all read
+// by policy (admission, the merge decision, the clarification writeback) or by an investigator
+// after the fact. Split out of `execution.ts`, which describes the STEPS.
+/**
+ * How a run entered the system. See `ExecutionInstance.intakeOrigin`.
+ *
+ * - `ui`: someone started it in the app, on their own board. The read-time default, and what
+ *   every legacy run is.
+ * - `public-api`: started headlessly through the `/api/v1` surface.
+ * - `tracker`: dispatched from a pushed ticket by a per-ticket issue-intake schedule.
+ * - `schedule`: a recurring schedule fired it, either on its cadence or because a tracker push
+ *   drained its queue early. Both are the same run against the same reused block (ADR 0032), so
+ *   they deliberately share one origin; what differs is only what made the tick happen.
+ *
+ * `ui` is the DEFAULT, which makes it a positive claim that a human is watching in the app, not
+ * a catch-all for "nothing said". Every UNATTENDED start path names itself, so a path that
+ * states nothing is the app: the one caller allowed to rely on the default. That rule exists
+ * because the opposite reading is silent, and it already cost one bug (a webhook-dispatched run
+ * defaulted into `ui` and its parked review's questions never reached the requester's ticket).
+ */
+export const intakeOriginSchema = v.picklist(['ui', 'public-api', 'tracker', 'schedule']);
+/**
+ * Whether an intake origin means the run's questions have to be pushed back OUT to where it came
+ * from, because there is no human overseer in the app to answer them (the parked requirements
+ * review's questions, above all).
+ *
+ * A `Record` rather than a `!== 'ui'` test on purpose: this is the classification the whole
+ * clarification writeback keys off, and a new intake surface must state which side of it falls
+ * on rather than inheriting an answer by being new. Adding a member to the picklist above fails
+ * to compile until it is answered here.
+ *
+ * `schedule` is the entry worth explaining, because "unattended" would predict `true` and the
+ * answer is `false`. A cadence fire runs against the schedule's REUSED block, and in queue mode
+ * `BugIntakeService` REPLACE-links each pick onto it: the block's linked ticket is dropped and
+ * re-pointed on the next fire, by design, so the block never accumulates stale context. Posting
+ * questions there would open a conversation on a channel that closes underneath it, since a
+ * reply arriving after the link moved resolves to no block and is dropped. What the writeback
+ * needs is not "was anyone present" but "is there a STABLE place to hold a conversation", and a
+ * reused block does not have one. Per-ticket dispatch does, which is why it is `true`: one
+ * permanent block per ticket. Giving queue mode the same treatment is a change to the LINKAGE
+ * (a per-run link, or a block per pick), never a flip of this flag.
+ */
+const HEADLESS_INTAKE = {
+    ui: false,
+    'public-api': true,
+    tracker: true,
+    schedule: false,
+};
+/**
+ * Whether a run entered headlessly ({@link HEADLESS_INTAKE}). `undefined` is every legacy run
+ * and degrades to `ui`, the safe reading: no outbound writeback for a run whose intake cannot
+ * be proven headless.
+ *
+ * `=== true` rather than the bare lookup, which the type says is already a `boolean`. The value
+ * reaches here off a run's persisted `detail` JSON, and the picklist is a CLOSED vocabulary whose
+ * members outlive their retirement in stored rows: a run written under a member later dropped
+ * from the type indexes to `undefined` at runtime, and the declared `boolean` would be a lie the
+ * caller reads as "not headless" anyway. Saying so explicitly makes unrecognised and absent one
+ * answer on purpose rather than by luck.
+ */
+export function isHeadlessIntake(origin) {
+    return origin != null && HEADLESS_INTAKE[origin] === true;
+}
+/**
+ * Whether a run may LAND its work. `live` (the default, and every run before this existed) is the
+ * historical behaviour. `dry_run` is the sandboxed mode: the pipeline runs in full and opens its
+ * pull request, so the human sees a real diff on a real branch, but nothing merges: neither the
+ * `merger` step's auto-merge nor the manual merge endpoint.
+ *
+ * The PR is deliberately still opened. The deliverable a non-developer initiator needs to SEE is the diff,
+ * and withholding the push would leave them reading prose about work they cannot inspect; what
+ * makes the mode a sandbox is that the change cannot reach the default branch, not that it stays
+ * invisible.
+ *
+ * Requested per run at start, and FORCED for the roles a task's merge preset lists in
+ * `dryRunRoles`. The two compose one way only: a live request from a sandboxed role is a dry run,
+ * and there is no way to ask out of it, or the setting would be advisory.
+ */
+export const runModeSchema = v.picklist(['live', 'dry_run']);
+/**
+ * Whether a run is sandboxed. A helper rather than `=== 'dry_run'` scattered across the merge path
+ * and the SPA, so every place that must refuse to land work (or must say that a run will never
+ * land any) reads the mode the same way, and so a run persisted before the mode existed
+ * (absent ⇒ `live`) can never be mistaken for one.
+ */
+export function isDryRun(mode) {
+    return mode === 'dry_run';
+}
+/**
+ * Per-run diagnostic context captured for AFTER-THE-FACT investigation of a run (esp. a
+ * failure): the "where/what did this run actually execute on" facts that were previously
+ * spread across the DB (repo↔service↔installation joins), the harness transcript (model), or
+ * lost entirely (which backend a step ran on). Stamped by the engine at dispatch and refined
+ * on the first poll; it reflects the MOST RECENT container-step dispatch (the step most likely
+ * relevant to a failure), not a per-step history. Rides in the run's `detail` JSON (no dedicated
+ * column), like `ExecutionInstance.notes`/`frontendBindings`. Absent on legacy runs and on
+ * runs with no container step (pure inline/gate pipelines). NEVER carries a token or secret.
+ */
+export const runDiagnosticsSchema = v.object({
+    /** Context of the most recent container-step dispatch. */
+    lastDispatch: v.optional(v.object({
+        /** Index of the dispatched step within the pipeline. */
+        stepIndex: v.number(),
+        /** The step's agent kind (`coder`, `merger`, a custom kind, …). */
+        agentKind: v.string(),
+        /** Resolved model ref `provider:model` (e.g. `anthropic:claude-opus-4-8`); null if unresolved. */
+        model: v.optional(v.nullable(v.string())),
+        /**
+         * Which runner backend the step actually ran on, the datum that distinguishes a native
+         * host-process run from a sandboxed container: `local-native` | `local-container` |
+         * `runner-pool` | `cloudflare-container`. Filled on the first poll (the transport reports
+         * it); absent until then or on an older runtime.
+         */
+        executionBackend: v.optional(v.string()),
+        /** The repo the step operated on. */
+        repo: v.optional(v.object({
+            owner: v.string(),
+            name: v.string(),
+            /** The base branch the work branched from. */
+            baseBranch: v.optional(v.string()),
+            /** VCS provider (`github` | `gitlab`), resolved from the run's repo origin. */
+            provider: v.optional(v.string()),
+        })),
+        /** Epoch ms the dispatch was recorded. */
+        at: v.number(),
+    })),
+    /**
+     * The control-plane (orchestrator) host running the engine, NOT necessarily where the agent
+     * ran (a container step runs elsewhere; see `lastDispatch.executionBackend`). `platform` is the
+     * orchestrator's `process.platform` (e.g. `win32` pins a Windows local deployment, the class
+     * of host that surfaced the native-Windows git-auth break). Best-effort.
+     */
+    host: v.optional(v.object({
+        platform: v.optional(v.string()),
+    })),
+});
+//# sourceMappingURL=run-provenance.js.map

package/dist/run-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-provenance.js","sourceRoot":"","sources":["../src/run-provenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,4FAA4F;AAC5F,8FAA8F;AAC9F,gGAAgG;AAChG,+FAA+F;AAC/F,0EAA0E;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAA;AAGzF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,eAAe,GAAkC;IACrD,EAAE,EAAE,KAAK;IACT,YAAY,EAAE,IAAI;IAClB,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,KAAK;CAChB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAgC;IAC/D,OAAO,MAAM,IAAI,IAAI,IAAI,eAAe,CAAC,MAAM,CAAC,KAAK,IAAI,CAAA;AAC3D,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;AAG5D;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgC;IACvD,OAAO,IAAI,KAAK,SAAS,CAAA;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,0DAA0D;IAC1D,YAAY,EAAE,CAAC,CAAC,QAAQ,CACtB,CAAC,CAAC,MAAM,CAAC;QACP,wDAAwD;QACxD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,mEAAmE;QACnE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;QACrB,kGAAkG;QAClG,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACzC;;;;;WAKG;QACH,gBAAgB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QACxC,qCAAqC;QACrC,IAAI,EAAE,CAAC,CAAC,QAAQ,CACd,CAAC,CAAC,MAAM,CAAC;YACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;YACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;YAChB,8CAA8C;YAC9C,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAClC,+EAA+E;YAC/E,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjC,CAAC,CACH;QACD,0CAA0C;QAC1C,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;KACf,CAAC,CACH;IACD;;;;;OAKG;IACH,IAAI,EAAE,CAAC,CAAC,QAAQ,CACd,CAAC,CAAC,MAAM,CAAC;QACP,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;KACjC,CAAC,CACH;CACF,CAAC,CAAA"}

package/dist/snapshot.d.ts

@@ -1456,7 +1456,7 @@ export declare const workspaceSnapshotSchema: v.ObjectSchema<{
         readonly initiatedBy: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         readonly initiatedByRole: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<readonly ["admin", "member", "viewer"], undefined>, undefined>, undefined>;
         readonly mode: v.OptionalSchema<v.PicklistSchema<["live", "dry_run"], undefined>, undefined>;
-        readonly intakeOrigin: v.OptionalSchema<v.PicklistSchema<["ui", "public-api"], undefined>, undefined>;
+        readonly intakeOrigin: v.OptionalSchema<v.PicklistSchema<["ui", "public-api", "tracker", "schedule"], undefined>, undefined>;
         readonly createdAt: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         readonly rev: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         readonly diagnostics: v.OptionalSchema<v.ObjectSchema<{

package/dist/tracker.d.ts

@@ -25,9 +25,10 @@ export declare const trackerSettingsSchema: v.ObjectSchema<{
      * issue(s), so the loop is answerable from where the work was requested. Per-task
      * overridable via `Block.trackerQuestionsOnPark`. Default off.
      *
-     * Deliberately scoped to runs whose `ExecutionInstance.intakeOrigin` is `public-api`:
-     * a task started in the SPA has a human overseer in the app and its clarification
-     * surface is unchanged (see `docs/initiatives/headless-clarification-loop.md`).
+     * Deliberately scoped to runs whose `ExecutionInstance.intakeOrigin` is HEADLESS
+     * (`isHeadlessIntake`: a `/api/v1` start or a per-ticket tracker dispatch): a task started
+     * in the SPA has a human overseer in the app and its clarification surface is unchanged
+     * (see `docs/initiatives/headless-clarification-loop.md`).
      */
     readonly writebackQuestionsOnPark: v.BooleanSchema<undefined>;
     readonly updatedAt: v.NumberSchema<undefined>;

package/dist/tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAY5B,eAAO,MAAM,iBAAiB,2DAA2C,CAAA;AACzE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE,oFAAoF;AACpF,eAAO,MAAM,qBAAqB;;IAEhC,mFAAmF;;IAEnF,uEAAuE;;IAEvE;;;OAGG;;IAEH;;;;OAIG;;IAEH;;;;;;;;;OASG;;;aAGH,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,iDAAiD;AACjD,eAAO,MAAM,wBAAwB;;;;;;;aAOnC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA"}
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAY5B,eAAO,MAAM,iBAAiB,2DAA2C,CAAA;AACzE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE,oFAAoF;AACpF,eAAO,MAAM,qBAAqB;;IAEhC,mFAAmF;;IAEnF,uEAAuE;;IAEvE;;;OAGG;;IAEH;;;;OAIG;;IAEH;;;;;;;;;;OAUG;;;aAGH,CAAA;AACF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE,iDAAiD;AACjD,eAAO,MAAM,wBAAwB;;;;;;;aAOnC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA"}

package/dist/tracker.js

@@ -33,9 +33,10 @@ export const trackerSettingsSchema = v.object({
      * issue(s), so the loop is answerable from where the work was requested. Per-task
      * overridable via `Block.trackerQuestionsOnPark`. Default off.
      *
-     * Deliberately scoped to runs whose `ExecutionInstance.intakeOrigin` is `public-api`:
-     * a task started in the SPA has a human overseer in the app and its clarification
-     * surface is unchanged (see `docs/initiatives/headless-clarification-loop.md`).
+     * Deliberately scoped to runs whose `ExecutionInstance.intakeOrigin` is HEADLESS
+     * (`isHeadlessIntake`: a `/api/v1` start or a per-ticket tracker dispatch): a task started
+     * in the SPA has a human overseer in the app and its clarification surface is unchanged
+     * (see `docs/initiatives/headless-clarification-loop.md`).
      */
     writebackQuestionsOnPark: v.boolean(),
     updatedAt: v.number(),

package/dist/tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,yEAAyE;AACzE,kFAAkF;AAClF,0EAA0E;AAC1E,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;AAGzE,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACtC,mFAAmF;IACnF,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACtC,uEAAuE;IACvE,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,wBAAwB,EAAE,CAAC,CAAC,OAAO,EAAE;IACrC;;;;OAIG;IACH,uBAAuB,EAAE,CAAC,CAAC,OAAO,EAAE;IACpC;;;;;;;;;OASG;IACH,wBAAwB,EAAE,CAAC,CAAC,OAAO,EAAE;IACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF,iDAAiD;AACjD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACtC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACpE,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClE,wBAAwB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjD,uBAAuB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAChD,wBAAwB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;CAClD,CAAC,CAAA"}
+{"version":3,"file":"tracker.js","sourceRoot":"","sources":["../src/tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,yEAAyE;AACzE,kFAAkF;AAClF,0EAA0E;AAC1E,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;AAGzE,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACtC,mFAAmF;IACnF,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACtC,uEAAuE;IACvE,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,wBAAwB,EAAE,CAAC,CAAC,OAAO,EAAE;IACrC;;;;OAIG;IACH,uBAAuB,EAAE,CAAC,CAAC,OAAO,EAAE;IACpC;;;;;;;;;;OAUG;IACH,wBAAwB,EAAE,CAAC,CAAC,OAAO,EAAE;IACrC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAGF,iDAAiD;AACjD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC;IACtC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACpE,YAAY,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAClE,wBAAwB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACjD,uBAAuB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAChD,wBAAwB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;CAClD,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/contracts",
-  "version": "0.232.0",
+  "version": "0.233.0",
   "description": "Valibot wire contract shared between the Agent Architecture Board frontend and backend.",
   "repository": {
     "type": "git",