@atomic-chat/core 0.5.1 → 0.13.2

package/dist/decision/request.js

@@ -0,0 +1,56 @@
+/**
+ * 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 { AtomicCoreError } from '../contracts/index.js';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function bad(message, details) {
+    return new AtomicCoreError('INVALID_ARGUMENT', message, details);
+}
+function common(body) {
+    const out = {};
+    const truncation = body['truncation'];
+    if (truncation !== undefined) {
+        if (truncation !== 'allow' && truncation !== 'error')
+            throw bad('\'truncation\' must be "allow" or "error".');
+        out.truncation = truncation;
+    }
+    const timeout = body['timeout_ms'];
+    if (timeout !== undefined) {
+        if (typeof timeout !== 'number' || !Number.isInteger(timeout) || timeout < 1 || timeout > 60_000)
+            throw bad("'timeout_ms' must be an integer from 1 to 60000.");
+        out.timeout_ms = timeout;
+    }
+    return out;
+}
+export function parseScoreRequest(body) {
+    if (!isRecord(body))
+        throw bad('The request body must be a JSON object.');
+    const { task, criterion, candidates } = body;
+    if (typeof task !== 'string')
+        throw bad("'task' must be a string.");
+    if (typeof criterion !== 'string')
+        throw bad("'criterion' must be a string.");
+    if (!Array.isArray(candidates) || !candidates.every(isRecord))
+        throw bad("'candidates' must be a list of objects ({id, card}).");
+    return { task, criterion, candidates: candidates, ...common(body) };
+}
+export function parseDecideRequest(body) {
+    if (!isRecord(body))
+        throw bad('The request body must be a JSON object.');
+    if (!('state' in body) || body['state'] === null)
+        throw bad("'state' is required.");
+    const questions = body['questions'];
+    if (!isRecord(questions) || !Object.values(questions).every(isRecord))
+        throw bad("'questions' must be an object of question objects.");
+    return {
+        state: body['state'],
+        questions: questions,
+        ...common(body),
+    };
+}
+//# sourceMappingURL=request.js.map

package/dist/decision/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/decision/request.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AASvD,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAgC,EAAE,CAC5D,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAE1D,SAAS,GAAG,CAAC,OAAe,EAAE,OAAgB;IAC5C,OAAO,IAAI,eAAe,CAAC,kBAAkB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AAClE,CAAC;AAED,SAAS,MAAM,CAAC,IAA6B;IAC3C,MAAM,GAAG,GAA6D,EAAE,CAAA;IACxE,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,CAAA;IACrC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,OAAO;YAClD,MAAM,GAAG,CAAC,4CAA4C,CAAC,CAAA;QACzD,GAAG,CAAC,UAAU,GAAG,UAAU,CAAA;IAC7B,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,CAAA;IAClC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,MAAM;YAC9F,MAAM,GAAG,CAAC,kDAAkD,CAAC,CAAA;QAC/D,GAAG,CAAC,UAAU,GAAG,OAAO,CAAA;IAC1B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,GAAG,CAAC,yCAAyC,CAAC,CAAA;IACzE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,CAAA;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC,0BAA0B,CAAC,CAAA;IACnE,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC,+BAA+B,CAAC,CAAA;IAC7E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC3D,MAAM,GAAG,CAAC,sDAAsD,CAAC,CAAA;IACnE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,UAA+B,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;AAC1F,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,GAAG,CAAC,yCAAyC,CAAC,CAAA;IACzE,IAAI,CAAC,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI;QAAE,MAAM,GAAG,CAAC,sBAAsB,CAAC,CAAA;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAA;IACnC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;QACnE,MAAM,GAAG,CAAC,oDAAoD,CAAC,CAAA;IACjE,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC;QACpB,SAAS,EAAE,SAA6C;QACxD,GAAG,MAAM,CAAC,IAAI,CAAC;KAChB,CAAA;AACH,CAAC"}

package/dist/decision/service.d.ts

@@ -0,0 +1,202 @@
+/**
+ * The decision module's surface: one decision `llama-server` at most (the fork's `--decision`, or
+ * stock llama.cpp for an upstream decision GGUF), its lifecycle, and the calls the rest of the core
+ * makes to it.
+ *
+ * Outside the sessions registry on purpose (ADR 2026-09-30-the-decision-model-is-its-own-core-module):
+ * a chat model switch unloads every other local session and the chat auto-unload policy would treat
+ * the decision model as one more text model, while the router must stay up across both. So nothing
+ * here is a `LocalRuntime`; the module borrows only process mechanics.
+ *
+ * What it guarantees:
+ *  - `scoreCandidates` and `decide` never throw and never wait longer than their budget (2 s by
+ *    default): every failure is `{unavailable: true, reason}`, and the caller keeps its default policy;
+ *  - start and stop are serialized, and a stop aborts a start still waiting for readiness;
+ *  - a process that dies after it was ready is restarted with backoff, at most `MAX_RESTARTS` times in
+ *    a row; a start that fails is not retried until a setting changes, `load` is asked for, or a
+ *    TurboQuant or llama.cpp build is installed (`onEnginesChanged`); an `unsupported` module is also retried in
+ *    the background by a call, at most once per `UNSUPPORTED_RETRY_MS`, quietly (no `starting` on the
+ *    way, and no event at all when it lands where it was);
+ *  - the engine builds readiness refused are tried again after each of those three triggers (a build
+ *    installed, `load`, a launch setting changed), but not by a background retry;
+ *  - every state change is a `decision:state` event, and a failure nobody awaits a `decision:error`.
+ */
+import type { CoreEvents, DecisionEngineInfo, DecisionOutcome, DecisionQuestion, DecisionSettings, DecisionStatus, DecisionTruncation, RouterCandidate, RouterScoreResponse, SystemoneResponse } from '../contracts/index.js';
+import type { DecisionModelSource } from '../models/index.js';
+import type { DecisionBackend } from '../server/index.js';
+import type { ThreadFacts } from './args.js';
+import type { EngineRequirements } from './engine.js';
+import type { DecisionModelFacts } from './model-facts.js';
+import type { DecisionHttp } from './http.js';
+import type { DecisionProcessHandle, DecisionServerSpec } from './process.js';
+export declare const ROUTER_SCORE_PATH = "/v1/router/score";
+export declare const SYSTEMONE_PATH = "/v1/systemone";
+/**
+ * How often a call may retry an `unsupported` module in the background. The state only clears when
+ * a build that serves `--decision` appears on disk; an install through this core says so at once
+ * (`onEnginesChanged`), this catches one made by anything else. Each retry costs a directory scan
+ * and, for a pack not probed yet, one `-h`.
+ */
+export declare const UNSUPPORTED_RETRY_MS: number;
+export type DecisionEmitter = <K extends 'decision:state' | 'decision:error'>(name: K, payload: CoreEvents[K]) => void;
+export type DecisionLogger = (level: 'info' | 'warn' | 'debug', msg: string) => void;
+export interface DecisionCallOptions {
+    /** Overrides `settings.decision.timeout_ms` for this call. */
+    timeoutMs?: number;
+    /** The caller gave up; the call answers `aborted` at once. */
+    signal?: AbortSignal;
+    truncation?: DecisionTruncation;
+}
+export interface DecisionServiceDeps {
+    /** The core's data folder: relative model and spec paths are resolved against it. */
+    dataFolder: string;
+    readSettings: () => DecisionSettings;
+    /** A checked write of the `decision` settings section (`SettingsStore.updateDecision`). */
+    writeSettings: (patch: Record<string, unknown>) => Promise<unknown>;
+    /** The engine gate (`DecisionEngineResolver.resolve`). */
+    resolveEngine: (enginePath: string, needs?: EngineRequirements) => Promise<DecisionEngineInfo>;
+    /**
+     * A resolved build started but readiness refused it (`DECISION_ENGINE_UNSUPPORTED`, for example
+     * API version 2): the gate skips it from now on (`DecisionEngineResolver.reject`), and the start
+     * resolves again. Without it the first refusal ends the start.
+     */
+    rejectEngine?: (exe: string, why: string) => Promise<void>;
+    /**
+     * Try every build `rejectEngine` refused again (`DecisionEngineResolver.forgetRejected`): called when
+     * a build is installed, on an explicit `load`, and on a start with other launch settings.
+     */
+    forgetRejectedEngines?: () => void;
+    /** CPU facts for the automatic thread count. */
+    cpu: () => Promise<Omit<ThreadFacts, 'setting'>>;
+    /** Start one process and wait for readiness (`spawnDecisionServer` plus the journal). */
+    spawn: (spec: DecisionServerSpec, signal: AbortSignal) => Promise<DecisionProcessHandle>;
+    http: DecisionHttp;
+    emit: DecisionEmitter;
+    log: DecisionLogger;
+    now?: () => number;
+    /** Whether the spec file exists. */
+    fileExists?: (path: string) => Promise<boolean>;
+    /** What the model path is: a GGUF file, a checkpoint folder, or nothing. */
+    inspectModel?: (path: string) => Promise<DecisionModelSource>;
+    /** Which engine a GGUF needs, from its header (`readDecisionModelFacts`). */
+    readModelFacts?: (path: string) => Promise<DecisionModelFacts>;
+    /** Where checkpoint folders are converted to. Default: `<dataFolder>/decision/gguf-cache`. */
+    convertCacheDir?: string;
+    /**
+     * Delete every entry of the conversion cache but `keep` (a key folder name; none = all). The engine
+     * never deletes a cache entry, and an entry is as large as the model.
+     */
+    pruneConvertCache?: (cacheDir: string, keep: string | undefined) => Promise<void>;
+    /** Run `fn` after `ms`; returns the cancel. The default timer never keeps the process alive. */
+    schedule?: (fn: () => void, ms: number) => () => void;
+}
+export declare class DecisionService {
+    private readonly deps;
+    private state;
+    private handle;
+    private runningKey;
+    /** `launchKey` of the start in flight, from the moment it read the settings. */
+    private loadingKey;
+    private readySince;
+    /** `launchKey` of the last start: a start with another one tries the refused builds again. */
+    private lastLaunchKey;
+    /** When a call last retried an `unsupported` module; a quiet retry that changes nothing emits nothing. */
+    private lastQuietRetry;
+    /** The provider the configured model last needed: an install of another one cannot help it. */
+    private neededProvider;
+    private loading;
+    private loadAbort;
+    private cancelRestart;
+    private cancelIdle;
+    private inFlight;
+    private stopping;
+    /** Called on every state change and when a start settles: the public route's waits. */
+    private readonly waiters;
+    /** Start and stop, one at a time. */
+    private chain;
+    private readonly now;
+    private readonly schedule;
+    private readonly convertCacheDir;
+    constructor(deps: DecisionServiceDeps);
+    /** Called once by the owner: an enabled and configured module starts in the background. */
+    start(): void;
+    getStatus(): DecisionStatus;
+    getConfig(): DecisionSettings;
+    /** Write settings, then bring the process in line with them. */
+    configure(patch: Record<string, unknown>): Promise<DecisionStatus>;
+    /**
+     * After a settings change: turned off → stop; started (or starting) with other launch settings →
+     * restart; enabled and not running (idle, failed, unsupported) → start in the background. The crash
+     * count starts over. A change that does not touch the launch (`timeout_ms`, `idle_unload_secs`, …)
+     * leaves a running process or a start in flight alone; `idle_unload_secs` takes effect at once.
+     */
+    reconcile(): Promise<DecisionStatus>;
+    /**
+     * A TurboQuant or llama.cpp build was installed: a module that is `unsupported` or `failed` tries
+     * again, since the new build may be the first that serves the model (`--decision`, or an upstream
+     * build at the model's floor). Any other state is left as it is, and so is everything when
+     * `provider` is not the one the model needs (known once a start has read the model).
+     */
+    onEnginesChanged(provider?: string): Promise<DecisionStatus>;
+    /**
+     * Start now (or join the start in flight) and answer once it is ready; a failure is thrown. A new
+     * start tries again every engine build readiness refused before: the user asked for it.
+     */
+    load(): Promise<DecisionStatus>;
+    /** Stop the process (or the start in flight). The module stays enabled: the next call starts it again. */
+    unload(): Promise<DecisionStatus>;
+    /**
+     * `POST /v1/router/score`: independent, calibrated `p_success` per candidate. Fail-open: never
+     * throws, never waits past the budget.
+     */
+    scoreCandidates(task: string, criterion: string, candidates: RouterCandidate[], options?: DecisionCallOptions): Promise<DecisionOutcome<RouterScoreResponse>>;
+    /** `POST /v1/systemone`: TypeSafe-style questions about `state`. Fail-open like `scoreCandidates`. */
+    decide(state: unknown, questions: Record<string, DecisionQuestion>, options?: DecisionCallOptions): Promise<DecisionOutcome<SystemoneResponse>>;
+    /** What the public server forwards `/systemone` and `/router/score` to. */
+    publicBackend(): DecisionBackend;
+    /** Stop everything for good: timers, a start in flight, the process. No events after this. */
+    shutdown(): Promise<void>;
+    private setState;
+    private notifyWaiters;
+    private serial;
+    /**
+     * `quietCode`: a background retry of a state the app already heard about. A failure with this code
+     * is not reported again, and the start shows no `starting` on its way (see `startProcess`).
+     */
+    private startInBackground;
+    /** An `unsupported` module whose state is older than `UNSUPPORTED_RETRY_MS` tries again, quietly. */
+    private retryUnsupported;
+    /** Fire and forget: a cache that cannot be cleaned costs disk space, never a start. */
+    private pruneConvertCache;
+    private reportUnawaited;
+    private ensureLoaded;
+    /**
+     * `quiet`: a background retry of an `unsupported` module. It does not announce `starting` (the app
+     * would flash a start for every retry that finds nothing new) and, when it fails the same way again,
+     * leaves the state as it was without an event. A retry that gets further is reported as usual.
+     */
+    private startProcess;
+    /**
+     * Resolve an engine and spawn it; a build that readiness refuses as unsupported (an API version this
+     * core does not speak, a dev build with an unfinished decision API) or that dies while loading is
+     * handed to `rejectEngine` and the next one is tried, so a valid lower-ranked build still runs
+     * (`spawnOnFirstGoodEngine`). An explicit `engine_path` has nothing to fall back to.
+     */
+    private spawnOnFirstGoodEngine;
+    private onExit;
+    private onRestartFailed;
+    private scheduleRestart;
+    private stopProcess;
+    /** (Re)arm the idle unload; a call in flight pushes it back. */
+    private armIdle;
+    private call;
+    /**
+     * The public route's target. An enabled, configured module that is idle is started (a failure is a
+     * `decision:error`, as for a call); one that is starting or restarting is waited on, up to `waitMs`,
+     * until it is ready or lands in a state no start will leave (failed, unsupported, disabled), or the
+     * client leaves (`signal`).
+     */
+    private acquire;
+    /** The handle once there is one; `undefined` on timeout, on `signal`, or once no start is on its way. */
+    private waitForHandle;
+}