@vincemakes/kiso-runtime 0.1.31 → 0.1.33

package/dist/compose.d.ts

@@ -3,8 +3,10 @@
  * from session.ts: the extension system-prompt appends, the extension
  * hook composition (the existing come first), and the loop's microcompact config lookup.
  */
-import type { HookHost, KisoExtension } from "@vincemakes/kiso-core";
+import type { ApprovalChain, HookHost, KisoExtension, ToolRegistry } from "@vincemakes/kiso-core";
 import type { SessionConfig } from "./session.js";
+/** The table, or "" when the registry is empty (no vocabulary, no tools). */
+export declare function composeToolTable(registry: ToolRegistry): string;
 /**
  * E2: the session's systemPrompt plus every extension's append, in LOAD
  * order, \n\n-joined — deterministic (same extension list → same prompt).
@@ -30,3 +32,23 @@ export declare function microcompactFor(config: SessionConfig): {
     readonly thresholdTokens: number;
     readonly keepResults?: number;
 } | undefined;
+/**
+ * E1 (W21/R3 — moved out of the kernel by the 2026-08-09 corrective
+ * action; the composition is extension wiring, the same category as
+ * composeHooks): compose the extensions' approval policies into ONE
+ * chain — the kernel's gate. deny > allow > ask: any deny wins (the
+ * FIRST denial's reason), then ANY allow (a LATER allow beats an
+ * EARLIER ask: the allow-only dont-ask-again extension must override a
+ * mode tier's ask — the old ask-wins chain left it structurally dead),
+ * and an ask falls into the kernel's human flow (its speaker = the
+ * first non-abstain — the panel's why-asked line). Only an ask-free
+ * chain auto-approves: decidedBy = the deciding extension (the FIRST
+ * allow — the symmetry of the first denial; an every-speaker-allows
+ * chain records the first speaker). An all-abstain chain (ADR-0042)
+ * ASKS — no opinion is never a silent allow; absent a channel the
+ * kernel's honest denial. A policy that throws counts as ask — it
+ * speaks, never silently. No policies → undefined (no chain: the
+ * kernel's plain flow — the all-abstain ask exists only where a chain
+ * does).
+ */
+export declare function composeApprovalChain(extensions: readonly KisoExtension[]): ApprovalChain | undefined;

package/dist/compose.js

@@ -3,6 +3,42 @@
  * from session.ts: the extension system-prompt appends, the extension
  * hook composition (the existing come first), and the loop's microcompact config lookup.
  */
