@atomic-chat/core 0.5.1 → 0.13.2

package/dist/decision/outcome.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The fail-open outcome of a decision call, from the module's state or the engine's answer. Pure.
+ *
+ * A call never throws into its caller: the chat path asks the router before it picks a model, and a
+ * router that cannot answer must cost at most its budget, never the turn. Every way of not answering
+ * becomes `{unavailable: true, reason}`, and the caller applies its default policy.
+ */
+import type { DecisionEngineError, DecisionOutcome, DecisionState, DecisionUnavailableReason, RouterScoreResponse, SystemoneResponse } from '../contracts/index.js';
+export declare function unavailable<T>(reason: DecisionUnavailableReason, message: string, elapsedMs: number, extra?: {
+    status?: number;
+    error?: DecisionEngineError;
+}): DecisionOutcome<T>;
+/** Why a call cannot even be sent in `state`; `undefined` when the process is ready. */
+export declare function refusalForState(state: DecisionState, configured: boolean): {
+    reason: DecisionUnavailableReason;
+    message: string;
+} | undefined;
+/** The engine's `{"error": {...}}`, or a synthetic one around a body that is not an envelope. */
+export declare function engineErrorOf(status: number, text: string): DecisionEngineError;
+/**
+ * An engine answer as an outcome. `check` says whether a parsed 200 body is the expected shape: a
+ * 200 that is not JSON or not that shape is `invalid_response`, never a result the caller trusts.
+ */
+export declare function outcomeFromAnswer<T>(status: number, text: string, elapsedMs: number, check: (body: unknown) => body is T): DecisionOutcome<T>;
+export declare const NOT_CALIBRATED_MESSAGE = "The decision model has no router calibration, and allow_uncalibrated is off; the router cannot score.";
+/** A `/v1/router/score` answer: `scores` is a list of objects with an `id` and a numeric `p_success`. */
+export declare function isRouterScoreBody(body: unknown): body is RouterScoreResponse;
+/**
+ * Whether a router answer scores exactly the candidates that were asked about, in their order. The
+ * engine promises request order; a caller that zips scores with its candidates by index would credit
+ * the wrong executor if an answer broke that, so such an answer is not trusted.
+ */
+export declare function scoresMatchCandidates(body: RouterScoreResponse, ids: readonly string[]): boolean;
+/** A `/v1/systemone` answer: `answers` is an object of objects. */
+export declare function isSystemoneBody(body: unknown): body is SystemoneResponse;

package/dist/decision/outcome.js

