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

package/dist/decision/sampled-driver.js

@@ -0,0 +1,365 @@
+/**
+ * The engine-agnostic sampled-driver core (task 0114 R1, ADR-038): prompt
+ * rendering, per-question enum options, answer parsing and frequency
+ * estimation, shared by every backend that answers by drawing k samples from a
+ * model. A backend supplies only the per-ask session hook.
+ *
+ * Pure by contract (R2): imports only the sibling `types` and `errors` modules —
+ * no SDK, no workspace package, no platform API. That is what lets a driver
+ * package outside `ts-ai-runner` build on it without a cycle.
+ */
+import { DecisionBackendError, DecisionRequestError } from './errors.js';
+/**
+ * Fixed instructions text. It never asks for confidence, certainty or a
+ * probability — self-reported confidence would be fabricated calibration, which
+ * the decision contract forbids (ADR-030).
+ */
+export const DECISION_INSTRUCTIONS = 'You are a decision engine. Answer every question below using only the supplied state. ' +
+    'For each question choose exactly one of the listed options. ' +
+    'Reply with the JSON object the schema requires.';
+/** Build the enum schema over the whole question map: one call answers every key. */
+export function buildEnumSchema(questions) {
+    const properties = {};
+    for (const [key, question] of Object.entries(questions)) {
+        switch (question.kind) {
+            case 'choice':
+                properties[key] = { type: 'string', enum: Object.keys(question.labels) };
+                break;
+            case 'score':
+                properties[key] = { type: 'string', enum: question.rubric.map((_, level) => String(level)) };
+                break;
+            case 'noul':
+                properties[key] = { type: 'string', enum: ['yes', 'no'] };
+                break;
+        }
+    }
+    const keys = Object.keys(questions);
+    return {
+        type: 'object',
+        title: 'Decision',
+        'x-order': keys,
+        required: keys,
+        additionalProperties: false,
+        properties,
+    };
+}
+/** Format a {@link Desc} into prompt text: strings verbatim, structured values JSON, absence empty. */
+export function formatDesc(desc) {
+    if (typeof desc === 'string')
+        return desc;
+    if (desc === null || desc === undefined)
+        return '';
+    return JSON.stringify(desc);
+}
+/** The declared option values of a question, in declaration order (estimation + validation share this). */
+export function declaredOptions(question) {
+    switch (question.kind) {
+        case 'choice':
+            return Object.keys(question.labels);
+        case 'score':
+            return question.rubric.map((_, level) => String(level));
+        case 'noul':
+            return ['yes', 'no'];
+    }
+}
+/**
+ * Render the positional prompt: the state as text (JSON when structured), then
+ * one block per question key with the prompt `Desc` and its options with
+ * descriptions — choice label keys, score level indices with the rubric text,
+ * noul `yes`/`no` with any outcome descriptions.
+ */
+export function buildPrompt(state, questions) {
+    const parts = [];
+    const stateText = typeof state === 'string' ? state : state === null || state === undefined ? '' : JSON.stringify(state);
+    if (stateText.length > 0)
+        parts.push(stateText);
+    for (const [key, question] of Object.entries(questions)) {
+        const lines = [];
+        const prompt = formatDesc(question.prompt);
+        lines.push(`Question "${key}":${prompt.length > 0 ? ` ${prompt}` : ''}`);
+        lines.push('Options:');
+        switch (question.kind) {
+            case 'choice':
+                for (const [label, desc] of Object.entries(question.labels)) {
+                    const d = formatDesc(desc);
+                    lines.push(d.length > 0 ? `- ${label}: ${d}` : `- ${label}`);
+                }
+                break;
+            case 'score':
+                question.rubric.forEach((desc, level) => {
+                    const d = formatDesc(desc);
+                    lines.push(d.length > 0 ? `- ${level}: ${d}` : `- ${level}`);
+                });
+                break;
+            case 'noul': {
+                for (const outcome of ['yes', 'no']) {
+                    const d = formatDesc(question[outcome]);
+                    lines.push(d.length > 0 ? `- ${outcome}: ${d}` : `- ${outcome}`);
+                }
+                break;
+            }
+        }
+        parts.push(lines.join('\n'));
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Laya reference `confidence_from_probs` on the empirical distribution:
+ * `1 − H(p) / ln(n)` over the n declared options. One-hot ⇒ 1, uniform ⇒ 0.
+ */
+export function entropyConfidence(probabilities) {
+    const n = probabilities.length;
+    if (n <= 1)
+        return 1;
+    let entropy = 0;
+    for (const p of probabilities) {
+        if (p > 0)
+            entropy -= p * Math.log(p);
+    }
+    return 1 - entropy / Math.log(n);
+}
+/**
+ * Choice frequencies over every supplied label (unsampled ⇒ 0). The answer
+ * label is the most frequent with ties broken by label declaration order.
+ */
+export function estimateChoice(labels, samples) {
+    const counts = new Map(labels.map((label) => [label, 0]));
+    for (const sample of samples)
+        counts.set(sample, (counts.get(sample) ?? 0) + 1);
+    const k = samples.length;
+    const probabilities = {};
+    const distribution = [];
+    let bestLabel = labels[0] ?? '';
+    let bestCount = -1;
+    for (const label of labels) {
+        const count = counts.get(label) ?? 0;
+        const probability = count / k;
+        distribution.push(probability);
+        probabilities[label] = probability;
+        // Declaration order wins ties: strict `>` keeps the earlier label.
+        if (count > bestCount) {
+            bestCount = count;
+            bestLabel = label;
+        }
+    }
+    return {
+        kind: 'choice',
+        label: bestLabel,
+        confidence: entropyConfidence(distribution),
+        probabilities,
+    };
+}
+/**
+ * Score frequencies over the level indices `0…n-1`. The answer score is the
+ * most frequent level with ties going to the lower level; the legend maps each
+ * index back to its rubric description.
+ */
+export function estimateScore(rubric, samples) {
+    const k = samples.length;
+    const counts = [];
+    for (const sample of samples) {
+        const level = Number.parseInt(sample, 10);
+        counts[level] = (counts[level] ?? 0) + 1;
+    }
+    const probabilities = {};
+    const distribution = [];
+    let bestLevel = 0;
+    let bestCount = -1;
+    for (let level = 0; level < rubric.length; level++) {
+        const count = counts[level] ?? 0;
+        const probability = count / k;
+        distribution.push(probability);
+        probabilities[level] = probability;
+        // Lower level wins ties: strict `>` keeps the smaller index.
+        if (count > bestCount) {
+            bestCount = count;
+            bestLevel = level;
+        }
+    }
+    const legend = {};
+    rubric.forEach((desc, level) => {
+        legend[level] = desc;
+    });
+    return {
+        kind: 'score',
+        score: bestLevel,
+        confidence: entropyConfidence(distribution),
+        legend,
+        probabilities,
+    };
+}
+/** Noul is a bare yes-probability — no `confidence` key, by contract. */
+export function estimateNoul(samples) {
+    const yes = samples.filter((sample) => sample === 'yes').length;
+    return { kind: 'noul', probability: yes / samples.length };
+}
+/** A parsed value outside the declared enum is a schema violation, never an answer. */
+export function requireEnumValue(parsed, key, allowed, label = 'sample') {
+    const value = parsed[key];
+    if (value === undefined || !allowed.includes(value)) {
+        throw new DecisionBackendError(`${label} sample for '${key}' violates the schema enum: ${value === undefined ? '(missing)' : `'${value}'`}`, undefined);
+    }
+    return value;
+}
+/** Parse text as JSON, reporting failure instead of throwing. */
+function tryParse(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * The first balanced `{…}` substring, scanned with a string/escape-aware brace
+ * counter so braces inside string values do not close the object early.
+ */
+function firstBalancedObject(text) {
+    for (let start = text.indexOf('{'); start !== -1; start = text.indexOf('{', start + 1)) {
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = start; i < text.length; i++) {
+            const ch = text[i];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (ch === '\\')
+                    escaped = true;
+                else if (ch === '"')
+                    inString = false;
+                continue;
+            }
+            if (ch === '"') {
+                inString = true;
+            }
+            else if (ch === '{') {
+                depth += 1;
+            }
+            else if (ch === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    const parsed = tryParse(text.slice(start, i + 1));
+                    if (parsed.ok)
+                        return parsed.value;
+                    break;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Lenient answer parser for models without constrained decoding (task 0114 R6).
+ * Tries the whole text, then the first fenced block, then the first balanced
+ * object in prose. The result must be a flat object of string values.
+ */
+export function extractJsonAnswer(text) {
+    const direct = tryParse(text.trim());
+    let value = direct.ok ? direct.value : undefined;
+    if (value === undefined) {
+        const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+        if (fence !== null) {
+            const fenced = tryParse((fence[1] ?? '').trim());
+            if (fenced.ok)
+                value = fenced.value;
+        }
+    }
+    if (value === undefined)
+        value = firstBalancedObject(text);
+    if (value === undefined) {
+        throw new DecisionBackendError('no JSON object in sample output', undefined);
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new DecisionBackendError(`sample output is not a JSON object: ${JSON.stringify(value)}`, undefined);
+    }
+    const record = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry !== 'string') {
+            throw new DecisionBackendError(`sample output has a non-string value for '${key}'`, undefined);
+        }
+        record[key] = entry;
+    }
+    return record;
+}
+/**
+ * Build a sampled driver: k draws through one per-ask {@link SampleSession},
+ * enum-checked against the declared options and reduced to sample frequencies.
+ *
+ * The order inside `ask` is the contract (R5): validate → render → open →
+ * sample → enum-check → estimate, with `close` in `finally` either way.
+ */
+export function createSampledDriver(options) {
+    const { name, deterministic = false, sampleLabel } = options;
+    const samples = options.samples ?? 5;
+    const concurrency = options.concurrency ?? 1;
+    if (!Number.isInteger(samples) || samples < 1) {
+        throw new DecisionRequestError(`samples must be a positive integer; got ${samples}`, undefined, undefined);
+    }
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new DecisionRequestError(`concurrency must be a positive integer; got ${concurrency}`, undefined, undefined);
+    }
+    const k = deterministic ? 1 : samples;
+    const label = sampleLabel ?? name;
+    return {
+        name,
+        estimator: { kind: 'sample-frequency', samples: k, greedy: deterministic },
+        async ask({ state, questions, model, }) {
+            const entries = Object.entries(questions);
+            if (entries.length === 0) {
+                throw new DecisionRequestError('expected a nonempty question map', undefined, undefined);
+            }
+            for (const [key, question] of entries) {
+                const optionCount = declaredOptions(question).length;
+                if (optionCount < 2) {
+                    throw new DecisionRequestError(`question '${key}' has fewer than two options (${optionCount})`, undefined, undefined);
+                }
+            }
+            const instructions = options.instructions ?? DECISION_INSTRUCTIONS;
+            const prompt = buildPrompt(state, questions);
+            const session = await options.open({ instructions, prompt, questions, state, model });
+            try {
+                const draws = [];
+                for (let start = 0; start < k; start += concurrency) {
+                    const size = Math.min(concurrency, k - start);
+                    const batch = Array.from({ length: size }, () => session.sample());
+                    // allSettled awaits the whole batch before close; the first
+                    // rejection in draw order wins, so no partial estimate escapes.
+                    const settled = await Promise.allSettled(batch);
+                    const failure = settled.find((result) => result.status === 'rejected');
+                    if (failure !== undefined)
+                        throw failure.reason;
+                    for (const result of settled) {
+                        draws.push(result.value);
+                    }
+                }
+                const allowed = new Map(entries.map(([key, question]) => [key, declaredOptions(question)]));
+                const samplesByKey = new Map(entries.map(([key]) => [key, []]));
+                for (const draw of draws) {
+                    for (const [key] of entries) {
+                        samplesByKey.get(key)?.push(requireEnumValue(draw, key, allowed.get(key) ?? [], label));
+                    }
+                }
+                const answers = {};
+                for (const [key, question] of entries) {
+                    const values = samplesByKey.get(key) ?? [];
+                    switch (question.kind) {
+                        case 'choice':
+                            answers[key] = estimateChoice(Object.keys(question.labels), values);
+                            break;
+                        case 'score':
+                            answers[key] = estimateScore(question.rubric, values);
+                            break;
+                        case 'noul':
+                            answers[key] = estimateNoul(values);
+                            break;
+                    }
+                }
+                return answers;
+            }
+            finally {
+                await session.close?.();
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './agents/shims';
 export * from './ai-runner';
 export * from './decision/decision-maker';
 export * from './decision/errors';
+export * from './decision/sampled-driver';
 export * from './decision/types';
 export * from './decision/validation';
 export * from './doctor-runner';

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,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,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,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,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

@@ -5,6 +5,7 @@ export * from './agents/shims.js';
 export * from './ai-runner.js';
 export * from './decision/decision-maker.js';
 export * from './decision/errors.js';
+export * from './decision/sampled-driver.js';
 export * from './decision/types.js';
 export * from './decision/validation.js';
 export * from './doctor-runner.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-ai-runner",
-    "version": "0.5.30",
+    "version": "0.5.33",
     "description": "@gobing-ai/ts-ai-runner — Coding-agent shims, detection, doctor checks, and prompt execution.",
     "keywords": [
         "typescript",
@@ -47,13 +47,12 @@
         "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.30",
-        "@gobing-ai/ts-runtime": "^0.5.30",
-        "@typesafe-ai/sdk": "0.6.0"
+        "@gobing-ai/ts-infra": "^0.5.33",
+        "@gobing-ai/ts-runtime": "^0.5.33"
     },
     "devDependencies": {
         "@types/bun": "1.4.3",
-        "@gobing-ai/ts-db": "^0.5.30"
+        "@gobing-ai/ts-db": "^0.5.33"
     },
     "publishConfig": {
         "access": "public"

package/src/decision/decision-maker.ts

@@ -17,7 +17,6 @@ import type {
     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. */
@@ -55,7 +54,14 @@ export type DecisionBackend = 'typesafe' | 'laya-local' | 'fm-local';
 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'`. */
+    /**
+     * Named backend selector. Default: `'typesafe'`. Resolution order: `driver` → `backend` → `'typesafe'`.
+     *
+     * @deprecated `'typesafe'` (including the implicit default) now loads its driver from
+     * `@gobing-ai/ts-ai-decision` through a dynamic import, so it requires that package to be
+     * installed. Prefer `driver: createTypesafeDriver(...)` imported from `@gobing-ai/ts-ai-decision`;
+     * this bridge is removed in the next minor (ADR-039).
+     */
     backend?: DecisionBackend;
     /** Injected env record; defaults to `getProcessEnv()` (doctor-runner convention). */
     env?: Record<string, string | undefined>;
@@ -75,7 +81,7 @@ export interface DecisionMakerOptions {
  * 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 {
+export function resolveApiKey(options: DecisionMakerOptions): string {
     const env = options.env ?? getProcessEnv();
     const apiKey = options.apiKey ?? env.TYPESAFE_API_KEY;
     if (!apiKey) {
@@ -122,6 +128,49 @@ export async function resolveLayaDriver(
     return mod.createLayaDriver(options);
 }
 
+const TYPESAFE_DRIVER_PACKAGE = '@gobing-ai/ts-ai-decision';
+
+/**
+ * Resolve the `typesafe` driver from `@gobing-ai/ts-ai-decision` (task 0116 R5, ADR-039).
+ *
+ * The driver moved out of this package, which is now the contract-only surface. The key is
+ * resolved FIRST so a missing key keeps its exact pre-move error and no import is attempted.
+ *
+ * @internal Exported for the branch tests; see {@link resolveLayaDriver}.
+ */
+export async function resolveTypesafeDriver(
+    options: DecisionMakerOptions,
+    importModule: (specifier: string) => Promise<unknown> = (specifier) => import(specifier),
+): Promise<DecisionDriver> {
+    const apiKey = resolveApiKey(options);
+    let mod: { createTypesafeDriver?: (opts?: unknown) => DecisionDriver };
+    try {
+        mod = (await importModule(TYPESAFE_DRIVER_PACKAGE)) as {
+            createTypesafeDriver?: (opts?: unknown) => DecisionDriver;
+        };
+    } catch (cause) {
+        throw new DecisionConfigError(
+            `The 'typesafe' backend requires '${TYPESAFE_DRIVER_PACKAGE}' to be installed; install it with 'bun add ${TYPESAFE_DRIVER_PACKAGE}'`,
+            'TYPESAFE_BACKEND',
+            { cause },
+        );
+    }
+    if (typeof mod.createTypesafeDriver !== 'function') {
+        throw new DecisionConfigError(
+            `Module '${TYPESAFE_DRIVER_PACKAGE}' does not export createTypesafeDriver`,
+            'TYPESAFE_BACKEND',
+        );
+    }
+    return mod.createTypesafeDriver({
+        apiKey,
+        model: options.model,
+        baseURL: options.baseURL,
+        timeoutMs: options.timeoutMs,
+        maxRetries: options.maxRetries,
+        fetch: options.fetch,
+    });
+}
+
 const FM_DRIVER_PACKAGE = '@gobing-ai/ts-decision-fm';
 
 /** @internal Exported for task 0086 R9 branch tests; see {@link resolveLayaDriver}. */
@@ -159,14 +208,7 @@ export function createDecisionMaker(options: DecisionMakerOptions = {}): Decisio
         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,
-            });
+            resolvedDriver = await resolveTypesafeDriver(options);
             return resolvedDriver;
         }
         if (backend === 'laya-local') {