@vincemakes/kiso-core 0.1.0

package/dist/kernel/mode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * L2 — ModeProfile: a mode is a cross-layer behavior switch (mauri ADR-0011),
+ * not a kernel feature. The kernel knows ONE mode at a time and applies it
+ * structurally:
+ *
+ * - `visibleToolNames` — physical removal: the registry is subset() to these
+ *   tools BEFORE the adapter is called. The model cannot call what it cannot
+ *   see; no system-prompt overlay can make that guarantee.
+ * - `systemOverlay` — appended to the system prompt by the harness (the
+ *   kernel does not compose prompts); kept here because it is part of the
+ *   mode's contract.
+ * - `permissionDefault` — the decision onPreTool falls back to when no hook
+ *   or store decides.
+ * - `compactionKeepExtra` / `stopPredicate` — reserved (ADR-0011); read by
+ *   the harness when the semantics land.
+ */
+import type { PermissionDecision } from "./permission.js";
+export interface ModeProfile {
+    readonly name: string;
+    readonly systemOverlay?: string;
+    readonly visibleToolNames?: readonly string[];
+    readonly permissionDefault?: PermissionDecision;
+    readonly compactionKeepExtra?: readonly string[];
+    readonly stopPredicate?: string;
+}
+export declare function resolveModeProfile(modes: readonly ModeProfile[] | undefined, name: string | undefined): ModeProfile | undefined;

package/dist/kernel/mode.js

@@ -0,0 +1,21 @@
+/**
+ * L2 — ModeProfile: a mode is a cross-layer behavior switch (mauri ADR-0011),
+ * not a kernel feature. The kernel knows ONE mode at a time and applies it
+ * structurally:
+ *
+ * - `visibleToolNames` — physical removal: the registry is subset() to these
+ *   tools BEFORE the adapter is called. The model cannot call what it cannot
+ *   see; no system-prompt overlay can make that guarantee.
+ * - `systemOverlay` — appended to the system prompt by the harness (the
+ *   kernel does not compose prompts); kept here because it is part of the
+ *   mode's contract.
+ * - `permissionDefault` — the decision onPreTool falls back to when no hook
+ *   or store decides.
+ * - `compactionKeepExtra` / `stopPredicate` — reserved (ADR-0011); read by
+ *   the harness when the semantics land.
+ */
+export function resolveModeProfile(modes, name) {
+    if (!name || !modes)
+        return undefined;
+    return modes.find((m) => m.name === name);
+}

package/dist/kernel/permission.d.ts

@@ -0,0 +1,27 @@
+/**
+ * L2 — permission as a negotiation, not a gate (mauri ADR-0002).
+ *
+ * A permission decision is a dialog step with state and an upgrade path:
+ * allow one call, deny with a reason fed back to the model, or defer to a
+ * human. The kernel's contract is only the decision shape; where decisions
+ * are stored (accept-for-session) is harness territory (PermissionStore,
+ * M2). M1 treats `defer` as a deny with reason "awaiting user" — the model
+ * sees the refusal and can adjust; the human-in-the-loop wiring arrives
+ * with the harness.
+ */
+export type PermissionDecision = {
+    readonly action: "allow";
+} | {
+    readonly action: "deny";
+    readonly reason: string;
+} | {
+    readonly action: "defer";
+    readonly reason?: string;
+};
+/** The denial a tool result carries when a call was refused pre-flight. */
+export declare function denialResult(reason: string): {
+    content: string;
+    isError: boolean;
+    errorKind: "precondition";
+    tags: readonly ["denied"];
+};

package/dist/kernel/permission.js

@@ -0,0 +1,20 @@
+/**
+ * L2 — permission as a negotiation, not a gate (mauri ADR-0002).
+ *
+ * A permission decision is a dialog step with state and an upgrade path:
+ * allow one call, deny with a reason fed back to the model, or defer to a
+ * human. The kernel's contract is only the decision shape; where decisions
+ * are stored (accept-for-session) is harness territory (PermissionStore,
+ * M2). M1 treats `defer` as a deny with reason "awaiting user" — the model
+ * sees the refusal and can adjust; the human-in-the-loop wiring arrives
+ * with the harness.
+ */
+/** The denial a tool result carries when a call was refused pre-flight. */
+export function denialResult(reason) {
+    return {
+        content: `[Permission denied] ${reason}`,
+        isError: true,
+        errorKind: "precondition",
+        tags: ["denied"],
+    };
+}

package/dist/kernel/project.d.ts

