@devxiyang/agent-kernel 0.0.2 → 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devxiyang
+
+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

@@ -1,60 +1,45 @@
 # agent-kernel
 
-`agent-kernel` is a TypeScript library that provides a provider-agnostic agent runtime:
-- a persistent/in-memory conversation kernel
-- an event-driven agent loop with tool execution and parameter validation
-- a reusable async event stream primitive
-
-## Core Concepts
-
-- `Agent`: stateful runtime that orchestrates model calls, tool execution, and event emission.
-- `Kernel`: conversation state store (in-memory or persisted), with branching and compaction support.
-- `StreamFn`: provider adapter contract — you implement it once for any LLM backend.
-- `AgentTool`: executable unit with a TypeBox schema for parameter validation and provider schema generation.
-
-## Project Structure
-
-```text
-src/
-  core/
-    agent/
-    kernel/
-  event-stream.ts
-  index.ts
-```
-
-## Feature Map
-
-- Provider-agnostic runtime via `StreamFn`
-- Real-time events (`text_delta`, `tool_call`, `tool_result`, `step_done`, etc.)
-- Tool execution loop with automatic parameter validation (TypeBox + `Value.Parse`)
-- Validation errors returned as `tool_result` so the LLM can self-correct
-- Persistent sessions via `createAgent({ session: { dir, sessionId } })`
-- Conversation compaction via `kernel.compact(fromId, toId, summaryText)`
-- Strong TypeScript types — `execute` input is inferred from the TypeBox schema
-- **Parallel tool execution** — run all tool calls in a single turn concurrently
-- **Tool timeout** — per-call deadline; timed-out tools return an error result automatically
-- **Auto-compaction hook** — `onContextFull` fires when the context window is full
-- **Stream error retry** — automatic retry with fixed delay for transient LLM errors
-- **Session metadata** — attach a `title` (or any custom field) to a session; read it back from `listSessions`
+[![npm version](https://img.shields.io/npm/v/@devxiyang/agent-kernel)](https://www.npmjs.com/package/@devxiyang/agent-kernel)
+[![npm downloads](https://img.shields.io/npm/dm/@devxiyang/agent-kernel)](https://www.npmjs.com/package/@devxiyang/agent-kernel)
+[![license](https://img.shields.io/npm/l/@devxiyang/agent-kernel)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+
+A provider-agnostic agent runtime for TypeScript. Bring your own LLM — `agent-kernel` handles the loop, tool execution, event streaming, and conversation persistence.
+
+## Features
+
+- **Provider-agnostic** — implement one `StreamFn` adapter for any LLM backend (OpenAI, Anthropic, Vercel AI SDK, etc.)
+- **Real-time event stream** — `text_delta`, `tool_call`, `tool_result`, `step_done`, and more
+- **Typed tool execution** — TypeBox schemas drive runtime validation, coercion, and LLM schema generation
+- **Parallel tool execution** — run all tool calls in a turn concurrently
+- **Tool timeout** — per-call deadline; timed-out tools return an error result the LLM can handle
+- **Persistent sessions** — optional file-backed conversation history, survives restarts
+- **Conversation compaction** — replace old entries with a summary to stay within context limits
+- **Auto-compaction hook** — `onContextFull` fires when the token budget is reached
+- **Steering & follow-up** — inject messages mid-run without re-prompting
+- **Stream error retry** — automatic retry with configurable delay for transient LLM errors
+- **Session metadata** — attach titles and custom fields to sessions; query with `listSessions`
+- **Kernel cache** — LRU + TTL in-memory cache for session kernels
 
 ## Install
 
 ```bash
 npm install @devxiyang/agent-kernel
-npm install @sinclair/typebox
-npm install openai             # if using OpenAI SDK adapter
-npm install ai @ai-sdk/openai  # if using Vercel AI SDK adapter
 ```
 
-## Module Index
+`@sinclair/typebox` is a required peer dependency for tool parameter schemas:
 
-- `@devxiyang/agent-kernel` — root export (agent APIs + `EventStream`)
-- `@devxiyang/agent-kernel/agent` — direct agent module
-- `@devxiyang/agent-kernel/kernel` — kernel module (`createKernel`, kernel types)
-- `@devxiyang/agent-kernel/event-stream` — `EventStream`
+```bash
+npm install @sinclair/typebox
+```
 
----
+Optional — install the LLM SDK of your choice:
+
+```bash
+npm install openai             # OpenAI SDK
+npm install ai @ai-sdk/openai  # Vercel AI SDK
+```
 
 ## Quick Start
 
@@ -62,7 +47,7 @@ npm install ai @ai-sdk/openai  # if using Vercel AI SDK adapter
 import { Type } from '@sinclair/typebox'
 import { createAgent, type StreamFn, type AgentTool } from '@devxiyang/agent-kernel'
 
-// Minimal echo stream (replace with a real provider adapter)
+// 1. Implement StreamFn for your LLM provider (see adapter examples below)
 const stream: StreamFn = async (messages, _tools, onEvent) => {
   const last = messages.filter((m) => m.role === 'user').at(-1)
   const reply = `Echo: ${typeof last?.content === 'string' ? last.content : '[multi-part]'}`
@@ -74,34 +59,357 @@ const stream: StreamFn = async (messages, _tools, onEvent) => {
   }
 }
 
-const getTimeSchema = Type.Object({})
-
+// 2. Define tools
 const tools: AgentTool[] = [
   {
     name:        'get_time',
     description: 'Returns the current UTC time as an ISO string.',
-    parameters:  getTimeSchema,
+    parameters:  Type.Object({}),
     execute: async () => ({ content: new Date().toISOString(), isError: false }),
   },
 ]
 
+// 3. Create agent and subscribe to events
 const agent = createAgent({ stream, tools, maxSteps: 8 })
 
 agent.subscribe((event) => {
   if (event.type === 'text_delta') process.stdout.write(event.delta)
 })
 
+// 4. Send a message and wait for completion
 agent.prompt({ type: 'user', payload: { parts: [{ type: 'text', text: 'What time is it?' }] } })
 await agent.waitForIdle()
 ```
 
+## Module Index
+
+| Import path | Contents |
+|---|---|
+| `@devxiyang/agent-kernel` | `Agent`, `createAgent`, `runLoop`, `wrapTool`, `EventStream`, all types |
+| `@devxiyang/agent-kernel/agent` | Agent module only |
+| `@devxiyang/agent-kernel/kernel` | `createKernel`, `KernelCache`, `listSessions`, `deleteSession`, `updateSessionMeta`, kernel types |
+| `@devxiyang/agent-kernel/event-stream` | `EventStream` |
+
+## Core Concepts
+
+| Concept | Description |
+|---|---|
+| `Agent` | Stateful runtime — orchestrates the model loop, tool execution, and event emission |
+| `Kernel` | Conversation store (in-memory or file-backed) with branching and compaction |
+| `KernelCache` | LRU + TTL cache for reusing kernel instances across requests |
+| `StreamFn` | Provider adapter — one function that calls your LLM and emits stream events |
+| `AgentTool` | Executable unit with a TypeBox schema for validation and provider schema generation |
+| `EventStream` | Async-iterable push stream primitive used internally by the loop |
+
+---
+
+## Agent API
+
+### Sending messages
+
+```ts
+// Start a new run (throws if agent is already running)
+agent.prompt(entry)
+
+// Send a message — the agent decides whether to start a new run or queue it
+// Safe to call whether the agent is idle or running
+agent.followUp(entry)
+```
+
+Use `followUp` when you don't want to manage the agent's running state yourself. It starts a new run when idle and queues the message for the next run otherwise. `prompt` is a lower-level method that gives you explicit control: it throws if the agent is already running, forcing you to decide between `followUp` and `steer`.
+
+### Steering (mid-run interruption)
+
+`steer` injects a message that the loop picks up *between tool calls* in the current run. Unlike `followUp`, it interrupts the current turn rather than waiting for the run to finish.
+
+```ts
+// Safe to call while the agent is running
+agent.steer({ type: 'user', payload: { parts: [{ type: 'text', text: 'Actually, focus only on security.' }] } })
+```
+
+When a steering message arrives, the loop skips any remaining tool calls in the current batch (writing `"Skipped: user interrupted."` results to keep the conversation consistent) and immediately processes the steering message.
+
+**`steer` vs `followUp`**
+
+| | `followUp` | `steer` |
+|---|---|---|
+| When processed | After the current run ends | Between tool calls in the current run |
+| Effect | Continues the outer loop | Interrupts the current tool batch |
+| Use case | Next user turn | Real-time redirection mid-task |
+
+### Waiting for completion
+
+```ts
+await agent.waitForIdle()
+```
+
+Resolves when the agent is truly idle — no running loop and no queued follow-up messages. Useful in request-response contexts (e.g., IPC handlers) where the caller needs to wait for all events to be dispatched before returning.
+
+```ts
+// IPC handler pattern
+async function handleMessage(entry: AgentEntry) {
+  agent.followUp(entry)
+  await agent.waitForIdle()
+  // all events have been dispatched to subscribers
+}
+```
+
+If a subscriber calls `followUp` inside an `agent_end` handler, `waitForIdle` will continue waiting for that follow-up run to finish as well.
+
+### Recovery
+
+```ts
+// Resume after an error or abort, or drain queued follow-up/steering messages
+// Throws if already running or nothing to continue from
+agent.continue()
+```
+
+### Aborting and resetting
+
+```ts
+agent.abort()   // cancel the current run (no-op if idle)
+agent.reset()   // clear all queues and transient state (throws if running)
+```
+
+### Subscribing to events
+
+```ts
+const unsubscribe = agent.subscribe((event) => {
+  switch (event.type) {
+    case 'agent_start':   /* run began */ break
+    case 'turn_start':    /* LLM call starting */ break
+    case 'text_delta':    /* streaming text chunk */ break
+    case 'reasoning_delta': /* streaming reasoning chunk */ break
+    case 'tool_call':     /* tool invocation */ break
+    case 'tool_update':   /* partial tool progress */ break
+    case 'tool_result':   /* tool finished */ break
+    case 'message_end':   /* assistant message committed */ break
+    case 'step_done':     /* step usage stats */ break
+    case 'turn_end':      /* turn finished with tool results */ break
+    case 'agent_end':     /* run finished (check event.error) */ break
+  }
+})
+
+// Stop receiving events
+unsubscribe()
+```
+
+### Inspecting state
+
+```ts
+const { isRunning, streamEntry, pendingToolCalls, error } = agent.state
+
+// Access the underlying kernel
+const entries = agent.kernel.read()
+```
+
+---
+
+## Kernel
+
+The `Kernel` is the conversation store. It holds the full message history as an in-memory linked tree and optionally persists it to `kernel.jsonl`.
+
+### Creating a kernel
+
+```ts
+import { createKernel } from '@devxiyang/agent-kernel/kernel'
+
+// In-memory only (useful for testing)
+const kernel = createKernel()
+
+// File-backed — loads from disk if session exists
+const kernel = createKernel({
+  dir:       './.agent-sessions',
+  sessionId: 'my-session',
+  meta:      { title: 'Code review assistant' },
+})
+```
+
+### Reading conversation history
+
+```ts
+// All entries on the current branch (root → leaf)
+const entries = kernel.read()
+
+// Most recent entry (or null if empty)
+const last = kernel.peek()
+
+// Build provider-agnostic messages for passing to StreamFn
+const messages = kernel.buildMessages()
+```
+
+### Appending entries
+
+```ts
+kernel.append({ type: 'user', payload: { parts: [{ type: 'text', text: 'Hello' }] } })
+```
+
+The `Agent` calls `append` automatically during the loop. Call it directly only when working with a bare kernel outside of an agent.
+
+### Context budget
+
+```ts
+// Set a token limit; onContextFull fires when contextSize >= limit
+kernel.budget.set(80_000)
+
+console.log(kernel.contextSize)  // input tokens from the last assistant entry
+console.log(kernel.budget.limit) // current limit
+console.log(kernel.budget.used)  // same as contextSize
+```
+
+### Compaction
+
+Replace a range of entries with a summary to reduce context size:
+
+```ts
+const entries = kernel.read()
+// Compact the first half of the conversation
+kernel.compact(
+  entries[0].id,
+  entries[Math.floor(entries.length / 2)].id,
+  'Summary: discussed project setup and requirements.',
+)
+```
+
+Compaction rewrites `kernel.jsonl` to the clean current branch and appends a divider to `log.jsonl`.
+
+### Branching
+
+```ts
+// Rewind the conversation to a past entry (discards entries after toId in memory)
+kernel.branch(toId)
+```
+
+### Session files
+
+Each session writes three files to `<dir>/<sessionId>/`:
+
+| File | Contents |
+|---|---|
+| `kernel.jsonl` | Current branch only; rewritten on compaction |
+| `log.jsonl` | Append-only full history; never compacted; used for UI display |
+| `meta.json` | Session metadata (`createdAt`, `title`, custom fields) |
+
+---
+
+## KernelCache
+
+When an agent handles multiple sessions, recreating a `Kernel` from `kernel.jsonl` on every request adds unnecessary I/O. `KernelCache` keeps hot kernels in memory with LRU eviction and TTL expiry.
+
+```ts
+import { KernelCache } from '@devxiyang/agent-kernel/kernel'
+
+const cache = new KernelCache({
+  dir:     './.agent-sessions',
+  maxSize: 100,           // keep at most 100 kernels in memory (default: 50)
+  ttl:     15 * 60_000,   // evict after 15 min of inactivity (default: 30 min)
+})
+```
+
+### Per-request pattern
+
+```ts
+async function handleRequest(sessionId: string, text: string) {
+  // Kernel is reused across requests; Agent is lightweight, created fresh each time
+  const kernel = cache.get(sessionId)
+  const agent  = new Agent(kernel, { stream, tools, maxSteps: 8 })
+
+  agent.subscribe(event => { /* forward events to client */ })
+
+  agent.followUp({ type: 'user', payload: { parts: [{ type: 'text', text }] } })
+  await agent.waitForIdle()
+}
+```
+
+The `Agent` is cheap to construct (no I/O, no async work) so creating one per request is fine. Only the `Kernel` — which holds the in-memory conversation tree — benefits from caching.
+
+### Cache API
+
+```ts
+// Get or create a kernel for sessionId; updates LRU order and resets TTL
+const kernel = cache.get(sessionId)
+
+// Optionally pass metadata written to meta.json on first creation
+const kernel = cache.get(sessionId, { title: 'My session' })
+
+// Remove a specific session from cache (kernel.jsonl is not touched)
+cache.evict(sessionId)
+
+// Remove all cached kernels
+cache.clear()
+
+// Number of kernels currently cached
+cache.size
+```
+
+---
+
+## Persistent Sessions
+
+```ts
+import { createAgent } from '@devxiyang/agent-kernel'
+
+const agent = createAgent({
+  stream, tools, maxSteps: 8,
+  session: {
+    dir:       './.agent-sessions',
+    sessionId: 'my-session',
+    meta:      { title: 'Code review assistant' },
+  },
+})
+
+agent.prompt({ type: 'user', payload: { parts: [{ type: 'text', text: 'Summarize our last discussion.' }] } })
+await agent.waitForIdle()
+
+// Manual compaction when context grows
+const entries = agent.kernel.read()
+if (entries.length > 12) {
+  agent.kernel.compact(entries[0].id, entries[8].id, 'Summary of earlier context.')
+}
+```
+
+## Session Management
+
+```ts
+import { listSessions, deleteSession, updateSessionMeta } from '@devxiyang/agent-kernel/kernel'
+
+// List all sessions, sorted by most recently updated
+const sessions = listSessions('./.agent-sessions')
+// [
+//   { sessionId: 'my-session', updatedAt: 1740000000000, messageCount: 12,
+//     meta: { createdAt: 1739999000000, title: 'Code review assistant' } },
+// ]
+
+// Rename a session
+updateSessionMeta('./.agent-sessions', 'my-session', { title: 'New title' })
+
+// Delete a session
+deleteSession('./.agent-sessions', 'my-session')
+```
+
+All functions are safe to call on non-existent paths — `listSessions` returns `[]`, the others are silent no-ops.
+
+### `SessionInfo` type
+
+```ts
+type SessionMeta = {
+  createdAt: number   // Unix ms — set once, never overwritten
+  title?:    string
+}
+
+type SessionInfo = {
+  sessionId:    string
+  updatedAt:    number        // log.jsonl mtime in milliseconds
+  messageCount: number        // entries in log.jsonl
+  meta:         SessionMeta | null
+}
+```
+
 ---
 
 ## Defining Tools
 
-Tools carry their TypeBox schema in `parameters`. The loop validates and coerces LLM-supplied
-arguments before calling `execute`; validation errors are returned as `tool_result` so the LLM
-can retry with corrected parameters.
+TypeBox schemas in `parameters` drive both runtime validation and the JSON Schema passed to the LLM. The `execute` input type is inferred — no manual annotation needed.
 
 ```ts
 import { Type } from '@sinclair/typebox'
@@ -112,7 +420,6 @@ const searchSchema = Type.Object({
   limit: Type.Optional(Type.Number({ description: 'Max results (default 10)' })),
 })
 
-// typeof searchSchema drives the input type — no manual annotation needed
 const searchTool: AgentTool<typeof searchSchema> = {
   name:        'search_docs',
   description: 'Search project documentation by query.',
@@ -128,16 +435,12 @@ const searchTool: AgentTool<typeof searchSchema> = {
 }
 ```
 
-`parameters` is a standard JSON Schema at runtime (TypeBox schemas are JSON Schema), so
-provider adapters can pass `tool.parameters` directly to any LLM API.
+Validation errors are returned as `isError: true` tool results so the LLM can self-correct.
 
 ---
 
 ## Implementing a `StreamFn`
 
-`StreamFn` receives the current conversation messages and the full tool list on every call.
-Use `tools` to generate the provider-specific schema — no hardcoding needed.
-
 ```ts
 type StreamFn = (
   messages: AgentMessage[],
@@ -147,30 +450,27 @@ type StreamFn = (
 ) => Promise<LLMStepResult>
 ```
 
+The function receives the full conversation and tool list on every call. Use `tool.parameters` (plain JSON Schema) to generate provider-specific tool definitions.
+
 ---
 
-## Example: OpenAI SDK Adapter
+## Adapter Examples
 
-Uses the OpenAI Responses API. Tools are converted from TypeBox schemas on every call.
+### OpenAI SDK
 
 ```ts
 import OpenAI from 'openai'
-import type { AgentMessage, StreamFn, ToolCallInfo } from '@devxiyang/agent-kernel'
+import type { StreamFn, ToolCallInfo } from '@devxiyang/agent-kernel'
 
 const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
 
-function toOpenAIMessages(messages: AgentMessage[]) {
-  return messages.map((m) => ({
-    role:    m.role as 'user' | 'assistant' | 'tool',
-    content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
-  }))
-}
-
 export const openaiStream: StreamFn = async (messages, tools, onEvent, signal) => {
   const response = await client.responses.create({
     model: 'gpt-4o',
-    input: toOpenAIMessages(messages),
-    // TypeBox schemas are plain JSON Schema — pass them directly
+    input: messages.map((m) => ({
+      role:    m.role as 'user' | 'assistant' | 'tool',
+      content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+    })),
     tools: tools.map((t) => ({
       type:        'function' as const,
       name:        t.name,
@@ -218,70 +518,21 @@ export const openaiStream: StreamFn = async (messages, tools, onEvent, signal) =
     },
   }
 }
-
-// Usage
-import { Type } from '@sinclair/typebox'
-import { createAgent } from '@devxiyang/agent-kernel'
-
-const searchSchema = Type.Object({
-  query: Type.String({ description: 'Search query string' }),
-})
-
-const agent = createAgent({
-  stream: openaiStream,
-  tools: [
-    {
-      name:        'search_docs',
-      description: 'Search project documentation by query.',
-      parameters:  searchSchema,
-      execute: async (_id, input) => ({
-        content:  `Results for: ${input.query}`,
-        isError:  false,
-      }),
-    },
-  ],
-  maxSteps: 10,
-})
-
-agent.subscribe((e) => { if (e.type === 'text_delta') process.stdout.write(e.delta) })
-agent.prompt({ type: 'user', payload: { parts: [{ type: 'text', text: 'Find compact API docs' }] } })
-await agent.waitForIdle()
 ```
 
----
-
-## Example: Vercel AI SDK v6 Adapter
-
-Uses `streamText` from `ai`. Tools without an `execute` function are returned as tool calls
-for our loop to handle. `jsonSchema()` wraps TypeBox schemas as AI SDK-compatible schemas.
+### Vercel AI SDK
 
 ```ts
 import { streamText, jsonSchema, tool } from 'ai'
 import { openai } from '@ai-sdk/openai'
-import type { AgentMessage, StreamFn, ToolCallInfo } from '@devxiyang/agent-kernel'
-
-function toAISDKMessages(messages: AgentMessage[]) {
-  return messages.map((m) => {
-    if (m.role === 'tool') {
-      // tool_result entries — AI SDK expects role 'tool'
-      const payload = m.content as { toolCallId: string; content: string }
-      return { role: 'tool' as const, content: [{ type: 'tool-result' as const, toolCallId: payload.toolCallId, result: payload.content }] }
-    }
-    return {
-      role:    m.role as 'user' | 'assistant',
-      content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
-    }
-  })
-}
+import type { StreamFn, ToolCallInfo } from '@devxiyang/agent-kernel'
 
 export const aiSdkStream: StreamFn = async (messages, tools, onEvent, signal) => {
-  // Build AI SDK tool definitions — no execute, our loop handles execution
   const aiTools = Object.fromEntries(
     tools.map((t) => [
       t.name,
       tool({
         description: t.description,
-        // jsonSchema() accepts any plain JSON Schema — TypeBox schemas qualify
         inputSchema: t.parameters ? jsonSchema(t.parameters) : jsonSchema({ type: 'object', properties: {} }),
       }),
     ]),
@@ -289,9 +540,12 @@ export const aiSdkStream: StreamFn = async (messages, tools, onEvent, signal) =>
 
   const result = streamText({
     model:       openai('gpt-4o'),
-    messages:    toAISDKMessages(messages),
+    messages:    messages.map((m) => ({
+      role:    m.role as 'user' | 'assistant',
+      content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
+    })),
     tools:       aiTools,
-    maxSteps:    1,          // one LLM call per StreamFn invocation; our kernel loops
+    maxSteps:    1,
     abortSignal: signal,
   })
 
@@ -326,200 +580,87 @@ export const aiSdkStream: StreamFn = async (messages, tools, onEvent, signal) =>
     },
   }
 }
-
-// Usage
-import { Type } from '@sinclair/typebox'
-import { createAgent } from '@devxiyang/agent-kernel'
-
-const searchSchema = Type.Object({
-  query: Type.String({ description: 'Search query string' }),
-})
-
-const agent = createAgent({
-  stream: aiSdkStream,
-  tools: [
-    {
-      name:        'search_docs',
-      description: 'Search project documentation by query.',
-      parameters:  searchSchema,
-      execute: async (_id, input) => ({
-        content:  `Results for: ${input.query}`,
-        isError:  false,
-      }),
-    },
-  ],
-  maxSteps: 10,
-})
-
-agent.subscribe((e) => { if (e.type === 'text_delta') process.stdout.write(e.delta) })
-agent.prompt({ type: 'user', payload: { parts: [{ type: 'text', text: 'Find compact API docs' }] } })
-await agent.waitForIdle()
 ```
 
 ---
 
-## Advanced Agent Options
+## Advanced Options
 
 ### Parallel Tool Execution
 
-By default tools run sequentially. Set `parallelTools: true` to run all tool calls in a turn concurrently with `Promise.allSettled`. If a steering message arrives after all tools complete, their results are discarded and replaced with skipped markers.
+Run all tool calls in a turn concurrently. If a steering message arrives after execution, results are discarded and replaced with skipped markers.
 
 ```ts
-const agent = createAgent({
-  stream, tools, maxSteps: 10,
-  parallelTools: true,
-})
+const agent = createAgent({ stream, tools, maxSteps: 10, parallelTools: true })
 ```
 
 ### Tool Timeout
 
-Set a per-tool execution deadline in milliseconds. Tools that exceed it return an `isError: true` result so the LLM can handle the failure gracefully.
+Per-call deadline in milliseconds. Timed-out tools return `isError: true` so the LLM can handle the failure.
 
 ```ts
-const agent = createAgent({
-  stream, tools, maxSteps: 10,
-  toolTimeout: 15_000, // 15 s per tool call
-})
-```
-
-### Auto-Compaction Hook (`onContextFull`)
-
-Fires after a step when `kernel.contextSize >= kernel.budget.limit`. The callback is responsible for compacting the kernel; the loop just provides the hook.
-
-```ts
-const agent = createAgent({
-  stream, tools, maxSteps: 10,
-  onContextFull: async (kernel) => {
-    const entries = kernel.read()
-    const from = entries[0].id
-    const to   = entries[Math.floor(entries.length / 2)].id
-    kernel.compact(from, to, 'Earlier context summarised.')
-  },
-})
-
-agent.kernel.budget.set(80_000) // tokens — trigger at 80 k input tokens
+const agent = createAgent({ stream, tools, maxSteps: 10, toolTimeout: 15_000 })
 ```
 
-Only fires when `budget.limit` is explicitly set (the default is `Infinity`).
-
 ### Stream Error Retry
 
-Automatically retry transient LLM errors with a fixed delay. Abort signals are respected — no retry happens after abort.
+Retry transient LLM errors with a fixed delay. Abort signals are respected — no retry after abort.
 
 ```ts
 const agent = createAgent({
   stream, tools, maxSteps: 10,
-  retryOnError: {
-    maxAttempts: 3,  // total attempts including the first
-    delayMs:     500,
-  },
+  retryOnError: { maxAttempts: 3, delayMs: 500 },
 })
 ```
 
-Only `stream()` calls are retried; tool execution is not affected.
+### Auto-Compaction (`onContextFull`)
 
----
-
-## Persistent Session + Kernel Compaction
+Fires after a step when `kernel.contextSize >= kernel.budget.limit`. Set `kernel.budget` to activate.
 
 ```ts
-import { createAgent } from '@devxiyang/agent-kernel'
-
 const agent = createAgent({
-  stream:   openaiStream,   // or aiSdkStream
-  tools:    [],
-  maxSteps: 8,
-  session: {
-    dir:       './.agent-sessions',
-    sessionId: 'demo-session-001',
+  stream, tools, maxSteps: 10,
+  onContextFull: async (kernel) => {
+    const entries = kernel.read()
+    kernel.compact(entries[0].id, entries[Math.floor(entries.length / 2)].id, 'Earlier context summarised.')
   },
 })
 
-agent.prompt({ type: 'user', payload: { parts: [{ type: 'text', text: 'Summarize our last discussion.' }] } })
-await agent.waitForIdle()
-
-// Compact old entries when context grows
-const entries = agent.kernel.read()
-if (entries.length > 12) {
-  const fromId = entries[0].id
-  const toId   = entries[Math.min(8, entries.length - 1)].id
-  agent.kernel.compact(fromId, toId, 'Summary of earlier context and decisions.')
-}
+agent.kernel.budget.set(80_000) // trigger at 80 k input tokens
 ```
 
-Session files are written under `./.agent-sessions/<sessionId>/` (`kernel.jsonl`, `log.jsonl`).
-
 ---
 
-## Session Management
+## Tool Hooks (`wrapTool`)
 
-`listSessions`, `deleteSession`, and `updateSessionMeta` are standalone utilities for CLI and Web API use cases.
+Intercept tool calls before or after execution without modifying the original tool.
 
 ```ts
-import {
-  listSessions,
-  deleteSession,
-  updateSessionMeta,
-} from '@devxiyang/agent-kernel/kernel'
-
-// List all sessions, sorted by most recently updated
-const sessions = listSessions('./.agent-sessions')
-// [
-//   { sessionId: 'demo-001', updatedAt: 1740000000000, messageCount: 12,
-//     meta: { createdAt: 1739999000000, title: 'My first session' } },
-//   { sessionId: 'demo-002', updatedAt: 1739000000000, messageCount: 4,
-//     meta: { createdAt: 1738999000000 } },
-// ]
-
-// Delete a session
-deleteSession('./.agent-sessions', 'demo-001')
+import { wrapTool } from '@devxiyang/agent-kernel'
 
-// Update a session's metadata (merge — never overwrites createdAt)
-updateSessionMeta('./.agent-sessions', 'demo-002', { title: 'Renamed session' })
-```
-
-### Session Metadata
-
-Pass `meta` when creating a session to set an initial title or other fields. `createdAt` is set automatically on first creation and is never overwritten.
-
-```ts
-const agent = createAgent({
-  stream, tools, maxSteps: 8,
-  session: {
-    dir:       './.agent-sessions',
-    sessionId: 'my-session',
-    meta:      { title: 'Code review assistant' },
+const guardedTool = wrapTool(myTool, {
+  before: async (toolCallId, toolName, input) => {
+    if (!isAllowed(input)) return { action: 'block', reason: 'Not permitted.' }
+  },
+  after: async (toolCallId, toolName, result) => {
+    return { content: redact(result.content) }
   },
 })
 ```
 
-`SessionMeta` and `SessionInfo` types:
-
-```ts
-type SessionMeta = {
-  createdAt: number   // Unix ms — set once at creation
-  title?:    string
-}
-
-type SessionInfo = {
-  sessionId:    string        // directory name used as session ID
-  updatedAt:    number        // log.jsonl mtime in milliseconds
-  messageCount: number        // number of entries in log.jsonl
-  meta:         SessionMeta | null
-}
-```
-
-All functions are safe to call on non-existent paths — `listSessions` returns `[]`,
-`deleteSession` and `updateSessionMeta` are silent no-ops when the session does not exist.
+`before` can return `{ action: 'block', reason }` to skip execution; the reason is returned as `isError: true`. `after` can override `content`, `isError`, or `details`.
 
 ---
 
-## Build Output
-
-Compiled files and type declarations are generated into `dist/`.
+## Build & Test
 
 ```bash
-npm run build      # compile TypeScript to dist/
+npm run build      # compile TypeScript → dist/
 npm run typecheck  # type-check without emitting
 npm test           # run unit tests (vitest)
+npm run test:watch # watch mode
 ```
+
+## License
+
+[MIT](./LICENSE)

package/dist/core/agent/agent.d.ts

@@ -107,7 +107,7 @@ export declare class Agent {
      * Throws if called while running — abort() first.
      */
     reset(): void;
-    /** Resolves when the agent finishes its current run (or immediately if idle). */
+    /** Resolves when the agent is truly idle (no running loop, no queued follow-ups). */
     waitForIdle(): Promise<void>;
     private _run;
     private _consume;

package/dist/core/agent/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/core/agent/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/core/agent/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAG3D,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EAEV,YAAY,EACZ,SAAS,EACT,QAAQ,EAER,SAAS,EACV,MAAM,SAAS,CAAA;AAIhB,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,SAAS,EAAS,OAAO,CAAA;IACzB,mEAAmE;IACnE,WAAW,EAAO,UAAU,GAAG,IAAI,CAAA;IACnC,yCAAyC;IACzC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC7B,4DAA4D;IAC5D,KAAK,EAAa,MAAM,GAAG,IAAI,CAAA;CAChC;AAID;;;;;;GAMG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IAErC,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,iBAAiB,CAAkC;IAC3D,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,aAAa,CAAkC;IAEvD,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,eAAe,CAAiD;IAExE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IAGpE,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,gBAAgB,CAAO;IAC/B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,MAAM,CAAgC;gBAElC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY;IAiBtD,4EAA4E;IAC5E,IAAI,MAAM,IAAI,WAAW,CAAwB;IAEjD,yDAAyD;IACzD,IAAI,KAAK,IAAI,UAAU,CAOtB;IAID,yEAAyE;IACzE,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI;IAClC,8EAA8E;IAC9E,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IACnC,gEAAgE;IAChE,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IACtC,iEAAiE;IACjE,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAItC;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAOtD;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,EAAE,GAAG,IAAI;IAahD;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IA0BhB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,EAAE,GAAG,IAAI;IAI/C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,EAAE,GAAG,IAAI;IAMlD,oDAAoD;IACpD,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAiBb,qFAAqF;IAC/E,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAQlC,OAAO,CAAC,IAAI;YAqBE,QAAQ;IAsBtB,OAAO,CAAC,YAAY;IAmDpB,OAAO,CAAC,kBAAkB;YAWZ,cAAc;YAOd,cAAc;CAM7B;AAID,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,8DAA8D;IAC9D,OAAO,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;KAAE,CAAA;CAC3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,KAAK,CAI/D"}

package/dist/core/agent/agent.js

@@ -175,13 +175,13 @@ export class Agent {
         this._error = null;
     }
     // ── Wait ────────────────────────────────────────────────────────────────
-    /** Resolves when the agent finishes its current run (or immediately if idle). */
+    /** Resolves when the agent is truly idle (no running loop, no queued follow-ups). */
     async waitForIdle() {
-        if (this._runningPromise) {
+        while (this._runningPromise) {
             try {
                 await this._runningPromise;
             }
-            catch { /* caller handles errors via subscribe */ }
+            catch { /* errors propagate via subscribe */ }
         }
     }
     // ── Private ─────────────────────────────────────────────────────────────
@@ -219,6 +219,9 @@ export class Agent {
         finally {
             this._abortController = null;
             this._runningPromise = null;
+            if (this._followUpQueue.length > 0) {
+                this._run();
+            }
         }
     }
     _handleEvent(event) {

package/dist/core/agent/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/core/agent/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/core/agent/agent.ts"],"names":[],"mappings":"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"}

package/dist/core/kernel/index.d.ts

@@ -7,6 +7,8 @@
 export type { Usage, DataContent, TextPart, ImagePart, AudioPart, VideoPart, FilePart, ContentPart, ImageMediaType, AudioMediaType, VideoMediaType, FileMediaType, StopReason, ToolCallInfo, AgentEntry, AgentMessage, StoredEntry, AppendResult, CompactionEntry, TokenBudget, AgentKernel, KernelOptions, SessionMeta, } from './types';
 export { COMPACTION_TYPE } from './types';
 export { createKernel } from './kernel';
+export type { KernelCacheOptions } from './kernel-cache';
+export { KernelCache } from './kernel-cache';
 export type { SessionInfo } from './session-store';
 export { listSessions, deleteSession, updateSessionMeta } from './session-store';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/kernel/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/kernel/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,KAAK,EACL,WAAW,EACX,QAAQ,EACR,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,WAAW,EACX,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,WAAW,EACX,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/kernel/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,KAAK,EACL,WAAW,EACX,QAAQ,EACR,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,WAAW,EACX,cAAc,EACd,cAAc,EACd,cAAc,EACd,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,WAAW,EACX,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/core/kernel/index.js

@@ -6,5 +6,6 @@
  */
 export { COMPACTION_TYPE } from './types';
 export { createKernel } from './kernel';
+export { KernelCache } from './kernel-cache';
 export { listSessions, deleteSession, updateSessionMeta } from './session-store';
 //# sourceMappingURL=index.js.map

package/dist/core/kernel/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/kernel/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGvC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/kernel/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4BH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAGvC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/core/kernel/kernel-cache.d.ts

@@ -0,0 +1,37 @@
+import type { AgentKernel, KernelOptions } from './types';
+export interface KernelCacheOptions {
+    /** Base directory for session persistence (passed to createKernel). */
+    dir: string;
+    /** Maximum number of kernels to keep in memory. LRU eviction. Default: 50 */
+    maxSize?: number;
+    /** Milliseconds of inactivity before a kernel is evicted. Default: 30 minutes */
+    ttl?: number;
+    /** Injectable time source for testing. Defaults to performance or Date. */
+    perf?: {
+        now(): number;
+    };
+}
+/**
+ * In-memory LRU cache of AgentKernel instances keyed by sessionId.
+ *
+ * Kernels are expensive to recreate because loadFromFile replays kernel.jsonl
+ * on every cold start. KernelCache keeps hot sessions in memory and evicts
+ * them by LRU order or TTL, falling back to file-based restore on cache miss.
+ */
+export declare class KernelCache {
+    private readonly _dir;
+    private readonly _cache;
+    constructor(options: KernelCacheOptions);
+    /**
+     * Return the cached kernel for sessionId, or create one from disk.
+     * Updates LRU order and TTL on every call.
+     */
+    get(sessionId: string, meta?: KernelOptions['meta']): AgentKernel;
+    /** Remove a specific session from the cache. */
+    evict(sessionId: string): void;
+    /** Remove all cached kernels. */
+    clear(): void;
+    /** Number of kernels currently in cache. */
+    get size(): number;
+}
+//# sourceMappingURL=kernel-cache.d.ts.map

package/dist/core/kernel/kernel-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-cache.d.ts","sourceRoot":"","sources":["../../../src/core/kernel/kernel-cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAIzD,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAA;IACX,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,IAAI,CAAC,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAA;CACzB;AAID;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAE1C,OAAO,EAAE,kBAAkB;IASvC;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,WAAW;IASjE,gDAAgD;IAChD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,iCAAiC;IACjC,KAAK,IAAI,IAAI;IAIb,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/core/kernel/kernel-cache.js

@@ -0,0 +1,47 @@
+import { LRUCache } from 'lru-cache';
+import { createKernel } from './kernel';
+// ─── KernelCache ──────────────────────────────────────────────────────────────
+/**
+ * In-memory LRU cache of AgentKernel instances keyed by sessionId.
+ *
+ * Kernels are expensive to recreate because loadFromFile replays kernel.jsonl
+ * on every cold start. KernelCache keeps hot sessions in memory and evicts
+ * them by LRU order or TTL, falling back to file-based restore on cache miss.
+ */
+export class KernelCache {
+    _dir;
+    _cache;
+    constructor(options) {
+        this._dir = options.dir;
+        this._cache = new LRUCache({
+            max: options.maxSize ?? 50,
+            ttl: options.ttl ?? 30 * 60 * 1000,
+            ...(options.perf && { perf: options.perf }),
+        });
+    }
+    /**
+     * Return the cached kernel for sessionId, or create one from disk.
+     * Updates LRU order and TTL on every call.
+     */
+    get(sessionId, meta) {
+        const cached = this._cache.get(sessionId);
+        if (cached)
+            return cached;
+        const kernel = createKernel({ dir: this._dir, sessionId, meta });
+        this._cache.set(sessionId, kernel);
+        return kernel;
+    }
+    /** Remove a specific session from the cache. */
+    evict(sessionId) {
+        this._cache.delete(sessionId);
+    }
+    /** Remove all cached kernels. */
+    clear() {
+        this._cache.clear();
+    }
+    /** Number of kernels currently in cache. */
+    get size() {
+        return this._cache.size;
+    }
+}
+//# sourceMappingURL=kernel-cache.js.map

package/dist/core/kernel/kernel-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-cache.js","sourceRoot":"","sources":["../../../src/core/kernel/kernel-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAgBvC,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,OAAO,WAAW;IACL,IAAI,CAAU;IACd,MAAM,CAA+B;IAEtD,YAAY,OAA2B;QACrC,IAAI,CAAC,IAAI,GAAK,OAAO,CAAC,GAAG,CAAA;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,CAAsB;YAC9C,GAAG,EAAG,OAAO,CAAC,OAAO,IAAI,EAAE;YAC3B,GAAG,EAAG,OAAO,CAAC,GAAG,IAAQ,EAAE,GAAG,EAAE,GAAG,IAAI;YACvC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;SAC5C,CAAC,CAAA;IACJ,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,SAAiB,EAAE,IAA4B;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;QACzC,IAAI,MAAM;YAAE,OAAO,MAAM,CAAA;QAEzB,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAChE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;QAClC,OAAO,MAAM,CAAA;IACf,CAAC;IAED,gDAAgD;IAChD,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAC/B,CAAC;IAED,iCAAiC;IACjC,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;IAED,4CAA4C;IAC5C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAA;IACzB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devxiyang/agent-kernel",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Agent kernel and loop library",
   "license": "MIT",
   "repository": {
@@ -52,6 +52,7 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.48"
+    "@sinclair/typebox": "^0.34.48",
+    "lru-cache": "^11.2.6"
   }
 }