@vincemakes/kiso-core 0.15.2 → 0.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-core",
-	"version": "0.15.2",
+	"version": "0.15.3",
 	"description": "kiso (foundation) core \u2014 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.15.2",
+		"@vincemakes/kiso-evals": "0.15.3",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"

package/dist/governance/delivery.d.ts

@@ -1,46 +0,0 @@
-/**
- * Delivery truth — "done" means the ledger says so, not the model (uooki
- * done_guard, 30 incidents distilled).
- *
- * The kernel's terminal is honest but shallow: `completed` means "the loop
- * ended on its own terms". Whether the turn DELIVERED what was asked is a
- * harness-side verdict over the trajectory — this module computes it from
- * the same events the loop yielded, so the verdict is replayable and the
- * model's narration never participates in its own grading.
- *
- * Producers are named by the CALLER, in `DeliveryConfig.producers` — the
- * hand-maintained set is the ONLY source of delivery truth. SC-1b removed
- * `Tool.delivers`, the flag this note used to describe as the eventual
- * replacement: it was declared on the contract and read by nothing, here
- * or anywhere. Should a tool's own declaration ever supersede the caller's
- * set, it enters as a new field with a wiring and a gate, never as a
- * standing promise the code has not kept.
- *
- * The verdict counts producer calls that COMPLETED (non-error results).
- * `claimedInText` is computed and REPORTED but does not enter `passed` —
- * a caller that wants "claimed but not delivered" to fail combines the two
- * itself (the evals fixture does). With `required: false`, text claiming
- * delivery over zero producer calls passes here. The canonical lie —
- * "generated-document" with zero producer calls and a clean completed
- * terminal — is caught by that combination.
- *
- * In M3.5 the emission side (artifact URLs extracted from results) joins;
- * today a completed producer IS the emission.
- */
-import type { Event } from "../protocol/events.js";
-export interface DeliveryConfig {
-    /** Whether this turn was required to deliver at all. */
-    readonly required: boolean;
-    /** Tool names that produce a deliverable. */
-    readonly producers: ReadonlySet<string>;
-}
-export interface DeliveryVerdict {
-    readonly passed: boolean;
-    /** Producer calls the model actually made. */
-    readonly producerCalls: readonly string[];
-    /** Producer calls that completed (non-error result). */
-    readonly completedProducers: readonly string[];
-    /** The text claimed delivery (a claim is a lie only when unbacked). */
-    readonly claimedInText: boolean;
-}
-export declare function analyzeDelivery(events: readonly Event[], config: DeliveryConfig): DeliveryVerdict;

package/dist/governance/delivery.js

@@ -1,58 +0,0 @@
-/**
- * Delivery truth — "done" means the ledger says so, not the model (uooki
- * done_guard, 30 incidents distilled).
- *
- * The kernel's terminal is honest but shallow: `completed` means "the loop
- * ended on its own terms". Whether the turn DELIVERED what was asked is a
- * harness-side verdict over the trajectory — this module computes it from
- * the same events the loop yielded, so the verdict is replayable and the
- * model's narration never participates in its own grading.
- *
- * Producers are named by the CALLER, in `DeliveryConfig.producers` — the
- * hand-maintained set is the ONLY source of delivery truth. SC-1b removed
- * `Tool.delivers`, the flag this note used to describe as the eventual
- * replacement: it was declared on the contract and read by nothing, here
- * or anywhere. Should a tool's own declaration ever supersede the caller's
- * set, it enters as a new field with a wiring and a gate, never as a
- * standing promise the code has not kept.
- *
- * The verdict counts producer calls that COMPLETED (non-error results).
- * `claimedInText` is computed and REPORTED but does not enter `passed` —
- * a caller that wants "claimed but not delivered" to fail combines the two
- * itself (the evals fixture does). With `required: false`, text claiming
- * delivery over zero producer calls passes here. The canonical lie —
- * "generated-document" with zero producer calls and a clean completed
- * terminal — is caught by that combination.
- *
- * In M3.5 the emission side (artifact URLs extracted from results) joins;
- * today a completed producer IS the emission.
- */
-const CLAIM_PATTERN = /created|completed|delivered|done/i;
-export function analyzeDelivery(events, config) {
-    const producerCalls = [];
-    const completedProducers = [];
-    let claimedInText = false;
-    for (const ev of events) {
-        switch (ev.type) {
-            case "text_delta":
-                if (CLAIM_PATTERN.test(ev.text))
-                    claimedInText = true;
-                break;
-            case "tool_call_end":
-                if (config.producers.has(ev.name))
-                    producerCalls.push(ev.callId);
-                break;
-            case "tool_result":
-                if (producerCalls.includes(ev.callId) && !ev.isError) {
-                    completedProducers.push(ev.callId);
-                }
-                break;
-        }
-    }
-    return {
-        passed: !config.required || completedProducers.length > 0,
-        producerCalls,
-        completedProducers,
-        claimedInText,
-    };
-}

