@gobing-ai/ts-ai-runner 0.5.0 → 0.5.2

package/dist/decision/typesafe-driver.js

@@ -0,0 +1,134 @@
+/**
+ * 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 { APIConnectionError, APIError, APITimeoutError, AuthenticationError, choice, noul, PermissionDeniedError, RateLimitError, score, TypeSafeClient, TypeSafeError, } from '@typesafe-ai/sdk';
+import { DecisionAuthError, DecisionBackendError, DecisionConnectionError, DecisionRateLimitError, DecisionRequestError, DecisionTimeoutError, } from './errors.js';
+import { validateAnswers, validateQuestions } from './validation.js';
+/**
+ * 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.6.0 exports no default
+            // base-URL constant (`ENV` holds env-var names only), so an
+            // omitted baseURL still lets 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);
+            let result;
+            try {
+                const sdkQuestions = Object.fromEntries(Object.entries(questions).map(([name, question]) => [name, toSdkQuestion(question)]));
+                result = await client.systemOne({ 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 };
+            return noul(question.prompt ?? null, outcomes);
+        }
+    }
+}
+/** 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':
+            return {
+                kind: 'score',
+                score: answer.score,
+                confidence: answer.confidence,
+                legend: answer.legend,
+                probabilities: answer.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/dist/decision/validation.d.ts

@@ -0,0 +1,6 @@
+import type { Question } from './types';
+/** Validate caller data before either a custom driver or the SDK consumes it. */
+export declare function validateQuestions(questions: unknown): asserts questions is Record<string, Question>;
+/** Verify the correspondence that permits the facade's typed answer narrowing. */
+export declare function validateAnswers(questions: Record<string, Question>, answers: unknown): void;
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/decision/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAoBxC,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAoCnG;AAUD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA8B3F"}

package/dist/decision/validation.js

