@vincemakes/kiso-runtime 0.1.34 → 0.1.36

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from "./recovery.js";
 export * from "./compose.js";
 export * from "./summarize.js";
 export * from "./store.js";
+export * from "./ledger.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/index.js

@@ -5,5 +5,6 @@ export * from "./recovery.js";
 export * from "./compose.js";
 export * from "./summarize.js";
 export * from "./store.js";
+export * from "./ledger.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/ledger.d.ts

@@ -0,0 +1,45 @@
+/**
+ * L2 — the execution ledger: exactly-once side effects from the event log.
+ *
+ * Every tool execution writes `tool_execution_started` before the handler
+ * and `tool_execution_succeeded` / `tool_execution_failed` after
+ * (kernel/loop.ts). From those events alone — no second store — this module
+ * answers the recovery questions:
+ *
+ *   1. What is the durable status of execution X? (`executionLedger`)
+ *   2. What is the latest execution of call Y? (`executionForCallId`)
+ *
+ * IDENTITY (Area 3): the ledger is keyed by `executionId` — a persistent,
+ * framework-generated id unique per log (one per started event). The
+ * provider's `callId` is correlation only and may repeat; two logical calls
+ * with identical (name, input) are two executions.
+ *
+ * Status derivation:
+ *   started, no terminal event yet   → "uncertain"   (interrupted: human)
+ *   succeeded                        → "succeeded"   (confirmed, never re-run)
+ *   failed (any)                     → "failed"      (a complete receipt IS
+ *                                       the outcome — ruling #12 / ADR-0038;
+ *                                       safeToRetry stays on the event for
+ *                                       history, it no longer feeds status)
+ *   resolved "rerun"                 → "rerun"       (human cleared it)
+ *   resolved "abandoned"             → "abandoned"   (human killed it)
+ */
+import type { Event } from "@vincemakes/kiso-core";
+export type ExecutionStatus = "uncertain" | "succeeded" | "failed" | "rerun" | "abandoned";
+export interface ExecutionRecord {
+    readonly executionId: string;
+    readonly callId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly status: ExecutionStatus;
+    /** Present when `status` is "succeeded" — the durable result to replay. */
+    readonly result?: {
+        readonly content: string;
+        readonly isError: false;
+    };
+    readonly error?: string;
+}
+/** executionId → durable status, rebuilt purely from events (ADR-0002). */
+export declare function executionLedger(events: readonly Event[]): Map<string, ExecutionRecord>;
+/** The LATEST execution record for a provider call id (correlation only). */
+export declare function executionForCallId(events: readonly Event[], callId: string): ExecutionRecord | undefined;

package/dist/ledger.js

