@gobing-ai/ts-ai-decision 0.5.30 → 0.5.33

package/dist/types.d.ts

@@ -46,13 +46,21 @@ export interface DecisionDefinition {
     readonly fallback: string | number | boolean;
     /** Overrides `defaults.minConfidence` (0..1). */
     readonly minConfidence?: number;
-    /** Registry name, checked at hub load, not by the catalog loader. */
-    readonly maker?: string;
+    /** Registry name, or an ordered fallback chain of names (ADR-040); checked at hub load, not by the loader. */
+    readonly maker?: MakerRef;
+    /** One maker asked beside the primary on live traffic and reported, never served (ADR-040). */
+    readonly shadow?: string;
     readonly model?: string;
 }
+/**
+ * A maker reference: one registry name, or an ordered fallback chain of names (ADR-040). The
+ * authored form is preserved (`string` stays `string`), so a single-name catalog round-trips
+ * byte-identically; the hub resolves the chain per call.
+ */
+export type MakerRef = string | readonly string[];
 /** Catalog-wide maker/model/minConfidence defaults; every key optional. */
 export interface CatalogDefaults {
-    readonly maker?: string;
+    readonly maker?: MakerRef;
     readonly model?: string;
     readonly minConfidence?: number;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE1D,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAEvD,yFAAyF;AACzF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,2GAA2G;AAC3G,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC;AAE5B,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAA;CAAE,CAAC;AAE7G,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC7C,iDAAiD;IACjD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;CACpE;AAED,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAElD,iFAAiF;AACjF,MAAM,MAAM,WAAW,GACjB;IACI,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CACzD,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GACnG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;CAC/E,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAE1D,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAEvD,yFAAyF;AACzF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,2GAA2G;AAC3G,MAAM,MAAM,QAAQ,GAAG,IAAI,CAAC;AAE5B,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAA;CAAE,CAAC;AAE7G,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC7C,iDAAiD;IACjD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,8GAA8G;IAC9G,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAElD,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;CACpE;AAED,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAElD,iFAAiF;AACjF,MAAM,MAAM,WAAW,GACjB;IACI,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CACzD,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAA;CAAE,GACnG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;CAC/E,CAAC"}

package/dist/typesafe-driver.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The TypeSafe backend driver — the only decision file that imports
+ * `@typesafe-ai/sdk` (0069 pin). Client wiring (R1/R2), neutral⇄SDK question
+ * and answer mapping (R4/R5), and the error translation table (R7) live here;
+ * everything above this file stays vendor-neutral.
+ */
+import { type DecisionDriver } from '@gobing-ai/ts-ai-runner';
+/** Configuration the facade resolves (key per R7) and forwards to the TypeSafe driver. */
+export interface TypesafeDriverConfig {
+    apiKey: string;
+    model?: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * Build the TypeSafe driver: exactly one `TypeSafeClient` per driver instance
+ * (R2), the API key always passed explicitly so the SDK's `TYPESAFE_API_KEY`
+ * self-resolution never runs (R1). All transport failures — at construction
+ * or at ask time — come back as `DecisionError`s, never SDK classes (R7).
+ */
+export declare function createTypesafeDriver(config: TypesafeDriverConfig): DecisionDriver;
+//# sourceMappingURL=typesafe-driver.d.ts.map

package/dist/typesafe-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesafe-driver.d.ts","sourceRoot":"","sources":["../src/typesafe-driver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAKH,KAAK,cAAc,EAQtB,MAAM,yBAAyB,CAAC;AAqBjC,0FAA0F;AAC1F,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAqDjF"}

package/dist/typesafe-driver.js

@@ -0,0 +1,160 @@
+/**
+ * The TypeSafe backend driver — the only decision file that imports
+ * `@typesafe-ai/sdk` (0069 pin). Client wiring (R1/R2), neutral⇄SDK question
+ * and answer mapping (R4/R5), and the error translation table (R7) live here;
+ * everything above this file stays vendor-neutral.
+ */
+import { DecisionAuthError, DecisionBackendError, DecisionConnectionError, DecisionRateLimitError, DecisionRequestError, DecisionTimeoutError, validateAnswers, validateQuestions, } from '@gobing-ai/ts-ai-runner';
+import { APIConnectionError, APIError, APITimeoutError, AuthenticationError, choice, PermissionDeniedError, RateLimitError, score, TypeSafeClient, TypeSafeError, } from '@typesafe-ai/sdk';
+/**
+ * Build the TypeSafe driver: exactly one `TypeSafeClient` per driver instance
+ * (R2), the API key always passed explicitly so the SDK's `TYPESAFE_API_KEY`
+ * self-resolution never runs (R1). All transport failures — at construction
+ * or at ask time — come back as `DecisionError`s, never SDK classes (R7).
+ */
+export function createTypesafeDriver(config) {
+    let client;
+    try {
+        client = new TypeSafeClient({
+            apiKey: config.apiKey,
+            // baseURL is forwarded as-is. SDK 0.7.0 still exports no default
+            // base-URL constant (`ENV.baseURL` is the env-var NAME, and the
+            // documented default `https://api.typesafe.ai` lives only in the
+            // config JSDoc), so an omitted baseURL keeps letting the SDK
+            // self-resolve `TYPESAFE_BASE_URL` — documented residual for 0073.
+            baseURL: config.baseURL,
+            defaultModel: config.model,
+            timeout: config.timeoutMs,
+            retry: config.maxRetries === undefined ? undefined : { maxRetries: config.maxRetries },
+            fetch: config.fetch,
+        });
+    }
+    catch (err) {
+        translateError(err);
+    }
+    return {
+        name: 'typesafe',
+        async ask({ state, questions, model }) {
+            validateQuestions(questions);
+            // The neutral contract allows `null` state ("no caller context") and the SDK type
+            // accepts it, but the wire drops a null field and the API answers 422 "state: Field
+            // required" — so every fully parameterless decision used to fall back on this backend.
+            // Same null→'' mapping the laya and fm drivers already apply; structured state passes
+            // through untouched (the wire accepts an object or array).
+            let result;
+            try {
+                const sdkQuestions = Object.fromEntries(Object.entries(questions).map(([name, question]) => [name, toSdkQuestion(question)]));
+                result = await client.systemOne({ state: state ?? '', questions: sdkQuestions, model });
+            }
+            catch (err) {
+                translateError(err);
+            }
+            // R6: the SDK echoes the request's question names, so the mapped
+            // record keeps the caller's keys in correspondence. R8: `model`
+            // and `usage` on the result are deliberately not surfaced.
+            if (!result?.answers || typeof result.answers !== 'object' || Array.isArray(result.answers)) {
+                throw new DecisionBackendError('Invalid decision response: expected answers map', undefined);
+            }
+            const answers = Object.fromEntries(Object.entries(result.answers).map(([name, answer]) => [name, fromSdkAnswer(answer)]));
+            validateAnswers(questions, answers);
+            return answers;
+        },
+    };
+}
+/** Neutral question → SDK wire question (R4). `null` is "undescribed" on the wire. */
+function toSdkQuestion(question) {
+    switch (question.kind) {
+        case 'choice':
+            return choice(question.prompt ?? null, question.labels);
+        case 'score':
+            return score(question.prompt ?? null, question.rubric);
+        case 'noul': {
+            const outcomes = question.yes === undefined && question.no === undefined
+                ? undefined
+                : { true: question.yes, false: question.no };
+            // SDK 0.7.0's `noul()` overloads cannot express an undescribed noul
+            // (`instructions` null with no criteria), which the neutral contract allows,
+            // so the same object is built directly. The intent type is identical to the
+            // builder's, and the wire shape is unchanged for every described case.
+            const noulQuestion = { type: 'noul', instructions: question.prompt ?? null };
+            if (outcomes !== undefined)
+                noulQuestion.criteria = outcomes;
+            return noulQuestion;
+        }
+    }
+}
+/**
+ * Read the rubric legend as the neutral index → description map. The SDK's `ScoreLegend`
+ * threads a recursive conditional (`SentContent`) that the compiler cannot resolve once the
+ * question map is the neutral union, so the value is handed over here; `validateAnswers`
+ * enforces the real shape at runtime.
+ */
+function legendOf(wire) {
+    return wire.legend;
+}
+/** SDK wire response → neutral answer (R5). Noul gets no confidence — the wire has none and none is invented. */
+function fromSdkAnswer(answer) {
+    if (!answer || typeof answer !== 'object')
+        throw new DecisionBackendError('Invalid decision response: expected answer object', undefined);
+    switch (answer.type) {
+        case 'choice':
+            return {
+                kind: 'choice',
+                label: answer.choice,
+                confidence: answer.confidence,
+                probabilities: answer.probabilities,
+            };
+        case 'score': {
+            // SDK 0.7.0 infers `ScoreResponse<ScoreCriteria>` from `ResultFor<Question>` too deeply to
+            // instantiate (TS2589), so the branch reads through the non-generic default instead and
+            // hands the legend over through a helper. `validateAnswers` checks the values at runtime.
+            const wire = answer;
+            return {
+                kind: 'score',
+                score: wire.score,
+                confidence: wire.confidence,
+                legend: legendOf(wire),
+                probabilities: wire.probabilities,
+            };
+        }
+        case 'noul':
+            return { kind: 'noul', probability: answer.noul };
+        default:
+            throw new DecisionBackendError('Invalid decision response: unknown answer kind', undefined);
+    }
+}
+/**
+ * R7, per the design doc's error table. Ordered subclass-before-base:
+ * `APITimeoutError` extends `APIConnectionError`, and the HTTP subclasses
+ * extend `APIError`. Rows the table does not name fall to the nearest home:
+ * 4xx (`NotFoundError` included) is a `DecisionRequestError`, and any local
+ * `TypeSafeError` (empty questions, invalid client config) lands there too
+ * with `status: undefined` — so no SDK class ever escapes. Foreign errors are
+ * rethrown untouched; they are not this package's to translate.
+ */
+function translateError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof RateLimitError) {
+        throw new DecisionRateLimitError(message, err.status, err.retryAfterMs, { cause: err });
+    }
+    if (err instanceof AuthenticationError || err instanceof PermissionDeniedError) {
+        throw new DecisionAuthError(message, err.status, { cause: err });
+    }
+    if (err instanceof APITimeoutError) {
+        throw new DecisionTimeoutError(message, err.timeoutMs, { cause: err });
+    }
+    if (err instanceof APIConnectionError) {
+        throw new DecisionConnectionError(message, { cause: err });
+    }
+    if (err instanceof APIError) {
+        if (err.status < 500) {
+            const raw = typeof err.body === 'string' ? err.body : (JSON.stringify(err.body) ?? '');
+            throw new DecisionRequestError(message, err.status, raw.slice(0, 200) || undefined, { cause: err });
+        }
+        throw new DecisionBackendError(message, err.status, { cause: err });
+    }
+    if (err instanceof TypeSafeError) {
+        throw new DecisionRequestError(message, undefined, message, { cause: err });
+    }
+    throw err;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-decision",
-    "version": "0.5.30",
+    "version": "0.5.33",
     "description": "@gobing-ai/ts-ai-decision — Declarative YAML decision catalog over the ts-ai-runner DecisionMaker surface.",
     "keywords": [
         "typescript",
@@ -51,13 +51,17 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-decision-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-ai-runner": "^0.5.30",
-        "@gobing-ai/ts-decision-fm": "^0.5.30",
-        "@gobing-ai/ts-laya-mlx": "^0.5.30",
-        "@gobing-ai/ts-runtime": "^0.5.30",
+        "@gobing-ai/ts-ai-runner": "^0.5.33",
+        "@gobing-ai/ts-decision-fm": "^0.5.33",
+        "@gobing-ai/ts-runtime": "^0.5.33",
+        "@typesafe-ai/sdk": "0.7.0",
         "zod": "^4.1.0"
     },
+    "optionalDependencies": {
+        "@gobing-ai/ts-laya-mlx": "^0.5.33"
+    },
     "devDependencies": {
+        "@gobing-ai/ts-utils": "^0.5.33",
         "@types/bun": "1.4.3"
     },
     "publishConfig": {

package/schemas/decision-catalog.schema.json

@@ -18,9 +18,21 @@
             "additionalProperties": false,
             "properties": {
                 "maker": {
+                    "oneOf": [
+                        { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                        {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+                        }
+                    ],
+                    "description": "Registered maker name, or an ordered fallback list (ADR-040). Built-ins: typesafe | fm-local | laya-local | llm-agent."
+                },
+                "shadow": {
                     "type": "string",
                     "pattern": "^[a-z][a-z0-9-]*$",
-                    "description": "Registered maker name (built-ins: typesafe | fm-local | laya-local)."
+                    "description": "Maker asked beside the primary and reported on the result, never served (ADR-040)."
                 },
                 "model": {
                     "type": "string",
@@ -213,9 +225,21 @@
                     "maximum": 1
                 },
                 "maker": {
+                    "oneOf": [
+                        { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                        {
+                            "type": "array",
+                            "minItems": 1,
+                            "uniqueItems": true,
+                            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+                        }
+                    ],
+                    "description": "Registered maker name, or an ordered fallback list (ADR-040); checked by the hub, not the loader."
+                },
+                "shadow": {
                     "type": "string",
                     "pattern": "^[a-z][a-z0-9-]*$",
-                    "description": "Registered maker name; checked by the hub, not the loader."
+                    "description": "Maker asked beside the primary and reported on the result, never served (ADR-040)."
                 },
                 "model": {
                     "type": "string"

package/src/agent-driver.ts

@@ -0,0 +1,164 @@
+/**
+ * The `llm-agent` decision driver (task 0115, ADR-038/ADR-039): any installed
+ * `ts-ai-runner` coding agent or model answering through the shared sampled-driver
+ * core. Each sample is one isolated one-shot prompt run; probabilities are sample
+ * frequencies (ADR-030) — the agent is never asked for a confidence.
+ *
+ * Every sample runs in a per-ask scratch directory. That is load-bearing, not
+ * tidiness: the claude one-shot shim grants `--permission-mode acceptEdits
+ * --allowedTools Write Edit`, so a decision must never be able to write into the
+ * caller's workspace (R6).
+ */
+
+import {
+    AgentDetector,
+    type AgentName,
+    AiRunner,
+    createSampledDriver,
+    DecisionBackendError,
+    DecisionConfigError,
+    DecisionTimeoutError,
+    declaredOptions,
+    extractJsonAnswer,
+    type PromptOptions,
+    type Question,
+    type SampledDecisionDriver,
+    type SampleSession,
+    TIER1_PRIORITY,
+} from '@gobing-ai/ts-ai-runner';
+import { createNodeFileSystem, type FileSystem, getProcessEnv, joinPath } from '@gobing-ai/ts-runtime';
+
+/** The one runner method a sampled decision needs; a real `AiRunner` satisfies it. */
+export type AgentPromptRunner = Pick<AiRunner, 'runPromptCommand'>;
+
+/** The one detector method the driver needs; a real `AgentDetector` satisfies it. */
+export type AgentDetectorPort = Pick<AgentDetector, 'detectOne'>;
+
+/** Configuration options for {@link createAgentDriver}. */
+export interface AgentDriverOptions {
+    /** Agent to sample. Default: the first installed agent in `TIER1_PRIORITY` (fm is never auto-picked). */
+    readonly agent?: AgentName;
+    /** Model id forwarded as `PromptOptions.model`; a per-ask `model` overrides it. */
+    readonly model?: string;
+    /** Samples per ask. Default: 3. Ignored when `deterministic`. */
+    readonly samples?: number;
+    /** One greedy sample; probabilities are one-hot. Default: false. */
+    readonly deterministic?: boolean;
+    /** Max samples in flight. Default: 1 (sequential). */
+    readonly concurrency?: number;
+    /** Budget for one sample. Default: 120_000. */
+    readonly timeoutMs?: number;
+    /** Injected runner. Default: a lazy `new AiRunner()`. */
+    readonly runner?: AgentPromptRunner;
+    /** Injected detector. Default: a lazy `new AgentDetector({ runner })`. */
+    readonly detector?: AgentDetectorPort;
+    /** Scratch-directory lifecycle. Default: ts-runtime's node FileSystem. */
+    readonly fs?: Pick<FileSystem, 'ensureDir' | 'deleteFile'>;
+}
+
+/** The agent driver: a sampled decision driver named `llm-agent`. */
+export interface AgentDecisionDriver extends SampledDecisionDriver {
+    readonly name: 'llm-agent';
+}
+
+/**
+ * Instructions for a *generic* agent. fm's text mentions "the schema" because fm
+ * receives `--schema`; agents get no such flag, so this text never does.
+ */
+export const AGENT_INSTRUCTIONS =
+    'You are a decision function. Read the context and questions, then reply with exactly one JSON ' +
+    'object mapping each question key to one of its allowed option strings. No prose, no code, no ' +
+    'tool use, no confidence values.';
+
+/**
+ * The per-ask reply contract appended to the prompt: every key with its allowed
+ * option strings, plus one example object. It never asks for probabilities or
+ * confidence (ADR-030).
+ */
+export function JSON_REPLY_SUFFIX(questions: Record<string, Question>): string {
+    const lines = ['', 'Reply with exactly one JSON object and nothing else.'];
+    for (const [key, question] of Object.entries(questions)) {
+        const options = declaredOptions(question)
+            .map((option) => `"${option}"`)
+            .join(', ');
+        lines.push(`- "${key}": one of ${options}`);
+    }
+    const example: Record<string, string> = {};
+    for (const [key, question] of Object.entries(questions)) {
+        example[key] = declaredOptions(question)[0] ?? '';
+    }
+    lines.push('', 'Example:', JSON.stringify(example));
+    return lines.join('\n');
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/**
+ * Build the `llm-agent` decision driver. Construction spawns nothing: the runner
+ * and detector are created lazily and the agent is resolved on the first `ask`.
+ */
+export function createAgentDriver(options: AgentDriverOptions = {}): AgentDecisionDriver {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fs = options.fs ?? createNodeFileSystem();
+    // Created inside the factory, and only when not injected, so construction never spawns.
+    const runner = options.runner ?? new AiRunner();
+    // A real AiRunner satisfies AgentPromptRunner, so this cast only widens a fake back
+    // to the injected seam; a fake runner is always paired with its own fake detector.
+    const detector = options.detector ?? new AgentDetector({ runner: runner as AiRunner });
+    // Memoised on success only: a later ask retries an unresolved agent after an install.
+    let resolved: AgentName | undefined;
+
+    async function resolveAgent(): Promise<AgentName> {
+        if (options.agent !== undefined) return options.agent;
+        if (resolved !== undefined) return resolved;
+        for (const candidate of TIER1_PRIORITY) {
+            const detected = await detector.detectOne(candidate);
+            if (detected.installed) {
+                resolved = detected.name as AgentName;
+                return resolved;
+            }
+        }
+        throw new DecisionConfigError(
+            `no coding agent available for llm-agent; install one of: ${TIER1_PRIORITY.join(', ')}`,
+            'AGENT',
+        );
+    }
+
+    return createSampledDriver({
+        name: 'llm-agent',
+        samples: options.samples ?? 3,
+        deterministic: options.deterministic ?? false,
+        concurrency: options.concurrency ?? 1,
+        instructions: AGENT_INSTRUCTIONS,
+        async open({ instructions, prompt, questions, model }): Promise<SampleSession> {
+            const agent = await resolveAgent();
+            const scratch = joinPath(getProcessEnv().TMPDIR ?? '/tmp', `llm-agent-${crypto.randomUUID()}`);
+            await fs.ensureDir(scratch);
+            const input = `${instructions}\n\n${prompt}${JSON_REPLY_SUFFIX(questions)}`;
+            const promptOptions: PromptOptions = { input, mode: 'text' };
+            const effectiveModel = model ?? options.model;
+            if (effectiveModel !== undefined) promptOptions.model = effectiveModel;
+
+            return {
+                async sample(): Promise<Record<string, string>> {
+                    const result = await runner.runPromptCommand(agent, promptOptions, {
+                        cwd: scratch,
+                        timeout: timeoutMs,
+                    });
+                    if (result.exitCode === null) {
+                        throw new DecisionTimeoutError(`llm-agent sample timed out after ${timeoutMs}ms`, timeoutMs);
+                    }
+                    if (result.exitCode !== 0) {
+                        const firstLine = result.stderr.split('\n')[0]?.trim() ?? '';
+                        throw new DecisionBackendError(
+                            `llm-agent sample failed (${agent} exit ${result.exitCode}): ${firstLine}`,
+                            undefined,
+                        );
+                    }
+                    return extractJsonAnswer(result.stdout);
+                },
+                close: () => fs.deleteFile(scratch),
+            };
+        },
+    }) as AgentDecisionDriver;
+}

package/src/catalog.ts

@@ -354,6 +354,7 @@ function checkDecision(id: string, raw: ParsedDecision, source: string): Decisio
         fallback: raw.fallback,
         ...(raw.minConfidence !== undefined ? { minConfidence: raw.minConfidence } : {}),
         ...(raw.maker !== undefined ? { maker: raw.maker } : {}),
+        ...(raw.shadow !== undefined ? { shadow: raw.shadow } : {}),
         ...(raw.model !== undefined ? { model: raw.model } : {}),
     };
 }