@@ -0,0 +1,92 @@
+import { DecisionBackendError, DecisionRequestError } from './errors.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function json(value, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    const valid = Object.values(value).every((entry) => json(entry, ancestors));
+    ancestors.delete(value);
+    return valid;
+}
+function desc(value) {
+    return (value === null || typeof value === 'string' || typeof value === 'object') && json(value);
+}
+/** Validate caller data before either a custom driver or the SDK consumes it. */
+export function validateQuestions(questions) {
+    const fail = (name) => {
+        throw new DecisionRequestError(`Invalid decision question: ${name}`, undefined, undefined);
+    };
+    if (!record(questions) || Object.keys(questions).length === 0)
+        fail('expected a nonempty question map');
+    for (const [name, question] of Object.entries(questions)) {
+        if (!record(question))
+            fail(name);
+        if (question.prompt !== undefined && !desc(question.prompt))
+            fail(name);
+        switch (question.kind) {
+            case 'choice':
+                if (!record(question.labels) ||
+                    Object.keys(question.labels).length === 0 ||
+                    !Object.values(question.labels).every(desc))
+                    fail(name);
+                break;
+            case 'score':
+                if (!Array.isArray(question.rubric) ||
+                    question.rubric.length < 2 ||
+                    !Array.from(question.rubric).every(desc))
+                    fail(name);
+                break;
+            case 'noul':
+                if ((question.yes !== undefined && !desc(question.yes)) ||
+                    (question.no !== undefined && !desc(question.no)))
+                    fail(name);
+                break;
+            default:
+                fail(name);
+        }
+    }
+}
+function bounded(value, max = 1) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= max;
+}
+function keysMatch(value, keys) {
+    return record(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+/** Verify the correspondence that permits the facade's typed answer narrowing. */
+export function validateAnswers(questions, answers) {
+    const fail = (name) => {
+        throw new DecisionBackendError(`Invalid decision response: ${name}`, undefined);
+    };
+    if (!keysMatch(answers, Object.keys(questions)))
+        fail('answer names do not match questions');
+    for (const [name, question] of Object.entries(questions)) {
+        const answer = answers[name];
+        if (!record(answer) || answer.kind !== question.kind)
+            fail(name);
+        if (question.kind === 'noul') {
+            if (!bounded(answer.probability))
+                fail(name);
+            continue;
+        }
+        const keys = question.kind === 'choice' ? Object.keys(question.labels) : Array.from(question.rubric.keys(), String);
+        if (!bounded(answer.confidence) ||
+            !keysMatch(answer.probabilities, keys) ||
+            !Object.values(answer.probabilities).every((p) => bounded(p)))
+            fail(name);
+        if (question.kind === 'choice') {
+            if (typeof answer.label !== 'string' || !Object.hasOwn(question.labels, answer.label))
+                fail(name);
+        }
+        else if (!bounded(answer.score, question.rubric.length - 1) ||
+            !keysMatch(answer.legend, keys) ||
+            !Object.values(answer.legend).every(desc)) {
+            fail(name);
+        }
+    }
+}

package/dist/index.d.ts

@@ -3,6 +3,9 @@ export * from './agent-spec';
 export * from './agents/auth-shims';
 export * from './agents/shims';
 export * from './ai-runner';
+export * from './decision/decision-maker';
+export * from './decision/errors';
+export * from './decision/types';
 export * from './doctor-runner';
 export * from './events';
 export * from './identity';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -3,6 +3,9 @@ export * from './agent-spec.js';
 export * from './agents/auth-shims.js';
 export * from './agents/shims.js';
 export * from './ai-runner.js';
+export * from './decision/decision-maker.js';
+export * from './decision/errors.js';
+export * from './decision/types.js';
 export * from './doctor-runner.js';
 export * from './events.js';
 export * from './identity.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.5.0",
+    "version": "0.5.2",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,12 +47,13 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-ai-runner-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-infra": "^0.5.0",
-        "@gobing-ai/ts-runtime": "^0.5.0"
+        "@gobing-ai/ts-infra": "^0.5.2",
+        "@gobing-ai/ts-runtime": "^0.5.2",
+        "@typesafe-ai/sdk": "0.6.0"
     },
     "devDependencies": {
         "@types/bun": "1.3.14",
-        "@gobing-ai/ts-db": "^0.5.0"
+        "@gobing-ai/ts-db": "^0.5.2"
     },
     "publishConfig": {
         "access": "public"

package/src/agents/shims.ts

@@ -477,14 +477,14 @@ const AGENT_SESSION_CAPABILITY: Readonly<Record<AgentName, AgentSessionCapabilit
         supportsSessionDir: true,
         supportsPersistentStdin: true,
         supportsStructuredOutput: true,
-        verifiedAgainst: '0.85.1',
+        verifiedAgainst: '0.87.0',
     },
     claude: {
         supportsResumeById: true,
         supportsSessionDir: false,
         supportsPersistentStdin: true,
         supportsStructuredOutput: true,
-        verifiedAgainst: '2.1.274',
+        verifiedAgainst: '2.1.278',
         // Persistent stdin is shim-wired: `-p --input-format stream-json --output-format
         // stream-json` keeps the process alive reading JSONL envelopes (verified --help;
         // --input-format only works with --print).
@@ -495,7 +495,7 @@ const AGENT_SESSION_CAPABILITY: Readonly<Record<AgentName, AgentSessionCapabilit
         supportsSessionDir: false,
         supportsPersistentStdin: false,
         supportsStructuredOutput: true,
-        verifiedAgainst: '0.154.0',
+        verifiedAgainst: '0.155.1',
         // R3 branch 2: `exec resume <id> <prompt>` is the working non-interactive
         // resume (verified 0.154.0) — wired in getPromptCommand below.
         note: 'no session-dir flag — sessionDir is ignored; `exec` carries one prompt arg (stdin `-` is one-shot), so no multi-turn stdin',
@@ -515,7 +515,7 @@ const AGENT_SESSION_CAPABILITY: Readonly<Record<AgentName, AgentSessionCapabilit
         supportsSessionDir: false,
         supportsPersistentStdin: false,
         supportsStructuredOutput: true,
-        verifiedAgainst: '1.0.34',
+        verifiedAgainst: '1.0.40',
         note: 'no session-dir flag — sessionDir is ignored (best-effort isolate); no multi-turn stdin input mode',
     },
     gemini: {

package/src/decision/decision-maker.ts

@@ -0,0 +1,160 @@
+/**
+ * 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';
+import type {
+    AnswersFor,
+    ChoiceAnswer,
+    DecisionDriver,
+    DecisionState,
+    Desc,
+    NoulAnswer,
+    Question,
+    ScoreAnswer,
+} from './types';
+import { q } from './types';
+import { createTypesafeDriver } from './typesafe-driver';
+import { validateAnswers, validateQuestions } from './validation';
+
+/** 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>;
+}
+
+/** Available named decision backends (task 0080). */
+export type DecisionBackend = 'typesafe' | 'laya-local';
+
+/** Factory options: driver selection, credential injection, and transport tuning. */
+export interface DecisionMakerOptions {
+    /** Custom driver — when supplied, `backend` is ignored, no default driver is constructed and no key is required. */
+    driver?: DecisionDriver;
+    /** Named backend selector. Default: `'typesafe'`. Resolution order: `driver` → `backend` → `'typesafe'`. */
+    backend?: DecisionBackend;
+    /** 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;
+    [key: string]: unknown;
+}
+
+/**
+ * Resolve the key per R7: `options.apiKey ?? (options.env ?? getProcessEnv()).TYPESAFE_API_KEY`.
+ * Throws before any driver construction or request.
+ */
+function resolveApiKey(options: DecisionMakerOptions): string {
+    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;
+}
+
+const LAYA_DRIVER_PACKAGE = '@gobing-ai/ts-laya-mlx';
+
+async function resolveLayaDriver(options: DecisionMakerOptions): Promise<DecisionDriver> {
+    try {
+        const mod = (await import(LAYA_DRIVER_PACKAGE)) as {
+            createLayaDriver?: (opts?: unknown) => DecisionDriver;
+        };
+        if (typeof mod.createLayaDriver !== 'function') {
+            throw new Error(`Module '${LAYA_DRIVER_PACKAGE}' does not export createLayaDriver`);
+        }
+        return mod.createLayaDriver(options);
+    } catch (cause) {
+        throw new DecisionConfigError(
+            `The 'laya-local' backend requires '${LAYA_DRIVER_PACKAGE}' to be installed; install it with 'bun add ${LAYA_DRIVER_PACKAGE}'`,
+            'LAYA_BACKEND',
+            { cause },
+        );
+    }
+}
+
+/**
+ * Build a DecisionMaker. `options.driver` wins when supplied; otherwise `options.backend`
+ * resolves the driver (default `'typesafe'`). The driver is constructed lazily on first use.
+ */
+export function createDecisionMaker(options: DecisionMakerOptions = {}): DecisionMaker {
+    let resolvedDriver: DecisionDriver | undefined;
+    const getDriver = async (): Promise<DecisionDriver> => {
+        if (options.driver) return options.driver;
+        if (resolvedDriver) return resolvedDriver;
+        const backend = options.backend ?? 'typesafe';
+        if (backend === 'typesafe') {
+            resolvedDriver = createTypesafeDriver({
+                apiKey: resolveApiKey(options),
+                model: options.model,
+                baseURL: options.baseURL,
+                timeoutMs: options.timeoutMs,
+                maxRetries: options.maxRetries,
+                fetch: options.fetch,
+            });
+            return resolvedDriver;
+        }
+        if (backend === 'laya-local') {
+            resolvedDriver = await resolveLayaDriver(options);
+            return resolvedDriver;
+        }
+        throw new DecisionConfigError(`Unknown decision backend '${backend}'`, 'backend');
+    };
+
+    const ask = async <const Q extends Record<string, Question>>(req: {
+        state: DecisionState;
+        questions: Q;
+        model?: string;
+    }): Promise<AnswersFor<Q>> => {
+        // R3: the questions map reaches the driver untouched — same reference,
+        // no reordering, renaming, or dropping.
+        const driver = await getDriver();
+        validateQuestions(req.questions);
+        const answers = await driver.ask(req);
+        validateAnswers(req.questions, answers);
+        // Runtime validation above establishes each question/answer correspondence.
+        return answers as AnswersFor<Q>;
+    };
+
+    return {
+        driver: options.driver?.name ?? options.backend ?? '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/src/decision/errors.ts

@@ -0,0 +1,88 @@
+/**
+ * `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: string, options?: { cause?: unknown }) {
+        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 {
+    constructor(
+        message: string,
+        readonly variable: string,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+    }
+}
+
+/** Authentication or permission failure upstream. Carries the HTTP status. */
+export class DecisionAuthError extends DecisionError {
+    constructor(
+        message: string,
+        readonly status: number | undefined,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+    }
+}
+
+/** Rate limited upstream. Carries the status and the parsed retry-after hint. */
+export class DecisionRateLimitError extends DecisionError {
+    constructor(
+        message: string,
+        readonly status: number | undefined,
+        readonly retryAfterMs: number | undefined,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+    }
+}
+
+/** Request timed out. Carries the configured timeout in milliseconds. */
+export class DecisionTimeoutError extends DecisionError {
+    constructor(
+        message: string,
+        readonly timeoutMs: number | undefined,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+    }
+}
+
+/** The backend was unreachable. Carries the underlying cause. */
+export class DecisionConnectionError extends DecisionError {
+    constructor(message: string, options?: { cause?: unknown }) {
+        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 {
+    constructor(
+        message: string,
+        readonly status: number | undefined,
+        readonly bodySummary: string | undefined,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+    }
+}
+
+/** Upstream server failure (5xx). Carries the HTTP status. */
+export class DecisionBackendError extends DecisionError {
+    constructor(
+        message: string,
+        readonly status: number | undefined,
+        options?: { cause?: unknown },
+    ) {
+        super(message, options);
+    }
+}