@m4ike1/ion-agent-core 0.1.0

package/README.md

@@ -0,0 +1,622 @@
+# @m4ike1/ion-agent-core
+
+Stateful agent runtime with tool execution and event streaming. Built on `@m4ike1/ion-ai`.
+
+The `Agent` class owns the transcript, runs the prompt → LLM → tool loop, and emits
+lifecycle events for UI updates. For details see
+[docs/how-to.md](docs/how-to.md) (recipes) and
+[docs/api-reference.md](docs/api-reference.md) (API dictionary).
+The durable conversation/session harness in this package is specified separately in
+[docs/harness.md](docs/harness.md).
+
+## Installation
+
+```bash
+npm install @m4ike1/ion-agent-core
+```
+
+### Entrypoints
+
+```typescript
+import { Agent } from "@m4ike1/ion-agent-core"; // core runtime (Agent, agentLoop, streamProxy, types)
+import { NodeExecutionEnv } from "@m4ike1/ion-agent-core/node"; // Node execution env + everything above
+import type { ... } from "@m4ike1/ion-agent-core/harness/session"; // session layer
+import type { ... } from "@m4ike1/ion-agent-core/harness/session/testing"; // session test helpers
+import { reduceLaneSnapshot } from "@m4ike1/ion-agent-core/harness/runtime/reducer";
+import type { ... } from "@m4ike1/ion-agent-core/harness/context";
+import { NodeExecutionEnv } from "@m4ike1/ion-agent-core/harness/env/nodejs";
+```
+
+### SQLite session backends
+
+The SQLite session backend and the `node:sqlite` adapter live in a separate package,
+`@m4ike1/ion-session-backend-sqlite-node`, so the core package does not pull in
+runtime builtins or native SQLite dependencies by default. The backend accepts a
+runtime-specific SQLite factory, allowing other session backends to ship as their
+own packages in the future.
+
+## Quick Start
+
+```typescript
+import { Agent } from "@m4ike1/ion-agent-core";
+import { createModels } from "@m4ike1/ion-ai";
+import { anthropicProvider } from "@m4ike1/ion-ai/providers/anthropic";
+
+const models = createModels();
+models.setProvider(anthropicProvider());
+const model = models.getModel("anthropic", "claude-sonnet-4-6");
+if (!model) throw new Error("Model not found");
+
+const agent = new Agent({
+  initialState: {
+    systemPrompt: "You are a helpful assistant.",
+    model,
+  },
+  streamFn: models.streamSimple.bind(models),
+});
+
+agent.subscribe((event) => {
+  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+    // Stream just the new text chunk
+    process.stdout.write(event.assistantMessageEvent.delta);
+  }
+});
+
+await agent.prompt("Hello!");
+```
+
+`streamFn` defaults to the function installed via `setDefaultStreamFn()` when omitted.
+`Models.streamSimple` satisfies the `StreamFn` contract: never throw for
+request/model/runtime failures; encode failures in the returned stream as a final
+`AssistantMessage` with `stopReason` `"error"` / `"aborted"`.
+
+## Experimental facet services
+
+Transport-neutral facet-service primitives live in `@m4ike1/chord`. The agent core
+does not export the service runtime.
+
+## Core Concepts
+
+### AgentMessage vs LLM Message
+
+The agent works with `AgentMessage`, a flexible type that can include:
+
+- Standard LLM messages (`user`, `assistant`, `toolResult`)
+- Custom app-specific message types via declaration merging
+
+LLMs only understand `user`, `assistant`, and `toolResult`. The `convertToLlm`
+function bridges this gap by filtering and transforming messages before each LLM call.
+The default `convertToLlm` passes through only `user` / `assistant` / `toolResult`.
+
+### Message Flow
+
+```text
+AgentMessage[] → transformContext() → AgentMessage[] → convertToLlm() → Message[] → LLM
+                    (optional)                           (required)
+```
+
+1. **transformContext**: Prune old messages, inject external context
+2. **convertToLlm**: Filter out UI-only messages, convert custom types to LLM format
+
+Both hooks must not throw or reject; return a safe fallback instead. A throwing
+`convertToLlm`, `shouldStopAfterTurn`, or `prepareNextTurn` interrupts the low-level
+loop without producing a normal event sequence.
+
+## Event Flow
+
+The agent emits events for UI updates. Understanding the event sequence helps build
+responsive interfaces.
+
+### prompt() Event Sequence
+
+When you call `prompt("Hello")`:
+
+```text
+prompt("Hello")
+├─ agent_start
+├─ turn_start
+├─ message_start   { message: userMessage }      // Your prompt
+├─ message_end     { message: userMessage }
+├─ message_start   { message: assistantMessage } // LLM starts responding
+├─ message_update  { message: partial... }       // Streaming chunks
+├─ message_update  { message: partial... }
+├─ message_end     { message: assistantMessage } // Complete response
+├─ turn_end        { message, toolResults: [] }
+└─ agent_end       { messages: [...] }
+```
+
+### With Tool Calls
+
+If the assistant calls tools, the loop continues:
+
+```text
+prompt("Read config.json")
+├─ agent_start
+├─ turn_start
+├─ message_start/end  { userMessage }
+├─ message_start      { assistantMessage with toolCall }
+├─ message_update...
+├─ message_end        { assistantMessage }
+├─ tool_execution_start  { toolCallId, toolName, args }
+├─ tool_execution_update { partialResult }           // If tool streams
+├─ tool_execution_end    { toolCallId, result }
+├─ message_start/end  { toolResultMessage }
+├─ turn_end           { message, toolResults: [toolResult] }
+│
+├─ turn_start                                        // Next turn
+├─ message_start      { assistantMessage }           // LLM responds to tool result
+├─ message_update...
+├─ message_end
+├─ turn_end
+└─ agent_end
+```
+
+Tool execution mode is configurable:
+
+- `parallel` (default): preflight tool calls sequentially, execute allowed tools
+  concurrently, emit `tool_execution_end` as soon as each tool is finalized, then
+  emit toolResult messages and `turn_end.toolResults` in assistant source order
+- `sequential`: execute tool calls one by one, matching the historical behavior
+
+In parallel mode, tool completion events follow tool completion order, but persisted
+toolResult messages still follow assistant source order.
+
+The mode can be set globally via `toolExecution` in the agent config, or per-tool
+via `executionMode` on `AgentTool`. If any tool call in a batch targets a tool with
+`executionMode: "sequential"`, the entire batch executes sequentially regardless of
+the global setting.
+
+The `beforeToolCall` hook runs after `tool_execution_start` and validated argument
+parsing. It can block execution and attach `terminate: true` to the blocked result.
+The `afterToolCall` hook runs after tool execution finishes and before
+`tool_execution_end` and final tool result message events are emitted.
+
+Tools, blocked `beforeToolCall` results, and `afterToolCall` overrides can return
+`terminate: true` to hint that the automatic follow-up LLM call should be skipped.
+The loop only stops early when every finalized tool result in that batch sets
+`terminate: true`. Mixed batches continue normally.
+
+When you use the `Agent` class, assistant `message_end` processing is treated as a
+barrier before tool preflight begins. That means `beforeToolCall` sees agent state
+that already includes the assistant message that requested the tool call.
+
+### Truncated responses
+
+If the assistant message ends with `stopReason: "length"` (output token limit hit),
+no tool call in that message is executed: streamed tool-call arguments may be
+silently truncated, so each call is reported as an error result and the model is
+asked to re-issue the calls with complete arguments.
+
+### continue() Event Sequence
+
+`continue()` resumes from existing context without adding a new message. Use it for
+retries after errors.
+
+```typescript
+// After an error, retry from current state
+await agent.continue();
+```
+
+The last message in context must be `user` or `toolResult` (not `assistant`).
+If the last message is `assistant` but a steering or follow-up message is queued,
+`continue()` runs the queued message instead of throwing.
+
+### Event Types
+
+| Event | Description |
+|-------|-------------|
+| `agent_start` | Agent begins processing |
+| `agent_end` | Final event for the run. Awaited subscribers for this event still count toward settlement |
+| `turn_start` | New turn begins (one LLM call + tool executions) |
+| `turn_end` | Turn completes with assistant message and tool results |
+| `message_start` | Any message begins (user, assistant, toolResult) |
+| `message_update` | **Assistant only.** Includes `assistantMessageEvent` with delta |
+| `message_end` | Message completes |
+| `tool_execution_start` | Tool begins |
+| `tool_execution_update` | Tool streams progress |
+| `tool_execution_end` | Tool completes |
+
+`Agent.subscribe()` listeners are awaited in registration order and receive the
+active run's `AbortSignal`. `agent_end` means no more loop events will be emitted,
+but `await agent.waitForIdle()` and `await agent.prompt(...)` only settle after
+awaited `agent_end` listeners finish. Raw `agentLoop()` / `agentLoopContinue()`
+streams are observational only: they preserve event order but do not wait for your
+async event handling to settle before later producer phases continue.
+
+## Agent Options
+
+See [docs/api-reference.md](docs/api-reference.md) for the full field dictionary.
+Common setup:
+
+```typescript
+const agent = new Agent({
+  // Initial state
+  initialState: {
+    systemPrompt: "You are a helpful assistant.",
+    model,
+    thinkingLevel: "medium", // "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
+    tools: [readFileTool],
+    messages: [],
+  },
+
+  // Convert AgentMessage[] to LLM Message[] (required for custom message types)
+  convertToLlm: (messages) => messages.filter(...),
+
+  // Transform context before convertToLlm (for pruning, compaction)
+  transformContext: async (messages, signal) => pruneOldMessages(messages),
+
+  // Steering mode: "one-at-a-time" (default) or "all"
+  steeringMode: "one-at-a-time",
+
+  // Follow-up mode: "one-at-a-time" (default) or "all"
+  followUpMode: "one-at-a-time",
+
+  // Stream function (falls back to setDefaultStreamFn() when omitted)
+  streamFn: models.streamSimple.bind(models),
+
+  // Session ID for provider caching
+  sessionId: "session-123",
+
+  // Dynamic API key resolution (for expiring OAuth tokens)
+  getApiKey: async (provider) => refreshToken(),
+
+  // Tool execution mode: "parallel" (default) or "sequential"
+  toolExecution: "parallel",
+
+  // Preflight each tool call after args are validated. Can block execution.
+  beforeToolCall: async ({ toolCall, args, context }) => {
+    if (toolCall.name === "bash") {
+      return { block: true, reason: "bash is disabled", terminate: true };
+    }
+  },
+
+  // Postprocess each tool result before final tool events are emitted.
+  afterToolCall: async ({ toolCall, result, isError, context }) => {
+    if (toolCall.name === "notify_done" && !isError) {
+      return { terminate: true };
+    }
+    if (!isError) {
+      return { details: { ...result.details, audited: true } };
+    }
+  },
+
+  // Stop gracefully after a completed turn, before queued messages are polled.
+  shouldStopAfterTurn: async ({ context }, signal) => {
+    return shouldCompactBeforeNextTurn(context.messages);
+  },
+
+  // Replace context/model/thinking state before the next turn starts.
+  prepareNextTurnWithContext: async ({ context, message }) => undefined,
+
+  // Custom thinking budgets for token-based providers
+  thinkingBudgets: {
+    minimal: 128,
+    low: 512,
+    medium: 1024,
+    high: 2048,
+  },
+});
+```
+
+The `Agent` class accepts `shouldStopAfterTurn` in `AgentOptions`. Low-level loop
+callers set the same hook in `AgentLoopConfig`. It runs after `turn_end` is emitted
+and after the assistant response and any tool executions have completed normally.
+If it returns `true`, the loop emits `agent_end` and exits before polling steering
+or follow-up queues, and before starting another LLM call. It does not abort the
+provider stream, does not cancel running tools, and does not alter the assistant
+message stop reason. The `AgentOptions` callback also receives the active run's
+`AbortSignal` as its second argument.
+
+## Agent State
+
+```typescript
+interface AgentState {
+  systemPrompt: string;
+  model: Model<any>;
+  thinkingLevel: ThinkingLevel;
+  tools: AgentTool<any>[];
+  messages: AgentMessage[];
+  readonly isStreaming: boolean;
+  readonly streamingMessage?: AgentMessage;
+  readonly pendingToolCalls: ReadonlySet<string>;
+  readonly errorMessage?: string;
+}
+```
+
+Access state via `agent.state`.
+
+Assigning `agent.state.tools = [...]` or `agent.state.messages = [...]` copies the
+top-level array before storing it. Mutating the returned array mutates the current
+agent state.
+
+During streaming, `agent.state.streamingMessage` contains the current partial
+assistant message.
+
+`agent.state.isStreaming` remains `true` until the run fully settles, including
+awaited `agent_end` subscribers. `agent.state.errorMessage` holds the error message
+from the most recent failed or aborted assistant turn, if any.
+
+## Methods
+
+### Prompting
+
+```typescript
+// Text prompt
+await agent.prompt("Hello");
+
+// With images
+await agent.prompt("What's in this image?", [
+  { type: "image", data: base64Data, mimeType: "image/jpeg" }
+]);
+
+// AgentMessage directly
+await agent.prompt({ role: "user", content: [{ type: "text", text: "Hello" }], timestamp: Date.now() });
+
+// Batch of messages
+await agent.prompt([msg1, msg2]);
+
+// Continue from current context (last message must be user or toolResult)
+await agent.continue();
+```
+
+Only one run at a time: `prompt()` / `continue()` throw while a run is active. Use
+`steer()` / `followUp()` to queue messages, or wait for completion. `reset()`
+throws while a run is active.
+
+### State Management
+
+```typescript
+agent.state.systemPrompt = "New prompt";
+agent.state.model = getModel("openai", "gpt-4o");
+agent.state.thinkingLevel = "medium";
+agent.state.tools = [myTool];
+agent.toolExecution = "sequential";
+agent.beforeToolCall = async ({ toolCall }) => undefined;
+agent.afterToolCall = async ({ toolCall, result }) => undefined;
+agent.shouldStopAfterTurn = async ({ context }) => shouldCompactBeforeNextTurn(context.messages);
+agent.state.messages = newMessages; // top-level array is copied
+agent.state.messages.push(message);
+agent.reset(); // clears transcript, runtime state, and both queues
+```
+
+### Session and Thinking Budgets
+
+```typescript
+agent.sessionId = "session-123";
+
+agent.thinkingBudgets = {
+  minimal: 128,
+  low: 512,
+  medium: 1024,
+  high: 2048,
+};
+```
+
+### Control
+
+```typescript
+agent.abort();             // Cancel current operation
+await agent.waitForIdle(); // Wait for completion (settles after awaited agent_end listeners)
+agent.signal;              // Active run AbortSignal, if any
+agent.hasQueuedMessages(); // True when either queue still holds messages
+```
+
+### Events
+
+```typescript
+const unsubscribe = agent.subscribe(async (event, signal) => {
+  if (event.type === "agent_end") {
+    // Final barrier work for the run
+    await flushSessionState(signal);
+  }
+});
+unsubscribe();
+```
+
+## Steering and Follow-up
+
+Steering messages let you interrupt the agent while tools are running. Follow-up
+messages let you queue work after the agent would otherwise stop.
+
+```typescript
+agent.steeringMode = "one-at-a-time";
+agent.followUpMode = "one-at-a-time";
+
+// While agent is running tools
+agent.steer({
+  role: "user",
+  content: [{ type: "text", text: "Stop! Do this instead." }],
+  timestamp: Date.now(),
+});
+
+// After the agent finishes its current work
+agent.followUp({
+  role: "user",
+  content: [{ type: "text", text: "Also summarize the result." }],
+  timestamp: Date.now(),
+});
+
+const steeringMode = agent.steeringMode;
+const followUpMode = agent.followUpMode;
+
+agent.clearSteeringQueue();
+agent.clearFollowUpQueue();
+agent.clearAllQueues();
+```
+
+Use clearSteeringQueue, clearFollowUpQueue, or clearAllQueues to drop queued messages.
+
+When steering messages are detected after a turn completes:
+
+1. All tool calls from the current assistant message have already finished
+2. Steering messages are injected
+3. The LLM responds on the next turn
+
+Follow-up messages are checked only when there are no more tool calls and no
+steering messages. If any are queued, they are injected and another turn runs.
+
+Queue modes: `"one-at-a-time"` (default) drains only the oldest queued message per
+drain point; `"all"` drains every queued message at that point.
+
+## Custom Message Types
+
+Extend `AgentMessage` via declaration merging:
+
+```typescript
+declare module "@m4ike1/ion-agent-core" {
+  interface CustomAgentMessages {
+    notification: { role: "notification"; text: string; timestamp: number };
+  }
+}
+
+// Now valid
+const msg: AgentMessage = { role: "notification", text: "Info", timestamp: Date.now() };
+```
+
+Handle custom types in `convertToLlm`:
+
+```typescript
+const agent = new Agent({
+  streamFn: models.streamSimple.bind(models),
+  convertToLlm: (messages) => messages.flatMap(m => {
+    if (m.role === "notification") return []; // Filter out
+    return [m];
+  }),
+});
+```
+
+## Tools
+
+Define tools using `AgentTool`:
+
+```typescript
+import { Type } from "typebox";
+
+const readFileTool: AgentTool = {
+  name: "read_file",
+  label: "Read File",  // For UI display
+  description: "Read a file's contents",
+  parameters: Type.Object({
+    path: Type.String({ description: "File path" }),
+  }),
+  // Override execution mode for this tool (optional).
+  // "sequential" forces the entire batch to run one at a time.
+  // "parallel" allows concurrent execution with other tool calls.
+  // If omitted, the global toolExecution config applies.
+  executionMode: "sequential",
+  execute: async (toolCallId, params, signal, onUpdate) => {
+    const content = await fs.readFile(params.path, "utf-8");
+
+    // Optional: stream progress
+    onUpdate?.({ content: [{ type: "text", text: "Reading..." }], details: {} });
+
+    // Optional: add `terminate: true` here to skip the automatic follow-up LLM call
+    // when every finalized tool result in the batch does the same.
+    return {
+      content: [{ type: "text", text: content }],
+      details: { path: params.path, size: content.length },
+    };
+  },
+};
+
+agent.state.tools = [readFileTool];
+```
+
+`AgentTool` also supports `prepareArguments` (compatibility shim normalizing raw
+tool-call arguments to the schema before validation) and `replay` (`"never"` |
+`"safe"`, recovery policy for a durable effect whose outcome is unknown).
+
+### Error Handling
+
+**Throw an error** when a tool fails. Do not return error messages as content.
+
+```typescript
+execute: async (toolCallId, params, signal, onUpdate) => {
+  if (!fs.existsSync(params.path)) {
+    throw new Error(`File not found: ${params.path}`);
+  }
+  // Return content only on success
+  return { content: [{ type: "text", text: "..." }] };
+}
+```
+
+Thrown errors are caught by the agent and reported to the LLM as tool errors with
+`isError: true`.
+
+Return `terminate: true` from `execute()`, a blocked `beforeToolCall`, or
+`afterToolCall` to hint that the agent should stop after the current tool batch.
+This only takes effect when every finalized tool result in the batch is
+terminating. The hint is runtime-only; emitted `toolResult` transcript messages
+remain standard LLM tool results.
+
+## Proxy Usage
+
+For browser apps that proxy through a backend:
+
+```typescript
+import { Agent, streamProxy } from "@m4ike1/ion-agent-core";
+
+const agent = new Agent({
+  streamFn: (model, context, options) =>
+    streamProxy(model, context, {
+      ...options,
+      authToken: "...",
+      proxyUrl: "https://your-server.com",
+    }),
+});
+```
+
+`streamProxy` POSTs `{ model, context, options }` to `${proxyUrl}/api/stream` with a
+`Bearer` auth token and reconstructs the assistant stream client-side. Only
+serializable stream options are forwarded (temperature, samplingParams, maxTokens,
+reasoning, cacheRetention, sessionId, headers, metadata, transport,
+thinkingBudgets, maxRetryDelayMs).
+
+## Low-Level API
+
+For direct control without the Agent class:
+
+```typescript
+import { agentLoop, agentLoopContinue } from "@m4ike1/ion-agent-core";
+
+const context: AgentContext = {
+  systemPrompt: "You are helpful.",
+  messages: [],
+  tools: [],
+};
+
+const config: AgentLoopConfig = {
+  model: getModel("openai", "gpt-4o"),
+  convertToLlm: (msgs) => msgs.filter(m => ["user", "assistant", "toolResult"].includes(m.role)),
+  toolExecution: "parallel",  // overridden by per-tool executionMode if set
+  beforeToolCall: async ({ toolCall, args, context }) => undefined,
+  afterToolCall: async ({ toolCall, result, isError, context }) => undefined,
+  shouldStopAfterTurn: async ({ message, toolResults, context, newMessages }) => {
+    return shouldCompactBeforeNextTurn(context.messages);
+  },
+};
+
+const userMessage = { role: "user", content: [{ type: "text", text: "Hello" }], timestamp: Date.now() };
+
+const streamFn = models.streamSimple.bind(models);
+for await (const event of agentLoop([userMessage], context, config, undefined, streamFn)) {
+  console.log(event.type);
+}
+
+// Continue from existing context
+for await (const event of agentLoopContinue(context, config, undefined, streamFn)) {
+  console.log(event.type);
+}
+```
+
+`runAgentLoop` / `runAgentLoopContinue` are the promise-based variants: same
+arguments plus an `emit` sink, resolving to the new messages.
+
+These low-level streams are observational. They preserve event order, but they do
+not wait for your async event handling to settle before later producer phases
+continue. If you need message processing to act as a barrier before tool preflight,
+use the `Agent` class instead of raw `agentLoop()` or `agentLoopContinue()`.
+
+## License
+
+MIT

package/dist/agent-loop.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+import { EventStream } from "@m4ike1/ion-ai";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.ts";
+export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
+/**
+ * Start an agent loop with a new prompt message.
+ * The prompt is added to the context and events are emitted for it.
+ */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal: AbortSignal | undefined, streamFn: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Continue an agent loop from the current context without adding a new message.
+ * Used for retries - context already has user message or tool results.
+ *
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
+ */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal: AbortSignal | undefined, streamFn: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal: AbortSignal | undefined, streamFn: StreamFn): Promise<AgentMessage[]>;
+export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal: AbortSignal | undefined, streamFn: StreamFn): Promise<AgentMessage[]>;
+//# sourceMappingURL=agent-loop.d.ts.map