@cat-factory/contracts 0.349.0 → 0.351.0

package/dist/agent-gating.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-gating.d.ts","sourceRoot":"","sources":["../src/agent-gating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAuChD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CA+DpD,CAAA;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAGvD,CAAA;AAEF,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAEtE"}
+{"version":3,"file":"agent-gating.d.ts","sourceRoot":"","sources":["../src/agent-gating.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAuChD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,WAAW,CAAC,MAAM,CA0EpD,CAAA;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAEtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,MAAM,CAGvD,CAAA;AAEF,yEAAyE;AACzE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAEtE"}

package/dist/agent-gating.js

@@ -78,6 +78,17 @@ export const BUILTIN_GATABLE_KINDS = new Set([
     // Shipped GATABLE but ungated: no built-in preset carries `gating` on it, so the default cost
     // is unchanged and an author who wants a trivial bugfix to skip the reproduction opts in.
     'repro-test',
+    // The bugfix verification tests, on the same argument as `repro-test` and `mocker` (which sits
+    // immediately before it in `pl_bugfix_tested`). It is another `container-coding` dispatch, and
+    // nothing reads its declaration structurally: the digest resolver no-ops on a step that never
+    // ran, the PR report's note and the outcome summary's gap both key off a step carrying a
+    // result, and both answer the plain absence when there is none. So its skip THINS a run.
+    //
+    // Gatable together with the mocker before it, deliberately: an author who gates one and not the
+    // other splits a pair, leaving integration tests to be written against doubles the gated-out
+    // mocker never created. Leaving this one out of the set is what made that split the only
+    // reachable configuration.
+    'integration-test',
     // Documentation of work already done.
     'documenter',
     'business-documenter',

package/dist/agent-gating.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-gating.js","sourceRoot":"","sources":["../src/agent-gating.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,mEAAmE;AACnE,EAAE;AACF,+FAA+F;AAC/F,0FAA0F;AAC1F,6FAA6F;AAC7F,oGAAoG;AACpG,kGAAkG;AAClG,8FAA8F;AAC9F,kGAAkG;AAClG,6FAA6F;AAC7F,YAAY;AACZ,EAAE;AACF,iGAAiG;AACjG,oGAAoG;AACpG,qGAAqG;AACrG,qGAAqG;AACrG,oGAAoG;AACpG,eAAe;AACf,EAAE;AACF,sFAAsF;AACtF,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,yFAAyF;AACzF,kGAAkG;AAClG,kGAAkG;AAClG,oGAAoG;AACpG,2FAA2F;AAC3F,kGAAkG;AAClG,WAAW;AACX,mGAAmG;AACnG,sCAAsC;AACtC,EAAE;AACF,kGAAkG;AAClG,4FAA4F;AAC5F,mDAAmD;AACnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAS;IACxE,+EAA+E;IAC/E,UAAU;IACV,qBAAqB;IACrB,gBAAgB;IAChB,cAAc;IACd,0FAA0F;IAC1F,qFAAqF;IACrF,WAAW;IACX,YAAY;IACZ,aAAa;IACb,yDAAyD;IACzD,QAAQ;IACR,YAAY;IACZ,gBAAgB;IAChB,4FAA4F;IAC5F,oFAAoF;IACpF,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,4BAA4B;IAC5B,EAAE;IACF,6FAA6F;IAC7F,qFAAqF;IACrF,6FAA6F;IAC7F,+FAA+F;IAC/F,mFAAmF;IACnF,EAAE;IACF,8FAA8F;IAC9F,0FAA0F;IAC1F,YAAY;IACZ,sCAAsC;IACtC,YAAY;IACZ,qBAAqB;IACrB,+FAA+F;IAC/F,6FAA6F;IAC7F,sFAAsF;IACtF,6FAA6F;IAC7F,iGAAiG;IACjG,EAAE;IACF,8FAA8F;IAC9F,iBAAiB;IACjB,4FAA4F;IAC5F,8FAA8F;IAC9F,8FAA8F;IAC9F,wFAAwF;IACxF,EAAE;IACF,gGAAgG;IAChG,iGAAiG;IACjG,gGAAgG;IAChG,kGAAkG;IAClG,gGAAgG;IAChG,kGAAkG;IAClG,6FAA6F;IAC7F,yFAAyF;IACzF,wDAAwD;IACxD,qBAAqB;IACrB,cAAc;IACd,YAAY;IACZ,qBAAqB;CACtB,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAS;IAC3E,gBAAgB;IAChB,iBAAiB;CAClB,CAAC,CAAA;AAEF,yEAAyE;AACzE,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC3C,CAAC"}
+{"version":3,"file":"agent-gating.js","sourceRoot":"","sources":["../src/agent-gating.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,mEAAmE;AACnE,EAAE;AACF,+FAA+F;AAC/F,0FAA0F;AAC1F,6FAA6F;AAC7F,oGAAoG;AACpG,kGAAkG;AAClG,8FAA8F;AAC9F,kGAAkG;AAClG,6FAA6F;AAC7F,YAAY;AACZ,EAAE;AACF,iGAAiG;AACjG,oGAAoG;AACpG,qGAAqG;AACrG,qGAAqG;AACrG,oGAAoG;AACpG,eAAe;AACf,EAAE;AACF,sFAAsF;AACtF,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,yFAAyF;AACzF,kGAAkG;AAClG,kGAAkG;AAClG,oGAAoG;AACpG,2FAA2F;AAC3F,kGAAkG;AAClG,WAAW;AACX,mGAAmG;AACnG,sCAAsC;AACtC,EAAE;AACF,kGAAkG;AAClG,4FAA4F;AAC5F,mDAAmD;AACnD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAS;IACxE,+EAA+E;IAC/E,UAAU;IACV,qBAAqB;IACrB,gBAAgB;IAChB,cAAc;IACd,0FAA0F;IAC1F,qFAAqF;IACrF,WAAW;IACX,YAAY;IACZ,aAAa;IACb,yDAAyD;IACzD,QAAQ;IACR,YAAY;IACZ,gBAAgB;IAChB,4FAA4F;IAC5F,oFAAoF;IACpF,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,0FAA0F;IAC1F,6FAA6F;IAC7F,2FAA2F;IAC3F,4BAA4B;IAC5B,EAAE;IACF,6FAA6F;IAC7F,qFAAqF;IACrF,6FAA6F;IAC7F,+FAA+F;IAC/F,mFAAmF;IACnF,EAAE;IACF,8FAA8F;IAC9F,0FAA0F;IAC1F,YAAY;IACZ,+FAA+F;IAC/F,+FAA+F;IAC/F,8FAA8F;IAC9F,yFAAyF;IACzF,yFAAyF;IACzF,EAAE;IACF,gGAAgG;IAChG,6FAA6F;IAC7F,yFAAyF;IACzF,2BAA2B;IAC3B,kBAAkB;IAClB,sCAAsC;IACtC,YAAY;IACZ,qBAAqB;IACrB,+FAA+F;IAC/F,6FAA6F;IAC7F,sFAAsF;IACtF,6FAA6F;IAC7F,iGAAiG;IACjG,EAAE;IACF,8FAA8F;IAC9F,iBAAiB;IACjB,4FAA4F;IAC5F,8FAA8F;IAC9F,8FAA8F;IAC9F,wFAAwF;IACxF,EAAE;IACF,gGAAgG;IAChG,iGAAiG;IACjG,gGAAgG;IAChG,kGAAkG;IAClG,gGAAgG;IAChG,kGAAkG;IAClG,6FAA6F;IAC7F,yFAAyF;IACzF,wDAAwD;IACxD,qBAAqB;IACrB,cAAc;IACd,YAAY;IACZ,qBAAqB;CACtB,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAwB,IAAI,GAAG,CAAS;IAC3E,gBAAgB;IAChB,iBAAiB;CAClB,CAAC,CAAA;AAEF,yEAAyE;AACzE,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,OAAO,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC3C,CAAC"}

package/dist/assistant.d.ts

@@ -0,0 +1,419 @@
+import * as v from 'valibot';
+/**
+ * The actions the assistant can perform. CLOSED, and deliberately small.
+ *
+ * Each member is an operation the board already offers behind a form, so the assistant adds a
+ * way to ASK for it rather than a capability nobody could otherwise reach. Adding a member means
+ * adding its result variant below and its executor in the engine catalog, both of which fail to
+ * compile until they exist.
+ */
+export declare const assistantActionIdSchema: v.PicklistSchema<["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"], undefined>;
+export type AssistantActionId = v.InferOutput<typeof assistantActionIdSchema>;
+/** Every action the assistant knows, in the order the SPA lists them as suggestions. */
+export declare const ASSISTANT_ACTION_IDS: readonly ["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"];
+/** A board service the turn touched: enough to name it and to link to it. */
+export declare const assistantServiceRefSchema: v.ObjectSchema<{
+    /** The service FRAME's block id. */
+    readonly blockId: v.StringSchema<undefined>;
+    /** The frame's title, as it stands after the turn. */
+    readonly title: v.StringSchema<undefined>;
+}, undefined>;
+export type AssistantServiceRef = v.InferOutput<typeof assistantServiceRefSchema>;
+/**
+ * A declared dependency edge.
+ *
+ * `created` is false when the edge was already on the board. The turn still SUCCEEDED (the board
+ * is in the state that was asked for), and saying so is what stops the SPA from reporting an
+ * idempotent re-declaration as a fresh one.
+ */
+export declare const assistantDependencyDeclaredSchema: v.ObjectSchema<{
+    readonly actionId: v.LiteralSchema<"declare-service-dependency", undefined>;
+    /** The service that DEPENDS on the other (the edge is stored on this one). */
+    readonly consumer: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** The service depended ON, spun up alongside the consumer when it is tested. */
+    readonly provider: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** Whether this turn added the edge (false ⇒ it was already declared). */
+    readonly created: v.BooleanSchema<undefined>;
+}, undefined>;
+/**
+ * A service frame backed by a repository.
+ *
+ * `created` distinguishes a new frame from an existing account service this board now MOUNTS,
+ * the deduplication `addServiceFromRepo` performs for a whole-repo service the org already runs.
+ * The two are different facts about the board, and a caller told only "here is your service"
+ * would read the second as the first.
+ */
+export declare const assistantServiceAddedSchema: v.ObjectSchema<{
+    readonly actionId: v.LiteralSchema<"add-service-from-repo", undefined>;
+    readonly service: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** The repository the frame is backed by. */
+    readonly repo: v.ObjectSchema<{
+        readonly owner: v.StringSchema<undefined>;
+        readonly name: v.StringSchema<undefined>;
+        /** The monorepo subdirectory the service lives in, or null for a whole-repo service. */
+        readonly directory: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+    /** Whether this turn created the frame (false ⇒ an existing org service was mounted here). */
+    readonly created: v.BooleanSchema<undefined>;
+}, undefined>;
+/** A board task filed from a tracker issue. */
+export declare const assistantTaskCreatedSchema: v.ObjectSchema<{
+    readonly actionId: v.LiteralSchema<"create-task-from-issue", undefined>;
+    readonly task: v.ObjectSchema<{
+        readonly blockId: v.StringSchema<undefined>;
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** The service frame the task was filed under. */
+    readonly service: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    readonly issue: v.ObjectSchema<{
+        readonly source: v.UnionSchema<[v.PicklistSchema<readonly ["jira", "github", "linear", "gitlab"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>;
+        /** The source's canonical key (`owner/repo#12`, `PROJ-7`). */
+        readonly externalId: v.StringSchema<undefined>;
+        readonly url: v.StringSchema<undefined>;
+    }, undefined>;
+}, undefined>;
+/** What a performed turn did, discriminated by the action that did it. */
+export declare const assistantActionResultSchema: v.VariantSchema<"actionId", [v.ObjectSchema<{
+    readonly actionId: v.LiteralSchema<"declare-service-dependency", undefined>;
+    /** The service that DEPENDS on the other (the edge is stored on this one). */
+    readonly consumer: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** The service depended ON, spun up alongside the consumer when it is tested. */
+    readonly provider: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** Whether this turn added the edge (false ⇒ it was already declared). */
+    readonly created: v.BooleanSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly actionId: v.LiteralSchema<"add-service-from-repo", undefined>;
+    readonly service: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** The repository the frame is backed by. */
+    readonly repo: v.ObjectSchema<{
+        readonly owner: v.StringSchema<undefined>;
+        readonly name: v.StringSchema<undefined>;
+        /** The monorepo subdirectory the service lives in, or null for a whole-repo service. */
+        readonly directory: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>;
+    /** Whether this turn created the frame (false ⇒ an existing org service was mounted here). */
+    readonly created: v.BooleanSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly actionId: v.LiteralSchema<"create-task-from-issue", undefined>;
+    readonly task: v.ObjectSchema<{
+        readonly blockId: v.StringSchema<undefined>;
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    /** The service frame the task was filed under. */
+    readonly service: v.ObjectSchema<{
+        /** The service FRAME's block id. */
+        readonly blockId: v.StringSchema<undefined>;
+        /** The frame's title, as it stands after the turn. */
+        readonly title: v.StringSchema<undefined>;
+    }, undefined>;
+    readonly issue: v.ObjectSchema<{
+        readonly source: v.UnionSchema<[v.PicklistSchema<readonly ["jira", "github", "linear", "gitlab"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>;
+        /** The source's canonical key (`owner/repo#12`, `PROJ-7`). */
+        readonly externalId: v.StringSchema<undefined>;
+        readonly url: v.StringSchema<undefined>;
+    }, undefined>;
+}, undefined>], undefined>;
+export type AssistantActionResult = v.InferOutput<typeof assistantActionResultSchema>;
+/**
+ * Why the platform could not resolve one argument to something on the board.
+ *
+ * Each member names a DIFFERENT next move for the person, which is why they are not one
+ * "could not resolve" value: an unknown name is retyped, an ambiguous one is picked from the
+ * candidates, a missing argument is supplied, and an unconnected repository or tracker is a trip
+ * to the integrations panel before the same sentence works.
+ */
+export declare const assistantClarificationReasonSchema: v.PicklistSchema<["missing_argument", "invalid_argument", "unknown_service", "ambiguous_service", "unknown_repository", "unreadable_repository_url", "unknown_issue_source", "ambiguous_issue_source", "unresolved_issue_service"], undefined>;
+export type AssistantClarificationReason = v.InferOutput<typeof assistantClarificationReasonSchema>;
+/**
+ * One action's arguments on the wire: declared keys, string values.
+ *
+ * Capped per value at the same length as a prompt, because they come back INTO the platform when a
+ * clarification is answered, and an unbounded value there would be a bigger input than the sentence
+ * that produced it.
+ */
+export declare const assistantArgumentsSchema: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+export type AssistantArguments = v.InferOutput<typeof assistantArgumentsSchema>;
+/** Why no action ran at all. */
+export declare const assistantDeclineReasonSchema: v.PicklistSchema<["no_matching_action"], undefined>;
+export type AssistantDeclineReason = v.InferOutput<typeof assistantDeclineReasonSchema>;
+/**
+ * The outcome of one turn.
+ *
+ * `needs_input` carries the action it was HEADING for, so the SPA can say what it was about to do
+ * rather than only what it could not find, and `candidates` is the shortlist the platform was
+ * choosing between (empty when there was nothing to choose from, since an unknown name has no
+ * near-misses to offer).
+ */
+export declare const assistantOutcomeSchema: v.VariantSchema<"status", [v.ObjectSchema<{
+    readonly status: v.LiteralSchema<"performed", undefined>;
+    readonly result: v.VariantSchema<"actionId", [v.ObjectSchema<{
+        readonly actionId: v.LiteralSchema<"declare-service-dependency", undefined>;
+        /** The service that DEPENDS on the other (the edge is stored on this one). */
+        readonly consumer: v.ObjectSchema<{
+            /** The service FRAME's block id. */
+            readonly blockId: v.StringSchema<undefined>;
+            /** The frame's title, as it stands after the turn. */
+            readonly title: v.StringSchema<undefined>;
+        }, undefined>;
+        /** The service depended ON, spun up alongside the consumer when it is tested. */
+        readonly provider: v.ObjectSchema<{
+            /** The service FRAME's block id. */
+            readonly blockId: v.StringSchema<undefined>;
+            /** The frame's title, as it stands after the turn. */
+            readonly title: v.StringSchema<undefined>;
+        }, undefined>;
+        /** Whether this turn added the edge (false ⇒ it was already declared). */
+        readonly created: v.BooleanSchema<undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly actionId: v.LiteralSchema<"add-service-from-repo", undefined>;
+        readonly service: v.ObjectSchema<{
+            /** The service FRAME's block id. */
+            readonly blockId: v.StringSchema<undefined>;
+            /** The frame's title, as it stands after the turn. */
+            readonly title: v.StringSchema<undefined>;
+        }, undefined>;
+        /** The repository the frame is backed by. */
+        readonly repo: v.ObjectSchema<{
+            readonly owner: v.StringSchema<undefined>;
+            readonly name: v.StringSchema<undefined>;
+            /** The monorepo subdirectory the service lives in, or null for a whole-repo service. */
+            readonly directory: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>;
+        /** Whether this turn created the frame (false ⇒ an existing org service was mounted here). */
+        readonly created: v.BooleanSchema<undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly actionId: v.LiteralSchema<"create-task-from-issue", undefined>;
+        readonly task: v.ObjectSchema<{
+            readonly blockId: v.StringSchema<undefined>;
+            readonly title: v.StringSchema<undefined>;
+        }, undefined>;
+        /** The service frame the task was filed under. */
+        readonly service: v.ObjectSchema<{
+            /** The service FRAME's block id. */
+            readonly blockId: v.StringSchema<undefined>;
+            /** The frame's title, as it stands after the turn. */
+            readonly title: v.StringSchema<undefined>;
+        }, undefined>;
+        readonly issue: v.ObjectSchema<{
+            readonly source: v.UnionSchema<[v.PicklistSchema<readonly ["jira", "github", "linear", "gitlab"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>;
+            /** The source's canonical key (`owner/repo#12`, `PROJ-7`). */
+            readonly externalId: v.StringSchema<undefined>;
+            readonly url: v.StringSchema<undefined>;
+        }, undefined>;
+    }, undefined>], undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly status: v.LiteralSchema<"needs_input", undefined>;
+    readonly actionId: v.PicklistSchema<["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"], undefined>;
+    readonly reason: v.PicklistSchema<["missing_argument", "invalid_argument", "unknown_service", "ambiguous_service", "unknown_repository", "unreadable_repository_url", "unknown_issue_source", "ambiguous_issue_source", "unresolved_issue_service"], undefined>;
+    /** The argument key that could not be resolved (`consumer`, `repoUrl`, `source`, …). */
+    readonly field: v.StringSchema<undefined>;
+    /**
+     * What the platform was choosing between, at most a handful. Empty ⇒ nothing matched.
+     *
+     * Every entry is a legal VALUE for {@link field}, not a label describing one, because the
+     * clarification is answered by putting a candidate in that field (see
+     * {@link assistantAnswerSchema}). An action offering a candidate its own next turn would
+     * refuse is a question with no acceptable answer, which is why the near-misses an unknown
+     * repository reports are `owner/name` slugs and the trackers an ambiguous reference reports
+     * are source ids.
+     */
+    readonly candidates: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The arguments the turn resolved, so the answer can be a RESUMPTION rather than a retyped
+     * sentence. Declared keys only, already validated, and the person's own words either way.
+     */
+    readonly arguments: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly status: v.LiteralSchema<"declined", undefined>;
+    readonly reason: v.PicklistSchema<["no_matching_action"], undefined>;
+}, undefined>], undefined>;
+export type AssistantOutcome = v.InferOutput<typeof assistantOutcomeSchema>;
+/** One turn: what the platform did, and which model read the prompt to decide it. */
+export declare const assistantTurnSchema: v.ObjectSchema<{
+    readonly outcome: v.VariantSchema<"status", [v.ObjectSchema<{
+        readonly status: v.LiteralSchema<"performed", undefined>;
+        readonly result: v.VariantSchema<"actionId", [v.ObjectSchema<{
+            readonly actionId: v.LiteralSchema<"declare-service-dependency", undefined>;
+            /** The service that DEPENDS on the other (the edge is stored on this one). */
+            readonly consumer: v.ObjectSchema<{
+                /** The service FRAME's block id. */
+                readonly blockId: v.StringSchema<undefined>;
+                /** The frame's title, as it stands after the turn. */
+                readonly title: v.StringSchema<undefined>;
+            }, undefined>;
+            /** The service depended ON, spun up alongside the consumer when it is tested. */
+            readonly provider: v.ObjectSchema<{
+                /** The service FRAME's block id. */
+                readonly blockId: v.StringSchema<undefined>;
+                /** The frame's title, as it stands after the turn. */
+                readonly title: v.StringSchema<undefined>;
+            }, undefined>;
+            /** Whether this turn added the edge (false ⇒ it was already declared). */
+            readonly created: v.BooleanSchema<undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly actionId: v.LiteralSchema<"add-service-from-repo", undefined>;
+            readonly service: v.ObjectSchema<{
+                /** The service FRAME's block id. */
+                readonly blockId: v.StringSchema<undefined>;
+                /** The frame's title, as it stands after the turn. */
+                readonly title: v.StringSchema<undefined>;
+            }, undefined>;
+            /** The repository the frame is backed by. */
+            readonly repo: v.ObjectSchema<{
+                readonly owner: v.StringSchema<undefined>;
+                readonly name: v.StringSchema<undefined>;
+                /** The monorepo subdirectory the service lives in, or null for a whole-repo service. */
+                readonly directory: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>;
+            /** Whether this turn created the frame (false ⇒ an existing org service was mounted here). */
+            readonly created: v.BooleanSchema<undefined>;
+        }, undefined>, v.ObjectSchema<{
+            readonly actionId: v.LiteralSchema<"create-task-from-issue", undefined>;
+            readonly task: v.ObjectSchema<{
+                readonly blockId: v.StringSchema<undefined>;
+                readonly title: v.StringSchema<undefined>;
+            }, undefined>;
+            /** The service frame the task was filed under. */
+            readonly service: v.ObjectSchema<{
+                /** The service FRAME's block id. */
+                readonly blockId: v.StringSchema<undefined>;
+                /** The frame's title, as it stands after the turn. */
+                readonly title: v.StringSchema<undefined>;
+            }, undefined>;
+            readonly issue: v.ObjectSchema<{
+                readonly source: v.UnionSchema<[v.PicklistSchema<readonly ["jira", "github", "linear", "gitlab"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>;
+                /** The source's canonical key (`owner/repo#12`, `PROJ-7`). */
+                readonly externalId: v.StringSchema<undefined>;
+                readonly url: v.StringSchema<undefined>;
+            }, undefined>;
+        }, undefined>], undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly status: v.LiteralSchema<"needs_input", undefined>;
+        readonly actionId: v.PicklistSchema<["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"], undefined>;
+        readonly reason: v.PicklistSchema<["missing_argument", "invalid_argument", "unknown_service", "ambiguous_service", "unknown_repository", "unreadable_repository_url", "unknown_issue_source", "ambiguous_issue_source", "unresolved_issue_service"], undefined>;
+        /** The argument key that could not be resolved (`consumer`, `repoUrl`, `source`, …). */
+        readonly field: v.StringSchema<undefined>;
+        /**
+         * What the platform was choosing between, at most a handful. Empty ⇒ nothing matched.
+         *
+         * Every entry is a legal VALUE for {@link field}, not a label describing one, because the
+         * clarification is answered by putting a candidate in that field (see
+         * {@link assistantAnswerSchema}). An action offering a candidate its own next turn would
+         * refuse is a question with no acceptable answer, which is why the near-misses an unknown
+         * repository reports are `owner/name` slugs and the trackers an ambiguous reference reports
+         * are source ids.
+         */
+        readonly candidates: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The arguments the turn resolved, so the answer can be a RESUMPTION rather than a retyped
+         * sentence. Declared keys only, already validated, and the person's own words either way.
+         */
+        readonly arguments: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly status: v.LiteralSchema<"declined", undefined>;
+        readonly reason: v.PicklistSchema<["no_matching_action"], undefined>;
+    }, undefined>], undefined>;
+    /**
+     * The model that chose the action, so a turn can be traced to the route that produced it.
+     *
+     * NULL for an ANSWERED clarification, which runs no model at all. Reporting the model the
+     * previous turn used would attribute a deterministic re-run to a call that never happened, and
+     * an absent value is the only honest way to say a turn spent nothing.
+     */
+    readonly model: v.NullableSchema<v.ObjectSchema<{
+        readonly provider: v.StringSchema<undefined>;
+        readonly model: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type AssistantTurn = v.InferOutput<typeof assistantTurnSchema>;
+/**
+ * Answering a question a previous turn asked, as DATA rather than as more prose.
+ *
+ * This is what makes a clarification terminate. The alternative the surface started with was to
+ * append the chosen candidate to the sentence and route it through the model again, and that
+ * cannot converge: the original words are still in the prompt (a repository under the wrong owner
+ * stays there beside the right one), and a candidate the model has no declared argument to put it
+ * in is simply dropped. Re-running the same action with the same arguments and the one field
+ * replaced is exact, terminates in one step, and bills nothing.
+ *
+ * It grants no authority the prompt path does not. The arguments are re-validated by the same
+ * descriptor rules, undeclared keys are dropped exactly as they are for a model's reply, every
+ * name is re-resolved against the board, and the action is the same one a button performs under
+ * the caller's own tier.
+ */
+export declare const assistantAnswerSchema: v.ObjectSchema<{
+    /** The action the question was asked on behalf of, as its outcome named it. */
+    readonly actionId: v.PicklistSchema<["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"], undefined>;
+    /** That turn's arguments, with the answered field replaced by the value the person chose. */
+    readonly arguments: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+}, undefined>;
+export type AssistantAnswer = v.InferOutput<typeof assistantAnswerSchema>;
+/**
+ * What a turn runs on: a sentence to route, or the answer to the question the last one asked.
+ *
+ * Discriminated rather than "a prompt plus an optional answer", because the two share no field: an
+ * answered turn has no sentence to read and never reaches a model, and a shape carrying a required
+ * prompt beside it would make every answer invent one.
+ */
+export declare const assistantTurnInputSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"prompt", undefined>;
+    readonly prompt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 2000, undefined>]>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"answer", undefined>;
+    readonly answer: v.ObjectSchema<{
+        /** The action the question was asked on behalf of, as its outcome named it. */
+        readonly actionId: v.PicklistSchema<["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"], undefined>;
+        /** That turn's arguments, with the answered field replaced by the value the person chose. */
+        readonly arguments: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+    }, undefined>;
+}, undefined>], undefined>;
+export type AssistantTurnInput = v.InferOutput<typeof assistantTurnInputSchema>;
+/**
+ * What this deployment's assistant can do, read before the prompt box is offered.
+ *
+ * `available` is about the MODEL, not about permissions: a deployment that wired no provider
+ * cannot answer a prompt, and hiding the box is a better answer than a 503 on every submission.
+ * The action list is published rather than assumed so a deployment that narrows the catalog
+ * narrows the suggestions with it, instead of advertising an action the engine would decline.
+ */
+export declare const assistantCapabilitySchema: v.ObjectSchema<{
+    readonly available: v.BooleanSchema<undefined>;
+    readonly actions: v.ArraySchema<v.PicklistSchema<["declare-service-dependency", "add-service-from-repo", "create-task-from-issue"], undefined>, undefined>;
+}, undefined>;
+export type AssistantCapability = v.InferOutput<typeof assistantCapabilitySchema>;
+//# sourceMappingURL=assistant.d.ts.map

package/dist/assistant.d.ts.map

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