@vincemakes/kiso-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kiso contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# @vincemakes/kiso-runtime
+
+The durable session layer: createAgent, AgentSession, Run, the
+crash-safe append-only JSONL store (torn-tail repair, cross-process
+writer locks, expected-last-seq CAS), per-run recovery (session.resume),
+real approval pauses, and the uncertain-execution ledger.
+
+See the repository README for the framework overview.

package/dist/agent.d.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentRuntime + createAgent — the high-level entry point (Phase C).
+ *
+ *   const agent = createAgent({ model, systemPrompt, tools, store,
+ *                              permissionPolicy, provider });
+ *   const session = await agent.session({ id: "demo" });
+ *   for await (const event of session.run("Inspect this repository")) { }
+ *
+ * The runtime is provider-agnostic: an adapter may be injected directly, or
+ * a provider name triggers a lazy import of the matching @kiso provider
+ * package (optional peers — an unused provider costs nothing). The kernel
+ * itself stays dependency-free; the SDKs live in the provider packages.
+ */
+import { type Adapter, type HookHost, type Tool } from "@vincemakes/kiso-core";
+import { AgentSession } from "./session.js";
+import type { SessionStore } from "./store.js";
+export interface PermissionRule {
+    readonly tool: string;
+    readonly action: "allow" | "deny" | "defer";
+}
+export interface PermissionPolicy {
+    /** First matching rule wins. */
+    readonly rules: readonly PermissionRule[];
+    /** Default for tools without a rule — deny is the safe default. */
+    readonly default?: "allow" | "deny" | "defer";
+}
+export interface AgentDefinition {
+    readonly model: string;
+    readonly systemPrompt?: string;
+    /** `Tool<any>` like the registry: typed tools register without casts. */
+    readonly tools: readonly Tool<any>[];
+    readonly store: SessionStore;
+    readonly permissionPolicy?: PermissionPolicy;
+    /** Raw loop hooks (observers, custom permission logic). */
+    readonly hooks?: HookHost;
+    /** Direct adapter injection (tests, faux, custom providers). */
+    readonly adapter?: Adapter;
+    /** Lazy provider: "anthropic" | "openai-compat" (imports the peer package). */
+    readonly provider?: "anthropic" | "openai-compat";
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly maxTurns?: number;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly compaction?: {
+        readonly thresholdTokens: number;
+    };
+    readonly maxRetries?: number;
+}
+export declare class AgentRuntime {
+    #private;
+    constructor(definition: AgentDefinition);
+    sessionIds(): string[];
+    /** Session metadata for listings (`kiso sessions`). */
+    sessions(): import("./store.js").SessionMeta[];
+    /** Release every held fd and writer lock (E 组: the CLI closes on exit). */
+    close(): void;
+    /** Load an existing session from disk, or create a fresh one. */
+    session(options: {
+        id: string;
+    }): Promise<AgentSession>;
+}
+/** The one-liner the README promises. */
+export declare function createAgent(definition: AgentDefinition): AgentRuntime;

package/dist/agent.js