@@ -0,0 +1,90 @@
+/**
+ * L2 — the execution ledger: exactly-once side effects from the event log.
+ *
+ * Every tool execution writes `tool_execution_started` before the handler
+ * and `tool_execution_succeeded` / `tool_execution_failed` after
+ * (kernel/loop.ts). From those events alone — no second store — this module
+ * answers the recovery questions:
+ *
+ *   1. What is the durable status of execution X? (`executionLedger`)
+ *   2. What is the latest execution of call Y? (`executionForCallId`)
+ *
+ * IDENTITY (Area 3): the ledger is keyed by `executionId` — a persistent,
+ * framework-generated id unique per log (one per started event). The
+ * provider's `callId` is correlation only and may repeat; two logical calls
+ * with identical (name, input) are two executions.
+ *
+ * Status derivation:
+ *   started, no terminal event yet   → "uncertain"   (interrupted: human)
+ *   succeeded                        → "succeeded"   (confirmed, never re-run)
+ *   failed (any)                     → "failed"      (a complete receipt IS
+ *                                       the outcome — ruling #12 / ADR-0038;
+ *                                       safeToRetry stays on the event for
+ *                                       history, it no longer feeds status)
+ *   resolved "rerun"                 → "rerun"       (human cleared it)
+ *   resolved "abandoned"             → "abandoned"   (human killed it)
+ */
+/** executionId → durable status, rebuilt purely from events (ADR-0002). */
+export function executionLedger(events) {
+    const ledger = new Map();
+    for (const ev of events) {
+        switch (ev.type) {
+            case "tool_execution_started":
+                ledger.set(ev.executionId, {
+                    executionId: ev.executionId,
+                    callId: ev.callId,
+                    name: ev.name,
+                    input: ev.input,
+                    status: "uncertain",
+                });
+                break;
+            case "tool_execution_succeeded": {
+                const prior = ledger.get(ev.executionId);
+                if (prior) {
+                    ledger.set(ev.executionId, { ...prior, status: "succeeded", result: ev.result });
+                }
+                break;
+            }
+            case "tool_execution_failed": {
+                const prior = ledger.get(ev.executionId);
+                if (prior) {
+                    ledger.set(ev.executionId, {
+                        ...prior,
+                        // ruling #12 (ADR-0038): a complete receipt IS the outcome —
+                        // failed is "failed", never "uncertain"; uncertainty
+                        // belongs to the crash window alone (started, no receipt).
+                        status: "failed",
+                        ...(ev.error !== undefined ? { error: ev.error } : {}),
+                    });
+                }
+                break;
+            }
+            case "tool_execution_resolved": {
+                const prior = ledger.get(ev.executionId);
+                if (prior) {
+                    ledger.set(ev.executionId, {
+                        ...prior,
+                        status: ev.resolution === "rerun" ? "rerun" : "abandoned",
+                    });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return ledger;
+}
+/** The LATEST execution record for a provider call id (correlation only). */
+export function executionForCallId(events, callId) {
+    const ledger = executionLedger(events);
+    let found;
+    for (const ev of events) {
+        if (ev.type !== "tool_execution_started")
+            continue;
+        if (ev.callId !== callId)
+            continue;
+        found = ledger.get(ev.executionId);
+    }
+    return found;
+}

package/dist/run.js

@@ -176,7 +176,7 @@ export class Run {
                     if (ev.seq > baseSeq)
                         await this.#session.persist(this.runId, ev);
                 };
-                for await (const ev of this.#recover(log, signal, lastOpen.events)) {
+                for await (const ev of this.#recover(log, signal, lastOpen.events, approvalChain, this.#config.hooks)) {
                     await persist(ev);
                     yield ev;
                 }
@@ -242,10 +242,211 @@ export class Run {
      * re-approved); a denial writes its tool result; a succeeded/failed
      * execution whose tool_result never landed is completed from the
      * receipt. Undecided requests pause and await approve().
+     *
+     * R-E 0.1.43 (Gap A): a committed turn's tool_call_end with no durable
+     * decision and no execution is UNDECIDED — recovery re-enters it into
+     * the approval pipeline before anything else (only a durable
+     * permission_decided authorizes an effect).
      */
-    async *#recover(log, signal, scope) {
-        const requests = scope.filter((e) => e.type === "permission_requested");
+    async *#recover(log, signal, scope, approvalChain, hooks) {
+        // ── Gap B: the tail draft is abandoned — never committed history ──
+        // "A model output suffix without a committed stop is an incomplete
+        // draft and must never become committed provider history." The
+        // resume appends the abandon marker FIRST: it voids the range after
+        // the last committed boundary (stop / user_input / terminal /
+        // compaction / summarized — or an earlier marker), so the projection
+        // excludes the draft and a call inside it is never executed (the
+        // boundary clause: the two Gaps divide at the stop). The audit bytes
+        // stay; a marker is kernel-exclusive (the AdapterEvent whitelist).
+        // Idempotent: an already-voided draft has a marker as its last
+        // boundary — the detection finds no output after it, and the
+        // recovered events (decided/started/result) are no draft.
+        const boundary = [...scope].reverse().find((e) => e.type === "stop" ||
+            e.type === "user_input" ||
+            e.type === "terminal" ||
+            e.type === "microcompacted" ||
+            e.type === "compacted" ||
+            e.type === "summarized" ||
+            e.type === "model_output_abandoned");
+        if (boundary !== undefined) {
+            // R-E 0.1.44 (verified against sentence 2): the draft detection
+            // stays text-only — a bare tool-call suffix [tool_call_end,
+            // permission_requested] with no text is the legal approval-panel
+            // pause (the Area 2 contract: the pending request binds and
+            // executes, pair-closed — the extensions-e2e gate). The finding's
+            // shapes all carry text, and the VOID SCOPE (what the marker
+            // covers) is the type filter at project.ts: model output dies
+            // with the draft, the framework's facts never do.
+            const draft = scope.some((e) => (e.type === "text_delta" || e.type === "thinking") && e.seq > boundary.seq);
+            if (draft) {
+                yield log.append({
+                    type: "model_output_abandoned",
+                    voidFromSeq: boundary.seq,
+                    reason: "a model output suffix without a committed stop — abandoned on resume",
+                });
+            }
+        }
+        // The invocation's framework identity (R-E 0.1.43): the
+        // tool_call_end's seq — carried by new logs, derived by
+        // callId+proximity for old ones (the last such call before the seq).
+        const callSeqOf = (callId, before) => {
+            let seq;
+            for (const e of scope) {
+                if (e.type === "tool_call_end" && e.callId === callId && e.seq < before)
+                    seq = e.seq;
+            }
+            return seq;
+        };
+        // ── Gap A: a committed turn's UNDECIDED invocation ────────────────
+        // A durable stop with a bare tool_call_end (no decision, no
+        // execution) re-enters the approval pipeline: the composed chain
+        // decides — allow → durable permission_decided (decidedBy
+        // faithfully) + the persisted execution; deny → decided + the
+        // denial result; ask/all-abstain → permission_requested (the
+        // requests pass below announces it and waits for the human). No
+        // guessing, no inheriting, no retro-authorization — re-decide.
+        // A durable POLICY verdict (E1: decidedBy set) newer than the call
+        // binds it — the chain never re-runs for a decided invocation.
+        const gapAsks = [];
+        for (const call of scope) {
+            if (call.type !== "tool_call_end")
+                continue;
+            // The boundary clause (the directive): a call whose turn has no
+            // legal stop is a DRAFT's call — Gap B voids it (never executed,
+            // never in the provider projection); this stage never touches it.
+            // The two Gaps divide at the stop; no mixing.
+            const turnEnd = scope.find((e) => e.type === "user_input" && e.seq > call.seq)?.seq ?? Number.POSITIVE_INFINITY;
+            const turnStop = scope.some((e) => e.type === "stop" && e.seq > call.seq && e.seq < turnEnd);
+            if (!turnStop)
+                continue;
+            // The requests pass below owns request-tracked invocations (it
+            // binds the stored request by decisionId, or pauses for the
+            // human) — Gap A must never re-decide over a stored
+            // permission_requested. "Only a durable permission_decided
+            // authorizes an effect": a pending request is not a decision.
+            const hasRequest = log.all.some((e) => e.type === "permission_requested" && e.callId === call.callId && e.seq > call.seq);
+            if (hasRequest)
+                continue;
+            const decided = log.all.find((e) => e.type === "permission_decided" && e.callId === call.callId && e.seq > call.seq && e.decidedBy !== undefined);
+            const hasExecution = log.all.some((e) => e.type === "tool_execution_started" && e.callId === call.callId && e.seq > call.seq);
+            const hasResult = log.all.some((e) => e.type === "tool_result" && e.callId === call.callId && e.seq > call.seq);
+            if (hasResult)
+                continue; // closed — nothing to fill
+            if (decided !== undefined) {
+                // E1: the durable verdict speaks for the call — apply it
+                // without re-running the chain.
+                if (signal.aborted)
+                    return;
+                if (decided.decision === "approved" && !hasExecution) {
+                    yield* this.#executePersisted(call.callId, call.name, call.input ?? {}, call.seq, signal);
+                }
+                else if (!hasResult) {
+                    yield* this.#denialResult(call.callId, decided.reason ?? "denied by user", call.seq);
+                }
+                continue;
+            }
+            // UNDECIDED — re-enter the approval pipeline with the LIVE
+            // decision order (loop.ts decideCall): the composed chain
+            // first; only when no chain exists do the hooks' onPreTool
+            // speak (defer → ask, deny → deny, allow → allow); no policies
+            // at all → the kernel's default allow. Same semantics as the
+            // live path — a defer policy must not collapse into an
+            // auto-allow on resume. A throwing chain counts as ask: it
+            // speaks, never silently (the live parity).
+            const payload = { callId: call.callId, name: call.name, input: call.input ?? {} };
+            // The chain's PolicyCall carries name+input only — callId is the
+            // framework's, the hook's is the provider-facing ToolCallPayload.
+            const policyCall = { name: payload.name, input: payload.input };
+            let verdict;
+            try {
+                if (approvalChain !== undefined) {
+                    const chainVerdict = await abortable(Promise.resolve(approvalChain.decide(policyCall, { signal, sessionId: this.#session.id })), signal);
+                    if (chainVerdict === ABORTED)
+                        return;
+                    verdict = chainVerdict;
+                }
+            }
+            catch {
+                verdict = { action: "ask" };
+            }
+            if (verdict === undefined && hooks?.onPreTool !== undefined) {
+                const decision = await abortable(Promise.resolve(hooks.onPreTool(payload, { sessionId: this.#session.id })), signal);
+                if (decision === ABORTED)
+                    return;
+                if (decision.action === "defer")
+                    verdict = { action: "ask" };
+                else if (decision.action !== "allow")
+                    verdict = { action: "deny", reason: decision.reason ?? "denied" };
+                else
+                    verdict = { action: "allow" };
+            }
+            if (verdict === undefined)
+                verdict = { action: "allow" }; // no policies — the kernel's default allow
+            const decisionId = `d-${log.all.length + 1}`;
+            if (verdict.action === "allow") {
+                yield log.append({
+                    type: "permission_decided",
+                    decisionId,
+                    callId: call.callId,
+                    invocationSeq: call.seq,
+                    decision: "approved",
+                    ...("decidedBy" in verdict ? { decidedBy: verdict.decidedBy } : {}),
+                });
+                if (signal.aborted)
+                    return;
+                yield* this.#executePersisted(call.callId, call.name, call.input ?? {}, call.seq, signal);
+            }
+            else if (verdict.action === "deny") {
+                yield log.append({
+                    type: "permission_decided",
+                    decisionId,
+                    callId: call.callId,
+                    invocationSeq: call.seq,
+                    decision: "denied",
+                    ...("reason" in verdict && verdict.reason !== undefined ? { reason: verdict.reason } : {}),
+                    ...("decidedBy" in verdict ? { decidedBy: verdict.decidedBy } : {}),
+                });
+                yield* this.#denialResult(call.callId, ("reason" in verdict && verdict.reason) || "denied", call.seq);
+            }
+            else {
+                // ask / all-abstain — the requests pass below announces the
+                // stored request and waits for the human.
+                const appended = log.append({
+                    type: "permission_requested",
+                    decisionId,
+                    callId: call.callId,
+                    invocationSeq: call.seq,
+                    name: call.name,
+                    input: call.input ?? {},
+                });
+                gapAsks.push(appended);
+                yield appended;
+            }
+        }
+        const requests = [...scope.filter((e) => e.type === "permission_requested"), ...gapAsks];
         for (const pending of requests) {
+            // R-E 0.1.43: the writes below carry the invocation's framework
+            // identity — the request's own, or the callId+proximity
+            // fallback for old logs (the compat contract).
+            const invocationSeq = pending.invocationSeq ?? callSeqOf(pending.callId, pending.seq);
+            // R-E 0.1.44 (sentence 3): a stored request whose invocation is
+            // VOIDED is expired — never re-presented, never executed (the
+            // dead-run expiry precedent above). The void ranges come from
+            // log.all — the marker THIS recovery appended is included. The
+            // receipt stays in the audit; only the presentation is gone.
+            // An identity-less request (an old log where neither the field nor
+            // the callId+proximity fallback yields a seq) is never proven
+            // voided — it keeps the pre-0.1.44 behavior.
+            const voided = invocationSeq !== undefined &&
+                log.all.some((e) => e.type === "model_output_abandoned" && invocationSeq > e.voidFromSeq && invocationSeq <= e.seq);
+            if (voided) {
+                yield log.append({
+                    type: "permission_expired",
+                    decisionId: pending.decisionId,
+                    reason: "the invocation was abandoned with an incomplete draft — never re-presented, never executed",
+                });
+                continue;
+            }
             const decided = log.all.find((e) => e.type === "permission_decided" && e.decisionId === pending.decisionId);
             // round 4: paired by events NEWER than the request — a historical
             // same-callId execution from an earlier run must not count as THIS
@@ -303,10 +504,10 @@ export class Run {
                 });
                 if (final.action === "allow") {
                     if (!hasExecution)
-                        yield* this.#executePersisted(pending.callId, pending.name, pending.input, signal);
+                        yield* this.#executePersisted(pending.callId, pending.name, pending.input, invocationSeq, signal);
                 }
                 else if (!hasResult) {
-                    yield* this.#denialResult(pending.callId, final.reason ?? "denied by user");
+                    yield* this.#denialResult(pending.callId, final.reason ?? "denied by user", invocationSeq);
                 }
             }
             else if (decided.decision === "approved") {
@@ -316,10 +517,10 @@ export class Run {
                 if (signal.aborted)
                     return;
                 if (!hasExecution)
-                    yield* this.#executePersisted(pending.callId, pending.name, pending.input, signal);
+                    yield* this.#executePersisted(pending.callId, pending.name, pending.input, invocationSeq, signal);
             }
             else if (!hasResult) {
-                yield* this.#denialResult(pending.callId, decided.reason ?? "denied by user");
+                yield* this.#denialResult(pending.callId, decided.reason ?? "denied by user", invocationSeq);
             }
         }
         // Receipt repair: an execution that reached a terminal state but
@@ -385,7 +586,7 @@ export class Run {
      * the permission hook (it was decided) and the model (it was never
      * asked to re-issue). Full ledgered lifecycle.
      */
-    async *#executePersisted(callId, name, input, signal) {
+    async *#executePersisted(callId, name, input, invocationSeq, signal) {
         const log = this.#session.log;
         const tool = this.#config.registry.get(name);
         const executionId = `ex-${log.lastSeq + 1}`;
@@ -393,7 +594,14 @@ export class Run {
         // not start the side effect (finding 3).
         if (signal.aborted)
             return;
-        yield log.append({ type: "tool_execution_started", executionId, callId, name, input });
+        yield log.append({
+            type: "tool_execution_started",
+            executionId,
+            callId,
+            ...(invocationSeq !== undefined ? { invocationSeq } : {}),
+            name,
+            input,
+        });
         let result;
         if (tool === undefined) {
             result = { content: `Unknown tool: ${name}`, isError: true, errorKind: "invalid_input" };
@@ -432,6 +640,7 @@ export class Run {
                 type: "tool_execution_failed",
                 executionId,
                 callId,
+                ...(invocationSeq !== undefined ? { invocationSeq } : {}),
                 error: result.content,
                 // P1-9: errorKind only exists on errors — runtime-guarded too.
                 ...(result.isError && result.errorKind !== undefined ? { errorKind: result.errorKind } : {}),
@@ -444,6 +653,7 @@ export class Run {
                 type: "tool_execution_succeeded",
                 executionId,
                 callId,
+                ...(invocationSeq !== undefined ? { invocationSeq } : {}),
                 result: { content: result.content, isError: false },
                 ...(result.tags !== undefined ? { tags: result.tags } : {}),
             });
@@ -451,6 +661,7 @@ export class Run {
         yield log.append({
             type: "tool_result",
             callId,
+            ...(invocationSeq !== undefined ? { invocationSeq } : {}),
             content: result.content,
             isError: result.isError,
             // P1-9: errorKind only exists on errors — runtime-guarded too.
@@ -465,11 +676,12 @@ export class Run {
         // alone. A retry passes the approval chain again.
     }
     /** The model-facing result of a durable denial — no execution happened. */
-    async *#denialResult(callId, reason) {
+    async *#denialResult(callId, reason, invocationSeq) {
         const denial = denialResult(reason);
         yield this.#session.log.append({
             type: "tool_result",
             callId,
+            ...(invocationSeq !== undefined ? { invocationSeq } : {}),
             content: denial.content,
             isError: true,
             errorKind: denial.errorKind,

package/dist/session.d.ts

@@ -145,7 +145,7 @@ export declare class AgentSession {
      */
     approve(decisionId: string, allow: boolean, reason?: string): Promise<void>;
     /** Executions that started but never reported a result (crash window). */
-    uncertainExecutions(): import("@vincemakes/kiso-core").ExecutionRecord[];
+    uncertainExecutions(): import("./ledger.js").ExecutionRecord[];
     /**
      * The human's verdict on an interrupted execution, keyed by EXECUTION ID
      * (B group): "rerun" (the human says the side effect did NOT happen — the

package/dist/session.js

@@ -27,7 +27,8 @@
  * support in recovery.ts, the E1/E2 composition helpers in compose.ts —
  * same package, same exports (index.ts re-exports all four).
  */
-import { EventLog, executionLedger, projectMessages, } from "@vincemakes/kiso-core";
+import { EventLog, projectMessages, } from "@vincemakes/kiso-core";
+import { executionLedger } from "./ledger.js";
 import { denialResult } from "@vincemakes/kiso-core";
 import { estimateSummarySavings, KEEP_RECENT_ROUNDS, lastSummaryPoint, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
 import { estimateTokens } from "@vincemakes/kiso-core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
   "type": "module",
   "license": "MIT",
@@ -21,11 +21,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.1.33"
+    "@vincemakes/kiso-core": "0.1.35"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.1.34",
-    "@vincemakes/kiso-provider-openai": "0.1.34"
+    "@vincemakes/kiso-provider-anthropic": "0.1.36",
+    "@vincemakes/kiso-provider-openai": "0.1.36"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -36,7 +36,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.1.33",
+    "@vincemakes/kiso-evals": "0.1.36",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"