@@ -0,0 +1,43 @@
+/**
+ * L2 — the reducer: messages are a PURE projection of the event log.
+ *
+ * ADR-0002 says the log is the single truth. These two functions are what
+ * make that claim enforceable: `projectMessages(log.all)` rebuilds the exact
+ * message array the loop hands to the adapter, and `messagesToEvents`
+ * encodes seed history into the log. Round-trip property:
+ * `projectMessages(messagesToEvents(m)) === m` — pinned by tests, and
+ * LOSSLESS (Area 6): `source`, `tags`, image content blocks, and assistant
+ * text-block boundaries survive the round trip.
+ *
+ * The loop no longer keeps a parallel `messages` array: every adapter call
+ * derives from the log, so there is one store and the replay of `seq` 0..N
+ * reproduces the run exactly.
+ *
+ * Events with no message shape (usage, stop, thinking, terminal, compacted's
+ * own record) are skipped by the projection; `compacted` REPLAYS the
+ * compaction by re-running microcompact at that point in the sequence —
+ * microcompact is deterministic and idempotent, so the replay equals the
+ * live run. See ADR-0002.
+ */
+import type { Event } from "../protocol/events.js";
+import type { EventInput } from "./event-log.js";
+import type { AssistantBlock, Message, MessageSource } from "../protocol/messages.js";
+/**
+ * Rebuild the message array from events. Deterministic and order-sensitive:
+ * replaying the same log always produces the same messages.
+ *
+ * Text block boundaries are preserved: `text_end` closes the current text
+ * block (an explicit boundary); `text_start` after a block opens a new one.
+ * A stream of deltas WITHOUT `text_end` (the adapters' common shape) closes
+ * at the next block/tool/result boundary.
+ */
+export declare function projectMessages(events: readonly (Event | EventInput)[]): readonly Message[];
+/**
+ * Encode seed messages into log events — LOSSLESSLY for the framework's own
+ * shapes (Area 6): one `text_delta` per text block (boundaries preserved),
+ * `source` on the first event of each message, `tags` on tool results,
+ * content blocks passed through. Nothing a legal Message can express is
+ * dropped.
+ */
+export declare function messagesToEvents(messages: readonly Message[]): EventInput[];
+export type { AssistantBlock, MessageSource };

package/dist/kernel/project.js

