@cat-factory/contracts 0.161.0 → 0.163.0

package/dist/public-api-keys.d.ts

@@ -3,17 +3,34 @@ import * as v from 'valibot';
  * The permission a key carries on the `/api/v1` surface. An ordered ladder — each level
  * INCLUDES the ones below it (`admin` ⊃ `write` ⊃ `read`), so an endpoint gates on a MINIMUM:
  *
- *  - `read`  — read-only reads/streams (list services/tasks/pipelines, poll a run, SSE).
- *  - `write` — everything `read` can do, PLUS non-destructive mutations (create/start/stop/
+ *  - `read`   — read-only reads/streams (list services/tasks/pipelines, poll a run, SSE).
+ *  - `write`  — everything `read` can do, PLUS non-destructive mutations (create/start/stop/
  *    retry/edit a task, start an initiative run).
- *  - `admin` — everything `write` can do, PLUS destructive / merge-adjacent operations
- *    (delete a task; future: resolve a merge-review notification, which performs a real merge).
+ *  - `decide` — everything `write` can do, PLUS answering a run's PARKED human decisions
+ *    (requirement-review findings, implementation-fork choices) — and, because of that,
+ *    starting a headless run on a pipeline that can park at all. Answering a decision injects
+ *    caller-supplied prose into the requirements every downstream agent then implements and
+ *    un-parks the run, so it is deliberately a rung above ordinary task authoring: a plain
+ *    `write` integration sees exactly the pre-existing behaviour, including the refusal of
+ *    parking pipelines. Minting a `decide` key is the operator asserting "this integration is
+ *    the headless overseer for these runs".
+ *
+ *    **The grant is WORKSPACE-WIDE, not limited to runs the key started.** The decision surface
+ *    is keyed by run id and resolves any run in the key's workspace — including a board task a
+ *    human started in the SPA — because a headless overseer that could only answer its own runs
+ *    would be useless for the case it exists for (an integration watching a team's board). That
+ *    is the same reach a `write` key already has over board runs (start/stop/retry), one rung
+ *    up. Scope a key to a workspace accordingly, and prefer `write` for an integration that
+ *    only needs to author and launch.
+ *  - `admin`  — everything `decide` can do, PLUS destructive / merge-adjacent operations
+ *    (delete a task, act on a notification — which can perform a real merge).
  *
  * The canonical rank order lives beside this schema (`PUBLIC_API_SCOPES`) so both the wire
- * validation and the server-side `scope ≥ required` check read from one source of truth.
+ * validation and the server-side `scope ≥ required` check read from one source of truth —
+ * the ARRAY ORDER *is* the ladder, and `scopeSatisfies` derives its ranks from it.
  */
-export declare const PUBLIC_API_SCOPES: readonly ['read', 'write', 'admin'];
-export declare const publicApiScopeSchema: v.PicklistSchema<readonly ["read", "write", "admin"], undefined>;
+export declare const PUBLIC_API_SCOPES: readonly ['read', 'write', 'decide', 'admin'];
+export declare const publicApiScopeSchema: v.PicklistSchema<readonly ["read", "write", "decide", "admin"], undefined>;
 export type PublicApiScope = v.InferOutput<typeof publicApiScopeSchema>;
 /** One public-API key as exposed to clients — metadata only, never the secret. */
 export declare const publicApiKeySchema: v.ObjectSchema<{
@@ -23,7 +40,7 @@ export declare const publicApiKeySchema: v.ObjectSchema<{
     readonly workspaceId: v.StringSchema<undefined>;
     readonly label: v.StringSchema<undefined>;
     /** What the key is allowed to do on `/api/v1` (read ⊂ write ⊂ admin). */
-    readonly scope: v.PicklistSchema<readonly ["read", "write", "admin"], undefined>;
+    readonly scope: v.PicklistSchema<readonly ["read", "write", "decide", "admin"], undefined>;
     /** The user who minted the key (`usr_*`), for audit/UI attribution; `null` when unknown. */
     readonly createdByUserId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly createdAt: v.NumberSchema<undefined>;
@@ -40,7 +57,7 @@ export declare const publicApiKeyListResultSchema: v.ObjectSchema<{
         readonly workspaceId: v.StringSchema<undefined>;
         readonly label: v.StringSchema<undefined>;
         /** What the key is allowed to do on `/api/v1` (read ⊂ write ⊂ admin). */
-        readonly scope: v.PicklistSchema<readonly ["read", "write", "admin"], undefined>;
+        readonly scope: v.PicklistSchema<readonly ["read", "write", "decide", "admin"], undefined>;
         /** The user who minted the key (`usr_*`), for audit/UI attribution; `null` when unknown. */
         readonly createdByUserId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly createdAt: v.NumberSchema<undefined>;
@@ -53,12 +70,13 @@ export type PublicApiKeyListResult = v.InferOutput<typeof publicApiKeyListResult
 /**
  * Mint a new key. A label plus an optional `scope` (the account/workspace scope comes from the
  * mounting route). `scope` defaults to `write` — the safe middle of the ladder: a fresh key can
- * create/start/manage tasks but NOT delete or perform a merge-adjacent action until it is minted
- * `admin` explicitly. Pass `read` for a monitor-only integration.
+ * create/start/manage tasks but NOT answer a parked run's decisions, delete, or perform a
+ * merge-adjacent action until it is minted `decide` / `admin` explicitly. Pass `read` for a
+ * monitor-only integration.
  */
 export declare const createPublicApiKeySchema: v.ObjectSchema<{
     readonly label: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 120, undefined>]>;
-    readonly scope: v.OptionalSchema<v.PicklistSchema<readonly ["read", "write", "admin"], undefined>, "write">;
+    readonly scope: v.OptionalSchema<v.PicklistSchema<readonly ["read", "write", "decide", "admin"], undefined>, "write">;
 }, undefined>;
 export type CreatePublicApiKeyInput = v.InferOutput<typeof createPublicApiKeySchema>;
 /**
@@ -73,7 +91,7 @@ export declare const createdPublicApiKeySchema: v.ObjectSchema<{
         readonly workspaceId: v.StringSchema<undefined>;
         readonly label: v.StringSchema<undefined>;
         /** What the key is allowed to do on `/api/v1` (read ⊂ write ⊂ admin). */
-        readonly scope: v.PicklistSchema<readonly ["read", "write", "admin"], undefined>;
+        readonly scope: v.PicklistSchema<readonly ["read", "write", "decide", "admin"], undefined>;
         /** The user who minted the key (`usr_*`), for audit/UI attribution; `null` when unknown. */
         readonly createdByUserId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly createdAt: v.NumberSchema<undefined>;

package/dist/public-api-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-api-keys.d.ts","sourceRoot":"","sources":["../src/public-api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAiB5B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,YAAI,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA;AACpE,eAAO,MAAM,oBAAoB,kEAAgC,CAAA;AACjE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,kFAAkF;AAClF,eAAO,MAAM,kBAAkB;IAC7B,uEAAuE;;;;;IAKvE,yEAAyE;;IAEzE,4FAA4F;;;;IAI5F,mFAAmF;;aAEnF,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE,eAAO,MAAM,4BAA4B;;QAhBvC,uEAAuE;;;;;QAKvE,yEAAyE;;QAEzE,4FAA4F;;;;QAI5F,mFAAmF;;;aAKM,CAAA;AAC3F,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;aAGnC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEpF;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;QAnCpC,uEAAuE;;;;;QAKvE,yEAAyE;;QAEzE,4FAA4F;;;;QAI5F,mFAAmF;;;IA0BnF,sEAAsE;;aAEtE,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA"}
+{"version":3,"file":"public-api-keys.d.ts","sourceRoot":"","sources":["../src/public-api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAiB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,iBAAiB,YAAI,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAA;AAC9E,eAAO,MAAM,oBAAoB,4EAAgC,CAAA;AACjE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,kFAAkF;AAClF,eAAO,MAAM,kBAAkB;IAC7B,uEAAuE;;;;;IAKvE,yEAAyE;;IAEzE,4FAA4F;;;;IAI5F,mFAAmF;;aAEnF,CAAA;AACF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE,eAAO,MAAM,4BAA4B;;QAhBvC,uEAAuE;;;;;QAKvE,yEAAyE;;QAEzE,4FAA4F;;;;QAI5F,mFAAmF;;;aAKM,CAAA;AAC3F,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,4BAA4B,CAAC,CAAA;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;aAGnC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEpF;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;QApCpC,uEAAuE;;;;;QAKvE,yEAAyE;;QAEzE,4FAA4F;;;;QAI5F,mFAAmF;;;IA2BnF,sEAAsE;;aAEtE,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,yBAAyB,CAAC,CAAA"}

package/dist/public-api-keys.js

@@ -17,16 +17,33 @@ import * as v from 'valibot';
  * The permission a key carries on the `/api/v1` surface. An ordered ladder — each level
  * INCLUDES the ones below it (`admin` ⊃ `write` ⊃ `read`), so an endpoint gates on a MINIMUM:
  *
- *  - `read`  — read-only reads/streams (list services/tasks/pipelines, poll a run, SSE).
- *  - `write` — everything `read` can do, PLUS non-destructive mutations (create/start/stop/
+ *  - `read`   — read-only reads/streams (list services/tasks/pipelines, poll a run, SSE).
+ *  - `write`  — everything `read` can do, PLUS non-destructive mutations (create/start/stop/
  *    retry/edit a task, start an initiative run).
- *  - `admin` — everything `write` can do, PLUS destructive / merge-adjacent operations
- *    (delete a task; future: resolve a merge-review notification, which performs a real merge).
+ *  - `decide` — everything `write` can do, PLUS answering a run's PARKED human decisions
+ *    (requirement-review findings, implementation-fork choices) — and, because of that,
+ *    starting a headless run on a pipeline that can park at all. Answering a decision injects
+ *    caller-supplied prose into the requirements every downstream agent then implements and
+ *    un-parks the run, so it is deliberately a rung above ordinary task authoring: a plain
+ *    `write` integration sees exactly the pre-existing behaviour, including the refusal of
+ *    parking pipelines. Minting a `decide` key is the operator asserting "this integration is
+ *    the headless overseer for these runs".
+ *
+ *    **The grant is WORKSPACE-WIDE, not limited to runs the key started.** The decision surface
+ *    is keyed by run id and resolves any run in the key's workspace — including a board task a
+ *    human started in the SPA — because a headless overseer that could only answer its own runs
+ *    would be useless for the case it exists for (an integration watching a team's board). That
+ *    is the same reach a `write` key already has over board runs (start/stop/retry), one rung
+ *    up. Scope a key to a workspace accordingly, and prefer `write` for an integration that
+ *    only needs to author and launch.
+ *  - `admin`  — everything `decide` can do, PLUS destructive / merge-adjacent operations
+ *    (delete a task, act on a notification — which can perform a real merge).
  *
  * The canonical rank order lives beside this schema (`PUBLIC_API_SCOPES`) so both the wire
- * validation and the server-side `scope ≥ required` check read from one source of truth.
+ * validation and the server-side `scope ≥ required` check read from one source of truth —
+ * the ARRAY ORDER *is* the ladder, and `scopeSatisfies` derives its ranks from it.
  */
-export const PUBLIC_API_SCOPES = ['read', 'write', 'admin'];
+export const PUBLIC_API_SCOPES = ['read', 'write', 'decide', 'admin'];
 export const publicApiScopeSchema = v.picklist(PUBLIC_API_SCOPES);
 /** One public-API key as exposed to clients — metadata only, never the secret. */
 export const publicApiKeySchema = v.object({
@@ -48,8 +65,9 @@ export const publicApiKeyListResultSchema = v.object({ keys: v.array(publicApiKe
 /**
  * Mint a new key. A label plus an optional `scope` (the account/workspace scope comes from the
  * mounting route). `scope` defaults to `write` — the safe middle of the ladder: a fresh key can
- * create/start/manage tasks but NOT delete or perform a merge-adjacent action until it is minted
- * `admin` explicitly. Pass `read` for a monitor-only integration.
+ * create/start/manage tasks but NOT answer a parked run's decisions, delete, or perform a
+ * merge-adjacent action until it is minted `decide` / `admin` explicitly. Pass `read` for a
+ * monitor-only integration.
  */
 export const createPublicApiKeySchema = v.object({
     label: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(120)),

package/dist/public-api-keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-api-keys.js","sourceRoot":"","sources":["../src/public-api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,yCAAyC;AACzC,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,wEAAwE;AACxE,gFAAgF;AAChF,gEAAgE;AAChE,EAAE;AACF,+EAA+E;AAC/E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAU,CAAA;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAA;AAGjE,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,uEAAuE;IACvE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,yEAAyE;IACzE,KAAK,EAAE,oBAAoB;IAC3B,4FAA4F;IAC5F,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,mFAAmF;IACnF,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAClC,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAA;AAG3F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrE,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACjD,CAAC,CAAA;AAGF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,GAAG,EAAE,kBAAkB;IACvB,sEAAsE;IACtE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAA"}
+{"version":3,"file":"public-api-keys.js","sourceRoot":"","sources":["../src/public-api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B,8EAA8E;AAC9E,yCAAyC;AACzC,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,wEAAwE;AACxE,gFAAgF;AAChF,gEAAgE;AAChE,EAAE;AACF,+EAA+E;AAC/E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAA;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAA;AAGjE,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,uEAAuE;IACvE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,yEAAyE;IACzE,KAAK,EAAE,oBAAoB;IAC3B,4FAA4F;IAC5F,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,mFAAmF;IACnF,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAClC,CAAC,CAAA;AAGF,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC,CAAA;AAG3F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrE,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACjD,CAAC,CAAA;AAGF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,GAAG,EAAE,kBAAkB;IACvB,sEAAsE;IACtE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAA"}

package/dist/public-decisions.d.ts

@@ -0,0 +1,254 @@
+import * as v from 'valibot';
+/** Which parked decision a `publicDecision` entry describes. */
+export declare const publicDecisionKindSchema: v.PicklistSchema<["requirements-review", "fork"], undefined>;
+export type PublicDecisionKind = v.InferOutput<typeof publicDecisionKindSchema>;
+/**
+ * One reviewer finding as exposed externally — the question, how serious it is, and where it
+ * stands. `itemId` is the STABLE anchor a reply addresses (and, in slice 2, the id rendered into
+ * the tracker-issue comment so a ticket reply can target a finding). The internal item's
+ * `autoAnswerable` classification and the Requirement-Writer recommendation machinery are
+ * deliberately not exposed: they drive in-app affordances a headless caller has no use for.
+ */
+export declare const publicReviewFindingSchema: v.ObjectSchema<{
+    readonly itemId: v.StringSchema<undefined>;
+    /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+    readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+    /** How important resolving it is before implementation proceeds. */
+    readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+    /** Short headline of the concern. */
+    readonly title: v.StringSchema<undefined>;
+    /** The full question / gap / challenge, in plain prose. */
+    readonly detail: v.StringSchema<undefined>;
+    /** `open` until answered or dismissed; only `open` findings block incorporation. */
+    readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+    /** The recorded answer, or null while unanswered. */
+    readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicReviewFinding = v.InferOutput<typeof publicReviewFindingSchema>;
+/**
+ * A parked requirements review as exposed externally. The loop a caller drives: answer or dismiss
+ * every `open` finding, then `incorporate` (which folds the answers into one standard-format
+ * document and re-reviews it in the background). The review converges (`incorporated` — the run
+ * advances), comes back with a fresh round (`ready`), or hits its iteration cap (`exceeded`, where
+ * `resolve-exceeded` picks one more round / proceed anyway / stop).
+ */
+export declare const publicRequirementsDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"requirements-review", undefined>;
+    readonly reviewId: v.StringSchema<undefined>;
+    /** The board task the review belongs to. */
+    readonly taskId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    /** Which reviewer pass this is (the initial review is 1). */
+    readonly iteration: v.NumberSchema<undefined>;
+    /** The reviewer-pass budget, from the task's merge preset. */
+    readonly maxIterations: v.NumberSchema<undefined>;
+    readonly findings: v.ArraySchema<v.ObjectSchema<{
+        readonly itemId: v.StringSchema<undefined>;
+        /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        /** How important resolving it is before implementation proceeds. */
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        /** `open` until answered or dismissed; only `open` findings block incorporation. */
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+        /** The recorded answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The standardized requirements document the last incorporation produced; null until one
+     * exists. Once the review settles, this is what every downstream agent implements — so a
+     * caller can read exactly what its answers turned into before proceeding.
+     */
+    readonly incorporatedRequirements: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicRequirementsDecision = v.InferOutput<typeof publicRequirementsDecisionSchema>;
+/**
+ * A parked implementation-fork choice as exposed externally: the materially different ways to
+ * implement the task, surfaced before any code is written. A caller picks a `forkId` or submits
+ * its own `custom` approach; the Coder then runs with the choice folded in as a binding directive.
+ * The grounded chat is deliberately NOT exposed — it is an interactive deliberation affordance,
+ * and a headless caller that wants to reason about the forks has the full `approach`/`tradeoffs`
+ * text right here.
+ */
+export declare const publicForkDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"fork", undefined>;
+    /** The run's fork-decision lifecycle state; only `awaiting_choice` accepts a choice. */
+    readonly status: v.PicklistSchema<["proposing", "awaiting_choice", "answering", "chosen", "single_path", "skipped"], undefined>;
+    /** The proposer's read of where the change lands (grounding for the choice). */
+    readonly seamSummary: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** The proposed approaches, each with its id, plan, trade-offs and risk notes. */
+    readonly forks: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly title: v.StringSchema<undefined>;
+        readonly summary: v.StringSchema<undefined>;
+        readonly approach: v.StringSchema<undefined>;
+        readonly tradeoffs: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        readonly riskNotes: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly recommended: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type PublicForkDecision = v.InferOutput<typeof publicForkDecisionSchema>;
+export declare const publicDecisionSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"requirements-review", undefined>;
+    readonly reviewId: v.StringSchema<undefined>;
+    /** The board task the review belongs to. */
+    readonly taskId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    /** Which reviewer pass this is (the initial review is 1). */
+    readonly iteration: v.NumberSchema<undefined>;
+    /** The reviewer-pass budget, from the task's merge preset. */
+    readonly maxIterations: v.NumberSchema<undefined>;
+    readonly findings: v.ArraySchema<v.ObjectSchema<{
+        readonly itemId: v.StringSchema<undefined>;
+        /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        /** How important resolving it is before implementation proceeds. */
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        /** `open` until answered or dismissed; only `open` findings block incorporation. */
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+        /** The recorded answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The standardized requirements document the last incorporation produced; null until one
+     * exists. Once the review settles, this is what every downstream agent implements — so a
+     * caller can read exactly what its answers turned into before proceeding.
+     */
+    readonly incorporatedRequirements: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"fork", undefined>;
+    /** The run's fork-decision lifecycle state; only `awaiting_choice` accepts a choice. */
+    readonly status: v.PicklistSchema<["proposing", "awaiting_choice", "answering", "chosen", "single_path", "skipped"], undefined>;
+    /** The proposer's read of where the change lands (grounding for the choice). */
+    readonly seamSummary: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** The proposed approaches, each with its id, plan, trade-offs and risk notes. */
+    readonly forks: v.ArraySchema<v.ObjectSchema<{
+        readonly id: v.StringSchema<undefined>;
+        readonly title: v.StringSchema<undefined>;
+        readonly summary: v.StringSchema<undefined>;
+        readonly approach: v.StringSchema<undefined>;
+        readonly tradeoffs: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        readonly riskNotes: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly recommended: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>], undefined>;
+export type PublicDecision = v.InferOutput<typeof publicDecisionSchema>;
+/**
+ * A run's currently-parked decisions. `parked` is the single flag a caller polls or reacts to:
+ * true when the run is `blocked` awaiting one of the decisions listed. An empty list with
+ * `parked: false` is the ordinary case for a run that is simply still working.
+ */
+export declare const publicDecisionListSchema: v.ObjectSchema<{
+    readonly runId: v.StringSchema<undefined>;
+    readonly taskId: v.StringSchema<undefined>;
+    /** The run's raw status — `blocked` is the parked state. */
+    readonly status: v.PicklistSchema<["running", "blocked", "paused", "done", "failed"], undefined>;
+    /** Whether the run is currently parked awaiting a human decision. */
+    readonly parked: v.BooleanSchema<undefined>;
+    readonly decisions: v.ArraySchema<v.VariantSchema<"kind", [v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"requirements-review", undefined>;
+        readonly reviewId: v.StringSchema<undefined>;
+        /** The board task the review belongs to. */
+        readonly taskId: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+        /** Which reviewer pass this is (the initial review is 1). */
+        readonly iteration: v.NumberSchema<undefined>;
+        /** The reviewer-pass budget, from the task's merge preset. */
+        readonly maxIterations: v.NumberSchema<undefined>;
+        readonly findings: v.ArraySchema<v.ObjectSchema<{
+            readonly itemId: v.StringSchema<undefined>;
+            /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+            readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+            /** How important resolving it is before implementation proceeds. */
+            readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+            /** Short headline of the concern. */
+            readonly title: v.StringSchema<undefined>;
+            /** The full question / gap / challenge, in plain prose. */
+            readonly detail: v.StringSchema<undefined>;
+            /** `open` until answered or dismissed; only `open` findings block incorporation. */
+            readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+            /** The recorded answer, or null while unanswered. */
+            readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /**
+         * The standardized requirements document the last incorporation produced; null until one
+         * exists. Once the review settles, this is what every downstream agent implements — so a
+         * caller can read exactly what its answers turned into before proceeding.
+         */
+        readonly incorporatedRequirements: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"fork", undefined>;
+        /** The run's fork-decision lifecycle state; only `awaiting_choice` accepts a choice. */
+        readonly status: v.PicklistSchema<["proposing", "awaiting_choice", "answering", "chosen", "single_path", "skipped"], undefined>;
+        /** The proposer's read of where the change lands (grounding for the choice). */
+        readonly seamSummary: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** The proposed approaches, each with its id, plan, trade-offs and risk notes. */
+        readonly forks: v.ArraySchema<v.ObjectSchema<{
+            readonly id: v.StringSchema<undefined>;
+            readonly title: v.StringSchema<undefined>;
+            readonly summary: v.StringSchema<undefined>;
+            readonly approach: v.StringSchema<undefined>;
+            readonly tradeoffs: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+            readonly riskNotes: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly recommended: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>], undefined>, undefined>;
+}, undefined>;
+export type PublicDecisionList = v.InferOutput<typeof publicDecisionListSchema>;
+/** Answer one reviewer finding. Mirrors the SPA's `replyReviewItemSchema` bounds. */
+export declare const publicReplyFindingSchema: v.ObjectSchema<{
+    readonly reply: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+}, undefined>;
+export type PublicReplyFindingInput = v.InferOutput<typeof publicReplyFindingSchema>;
+/**
+ * Set a finding's status. Deliberately narrower than the SPA's full item-status patch: a headless
+ * caller may `dismiss` a finding as not applicable or `reopen` one it dismissed by mistake.
+ * `answered` is reached by REPLYING (which is what records the answer the incorporation folds in),
+ * and `recommend_requested` drives an in-app-only affordance, so neither is settable here.
+ */
+export declare const publicSetFindingStatusSchema: v.ObjectSchema<{
+    readonly status: v.PicklistSchema<["dismissed", "open"], undefined>;
+}, undefined>;
+export type PublicSetFindingStatusInput = v.InferOutput<typeof publicSetFindingStatusSchema>;
+/**
+ * Incorporate the recorded answers. Optional `feedback` is the "do it differently" lever when
+ * redoing a merge, exactly as in the SPA. Asynchronous: the durable driver folds and re-reviews in
+ * the background, so the response is the `incorporating` review, not the finished document.
+ */
+export declare const publicIncorporateSchema: v.ObjectSchema<{
+    readonly feedback: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
+}, undefined>;
+export type PublicIncorporateInput = v.InferOutput<typeof publicIncorporateSchema>;
+/**
+ * Resolve a review that hit its iteration cap: one more reviewer pass, proceed with the last
+ * incorporated document, or stop and reset the task to an editable state. The same three choices
+ * the SPA offers — there is deliberately no timed default (a parked run waits for an answer
+ * indefinitely, so a silent auto-proceed would ship requirements nobody approved).
+ */
+export declare const publicResolveExceededSchema: v.ObjectSchema<{
+    readonly choice: v.PicklistSchema<["extra-round", "proceed", "stop-reset"], undefined>;
+}, undefined>;
+export type PublicResolveExceededInput = v.InferOutput<typeof publicResolveExceededSchema>;
+/**
+ * Choose an implementation approach: EXACTLY one of a proposed `forkId` or a free-text `custom`
+ * approach, optionally with a steering `note` on a picked fork. Mirrors the SPA's `chooseForkSchema`
+ * (same xor rule and bounds) so both surfaces accept identical input.
+ */
+export declare const publicChooseForkSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
+    readonly forkId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly custom: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 8000, undefined>]>, undefined>, undefined>;
+    readonly note: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>, undefined>;
+}, undefined>, v.CheckAction<{
+    forkId?: string | null | undefined;
+    custom?: string | null | undefined;
+    note?: string | null | undefined;
+}, "Provide exactly one of forkId or custom.">]>;
+export type PublicChooseForkInput = v.InferOutput<typeof publicChooseForkSchema>;
+//# sourceMappingURL=public-decisions.d.ts.map

package/dist/public-decisions.d.ts.map

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

package/dist/public-decisions.js

@@ -0,0 +1,150 @@
+import * as v from 'valibot';
+import { forkDecisionStatusSchema, forkOptionSchema } from './forkDecision.js';
+import { publicRunStatusSchema } from './public-api.js';
+import { requirementReviewStatusSchema, reviewItemCategorySchema, reviewItemSeveritySchema, reviewItemStatusSchema, } from './requirements.js';
+// ---------------------------------------------------------------------------
+// Public-API wire contracts for a run's PARKED HUMAN DECISIONS (`/api/v1/runs/:runId/decisions`).
+//
+// The requirements-review loop is the platform's clarification machinery: the reviewer raises
+// findings, the run parks on a durable decision-wait, a human answers/dismisses, an incorporation
+// pass folds the answers in, and the run advances. Until now that loop was reachable only through
+// the SPA, so a headless (`/api/v1`) run could not include clarification at all — the public
+// surface refused any pipeline that could park.
+//
+// These resources are the external counterpart of that loop. Two decision kinds are exposed today:
+// the requirements review (findings + the iteration loop) and the implementation-fork choice. Both
+// are deliberately SMALL projections of the internal entities, following the `publicTask` /
+// `publicService` pattern: a caller sees the findings and their stable ids, never the engine's
+// step/approval internals, the recommendation machinery, or the reviewer's model plumbing.
+//
+// Answering rides the SAME service methods the SPA controllers call, so the park's CAS/approval-id
+// arbitration and the task's merge-preset knobs (iteration cap, tolerated severity) apply
+// identically whichever surface answers first. See
+// `docs/initiatives/headless-clarification-loop.md`.
+// ---------------------------------------------------------------------------
+/** Which parked decision a `publicDecision` entry describes. */
+export const publicDecisionKindSchema = v.picklist(['requirements-review', 'fork']);
+/**
+ * One reviewer finding as exposed externally — the question, how serious it is, and where it
+ * stands. `itemId` is the STABLE anchor a reply addresses (and, in slice 2, the id rendered into
+ * the tracker-issue comment so a ticket reply can target a finding). The internal item's
+ * `autoAnswerable` classification and the Requirement-Writer recommendation machinery are
+ * deliberately not exposed: they drive in-app affordances a headless caller has no use for.
+ */
+export const publicReviewFindingSchema = v.object({
+    itemId: v.string(),
+    /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+    category: reviewItemCategorySchema,
+    /** How important resolving it is before implementation proceeds. */
+    severity: reviewItemSeveritySchema,
+    /** Short headline of the concern. */
+    title: v.string(),
+    /** The full question / gap / challenge, in plain prose. */
+    detail: v.string(),
+    /** `open` until answered or dismissed; only `open` findings block incorporation. */
+    status: reviewItemStatusSchema,
+    /** The recorded answer, or null while unanswered. */
+    reply: v.nullable(v.string()),
+});
+/**
+ * A parked requirements review as exposed externally. The loop a caller drives: answer or dismiss
+ * every `open` finding, then `incorporate` (which folds the answers into one standard-format
+ * document and re-reviews it in the background). The review converges (`incorporated` — the run
+ * advances), comes back with a fresh round (`ready`), or hits its iteration cap (`exceeded`, where
+ * `resolve-exceeded` picks one more round / proceed anyway / stop).
+ */
+export const publicRequirementsDecisionSchema = v.object({
+    kind: v.literal('requirements-review'),
+    reviewId: v.string(),
+    /** The board task the review belongs to. */
+    taskId: v.string(),
+    status: requirementReviewStatusSchema,
+    /** Which reviewer pass this is (the initial review is 1). */
+    iteration: v.number(),
+    /** The reviewer-pass budget, from the task's merge preset. */
+    maxIterations: v.number(),
+    findings: v.array(publicReviewFindingSchema),
+    /**
+     * The standardized requirements document the last incorporation produced; null until one
+     * exists. Once the review settles, this is what every downstream agent implements — so a
+     * caller can read exactly what its answers turned into before proceeding.
+     */
+    incorporatedRequirements: v.nullable(v.string()),
+});
+/**
+ * A parked implementation-fork choice as exposed externally: the materially different ways to
+ * implement the task, surfaced before any code is written. A caller picks a `forkId` or submits
+ * its own `custom` approach; the Coder then runs with the choice folded in as a binding directive.
+ * The grounded chat is deliberately NOT exposed — it is an interactive deliberation affordance,
+ * and a headless caller that wants to reason about the forks has the full `approach`/`tradeoffs`
+ * text right here.
+ */
+export const publicForkDecisionSchema = v.object({
+    kind: v.literal('fork'),
+    /** The run's fork-decision lifecycle state; only `awaiting_choice` accepts a choice. */
+    status: forkDecisionStatusSchema,
+    /** The proposer's read of where the change lands (grounding for the choice). */
+    seamSummary: v.nullable(v.string()),
+    /** The proposed approaches, each with its id, plan, trade-offs and risk notes. */
+    forks: v.array(forkOptionSchema),
+});
+export const publicDecisionSchema = v.variant('kind', [
+    publicRequirementsDecisionSchema,
+    publicForkDecisionSchema,
+]);
+/**
+ * A run's currently-parked decisions. `parked` is the single flag a caller polls or reacts to:
+ * true when the run is `blocked` awaiting one of the decisions listed. An empty list with
+ * `parked: false` is the ordinary case for a run that is simply still working.
+ */
+export const publicDecisionListSchema = v.object({
+    runId: v.string(),
+    taskId: v.string(),
+    /** The run's raw status — `blocked` is the parked state. */
+    status: publicRunStatusSchema,
+    /** Whether the run is currently parked awaiting a human decision. */
+    parked: v.boolean(),
+    decisions: v.array(publicDecisionSchema),
+});
+// ---- Request bodies -------------------------------------------------------
+/** Answer one reviewer finding. Mirrors the SPA's `replyReviewItemSchema` bounds. */
+export const publicReplyFindingSchema = v.object({
+    reply: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(4000)),
+});
+/**
+ * Set a finding's status. Deliberately narrower than the SPA's full item-status patch: a headless
+ * caller may `dismiss` a finding as not applicable or `reopen` one it dismissed by mistake.
+ * `answered` is reached by REPLYING (which is what records the answer the incorporation folds in),
+ * and `recommend_requested` drives an in-app-only affordance, so neither is settable here.
+ */
+export const publicSetFindingStatusSchema = v.object({
+    status: v.picklist(['dismissed', 'open']),
+});
+/**
+ * Incorporate the recorded answers. Optional `feedback` is the "do it differently" lever when
+ * redoing a merge, exactly as in the SPA. Asynchronous: the durable driver folds and re-reviews in
+ * the background, so the response is the `incorporating` review, not the finished document.
+ */
+export const publicIncorporateSchema = v.object({
+    feedback: v.optional(v.pipe(v.string(), v.trim(), v.maxLength(4000))),
+});
+/**
+ * Resolve a review that hit its iteration cap: one more reviewer pass, proceed with the last
+ * incorporated document, or stop and reset the task to an editable state. The same three choices
+ * the SPA offers — there is deliberately no timed default (a parked run waits for an answer
+ * indefinitely, so a silent auto-proceed would ship requirements nobody approved).
+ */
+export const publicResolveExceededSchema = v.object({
+    choice: v.picklist(['extra-round', 'proceed', 'stop-reset']),
+});
+/**
+ * Choose an implementation approach: EXACTLY one of a proposed `forkId` or a free-text `custom`
+ * approach, optionally with a steering `note` on a picked fork. Mirrors the SPA's `chooseForkSchema`
+ * (same xor rule and bounds) so both surfaces accept identical input.
+ */
+export const publicChooseForkSchema = v.pipe(v.object({
+    forkId: v.optional(v.nullable(v.string())),
+    custom: v.optional(v.nullable(v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(8000)))),
+    note: v.optional(v.nullable(v.pipe(v.string(), v.trim(), v.maxLength(4000)))),
+}), v.check((c) => (c.forkId != null && c.forkId.length > 0) !== (c.custom != null && c.custom.length > 0), 'Provide exactly one of forkId or custom.'));
+//# sourceMappingURL=public-decisions.js.map

package/dist/public-decisions.js.map

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

package/dist/routes/agent-runs.d.ts

@@ -853,6 +853,7 @@ export declare const retryAgentRunContract: {
                     readonly serviceUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 }, undefined>, undefined>, undefined>;
                 readonly initiatedBy: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                readonly intakeOrigin: v.OptionalSchema<v.PicklistSchema<["ui", "public-api"], undefined>, undefined>;
                 readonly createdAt: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
                 readonly rev: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
                 readonly diagnostics: v.OptionalSchema<v.ObjectSchema<{
@@ -1773,6 +1774,7 @@ export declare const stopAgentRunContract: {
                     readonly serviceUrl: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 }, undefined>, undefined>, undefined>;
                 readonly initiatedBy: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+                readonly intakeOrigin: v.OptionalSchema<v.PicklistSchema<["ui", "public-api"], 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/routes/agent-runs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-runs.d.ts","sourceRoot":"","sources":["../../src/routes/agent-runs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAqB,MAAM,yBAAyB,CAAA;AAC3E,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAsB5B,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMhC,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM/B,CAAA"}
+{"version":3,"file":"agent-runs.d.ts","sourceRoot":"","sources":["../../src/routes/agent-runs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAqB,MAAM,yBAAyB,CAAA;AAC3E,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAsB5B,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMhC,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM/B,CAAA"}