@cleocode/core 2026.9.20 → 2026.9.21

package/dist/decide/client.js

@@ -0,0 +1,262 @@
+/**
+ * Typed-decision client — the one entry point CLEO call sites use for
+ * "System One" decisions.
+ *
+ * `decide(siteId, req, fallback, opts)` ALWAYS resolves with a
+ * {@link DecisionOutcome}; it never rejects because of the provider. The
+ * pipeline is:
+ *
+ * 1. No provider configured → the site's heuristic (`source: 'fallback'`).
+ * 2. Redact the state through the memory redaction module, then validate the
+ *    request with the contract schema (invalid → fallback).
+ * 3. In-memory LRU cache hit → `source: 'cache'`.
+ * 4. Within ONE per-site deadline (default {@link DEFAULT_DECISION_TIMEOUT_MS}):
+ *    take a token from the machine-wide budget, then call the provider.
+ *    Budget denial, timeout, 401/402/429/5xx, network failure or a malformed
+ *    answer → fallback. A 429 also empties the shared budget for its
+ *    `retry-after` so no other process piles on.
+ * 5. Append one audit line (never containing the key or raw state).
+ *
+ * Provider-specific knowledge (endpoints, wire JSON) lives only in
+ * `./jev-wire.ts`; this module sees the {@link DecisionProvider} port.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import { decisionOutcomeSchema, decisionProviderConfigSchema, decisionRequestSchema, } from '@cleocode/contracts';
+import { redactContent } from '../memory/redaction.js';
+import { getProjectRoot } from '../paths.js';
+import { auditAnswers, createJsonlDecisionAudit, } from './audit.js';
+import { createFileTokenBucket } from './budget.js';
+import { createDecisionCache, decisionCacheKey, hashCanonical, } from './cache.js';
+import { loadDecideConnection } from './credentials.js';
+import { createJevProvider, JEV_ADAPTER_VERSION } from './jev-wire.js';
+import { DecisionProviderError, } from './provider.js';
+/** Default per-site deadline for the budget + provider round trip, in ms. */
+export const DEFAULT_DECISION_TIMEOUT_MS = 300;
+let defaultCache = null;
+let defaultBudget = null;
+function processCache() {
+    defaultCache ??= createDecisionCache();
+    return defaultCache;
+}
+function processBudget() {
+    defaultBudget ??= createFileTokenBucket();
+    return defaultBudget;
+}
+/**
+ * Reset the process-default cache and budget. Tests only.
+ *
+ * @internal
+ */
+export function _resetDecideDefaultsForTest() {
+    defaultCache = null;
+    defaultBudget = null;
+}
+function redactJson(value) {
+    if (typeof value === 'string')
+        return redactContent(value).content;
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(redactJson);
+    const out = {};
+    for (const [k, v] of Object.entries(value))
+        out[k] = redactJson(v);
+    return out;
+}
+/**
+ * Scrub secrets from a decision state before it leaves the machine, using the
+ * shared memory redaction patterns. Strings are redacted in place; structured
+ * state is redacted leaf by leaf so it stays valid JSON.
+ *
+ * @param state - Raw state.
+ * @returns Redacted state of the same shape.
+ */
+export function redactDecisionState(state) {
+    if (typeof state === 'string')
+        return redactContent(state).content;
+    if (Array.isArray(state))
+        return state.map(redactJson);
+    const out = {};
+    for (const [k, v] of Object.entries(state))
+        out[k] = redactJson(v);
+    return out;
+}
+/** The explicit connection, or — when none was passed — the stored one. */
+function resolveConnection(opts) {
+    if (opts.connection !== undefined)
+        return opts.connection;
+    if (opts.provider)
+        return null;
+    return loadDecideConnection()?.connection() ?? null;
+}
+function resolveProvider(opts, connection) {
+    if (opts.provider)
+        return opts.provider;
+    if (!connection || connection.apiKey.trim() === '')
+        return null;
+    if (!decisionProviderConfigSchema.safeParse({ baseUrl: connection.baseUrl }).success)
+        return null;
+    return createJevProvider(connection);
+}
+function resolveAudit(opts) {
+    if (opts.audit !== undefined)
+        return opts.audit;
+    try {
+        return createJsonlDecisionAudit(opts.projectRoot ?? getProjectRoot());
+    }
+    catch {
+        return null;
+    }
+}
+function reasonForError(err) {
+    switch (err.kind) {
+        case 'aborted':
+            return 'timeout';
+        case 'invalid_request':
+            return 'invalid_request';
+        default:
+            return err.kind;
+    }
+}
+/** True when `outcome` is contract-valid and answers every question with the right type. */
+function coversRequest(outcome, req) {
+    if (!decisionOutcomeSchema.safeParse(outcome).success)
+        return false;
+    return Object.entries(req.questions).every(([name, q]) => outcome.answers[name]?.type === q.type);
+}
+/** Budget + provider call; never rejects. */
+async function attempt(provider, budget, req, signal) {
+    if (budget) {
+        const grant = await budget.tryAcquire();
+        if (!grant.granted) {
+            return {
+                ok: false,
+                reason: grant.reason === 'exhausted'
+                    ? 'budget_exhausted'
+                    : grant.reason === 'cooling_down'
+                        ? 'budget_cooling_down'
+                        : 'budget_unavailable',
+            };
+        }
+    }
+    if (signal.aborted)
+        return { ok: false, reason: 'timeout' };
+    try {
+        const outcome = await provider.decide(req, signal);
+        if (!coversRequest(outcome, req))
+            return { ok: false, reason: 'invalid_response' };
+        return { ok: true, outcome };
+    }
+    catch (err) {
+        if (err instanceof DecisionProviderError) {
+            if (err.kind === 'rate_limited' && budget)
+                await budget.penalize(err.retryAfterMs);
+            return { ok: false, reason: reasonForError(err) };
+        }
+        return { ok: false, reason: signal.aborted ? 'timeout' : 'provider_error' };
+    }
+}
+/**
+ * Run `attempt` under a hard deadline. Resolves at the latest when the
+ * deadline or the caller's signal fires, even if the provider ignores its
+ * abort signal.
+ */
+function withDeadline(run, timeoutMs, callerSignal) {
+    const controller = new AbortController();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            callerSignal?.removeEventListener('abort', onCallerAbort);
+            resolve(result);
+        };
+        const onTimeout = () => {
+            controller.abort();
+            finish({ ok: false, reason: 'timeout' });
+        };
+        const onCallerAbort = () => onTimeout();
+        const timer = setTimeout(onTimeout, Math.max(0, timeoutMs));
+        if (callerSignal?.aborted) {
+            onTimeout();
+            return;
+        }
+        callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+        run(controller.signal).then(finish, () => finish({ ok: false, reason: 'provider_error' }));
+    });
+}
+/**
+ * Ask a typed decision at call site `siteId`.
+ *
+ * Never rejects on provider trouble: when the provider is unconfigured,
+ * over budget, slow, failing or wrong, the site's `fallback` heuristic answers
+ * and the outcome carries `source: 'fallback'`.
+ *
+ * @param siteId - Stable call-site identifier (audited; used for per-site tuning).
+ * @param req - Questions and state.
+ * @param fallback - The site's heuristic; receives the original (unredacted) request.
+ * @param opts - Provider, deadline, cache, budget and audit wiring.
+ * @returns The decision outcome.
+ *
+ * @example
+ * ```ts
+ * const outcome = await decide(
+ *   'tasks.duplicate-check',
+ *   { state: text, questions: { dup: { type: 'noul', criteria: 'The two tasks describe the same work' } } },
+ *   () => ({ dup: { type: 'noul', value: false, probability: 0.2, confidence: 0.5 } }),
+ *   { connection, timeoutMs: 250 },
+ * );
+ * ```
+ */
+export async function decide(siteId, req, fallback, opts = {}) {
+    const started = performance.now();
+    const elapsed = () => Math.max(0, performance.now() - started);
+    const audit = resolveAudit(opts);
+    const connection = resolveConnection(opts);
+    const defaultModel = req.model === undefined ? connection?.model : undefined;
+    const sent = {
+        ...req,
+        ...(defaultModel ? { model: defaultModel } : {}),
+        state: redactDecisionState(req.state),
+    };
+    const questionsHash = hashCanonical(req.questions);
+    const stateHash = hashCanonical(sent.state);
+    const finish = (outcome, reason) => {
+        audit?.write({
+            timestamp: new Date().toISOString(),
+            site: siteId,
+            ...(outcome.requestId ? { requestId: outcome.requestId } : {}),
+            questionsHash,
+            stateHash,
+            answers: auditAnswers(outcome),
+            source: outcome.source,
+            ...(reason ? { fallbackReason: reason } : {}),
+            latencyMs: outcome.latencyMs,
+            ...(outcome.costUsd !== undefined ? { costUsd: outcome.costUsd } : {}),
+            ...(sent.model !== undefined ? { model: sent.model } : {}),
+        });
+        return outcome;
+    };
+    const useFallback = (reason) => finish({ answers: fallback(req), source: 'fallback', latencyMs: elapsed() }, reason);
+    const provider = resolveProvider(opts, connection);
+    if (!provider)
+        return useFallback('unconfigured');
+    if (!decisionRequestSchema.safeParse(sent).success)
+        return useFallback('invalid_request');
+    const cache = opts.cache === undefined ? processCache() : opts.cache;
+    const key = decisionCacheKey(opts.adapterVersion ?? JEV_ADAPTER_VERSION, sent);
+    const hit = cache?.get(key);
+    if (hit)
+        return finish({ ...hit, source: 'cache', latencyMs: elapsed() });
+    const budget = opts.budget === undefined ? processBudget() : opts.budget;
+    const result = await withDeadline((signal) => attempt(provider, budget, sent, signal), opts.timeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS, opts.signal);
+    if (!result.ok)
+        return useFallback(result.reason);
+    cache?.set(key, result.outcome);
+    return finish({ ...result.outcome, source: 'provider', latencyMs: elapsed() });
+}
+//# sourceMappingURL=client.js.map