@@ -0,0 +1,287 @@
+/**
+ * L2 — the reducer: messages are a PURE projection of the event log.
+ *
+ * ADR-0002 says the log is the single truth. These two functions are what
+ * make that claim enforceable: `projectMessages(log.all)` rebuilds the exact
+ * message array the loop hands to the adapter, and `messagesToEvents`
+ * encodes seed history into the log. Round-trip property:
+ * `projectMessages(messagesToEvents(m)) === m` — pinned by tests, and
+ * LOSSLESS (Area 6): `source`, `tags`, image content blocks, and assistant
+ * text-block boundaries survive the round trip.
+ *
+ * The loop no longer keeps a parallel `messages` array: every adapter call
+ * derives from the log, so there is one store and the replay of `seq` 0..N
+ * reproduces the run exactly.
+ *
+ * Events with no message shape (usage, stop, thinking, terminal, compacted's
+ * own record) are skipped by the projection; `compacted` REPLAYS the
+ * compaction by re-running microcompact at that point in the sequence —
+ * microcompact is deterministic and idempotent, so the replay equals the
+ * live run. See ADR-0002.
+ */
+/**
+ * Rebuild the message array from events. Deterministic and order-sensitive:
+ * replaying the same log always produces the same messages.
+ *
+ * Text block boundaries are preserved: `text_end` closes the current text
+ * block (an explicit boundary); `text_start` after a block opens a new one.
+ * A stream of deltas WITHOUT `text_end` (the adapters' common shape) closes
+ * at the next block/tool/result boundary.
+ */
+export function projectMessages(events) {
+    const out = [];
+    let blocks = [];
+    let text = null;
+    let assistantSource;
+    const pushText = () => {
+        if (text !== null) {
+            blocks.push({ type: "text", text });
+            text = null;
+        }
+    };
+    const flushAssistant = () => {
+        pushText();
+        if (blocks.length === 0) {
+            assistantSource = undefined;
+            return;
+        }
+        out.push({
+            role: "assistant",
+            blocks: [...blocks],
+            ...(assistantSource !== undefined ? { source: assistantSource } : {}),
+        });
+        blocks = [];
+        assistantSource = undefined;
+    };
+    // C 组/六: vetoed/rewritten user inputs. Collect the replacement map
+    // first — the FINAL replacement for each input wins (later replacements
+    // never produce extra messages), and the replacement renders AT THE
+    // INPUT'S OWN POSITION: the original is skipped, the final non-null
+    // content speaks for it there, a null content is a true veto (nothing
+    // at that position).
+    const replaced = new Map();
+    for (const ev of events) {
+        if (ev.type === "user_input_replaced") {
+            replaced.set(ev.replaces, {
+                content: ev.content,
+                ...(ev.source !== undefined ? { source: ev.source } : {}),
+            });
+        }
+    }
+    let explicitAssistant = false;
+    for (const ev of events) {
+        switch (ev.type) {
+            case "user_input": {
+                // 六: the final replacement renders HERE, at the input's own
+                // position — the original is skipped, the replacement event
+                // itself produces nothing (a later replacement for the same
+                // input never becomes a second message).
+                if ("seq" in ev && typeof ev.seq === "number" && replaced.has(ev.seq)) {
+                    const replacement = replaced.get(ev.seq);
+                    flushAssistant();
+                    if (replacement.content !== null) {
+                        out.push({
+                            role: "user",
+                            content: replacement.content,
+                            ...(replacement.source !== undefined ? { source: replacement.source } : {}),
+                        });
+                    }
+                    break;
+                }
+                flushAssistant();
+                out.push({
+                    role: "user",
+                    content: ev.content,
+                    ...(ev.source !== undefined ? { source: ev.source } : {}),
+                });
+                break;
+            }
+            case "user_input_replaced":
+                // The replacement already rendered at its input's position —
+                // this event carries no message of its own (六).
+                break;
+            case "assistant_start":
+                // D 组: an explicit message boundary — close any open message
+                // and begin a new one (adjacent assistants stay separate).
+                flushAssistant();
+                explicitAssistant = true;
+                if (ev.source !== undefined)
+                    assistantSource = ev.source;
+                break;
+            case "assistant_end":
+                // Close the message; an EMPTY explicit message is preserved.
+                if (explicitAssistant && blocks.length === 0 && text === null) {
+                    out.push({
+                        role: "assistant",
+                        blocks: [],
+                        ...(assistantSource !== undefined ? { source: assistantSource } : {}),
+                    });
+                    assistantSource = undefined;
+                }
+                else {
+                    flushAssistant();
+                }
+                explicitAssistant = false;
+                break;
+            case "text_start":
+                pushText(); // an explicit boundary: a new block begins
+                if (ev.source !== undefined)
+                    assistantSource = ev.source;
+                break;
+            case "text_end":
+                pushText(); // an explicit boundary: the block closes
+                break;
+            case "text_delta":
+                text = (text ?? "") + ev.text;
+                break;
+            case "tool_call_start":
+                if (ev.source !== undefined)
+                    assistantSource = ev.source;
+                break;
+            case "tool_call_input_delta":
+                break; // the parsed input arrives at tool_call_end
+            case "tool_call_end":
+                pushText();
+                blocks.push({
+                    type: "tool_use",
+                    callId: ev.callId,
+                    name: ev.name,
+                    input: ev.input ?? {},
+                });
+                break;
+            case "tool_result": {
+                flushAssistant();
+                const message = {
+                    role: "tool",
+                    callId: ev.callId,
+                    content: ev.content,
+                    isError: ev.isError,
+                    ...(ev.source !== undefined ? { source: ev.source } : {}),
+                    ...(ev.tags !== undefined ? { tags: ev.tags } : {}),
+                };
+                // 五: the originating event's seq rides on the message as a
+                // NON-ENUMERABLE correlation field — the stable identity
+                // compaction uses to name WHICH result it replaced. Deep
+                // equality with seed messages (which carry no such field)
+                // still holds; a spread drops it, which is fine because the
+                // projection re-derives everything fresh from the log.
+                if ("seq" in ev && typeof ev.seq === "number") {
+                    Object.defineProperty(message, "eventSeq", { value: ev.seq, enumerable: false, configurable: true });
+                }
+                out.push(message);
+                break;
+            }
+            case "compacted": {
+                flushAssistant();
+                // Apply the EXACT persisted replacements — never re-run the
+                // compaction algorithm (a future version could differ). 五:
+                // v2 entries are keyed by the replaced tool-result EVENT's
+                // seq, so only the specific result is rewritten — never a
+                // same-callId sibling from another turn or run. 第四轮: v1
+                // entries (round-three sessions, no eventSeq) replay with v1
+                // semantics — every tool result with that callId is replaced,
+                // exactly as the old framework did.
+                const byEventSeq = new Map(ev.cleared.filter((c) => c.eventSeq !== undefined).map((c) => [c.eventSeq, c.content]));
+                const byCallId = new Map(ev.cleared.filter((c) => c.eventSeq === undefined).map((c) => [c.callId, c.content]));
+                const replaced = out.map((m) => {
+                    if (m.role !== "tool")
+                        return m;
+                    if (m.eventSeq !== undefined && byEventSeq.has(m.eventSeq)) {
+                        return { ...m, content: byEventSeq.get(m.eventSeq) };
+                    }
+                    if (byCallId.has(m.callId))
+                        return { ...m, content: byCallId.get(m.callId) };
+                    return m;
+                });
+                out.splice(0, out.length, ...replaced);
+                break;
+            }
+            case "thinking":
+            case "usage":
+            case "stop":
+            case "terminal":
+            case "tool_execution_started":
+            case "tool_execution_succeeded":
+            case "tool_execution_failed":
+            case "tool_execution_resolved":
+            case "permission_requested":
+            case "permission_decided":
+            case "permission_expired":
+            case "uncertain_pending":
+                flushAssistant();
+                break;
+        }
+    }
+    flushAssistant();
+    return out;
+}
+/**
+ * Encode seed messages into log events — LOSSLESSLY for the framework's own
+ * shapes (Area 6): one `text_delta` per text block (boundaries preserved),
+ * `source` on the first event of each message, `tags` on tool results,
+ * content blocks passed through. Nothing a legal Message can express is
+ * dropped.
+ */
+export function messagesToEvents(messages) {
+    const out = [];
+    for (const msg of messages) {
+        switch (msg.role) {
+            case "user": {
+                out.push({
+                    type: "user_input",
+                    content: msg.content,
+                    ...(msg.source !== undefined ? { source: msg.source } : {}),
+                });
+                break;
+            }
+            case "assistant": {
+                // D 组: an explicit assistant_start/assistant_end pair frames
+                // the message — adjacent and empty assistants round-trip.
+                out.push({
+                    type: "assistant_start",
+                    ...(msg.source !== undefined ? { source: msg.source } : {}),
+                });
+                for (const block of msg.blocks) {
+                    if (block.type === "text") {
+                        out.push({
+                            type: "text_start",
+                            ...(msg.source !== undefined ? { source: msg.source } : {}),
+                        });
+                        out.push({ type: "text_delta", text: block.text });
+                        out.push({ type: "text_end" });
+                    }
+                    else {
+                        out.push({
+                            type: "tool_call_start",
+                            callId: block.callId,
+                            name: block.name,
+                            ...(msg.source !== undefined ? { source: msg.source } : {}),
+                        });
+                        out.push({
+                            type: "tool_call_end",
+                            callId: block.callId,
+                            name: block.name,
+                            input: block.input,
+                        });
+                    }
+                }
+                out.push({ type: "assistant_end" });
+                break;
+            }
+            case "tool": {
+                // D1: the FULL content (blocks included) is preserved — never
+                // flattened to text.
+                out.push({
+                    type: "tool_result",
+                    callId: msg.callId,
+                    content: msg.content,
+                    isError: msg.isError,
+                    ...(msg.source !== undefined ? { source: msg.source } : {}),
+                    ...(msg.tags !== undefined ? { tags: msg.tags } : {}),
+                });
+                break;
+            }
+        }
+    }
+    return out;
+}