+/**
+ * 0.1.40 (R-C item 1) — the tool substitution table: the fixed vocabulary
+ * (the reference implementation's content in kiso's voice, each line bound
+ * to the tool that makes
+ * it true) filtered to the ACTIVE tool set + each active tool's ONE-line
+ * snippet + its guideline bullets. The full descriptions NEVER enter the
+ * system prompt — the provider transmits them in the JSON schema anyway
+ * (never pay twice). Deterministic: same registry → same table.
+ */
+const TOOL_RULES = [
+    { tool: "read_file", line: "read files with read_file, never shell cat/head/tail" },
+    { tool: "search_text", line: "search with search_text, never shell grep/rg" },
+    { tool: "list_dir", line: "list with list_dir, never ls" },
+    { tool: "shell", line: "reserve shell for real system commands" },
+];
+/** The table, or "" when the registry is empty (no vocabulary, no tools). */
+export function composeToolTable(registry) {
+    const tools = registry.list();
+    if (tools.length === 0)
+        return "";
+    const active = new Set(tools.map((t) => t.name));
+    const lines = [
+        "Tool use:",
+        ...TOOL_RULES.filter((r) => active.has(r.tool)).map((r) => `- ${r.line}`),
+        // the parallel directive: the window applies to every active turn.
+        "- batch independent tool calls into one reply — they run in parallel",
+        // D1: a tool result is evidence, not an answer — the turn ends with
+        // the findings that make the evidence useful to the human.
+        "- end your turn with your findings — never end on a bare tool result",
+        ...tools.flatMap((t) => (t.promptSnippet === undefined ? [] : [`- ${t.promptSnippet}`])),
+    ];
+    const guidelines = tools.flatMap((t) => (t.promptGuidelines ?? []).map((g) => `- ${t.name}: ${g}`));
+    if (guidelines.length > 0)
+        lines.push("Active tool guidelines:", ...guidelines);
+    return lines.join("\n");
+}
 /**
  * E2: the session's systemPrompt plus every extension's append, in LOAD
  * order, \n\n-joined — deterministic (same extension list → same prompt).
@@ -115,3 +151,81 @@ export function microcompactFor(config) {
     }
     return undefined;
 }
+/**
+ * E1 (W21/R3 — moved out of the kernel by the 2026-08-09 corrective
+ * action; the composition is extension wiring, the same category as
+ * composeHooks): compose the extensions' approval policies into ONE
+ * chain — the kernel's gate. deny > allow > ask: any deny wins (the
+ * FIRST denial's reason), then ANY allow (a LATER allow beats an
+ * EARLIER ask: the allow-only dont-ask-again extension must override a
+ * mode tier's ask — the old ask-wins chain left it structurally dead),
+ * and an ask falls into the kernel's human flow (its speaker = the
+ * first non-abstain — the panel's why-asked line). Only an ask-free
+ * chain auto-approves: decidedBy = the deciding extension (the FIRST
+ * allow — the symmetry of the first denial; an every-speaker-allows
+ * chain records the first speaker). An all-abstain chain (ADR-0042)
+ * ASKS — no opinion is never a silent allow; absent a channel the
+ * kernel's honest denial. A policy that throws counts as ask — it
+ * speaks, never silently. No policies → undefined (no chain: the
+ * kernel's plain flow — the all-abstain ask exists only where a chain
+ * does).
+ */
+export function composeApprovalChain(extensions) {
+    const policies = extensions.flatMap((e) => (e.approvals ?? []).map((policy) => ({ extension: e.name, policy })));
+    if (policies.length === 0)
+        return undefined;
+    return {
+        async decide(payload, ctx) {
+            let chainVerdict;
+            let deniedReason;
+            let deniedBy;
+            let allowedBy; // the FIRST allowing extension (the composition's decider for an allow)
+            let firstSpeaker; // the first non-abstain verdict's extension
+            let anySpoke = false;
+            for (const { extension, policy } of policies) {
+                let v;
+                try {
+                    v = await Promise.resolve(policy.decide(payload, ctx));
+                }
+                catch {
+                    v = { action: "ask" }; // a throwing policy counts as ask — it speaks, never silently
+                }
+                if (v.action === "abstain")
+                    continue; // no opinion — not a verdict
+                anySpoke = true;
+                firstSpeaker ??= extension;
+                if (v.action === "deny") {
+                    deniedBy ??= extension;
+                    deniedReason ??= v.reason; // the FIRST denial's reason
+                }
+                else if (v.action === "allow") {
+                    // deny > allow > ask — the allow overrides any EARLIER
+                    // ask in the chain (the allow-only dont-ask-again
+                    // extension after a mode tier that asked). The first
+                    // allow is the deciding one — the symmetry of deniedBy.
+                    allowedBy ??= extension;
+                    chainVerdict = { action: "allow" };
+                }
+                else if (chainVerdict === undefined) {
+                    chainVerdict = { action: "ask" }; // recorded — a later allow overrides it
+                }
+            }
+            if (deniedBy !== undefined) {
+                return { action: "deny", reason: deniedReason ?? "denied", decidedBy: deniedBy };
+            }
+            if (allowedBy !== undefined) {
+                return { action: "allow", decidedBy: allowedBy }; // an allow beat any earlier ask
+            }
+            if (chainVerdict === undefined && anySpoke) {
+                return { action: "allow", decidedBy: firstSpeaker }; // every speaker allows
+            }
+            if (chainVerdict === undefined) {
+                // an all-abstain (ADR-0042): NO policy speaks — the call falls
+                // to the ask flow, never to a silent auto-approve. The human
+                // decides; absent a channel, the kernel's honest denial.
+                return { action: "ask" };
+            }
+            return { action: "ask", ...(firstSpeaker !== undefined ? { speaker: firstSpeaker } : {}) };
+        },
+    };
+}

package/dist/run.js

@@ -5,7 +5,8 @@
  */
 import { denialResult, loop } from "@vincemakes/kiso-core";
 import { ABORTED, MergedSignal, abortable, openRunId } from "./recovery.js";
