@gobing-ai/ts-ai-runner 0.4.69 → 0.5.1

package/README.md

@@ -32,6 +32,7 @@ bun add @gobing-ai/ts-ai-runner
 | `AgentEvents` / `AiRunnerProcessEvents` | Typed event maps for agent and process-level observability |
 | `AGENT_SHIMS` / `TIER1_PRIORITY` / `TIER2_AGENTS` / `DISPLAY_ORDER` | Agent registry constants |
 | `isAgentName()` | Type guard for supported agent identifiers |
+| `createDecisionMaker()` / `q` | Batch `ask` and single-question `choice`/`score`/`noul` decisions with provider-neutral question/answer types and a `DecisionError` taxonomy |
 
 Supported agent identifiers: `claude`, `codex`, `gemini` (deprecated), `pi`, `omp`, `opencode`, `antigravity-cli`, `openclaw`, `hermes`, `grok`, `deepseek`. The `antigravity` id is a deprecated alias of `antigravity-cli`. See [Deprecation & Aliases](#deprecation--aliases).
 
@@ -730,6 +731,119 @@ If the agent supports an auth-status command, `getAuthCommand()` already returns
 
 After these changes, the new agent is automatically available to `AiRunner`, `AgentDetector`, `DoctorRunner`, `TeamOrchestrator`, and all downstream consumers — no further registration needed.
 
+## Decision Making
+
+`createDecisionMaker()` exposes a provider-neutral LLM decision surface: ask N questions against one
+shared state and get typed, discriminated answers back. Questions are built with the `q` builders;
+answers are decoded into neutral `ChoiceAnswer` / `ScoreAnswer` / `NoulAnswer` types — no SDK type
+crosses this boundary.
+
+### Batch `ask` — many questions, one request
+
+All questions in one `ask` call share the state and cost a single backend request:
+
+```ts
+import { createDecisionMaker, q } from '@gobing-ai/ts-ai-runner';
+
+const decisions = createDecisionMaker(); // reads TYPESAFE_API_KEY from the environment
+const state = { ticket: 'T-1042', body: 'Users cannot reset their passwords.' };
+
+const answers = await decisions.ask({
+    state,
+    questions: {
+        route: q.choice('Which team should own this?', {
+            billing: 'Invoices and payment issues',
+            access: 'Login and account access',
+            other: 'Anything else',
+        }),
+        urgency: q.score('How urgent is this?', ['Routine', 'Elevated', 'Drop everything']),
+        duplicate: q.noul('Has this ticket been reported before?'),
+    },
+});
+
+answers.route.label; // 'billing' | 'access' | 'other'
+answers.urgency.score; // rubric level
+answers.duplicate.probability; // yes-probability
+```
+
+### Single-question sugar
+
+`choice`, `score`, and `noul` are one-question convenience forms over `ask`:
+
+```ts
+const route = await decisions.choice(state, 'Which team should own this?', {
+    billing: 'Invoices and payment issues',
+    access: 'Login and account access',
+});
+route.label; // 'billing' | 'access'
+
+const duplicate = await decisions.noul(state, 'Has this ticket been reported before?');
+duplicate.probability; // yes-probability — no `confidence` field: the API reports none for yes/no
+```
+
+A yes/no answer carries only `probability`. The API returns no calibration confidence for noul
+questions, so none is synthesized.
+
+### Configuration
+
+The API key resolves as `options.apiKey`, else `TYPESAFE_API_KEY` from the injected `env` record,
+else from the process environment. A missing key throws `DecisionConfigError` before any request:
+
+```ts
+const key = 'sk-…'; // from your secret store
+const explicit = createDecisionMaker({ apiKey: key }); // explicit key wins
+const sandboxed = createDecisionMaker({ env: { TYPESAFE_API_KEY: key } }); // injected record — the host owns the environment
+```
+
+Other options: `model`, `baseURL`, `timeoutMs`, `maxRetries`, and an injected `fetch` for tests. When
+`baseURL` is omitted the SDK resolves `TYPESAFE_BASE_URL` from the environment itself — pass `baseURL`
+explicitly to pin the endpoint.
+
+### Errors
+
+SDK failures and malformed questions/responses surface as `DecisionError` subclasses. Custom
+drivers' own exceptions propagate; no vendor SDK error class escapes the default driver:
+
+| Error | When | Carries |
+| ----- | ------- | ------- |
+| `DecisionConfigError` | No API key resolved | variable name |
+| `DecisionAuthError` | Authentication or permission rejected upstream | HTTP status |
+| `DecisionRateLimitError` | Rate limited upstream | status, `retryAfterMs` |
+| `DecisionTimeoutError` | Request timed out | `timeoutMs` |
+| `DecisionConnectionError` | Backend unreachable | underlying cause |
+| `DecisionRequestError` | Invalid question or request rejected as malformed (other 4xx) | status, body summary |
+| `DecisionBackendError` | Invalid answer or upstream server failure (5xx) | HTTP status when present |
+
+The facade validates both default and custom drivers: answer names/kinds must match the questions,
+choice labels must belong to the supplied label map, probability/confidence values must be finite
+and within `[0, 1]`, and score values must fit the zero-indexed rubric (fractional expected scores
+are supported). Missing probability/legend keys are rejected. These checks establish structural
+validity, not calibration or decision quality.
+
+Applications own decision policy and evidence selection. For example, Spur can adapt its existing
+`HitlResponder` to use DecisionMaker while retaining its own HITL actions and fallback behavior;
+the workflow engine itself has no dependency on ai-runner.
+
+### Adding a backend driver
+
+Additional backend drivers are the intended extension point. A driver implements only `ask` —
+question building, the single-question sugar, and answer typing all come from the facade:
+
+```ts
+import type { Answer, DecisionDriver } from '@gobing-ai/ts-ai-runner';
+
+const myDriver: DecisionDriver = {
+    name: 'my-backend',
+    async ask() {
+        const answers: Record<string, Answer> = {};
+        // Call your backend; return one answer per key in the question map.
+        return answers;
+    },
+};
+
+const custom = createDecisionMaker({ driver: myDriver }); // no TYPESAFE_API_KEY required
+```
+
 ## Boundary Notes
 
 - This package is a command adapter, not an agent orchestration framework.

package/dist/decision/decision-maker.d.ts

@@ -0,0 +1,45 @@
+import type { AnswersFor, ChoiceAnswer, DecisionDriver, DecisionState, Desc, NoulAnswer, Question, ScoreAnswer } from './types';
+/** Public decision surface: batch `ask` plus the three single-question sugar methods. */
+export interface DecisionMaker {
+    /** Name of the backing driver (e.g. `"typesafe"`, or a custom driver's name). */
+    readonly driver: string;
+    /** Evaluate N named questions against one shared state in a single driver request. */
+    ask<const Q extends Record<string, Question>>(req: {
+        state: DecisionState;
+        questions: Q;
+        model?: string;
+    }): Promise<AnswersFor<Q>>;
+    /** Pick one label. Sugar over `ask` with exactly one choice question. */
+    choice<const L extends string>(state: DecisionState, prompt: Desc, labels: Record<L, Desc>): Promise<ChoiceAnswer<L>>;
+    /** Score against a rubric. Sugar over `ask` with exactly one score question. */
+    score(state: DecisionState, prompt: Desc, rubric: readonly [Desc, Desc, ...Desc[]]): Promise<ScoreAnswer>;
+    /** Yes/no judgment. Sugar over `ask` with exactly one noul question. */
+    noul(state: DecisionState, prompt?: Desc, outcomes?: {
+        yes?: Desc;
+        no?: Desc;
+    }): Promise<NoulAnswer>;
+}
+/** Factory options: driver selection, credential injection, and transport tuning. */
+export interface DecisionMakerOptions {
+    /** Custom driver — when supplied, the default TypeSafe driver is never constructed and no key is required. */
+    driver?: DecisionDriver;
+    /** Injected env record; defaults to `getProcessEnv()` (doctor-runner convention). */
+    env?: Record<string, string | undefined>;
+    /** Explicit key — wins over `env.TYPESAFE_API_KEY`. */
+    apiKey?: string;
+    /** Forwarded to the TypeSafe driver; default is the SDK's model default. */
+    model?: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Injected fetch for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * Build a DecisionMaker. `options.driver` wins when supplied; otherwise the
+ * TypeSafe driver is constructed lazily on first use, after key resolution —
+ * so a custom driver never requires a key and a missing key fails before any
+ * request (R6/R7).
+ */
+export declare function createDecisionMaker(options?: DecisionMakerOptions): DecisionMaker;
+//# sourceMappingURL=decision-maker.d.ts.map

package/dist/decision/decision-maker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-maker.d.ts","sourceRoot":"","sources":["../../src/decision/decision-maker.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACR,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,WAAW,EACd,MAAM,SAAS,CAAC;AAKjB,yFAAyF;AACzF,MAAM,WAAW,aAAa;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE;QAC/C,KAAK,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,CAAC,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,yEAAyE;IACzE,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EACzB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,IAAI,EACZ,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,GACxB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,gFAAgF;IAChF,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1G,wEAAwE;IACxE,IAAI,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,IAAI,CAAC;QAAC,EAAE,CAAC,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACxG;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACjC,8GAA8G;IAC9G,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB;AAkBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CA6CrF"}

package/dist/decision/decision-maker.js

@@ -0,0 +1,67 @@
+/**
+ * The public decision surface — the only type callers see. `choice`, `score`,
+ * and `noul` are implemented once, here, as `ask()` with a single-entry
+ * question map; drivers implement `ask` and nothing else, so the sugar can
+ * never drift from the batch path. This file imports no SDK (R9).
+ */
+import { getProcessEnv } from '@gobing-ai/ts-runtime';
+import { DecisionConfigError } from './errors.js';
+import { q } from './types.js';
+import { createTypesafeDriver } from './typesafe-driver.js';
+import { validateAnswers, validateQuestions } from './validation.js';
+/**
+ * Resolve the key per R7: `options.apiKey ?? (options.env ?? getProcessEnv()).TYPESAFE_API_KEY`.
+ * Throws before any driver construction or request.
+ */
+function resolveApiKey(options) {
+    const env = options.env ?? getProcessEnv();
+    const apiKey = options.apiKey ?? env.TYPESAFE_API_KEY;
+    if (!apiKey) {
+        throw new DecisionConfigError('Missing TYPESAFE_API_KEY — set it in the environment or pass options.apiKey.', 'TYPESAFE_API_KEY');
+    }
+    return apiKey;
+}
+/**
+ * Build a DecisionMaker. `options.driver` wins when supplied; otherwise the
+ * TypeSafe driver is constructed lazily on first use, after key resolution —
+ * so a custom driver never requires a key and a missing key fails before any
+ * request (R6/R7).
+ */
+export function createDecisionMaker(options = {}) {
+    // Lazy driver slot: resolved on first use, at most once. A caller-supplied
+    // driver never reaches key resolution or default-driver construction (R6).
+    let defaultDriver;
+    const resolveDriver = () => {
+        if (options.driver)
+            return options.driver;
+        defaultDriver ??= createTypesafeDriver({
+            apiKey: resolveApiKey(options),
+            model: options.model,
+            baseURL: options.baseURL,
+            timeoutMs: options.timeoutMs,
+            maxRetries: options.maxRetries,
+            fetch: options.fetch,
+        });
+        return defaultDriver;
+    };
+    const ask = async (req) => {
+        // R3: the questions map reaches the driver untouched — same reference,
+        // no reordering, renaming, or dropping.
+        const driver = resolveDriver();
+        validateQuestions(req.questions);
+        const answers = await driver.ask(req);
+        validateAnswers(req.questions, answers);
+        // Runtime validation above establishes each question/answer correspondence.
+        return answers;
+    };
+    return {
+        driver: options.driver?.name ?? 'typesafe',
+        ask,
+        // R4/R5: each sugar method is one `ask` with exactly one `q.*` question,
+        // unwrapping the single answer — no second driver call, no duplicated
+        // request assembly.
+        choice: (state, prompt, labels) => ask({ state, questions: { question: q.choice(prompt, labels) } }).then((a) => a.question),
+        score: (state, prompt, rubric) => ask({ state, questions: { question: q.score(prompt, rubric) } }).then((a) => a.question),
+        noul: (state, prompt, outcomes) => ask({ state, questions: { question: q.noul(prompt, outcomes) } }).then((a) => a.question),
+    };
+}

package/dist/decision/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `DecisionError` taxonomy. Both the facade and the driver throw from this set;
+ * no raw SDK error class escapes the package. Keeping every class in one file
+ * makes that invariant checkable by reading a single file.
+ */
+/** Base class for every decision-surface error. */
+export declare class DecisionError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Missing configuration — e.g. no `TYPESAFE_API_KEY` in the injected env. Carries the variable name. */
+export declare class DecisionConfigError extends DecisionError {
+    readonly variable: string;
+    constructor(message: string, variable: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Authentication or permission failure upstream. Carries the HTTP status. */
+export declare class DecisionAuthError extends DecisionError {
+    readonly status: number | undefined;
+    constructor(message: string, status: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Rate limited upstream. Carries the status and the parsed retry-after hint. */
+export declare class DecisionRateLimitError extends DecisionError {
+    readonly status: number | undefined;
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, status: number | undefined, retryAfterMs: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Request timed out. Carries the configured timeout in milliseconds. */
+export declare class DecisionTimeoutError extends DecisionError {
+    readonly timeoutMs: number | undefined;
+    constructor(message: string, timeoutMs: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** The backend was unreachable. Carries the underlying cause. */
+export declare class DecisionConnectionError extends DecisionError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The request was rejected as malformed (4xx other than auth/rate-limit). Carries status and a body summary. */
+export declare class DecisionRequestError extends DecisionError {
+    readonly status: number | undefined;
+    readonly bodySummary: string | undefined;
+    constructor(message: string, status: number | undefined, bodySummary: string | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Upstream server failure (5xx). Carries the HTTP status. */
+export declare class DecisionBackendError extends DecisionError {
+    readonly status: number | undefined;
+    constructor(message: string, status: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/decision/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/decision/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mDAAmD;AACnD,qBAAa,aAAc,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI7D;AAED,yGAAyG;AACzG,qBAAa,mBAAoB,SAAQ,aAAa;IAG9C,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBADzB,OAAO,EAAE,MAAM,EACN,QAAQ,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpC;AAED,8EAA8E;AAC9E,qBAAa,iBAAkB,SAAQ,aAAa;IAG5C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;gBADnC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,GAAG,SAAS,EACnC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpC;AAED,iFAAiF;AACjF,qBAAa,sBAAuB,SAAQ,aAAa;IAGjD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS;gBAFzC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,EACzC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpC;AAED,yEAAyE;AACzE,qBAAa,oBAAqB,SAAQ,aAAa;IAG/C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;gBADtC,OAAO,EAAE,MAAM,EACN,SAAS,EAAE,MAAM,GAAG,SAAS,EACtC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpC;AAED,iEAAiE;AACjE,qBAAa,uBAAwB,SAAQ,aAAa;gBAC1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAG7D;AAED,iHAAiH;AACjH,qBAAa,oBAAqB,SAAQ,aAAa;IAG/C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS;gBAFxC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,WAAW,EAAE,MAAM,GAAG,SAAS,EACxC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpC;AAED,8DAA8D;AAC9D,qBAAa,oBAAqB,SAAQ,aAAa;IAG/C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS;gBADnC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,GAAG,SAAS,EACnC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIpC"}

package/dist/decision/errors.js

@@ -0,0 +1,70 @@
+/**
+ * `DecisionError` taxonomy. Both the facade and the driver throw from this set;
+ * no raw SDK error class escapes the package. Keeping every class in one file
+ * makes that invariant checkable by reading a single file.
+ */
+/** Base class for every decision-surface error. */
+export class DecisionError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** Missing configuration — e.g. no `TYPESAFE_API_KEY` in the injected env. Carries the variable name. */
+export class DecisionConfigError extends DecisionError {
+    variable;
+    constructor(message, variable, options) {
+        super(message, options);
+        this.variable = variable;
+    }
+}
+/** Authentication or permission failure upstream. Carries the HTTP status. */
+export class DecisionAuthError extends DecisionError {
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.status = status;
+    }
+}
+/** Rate limited upstream. Carries the status and the parsed retry-after hint. */
+export class DecisionRateLimitError extends DecisionError {
+    status;
+    retryAfterMs;
+    constructor(message, status, retryAfterMs, options) {
+        super(message, options);
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/** Request timed out. Carries the configured timeout in milliseconds. */
+export class DecisionTimeoutError extends DecisionError {
+    timeoutMs;
+    constructor(message, timeoutMs, options) {
+        super(message, options);
+        this.timeoutMs = timeoutMs;
+    }
+}
+/** The backend was unreachable. Carries the underlying cause. */
+export class DecisionConnectionError extends DecisionError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** The request was rejected as malformed (4xx other than auth/rate-limit). Carries status and a body summary. */
+export class DecisionRequestError extends DecisionError {
+    status;
+    bodySummary;
+    constructor(message, status, bodySummary, options) {
+        super(message, options);
+        this.status = status;
+        this.bodySummary = bodySummary;
+    }
+}
+/** Upstream server failure (5xx). Carries the HTTP status. */
+export class DecisionBackendError extends DecisionError {
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.status = status;
+    }
+}

package/dist/decision/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Provider-neutral decision vocabulary — deliberately not re-exported from
+ * `@typesafe-ai/sdk`. Re-exporting the SDK's response types would bind every
+ * caller to the vendor; the neutral names here (`kind`, `labels`, `rubric`,
+ * `probability`) keep vendor mapping explicit and confined to the driver.
+ * This file imports nothing — no SDK, no workspace package (boundary rule).
+ */
+/** Any JSON-serializable value. */
+export type Json = string | number | boolean | null | Json[] | {
+    [k: string]: Json;
+};
+/** Caller-supplied decision context: free text, a structured object, or a list. */
+export type DecisionState = string | Json[] | {
+    [k: string]: Json;
+} | null;
+/** A description; `null` means "left undescribed" (e.g. a label needing no rationale). */
+export type Desc = string | Json[] | {
+    [k: string]: Json;
+} | null;
+/** Pick one label from a fixed set. Labels are the answer's type parameter. */
+export type ChoiceQuestion<L extends string> = {
+    kind: 'choice';
+    prompt?: Desc;
+    labels: Record<L, Desc>;
+};
+/** Score against a rubric; at least two levels, enforced at compile time. */
+export type ScoreQuestion = {
+    kind: 'score';
+    prompt?: Desc;
+    rubric: readonly [Desc, Desc, ...Desc[]];
+};
+/** Binary yes/no judgment with optional per-outcome descriptions. */
+export type NoulQuestion = {
+    kind: 'noul';
+    prompt?: Desc;
+    yes?: Desc;
+    no?: Desc;
+};
+/** Any question the decision surface accepts. */
+export type Question = ChoiceQuestion<string> | ScoreQuestion | NoulQuestion;
+/** Selected label, calibration confidence, and a probability per label. */
+export type ChoiceAnswer<L extends string> = {
+    kind: 'choice';
+    label: L;
+    confidence: number;
+    probabilities: Record<L, number>;
+};
+/** Rubric score, confidence, per-level legend, and a probability per level. */
+export type ScoreAnswer = {
+    kind: 'score';
+    score: number;
+    confidence: number;
+    legend: Record<number, Desc>;
+    probabilities: Record<number, number>;
+};
+/**
+ * Bare yes-probability — no `confidence`, on purpose. The wire response
+ * returns only a probability; synthesizing a confidence would fabricate
+ * calibration data. The asymmetry is load-bearing: later code cannot paper
+ * over it.
+ */
+export type NoulAnswer = {
+    kind: 'noul';
+    probability: number;
+};
+/** Any answer the decision surface returns — discriminate on `kind`. */
+export type Answer = ChoiceAnswer<string> | ScoreAnswer | NoulAnswer;
+/** The answer type a question of shape `Q` decodes to. */
+export type AnswerFor<Q> = Q extends ChoiceQuestion<infer L> ? ChoiceAnswer<L> : Q extends ScoreQuestion ? ScoreAnswer : Q extends NoulQuestion ? NoulAnswer : never;
+/** Conditional answer record for a keyed question map. */
+export type AnswersFor<Q extends Record<string, Question>> = {
+    readonly [K in keyof Q]: AnswerFor<Q[K]>;
+};
+/**
+ * Question builders for the batch path. Namespaced under `q` because
+ * `choice` / `score` / `noul` are already `DecisionMaker` method names.
+ */
+export declare const q: {
+    /**
+     * Build a choice question. `const` on the type parameter keeps an inline
+     * label map from widening to `string` — the caller keeps the union.
+     */
+    choice: <const L extends string>(prompt: Desc, labels: Record<L, Desc>) => ChoiceQuestion<L>;
+    /** Build a score question from a rubric of at least two levels. */
+    score: (prompt: Desc, rubric: readonly [Desc, Desc, ...Desc[]]) => ScoreQuestion;
+    /** Build a yes/no question; outcomes are optional and default undescribed. */
+    noul: (prompt?: Desc, outcomes?: {
+        yes?: Desc;
+        no?: Desc;
+    }) => NoulQuestion;
+};
+/**
+ * The one-method internal seam every backend driver implements. The loose
+ * `Record<string, Answer>` return is narrowed to `AnswersFor<Q>` by a single
+ * documented cast at the facade boundary — drivers stay trivial to write.
+ */
+export interface DecisionDriver {
+    readonly name: string;
+    ask(req: {
+        state: DecisionState;
+        questions: Record<string, Question>;
+        model?: string;
+    }): Promise<Record<string, Answer>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/decision/types.d.ts.map

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

package/dist/decision/types.js

@@ -0,0 +1,34 @@
+/**
+ * Provider-neutral decision vocabulary — deliberately not re-exported from
+ * `@typesafe-ai/sdk`. Re-exporting the SDK's response types would bind every
+ * caller to the vendor; the neutral names here (`kind`, `labels`, `rubric`,
+ * `probability`) keep vendor mapping explicit and confined to the driver.
+ * This file imports nothing — no SDK, no workspace package (boundary rule).
+ */
+/**
+ * Question builders for the batch path. Namespaced under `q` because
+ * `choice` / `score` / `noul` are already `DecisionMaker` method names.
+ */
+export const q = {
+    /**
+     * Build a choice question. `const` on the type parameter keeps an inline
+     * label map from widening to `string` — the caller keeps the union.
+     */
+    choice: (prompt, labels) => ({
+        kind: 'choice',
+        prompt,
+        labels,
+    }),
+    /** Build a score question from a rubric of at least two levels. */
+    score: (prompt, rubric) => ({
+        kind: 'score',
+        prompt,
+        rubric,
+    }),
+    /** Build a yes/no question; outcomes are optional and default undescribed. */
+    noul: (prompt, outcomes) => ({
+        kind: 'noul',
+        prompt,
+        ...outcomes,
+    }),
+};

package/dist/decision/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 './types';
+/** 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/decision/typesafe-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesafe-driver.d.ts","sourceRoot":"","sources":["../../src/decision/typesafe-driver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH,OAAO,KAAK,EAAU,cAAc,EAAY,MAAM,SAAS,CAAC;AAGhE,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,CA8CjF"}