package/dist/decide/client.js.map

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

package/dist/decide/credentials.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Decision-provider credential store — the two settings a user supplies
+ * (an API base URL and an API key) plus an optional default model.
+ *
+ * Stored at `<cleoHome>/decide-credentials.json` (resolved through
+ * `@cleocode/paths`, arch gate 2) with 0600 permissions:
+ *
+ * - Writes go through `withLock` (cross-process lock) and
+ *   `writeJsonFileAtomic({ mode: 0o600 })`, so neither the live file, the
+ *   temp file nor a rotated backup ever exists at a looser mode. Modelled on
+ *   `../llm/credentials-store.ts`.
+ * - The file lives at the TOP level of the CLEO home so its rotated backups
+ *   land in the owner-only `<cleoHome>/.backups/`, and the portable-bundle
+ *   scanner classifies it as a secret (see `store/portable-bundle-scan.ts`).
+ * - Reads return a {@link SealedDecideConnection}: the key sits in a private
+ *   class field, so `JSON.stringify`, `util.inspect` and template strings of
+ *   the handle only ever show a masked last-4 preview. The plaintext is
+ *   materialised solely by {@link SealedDecideConnection.connection}, which the
+ *   decision client calls at the wire.
+ *
+ * The key never lands in `config.json`, logs, LAFS envelopes or the decisions
+ * audit: nothing here logs, and every summary this module returns carries the
+ * masked preview only.
+ *
+ * @task T12491
+ * @epic T12486
+ */
+import { inspect } from 'node:util';
+import type { DecisionProviderConnection } from './provider.js';
+/** File name of the store, directly under the CLEO home. */
+export declare const DECIDE_CREDENTIALS_FILE = "decide-credentials.json";
+/** Settings accepted by {@link saveDecideCredentials}. */
+export interface DecideCredentialsInput {
+    /** Absolute provider base URL, e.g. `https://provider.example`. */
+    readonly baseUrl: string;
+    /** API key. Leading/trailing whitespace (e.g. a piped newline) is trimmed. */
+    readonly apiKey: string;
+    /** Optional default model; omitted → the request carries no model. */
+    readonly model?: string;
+}
+/** Secret-free description of the stored settings. Safe to log and to emit in envelopes. */
+export interface DecideCredentialsSummary {
+    /** True when a valid base URL and a non-blank key are stored. */
+    readonly configured: boolean;
+    /** Absolute path of the store file. */
+    readonly path: string;
+    /** Stored base URL, when present. */
+    readonly baseUrl?: string;
+    /** Stored default model, when present. */
+    readonly model?: string;
+    /** Masked key preview (`…abcd`), when a key is stored. */
+    readonly keyPreview?: string;
+    /** ISO timestamp of the last write, when known. */
+    readonly updatedAt?: string;
+}
+/**
+ * Absolute path of the decision-credential store.
+ *
+ * @returns `<cleoHome>/decide-credentials.json`.
+ */
+export declare function decideCredentialsPath(): string;
+/**
+ * Mask an API key down to its last four characters.
+ *
+ * @param apiKey - Plaintext key (read transiently, not retained).
+ * @returns `…` plus at most the last 4 characters; `…` alone for keys of 4 or fewer characters.
+ */
+export declare function maskApiKey(apiKey: string): string;
+/**
+ * Opaque handle to a stored connection. The key is held in a private field;
+ * serialising or inspecting the handle yields the masked preview only.
+ */
+export declare class SealedDecideConnection {
+    #private;
+    /** Provider base URL (not secret). */
+    readonly baseUrl: string;
+    /** Default model, when configured. */
+    readonly model?: string;
+    /** Masked key preview (`…abcd`). */
+    readonly keyPreview: string;
+    /**
+     * @param baseUrl - Provider base URL.
+     * @param apiKey - Plaintext key; captured privately.
+     * @param model - Optional default model.
+     */
+    constructor(baseUrl: string, apiKey: string, model?: string);
+    /**
+     * Materialise the wire connection. Call only where the request is built.
+     *
+     * @returns Base URL, plaintext key and optional model.
+     */
+    connection(): DecisionProviderConnection;
+    /** @returns The secret-free JSON form. */
+    toJSON(): {
+        baseUrl: string;
+        model?: string;
+        keyPreview: string;
+    };
+    /** @returns A secret-free string form. */
+    toString(): string;
+    /** Secret-free `util.inspect` / `console.log` form. */
+    [inspect.custom](): string;
+}
+/**
+ * Whether `baseUrl` is an acceptable provider URL: absolute `https://`, or
+ * plain `http://` to a loopback host (`localhost`, `127.0.0.1`, `::1`). A
+ * remote plain-http URL is rejected so the bearer key never crosses the
+ * network in clear text.
+ *
+ * @param baseUrl - Candidate base URL.
+ * @returns True when the URL may be stored and used.
+ */
+export declare function isAllowedDecideBaseUrl(baseUrl: string): boolean;
+/**
+ * Whether two base URLs address the same host (hostname + port).
+ *
+ * @param a - First URL.
+ * @param b - Second URL.
+ * @returns True when both parse and share `host`; false otherwise.
+ */
+export declare function sameDecideHost(a: string, b: string): boolean;
+/**
+ * Load the stored connection. Synchronous and total: missing, malformed or
+ * incomplete settings return `null` (the decision client then falls back to
+ * heuristics).
+ *
+ * @returns The sealed connection, or `null` when unconfigured.
+ */
+export declare function loadDecideConnection(): SealedDecideConnection | null;
+/**
+ * Describe the stored settings without the key.
+ *
+ * @returns A secret-free summary.
+ */
+export declare function describeDecideCredentials(): DecideCredentialsSummary;
+/** Error thrown by {@link saveDecideCredentials} for invalid input. The message never contains the key. */
+export declare class DecideCredentialsError extends Error {
+    /** @param message - Secret-free description. */
+    constructor(message: string);
+}
+/** Reset the once-only loose-home warning. Tests only. @internal */
+export declare function _resetDecideHomeWarningForTest(): void;
+/**
+ * Store the base URL, API key and optional model (0600, locked, atomic).
+ *
+ * @param input - Settings to store; replaces any previous settings.
+ * @returns Secret-free summary of what is now stored.
+ * @throws {DecideCredentialsError} When the URL is not https (or loopback http), the key is
+ *   blank, the model name is invalid, or the store or its backups are symlinks.
+ */
+export declare function saveDecideCredentials(input: DecideCredentialsInput): Promise<DecideCredentialsSummary>;
+/**
+ * Remove the stored settings: the store is overwritten with empty settings
+ * and every rotated backup of it (which may hold an old key) is deleted.
+ *
+ * @returns True when settings were present before the call.
+ */
+export declare function clearDecideCredentials(): Promise<boolean>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/decide/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/decide/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAaH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAEhE,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAejE,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;GAGG;AACH,qBAAa,sBAAsB;;IACjC,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAG5B;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAO3D;;;;OAIG;IACH,UAAU,IAAI,0BAA0B;IAQxC,0CAA0C;IAC1C,MAAM,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAQjE,0CAA0C;IAC1C,QAAQ,IAAI,MAAM;IAIlB,uDAAuD;IACvD,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM;CAG3B;AAmCD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAa/D;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAM5D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,sBAAsB,GAAG,IAAI,CAWpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,wBAAwB,CAYpE;AAED,2GAA2G;AAC3G,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,gDAAgD;gBACpC,OAAO,EAAE,MAAM;CAI5B;AA2DD,oEAAoE;AACpE,wBAAgB,8BAA8B,IAAI,IAAI,CAErD;AAkBD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,wBAAwB,CAAC,CAqCnC;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,OAAO,CAAC,CAW/D"}