@vincemakes/kiso-runtime 0.1.4 → 0.1.6

package/dist/agent.d.ts

@@ -11,7 +11,7 @@
  * 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 { type Adapter, type HookHost, type KisoExtension, type Tool } from "@vincemakes/kiso-core";
 import { AgentSession } from "./session.js";
 import type { SessionStore } from "./store.js";
 export interface PermissionRule {
@@ -50,6 +50,11 @@ export interface AgentDefinition {
         readonly thresholdTokens: number;
     };
     readonly maxRetries?: number;
+    /** E1: loaded extensions — their tools merge into the registry (a name
+     *  collision with a built-in is a loud startup error), their hooks
+     *  compose after the agent's own (既有先行), their approvals join the
+     *  loop's policy chain. */
+    readonly extensions?: readonly KisoExtension[];
 }
 export declare class AgentRuntime {
     #private;

package/dist/agent.js

@@ -22,6 +22,12 @@ export class AgentRuntime {
         this.#registry = new ToolRegistry();
         for (const tool of definition.tools)
             this.#registry.register(tool);
+        // E1: extension tools join the registry — a collision with a built-in
+        // name throws here, at agent creation: a loud startup failure.
+        for (const ext of definition.extensions ?? []) {
+            for (const tool of ext.tools ?? [])
+                this.#registry.register(tool);
+        }
         this.#adapterPromise = resolveAdapter(definition);
     }
     sessionIds() {
@@ -59,6 +65,7 @@ export class AgentRuntime {
             ...(this.#definition.compaction !== undefined ? { compaction: this.#definition.compaction } : {}),
             ...(this.#definition.microcompact !== undefined ? { microcompact: this.#definition.microcompact } : {}),
             ...(this.#definition.maxRetries !== undefined ? { maxRetries: this.#definition.maxRetries } : {}),
+            ...(this.#definition.extensions !== undefined ? { extensions: this.#definition.extensions } : {}),
         };
         return new AgentSession(options.id, log, store, adapter, config);
     }

package/dist/extensions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * E1 — loadExtensions: extension modules from a directory.
+ *
+ * Each *.mjs file's default export is a KisoExtension — or a factory
+ * returning one. Loading is LOUD: a bad file, a malformed export, or a
+ * duplicate extension name throws with the file name(s), so a broken
+ * extension installation fails the process at startup instead of silently
+ * changing behavior. An absent directory is the normal "no extensions"
+ * case and yields [].
+ */
+import type { KisoExtension } from "@vincemakes/kiso-core";
+export type { KisoExtension };
+export declare function loadExtensions(dir: string): Promise<KisoExtension[]>;

package/dist/extensions.js

@@ -0,0 +1,54 @@
+/**
+ * E1 — loadExtensions: extension modules from a directory.
+ *
+ * Each *.mjs file's default export is a KisoExtension — or a factory
+ * returning one. Loading is LOUD: a bad file, a malformed export, or a
+ * duplicate extension name throws with the file name(s), so a broken
+ * extension installation fails the process at startup instead of silently
+ * changing behavior. An absent directory is the normal "no extensions"
+ * case and yields [].
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+export async function loadExtensions(dir) {
+    let files;
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith(".mjs")).sort();
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return []; // no extensions dir = none installed
+        throw err;
+    }
+    const out = [];
+    for (const file of files) {
+        let ext;
+        try {
+            const mod = (await import(pathToFileURL(join(dir, file)).href));
+            ext = mod.default;
+            if (typeof ext === "function")
+                ext = await ext(); // a factory
+        }
+        catch (err) {
+            throw new Error(`[extensions] failed to load ${file}: ${err.message}`);
+        }
+        if (!isExtension(ext)) {
+            throw new Error(`[extensions] ${file} must default-export a KisoExtension {name, hooks?, tools?, approvals?} or a factory returning one`);
+        }
+        if (out.some((e) => e.name === ext.name)) {
+            throw new Error(`[extensions] duplicate extension name "${ext.name}" in ${file}`);
+        }
+        out.push(ext);
+    }
+    return out;
+}
+function isExtension(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const e = v;
+    return (typeof e.name === "string" &&
+        (e.hooks === undefined || (typeof e.hooks === "object" && e.hooks !== null)) &&
+        (e.tools === undefined || Array.isArray(e.tools)) &&
+        (e.approvals === undefined || Array.isArray(e.approvals)));
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/session.d.ts

@@ -23,7 +23,7 @@
  * 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 { EventLog, type AbortSignalLike, type Adapter, type Event, type KisoExtension, 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
@@ -144,6 +144,13 @@ export interface SessionConfig {
         readonly thresholdTokens: number;
     };
     readonly maxRetries?: number;
+    /**
+     * E1: loaded extensions — their tools join the registry (idempotently;
+     * a collision with a built-in name was already rejected at agent
+     * creation), their hooks compose AFTER the existing ones (既有先行),
+     * their approval policies enter the loop's policy chain.
+     */
+    readonly extensions?: readonly KisoExtension[];
 }
 /**
  * A single turn. Async-iterable, so `for await (const ev of session.run(x))`

package/dist/session.js

@@ -88,7 +88,17 @@ export class AgentSession {
         this.log = log;
         this.#store = store;
         this.#adapter = adapter;
-        this.#config = config;
+        // E1: extension tools join the registry. The collision check already
+        // happened at agent creation (loud startup error); the idempotent
+        // skip keeps a second session on the same registry from re-registering.
+        for (const ext of config.extensions ?? []) {
+            for (const tool of ext.tools ?? []) {
+                if (!config.registry.has(tool.name))
+                    config.registry.register(tool);
+            }
+        }
+        const composedHooks = composeHooks(config.hooks, config.extensions ?? []);
+        this.#config = composedHooks === undefined ? config : { ...config, hooks: composedHooks };
     }
     /** Write-ahead through the store; a rejected write POISONS the session
      *  (一/第四轮): the in-memory log no longer matches the disk — whatever
@@ -427,18 +437,26 @@ export class Run {
             this.#session.beginRun(this);
             const log = this.#session.log;
             const signal = this.#externalSignal ? new MergedSignal(this.#abort.signal, this.#externalSignal) : this.#abort.signal;
+            // E2: the session's own microcompact wins; otherwise the FIRST
+            // extension providing a compaction config supplies it.
+            const microcompact = microcompactFor(this.#config);
+            // 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 loopConfig = () => ({
                 adapter: this.#adapter,
                 model: this.#config.model,
-                ...(this.#config.systemPrompt !== undefined ? { systemPrompt: this.#config.systemPrompt } : {}),
+                ...(systemPrompt !== undefined ? { systemPrompt } : {}),
                 registry: this.#config.registry,
                 ...(this.#config.hooks !== undefined ? { hooks: this.#config.hooks } : {}),
                 ...(this.#config.maxTurns !== undefined ? { maxTurns: this.#config.maxTurns } : {}),
                 ...(this.#config.maxTokens !== undefined ? { maxTokens: this.#config.maxTokens } : {}),
                 ...(this.#config.temperature !== undefined ? { temperature: this.#config.temperature } : {}),
                 ...(this.#config.compaction !== undefined ? { compaction: this.#config.compaction } : {}),
-                ...(this.#config.microcompact !== undefined ? { microcompact: this.#config.microcompact } : {}),
+                ...(microcompact !== undefined ? { microcompact } : {}),
                 ...(this.#config.maxRetries !== undefined ? { maxRetries: this.#config.maxRetries } : {}),
+                approvalPolicies: (this.#config.extensions ?? []).flatMap((e) => (e.approvals ?? []).map((policy) => ({ extension: e.name, policy }))),
                 log,
                 signal,
                 resolveApproval: (decisionId) => new Promise((resolve) => {
@@ -856,6 +874,118 @@ export class Run {
         });
     }
 }
+/**
+ * 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.
+ */
+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.
+ */
+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).
+ */
+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;
+}
 /**
  * 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vincemakes/kiso-runtime",
-  "version": "0.1.4",
-  "description": "kiso runtime \u2014 durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
+  "version": "0.1.6",
+  "description": "kiso runtime — durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
   "type": "module",
   "license": "MIT",
   "exports": {
@@ -21,11 +21,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.1.4"
+    "@vincemakes/kiso-core": "0.1.6"
   },
   "peerDependencies": {
-    "@vincemakes/kiso-provider-anthropic": "0.1.4",
-    "@vincemakes/kiso-provider-openai": "0.1.4"
+    "@vincemakes/kiso-provider-anthropic": "0.1.6",
+    "@vincemakes/kiso-provider-openai": "0.1.6"
   },
   "peerDependenciesMeta": {
     "@vincemakes/kiso-provider-anthropic": {
@@ -36,7 +36,7 @@
     }
   },
   "devDependencies": {
-    "@vincemakes/kiso-evals": "0.1.4",
+    "@vincemakes/kiso-evals": "0.1.6",
     "@types/node": "^26.1.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"