-import { composeSystemPrompt, microcompactFor } from "./compose.js";
+import { composeApprovalChain, composeSystemPrompt, composeToolTable, microcompactFor } from "./compose.js";
+import { truncationGuard } from "./truncation-guard.js";
 import { ResumeBlockedError } from "./session.js";
 /**
  * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
@@ -56,12 +57,24 @@ export class Run {
             // E2: the session's own microcompact wins; otherwise the FIRST
             // extension providing a compaction config supplies it.
             const microcompact = microcompactFor(this.#config);
+            // 0.1.40 (R-C item 1): the tool substitution table — the ACTIVE tool
+            // set's vocabulary, snippets, and guidelines — sits BETWEEN the
+            // session's base prompt and the extension appends: generated
+            // machinery never outranks the deliberate extension text (the E2
+            // "append lands at the END" contract holds). "" when empty.
+            const toolTable = composeToolTable(this.#config.registry);
+            const basePrompt = toolTable === "" ? this.#config.systemPrompt
+                : this.#config.systemPrompt === undefined ? toolTable
+                    : `${this.#config.systemPrompt}\n\n${toolTable}`;
             // E2: the session's own systemPrompt first, then every extension
             // append in LOAD order — deterministic (same extensions → same
             // prompt); no appends → byte-identical to the extension-less run.
-            const systemPrompt = composeSystemPrompt(this.#config.systemPrompt, this.#config.extensions ?? []);
+            const systemPrompt = composeSystemPrompt(basePrompt, this.#config.extensions ?? []);
+            const approvalChain = composeApprovalChain(this.#config.extensions ?? []);
             const loopConfig = () => ({
-                adapter: this.#adapter,
+                // 0.1.40 (R-C item 3): the truncation guard gates the model
+                // stream — a truncated turn's tool batch never executes.
+                adapter: truncationGuard(this.#adapter),
                 model: this.#config.model,
                 sessionId: this.#session.id, // P3: tools see their session (ToolContext.sessionId)
                 ...(systemPrompt !== undefined ? { systemPrompt } : {}),
@@ -73,7 +86,9 @@ export class Run {
                 ...(this.#config.compaction !== undefined ? { compaction: this.#config.compaction } : {}),
                 ...(microcompact !== undefined ? { microcompact } : {}),
                 ...(this.#config.maxRetries !== undefined ? { maxRetries: this.#config.maxRetries } : {}),
-                approvalPolicies: (this.#config.extensions ?? []).flatMap((e) => (e.approvals ?? []).map((policy) => ({ extension: e.name, policy }))),
+                // E1: the composed approval chain — the extensions'
+                // policies composed into ONE gate (deny > allow > ask).
+                ...(approvalChain !== undefined ? { approvalPolicy: approvalChain } : {}),
                 log,
                 signal,
                 resolveApproval: (decisionId) => new Promise((resolve) => {

package/dist/session.d.ts

@@ -61,6 +61,16 @@ export interface SummarizeResult {
     /** The estimated tokens the compression saved (chars/4 proxy). */
     readonly savedTokens: number;
 }