@@ -0,0 +1,105 @@
+/**
+ * The fail-open outcome of a decision call, from the module's state or the engine's answer. Pure.
+ *
+ * A call never throws into its caller: the chat path asks the router before it picks a model, and a
+ * router that cannot answer must cost at most its budget, never the turn. Every way of not answering
+ * becomes `{unavailable: true, reason}`, and the caller applies its default policy.
+ */
+export function unavailable(reason, message, elapsedMs, extra = {}) {
+    return { unavailable: true, reason, message, elapsed_ms: elapsedMs, ...extra };
+}
+/** Why a call cannot even be sent in `state`; `undefined` when the process is ready. */
+export function refusalForState(state, configured) {
+    switch (state) {
+        case 'ready':
+            return undefined;
+        case 'disabled':
+            return { reason: 'disabled', message: 'The decision model is turned off.' };
+        case 'unsupported':
+            return { reason: 'unsupported', message: 'No installed engine build can run the decision model.' };
+        case 'failed':
+            return { reason: 'failed', message: 'The decision model failed to start; see its status.' };
+        case 'starting':
+        case 'restarting':
+            return { reason: 'starting', message: 'The decision model is starting.' };
+        case 'idle':
+            return configured
+                ? { reason: 'starting', message: 'The decision model was not running; it is being started.' }
+                : { reason: 'not_configured', message: 'No decision model file is configured.' };
+    }
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The engine's `{"error": {...}}`, or a synthetic one around a body that is not an envelope. */
+export function engineErrorOf(status, text) {
+    try {
+        const body = JSON.parse(text);
+        const error = isRecord(body) ? body['error'] : undefined;
+        if (isRecord(error) && typeof error['message'] === 'string')
+            return error;
+    }
+    catch {
+        // not JSON: fall through
+    }
+    return { code: status, message: text.slice(0, 500) || `HTTP ${status}` };
+}
+/**
+ * An engine answer as an outcome. `check` says whether a parsed 200 body is the expected shape: a
+ * 200 that is not JSON or not that shape is `invalid_response`, never a result the caller trusts.
+ */
+export function outcomeFromAnswer(status, text, elapsedMs, check) {
+    if (status === 200) {
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            return unavailable('invalid_response', 'The decision model answered with something that is not JSON.', elapsedMs, {
+                status,
+            });
+        }
+        if (!check(body))
+            return unavailable('invalid_response', 'The decision model answered in an unexpected shape.', elapsedMs, {
+                status,
+            });
+        return { unavailable: false, result: body, elapsed_ms: elapsedMs };
+    }
+    const error = engineErrorOf(status, text);
+    if (status === 429)
+        return unavailable('overloaded', 'The decision model is busy; its queue is full.', elapsedMs, {
+            status,
+            error,
+        });
+    if (status === 503)
+        return unavailable('not_running', 'The decision model is loading or stopping.', elapsedMs, {
+            status,
+            error,
+        });
+    // 501 is only ever `ROUTER_NOT_CALIBRATED` in DECISION.md; the reason is checked too, for a proxy
+    // that rewrote the status.
+    if (status === 501 || error.reason === 'ROUTER_NOT_CALIBRATED')
+        return unavailable('not_calibrated', NOT_CALIBRATED_MESSAGE, elapsedMs, { status, error });
+    return unavailable('rejected', `The decision model refused the request: ${error.message}`, elapsedMs, {
+        status,
+        error,
+    });
+}
+export const NOT_CALIBRATED_MESSAGE = 'The decision model has no router calibration, and allow_uncalibrated is off; the router cannot score.';
+/** A `/v1/router/score` answer: `scores` is a list of objects with an `id` and a numeric `p_success`. */
+export function isRouterScoreBody(body) {
+    if (!isRecord(body) || !Array.isArray(body['scores']))
+        return false;
+    return body['scores'].every((s) => isRecord(s) && typeof s['id'] === 'string' && typeof s['p_success'] === 'number');
+}
+/**
+ * Whether a router answer scores exactly the candidates that were asked about, in their order. The
+ * engine promises request order; a caller that zips scores with its candidates by index would credit
+ * the wrong executor if an answer broke that, so such an answer is not trusted.
+ */
+export function scoresMatchCandidates(body, ids) {
+    return body.scores.length === ids.length && body.scores.every((s, i) => s.id === ids[i]);
+}
+/** A `/v1/systemone` answer: `answers` is an object of objects. */
+export function isSystemoneBody(body) {
+    return isRecord(body) && isRecord(body['answers']) && Object.values(body['answers']).every(isRecord);
+}
+//# sourceMappingURL=outcome.js.map

package/dist/decision/outcome.js.map

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