@@ -0,0 +1,119 @@
+/**
+ * AgentRuntime + createAgent — the high-level entry point (Phase C).
+ *
+ *   const agent = createAgent({ model, systemPrompt, tools, store,
+ *                              permissionPolicy, provider });
+ *   const session = await agent.session({ id: "demo" });
+ *   for await (const event of session.run("Inspect this repository")) { }
+ *
+ * The runtime is provider-agnostic: an adapter may be injected directly, or
+ * a provider name triggers a lazy import of the matching @kiso provider
+ * package (optional peers — an unused provider costs nothing). The kernel
+ * itself stays dependency-free; the SDKs live in the provider packages.
+ */
+import { EventLog, ToolRegistry } from "@vincemakes/kiso-core";
+import { AgentSession } from "./session.js";
+export class AgentRuntime {
+    #definition;
+    #registry;
+    #adapterPromise;
+    constructor(definition) {
+        this.#definition = definition;
+        this.#registry = new ToolRegistry();
+        for (const tool of definition.tools)
+            this.#registry.register(tool);
+        this.#adapterPromise = resolveAdapter(definition);
+    }
+    sessionIds() {
+        return this.#definition.store.list().map((m) => m.id);
+    }
+    /** Session metadata for listings (`kiso sessions`). */
+    sessions() {
+        return this.#definition.store.list();
+    }
+    /** Release every held fd and writer lock (E 组: the CLI closes on exit). */
+    close() {
+        this.#definition.store.closeAll();
+    }
+    /** Load an existing session from disk, or create a fresh one. */
+    async session(options) {
+        const store = this.#definition.store;
+        const records = store.load(options.id);
+        const log = new EventLog(records.map((r) => r.event));
+        const adapter = await this.#adapterPromise;
+        const config = {
+            model: this.#definition.model,
+            ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
+            registry: this.#registry,
+            ...(this.#definition.permissionPolicy !== undefined || this.#definition.hooks !== undefined
+                ? {
+                    hooks: {
+                        ...this.#definition.hooks,
+                        ...(this.#definition.permissionPolicy !== undefined ? policyHooks(this.#definition.permissionPolicy) : {}),
+                    },
+                }
+                : {}),
+            ...(this.#definition.maxTurns !== undefined ? { maxTurns: this.#definition.maxTurns } : {}),
+            ...(this.#definition.maxTokens !== undefined ? { maxTokens: this.#definition.maxTokens } : {}),
+            ...(this.#definition.temperature !== undefined ? { temperature: this.#definition.temperature } : {}),
+            ...(this.#definition.compaction !== undefined ? { compaction: this.#definition.compaction } : {}),
+            ...(this.#definition.maxRetries !== undefined ? { maxRetries: this.#definition.maxRetries } : {}),
+        };
+        return new AgentSession(options.id, log, store, adapter, config);
+    }
+}
+/** The one-liner the README promises. */
+export function createAgent(definition) {
+    return new AgentRuntime(definition);
+}
+/** Wire a PermissionPolicy into the loop's onPreTool hook. */
+function policyHooks(policy) {
+    return {
+        onPreTool: async (call) => {
+            for (const rule of policy.rules) {
+                if (rule.tool === call.name) {
+                    return rule.action === "allow"
+                        ? { action: "allow" }
+                        : rule.action === "deny"
+                            ? { action: "deny", reason: `denied by policy rule for ${call.name}` }
+                            : { action: "defer" };
+                }
+            }
+            switch (policy.default ?? "deny") {
+                case "allow":
+                    return { action: "allow" };
+                case "defer":
+                    return { action: "defer" };
+                default:
+                    return { action: "deny", reason: `no policy rule for ${call.name} (default deny)` };
+            }
+        },
+    };
+}
+async function resolveAdapter(definition) {
+    if (definition.adapter)
+        return definition.adapter;
+    switch (definition.provider) {
+        // 七: the runtime imports ONLY the provider package — its high-level
+        // factory owns the SDK and builds the adapter from config. The SDKs
+        // are private dependencies of the provider packages, so a nested
+        // consumer install resolves them next to the provider, never through
+        // a hoisted root that may not exist.
+        case "anthropic": {
+            const { createAnthropicProvider } = await import("@vincemakes/kiso-provider-anthropic");
+            return createAnthropicProvider({
+                ...(definition.apiKey !== undefined ? { apiKey: definition.apiKey } : {}),
+                ...(definition.baseUrl !== undefined ? { baseUrl: definition.baseUrl } : {}),
+            });
+        }
+        case "openai-compat": {
+            const { createOpenAICompatProvider } = await import("@vincemakes/kiso-provider-openai");
+            return createOpenAICompatProvider({
+                ...(definition.apiKey !== undefined ? { apiKey: definition.apiKey } : {}),
+                ...(definition.baseUrl !== undefined ? { baseUrl: definition.baseUrl } : {}),
+            });
+        }
+        default:
+            throw new Error("createAgent: pass an `adapter` or a `provider` (\"anthropic\" | \"openai-compat\")");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./agent.js";
+export * from "./session.js";
+export * from "./store.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./agent.js";
+export * from "./session.js";
+export * from "./store.js";

package/dist/session.d.ts

@@ -0,0 +1,155 @@
+/**
+ * AgentSession + Run — the durable multi-turn conversation (Phase C/D).
+ *
+ * A session owns ONE EventLog, seeded from disk on load and continued in
+ * memory. Each `run(input)`:
+ *
+ *   1. appends the user input to the log AND the store (durable first);
+ *   2. drives the kernel loop against the session's log — every adapter
+ *      call is a pure projection of that log (ADR-0002), so multi-turn
+ *      context is free;
+ *   3. writes every event to the store BEFORE yielding it (write-ahead);
+ *   4. yields the stream; the run's `runId` and `abort()` ride on the Run
+ *      handle, not on the event union.
+ *
+ * Phase D adds the human-in-the-loop surface:
+ *   - `pendingApprovals()` — pauses that still await a decision
+ *     (permission_requested without permission_decided);
+ *   - `approve(decisionId, allow)` — resumes a paused run in-process, or
+ *     persists the decision directly when the run is gone;
+ *   - `uncertainExecutions()` / `resolveUncertain(...)` — the ledger of
+ *     interrupted side effects and the human's rerun/abandon verdict.
+ *
+ * Restart recovery is the same code path as a second run: rebuild the log
+ * from the JSONL, continue numbering where the file ended.
+ */
+import { EventLog, type AbortSignalLike, type Adapter, type Event, type Message, type PermissionDecision, type Tool } from "@vincemakes/kiso-core";
+import { type SessionStore } from "./store.js";
+/** A session whose disk write was rejected (stale handle) is PERMANENTLY
+ * poisoned: its in-memory log no longer matches the disk, so no further
+ * run may proceed — reload the session (一). */
+export declare class PoisonedSessionError extends Error {
+    constructor(reason: string);
+}
+export declare class ResumeBlockedError extends Error {
+    readonly uncertain: readonly {
+        executionId: string;
+        callId: string;
+        name: string;
+    }[];
+    constructor(uncertain: readonly {
+        executionId: string;
+        callId: string;
+        name: string;
+    }[]);
+}
+export interface ApprovalRequest {
+    readonly decisionId: string;
+    readonly callId: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+export declare class AgentSession {
+    #private;
+    readonly id: string;
+    readonly log: EventLog;
+    /** Permanently invalidate the session after a rejected disk write (一). */
+    poison(reason: string): void;
+    ensureHealthy(): void;
+    constructor(id: string, log: EventLog, store: SessionStore, adapter: Adapter, config: SessionConfig);
+    /** Write-ahead through the store; a rejected write POISONS the session
+     *  (一/第四轮): the in-memory log no longer matches the disk — whatever
+     *  the cause (stale handle, corruption, a live external writer, an I/O
+     *  fault) — so no further run, resume, or log mutation may proceed.
+     *  The health check runs BEFORE every write, on every path. */
+    persist(runId: string, event: Event): Promise<void>;
+    beginRun(run: Run): void;
+    endRun(run: Run): void;
+    /** The conversation so far, as the model sees it. */
+    projected(): readonly Message[];
+    /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
+    run(input: string, options?: {
+        signal?: AbortSignalLike;
+    }): Run;
+    /**
+     * Continue the interrupted run (Area 2): apply durable decisions,
+     * fill missing receipts, resume the pause, and drive the original
+     * trajectory to its terminal — WITHOUT inventing a new user turn.
+     * Yields nothing when the session already completed.
+     */
+    resume(): Run;
+    /**
+     * Pauses that still await a human decision (durable, survives restart).
+     * B 组: a request whose RUN has terminated is DEAD — it is neither
+     * re-presented here nor recoverable; expired requests are excluded too.
+     */
+    pendingApprovals(): ApprovalRequest[];
+    /**
+     * Answer a pending approval (Area 2). With a live run, the decision is
+     * RESOLVED into the run's frame — the loop (or the resume recovery)
+     * writes `permission_decided` itself, so there is exactly one writer per
+     * event and seq never duplicates. With no live run, the decision is
+     * persisted directly (durable, attributed to the original run) and the
+     * 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.
+     */
+    approve(decisionId: string, allow: boolean): Promise<void>;
+    /** Executions that started but never reported a result (crash window). */
+    uncertainExecutions(): import("@vincemakes/kiso-core").ExecutionRecord[];
+    /**
+     * The human's verdict on an interrupted execution, keyed by EXECUTION ID
+     * (B 组): "rerun" (the human says the side effect did NOT happen — the
+     * attempt is completed with a recorded failure so the model may re-issue
+     * it as a new logical call) or "abandoned" (treated as failed forever).
+     * Only uncertain → rerun/abandoned is legal; a resolved or successful
+     * execution is left untouched (idempotent, irreversible). Both fill a
+     * model-facing result — a dangling tool_use with NO result would be
+     * rejected by real providers (review finding 1).
+     */
+    resolveUncertain(executionId: string, resolution: "rerun" | "abandoned"): Promise<void>;
+    /** The runId that owns an execution — from its durable started record. */
+    private runIdFor;
+    registerUncertaintyResolver(executionId: string, resolve: (resolution: "rerun" | "abandoned") => void): void;
+    dropUncertaintyResolver(executionId: string): void;
+    registerResolver(decisionId: string, resolve: (decision: PermissionDecision) => void): void;
+    /** 第四轮(对抗): a verdict the human already gave for a live decision. */
+    approvalVerdict(decisionId: string): boolean | undefined;
+    /** 第四轮(对抗): a verdict the human already gave for a live execution. */
+    uncertaintyVerdict(executionId: string): "rerun" | "abandoned" | undefined;
+    /**
+     * 第五轮(P1-5): flush every verdict submitted to a live resolver that is
+     * not yet durable. Called from the Run iterator's FINALLY — whether the
+     * run completed, aborted, or was abandoned by the consumer. An event the
+     * loop already appended is left alone (its persist precedes its yield);
+     * a missing event is appended here and persisted, attributed to the run.
+     */
+    flushPendingVerdicts(runId: string, log: EventLog): Promise<void>;
+    dropResolver(decisionId: string): void;
+}
+export interface SessionConfig {
+    readonly model: string;
+    readonly systemPrompt?: string;
+    readonly tools?: readonly Tool<any>[];
+    readonly registry: import("@vincemakes/kiso-core").ToolRegistry;
+    readonly hooks?: import("@vincemakes/kiso-core").HookHost;
+    readonly maxTurns?: number;
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly compaction?: {
+        readonly thresholdTokens: number;
+    };
+    readonly maxRetries?: number;
+}
+/**
+ * A single turn. Async-iterable, so `for await (const ev of session.run(x))`
+ * is the natural shape; the handle also carries the runId and the abort.
+ */
+export declare class Run implements AsyncIterable<Event> {
+    #private;
+    runId: string;
+    constructor(store: SessionStore, adapter: Adapter, config: SessionConfig, session: AgentSession, input: string | undefined, externalSignal: AbortSignalLike | undefined, resume: boolean);
+    /** Cancel the run: propagates to the adapter (SDK) and future executions. */
+    abort(): void;
+    [Symbol.asyncIterator](): AsyncIterator<Event>;
+}