@vincemakes/kiso-runtime 0.1.31 → 0.1.32

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 { 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).

package/dist/compose.js

@@ -3,6 +3,38 @@
  * 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 CC 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",
+        ...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).

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 { 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,23 @@ 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 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 } : {}),

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).

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

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,27 @@
+/**
+ * 0.1.40 (R-C item 3) — the truncation guard: a runtime adapter wrapper.
+ *
+ * The pi 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,54 @@
+/**
+ * 0.1.40 (R-C item 3) — the truncation guard: a runtime adapter wrapper.
+ *
+ * The pi 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.32",
   "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.31"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.1.31",
-    "@vincemakes/kiso-provider-openai": "0.1.31"
+    "@vincemakes/kiso-provider-anthropic": "0.1.32",
+    "@vincemakes/kiso-provider-openai": "0.1.32"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -36,7 +36,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.1.31",
+    "@vincemakes/kiso-evals": "0.1.32",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"