@cleocode/core 2026.9.20 → 2026.9.22

package/dist/decide/budget.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Request budget for decision providers — a token bucket shared by every CLEO
+ * process on the machine.
+ *
+ * The provider allows 600 requests/minute per key. Every CLEO process (CLI
+ * invocations, the sentient daemon, spawned agents) draws from ONE bucket whose
+ * state lives in `<cleoHome>/decide/budget.json`, guarded by a `proper-lockfile`
+ * lock — the same cross-process state-file pattern as
+ * `llm/rate-limit-guard.ts`, with much shorter lock retries because a decision
+ * has a sub-second budget.
+ *
+ * ## Why capacity 60 + 540/min, not 600 + 600/min
+ *
+ * A bucket of capacity `C` refilled at `r` admits at most `C + r·W` requests in
+ * any window `W`. The defaults (60 + 540/min) keep every 60-second window at or
+ * under 600 even after an idle period, so the budget itself never triggers a
+ * 429. A 429 still happens if the key is shared with non-CLEO clients; then
+ * {@link DecisionBudget.penalize} empties the bucket and blocks every process
+ * until the server's `retry-after` has passed.
+ *
+ * The bucket fails CLOSED: if the lock cannot be taken quickly or the state
+ * cannot be read, the request is denied and the caller falls back to its
+ * heuristic. Exceeding the provider's limit is worse than one fallback.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+/** Default burst capacity (tokens). */
+export declare const DEFAULT_BUDGET_CAPACITY = 60;
+/** Default refill rate (tokens per minute). Capacity + refill ≤ 600 per minute. */
+export declare const DEFAULT_BUDGET_REFILL_PER_MINUTE = 540;
+/** Cool-down applied after a 429 that carried no usable `retry-after`. */
+export declare const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 10000;
+/**
+ * Longest cool-down any 429 may impose. The bucket is machine-wide, so an
+ * uncapped `retry-after: 999999999` would stop every decision on the machine
+ * for decades.
+ */
+export declare const MAX_RATE_LIMIT_COOLDOWN_MS = 60000;
+/** Result of {@link DecisionBudget.tryAcquire}. */
+export type BudgetGrant = {
+    readonly granted: true;
+} | {
+    readonly granted: false;
+    readonly reason: 'exhausted' | 'cooling_down' | 'unavailable';
+};
+/** A request budget. Implementations never throw. */
+export interface DecisionBudget {
+    /** Take one token if available. */
+    tryAcquire(): Promise<BudgetGrant>;
+    /** Empty the bucket and block all acquisitions for `retryAfterMs` (after a 429). */
+    penalize(retryAfterMs?: number): Promise<void>;
+}
+/** Bucket parameters. */
+export interface TokenBucketOptions {
+    /** Burst capacity. Default {@link DEFAULT_BUDGET_CAPACITY}. */
+    readonly capacity?: number;
+    /** Refill rate per minute. Default {@link DEFAULT_BUDGET_REFILL_PER_MINUTE}. */
+    readonly refillPerMinute?: number;
+    /** Wall clock in epoch ms (shared across processes). Default `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A process-local bucket. Useful for tests and for callers that must not touch
+ * the filesystem; it does NOT coordinate with other processes.
+ *
+ * @param opts - Bucket parameters.
+ * @returns A {@link DecisionBudget}.
+ */
+export declare function createMemoryTokenBucket(opts?: TokenBucketOptions): DecisionBudget;
+/** Options for {@link createFileTokenBucket}. */
+export interface FileTokenBucketOptions extends TokenBucketOptions {
+    /** State-file path. Default {@link defaultBudgetStatePath}. */
+    readonly statePath?: string;
+}
+/**
+ * Default location of the shared bucket state: `<cleoHome>/decide/budget.json`.
+ *
+ * @returns Absolute path.
+ */
+export declare function defaultBudgetStatePath(): string;
+/**
+ * A bucket whose state is shared by every process on the machine through a
+ * locked JSON file.
+ *
+ * @param opts - Bucket parameters and state path.
+ * @returns A {@link DecisionBudget}; `tryAcquire` resolves `unavailable` when
+ *   the lock or state file cannot be used.
+ */
+export declare function createFileTokenBucket(opts?: FileTokenBucketOptions): DecisionBudget;
+//# sourceMappingURL=budget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/decide/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,uCAAuC;AACvC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,mFAAmF;AACnF,eAAO,MAAM,gCAAgC,MAAM,CAAC;AACpD,0EAA0E;AAC1E,eAAO,MAAM,8BAA8B,QAAS,CAAC;AACrD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,mDAAmD;AACnD,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,aAAa,CAAA;CAAE,CAAC;AAE/F,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACnC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AAED,yBAAyB;AACzB,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAwDD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,GAAE,kBAAuB,GAAG,cAAc,CAWrF;AAED,iDAAiD;AACjD,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AA+CD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,sBAA2B,GAAG,cAAc,CAiCvF"}

package/dist/decide/budget.js

@@ -0,0 +1,194 @@
+/**
+ * Request budget for decision providers — a token bucket shared by every CLEO
+ * process on the machine.
+ *
+ * The provider allows 600 requests/minute per key. Every CLEO process (CLI
+ * invocations, the sentient daemon, spawned agents) draws from ONE bucket whose
+ * state lives in `<cleoHome>/decide/budget.json`, guarded by a `proper-lockfile`
+ * lock — the same cross-process state-file pattern as
+ * `llm/rate-limit-guard.ts`, with much shorter lock retries because a decision
+ * has a sub-second budget.
+ *
+ * ## Why capacity 60 + 540/min, not 600 + 600/min
+ *
+ * A bucket of capacity `C` refilled at `r` admits at most `C + r·W` requests in
+ * any window `W`. The defaults (60 + 540/min) keep every 60-second window at or
+ * under 600 even after an idle period, so the budget itself never triggers a
+ * 429. A 429 still happens if the key is shared with non-CLEO clients; then
+ * {@link DecisionBudget.penalize} empties the bucket and blocks every process
+ * until the server's `retry-after` has passed.
+ *
+ * The bucket fails CLOSED: if the lock cannot be taken quickly or the state
+ * cannot be read, the request is denied and the caller falls back to its
+ * heuristic. Exceeding the provider's limit is worse than one fallback.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getCleoHome } from '@cleocode/paths';
+import lockfile from 'proper-lockfile';
+import { z } from 'zod';
+/** Default burst capacity (tokens). */
+export const DEFAULT_BUDGET_CAPACITY = 60;
+/** Default refill rate (tokens per minute). Capacity + refill ≤ 600 per minute. */
+export const DEFAULT_BUDGET_REFILL_PER_MINUTE = 540;
+/** Cool-down applied after a 429 that carried no usable `retry-after`. */
+export const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 10_000;
+/**
+ * Longest cool-down any 429 may impose. The bucket is machine-wide, so an
+ * uncapped `retry-after: 999999999` would stop every decision on the machine
+ * for decades.
+ */
+export const MAX_RATE_LIMIT_COOLDOWN_MS = 60_000;
+function resolve(opts) {
+    return {
+        capacity: Math.max(1, opts.capacity ?? DEFAULT_BUDGET_CAPACITY),
+        refillPerMs: Math.max(0, opts.refillPerMinute ?? DEFAULT_BUDGET_REFILL_PER_MINUTE) / 60_000,
+        now: opts.now ?? Date.now,
+    };
+}
+/** Apply refill + one acquisition to `state` (mutates) and report the outcome. */
+function take(state, bucket) {
+    const now = bucket.now();
+    // A cool-down beyond the cap can only come from a state file written before
+    // the cap existed; honour at most the cap from when it was imposed.
+    state.blockedUntil = Math.min(state.blockedUntil, state.updatedAt + MAX_RATE_LIMIT_COOLDOWN_MS);
+    if (now < state.blockedUntil)
+        return { granted: false, reason: 'cooling_down' };
+    const elapsed = Math.max(0, now - state.updatedAt);
+    state.tokens = Math.min(bucket.capacity, state.tokens + elapsed * bucket.refillPerMs);
+    state.updatedAt = now;
+    if (state.tokens < 1)
+        return { granted: false, reason: 'exhausted' };
+    state.tokens -= 1;
+    return { granted: true };
+}
+function penalizeState(state, bucket, retryAfterMs) {
+    const now = bucket.now();
+    const wait = Math.min(MAX_RATE_LIMIT_COOLDOWN_MS, retryAfterMs !== undefined && retryAfterMs >= 0 ? retryAfterMs : DEFAULT_RATE_LIMIT_COOLDOWN_MS);
+    state.tokens = 0;
+    state.updatedAt = now;
+    state.blockedUntil = Math.max(state.blockedUntil, now + wait);
+}
+function freshState(bucket) {
+    return { tokens: bucket.capacity, updatedAt: bucket.now(), blockedUntil: 0 };
+}
+/**
+ * A process-local bucket. Useful for tests and for callers that must not touch
+ * the filesystem; it does NOT coordinate with other processes.
+ *
+ * @param opts - Bucket parameters.
+ * @returns A {@link DecisionBudget}.
+ */
+export function createMemoryTokenBucket(opts = {}) {
+    const bucket = resolve(opts);
+    const state = freshState(bucket);
+    return {
+        async tryAcquire() {
+            return take(state, bucket);
+        },
+        async penalize(retryAfterMs) {
+            penalizeState(state, bucket, retryAfterMs);
+        },
+    };
+}
+/**
+ * Default location of the shared bucket state: `<cleoHome>/decide/budget.json`.
+ *
+ * @returns Absolute path.
+ */
+export function defaultBudgetStatePath() {
+    return join(getCleoHome(), 'decide', 'budget.json');
+}
+/** Short lock retries: the whole decision has a sub-second budget. */
+const LOCK_OPTIONS = {
+    realpath: false,
+    stale: 2_000,
+    retries: { retries: 4, factor: 1.5, minTimeout: 5, maxTimeout: 25 },
+};
+/** Schema of the persisted state; anything else is treated as corrupt. */
+const bucketStateSchema = z.object({
+    tokens: z.number(),
+    updatedAt: z.number(),
+    blockedUntil: z.number(),
+});
+function readState(path, bucket) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return freshState(bucket);
+    }
+    try {
+        const parsed = bucketStateSchema.safeParse(JSON.parse(raw));
+        // A corrupt file resets to an EMPTY bucket, not a full one: fail closed.
+        return parsed.success ? parsed.data : { tokens: 0, updatedAt: bucket.now(), blockedUntil: 0 };
+    }
+    catch {
+        return { tokens: 0, updatedAt: bucket.now(), blockedUntil: 0 };
+    }
+}
+function writeState(path, state) {
+    const tmp = join(dirname(path), `.budget.${randomBytes(6).toString('hex')}.tmp`);
+    writeFileSync(tmp, JSON.stringify(state), 'utf-8');
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
+/**
+ * A bucket whose state is shared by every process on the machine through a
+ * locked JSON file.
+ *
+ * @param opts - Bucket parameters and state path.
+ * @returns A {@link DecisionBudget}; `tryAcquire` resolves `unavailable` when
+ *   the lock or state file cannot be used.
+ */
+export function createFileTokenBucket(opts = {}) {
+    const bucket = resolve(opts);
+    const statePath = opts.statePath ?? defaultBudgetStatePath();
+    async function withState(mutate) {
+        mkdirSync(dirname(statePath), { recursive: true });
+        const release = await lockfile.lock(statePath, LOCK_OPTIONS);
+        try {
+            const state = readState(statePath, bucket);
+            const result = mutate(state);
+            writeState(statePath, state);
+            return result;
+        }
+        finally {
+            await release().catch(() => undefined);
+        }
+    }
+    return {
+        async tryAcquire() {
+            try {
+                return await withState((state) => take(state, bucket));
+            }
+            catch {
+                return { granted: false, reason: 'unavailable' };
+            }
+        },
+        async penalize(retryAfterMs) {
+            try {
+                await withState((state) => penalizeState(state, bucket, retryAfterMs));
+            }
+            catch {
+                /* best effort: the next acquisition will meet the provider's 429 again */
+            }
+        },
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/decide/budget.js.map

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

package/dist/decide/cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * In-memory LRU cache of provider decision outcomes.
+ *
+ * Keyed by `sha256(adapterVersion, model, questions, state)` over a canonical
+ * (key-sorted) JSON serialization, so logically identical requests hit the
+ * same entry regardless of object key order. Only provider answers are
+ * stored; fallbacks are never cached. The cache is per-process and holds no
+ * secrets (the key is not part of any request).
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import type { DecisionOutcome, DecisionRequest } from '@cleocode/contracts';
+/** Default number of entries kept by {@link createDecisionCache}. */
+export declare const DEFAULT_DECISION_CACHE_SIZE = 512;
+/** A bounded store of decision outcomes. */
+export interface DecisionCache {
+    /** Look up an outcome, marking it most-recently used. */
+    get(key: string): DecisionOutcome | undefined;
+    /** Store an outcome, evicting the least-recently used entry when full. */
+    set(key: string, outcome: DecisionOutcome): void;
+    /** Number of stored entries. */
+    readonly size: number;
+    /** Drop every entry. */
+    clear(): void;
+}
+/**
+ * sha256 hex of the canonical serialization of `value`.
+ *
+ * @param value - Any JSON-compatible value.
+ * @returns 64-char lowercase hex digest.
+ */
+export declare function hashCanonical(value: unknown): string;
+/**
+ * Cache key for a request under a given adapter version.
+ *
+ * @param adapterVersion - Wire-adapter identity; bump it to invalidate entries.
+ * @param req - The request as sent to the provider (post-redaction).
+ * @returns sha256 hex key.
+ */
+export declare function decisionCacheKey(adapterVersion: string, req: DecisionRequest): string;
+/**
+ * Create an LRU {@link DecisionCache}.
+ *
+ * @param maxEntries - Capacity (minimum 1). Defaults to {@link DEFAULT_DECISION_CACHE_SIZE}.
+ * @returns A new, empty cache.
+ */
+export declare function createDecisionCache(maxEntries?: number): DecisionCache;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/decide/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE5E,qEAAqE;AACrE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAC9C,0EAA0E;IAC1E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACjD,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAYD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,CAOrF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,GAAE,MAAoC,GAC/C,aAAa,CA2Bf"}

package/dist/decide/cache.js

@@ -0,0 +1,87 @@
+/**
+ * In-memory LRU cache of provider decision outcomes.
+ *
+ * Keyed by `sha256(adapterVersion, model, questions, state)` over a canonical
+ * (key-sorted) JSON serialization, so logically identical requests hit the
+ * same entry regardless of object key order. Only provider answers are
+ * stored; fallbacks are never cached. The cache is per-process and holds no
+ * secrets (the key is not part of any request).
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import { createHash } from 'node:crypto';
+/** Default number of entries kept by {@link createDecisionCache}. */
+export const DEFAULT_DECISION_CACHE_SIZE = 512;
+/** JSON serialization with object keys sorted at every depth. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}
+/**
+ * sha256 hex of the canonical serialization of `value`.
+ *
+ * @param value - Any JSON-compatible value.
+ * @returns 64-char lowercase hex digest.
+ */
+export function hashCanonical(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+/**
+ * Cache key for a request under a given adapter version.
+ *
+ * @param adapterVersion - Wire-adapter identity; bump it to invalidate entries.
+ * @param req - The request as sent to the provider (post-redaction).
+ * @returns sha256 hex key.
+ */
+export function decisionCacheKey(adapterVersion, req) {
+    return hashCanonical({
+        adapterVersion,
+        model: req.model ?? null,
+        questions: req.questions,
+        state: req.state,
+    });
+}
+/**
+ * Create an LRU {@link DecisionCache}.
+ *
+ * @param maxEntries - Capacity (minimum 1). Defaults to {@link DEFAULT_DECISION_CACHE_SIZE}.
+ * @returns A new, empty cache.
+ */
+export function createDecisionCache(maxEntries = DEFAULT_DECISION_CACHE_SIZE) {
+    const capacity = Math.max(1, Math.floor(maxEntries));
+    const entries = new Map();
+    return {
+        get(key) {
+            const hit = entries.get(key);
+            if (hit === undefined)
+                return undefined;
+            entries.delete(key);
+            entries.set(key, hit);
+            return hit;
+        },
+        set(key, outcome) {
+            entries.delete(key);
+            entries.set(key, outcome);
+            while (entries.size > capacity) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+        },
+        get size() {
+            return entries.size;
+        },
+        clear() {
+            entries.clear();
+        },
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/decide/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/decide/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,qEAAqE;AACrE,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAc/C,iEAAiE;AACjE,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACxF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAC9F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAsB,EAAE,GAAoB;IAC3E,OAAO,aAAa,CAAC;QACnB,cAAc;QACd,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,aAAqB,2BAA2B;IAEhD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IACnD,OAAO;QACL,GAAG,CAAC,GAAG;YACL,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YACxC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACtB,OAAO,GAAG,CAAC;QACb,CAAC;QACD,GAAG,CAAC,GAAG,EAAE,OAAO;YACd,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC1B,OAAO,OAAO,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;gBACrC,IAAI,MAAM,CAAC,IAAI;oBAAE,MAAM;gBACvB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,IAAI,IAAI;YACN,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;QACD,KAAK;YACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/decide/client.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 { type DecisionAnswer, type DecisionOutcome, type DecisionRequest, type DecisionState } from '@cleocode/contracts';
+import { type DecisionAuditSink } from './audit.js';
+import { type DecisionBudget } from './budget.js';
+import { type DecisionCache } from './cache.js';
+import { type DecisionProvider, type DecisionProviderConnection } from './provider.js';
+/** Default per-site deadline for the budget + provider round trip, in ms. */
+export declare const DEFAULT_DECISION_TIMEOUT_MS = 300;
+/**
+ * A call site's local heuristic. It must be total and fast: it answers every
+ * question in the request whenever no provider answer is available.
+ */
+export type DecisionHeuristic = (req: DecisionRequest) => Readonly<Record<string, DecisionAnswer>>;
+/** Options for {@link decide}. */
+export interface DecideOptions {
+    /**
+     * Provider connection (base URL + API key + optional default model).
+     * Absent (`undefined`) → the connection stored by `cleo decide config`
+     * (`./credentials.ts`) is loaded. `null`, a blank key or an invalid URL →
+     * unconfigured, and every call returns the fallback.
+     */
+    readonly connection?: DecisionProviderConnection | null;
+    /** Explicit provider; overrides `connection`. Tests inject a fake here. */
+    readonly provider?: DecisionProvider;
+    /** Deadline for budget + provider, ms. Default {@link DEFAULT_DECISION_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Outcome cache; `null` disables. Default: one per-process LRU. */
+    readonly cache?: DecisionCache | null;
+    /** Request budget; `null` disables. Default: the machine-wide file bucket. */
+    readonly budget?: DecisionBudget | null;
+    /** Audit sink; `null` disables. Default: `<projectRoot>/.cleo/audit/decisions.jsonl`. */
+    readonly audit?: DecisionAuditSink | null;
+    /** Project root for the default audit sink. Default: the resolved CLEO project root. */
+    readonly projectRoot?: string;
+    /** Cache-key namespace. Default: the Jev adapter version. */
+    readonly adapterVersion?: string;
+    /** Caller cancellation; treated like a timeout (fallback, no throw). */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Reset the process-default cache and budget. Tests only.
+ *
+ * @internal
+ */
+export declare function _resetDecideDefaultsForTest(): void;
+/**
+ * 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 declare function redactDecisionState(state: DecisionState): DecisionState;
+/**
+ * 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 declare function decide(siteId: string, req: DecisionRequest, fallback: DecisionHeuristic, opts?: DecideOptions): Promise<DecisionOutcome>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/decide/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,EAInB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAEhC,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,eAAe,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAEnG,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,uFAAuF;IACvF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,yFAAyF;IACzF,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAeD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD;AAWD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAMvE;AAuHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,MAAM,CAC1B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,eAAe,CAAC,CAqD1B"}