package/dist/protocol/adapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * L1 — the adapter contract.
+ *
+ * One interface every provider implements. `stream()` returns an
+ * ASYNC ITERABLE of events — never a settled promise of a list, and never a
+ * callback emitter. An async iterable is incremental (the consumer sees each
+ * event as it happens), interruptible (AbortSignal), and replayable (the
+ * events carry `seq`). The three properties that let a ReAct loop stream
+ * without buffering and without losing its place.
+ *
+ * WHY not a `Promise<Event[]>`: a buffered adapter is what made agno's
+ * streaming a second-class feature bolted onto a batch loop. The contract
+ * shape IS the architecture — see ADR-0001.
+ *
+ * Adapters translate provider wire events INTO `Event`. They never see tool
+ * handlers (only `ToolSpec` projections) — the kernel is the only thing that
+ * runs tools. Provider-private fields (thinking blocks, cache_control,
+ * reasoning_content) are digested HERE and never leak into the union.
+ */
+import { type Event } from "./events.js";
+import type { Message, ToolSpec } from "./messages.js";
+/**
+ * What the kernel accepts as a cancellation signal: a REAL AbortSignal
+ * (the universal host type — every Node and browser host has one) or a
+ * minimal structural stub for tests and exotic hosts. `AbortSignal` itself
+ * is not structurally assignable to a hand-rolled interface (its listener
+ * and options shapes are richer), so the union is the honest contract:
+ * real signals pass without casts, stubs stay possible.
+ */
+export type AbortSignalLike = AbortSignal | AbortSignalStub;
+/** Minimal structural stand-in: `aborted` + `addEventListener` + `removeEventListener`. */
+export interface AbortSignalStub {
+    readonly aborted: boolean;
+    addEventListener(type: string, listener: (this: AbortSignalStub, ev: unknown) => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (this: AbortSignalStub, ev: unknown) => void, options?: {
+        once?: boolean;
+    }): void;
+}
+export interface StreamOptions {
+    readonly model: string;
+    readonly messages: readonly Message[];
+    /** Provider-level system prompt. The kernel never composes prompts. */
+    readonly systemPrompt?: string;
+    readonly tools?: readonly ToolSpec[];
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly signal?: AbortSignalLike;
+}
+/**
+ * The NARROW event set an adapter may produce (五). Everything else in the
+ * union is kernel-owned — `terminal`, `tool_execution_*`, `permission_*`,
+ * `user_input`, `compacted`, `uncertain_pending`, `user_input_replaced`,
+ * `assistant_start`/`assistant_end` — and a provider that yields any of
+ * those is FORGING kernel state. The type narrows the adapter contract;
+ * the loop ALSO enforces it at runtime (JS and third-party adapters are
+ * not trusted — see kernel/loop.ts).
+ */
+export type AdapterEvent = Extract<Event, {
+    type: "text_start" | "text_delta" | "text_end" | "tool_call_start" | "tool_call_input_delta" | "tool_call_end" | "thinking" | "usage" | "stop";
+}>;
+/** Runtime whitelist backing the narrowed type — the loop's trust gate. */
+export declare const ADAPTER_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * 第五轮(P1-8): the trust gate validates STRUCTURE, not just the type name.
+ * A third-party adapter can emit a legal type with illegal fields (a stop
+ * without a reason, a usage with known:true and no token, an array tool
+ * input) — persisted, that would poison the next load. The gate reuses the
+ * same per-variant validator the store relies on (isKisoEvent), so there
+ * is exactly ONE set of rules: an invalid event is a forgery, never
+ * appended, and the turn ends with an invalid_request terminal.
+ */
+export declare function isAdapterEvent(value: Event): value is AdapterEvent;
+export interface Adapter {
+    stream(options: StreamOptions): AsyncIterable<AdapterEvent>;
+}

