@vincemakes/kiso-core 0.26.0 → 0.26.2

package/dist/errors.d.ts

@@ -6,4 +6,10 @@
  * providers proxy raw.
  */
 import type { StructuredError } from "./protocol/events.js";
-export declare function mapApiError(status: number | undefined, message: string): StructuredError;
+/** CX-1 F8: `Retry-After` → milliseconds. Integer seconds or an HTTP-date;
+ *  anything else — negative, non-finite, a date already past — is
+ *  undefined (the kernel falls back to its own backoff). Never shortened:
+ *  a wait above the kernel's cap is reported as-is and the kernel stops
+ *  rather than retrying early. */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+export declare function mapApiError(status: number | undefined, message: string, retryAfterMs?: number): StructuredError;

package/dist/errors.js

@@ -5,8 +5,33 @@
  * (ADR-0005). 529 is the Cloudflare overload code most OpenAI-compat
  * providers proxy raw.
  */
-export function mapApiError(status, message) {
-    const withStatus = (e) => status !== undefined ? { ...e, status } : e;
+/** CX-1 F8: `Retry-After` → milliseconds. Integer seconds or an HTTP-date;
+ *  anything else — negative, non-finite, a date already past — is
+ *  undefined (the kernel falls back to its own backoff). Never shortened:
+ *  a wait above the kernel's cap is reported as-is and the kernel stops
+ *  rather than retrying early. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (value === null || value === undefined)
+        return undefined;
+    const v = value.trim();
+    if (v === "")
+        return undefined;
+    if (/^\d+$/.test(v)) {
+        const ms = Number(v) * 1000;
+        return Number.isFinite(ms) ? ms : undefined;
+    }
+    const at = Date.parse(v);
+    if (!Number.isFinite(at))
+        return undefined;
+    const ms = at - now;
+    return ms >= 0 ? ms : undefined;
+}
+export function mapApiError(status, message, retryAfterMs) {
+    const withStatus = (e) => ({
+        ...e,
+        ...(status !== undefined ? { status } : {}),
+        ...(retryAfterMs !== undefined && Number.isFinite(retryAfterMs) && retryAfterMs >= 0 ? { retryAfterMs } : {}),
+    });
     switch (status) {
         case 401:
         case 403:

package/dist/kernel/loop.d.ts

@@ -168,6 +168,9 @@ export interface LoopConfig {
  */
 export declare const DEFAULT_MAX_TURNS: number;
 export declare const DEFAULT_MAX_RETRIES = 2;
+/** CX-1 F8: the longest Retry-After the kernel will honor; beyond it the
+ *  run stops with an explicit error rather than waiting or retrying early. */
+export declare const RETRY_AFTER_MAX_MS = 60000;
 export declare function loop(config: LoopConfig): AsyncGenerator<Event>;
 /**
  * Adapter exceptions → StructuredError. Anything already shaped like one

package/dist/kernel/loop.js

@@ -63,6 +63,9 @@ import { messagesToEvents, MICROCOMPACTABLE, DO_NOT_COMPACT, projectMessages } f
  */
 export const DEFAULT_MAX_TURNS = Number.POSITIVE_INFINITY;
 export const DEFAULT_MAX_RETRIES = 2;
+/** CX-1 F8: the longest Retry-After the kernel will honor; beyond it the
+ *  run stops with an explicit error rather than waiting or retrying early. */
+export const RETRY_AFTER_MAX_MS = 60_000;
 export async function* loop(config) {
     const log = config.log ?? new EventLog();
     const hooks = config.hooks ?? NoOpHooks;
@@ -73,6 +76,13 @@ export async function* loop(config) {
     const registry = mode?.visibleToolNames !== undefined
         ? config.registry.subset(mode.visibleToolNames)
         : config.registry;
+    // CX-1 F7b (audit F7): ONE tool table per request — captured at
+    // assembly, dispatched from until the next assembly. The definition
+    // the model saw, the schema the arguments are validated against, the
+    // execute that runs and the effects the scheduler reads are the same
+    // captured values; a live source that changes mid-request reaches the
+    // NEXT request.
+    let table = registry.snapshot();
     // Seed: a fresh log encodes the seed history as events so the projection
     // (and any later replay) contains it. A non-empty log (session resume)
     // is never re-seeded — the log already holds everything.
@@ -315,7 +325,7 @@ export async function* loop(config) {
     };
     const launch = (call) => {
         execActive += 1;
-        const tool = registry.get(call.name);
+        const tool = table.get(call.name);
         const slot = reserve(tool);
         // EC-1 ③ — this call's place in the ASK order, filled in by the
         // decide chain (call order). `ahead` is the gate of an ask ACCEPTED
@@ -326,7 +336,7 @@ export async function* loop(config) {
         launches.push((async () => {
             try {
                 decideChain = decideChain.then(async () => {
-                    const v = await decideCall(call, registry, hooks, { signal: signal ?? NEVER_ABORT, ...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}) }, log, config.resolveApproval, config.approvalVerdict, signal, config.approvalPolicy, nextDecisionId, pushExec);
+                    const v = await decideCall(call, table, hooks, { signal: signal ?? NEVER_ABORT, ...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}) }, log, config.resolveApproval, config.approvalVerdict, signal, config.approvalPolicy, nextDecisionId, pushExec);
                     askOrder.ahead = askGate;
                     if (v.action === "ask") {
                         askGate = new Promise((res) => {
@@ -425,7 +435,7 @@ export async function* loop(config) {
                     return;
                 await acquireWindow();
                 try {
-                    await runLedgered(call, registry, hooks, { signal: signal ?? NEVER_ABORT, ...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}) }, signal, pushExec);
+                    await runLedgered(call, table, hooks, { signal: signal ?? NEVER_ABORT, ...(config.sessionId !== undefined ? { sessionId: config.sessionId } : {}) }, signal, pushExec);
                 }
                 finally {
                     releaseWindow();
@@ -521,7 +531,7 @@ export async function* loop(config) {
         // commit-required execution in the draft (impossible under
         // invariant 3) suppresses the marker — no void over a started
         // fact, the pre-F4 abandon exactly.
-        const unsafeStartedInDraft = () => log.all.some((e) => e.type === "tool_execution_started" && e.seq > turnStart && registry.get(e.name)?.effects?.precommitSafe !== true);
+        const unsafeStartedInDraft = () => log.all.some((e) => e.type === "tool_execution_started" && e.seq > turnStart && table.get(e.name)?.effects?.precommitSafe !== true);
         const abandonDraft = async function* (reason) {
             settleTurn();
             violated = true;
@@ -549,7 +559,7 @@ export async function* loop(config) {
                     messages,
                     ...(config.reasoning !== undefined ? { reasoning: config.reasoning } : {}),
                     ...(config.systemPrompt !== undefined ? { systemPrompt: config.systemPrompt } : {}),
-                    tools: registry.toSpecs(),
+                    tools: (table = registry.snapshot()).specs,
                     ...(config.maxTokens !== undefined ? { maxTokens: config.maxTokens } : {}),
                     ...(config.temperature !== undefined ? { temperature: config.temperature } : {}),
                     ...(signal !== undefined ? { signal } : {}),
@@ -630,13 +640,28 @@ export async function* loop(config) {
                     yield await terminal({ kind: "aborted", by: "user" });
                     return;
                 }
-                const structured = toStructuredError(err);
+                let structured = toStructuredError(err);
+                // CX-1 F8 (ruled: the kernel owns retries): the wait is
+                // max(attempts × 250 ms, the provider's Retry-After), abortable.
+                // A wait above the cap is never shortened — the run stops with
+                // an explicit error instead of retrying early.
+                const retryWait = () => {
+                    const ms = Math.max((attempts + 1) * 250, structured.retryAfterMs ?? 0);
+                    return ms > RETRY_AFTER_MAX_MS ? null : ms;
+                };
+                if (structured.retryable && attempts < maxRetries && retryWait() === null) {
+                    structured = {
+                        ...structured,
+                        retryable: false,
+                        message: `${structured.message} (the provider asked to wait ${structured.retryAfterMs}ms — beyond the ${RETRY_AFTER_MAX_MS}ms cap; not retried)`,
+                    };
+                }
                 // Phase B: never SILENTLY re-stream a turn that already emitted
                 // content — duplicates are worse than failures. Nothing streamed
                 // yet: the cheap in-place retry (no draft exists to void).
                 if (structured.retryable && !streamed && attempts < maxRetries) {
                     attempts += 1;
-                    await sleep(attempts * 250, signal); // abortable backoff
+                    await sleep(retryWait() ?? attempts * 250, signal); // abortable backoff, Retry-After honored
                     continue;
                 }
                 // F4 — ABANDON HYGIENE, every streamed exit: settle, drain,
@@ -651,7 +676,7 @@ export async function* loop(config) {
                 // budget (ADR-0005 Amendment 1: frame state, per-process).
                 if (structured.retryable && attempts < maxRetries && !unsafeStartedInDraft()) {
                     attempts += 1;
-                    await sleep(attempts * 250, signal); // the same abortable backoff
+                    await sleep(retryWait() ?? attempts * 250, signal); // the same abortable backoff, Retry-After honored
                     // Fresh per-attempt state — the marker is the boundary now.
                     pending.length = 0;
                     lastStop = undefined;
@@ -959,12 +984,76 @@ async function decideCall(call, registry, hooks, ctx, log, resolveApproval, reso
     // its verdict. A throwing chain counts as ask. Allow/deny are recorded
     // durably with decidedBy = the deciding extension, never pausing for a
     // human.
-    const originalCall = [...log.all].reverse().find((e) => e.type === "tool_call_end" && e.callId === call.callId);
-    const durable = originalCall !== undefined && JSON.stringify(originalCall.input) === JSON.stringify(call.input)
-        ? log.all.find((e) => e.type === "permission_decided" && e.decidedBy !== undefined && e.callId === call.callId)
-        : undefined;
+    // CX-1 F1 (audit F1): a durable decision is consumable ONCE — by the
+    // invocation it was recorded for, or by that invocation's RE-ISSUE on
+    // resume (same callId, same tool, identical input, and the original
+    // never produced a result). A provider callId alone is correlation,
+    // never identity: the old lookup found the current call itself
+    // (already appended), compared its input to its own, and took the
+    // FIRST decision with that callId in the whole log — so a reused
+    // callId inherited an old allow for a new call.
+    //
+    // The decision's invocationSeq names the original call (every
+    // producer stamps it, round 5). A legacy decision (no invocationSeq,
+    // pre-round-5 logs) binds to the nearest PRECEDING same-callId call
+    // before it — call first, decision after — with no run boundary
+    // between; one that binds to nothing is ambiguous, and the call goes
+    // to ask, never to the chain's allow.
+    const all = log.all;
+    const legacyBinding = (d) => {
+        for (let i = all.length - 1; i >= 0; i -= 1) {
+            const e = all[i];
+            if (e.seq >= d.seq)
+                continue;
+            if (e.type === "terminal")
+                return undefined;
+            if (e.type === "tool_call_end" && e.callId === call.callId)
+                return e.seq;
+        }
+        return undefined;
+    };
+    /** The re-issue rule: a resume re-issues the pending call under the SAME
+     *  provider id — same callId, same tool, identical input — and the
+     *  original never completed: no result and no other call under that id
+     *  stands between the original and this call. A different callId with
+     *  the same arguments is a new invocation (the /mode-switch shape: a
+     *  write denied under plan is asked afresh under default). */
+    const reissues = (origSeq) => {
+        const orig = all.find((e) => e.seq === origSeq);
+        if (orig === undefined || orig.type !== "tool_call_end")
+            return false;
+        if (orig.callId !== call.callId || orig.name !== call.name)
+            return false;
+        if (JSON.stringify(orig.input) !== JSON.stringify(call.input))
+            return false;
+        for (const e of all) {
+            if (e.seq <= origSeq || e.seq >= call.seq)
+                continue;
+            if ((e.type === "tool_result" || e.type === "tool_call_end") && e.callId === orig.callId)
+                return false;
+        }
+        return true;
+    };
+    let durable;
+    let legacyAmbiguous = false;
+    for (const e of all) {
+        if (e.type !== "permission_decided" || e.decidedBy === undefined)
+            continue;
+        if (e.invocationSeq === undefined && e.callId !== call.callId)
+            continue;
+        const origSeq = e.invocationSeq ?? legacyBinding(e);
+        if (origSeq === undefined) {
+            legacyAmbiguous = true;
+            continue;
+        }
+        if (origSeq === call.seq || reissues(origSeq))
+            durable = e;
+    }
     let chainVerdict;
-    if (durable === undefined && approvalPolicy !== undefined) {
+    if (durable === undefined && legacyAmbiguous) {
+        chainVerdict = { action: "ask" }; // the conservative reading of an old log
+    }
+    else if (durable === undefined && approvalPolicy !== undefined) {
         try {
             chainVerdict = await raceAbort(Promise.resolve(approvalPolicy.decide(payload, ctx)), signal);
         }
@@ -1237,6 +1326,8 @@ export function toStructuredError(err) {
                 ...(e.status !== undefined ? { status: e.status } : {}),
                 retryable: e.retryable,
                 message: typeof e.message === "string" ? e.message : String(err),
+                // CX-1 F8: the provider's Retry-After rides through to the kernel
+                ...(typeof e.retryAfterMs === "number" && Number.isFinite(e.retryAfterMs) && e.retryAfterMs >= 0 ? { retryAfterMs: e.retryAfterMs } : {}),
             };
         }
     }

package/dist/protocol/events.d.ts

@@ -471,6 +471,10 @@ export interface StructuredError {
     readonly status?: number;
     readonly retryable: boolean;
     readonly message: string;
+    /** CX-1 F8: the provider's `Retry-After`, normalized to milliseconds
+     *  (finite, >= 0) — the kernel owns retries and honors it; absent when
+     *  the header was missing, unparseable, or a date already past. */
+    readonly retryAfterMs?: number;
 }
 /**
  * Why the whole run ended. The ONE terminal shape every run converges to.

package/dist/tools/registry.d.ts

@@ -24,12 +24,29 @@
  */
 import type { ToolSpec } from "../protocol/messages.js";
 import type { Tool } from "./tool.js";
+/** CX-1 F7: a captured tool table — what ONE request advertises and
+ *  dispatches from. */
+export interface ToolTable {
+    readonly specs: readonly ToolSpec[];
+    get(name: string): Tool<any> | undefined;
+}
 export declare class ToolRegistry {
     #private;
     register(tool: Tool<any>): void;
     /** 0.1.26: a live tool source — consulted on every lookup, never
      *  snapshotted. The source returns the CURRENT array (it may grow). */
-    registerLive(source: () => readonly Tool[]): void;
+    registerLive(source: () => readonly Tool[], owner?: string): void;
+    /** CX-1 F7 (audit F7) — ONE table per request. The loop takes a
+     *  snapshot at request assembly and dispatches from it: the definition
+     *  sent to the model, the schema validated against, the `execute` that
+     *  runs and the `effects` the scheduler reads are the SAME captured
+     *  values (a shallow copy of each Tool — extensions replace their Tool
+     *  objects rather than mutating them, and the copy makes that a
+     *  contract). Two sources publishing one name is an error the moment
+     *  it is observed, naming both owners — never a traversal-order pick;
+     *  the one exception is the SAME Tool object reached twice (the 0.1.27
+     *  dedup), which is one tool. */
+    snapshot(): ToolTable;
     get(name: string): Tool<any> | undefined;
     list(): readonly Tool[];
     has(name: string): boolean;

package/dist/tools/registry.js

@@ -33,15 +33,44 @@ export class ToolRegistry {
     }
     /** 0.1.26: a live tool source — consulted on every lookup, never
      *  snapshotted. The source returns the CURRENT array (it may grow). */
-    registerLive(source) {
-        this.#live.push(source);
+    registerLive(source, owner = `live#${this.#live.length + 1}`) {
+        this.#live.push({ source, owner });
+    }
+    /** CX-1 F7 (audit F7) — ONE table per request. The loop takes a
+     *  snapshot at request assembly and dispatches from it: the definition
+     *  sent to the model, the schema validated against, the `execute` that
+     *  runs and the `effects` the scheduler reads are the SAME captured
+     *  values (a shallow copy of each Tool — extensions replace their Tool
+     *  objects rather than mutating them, and the copy makes that a
+     *  contract). Two sources publishing one name is an error the moment
+     *  it is observed, naming both owners — never a traversal-order pick;
+     *  the one exception is the SAME Tool object reached twice (the 0.1.27
+     *  dedup), which is one tool. */
+    snapshot() {
+        const captured = new Map();
+        const take = (t, owner) => {
+            const prior = captured.get(t.name);
+            if (prior !== undefined) {
+                if (prior.original === t)
+                    return; // the same object reached twice — one tool
+                throw new Error(`tool table: '${t.name}' is published by two sources (${prior.owner}, ${owner})`);
+            }
+            captured.set(t.name, { tool: Object.freeze({ ...t }), original: t, owner });
+        };
+        for (const t of this.#tools.values())
+            take(t, "registered");
+        for (const { source, owner } of this.#live)
+            for (const t of source())
+                take(t, owner);
+        const specs = [...captured.values()].map(({ tool: t }) => ({ name: t.name, description: t.description, inputSchema: t.parameters }));
+        return { specs, get: (name) => captured.get(name)?.tool };
     }
     get(name) {
         const t = this.#tools.get(name);
         if (t !== undefined)
             return t;
-        for (const src of this.#live) {
-            const found = src().find((x) => x.name === name);
+        for (const { source } of this.#live) {
+            const found = source().find((x) => x.name === name);
             if (found !== undefined)
                 return found;
         }
@@ -61,8 +90,8 @@ export class ToolRegistry {
             seen.add(t.name);
             out.push(t);
         }
-        for (const src of this.#live) {
-            for (const t of src()) {
+        for (const { source } of this.#live) {
+            for (const t of source()) {
                 if (!seen.has(t.name)) {
                     seen.add(t.name);
                     out.push(t);
@@ -74,7 +103,7 @@ export class ToolRegistry {
     has(name) {
         if (this.#tools.has(name))
             return true;
-        return this.#live.some((src) => src().some((x) => x.name === name));
+        return this.#live.some(({ source }) => source().some((x) => x.name === name));
     }
     /** A registry restricted to the named tools. Unknown names are dropped
      *  loudly (the kernel never silently shrinks a tool set). */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-core",
-	"version": "0.26.0",
+	"version": "0.26.2",
 	"description": "kiso (foundation) core — protocol, event log, loop, hooks, modes, permissions, compaction, delivery truth. The 2,000-line kernel at the bottom of the kiso framework.",
 	"type": "module",
 	"license": "MIT",
@@ -33,7 +33,7 @@
 		"openai"
 	],
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.26.0",
+		"@vincemakes/kiso-evals": "0.26.2",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"