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

package/dist/hub.js

@@ -17,6 +17,38 @@ import { DecisionMakerRegistry } from './registry.js';
 export const DEFAULT_MIN_CONFIDENCE = 0.7;
 /** Hub default when neither the per-call options, the decision nor the catalog names a maker. */
 export const DEFAULT_MAKER = 'typesafe';
+/** Upper bound on a carried error message, in characters (ADR-040). */
+export const DECISION_ERROR_MESSAGE_MAX = 500;
+/**
+ * Reduce a thrown value to {@link DecisionErrorInfo}. Subclasses of `DecisionError` set their own
+ * `name`; a subclass that does not is named by its constructor rather than by `'Error'`.
+ */
+function toErrorInfo(error) {
+    if (!(error instanceof Error)) {
+        return { name: 'NonError', message: String(error).slice(0, DECISION_ERROR_MESSAGE_MAX) };
+    }
+    const named = error.name !== 'Error' ? error.name : (error.constructor?.name ?? error.name);
+    return { name: named, message: error.message.slice(0, DECISION_ERROR_MESSAGE_MAX) };
+}
+/**
+ * Normalize a {@link MakerRef} to an ordered chain. Empty and duplicate lists are caller errors
+ * here, not at load: the loader's schema already rejects them in a catalog.
+ */
+function toChain(ref) {
+    if (typeof ref === 'string')
+        return [ref];
+    if (ref.length === 0) {
+        throw new UnknownDecisionMakerError('A maker chain must name at least one maker', '');
+    }
+    const seen = new Set();
+    for (const name of ref) {
+        if (seen.has(name)) {
+            throw new UnknownDecisionMakerError(`Maker chain repeats '${name}'`, name);
+        }
+        seen.add(name);
+    }
+    return [...ref];
+}
 /** Effective confidence floor: decision → catalog defaults → package default. */
 function effectiveMinConfidence(definition, defaults) {
     return definition.minConfidence ?? defaults.minConfidence ?? DEFAULT_MIN_CONFIDENCE;
@@ -75,15 +107,19 @@ export class DecisionHub {
     }
     /**
      * Register every decision of an already-loaded catalog. All-or-nothing: a
-     * duplicate decision id or an unregistered maker name (decision or
-     * `defaults.maker`) throws {@link DecisionCatalogError} and registers
+     * duplicate decision id or an unregistered maker name (any chain name of a
+     * decision or `defaults.maker`, or a decision `shadow`) throws
+     * {@link DecisionCatalogError} and registers
      * nothing from the offending catalog.
      */
     load(catalog) {
         const defaultsMaker = catalog.defaults.maker;
-        if (defaultsMaker !== undefined && !this.registry.has(defaultsMaker)) {
-            throw new DecisionCatalogError(`Catalog "${catalog.source}" defaults.maker '${defaultsMaker}' is not registered in the hub registry ` +
-                `(registered: ${this.registry.names().join(', ') || 'none'})`, catalog.source, undefined, 'maker');
+        const defaultsChain = defaultsMaker === undefined ? undefined : toChain(defaultsMaker);
+        for (const name of defaultsChain ?? []) {
+            if (!this.registry.has(name)) {
+                throw new DecisionCatalogError(`Catalog "${catalog.source}" defaults.maker '${name}' is not registered in the hub registry ` +
+                    `(registered: ${this.registry.names().join(', ') || 'none'})`, catalog.source, undefined, 'maker');
+            }
         }
         // Stage first, commit only when every decision passed the cross-catalog checks.
         const staged = [];
@@ -93,9 +129,15 @@ export class DecisionHub {
                 throw new DecisionCatalogError(`Decision id "${id}" in catalog "${catalog.source}" duplicates the decision loaded from ` +
                     `"${existing.definition.source}"`, catalog.source, id, 'id');
             }
-            if (definition.maker !== undefined && !this.registry.has(definition.maker)) {
-                throw new DecisionCatalogError(`Decision "${id}" in catalog "${catalog.source}" names maker '${definition.maker}' that is not ` +
-                    `registered in the hub registry (registered: ${this.registry.names().join(', ') || 'none'})`, catalog.source, id, 'maker');
+            for (const name of definition.maker === undefined ? [] : toChain(definition.maker)) {
+                if (!this.registry.has(name)) {
+                    throw new DecisionCatalogError(`Decision "${id}" in catalog "${catalog.source}" names maker '${name}' that is not ` +
+                        `registered in the hub registry (registered: ${this.registry.names().join(', ') || 'none'})`, catalog.source, id, 'maker');
+                }
+            }
+            if (definition.shadow !== undefined && !this.registry.has(definition.shadow)) {
+                throw new DecisionCatalogError(`Decision "${id}" in catalog "${catalog.source}" names shadow '${definition.shadow}' that is not ` +
+                    `registered in the hub registry (registered: ${this.registry.names().join(', ') || 'none'})`, catalog.source, id, 'shadow');
             }
             staged.push({ definition, defaults: catalog.defaults });
         }
@@ -118,6 +160,7 @@ export class DecisionHub {
     /** Pure read of one decision's served contract; throws UnknownDecisionError for an unknown id. */
     describe(id) {
         const { definition, defaults } = this.mustGet(id);
+        const chain = this.effectiveChain(definition, defaults);
         const model = definition.model ?? defaults.model;
         return {
             id: definition.id,
@@ -128,15 +171,18 @@ export class DecisionHub {
             criteria: definition.criteria,
             fallback: definition.fallback,
             minConfidence: effectiveMinConfidence(definition, defaults),
-            maker: this.effectiveMakerName(definition, defaults),
+            maker: chain[0] ?? DEFAULT_MAKER,
+            makers: chain,
+            ...(definition.shadow !== undefined ? { shadow: definition.shadow } : {}),
             ...(model !== undefined ? { model } : {}),
         };
     }
     /**
      * Serve one decision with a fallback-guaranteed answer. Resolves the input,
      * renders exactly one Jev question keyed by the decision id, selects the
-     * maker by name (per call → decision → catalog defaults → hub default) and
-     * issues a single `maker.ask`. Backend construction, transport, timeout,
+     * maker chain (per call → decision → catalog defaults → hub default) and
+     * asks its makers in order until one answers, with an optional shadow asked
+     * beside it (ADR-040). Backend construction, transport, timeout,
      * invalid answers and low confidence all resolve to the declared fallback;
      * only caller mistakes throw, before any backend call.
      */
@@ -144,12 +190,20 @@ export class DecisionHub {
         const start = this.now();
         const { definition, defaults } = this.mustGet(id); // UnknownDecisionError — caller error
         const params = resolveDecisionInput(definition, input); // DecisionInputError — caller error
-        const makerName = options.maker ?? definition.maker ?? defaults.maker ?? this.defaultMaker;
-        if (!this.registry.has(makerName)) {
-            // Reachable only for a per-call name: catalog and hub default names are checked at
-            // load/construct. It is a caller error, thrown before any backend interaction.
-            throw new UnknownDecisionMakerError(`Decision "${id}" was asked on maker '${makerName}' that is not registered in the hub registry ` +
-                `(registered: ${this.registry.names().join(', ') || 'none'})`, makerName);
+        const chain = options.maker === undefined ? this.effectiveChain(definition, defaults) : toChain(options.maker);
+        for (const name of chain) {
+            // Reachable only for a per-call chain: catalog and hub default names are checked at
+            // load/construct. A caller error, thrown before any backend interaction.
+            if (!this.registry.has(name)) {
+                throw new UnknownDecisionMakerError(`Decision "${id}" was asked on maker '${name}' that is not registered in the hub registry ` +
+                    `(registered: ${this.registry.names().join(', ') || 'none'})`, name);
+            }
+        }
+        const shadowName = options.shadow ?? definition.shadow;
+        if (shadowName !== undefined && !this.registry.has(shadowName)) {
+            // Same caller-error rule as a per-call maker name: before any backend interaction.
+            throw new UnknownDecisionMakerError(`Decision "${id}" was asked with shadow '${shadowName}' that is not registered in the hub registry ` +
+                `(registered: ${this.registry.names().join(', ') || 'none'})`, shadowName);
         }
         const state = buildState(definition, params);
         const model = definition.model ?? defaults.model;
@@ -158,6 +212,75 @@ export class DecisionHub {
             questions: { [definition.id]: buildJevQuestion(renderQuestion(definition, params)) },
             ...(model !== undefined ? { model } : {}),
         };
+        // Shadow rule (ADR-040): start the shadow on the SAME request object, without awaiting it, so
+        // both paths run concurrently and latency is the slower of the two. It never rejects `decide`
+        // and never touches a served field — a rejected or failed ask maps to its own outcome.
+        const shadowStart = this.now();
+        const shadowTask = shadowName === undefined
+            ? undefined
+            : this.askOne(shadowName, definition, defaults, request, shadowStart).then((settled) => settled, (error) => ({
+                result: this.fallbackResult(definition, shadowName, 'error', null, shadowStart, undefined, toErrorInfo(error)),
+                failed: true,
+            }));
+        // Chain rule (ADR-040): ask makers in order and stop at the first that did not fail as a
+        // backend — `accepted` and `low-confidence` both answer. Every maker after the answering one
+        // stays unresolved, so its lazy factory never runs.
+        const attempts = [];
+        let last;
+        for (const makerName of chain) {
+            const attemptStart = this.now();
+            last = await this.askOne(makerName, definition, defaults, request, attemptStart);
+            attempts.push({
+                maker: makerName,
+                reason: last.result.reason,
+                durationMs: this.now() - attemptStart,
+                ...(last.result.error !== undefined ? { error: last.result.error } : {}),
+            });
+            if (!last.failed)
+                break;
+        }
+        // `toChain` rejects an empty list, so the loop always ran at least once.
+        const final = last?.result;
+        if (final === undefined) {
+            throw new UnknownDecisionMakerError(`Decision "${id}" has no maker to ask`, id);
+        }
+        // `durationMs` covers the whole call, shadow wait included; a single-maker call without a
+        // shadow keeps its exact previous shape.
+        const shadowOutcome = shadowTask === undefined ? undefined : this.toShadowOutcome(await shadowTask);
+        return {
+            ...final,
+            durationMs: this.now() - start,
+            ...(attempts.length > 1 ? { attempts } : {}),
+            ...(shadowOutcome !== undefined ? { shadow: shadowOutcome } : {}),
+        };
+    }
+    /**
+     * Project a shadow's own result onto {@link ShadowOutcome}. `value` is carried only when the shadow
+     * actually answered — a served-model answer or a low-confidence one — never its declared fallback.
+     */
+    toShadowOutcome(outcome) {
+        const { result } = outcome;
+        const answered = result.source === 'model' || result.reason === 'low-confidence';
+        return {
+            maker: result.maker,
+            ...(answered && outcome.answered !== undefined ? { value: outcome.answered } : {}),
+            confidence: result.confidence,
+            reason: result.reason,
+            durationMs: result.durationMs,
+            ...(result.error !== undefined ? { error: result.error } : {}),
+        };
+    }
+    /**
+     * Ask one maker and classify its outcome. `failed` is true exactly for `no-backend`, `timeout`
+     * and `error` — the reasons a chain advances past (ADR-040); `accepted` and `low-confidence`
+     * answer, so the chain stops there.
+     */
+    async askOne(makerName, definition, defaults, request, start) {
+        const outcome = (result, answered) => ({
+            result,
+            failed: result.reason === 'no-backend' || result.reason === 'timeout' || result.reason === 'error',
+            ...(answered !== undefined ? { answered } : {}),
+        });
         // The one auditable try/catch for steps 4–5: a resolve failure is a construction
         // failure (no-backend); ask failures map per the error taxonomy. Neither rejects.
         let inAsk = false;
@@ -171,11 +294,21 @@ export class DecisionHub {
             validateAnswers(request.questions, answers);
             const answer = answers[definition.id];
             if (answer === undefined || answer.kind !== definition.type) {
-                return this.fallbackResult(definition, makerName, 'error', null, start);
+                // Nothing was thrown here, so the failure is synthesized: every `error` reason
+                // must carry a cause a consumer can log (ADR-040).
+                return outcome(this.fallbackResult(definition, makerName, 'error', null, start, undefined, {
+                    name: 'DecisionBackendError',
+                    message: `Maker returned no answer of type ${definition.type} for "${definition.id}"`,
+                }));
             }
             const observed = observedAnswer(answer);
+            const answered = answer.kind === 'choice'
+                ? answer.label
+                : answer.kind === 'score'
+                    ? answer.score
+                    : answer.probability >= 0.5;
             if (observed.confidence < effectiveMinConfidence(definition, defaults)) {
-                return this.fallbackResult(definition, makerName, 'low-confidence', observed.confidence, start, observed.probability);
+                return outcome(this.fallbackResult(definition, makerName, 'low-confidence', observed.confidence, start, observed.probability), answered);
             }
             const base = {
                 id: definition.id,
@@ -187,16 +320,16 @@ export class DecisionHub {
             };
             switch (answer.kind) {
                 case 'choice':
-                    return { ...base, type: 'choice', value: answer.label };
+                    return outcome({ ...base, type: 'choice', value: answer.label }, answered);
                 case 'score':
-                    return { ...base, type: 'score', value: answer.score };
+                    return outcome({ ...base, type: 'score', value: answer.score }, answered);
                 case 'noul':
-                    return {
+                    return outcome({
                         ...base,
                         type: 'noul',
                         value: answer.probability >= 0.5,
                         probability: answer.probability,
-                    };
+                    }, answered);
             }
         }
         catch (error) {
@@ -205,12 +338,13 @@ export class DecisionHub {
                 : error instanceof DecisionTimeoutError
                     ? 'timeout'
                     : 'error';
-            return this.fallbackResult(definition, makerName, reason, null, start);
+            return outcome(this.fallbackResult(definition, makerName, reason, null, start, undefined, toErrorInfo(error)));
         }
     }
-    /** Maker-name precedence for discovery results: decision → catalog defaults → hub default. */
-    effectiveMakerName(definition, defaults) {
-        return definition.maker ?? defaults.maker ?? this.defaultMaker;
+    /** Maker-chain precedence for discovery results: decision → catalog defaults → hub default. */
+    effectiveChain(definition, defaults) {
+        const ref = definition.maker ?? defaults.maker;
+        return ref === undefined ? [this.defaultMaker] : toChain(ref);
     }
     mustGet(id) {
         const registered = this.decisions.get(id);
@@ -225,7 +359,7 @@ export class DecisionHub {
      * confidence (null when none), always the selected maker name. For noul,
      * `probability` stays null unless the answer itself supplied one.
      */
-    fallbackResult(definition, makerName, reason, confidence, start, probability) {
+    fallbackResult(definition, makerName, reason, confidence, start, probability, error) {
         const base = {
             id: definition.id,
             confidence,
@@ -233,6 +367,7 @@ export class DecisionHub {
             reason,
             maker: makerName,
             durationMs: this.now() - start,
+            ...(error !== undefined ? { error } : {}),
         };
         switch (definition.type) {
             case 'choice':

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './agent-driver';
 export * from './catalog';
 export * from './errors';
 export * from './hub';
@@ -5,4 +6,5 @@ export * from './params';
 export * from './registry';
 export * from './schema';
 export * from './types';
+export * from './typesafe-driver';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
+export * from './agent-driver.js';
 export * from './catalog.js';
 export * from './errors.js';
 export * from './hub.js';
@@ -5,3 +6,4 @@ export * from './params.js';
 export * from './registry.js';
 export * from './schema.js';
 export * from './types.js';
+export * from './typesafe-driver.js';

package/dist/registry.d.ts

@@ -1,16 +1,53 @@
-import { type DecisionMaker, type DecisionMakerOptions } from '@gobing-ai/ts-ai-runner';
+import { type DecisionDriver, type DecisionMaker, type DecisionMakerOptions } from '@gobing-ai/ts-ai-runner';
 import { type FmDriverOptions } from '@gobing-ai/ts-decision-fm';
-import { type LayaDriverOptions } from '@gobing-ai/ts-laya-mlx';
+import { type AgentDriverOptions } from './agent-driver';
+/**
+ * Options forwarded to `createLayaDriver`. Same fields as `LayaDriverOptions` in
+ * `@gobing-ai/ts-laya-mlx`. Declared here so published `.d.ts` files do not import
+ * that package: it is an optional, macOS-only dependency (ADR-041) and is absent
+ * on other platforms.
+ */
+export interface LayaLocalDriverOptions {
+    pythonPath?: string;
+    module?: string;
+    workerScript?: string;
+    cwd?: string;
+    modelId?: string;
+    modelPath?: string;
+    revision?: string;
+    cacheDir?: string;
+    dtype?: 'float32' | 'float16' | 'bfloat16';
+    batchSize?: number;
+    startupTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    env?: Record<string, string | undefined>;
+    platform?: string;
+    arch?: string;
+    core?: 'mlx-python' | 'mlx-native' | 'auto';
+    /** Same role as `LayaDriverOptions.client`. Typed wide so the optional module's class stays assignable. */
+    client?: unknown;
+    /** Same role as `LayaDriverOptions.nativeLoader`. */
+    nativeLoader?: unknown;
+}
+/**
+ * Load the bundled Laya driver. The package is an `optionalDependency` with
+ * `"os": ["darwin"]`, so non-macOS installs do not contain it. Only the import
+ * failure is rewritten; factory errors propagate unchanged.
+ *
+ * @internal Tests pass `load` because a workspace link always resolves.
+ */
+export declare function resolveBundledLayaDriver(options?: LayaLocalDriverOptions, load?: () => Promise<unknown>): Promise<DecisionDriver>;
 /** A maker, or a lazy factory for one (sync or async). Factories run on first `resolve` and are memoised on success. */
 export type MakerSource = DecisionMaker | (() => DecisionMaker | Promise<DecisionMaker>);
-/** Options for the three built-in makers pre-registered by {@link DecisionMakerRegistry} (task 0091 R2). */
+/** Options for the four built-in makers pre-registered by {@link DecisionMakerRegistry} (task 0091 R2, task 0115 R8). */
 export interface BuiltinMakerOptions {
     /** Forwarded to `createDecisionMaker` for every built-in (env, apiKey, baseURL, timeoutMs, ...). */
     readonly makerOptions?: Omit<DecisionMakerOptions, 'driver' | 'backend' | 'model'>;
-    /** Driver options for the bundled local drivers; the fm platform check runs at first resolve, not registration. */
+    /** Driver options for the bundled drivers; the fm platform check runs at first resolve, not registration. */
     readonly driverOptions?: {
         readonly 'fm-local'?: FmDriverOptions;
-        readonly 'laya-local'?: LayaDriverOptions;
+        readonly 'laya-local'?: LayaLocalDriverOptions;
+        readonly 'llm-agent'?: AgentDriverOptions;
     };
 }
 /**
@@ -24,7 +61,7 @@ export interface BuiltinMakerOptions {
  */
 export declare class DecisionMakerRegistry {
     private readonly entries;
-    /** Pre-registers `typesafe`, `fm-local` and `laya-local` unless `builtins: false`. */
+    /** Pre-registers `typesafe`, `fm-local`, `laya-local` and `llm-agent` unless `builtins: false`. */
     constructor(options?: {
         builtins?: BuiltinMakerOptions | false;
     });

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC7G,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGlF,wHAAwH;AACxH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;AAEzF,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;IACnF,mHAAmH;IACnH,QAAQ,CAAC,aAAa,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAA;KAAE,CAAC;CACjH;AAID;;;;;;;;GAQG;AACH,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IAEJ,sFAAsF;gBAC1E,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;KAAE;IAqBhE,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAWjD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,KAAK,IAAI,MAAM,EAAE;IAIjB;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BnD;;;;;OAKG;IACG,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAc9C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAE5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,EAAE,KAAK,kBAAkB,EAAqB,MAAM,gBAAgB,CAAC;AAI5E;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,MAAM,CAAC;IAC5C,2GAA2G;IAC3G,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,YAAY,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC1C,OAAO,GAAE,sBAA2B,EACpC,IAAI,GAAE,MAAM,OAAO,CAAC,OAAO,CAA0C,GACtE,OAAO,CAAC,cAAc,CAAC,CAmBzB;AAED,wHAAwH;AACxH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;AAEzF,yHAAyH;AACzH,MAAM,WAAW,mBAAmB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;IACnF,6GAA6G;IAC7G,QAAQ,CAAC,aAAa,CAAC,EAAE;QACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;QACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,sBAAsB,CAAC;QAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;KAC7C,CAAC;CACL;AAID;;;;;;;;GAQG;AACH,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IAEJ,mGAAmG;gBACvF,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAA;KAAE;IAgDhE,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAWjD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,KAAK,IAAI,MAAM,EAAE;IAIjB;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BnD;;;;;OAKG;IACG,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAc9C"}

package/dist/registry.js

@@ -1,7 +1,30 @@
-import { createDecisionMaker } from '@gobing-ai/ts-ai-runner';
+import { createDecisionMaker, DecisionConfigError, resolveApiKey, } from '@gobing-ai/ts-ai-runner';
 import { createFmDriver } from '@gobing-ai/ts-decision-fm';
-import { createLayaDriver } from '@gobing-ai/ts-laya-mlx';
+import { createAgentDriver } from './agent-driver.js';
 import { DecisionRegistryError, UnknownDecisionMakerError } from './errors.js';
+import { createTypesafeDriver } from './typesafe-driver.js';
+const LAYA_DRIVER_PACKAGE = '@gobing-ai/ts-laya-mlx';
+/**
+ * Load the bundled Laya driver. The package is an `optionalDependency` with
+ * `"os": ["darwin"]`, so non-macOS installs do not contain it. Only the import
+ * failure is rewritten; factory errors propagate unchanged.
+ *
+ * @internal Tests pass `load` because a workspace link always resolves.
+ */
+export async function resolveBundledLayaDriver(options = {}, load = () => import('@gobing-ai/ts-laya-mlx')) {
+    let loaded;
+    try {
+        loaded = await load();
+    }
+    catch (cause) {
+        throw new DecisionConfigError(`The 'laya-local' maker requires '${LAYA_DRIVER_PACKAGE}', an optional dependency installed only on macOS. On macOS, install it with 'bun add ${LAYA_DRIVER_PACKAGE}'.`, 'LAYA_BACKEND', { cause });
+    }
+    const record = loaded !== null && typeof loaded === 'object' ? loaded : {};
+    if (typeof record.createLayaDriver !== 'function') {
+        throw new DecisionConfigError(`Module '${LAYA_DRIVER_PACKAGE}' does not export createLayaDriver`, 'LAYA_BACKEND');
+    }
+    return record.createLayaDriver(options);
+}
 const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 /**
  * Registry mapping plain names to {@link DecisionMaker}s (task 0091, ADR-033
@@ -14,14 +37,34 @@ const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
  */
 export class DecisionMakerRegistry {
     entries = new Map();
-    /** Pre-registers `typesafe`, `fm-local` and `laya-local` unless `builtins: false`. */
+    /** Pre-registers `typesafe`, `fm-local`, `laya-local` and `llm-agent` unless `builtins: false`. */
     constructor(options) {
         if (options?.builtins === false)
             return;
         const { makerOptions = {}, driverOptions = {} } = options?.builtins ?? {};
-        this.register('typesafe', () => createDecisionMaker({ backend: 'typesafe', ...makerOptions }));
+        // The driver lives here now (ADR-039), so the built-in no longer routes through the
+        // deprecated dynamic-import bridge. A missing key still throws inside this lazy factory,
+        // before any request, so the hub keeps reporting `reason: 'no-backend'`.
+        //
+        // `Omit<>` over an index-signature option bag collapses every declared field to `unknown`,
+        // so the bag is read back through its own type here — same object, same runtime values.
+        const transportOptions = makerOptions;
+        this.register('typesafe', () => createDecisionMaker({
+            driver: createTypesafeDriver({
+                apiKey: resolveApiKey(transportOptions),
+                baseURL: transportOptions.baseURL,
+                timeoutMs: transportOptions.timeoutMs,
+                maxRetries: transportOptions.maxRetries,
+                fetch: transportOptions.fetch,
+            }),
+            ...makerOptions,
+        }));
         this.register('fm-local', () => createDecisionMaker({ driver: createFmDriver(driverOptions['fm-local'] ?? {}), ...makerOptions }));
-        this.register('laya-local', () => {
+        // Dynamic import: a top-level import would throw on hosts where the
+        // optional macOS package was not installed, and the rest of the hub
+        // would fail to load. A missing module becomes LAYA_BACKEND, which
+        // DecisionHub maps to reason 'no-backend'.
+        this.register('laya-local', async () => {
             const driverOpts = {
                 ...driverOptions['laya-local'],
             };
@@ -29,10 +72,13 @@ export class DecisionMakerRegistry {
                 driverOpts.env = makerOptions.env;
             }
             return createDecisionMaker({
-                driver: createLayaDriver(driverOpts),
+                driver: await resolveBundledLayaDriver(driverOpts),
                 ...makerOptions,
             });
         });
+        // Lazy like the rest: `names()`/`has()` construct nothing, and agent detection
+        // runs inside the first `ask`, so an unavailable agent surfaces as a fallback.
+        this.register('llm-agent', () => createDecisionMaker({ driver: createAgentDriver(driverOptions['llm-agent'] ?? {}), ...makerOptions }));
     }
     /** Register a maker or factory under `name`; chains. Throws on a bad or already-registered name. */
     register(name, source) {

package/dist/schema.d.ts

@@ -18,8 +18,8 @@ declare const FullParamSchema: z.ZodObject<{
         string: "string";
         number: "number";
         boolean: "boolean";
-        enum: "enum";
         json: "json";
+        enum: "enum";
     }>;
     default: z.ZodOptional<z.ZodUnknown>;
     values: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -30,15 +30,15 @@ export declare const ParamSchema: z.ZodUnion<readonly [z.ZodEnum<{
     string: "string";
     number: "number";
     boolean: "boolean";
-    enum: "enum";
     json: "json";
+    enum: "enum";
 }>, z.ZodObject<{
     type: z.ZodEnum<{
         string: "string";
         number: "number";
         boolean: "boolean";
-        enum: "enum";
         json: "json";
+        enum: "enum";
     }>;
     default: z.ZodOptional<z.ZodUnknown>;
     values: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -57,15 +57,15 @@ export declare const DecisionSchema: z.ZodObject<{
         string: "string";
         number: "number";
         boolean: "boolean";
-        enum: "enum";
         json: "json";
+        enum: "enum";
     }>, z.ZodObject<{
         type: z.ZodEnum<{
             string: "string";
             number: "number";
             boolean: "boolean";
-            enum: "enum";
             json: "json";
+            enum: "enum";
         }>;
         default: z.ZodOptional<z.ZodUnknown>;
         values: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -77,7 +77,8 @@ export declare const DecisionSchema: z.ZodObject<{
     }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodType<Desc, unknown, z.core.$ZodTypeInternals<Desc, unknown>>>, z.ZodArray<z.ZodType<Desc, unknown, z.core.$ZodTypeInternals<Desc, unknown>>>]>>;
     fallback: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
     minConfidence: z.ZodOptional<z.ZodNumber>;
-    maker: z.ZodOptional<z.ZodString>;
+    maker: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    shadow: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** Whole-catalog schema (strict; `version` must be 1 and at least one decision is required). */
@@ -85,7 +86,7 @@ export declare const DecisionCatalogSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     version: z.ZodLiteral<1>;
     defaults: z.ZodOptional<z.ZodObject<{
-        maker: z.ZodOptional<z.ZodString>;
+        maker: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
         model: z.ZodOptional<z.ZodString>;
         minConfidence: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
@@ -101,15 +102,15 @@ export declare const DecisionCatalogSchema: z.ZodObject<{
             string: "string";
             number: "number";
             boolean: "boolean";
-            enum: "enum";
             json: "json";
+            enum: "enum";
         }>, z.ZodObject<{
             type: z.ZodEnum<{
                 string: "string";
                 number: "number";
                 boolean: "boolean";
-                enum: "enum";
                 json: "json";
+                enum: "enum";
             }>;
             default: z.ZodOptional<z.ZodUnknown>;
             values: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -121,7 +122,8 @@ export declare const DecisionCatalogSchema: z.ZodObject<{
         }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodType<Desc, unknown, z.core.$ZodTypeInternals<Desc, unknown>>>, z.ZodArray<z.ZodType<Desc, unknown, z.core.$ZodTypeInternals<Desc, unknown>>>]>>;
         fallback: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
         minConfidence: z.ZodOptional<z.ZodNumber>;
-        maker: z.ZodOptional<z.ZodString>;
+        maker: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        shadow: z.ZodOptional<z.ZodString>;
         model: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAQ,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,eAAO,MAAM,mBAAmB,QAAuB,CAAC;AACxD,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,QAAyB,CAAC;AACzD,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAoBtD,qFAAqF;AACrF,QAAA,MAAM,eAAe;;;;;;;;;;;kBAOR,CAAC;AAEd,kFAAkF;AAClF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;oBAA8C,CAAC;AAMvE,wGAAwG;AACxG,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYd,CAAC;AAEd,gGAAgG;AAChG,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiB5B,CAAC;AAEP,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAClE,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAQ,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AAEH,eAAO,MAAM,mBAAmB,QAAuB,CAAC;AACxD,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,QAAyB,CAAC;AACzD,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAsCtD,qFAAqF;AACrF,QAAA,MAAM,eAAe;;;;;;;;;;;kBAOR,CAAC;AAEd,kFAAkF;AAClF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;oBAA8C,CAAC;AAMvE,wGAAwG;AACxG,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAad,CAAC;AAEd,gGAAgG;AAChG,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiB5B,CAAC;AAEP,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAClE,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/schema.js

@@ -11,6 +11,23 @@ export const DECISION_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
 export const PARAM_NAME_PATTERN = /^[a-z][a-zA-Z0-9_]*$/;
 /** Maker registry names: lowercase kebab-case. */
 export const MAKER_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** One maker name, or an ordered fallback chain of distinct names (ADR-040). */
+const MakerRefSchema = z.union([
+    z.string().regex(MAKER_NAME_PATTERN),
+    z
+        .array(z.string().regex(MAKER_NAME_PATTERN))
+        .min(1)
+        .superRefine((names, ctx) => {
+        const seen = new Set();
+        for (const name of names) {
+            if (seen.has(name)) {
+                ctx.addIssue({ code: 'custom', message: `maker list repeats '${name}'` });
+                return;
+            }
+            seen.add(name);
+        }
+    }),
+]);
 const JsonValueSchema = z.lazy(() => z.union([
     z.string(),
     z.number(),
@@ -46,7 +63,8 @@ export const DecisionSchema = z
     criteria: z.union([NoulCriteriaSchema, ChoiceCriteriaSchema, ScoreCriteriaSchema]).optional(),
     fallback: z.union([z.string(), z.number(), z.boolean()]),
     minConfidence: z.number().min(0).max(1).optional(),
-    maker: z.string().regex(MAKER_NAME_PATTERN).optional(),
+    maker: MakerRefSchema.optional(),
+    shadow: z.string().regex(MAKER_NAME_PATTERN).optional(),
     model: z.string().optional(),
 })
     .strict();
@@ -57,7 +75,7 @@ export const DecisionCatalogSchema = z
     version: z.literal(1),
     defaults: z
         .object({
-        maker: z.string().regex(MAKER_NAME_PATTERN).optional(),
+        maker: MakerRefSchema.optional(),
         model: z.string().optional(),
         minConfidence: z.number().min(0).max(1).optional(),
     })