@vincemakes/kiso-runtime 0.1.19 → 0.1.21

package/dist/agent.d.ts

@@ -42,6 +42,12 @@ export interface AgentDefinition {
     readonly maxTurns?: number;
     readonly maxTokens?: number;
     readonly temperature?: number;
+    /**
+     * DEPRECATED (ADR-0044): the classic auto-compaction path is retired —
+     * the loop ignores this (microcompact absorbed the responsibility; old
+     * sessions' `compacted` events still replay). Kept so old definitions
+     * type-check; removed at 1.0.
+     */
     readonly compaction?: {
         readonly thresholdTokens: number;
     };

package/dist/compose.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 手感批 B4 (pure move) — the E1/E2 composition helpers, moved verbatim
+ * from session.ts: the extension system-prompt appends, the extension
+ * hook composition (既有先行), and the loop's microcompact config lookup.
+ */
+import type { HookHost, KisoExtension } from "@vincemakes/kiso-core";
+import type { SessionConfig } from "./session.js";
+/**
+ * E2: the session's systemPrompt plus every extension's append, in LOAD
+ * order, \n\n-joined — deterministic (same extension list → same prompt).
+ * No appends → the base passes through byte-identical.
+ */
+export declare function composeSystemPrompt(base: string | undefined, extensions: readonly KisoExtension[]): string | undefined;
+/**
+ * E1: extension hooks compose AFTER the agent's own (既有先行 — the existing
+ * hook sees every event first). Observers all run, in order; onUserMessage
+ * and onPreTool — the FIRST decisive answer wins (the existing hook
+ * outranks extensions; defers fall through); onPostTool folds — each
+ * transforms the previous result. Returns the existing host unchanged when
+ * no extension provides hooks.
+ */
+export declare function composeHooks(existing: HookHost | undefined, extensions: readonly KisoExtension[]): HookHost | undefined;
+/**
+ * E2: the loop's microcompact config — the session's own microcompact wins;
+ * otherwise the FIRST extension providing a compaction config supplies it.
+ * An extension config without a threshold contributes nothing (a boundary
+ * needs a threshold to ever fire).
+ */
+export declare function microcompactFor(config: SessionConfig): {
+    readonly thresholdTokens: number;
+    readonly keepResults?: number;
+} | undefined;

package/dist/compose.js

@@ -0,0 +1,117 @@
+/**
+ * 手感批 B4 (pure move) — the E1/E2 composition helpers, moved verbatim
+ * from session.ts: the extension system-prompt appends, the extension
+ * hook composition (既有先行), and the loop's microcompact config lookup.
+ */
+/**
+ * E2: the session's systemPrompt plus every extension's append, in LOAD
+ * order, \n\n-joined — deterministic (same extension list → same prompt).
+ * No appends → the base passes through byte-identical.
+ */
+export function composeSystemPrompt(base, extensions) {
+    const appends = extensions.flatMap((e) => (e.systemPrompt?.append === undefined ? [] : [e.systemPrompt.append]));
+    if (appends.length === 0)
+        return base;
+    return base === undefined ? appends.join("\n\n") : `${base}\n\n${appends.join("\n\n")}`;
+}
+/**
+ * E1: extension hooks compose AFTER the agent's own (既有先行 — the existing
+ * hook sees every event first). Observers all run, in order; onUserMessage
+ * and onPreTool — the FIRST decisive answer wins (the existing hook
+ * outranks extensions; defers fall through); onPostTool folds — each
+ * transforms the previous result. Returns the existing host unchanged when
+ * no extension provides hooks.
+ */
+export function composeHooks(existing, extensions) {
+    const extHooks = extensions.flatMap((e) => (e.hooks === undefined ? [] : [e.hooks]));
+    if (extHooks.length === 0)
+        return existing;
+    const out = { ...existing };
+    const sources = existing === undefined ? extHooks : [existing, ...extHooks];
+    const observers = (key) => {
+        const handlers = sources.map(key).filter((h) => h !== undefined);
+        if (handlers.length <= 1)
+            return handlers[0];
+        return async (payload, ctx) => {
+            for (const h of handlers)
+                await h(payload, ctx);
+        };
+    };
+    for (const key of ["onPreLlm", "onEvent", "onPreCompact", "onPostCompact", "onPause", "onStop"]) {
+        const handler = observers((h) => h[key]);
+        if (handler !== undefined)
+            out[key] = handler;
+    }
+    const messageHandlers = sources
+        .map((h) => h.onUserMessage)
+        .filter((h) => h !== undefined);
+    if (messageHandlers.length === 1) {
+        out.onUserMessage = messageHandlers[0]; // length 1 guarantees the element
+    }
+    else if (messageHandlers.length > 1) {
+        // 复审 E1-P2: the pipe + veto short-circuit — each handler sees the
+        // message as the PREVIOUS one left it (既有先行), and a null (veto)
+        // anywhere ends the chain immediately: never "no opinion" for the
+        // next handler to outvote. Adding an extension can therefore never
+        // make the chain MORE permissive (the approval chain's deny>ask>allow
+        // monotonicity, on the message side).
+        out.onUserMessage = async (msg, ctx) => {
+            let current = msg;
+            for (const h of messageHandlers) {
+                const r = await h(current, ctx);
+                if (r === null)
+                    return null;
+                current = r;
+            }
+            return current;
+        };
+    }
+    const preToolHandlers = sources
+        .map((h) => h.onPreTool)
+        .filter((h) => h !== undefined);
+    if (preToolHandlers.length === 1) {
+        out.onPreTool = preToolHandlers[0];
+    }
+    else if (preToolHandlers.length > 1) {
+        out.onPreTool = async (call, ctx) => {
+            for (const h of preToolHandlers) {
+                const d = await h(call, ctx);
+                if (d.action !== "defer")
+                    return d;
+            }
+            return { action: "defer" };
+        };
+    }
+    const postToolHandlers = sources
+        .map((h) => h.onPostTool)
+        .filter((h) => h !== undefined);
+    if (postToolHandlers.length === 1) {
+        out.onPostTool = postToolHandlers[0];
+    }
+    else if (postToolHandlers.length > 1) {
+        out.onPostTool = async (call, result, ctx) => {
+            let r = result;
+            for (const h of postToolHandlers)
+                r = await h(call, r, ctx);
+            return r;
+        };
+    }
+    return out;
+}
+/**
+ * E2: the loop's microcompact config — the session's own microcompact wins;
+ * otherwise the FIRST extension providing a compaction config supplies it.
+ * An extension config without a threshold contributes nothing (a boundary
+ * needs a threshold to ever fire).
+ */
+export function microcompactFor(config) {
+    if (config.microcompact !== undefined)
+        return config.microcompact;
+    for (const ext of config.extensions ?? []) {
+        const c = ext.compaction;
+        if (c !== undefined && c.thresholdTokens !== undefined) {
+            return { thresholdTokens: c.thresholdTokens, ...(c.keepResults !== undefined ? { keepResults: c.keepResults } : {}) };
+        }
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export * from "./agent.js";
 export * from "./session.js";
+export * from "./run.js";
+export * from "./recovery.js";
+export * from "./compose.js";
 export * from "./store.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/index.js

@@ -1,5 +1,8 @@
 export * from "./agent.js";
 export * from "./session.js";
+export * from "./run.js";
+export * from "./recovery.js";
+export * from "./compose.js";
 export * from "./store.js";
 export * from "./extensions.js";
 export * from "./trust.js";

package/dist/recovery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 手感批 B4 (pure move) — the recovery support pieces, moved verbatim from
+ * session.ts: the open-run gate, the abort sentinel/race wrapper, and the
+ * merged abort signal.
+ */
+import type { AbortSignalLike, AbortSignalStub } from "@vincemakes/kiso-core";
+import type { StoreRecord } from "./store.js";
+/**
+ * The most recent run WITHOUT a terminal, or undefined when every recorded
+ * run terminated. Recovery can only drive ONE run to its terminal, so an
+ * open run must be the exclusive reason a session refuses new runs (四).
+ */
+export declare function openRunId(records: readonly StoreRecord[]): string | undefined;
+/** Sentinel: the signal aborted while the recovery awaited a decision. */
+export declare const ABORTED: unique symbol;
+/** Resolve with the decision, or ABORTED when the signal fires first. */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignalLike): Promise<T | typeof ABORTED>;
+/**
+ * A signal that fires when ANY source fires — the run's own controller and
+ * an optional external signal (the CLI's Ctrl+C, a fixture's flip).
+ */
+export declare class MergedSignal implements AbortSignalStub {
+    #private;
+    constructor(...sources: readonly AbortSignalLike[]);
+    get aborted(): boolean;
+    addEventListener(_type: string, listener: (this: AbortSignalStub, ev: unknown) => void): void;
+    removeEventListener(_type: string, listener: (this: AbortSignalStub, ev: unknown) => void): void;
+}

package/dist/recovery.js

@@ -0,0 +1,68 @@
+/**
+ * 手感批 B4 (pure move) — the recovery support pieces, moved verbatim from
+ * session.ts: the open-run gate, the abort sentinel/race wrapper, and the
+ * merged abort signal.
+ */
+/**
+ * The most recent run WITHOUT a terminal, or undefined when every recorded
+ * run terminated. Recovery can only drive ONE run to its terminal, so an
+ * open run must be the exclusive reason a session refuses new runs (四).
+ */
+export function openRunId(records) {
+    const terminated = new Set(records.filter((r) => r.event.type === "terminal").map((r) => r.runId));
+    for (let i = records.length - 1; i >= 0; i--) {
+        const runId = records[i].runId;
+        if (!terminated.has(runId))
+            return runId;
+    }
+    return undefined;
+}
+/** Sentinel: the signal aborted while the recovery awaited a decision. */
+export const ABORTED = Symbol("kiso-resume-aborted");
+/** Resolve with the decision, or ABORTED when the signal fires first. */
+export async function abortable(promise, signal) {
+    if (signal.aborted)
+        return ABORTED;
+    return new Promise((resolve) => {
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(ABORTED);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (err) => {
+            signal.removeEventListener("abort", onAbort);
+            throw err;
+        });
+    });
+}
+/**
+ * A signal that fires when ANY source fires — the run's own controller and
+ * an optional external signal (the CLI's Ctrl+C, a fixture's flip).
+ */
+export class MergedSignal {
+    #sources;
+    #listeners = new Set();
+    constructor(...sources) {
+        this.#sources = sources;
+        for (const source of sources) {
+            if (source.aborted)
+                continue;
+            source.addEventListener("abort", () => {
+                for (const listener of this.#listeners)
+                    listener();
+            });
+        }
+    }
+    get aborted() {
+        return this.#sources.some((s) => s.aborted);
+    }
+    addEventListener(_type, listener) {
+        this.#listeners.add(() => listener.call(this, undefined));
+    }
+    removeEventListener(_type, listener) {
+        this.#listeners.delete(listener);
+    }
+}

package/dist/run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 手感批 B4 (pure move) — the Run class (a single turn: write-ahead
+ * persistence, the loop drive, the durable recovery state machine), moved
+ * verbatim from session.ts.
+ */
+import { type AbortSignalLike, type Adapter, type Event } from "@vincemakes/kiso-core";
+import type { SessionStore } from "./store.js";
+import { type AgentSession, type SessionConfig } from "./session.js";
+/**
+ * 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>;
+}