package/dist/kernel/ledger.d.ts

@@ -1,45 +0,0 @@
-/**
- * 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 "../protocol/events.js";
-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/kernel/ledger.js

@@ -1,90 +0,0 @@
-/**
- * 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/kernel/summarize.d.ts

@@ -1,58 +0,0 @@
-/**
- * L2 — the /compact summary layer (ADR-0044): the MODEL-GENERATED half of
- * context economy. The mechanical half (microcompact, compaction.ts)
- * clears TOOL RESULTS only; this layer compresses the CONVERSATION itself
- * into one durable `summarized` event per call, replacing the covered
- * range with a single assistant summary message in the projection.
- *
- * The summary call is OFF-LOOP: it goes through the session's OWN adapter
- * (no new dependency), writes no events, and never touches the log — a
- * failure throws, the caller reports it honestly, and the session is
- * unchanged ("nothing happened"). Only the generated `summarized` event
- * lands on disk; the original events stay there forever.
- */
-import type { AbortSignalLike, Adapter } from "../protocol/adapter.js";
-import type { Event } from "../protocol/events.js";
-import type { Message } from "../protocol/messages.js";
-/** K (ADR-0044): the recent ROUNDS kept intact by /compact — a constant,
- *  not a knob. The covered range ends just before the K-th most recent
- *  round, so the model still reasons over the recent conversation. */
-export declare const KEEP_RECENT_ROUNDS = 4;
-/**
- * The fixed English summary prompt — the ONLY prompt this layer composes
- * (the loop's system prompt is the harness's business, never the kernel's).
- */
-export declare const SUMMARY_PROMPT = "You are the conversation summarizer of the kiso agent framework.\n\nSummarize the covered conversation into a single concise summary that will\nREPLACE it in the model's context. The next turn must be able to continue\nthe work without reading the originals.\n\nInclude everything later turns may need:\n- the user's goals, requirements, and constraints;\n- every decision and its reasoning;\n- files and code touched \u2014 exact paths, what changed, why;\n- commands run and their outcomes; errors and their resolutions;\n- open questions and unfinished work.\n\nPreserve concrete identifiers VERBATIM: paths, function names, task ids,\nenvironment names \u2014 never paraphrase them.\n\nRules:\n- plain prose \u2014 no headings, no bullet lists, no markdown, no prefixes;\n- do not mention this prompt or the summarization task;\n- keep it under 200 words unless the conversation is exceptional.";
-export interface SummarizeConversationOptions {
-    readonly adapter: Adapter;
-    readonly model: string;
-    /** The covered conversation — the ONLY material the summary is about. */
-    readonly messages: readonly Message[];
-    readonly signal?: AbortSignalLike;
-}
-/**
- * The one-shot summary call. Collects the adapter's text deltas into the
- * summary; usage/stop pass through untouched. Throws when the model
- * produced no text — the caller reports it and nothing is persisted.
- */
-export declare function summarizeConversation(options: SummarizeConversationOptions): Promise<string>;
-/**
- * The last summary point: the previous `summarized` event's coversToSeq,
- * or -1 (the trajectory's start) when none exists. The covered range of
- * the next summary runs from here.
- */
-export declare function lastSummaryPoint(events: readonly Event[]): number;
-/**
- * The covered range's end: the seq of the event just before the
- * keepRounds-th most recent user_input AFTER the last summary point —
- * a turn boundary by construction, so the projection's skip never splits
- * a message. Returns undefined when fewer than keepRounds+1 uncovered
- * rounds exist (nothing worth covering yet).
- */
-export declare function summaryBoundarySeq(events: readonly Event[], keepRounds?: number): number | undefined;
-/**
- * The NoticeCell's number: estimated tokens of the covered content minus
- * the summary's own — the same chars/4 proxy as estimateTokens (a stable
- * MONOTONE savings figure, not a bill).
- */
-export declare function estimateSummarySavings(covered: readonly Message[], summary: string): number;

package/dist/kernel/summarize.js