+/** W18: the knowable pre-call data, surfaced through onStart — everything
+ *  the indicator's indeterminate row shows (rounds, the token estimate)
+ *  is computed locally BEFORE the one adapter call; no fraction exists. */
+export interface CompactInfo {
+    readonly coversToSeq: number;
+    /** The covered user rounds — the inputs in (previous summary point, boundary]. */
+    readonly rounds: number;
+    /** The covered content's estimated tokens (the chars/4 proxy). */
+    readonly tokens: number;
+}
 export declare class AgentSession {
     #private;
     readonly id: string;
@@ -112,6 +122,7 @@ export declare class AgentSession {
     summarize(options?: {
         keepRounds?: number;
         signal?: AbortSignalLike;
+        onStart?: (info: CompactInfo) => void;
     }): Promise<SummarizeResult | null>;
     /**
      * Pauses that still await a human decision (durable, survives restart).
@@ -128,8 +139,11 @@ export declare class AgentSession {
      * next resume applies it without re-asking. The crash window between a
      * resolve and the run's write is benign: nothing has executed yet, so a
      * lost decision only re-presents the request.
+     * W21: an optional reason rides a DENIAL (the panel's feedback — the
+     * tool_result carries `[Permission denied] <the words>`); allow reasons
+     * are never persisted (the words ride the next user turn instead).
      */
-    approve(decisionId: string, allow: boolean): Promise<void>;
+    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[];
     /**

package/dist/session.js

@@ -30,6 +30,7 @@
 import { EventLog, executionLedger, projectMessages, } from "@vincemakes/kiso-core";
 import { denialResult } from "@vincemakes/kiso-core";
 import { estimateSummarySavings, KEEP_RECENT_ROUNDS, lastSummaryPoint, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
+import { estimateTokens } from "@vincemakes/kiso-core";
 import { StaleWriterError } from "./store.js";
 import { composeHooks } from "./compose.js";
 import { Run } from "./run.js";
@@ -181,18 +182,39 @@ export class AgentSession {
     async summarize(options = {}) {
         this.ensureHealthy();
         const keepRounds = options.keepRounds ?? KEEP_RECENT_ROUNDS;
+        // W18: the signal is observed at EVERY phase boundary — the cancel
+        // affordance works for the whole call (local work included), never
+        // just the adapter's wait. The abort error is the honest "nothing
+        // happened" outcome (ADR-0044 crash semantics).
+        const cancelled = () => new Error("the compaction was cancelled");
+        if (options.signal !== undefined && options.signal.aborted)
+            throw cancelled();
         const events = this.log.all;
         const boundary = summaryBoundarySeq(events, keepRounds);
         if (boundary === undefined)
             return null;
         const prevPoint = lastSummaryPoint(events);
         const covered = projectMessages(events.filter((e) => e.seq > prevPoint && e.seq <= boundary && e.type !== "summarized"));
+        // W18: the indicator's pre-call data — rounds + the token estimate
+        // are knowable BEFORE the adapter call; the summary itself is ONE
+        // call with no fraction (kiso never invents a percentage here).
+        if (options.signal !== undefined && options.signal.aborted)
+            throw cancelled();
+        options.onStart?.({
+            coversToSeq: boundary,
+            rounds: events.filter((e) => e.type === "user_input" && e.seq > prevPoint && e.seq <= boundary).length,
+            tokens: estimateTokens(covered),
+        });
         const summary = await summarizeConversation({
             adapter: this.#adapter,
             model: this.#config.model,
             messages: covered,
             ...(options.signal !== undefined ? { signal: options.signal } : {}),
         });
+        // The post-call boundary check: an abort that landed while the
+        // adapter returned must NOT persist — "nothing happened".
+        if (options.signal !== undefined && options.signal.aborted)
+            throw cancelled();
         const full = this.log.append({ type: "summarized", coversToSeq: boundary, summary });
         // The record rides the LAST recorded run's id — a summarized fact
         // must never open a run of its own: the open-run gate keys on
@@ -248,8 +270,11 @@ export class AgentSession {
      * next resume applies it without re-asking. The crash window between a
      * resolve and the run's write is benign: nothing has executed yet, so a
      * lost decision only re-presents the request.
+     * W21: an optional reason rides a DENIAL (the panel's feedback — the
+     * tool_result carries `[Permission denied] <the words>`); allow reasons
+     * are never persisted (the words ride the next user turn instead).
      */
-    async approve(decisionId, allow) {
+    async approve(decisionId, allow, reason) {
         // round 4: a poisoned session may not mutate the log — checked before
         // anything is recorded.
         this.ensureHealthy();
@@ -284,7 +309,10 @@ export class AgentSession {
             // cannot issue while awaiting approve().)
             this.#pendingDurableApprovals.set(decisionId, allow);
             this.#pendingResolvers.delete(decisionId);
-            resolver(allow ? { action: "allow" } : { action: "deny", reason: "denied by user" });
+            // W21: the panel's feedback rides the denial — the tool_result
+            // carries `[Permission denied] <the words>` (the rejection
+            // asymmetry: words keep the run alive).
+            resolver(allow ? { action: "allow" } : { action: "deny", reason: reason ?? "denied by user" });
             return;
         }
         const runId = request?.runId ?? "approval";
@@ -293,7 +321,7 @@ export class AgentSession {
             decisionId,
             ...(request !== undefined ? { callId: request.event.callId } : {}),
             decision: allow ? "approved" : "denied",
-            ...(allow ? {} : { reason: "denied by user" }),
+            ...(allow ? {} : { reason: reason ?? "denied by user" }),
         });
         await this.persist(runId, decided);
     }

package/dist/summarize.d.ts

@@ -51,8 +51,8 @@ export declare function lastSummaryPoint(events: readonly Event[]): number;
  * a message. Returns undefined when fewer than keepRounds+1 uncovered
  * rounds exist (nothing worth covering yet).
  *
- * ⑥ (todo round): a tool result tagged do-not-compact is DURABLE work
- * memory (the todo_set echo) — the summary must never cover its round,
+ * ⑥ (task round): a tool result tagged do-not-compact is DURABLE work
+ * memory (the task_set echo) — the summary must never cover its round,
  * or the model loses the current list. When the base boundary would
  * cover such a result, the boundary pulls back to just before the round
  * containing the LATEST one (still a turn boundary). A protected round

package/dist/summarize.js

@@ -85,8 +85,8 @@ export function lastSummaryPoint(events) {
  * a message. Returns undefined when fewer than keepRounds+1 uncovered
  * rounds exist (nothing worth covering yet).
  *
- * ⑥ (todo round): a tool result tagged do-not-compact is DURABLE work
- * memory (the todo_set echo) — the summary must never cover its round,
+ * ⑥ (task round): a tool result tagged do-not-compact is DURABLE work
+ * memory (the task_set echo) — the summary must never cover its round,
  * or the model loses the current list. When the base boundary would
  * cover such a result, the boundary pulls back to just before the round
  * containing the LATEST one (still a turn boundary). A protected round

package/dist/truncation-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 0.1.40 (R-C item 3) — the truncation guard: a runtime adapter wrapper.
+ *
+ * The reference implementation's protection: a truncated stream (stopReason
+ * max_tokens/length) can
+ * yield tool args that parse and validate but are silently incomplete —
+ * executing them is the destructive-bug class. The provider adapters already
+ * see the stop reason; the RUNTIME vetoes execution of the whole batch:
+ *
+ *   - tool_call_end events are held per turn (the deltas pass through live —
+ *     the UI still shows the calls building, only the COMPLETION is gated);
+ *   - a compatible stop flushes the held calls in order, then the stop — the
+ *     kernel launches them exactly as before (the parallel window survives;
+ *     only the 0.1.26 mid-stream launch timing is gone — the cost of the
+ *     guarantee: the turn's truncated intent is never half-executed);
+ *   - a truncation stop flushes the held calls with input: null — the
+ *     kernel's EXISTING invalid-input denial fails the whole batch without
+ *     executing anything (the same honest null the adapters already emit
+ *     for unparseable partials — zero new protocol surface), and the turn
+ *     still ends with the max_tokens terminal (the loop's voided settle).
+ *
+ * The kernel machinery (the streaming launch, the window, the voided
+ * settle) is untouched — the gate lives at the adapter boundary, where the
+ * stop reason is already known.
+ */
+import type { Adapter } from "@vincemakes/kiso-core";
+/** Wrap the adapter so a truncated turn's tool batch can never execute. */
+export declare function truncationGuard(adapter: Adapter): Adapter;

package/dist/truncation-guard.js

@@ -0,0 +1,55 @@
+/**
+ * 0.1.40 (R-C item 3) — the truncation guard: a runtime adapter wrapper.
+ *
+ * The reference implementation's protection: a truncated stream (stopReason
+ * max_tokens/length) can
+ * yield tool args that parse and validate but are silently incomplete —
+ * executing them is the destructive-bug class. The provider adapters already
+ * see the stop reason; the RUNTIME vetoes execution of the whole batch:
+ *
+ *   - tool_call_end events are held per turn (the deltas pass through live —
+ *     the UI still shows the calls building, only the COMPLETION is gated);
+ *   - a compatible stop flushes the held calls in order, then the stop — the
+ *     kernel launches them exactly as before (the parallel window survives;
+ *     only the 0.1.26 mid-stream launch timing is gone — the cost of the
+ *     guarantee: the turn's truncated intent is never half-executed);
+ *   - a truncation stop flushes the held calls with input: null — the
+ *     kernel's EXISTING invalid-input denial fails the whole batch without
+ *     executing anything (the same honest null the adapters already emit
+ *     for unparseable partials — zero new protocol surface), and the turn
+ *     still ends with the max_tokens terminal (the loop's voided settle).
+ *
+ * The kernel machinery (the streaming launch, the window, the voided
+ * settle) is untouched — the gate lives at the adapter boundary, where the
+ * stop reason is already known.
+ */
+/** Wrap the adapter so a truncated turn's tool batch can never execute. */
+export function truncationGuard(adapter) {
+    return {
+        stream(options) {
+            return guardStream(adapter.stream(options));
+        },
+    };
+}
+async function* guardStream(stream) {
+    const held = [];
+    for await (const ev of stream) {
+        if (ev.type === "tool_call_end") {
+            held.push(ev);
+            continue; // held — emitted at the stop, complete or nulled
+        }
+        if (ev.type === "stop") {
+            const truncated = ev.reason === "max_tokens";
+            for (const call of held) {
+                // truncation: null input — the kernel's denial path fails the
+                // call without executing it; otherwise: untouched, in order.
+                yield truncated ? { ...call, input: null } : call;
+            }
+            held.length = 0;
+        }
+        yield ev;
+    }
+    // A stream that ends WITHOUT a stop drops the held ends — the kernel
+    // already voids the malformed turn (invalid_request); the dangling
+    // deltas are the pre-existing malformed-stream shape.
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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.30"
+    "@vincemakes/kiso-core": "0.1.32"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.1.31",
-    "@vincemakes/kiso-provider-openai": "0.1.31"
+    "@vincemakes/kiso-provider-anthropic": "0.1.33",
+    "@vincemakes/kiso-provider-openai": "0.1.33"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -36,7 +36,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.1.31",
+    "@vincemakes/kiso-evals": "0.1.33",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"