package/dist/decision/process.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Spawning one decision `llama-server` (the fork's `--decision`, or stock llama.cpp for an upstream
+ * decision GGUF) and waiting until it is a decision model this core can use.
+ *
+ * Borrowed from the runtimes, as the image engine does: `spawnManaged`, `randomFreePort`,
+ * `buildProcessEnv`, the backend-output sink, and the journal hooks (the caller writes the record
+ * right after the spawn under `provider: 'decision'`, so a crashed owner's successor reaps it).
+ * Readiness is the chain of `readiness.ts`, polled until the startup deadline; an exit before it is
+ * reported with the last lines the process printed. On any failure the child is dead when this
+ * rejects.
+ */
+import { AtomicCoreError } from '../contracts/index.js';
+import type { DecisionCapability, DecisionEngineInfo, DecisionProps } from '../contracts/index.js';
+import type { ExitInfo } from '../runtime/llamacpp/index.js';
+import type { BackendOutputSink, ManagedProcess, SpawnSpec } from '../runtime/shared/index.js';
+import type { DecisionLaunchSpec, UpstreamDecisionLaunch } from './args.js';
+import type { DecisionHttp } from './http.js';
+/** SIGTERM → this long → SIGKILL. The engine cancels its queue on SIGTERM, so this is rarely used. */
+export declare const DECISION_TERMINATE_GRACE_MS = 5000;
+export declare const READY_POLL_INTERVAL_MS = 200;
+/** Lines of output kept for a post-mortem. */
+export declare const DECISION_TAIL_CAPACITY = 100;
+export interface DecisionServerSpec extends Omit<DecisionLaunchSpec, 'port'> {
+    engine: DecisionEngineInfo;
+    startupTimeoutMs: number;
+    /** How an upstream engine (`engine.dialect === 'upstream'`) runs the model; ignored by the fork. */
+    upstream?: UpstreamDecisionLaunch;
+}
+/** The argv for `spec` on `port`: the fork's `--decision`, or stock llama.cpp for an upstream GGUF. */
+export declare function decisionArgsFor(spec: DecisionServerSpec, port: number): string[];
+/** A running decision process that passed the readiness chain. */
+export interface DecisionProcessHandle {
+    pid: number;
+    port: number;
+    apiKey: string;
+    exe: string;
+    baseUrl: string;
+    props: DecisionProps;
+    capabilities: DecisionCapability[];
+    tail(): string[];
+    exitStatus(): ExitInfo | undefined;
+    exited: Promise<ExitInfo>;
+    terminate(graceMs?: number): Promise<ExitInfo>;
+}
+export interface SpawnDecisionDeps {
+    http: DecisionHttp;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    log?: (level: 'info' | 'warn' | 'debug', msg: string) => void;
+    backendOutput?: BackendOutputSink;
+    /** Right after the child started, before readiness: the journal entry goes here. */
+    onSpawned?: (pid: number, port: number, exe: string) => Promise<void>;
+    /** A child `onSpawned` saw is dead and will never be used. */
+    onGone?: (pid: number) => Promise<void>;
+    /** An unload or a shutdown while the process is still starting; the child is killed. */
+    signal?: AbortSignal;
+    freePort?: () => Promise<number>;
+    apiKey?: () => string;
+    /** Test seam: start the child (the fake engine in tests). */
+    spawn?: (spec: SpawnSpec, onData: (stream: 'stdout' | 'stderr', line: string) => void) => ManagedProcess;
+    pollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/** The error for a process that died before it was ready: the engine's own last lines in the details. */
+export declare function earlyExitError(exit: ExitInfo, tail: readonly string[]): AtomicCoreError;
+export declare function spawnDecisionServer(spec: DecisionServerSpec, deps: SpawnDecisionDeps): Promise<DecisionProcessHandle>;

package/dist/decision/process.js

@@ -0,0 +1,133 @@
+/**
+ * Spawning one decision `llama-server` (the fork's `--decision`, or stock llama.cpp for an upstream
+ * decision GGUF) and waiting until it is a decision model this core can use.
+ *
+ * Borrowed from the runtimes, as the image engine does: `spawnManaged`, `randomFreePort`,
+ * `buildProcessEnv`, the backend-output sink, and the journal hooks (the caller writes the record
+ * right after the spawn under `provider: 'decision'`, so a crashed owner's successor reaps it).
+ * Readiness is the chain of `readiness.ts`, polled until the startup deadline; an exit before it is
+ * reported with the last lines the process printed. On any failure the child is dead when this
+ * rejects.
+ */
+import { randomBytes } from 'node:crypto';
+import { dirname } from 'node:path';
+import { AtomicCoreError } from '../contracts/index.js';
+import { backendOutputReporter, buildProcessEnv, discoverCudaPaths, nodeCudaProbeEnv, randomFreePort, spawnManaged, } from '../runtime/shared/index.js';
+import { buildDecisionArgs, buildUpstreamDecisionArgs, commandSummary, decisionEnv, DECISION_HOST, withoutDecisionEnv, } from './args.js';
+import { UPSTREAM_DECISION_DEFAULT_CTX } from './model-facts.js';
+import { checkReadiness, READINESS_REQUEST_TIMEOUT_MS } from './readiness.js';
+/** SIGTERM → this long → SIGKILL. The engine cancels its queue on SIGTERM, so this is rarely used. */
+export const DECISION_TERMINATE_GRACE_MS = 5_000;
+export const READY_POLL_INTERVAL_MS = 200;
+/** Lines of output kept for a post-mortem. */
+export const DECISION_TAIL_CAPACITY = 100;
+/** The argv for `spec` on `port`: the fork's `--decision`, or stock llama.cpp for an upstream GGUF. */
+export function decisionArgsFor(spec, port) {
+    if (spec.engine.dialect !== 'upstream')
+        return buildDecisionArgs({ ...spec, port });
+    return buildUpstreamDecisionArgs({ ...spec, port }, spec.upstream ?? { ctxSize: UPSTREAM_DECISION_DEFAULT_CTX, wholePromptUbatch: false });
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function describeExit(exit) {
+    if (exit.code !== null)
+        return `code ${exit.code}`;
+    if (exit.signal !== null)
+        return `signal ${exit.signal}`;
+    return 'an unknown status';
+}
+/** The error for a process that died before it was ready: the engine's own last lines in the details. */
+export function earlyExitError(exit, tail) {
+    return new AtomicCoreError('MODEL_LOAD_FAILED', `The decision model exited with ${describeExit(exit)} while loading.`, tail.slice(-20).join('\n') || undefined);
+}
+export async function spawnDecisionServer(spec, deps) {
+    const platform = deps.platform ?? process.platform;
+    const baseEnv = withoutDecisionEnv(deps.env ?? process.env);
+    const log = deps.log ?? (() => { });
+    const sleep = deps.sleep ?? defaultSleep;
+    const now = deps.now ?? Date.now;
+    const exe = spec.engine.path;
+    const port = await (deps.freePort ?? (() => randomFreePort([])))().catch((error) => {
+        throw new AtomicCoreError('MODEL_LOAD_FAILED', 'No free port for the decision model.', error instanceof Error ? error.message : String(error));
+    });
+    const apiKey = (deps.apiKey ?? (() => randomBytes(24).toString('base64url')))();
+    const args = decisionArgsFor(spec, port);
+    log('info', `starting the decision model: ${commandSummary(exe, args)}`);
+    const { env, cwd } = buildProcessEnv({
+        platform,
+        baseEnv,
+        exeDir: dirname(exe),
+        cuda: discoverCudaPaths(nodeCudaProbeEnv(platform, baseEnv)),
+        userEnv: decisionEnv(apiKey),
+    });
+    const tail = [];
+    const reportOutput = backendOutputReporter(deps.backendOutput, deps.log);
+    const modelLabel = spec.modelId || 'decision';
+    const onLine = (stream, line) => {
+        reportOutput({ provider: 'decision', model: modelLabel, stream, line });
+        if (tail.length >= DECISION_TAIL_CAPACITY)
+            tail.shift();
+        tail.push(line);
+    };
+    const proc = (deps.spawn ?? ((s, cb) => spawnManaged(s, cb, { captureOutput: false })))({ exe, args, env, cwd }, onLine);
+    let exit;
+    void proc.exited.then((e) => (exit = e));
+    const baseUrl = `http://${DECISION_HOST}:${port}`;
+    const terminate = (graceMs = DECISION_TERMINATE_GRACE_MS) => proc.terminate(graceMs);
+    try {
+        await deps.onSpawned?.(proc.pid, port, exe);
+    }
+    catch (error) {
+        await terminate(0);
+        throw error;
+    }
+    const fail = async (graceMs, error) => {
+        await terminate(graceMs);
+        await deps.onGone?.(proc.pid);
+        throw error;
+    };
+    const deadline = now() + spec.startupTimeoutMs;
+    let lastDetail = '';
+    for (;;) {
+        if (deps.signal?.aborted)
+            return fail(0, new AtomicCoreError('DECISION_UNAVAILABLE', 'The decision model start was stopped.'));
+        const spawnFailure = proc.spawnFailure();
+        if (spawnFailure) {
+            await deps.onGone?.(proc.pid);
+            throw new AtomicCoreError('MODEL_LOAD_FAILED', 'The decision engine could not be started.', `${exe}: ${spawnFailure.message}`);
+        }
+        if (exit !== undefined) {
+            // Give the pipes a moment to deliver the final lines.
+            await sleep(50);
+            await deps.onGone?.(proc.pid);
+            const error = earlyExitError(exit, tail);
+            log('warn', `the decision model exited while loading (${describeExit(exit)})`);
+            throw error;
+        }
+        if (now() >= deadline)
+            return fail(DECISION_TERMINATE_GRACE_MS, new AtomicCoreError('MODEL_LOAD_TIMED_OUT', `The decision model did not become ready within ${Math.round(spec.startupTimeoutMs / 1000)} seconds.`, [lastDetail, ...tail.slice(-10)].filter(Boolean).join('\n') || undefined));
+        const result = await checkReadiness(deps.http, baseUrl, apiKey, READINESS_REQUEST_TIMEOUT_MS, spec.engine.dialect);
+        if (result.kind === 'ready') {
+            log('info', `the decision model is ready on port ${port} (${result.props.layout ?? 'unknown layout'}, ${result.props.model_id ?? 'unnamed'})`);
+            return {
+                pid: proc.pid,
+                port,
+                apiKey,
+                exe,
+                baseUrl,
+                props: result.props,
+                capabilities: result.capabilities,
+                tail: () => [...tail],
+                exitStatus: () => exit,
+                exited: proc.exited,
+                terminate,
+            };
+        }
+        if (result.kind === 'unsupported')
+            return fail(DECISION_TERMINATE_GRACE_MS, new AtomicCoreError('DECISION_ENGINE_UNSUPPORTED', spec.engine.dialect === 'upstream'
+                ? 'The engine started but does not serve the model as a decision model.'
+                : 'The engine started but does not serve decision API version 1.', `${exe}: ${result.detail}`));
+        lastDetail = result.detail;
+        await sleep(deps.pollIntervalMs ?? READY_POLL_INTERVAL_MS);
+    }
+}
+//# sourceMappingURL=process.js.map

package/dist/decision/process.js.map

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

package/dist/decision/readiness.d.ts

@@ -0,0 +1,74 @@
+/**
+ * "Is this a decision model I can talk to?", the check DECISION.md prescribes for a client:
+ * `GET /health` answers 200, then `GET /v1/models` lists the `decision` capability, then
+ * `GET /props` has `decision.api_version == 1`.
+ *
+ * `/health` answers 503 while the engine loads (the HTTP server starts first), so the chain is polled
+ * until the startup deadline. Only a clear verdict from a 200 answer refuses the build: `/v1/models`
+ * without the `decision` capability, `/props` without a decision block, or another `api_version`.
+ * That is some other `llama-server` (a build that ignored `--decision`, a stranger on the port) or a
+ * future API version. Anything else on the two later requests (a transport error, a request timeout
+ * on a busy machine, a 5xx or any other non-200, a 200 that is not JSON) says nothing about the build
+ * and counts as still loading: the refusal is remembered (`DecisionEngineResolver.reject`), so it
+ * must not come from a slow answer. The parsers are pure; `checkReadiness` does one round of the
+ * chain over the injected HTTP.
+ *
+ * Upstream llama.cpp has no `/props.decision` and no `decision` capability: its `/v1/models` entry
+ * carries `architecture.output_modalities`, `["decisions"]` for a decision model and `["text"]` for
+ * anything else. So an upstream process is ready once `/v1/models` lists `decisions`, and its props
+ * are filled in by the core (`upstreamProps`): the request contract it shares with the fork, the one
+ * endpoint it serves, and whether it reads images.
+ */
+import type { DecisionCapability, DecisionDialect, DecisionProps } from '../contracts/index.js';
+import type { DecisionHttp } from './http.js';
+export declare const HEALTH_PATH = "/health";
+export declare const MODELS_PATH = "/v1/models";
+export declare const PROPS_PATH = "/props";
+/** Each readiness request on its own; the startup deadline bounds the whole wait. */
+export declare const READINESS_REQUEST_TIMEOUT_MS = 2000;
+/**
+ * Every capability the model list names. Real servers answer `{data: [...]}` (OpenAI) and newer
+ * builds also `{models: [...]}`; both are read, and the union is kept.
+ */
+export declare function capabilitiesOf(body: unknown): DecisionCapability[];
+/** The `decision` block of `/props`, when it has a numeric `api_version`. Unknown fields are kept. */
+export declare function decisionPropsOf(body: unknown): DecisionProps | undefined;
+export type ReadinessResult = {
+    kind: 'loading';
+    detail: string;
+} | {
+    kind: 'ready';
+    props: DecisionProps;
+    capabilities: DecisionCapability[];
+} | {
+    kind: 'unsupported';
+    detail: string;
+};
+/**
+ * The verdict on the two answers after health: pure, so every refusal is tested without a server.
+ * `status: 0` is a transport error (its `text` the message). Only a 200 that parses as JSON can
+ * refuse; every other answer is `loading`.
+ */
+export declare function judgeDecisionEndpoint(models: {
+    status: number;
+    text: string;
+}, props: {
+    status: number;
+    text: string;
+}): ReadinessResult;
+/** What an upstream decision process serves: `/v1/systemone` only, no router. */
+export declare const UPSTREAM_DECISION_ENDPOINTS: readonly string[];
+/** The first `data` entry's `architecture.<key>` (upstream b11370 on); `[]` when there is none. */
+export declare function modalitiesOf(body: unknown, key: 'input_modalities' | 'output_modalities'): string[];
+/** The props the core stands in for an upstream process, which has no `/props.decision`. */
+export declare function upstreamProps(body: unknown): DecisionProps;
+/** The verdict on an upstream `/v1/models` answer after health. Pure, like `judgeDecisionEndpoint`. */
+export declare function judgeUpstreamDecisionEndpoint(models: {
+    status: number;
+    text: string;
+}): ReadinessResult;
+/**
+ * One round of the chain against `baseUrl`. A transport error or a request timeout is "still
+ * loading": the port may not be bound yet, or the engine is too busy loading to answer in time.
+ */
+export declare function checkReadiness(http: DecisionHttp, baseUrl: string, apiKey: string, timeoutMs?: number, dialect?: DecisionDialect): Promise<ReadinessResult>;

package/dist/decision/readiness.js

@@ -0,0 +1,165 @@
+/**
+ * "Is this a decision model I can talk to?", the check DECISION.md prescribes for a client:
+ * `GET /health` answers 200, then `GET /v1/models` lists the `decision` capability, then
+ * `GET /props` has `decision.api_version == 1`.
+ *
+ * `/health` answers 503 while the engine loads (the HTTP server starts first), so the chain is polled
+ * until the startup deadline. Only a clear verdict from a 200 answer refuses the build: `/v1/models`
+ * without the `decision` capability, `/props` without a decision block, or another `api_version`.
+ * That is some other `llama-server` (a build that ignored `--decision`, a stranger on the port) or a
+ * future API version. Anything else on the two later requests (a transport error, a request timeout
+ * on a busy machine, a 5xx or any other non-200, a 200 that is not JSON) says nothing about the build
+ * and counts as still loading: the refusal is remembered (`DecisionEngineResolver.reject`), so it
+ * must not come from a slow answer. The parsers are pure; `checkReadiness` does one round of the
+ * chain over the injected HTTP.
+ *
+ * Upstream llama.cpp has no `/props.decision` and no `decision` capability: its `/v1/models` entry
+ * carries `architecture.output_modalities`, `["decisions"]` for a decision model and `["text"]` for
+ * anything else. So an upstream process is ready once `/v1/models` lists `decisions`, and its props
+ * are filled in by the core (`upstreamProps`): the request contract it shares with the fork, the one
+ * endpoint it serves, and whether it reads images.
+ */
+import { DECISION_API_VERSION } from '../contracts/index.js';
+export const HEALTH_PATH = '/health';
+export const MODELS_PATH = '/v1/models';
+export const PROPS_PATH = '/props';
+/** Each readiness request on its own; the startup deadline bounds the whole wait. */
+export const READINESS_REQUEST_TIMEOUT_MS = 2_000;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Every capability the model list names. Real servers answer `{data: [...]}` (OpenAI) and newer
+ * builds also `{models: [...]}`; both are read, and the union is kept.
+ */
+export function capabilitiesOf(body) {
+    if (!isRecord(body))
+        return [];
+    const found = new Set();
+    for (const key of ['data', 'models']) {
+        const list = body[key];
+        if (!Array.isArray(list))
+            continue;
+        for (const entry of list) {
+            const caps = isRecord(entry) ? entry['capabilities'] : undefined;
+            if (Array.isArray(caps))
+                for (const cap of caps)
+                    if (typeof cap === 'string')
+                        found.add(cap);
+        }
+    }
+    return [...found];
+}
+/** The `decision` block of `/props`, when it has a numeric `api_version`. Unknown fields are kept. */
+export function decisionPropsOf(body) {
+    if (!isRecord(body))
+        return undefined;
+    const block = body['decision'];
+    if (!isRecord(block) || typeof block['api_version'] !== 'number')
+        return undefined;
+    return block;
+}
+/**
+ * The verdict on the two answers after health: pure, so every refusal is tested without a server.
+ * `status: 0` is a transport error (its `text` the message). Only a 200 that parses as JSON can
+ * refuse; every other answer is `loading`.
+ */
+export function judgeDecisionEndpoint(models, props) {
+    const modelsBody = models.status === 200 ? parseJson(models.text) : undefined;
+    if (modelsBody === undefined)
+        return { kind: 'loading', detail: notAVerdict(MODELS_PATH, models) };
+    const capabilities = capabilitiesOf(modelsBody);
+    if (!capabilities.includes('decision'))
+        return {
+            kind: 'unsupported',
+            detail: `${MODELS_PATH} does not list the "decision" capability (got ${JSON.stringify(capabilities)})`,
+        };
+    const propsBody = props.status === 200 ? parseJson(props.text) : undefined;
+    if (propsBody === undefined)
+        return { kind: 'loading', detail: notAVerdict(PROPS_PATH, props) };
+    const decision = decisionPropsOf(propsBody);
+    if (!decision)
+        return { kind: 'unsupported', detail: `${PROPS_PATH} has no decision block` };
+    if (decision.api_version !== DECISION_API_VERSION)
+        return {
+            kind: 'unsupported',
+            detail: `${PROPS_PATH} reports decision api_version ${decision.api_version}, this core speaks ${DECISION_API_VERSION}`,
+        };
+    return { kind: 'ready', props: decision, capabilities };
+}
+/** What an upstream decision process serves: `/v1/systemone` only, no router. */
+export const UPSTREAM_DECISION_ENDPOINTS = ['/v1/systemone'];
+/** The first `data` entry's `architecture.<key>` (upstream b11370 on); `[]` when there is none. */
+export function modalitiesOf(body, key) {
+    const list = isRecord(body) ? body['data'] : undefined;
+    if (!Array.isArray(list))
+        return [];
+    for (const entry of list) {
+        const arch = isRecord(entry) ? entry['architecture'] : undefined;
+        const values = isRecord(arch) ? arch[key] : undefined;
+        if (Array.isArray(values))
+            return values.filter((v) => typeof v === 'string');
+    }
+    return [];
+}
+/** The props the core stands in for an upstream process, which has no `/props.decision`. */
+export function upstreamProps(body) {
+    const list = isRecord(body) ? body['data'] : undefined;
+    const first = Array.isArray(list) && isRecord(list[0]) ? list[0] : undefined;
+    const id = typeof first?.['id'] === 'string' ? first['id'] : undefined;
+    return {
+        api_version: DECISION_API_VERSION,
+        endpoints: [...UPSTREAM_DECISION_ENDPOINTS],
+        source: 'gguf',
+        ...(id !== undefined ? { model_id: id } : {}),
+        input_modalities: modalitiesOf(body, 'input_modalities'),
+    };
+}
+/** The verdict on an upstream `/v1/models` answer after health. Pure, like `judgeDecisionEndpoint`. */
+export function judgeUpstreamDecisionEndpoint(models) {
+    const body = models.status === 200 ? parseJson(models.text) : undefined;
+    if (body === undefined)
+        return { kind: 'loading', detail: notAVerdict(MODELS_PATH, models) };
+    const outputs = modalitiesOf(body, 'output_modalities');
+    if (!outputs.includes('decisions'))
+        return {
+            kind: 'unsupported',
+            detail: `${MODELS_PATH} does not list the "decisions" output modality (got ${JSON.stringify(outputs)})`,
+        };
+    return { kind: 'ready', props: upstreamProps(body), capabilities: ['decision', 'systemone'] };
+}
+/** Why an answer is not a verdict, for the timeout's details. */
+function notAVerdict(path, answer) {
+    if (answer.status === 0)
+        return `${path}: ${answer.text}`;
+    if (answer.status !== 200)
+        return `${path} answered ${answer.status}`;
+    return `${path} answered 200 with a body that is not JSON`;
+}
+/**
+ * One round of the chain against `baseUrl`. A transport error or a request timeout is "still
+ * loading": the port may not be bound yet, or the engine is too busy loading to answer in time.
+ */
+export async function checkReadiness(http, baseUrl, apiKey, timeoutMs = READINESS_REQUEST_TIMEOUT_MS, dialect = 'turboquant') {
+    const get = (path) => http.request(`${baseUrl}${path}`, { method: 'GET', apiKey, timeoutMs }).catch((error) => ({
+        status: 0,
+        text: error instanceof Error ? error.message : String(error),
+    }));
+    const health = await get(HEALTH_PATH);
+    if (health.status !== 200)
+        return {
+            kind: 'loading',
+            detail: health.status === 0 ? health.text : `${HEALTH_PATH} answered ${health.status}`,
+        };
+    if (dialect === 'upstream')
+        return judgeUpstreamDecisionEndpoint(await get(MODELS_PATH));
+    const [models, props] = [await get(MODELS_PATH), await get(PROPS_PATH)];
+    return judgeDecisionEndpoint(models, props);
+}
+//# sourceMappingURL=readiness.js.map

package/dist/decision/readiness.js.map

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

package/dist/decision/request.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The control API's decision bodies, checked just enough to build an engine request. Pure.
+ *
+ * Only the shape the core itself relies on is checked here (strings, a list, an object). The rules of
+ * the engine (card schema, candidate ids, option counts) stay the engine's: it answers them with a
+ * precise reason and JSON path, which the caller gets back in the outcome's `error`. Duplicating them
+ * would only give two answers that can drift apart.
+ */
+import type { DecisionDecideRequest, DecisionScoreRequest } from '../contracts/index.js';
+export declare function parseScoreRequest(body: unknown): DecisionScoreRequest;
+export declare function parseDecideRequest(body: unknown): DecisionDecideRequest;