package/dist/protocol/adapter.js

@@ -0,0 +1,44 @@
+/**
+ * L1 — the adapter contract.
+ *
+ * One interface every provider implements. `stream()` returns an
+ * ASYNC ITERABLE of events — never a settled promise of a list, and never a
+ * callback emitter. An async iterable is incremental (the consumer sees each
+ * event as it happens), interruptible (AbortSignal), and replayable (the
+ * events carry `seq`). The three properties that let a ReAct loop stream
+ * without buffering and without losing its place.
+ *
+ * WHY not a `Promise<Event[]>`: a buffered adapter is what made agno's
+ * streaming a second-class feature bolted onto a batch loop. The contract
+ * shape IS the architecture — see ADR-0001.
+ *
+ * Adapters translate provider wire events INTO `Event`. They never see tool
+ * handlers (only `ToolSpec` projections) — the kernel is the only thing that
+ * runs tools. Provider-private fields (thinking blocks, cache_control,
+ * reasoning_content) are digested HERE and never leak into the union.
+ */
+import { isKisoEvent } from "./events.js";
+/** Runtime whitelist backing the narrowed type — the loop's trust gate. */
+export const ADAPTER_EVENT_TYPES = new Set([
+    "text_start",
+    "text_delta",
+    "text_end",
+    "tool_call_start",
+    "tool_call_input_delta",
+    "tool_call_end",
+    "thinking",
+    "usage",
+    "stop",
+]);
+/**
+ * 第五轮(P1-8): the trust gate validates STRUCTURE, not just the type name.
+ * A third-party adapter can emit a legal type with illegal fields (a stop
+ * without a reason, a usage with known:true and no token, an array tool
+ * input) — persisted, that would poison the next load. The gate reuses the
+ * same per-variant validator the store relies on (isKisoEvent), so there
+ * is exactly ONE set of rules: an invalid event is a forgery, never
+ * appended, and the turn ends with an invalid_request terminal.
+ */
+export function isAdapterEvent(value) {
+    return ADAPTER_EVENT_TYPES.has(value.type) && isKisoEvent(value);
+}