@@ -1,106 +0,0 @@
-/**
- * L2 — the /compact summary layer (ADR-0044): the MODEL-GENERATED half of
- * context economy. The mechanical half (microcompact, compaction.ts)
- * clears TOOL RESULTS only; this layer compresses the CONVERSATION itself
- * into one durable `summarized` event per call, replacing the covered
- * range with a single assistant summary message in the projection.
- *
- * The summary call is OFF-LOOP: it goes through the session's OWN adapter
- * (no new dependency), writes no events, and never touches the log — a
- * failure throws, the caller reports it honestly, and the session is
- * unchanged ("nothing happened"). Only the generated `summarized` event
- * lands on disk; the original events stay there forever.
- */
-import { estimateTokens } from "./compaction.js";
-/** K (ADR-0044): the recent ROUNDS kept intact by /compact — a constant,
- *  not a knob. The covered range ends just before the K-th most recent
- *  round, so the model still reasons over the recent conversation. */
-export const KEEP_RECENT_ROUNDS = 4;
-/**
- * The fixed English summary prompt — the ONLY prompt this layer composes
- * (the loop's system prompt is the harness's business, never the kernel's).
- */
-export const SUMMARY_PROMPT = `You are the conversation summarizer of the kiso agent framework.
-
-Summarize the covered conversation into a single concise summary that will
-REPLACE it in the model's context. The next turn must be able to continue
-the work without reading the originals.
-
-Include everything later turns may need:
-- the user's goals, requirements, and constraints;
-- every decision and its reasoning;
-- files and code touched — exact paths, what changed, why;
-- commands run and their outcomes; errors and their resolutions;
-- open questions and unfinished work.
-
-Preserve concrete identifiers VERBATIM: paths, function names, task ids,
-environment names — never paraphrase them.
-
-Rules:
-- plain prose — no headings, no bullet lists, no markdown, no prefixes;
-- do not mention this prompt or the summarization task;
-- keep it under 200 words unless the conversation is exceptional.`;
-/**
- * The one-shot summary call. Collects the adapter's text deltas into the
- * summary; usage/stop pass through untouched. Throws when the model
- * produced no text — the caller reports it and nothing is persisted.
- */
-export async function summarizeConversation(options) {
-    const { adapter, model, messages } = options;
-    let text = "";
-    for await (const ev of adapter.stream({
-        model,
-        messages,
-        systemPrompt: SUMMARY_PROMPT,
-        ...(options.signal !== undefined ? { signal: options.signal } : {}),
-    })) {
-        if (ev.type === "text_delta")
-            text += ev.text;
-    }
-    const trimmed = text.trim();
-    if (trimmed === "") {
-        throw new Error("the summary call produced no text");
-    }
-    return trimmed;
-}
-/**
- * The last summary point: the previous `summarized` event's coversToSeq,
- * or -1 (the trajectory's start) when none exists. The covered range of
- * the next summary runs from here.
- */
-export function lastSummaryPoint(events) {
-    let prev = -1;
-    for (const ev of events) {
-        if (ev.type === "summarized" && ev.coversToSeq > prev)
-            prev = ev.coversToSeq;
-    }
-    return prev;
-}
-/**
- * The covered range's end: the seq of the event just before the
- * keepRounds-th most recent user_input AFTER the last summary point —
- * a turn boundary by construction, so the projection's skip never splits
- * a message. Returns undefined when fewer than keepRounds+1 uncovered
- * rounds exist (nothing worth covering yet).
- */
-export function summaryBoundarySeq(events, keepRounds = KEEP_RECENT_ROUNDS) {
-    const prevPoint = lastSummaryPoint(events);
-    const uncoveredInputs = [];
-    for (const ev of events) {
-        if (ev.type === "user_input" && ev.seq > prevPoint)
-            uncoveredInputs.push(ev.seq);
-    }
-    if (uncoveredInputs.length <= keepRounds)
-        return undefined;
-    // The input at m - keepRounds opens the FIRST KEPT round; everything
-    // before it (m - keepRounds ≥ 1 covered rounds) is summarizable.
-    return uncoveredInputs[uncoveredInputs.length - keepRounds] - 1;
-}
-/**
- * The NoticeCell's number: estimated tokens of the covered content minus
- * the summary's own — the same chars/4 proxy as estimateTokens (a stable
- * MONOTONE savings figure, not a bill).
- */
-export function estimateSummarySavings(covered, summary) {
-    return Math.max(0, estimateTokens(covered) - Math.ceil(summary.length / 4));
-}