@openadapter/koda-agent-core 1.0.0-beta.3

package/README.md

@@ -0,0 +1,488 @@
+# @openadapter/koda-agent-core
+
+Stateful agent with tool execution and event streaming. Built on `@openadapter/koda-ai`.
+
+## Installation
+
+```bash
+npm install @openadapter/koda-agent-core
+```
+
+## Quick Start
+
+```typescript
+import { Agent } from "@openadapter/koda-agent-core";
+import { getModel } from "@openadapter/koda-ai";
+
+const agent = new Agent({
+  initialState: {
+    systemPrompt: "You are a helpful assistant.",
+    model: getModel("anthropic", "claude-sonnet-4-20250514"),
+  },
+});
+
+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!");
+```
+
+## 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.
+
+### Message Flow
+
+```
+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
+
+## 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")`:
+
+```
+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:
+
+```
+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. The `afterToolCall` hook runs after tool execution finishes and before `tool_execution_end` and final tool result message events are emitted.
+
+Tools can also 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.
+
+Low-level loop callers can set `shouldStopAfterTurn` to stop gracefully after the current turn completes:
+
+```typescript
+const stream = agentLoop(prompts, context, {
+  model,
+  convertToLlm,
+  shouldStopAfterTurn: async ({ message, toolResults, context, newMessages }) => {
+    return shouldCompactBeforeNextTurn(context.messages);
+  },
+});
+```
+
+`shouldStopAfterTurn` 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.
+
+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.
+
+### 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`).
+
+### 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. `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.
+
+## Agent Options
+
+```typescript
+const agent = new Agent({
+  // Initial state
+  initialState: {
+    systemPrompt: string,
+    model: Model<any>,
+    thinkingLevel: "off" | "minimal" | "low" | "medium" | "high" | "xhigh",
+    tools: AgentTool<any>[],
+    messages: AgentMessage[],
+  },
+
+  // 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",
+
+  // Custom stream function (for proxy backends)
+  streamFn: streamProxy,
+
+  // 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" };
+    }
+  },
+
+  // 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 } };
+    }
+  },
+
+  // Custom thinking budgets for token-based providers
+  thinkingBudgets: {
+    minimal: 128,
+    low: 512,
+    medium: 1024,
+    high: 2048,
+  },
+});
+```
+
+## 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.
+
+## 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: "Hello", timestamp: Date.now() });
+
+// Continue from current context (last message must be user or toolResult)
+await agent.continue();
+```
+
+### 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.state.messages = newMessages; // top-level array is copied
+agent.state.messages.push(message);
+agent.reset();
+```
+
+### 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
+```
+
+### 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: "Stop! Do this instead.",
+  timestamp: Date.now(),
+});
+
+// After the agent finishes its current work
+agent.followUp({
+  role: "user",
+  content: "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.
+
+## Custom Message Types
+
+Extend `AgentMessage` via declaration merging:
+
+```typescript
+declare module "@openadapter/koda-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({
+  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];
+```
+
+### 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()` 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 "@openadapter/koda-agent-core";
+
+const agent = new Agent({
+  streamFn: (model, context, options) =>
+    streamProxy(model, context, {
+      ...options,
+      authToken: "...",
+      proxyUrl: "https://your-server.com",
+    }),
+});
+```
+
+## Low-Level API
+
+For direct control without the Agent class:
+
+```typescript
+import { agentLoop, agentLoopContinue } from "@openadapter/koda-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,
+};
+
+const userMessage = { role: "user", content: "Hello", timestamp: Date.now() };
+
+for await (const event of agentLoop([userMessage], context, config)) {
+  console.log(event.type);
+}
+
+// Continue from existing context
+for await (const event of agentLoopContinue(context, config)) {
+  console.log(event.type);
+}
+```
+
+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,23 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+import { EventStream } from "@openadapter/koda-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, 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, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
+export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;

package/dist/agent-loop.js

@@ -0,0 +1 @@
+var N=Object.defineProperty;var g=(e,t)=>N(e,"name",{value:t,configurable:!0});import{EventStream as K,streamSimple as M,validateToolArguments as I}from"@openadapter/koda-ai";function z(e,t,n,o,s){const r=k();return q(e,t,n,async a=>{r.push(a)},o,s).then(a=>{r.end(a)}),r}g(z,"agentLoop");function G(e,t,n,o){if(e.messages.length===0)throw new Error("Cannot continue: no messages in context");if(e.messages[e.messages.length-1].role==="assistant")throw new Error("Cannot continue from message role: assistant");const s=k();return F(e,t,async r=>{s.push(r)},n,o).then(r=>{s.end(r)}),s}g(G,"agentLoopContinue");async function q(e,t,n,o,s,r){const a=[...e],l={...t,messages:[...t.messages,...e]};await o({type:"agent_start"}),await o({type:"turn_start"});for(const i of e)await o({type:"message_start",message:i}),await o({type:"message_end",message:i});return await b(l,a,n,s,o,r),a}g(q,"runAgentLoop");async function F(e,t,n,o,s){if(e.messages.length===0)throw new Error("Cannot continue: no messages in context");if(e.messages[e.messages.length-1].role==="assistant")throw new Error("Cannot continue from message role: assistant");const r=[],a={...e};return await n({type:"agent_start"}),await n({type:"turn_start"}),await b(a,r,t,o,n,s),r}g(F,"runAgentLoopContinue");function k(){return new K(e=>e.type==="agent_end",e=>e.type==="agent_end"?e.messages:[])}g(k,"createAgentStream");async function b(e,t,n,o,s,r){let a=e,l=n,i=!0;const c=Number(process.env.KODA_MAX_STEPS)||30;let m=0,u=await l.getSteeringMessages?.()||[];for(;;){let d=!0;for(;d||u.length>0;){if(i?i=!1:await s({type:"turn_start"}),u.length>0){for(const f of u)await s({type:"message_start",message:f}),await s({type:"message_end",message:f}),a.messages.push(f),t.push(f);u=[]}const p=await O(a,l,o,s,r);if(t.push(p),m++,p.stopReason==="error"||p.stopReason==="aborted"){await s({type:"turn_end",message:p,toolResults:[]}),await s({type:"agent_end",messages:t});return}const y=p.content.filter(f=>f.type==="toolCall"),C=[];if(d=!1,y.length>0){const f=await B(a,p,l,o,s);C.push(...f.messages),d=!f.terminate;for(const T of C)a.messages.push(T),t.push(T)}if(await s({type:"turn_end",message:p,toolResults:C}),m>=c&&d){await s({type:"agent_end",messages:t});return}const L={message:p,toolResults:C,context:a,newMessages:t},_=await l.prepareNextTurn?.(L);if(_&&(a=_.context??a,l={...l,model:_.model??l.model,reasoning:_.thinkingLevel===void 0?l.reasoning:_.thinkingLevel==="off"?void 0:_.thinkingLevel}),await l.shouldStopAfterTurn?.({message:p,toolResults:C,context:a,newMessages:t})){await s({type:"agent_end",messages:t});return}u=await l.getSteeringMessages?.()||[]}const w=await l.getFollowUpMessages?.()||[];if(w.length>0){u=w;continue}break}await s({type:"agent_end",messages:t})}g(b,"runLoop");async function O(e,t,n,o,s){let r=e.messages;t.transformContext&&(r=await t.transformContext(r,n));const a=await t.convertToLlm(r),l={systemPrompt:e.systemPrompt,messages:a,tools:e.tools},i=s||M,c=(t.getApiKey?await t.getApiKey(t.model.provider):void 0)||t.apiKey,m=await i(t.model,l,{...t,apiKey:c,signal:n});let u=null,d=!1;for await(const p of m)switch(p.type){case"start":u=p.partial,e.messages.push(u),d=!0,await o({type:"message_start",message:{...u}});break;case"text_start":case"text_delta":case"text_end":case"thinking_start":case"thinking_delta":case"thinking_end":case"toolcall_start":case"toolcall_delta":case"toolcall_end":u&&(u=p.partial,e.messages[e.messages.length-1]=u,await o({type:"message_update",assistantMessageEvent:p,message:{...u}}));break;case"done":case"error":{const y=await m.result();return d?e.messages[e.messages.length-1]=y:e.messages.push(y),d||await o({type:"message_start",message:{...y}}),await o({type:"message_end",message:y}),y}}const w=await m.result();return d?e.messages[e.messages.length-1]=w:(e.messages.push(w),await o({type:"message_start",message:{...w}})),await o({type:"message_end",message:w}),w}g(O,"streamAssistantResponse");async function B(e,t,n,o,s){const r=t.content.filter(l=>l.type==="toolCall"),a=r.some(l=>e.tools?.find(i=>i.name===l.name)?.executionMode==="sequential");return n.toolExecution==="sequential"||a?D(e,t,r,n,o,s):U(e,t,r,n,o,s)}g(B,"executeToolCalls");async function D(e,t,n,o,s,r){const a=[],l=[];for(const i of n){await r({type:"tool_execution_start",toolCallId:i.id,toolName:i.name,args:i.arguments});const c=await v(e,t,i,o,s);let m;if(c.kind==="immediate")m={toolCall:i,result:c.result,isError:c.isError};else{const d=await A(c,s,r);m=await S(e,t,c,d,o,s)}await E(m,r);const u=R(m);if(await P(u,r),a.push(m),l.push(u),s?.aborted)break}return{messages:l,terminate:x(a)}}g(D,"executeToolCallsSequential");async function U(e,t,n,o,s,r){const a=[];for(const c of n){await r({type:"tool_execution_start",toolCallId:c.id,toolName:c.name,args:c.arguments});const m=await v(e,t,c,o,s);if(m.kind==="immediate"){const u={toolCall:c,result:m.result,isError:m.isError};if(await E(u,r),a.push(u),s?.aborted)break;continue}if(a.push(async()=>{const u=await A(m,s,r),d=await S(e,t,m,u,o,s);return await E(d,r),d}),s?.aborted)break}const l=await Promise.all(a.map(c=>typeof c=="function"?c():Promise.resolve(c))),i=[];for(const c of l){const m=R(c);await P(m,r),i.push(m)}return{messages:i,terminate:x(l)}}g(U,"executeToolCallsParallel");function x(e){return e.length>0&&e.every(t=>t.result.terminate===!0)}g(x,"shouldTerminateToolBatch");function X(e,t){if(!e.prepareArguments)return t;const n=e.prepareArguments(t.arguments);return n===t.arguments?t:{...t,arguments:n}}g(X,"prepareToolCallArguments");async function v(e,t,n,o,s){const r=e.tools?.find(a=>a.name===n.name);if(!r)return{kind:"immediate",result:h(`Tool ${n.name} not found`),isError:!0};try{const a=X(r,n),l=I(r,a);if(o.beforeToolCall){const i=await o.beforeToolCall({assistantMessage:t,toolCall:n,args:l,context:e},s);if(s?.aborted)return{kind:"immediate",result:h("Operation aborted"),isError:!0};if(i?.block)return{kind:"immediate",result:h(i.reason||"Tool execution was blocked"),isError:!0}}return s?.aborted?{kind:"immediate",result:h("Operation aborted"),isError:!0}:{kind:"prepared",toolCall:n,tool:r,args:l}}catch(a){return{kind:"immediate",result:h(a instanceof Error?a.message:String(a)),isError:!0}}}g(v,"prepareToolCall");async function A(e,t,n){const o=[];try{const s=await e.tool.execute(e.toolCall.id,e.args,t,r=>{o.push(Promise.resolve(n({type:"tool_execution_update",toolCallId:e.toolCall.id,toolName:e.toolCall.name,args:e.toolCall.arguments,partialResult:r})))});return await Promise.all(o),{result:s,isError:!1}}catch(s){return await Promise.all(o),{result:h(s instanceof Error?s.message:String(s)),isError:!0}}}g(A,"executePreparedToolCall");async function S(e,t,n,o,s,r){let a=o.result,l=o.isError;if(s.afterToolCall)try{const i=await s.afterToolCall({assistantMessage:t,toolCall:n.toolCall,args:n.args,result:a,isError:l,context:e},r);i&&(a={content:i.content??a.content,details:i.details??a.details,terminate:i.terminate??a.terminate},l=i.isError??l)}catch(i){a=h(i instanceof Error?i.message:String(i)),l=!0}return{toolCall:n.toolCall,result:a,isError:l}}g(S,"finalizeExecutedToolCall");function h(e){return{content:[{type:"text",text:e}],details:{}}}g(h,"createErrorToolResult");async function E(e,t){await t({type:"tool_execution_end",toolCallId:e.toolCall.id,toolName:e.toolCall.name,result:e.result,isError:e.isError})}g(E,"emitToolExecutionEnd");function R(e){return{role:"toolResult",toolCallId:e.toolCall.id,toolName:e.toolCall.name,content:e.result.content,details:e.result.details,isError:e.isError,timestamp:Date.now()}}g(R,"createToolResultMessage");async function P(e,t){await t({type:"message_start",message:e}),await t({type:"message_end",message:e})}g(P,"emitToolResultMessage");export{z as agentLoop,G as agentLoopContinue,q as runAgentLoop,F as runAgentLoopContinue};

package/dist/agent.d.ts

@@ -0,0 +1,117 @@
+import { type ImageContent, type Message, type SimpleStreamOptions, type ThinkingBudgets, type Transport } from "@openadapter/koda-ai";
+import type { AfterToolCallContext, AfterToolCallResult, AgentEvent, AgentLoopTurnUpdate, AgentMessage, AgentState, BeforeToolCallContext, BeforeToolCallResult, QueueMode, StreamFn, ToolExecutionMode } from "./types.ts";
+export type { QueueMode } from "./types.ts";
+/** Options for constructing an {@link Agent}. */
+export interface AgentOptions {
+    initialState?: Partial<Omit<AgentState, "pendingToolCalls" | "isStreaming" | "streamingMessage" | "errorMessage">>;
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    streamFn?: StreamFn;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    onPayload?: SimpleStreamOptions["onPayload"];
+    onResponse?: SimpleStreamOptions["onResponse"];
+    beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+    prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
+    steeringMode?: QueueMode;
+    followUpMode?: QueueMode;
+    sessionId?: string;
+    thinkingBudgets?: ThinkingBudgets;
+    transport?: Transport;
+    maxRetryDelayMs?: number;
+    toolExecution?: ToolExecutionMode;
+}
+/**
+ * Stateful wrapper around the low-level agent loop.
+ *
+ * `Agent` owns the current transcript, emits lifecycle events, executes tools,
+ * and exposes queueing APIs for steering and follow-up messages.
+ */
+export declare class Agent {
+    private _state;
+    private readonly listeners;
+    private readonly steeringQueue;
+    private readonly followUpQueue;
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    streamFn: StreamFn;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    onPayload?: SimpleStreamOptions["onPayload"];
+    onResponse?: SimpleStreamOptions["onResponse"];
+    beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+    afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
+    prepareNextTurn?: (signal?: AbortSignal) => Promise<AgentLoopTurnUpdate | undefined> | AgentLoopTurnUpdate | undefined;
+    private activeRun?;
+    /** Session identifier forwarded to providers for cache-aware backends. */
+    sessionId?: string;
+    /** Optional per-level thinking token budgets forwarded to the stream function. */
+    thinkingBudgets?: ThinkingBudgets;
+    /** Preferred transport forwarded to the stream function. */
+    transport: Transport;
+    /** Optional cap for provider-requested retry delays. */
+    maxRetryDelayMs?: number;
+    /** Tool execution strategy for assistant messages that contain multiple tool calls. */
+    toolExecution: ToolExecutionMode;
+    constructor(options?: AgentOptions);
+    /**
+     * Subscribe to agent lifecycle events.
+     *
+     * Listener promises are awaited in subscription order and are included in
+     * the current run's settlement. Listeners also receive the active abort
+     * signal for the current run.
+     *
+     * `agent_end` is the final emitted event for a run, but the agent does not
+     * become idle until all awaited listeners for that event have settled.
+     */
+    subscribe(listener: (event: AgentEvent, signal: AbortSignal) => Promise<void> | void): () => void;
+    /**
+     * Current agent state.
+     *
+     * Assigning `state.tools` or `state.messages` copies the provided top-level array.
+     */
+    get state(): AgentState;
+    /** Controls how queued steering messages are drained. */
+    set steeringMode(mode: QueueMode);
+    get steeringMode(): QueueMode;
+    /** Controls how queued follow-up messages are drained. */
+    set followUpMode(mode: QueueMode);
+    get followUpMode(): QueueMode;
+    /** Queue a message to be injected after the current assistant turn finishes. */
+    steer(message: AgentMessage): void;
+    /** Queue a message to run only after the agent would otherwise stop. */
+    followUp(message: AgentMessage): void;
+    /** Remove all queued steering messages. */
+    clearSteeringQueue(): void;
+    /** Remove all queued follow-up messages. */
+    clearFollowUpQueue(): void;
+    /** Remove all queued steering and follow-up messages. */
+    clearAllQueues(): void;
+    /** Returns true when either queue still contains pending messages. */
+    hasQueuedMessages(): boolean;
+    /** Active abort signal for the current run, if any. */
+    get signal(): AbortSignal | undefined;
+    /** Abort the current run, if one is active. */
+    abort(): void;
+    /**
+     * Resolve when the current run and all awaited event listeners have finished.
+     *
+     * This resolves after `agent_end` listeners settle.
+     */
+    waitForIdle(): Promise<void>;
+    /** Clear transcript state, runtime state, and queued messages. */
+    reset(): void;
+    /** Start a new prompt from text, a single message, or a batch of messages. */
+    prompt(message: AgentMessage | AgentMessage[]): Promise<void>;
+    prompt(input: string, images?: ImageContent[]): Promise<void>;
+    /** Continue from the current transcript. The last message must be a user or tool-result message. */
+    continue(): Promise<void>;
+    private normalizePromptInput;
+    private runPromptMessages;
+    private runContinuation;
+    private createContextSnapshot;
+    private createLoopConfig;
+    private runWithLifecycle;
+    private handleRunFailure;
+    private finishRun;
+    private processEvents;
+}

package/dist/agent.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var n=(a,e)=>l(a,"name",{value:e,configurable:!0});import{streamSimple as u}from"@openadapter/koda-ai";import{runAgentLoop as h,runAgentLoopContinue as g}from"./agent-loop.js";function c(a){return a.filter(e=>e.role==="user"||e.role==="assistant"||e.role==="toolResult")}n(c,"defaultConvertToLlm");const m={input:0,output:0,cacheRead:0,cacheWrite:0,totalTokens:0,cost:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0}},d={id:"unknown",name:"unknown",api:"unknown",provider:"unknown",baseUrl:"",reasoning:!1,input:[],cost:{input:0,output:0,cacheRead:0,cacheWrite:0},contextWindow:0,maxTokens:0};function p(a){let e=a?.tools?.slice()??[],t=a?.messages?.slice()??[];return{systemPrompt:a?.systemPrompt??"",model:a?.model??d,thinkingLevel:a?.thinkingLevel??"off",get tools(){return e},set tools(s){e=s.slice()},get messages(){return t},set messages(s){t=s.slice()},isStreaming:!1,streamingMessage:void 0,pendingToolCalls:new Set,errorMessage:void 0}}n(p,"createMutableAgentState");class o{static{n(this,"PendingMessageQueue")}messages=[];mode;constructor(e){this.mode=e}enqueue(e){this.messages.push(e)}hasItems(){return this.messages.length>0}drain(){if(this.mode==="all"){const t=this.messages.slice();return this.messages=[],t}const e=this.messages[0];return e?(this.messages=this.messages.slice(1),[e]):[]}clear(){this.messages=[]}}class _{static{n(this,"Agent")}_state;listeners=new Set;steeringQueue;followUpQueue;convertToLlm;transformContext;streamFn;getApiKey;onPayload;onResponse;beforeToolCall;afterToolCall;prepareNextTurn;activeRun;sessionId;thinkingBudgets;transport;maxRetryDelayMs;toolExecution;constructor(e={}){this._state=p(e.initialState),this.convertToLlm=e.convertToLlm??c,this.transformContext=e.transformContext,this.streamFn=e.streamFn??u,this.getApiKey=e.getApiKey,this.onPayload=e.onPayload,this.onResponse=e.onResponse,this.beforeToolCall=e.beforeToolCall,this.afterToolCall=e.afterToolCall,this.prepareNextTurn=e.prepareNextTurn,this.steeringQueue=new o(e.steeringMode??"one-at-a-time"),this.followUpQueue=new o(e.followUpMode??"one-at-a-time"),this.sessionId=e.sessionId,this.thinkingBudgets=e.thinkingBudgets,this.transport=e.transport??"auto",this.maxRetryDelayMs=e.maxRetryDelayMs,this.toolExecution=e.toolExecution??"parallel"}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}get state(){return this._state}set steeringMode(e){this.steeringQueue.mode=e}get steeringMode(){return this.steeringQueue.mode}set followUpMode(e){this.followUpQueue.mode=e}get followUpMode(){return this.followUpQueue.mode}steer(e){this.steeringQueue.enqueue(e)}followUp(e){this.followUpQueue.enqueue(e)}clearSteeringQueue(){this.steeringQueue.clear()}clearFollowUpQueue(){this.followUpQueue.clear()}clearAllQueues(){this.clearSteeringQueue(),this.clearFollowUpQueue()}hasQueuedMessages(){return this.steeringQueue.hasItems()||this.followUpQueue.hasItems()}get signal(){return this.activeRun?.abortController.signal}abort(){this.activeRun?.abortController.abort()}waitForIdle(){return this.activeRun?.promise??Promise.resolve()}reset(){this._state.messages=[],this._state.isStreaming=!1,this._state.streamingMessage=void 0,this._state.pendingToolCalls=new Set,this._state.errorMessage=void 0,this.clearFollowUpQueue(),this.clearSteeringQueue()}async prompt(e,t){if(this.activeRun)throw new Error("Agent is already processing a prompt. Use steer() or followUp() to queue messages, or wait for completion.");const s=this.normalizePromptInput(e,t);await this.runPromptMessages(s)}async continue(){if(this.activeRun)throw new Error("Agent is already processing. Wait for completion before continuing.");const e=this._state.messages[this._state.messages.length-1];if(!e)throw new Error("No messages to continue from");if(e.role==="assistant"){const t=this.steeringQueue.drain();if(t.length>0){await this.runPromptMessages(t,{skipInitialSteeringPoll:!0});return}const s=this.followUpQueue.drain();if(s.length>0){await this.runPromptMessages(s);return}throw new Error("Cannot continue from message role: assistant")}await this.runContinuation()}normalizePromptInput(e,t){if(Array.isArray(e))return e;if(typeof e!="string")return[e];const s=[{type:"text",text:e}];return t&&t.length>0&&s.push(...t),[{role:"user",content:s,timestamp:Date.now()}]}async runPromptMessages(e,t={}){await this.runWithLifecycle(async s=>{await h(e,this.createContextSnapshot(),this.createLoopConfig(t),r=>this.processEvents(r),s,this.streamFn)})}async runContinuation(){await this.runWithLifecycle(async e=>{await g(this.createContextSnapshot(),this.createLoopConfig(),t=>this.processEvents(t),e,this.streamFn)})}createContextSnapshot(){return{systemPrompt:this._state.systemPrompt,messages:this._state.messages.slice(),tools:this._state.tools.slice()}}createLoopConfig(e={}){let t=e.skipInitialSteeringPoll===!0;return{model:this._state.model,reasoning:this._state.thinkingLevel==="off"?void 0:this._state.thinkingLevel,sessionId:this.sessionId,onPayload:this.onPayload,onResponse:this.onResponse,transport:this.transport,thinkingBudgets:this.thinkingBudgets,maxRetryDelayMs:this.maxRetryDelayMs,toolExecution:this.toolExecution,beforeToolCall:this.beforeToolCall,afterToolCall:this.afterToolCall,prepareNextTurn:this.prepareNextTurn?async()=>await this.prepareNextTurn?.(this.signal):void 0,convertToLlm:this.convertToLlm,transformContext:this.transformContext,getApiKey:this.getApiKey,getSteeringMessages:n(async()=>t?(t=!1,[]):this.steeringQueue.drain(),"getSteeringMessages"),getFollowUpMessages:n(async()=>this.followUpQueue.drain(),"getFollowUpMessages")}}async runWithLifecycle(e){if(this.activeRun)throw new Error("Agent is already processing.");const t=new AbortController;let s=n(()=>{},"resolvePromise");const r=new Promise(i=>{s=i});this.activeRun={promise:r,resolve:s,abortController:t},this._state.isStreaming=!0,this._state.streamingMessage=void 0,this._state.errorMessage=void 0;try{await e(t.signal)}catch(i){await this.handleRunFailure(i,t.signal.aborted)}finally{this.finishRun()}}async handleRunFailure(e,t){const s={role:"assistant",content:[{type:"text",text:""}],api:this._state.model.api,provider:this._state.model.provider,model:this._state.model.id,usage:m,stopReason:t?"aborted":"error",errorMessage:e instanceof Error?e.message:String(e),timestamp:Date.now()};await this.processEvents({type:"message_start",message:s}),await this.processEvents({type:"message_end",message:s}),await this.processEvents({type:"turn_end",message:s,toolResults:[]}),await this.processEvents({type:"agent_end",messages:[s]})}finishRun(){this._state.isStreaming=!1,this._state.streamingMessage=void 0,this._state.pendingToolCalls=new Set,this.activeRun?.resolve(),this.activeRun=void 0}async processEvents(e){switch(e.type){case"message_start":this._state.streamingMessage=e.message;break;case"message_update":this._state.streamingMessage=e.message;break;case"message_end":this._state.streamingMessage=void 0,this._state.messages.push(e.message);break;case"tool_execution_start":{const s=new Set(this._state.pendingToolCalls);s.add(e.toolCallId),this._state.pendingToolCalls=s;break}case"tool_execution_end":{const s=new Set(this._state.pendingToolCalls);s.delete(e.toolCallId),this._state.pendingToolCalls=s;break}case"turn_end":e.message.role==="assistant"&&e.message.errorMessage&&(this._state.errorMessage=e.message.errorMessage);break;case"agent_end":this._state.streamingMessage=void 0;break}const t=this.activeRun?.abortController.signal;if(!t)throw new Error("Agent listener invoked outside active run");for(const s of this.listeners)await s(e,t)}}export{_ as Agent};