@arki-moe/agent-ts 3.0.0 → 5.0.0

package/README.md

@@ -13,7 +13,8 @@ const getTimeTool: Tool = {
   name: "get_time",
   description: "Get the current time in ISO format",
   parameters: { type: "object", properties: {} },
-  execute: () => new Date().toISOString(),
+  data: { category: "time" },
+  execute: (_args, _agent) => new Date().toISOString(),
 };
 
 const agent = new Agent("openai", {
@@ -23,11 +24,12 @@ const agent = new Agent("openai", {
   onStream: (textDelta) => {
     process.stdout.write(textDelta);
   },
-  onToolCall: (message, args) => {
+  onToolCall: (message, args, agent) => {
     console.log("tool call:", message);
     console.log("tool args:", args);
+    console.log("agent context length:", agent.context.length);
   },
-  onToolResult: (msg) => console.log("tool result:", msg),
+  onToolResult: (msg, agent) => console.log("tool result:", msg, agent.context.length),
 });
 agent.registerTool(getTimeTool);
 
@@ -53,7 +55,7 @@ When `apiKey` is not provided in config, adapters read from the corresponding en
 - `Agent(adapterName, config)` - Create Agent
 - `agent.context` - Public property, complete conversation history
 - `agent.registerTool(tool)` - Register tool
-- `agent.run(message, options?)` - Execute tool chain automatically, returns all new `Message[]`
+- `agent.run(message)` - Execute tool chain automatically, returns all new `Message[]`
 
 ### Config
 
@@ -64,13 +66,15 @@ When `apiKey` is not provided in config, adapters read from the corresponding en
 | `system` | `string` | Optional system prompt |
 | `endCondition` | `(context, last) => boolean` | Stop condition for `run`. Defaults to `last.role === Role.Ai` |
 | `onStream` | `(textDelta: string) => void \| Promise<void>` | Stream hook for AI text only. When provided, adapters use SSE streaming and still return the final `Message[]`. |
-| `onToolCall` | `(message, args) => boolean \| void \| Promise<boolean \| void>` | Called before each tool execution; return `false` to skip tool execution and `onToolResult` |
-| `onToolResult` | `(message) => void \| Promise<void>` | Called after each tool execution (`message.role === Role.ToolResult`) |
+| `onToolCall` | `(message, args, agent) => boolean \| void \| Promise<boolean \| void>` | Called before each tool execution; return `false` to skip tool execution and `onToolResult` |
+| `onToolResult` | `(message, agent) => void \| Promise<void>` | Called after each tool execution (`message.role === Role.ToolResult`) |
 
-`agent.run` always appends new messages to `agent.context`. Set `options.once = true` to avoid persisting the user message (useful for one-shot hints). Multiple tool calls in a single model response are executed in parallel.
+`agent.run` always appends new messages to `agent.context`. Multiple tool calls in a single model response are executed in parallel.
 
 `onToolCall` receives parsed JSON args and can mutate them before execution. Returning `false` skips the tool call and does not emit a `ToolResult` message.
 
+`tool.data` is a local JSON metadata bag for your own use and is not sent to adapters.
+
 ## Scripts
 
 | Command | Description |

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import type { AgentConfig, Context, Message, RunOptions, Tool } from "./types";
+import type { AgentConfig, AgentLike, Context, Message, Tool } from "./types";
 export { openaiAdapter } from "./adapter/openai";
 export { openrouterAdapter } from "./adapter/openrouter";
-export type { Adapter, AgentConfig, Context, Message, RunOptions, Tool } from "./types";
+export type { Adapter, AgentConfig, AgentLike, Context, Message, Tool } from "./types";
 export { Role } from "./types";
-export declare class Agent {
+export declare class Agent implements AgentLike {
     context: Context;
     private adapter;
     private adapterName;
@@ -14,5 +14,5 @@ export declare class Agent {
     private onToolResult?;
     constructor(adapterName: string, config: AgentConfig);
     registerTool(tool: Tool): void;
-    run(message: string, options?: RunOptions): Promise<Message[]>;
+    run(message: string): Promise<Message[]>;
 }

package/dist/index.js

@@ -28,8 +28,7 @@ class Agent {
     registerTool(tool) {
         this.tools.push(tool);
     }
-    async run(message, options = {}) {
-        const once = options.once ?? false;
+    async run(message) {
         const all = [];
         const sessionContext = [...this.context];
         const persistToContext = (msgs) => {
@@ -40,8 +39,7 @@ class Agent {
         };
         const userMessage = { role: types_1.Role.User, content: message };
         pushToSession([userMessage]);
-        if (!once)
-            persistToContext([userMessage]);
+        persistToContext([userMessage]);
         const runAdapter = async () => {
             const msgs = await this.adapter(this.config, sessionContext, this.tools);
             pushToSession(msgs);
@@ -73,18 +71,18 @@ class Agent {
                         isError: true,
                     };
                     if (this.onToolResult)
-                        await Promise.resolve(this.onToolResult(result));
+                        await Promise.resolve(this.onToolResult(result, this));
                     return result;
                 }
                 if (this.onToolCall) {
-                    const shouldRun = await Promise.resolve(this.onToolCall(m, args));
+                    const shouldRun = await Promise.resolve(this.onToolCall(m, args, this));
                     if (shouldRun === false)
                         return null;
                 }
                 let content;
                 let isError = false;
                 try {
-                    const out = await Promise.resolve(tool.execute(args));
+                    const out = await Promise.resolve(tool.execute(args, this));
                     content = typeof out === "string" ? out : JSON.stringify(out);
                 }
                 catch (err) {
@@ -93,7 +91,7 @@ class Agent {
                 }
                 const result = { role: types_1.Role.ToolResult, callId: m.callId, content, isError };
                 if (this.onToolResult)
-                    await Promise.resolve(this.onToolResult(result));
+                    await Promise.resolve(this.onToolResult(result, this));
                 return result;
             }));
             const filteredResults = results.filter((result) => result !== null);

package/dist/types.d.ts

@@ -26,24 +26,27 @@ export type Message = {
     isError?: boolean;
 };
 export type Context = Message[];
+export interface AgentLike {
+    context: Context;
+    registerTool: (tool: Tool) => void;
+    run: (message: string) => Promise<Message[]>;
+}
 export type Tool = {
     name: string;
     description: string;
     parameters: unknown;
-    execute: (args: unknown) => Promise<unknown> | unknown;
+    data?: Record<string, unknown>;
+    execute: (args: unknown, agent: AgentLike) => Promise<unknown> | unknown;
 };
 export type AgentConfig = {
     endCondition?: (context: Message[], last: Message) => boolean;
     onStream?: (textDelta: string) => void | Promise<void>;
     onToolCall?: (message: Extract<Message, {
         role: Role.ToolCall;
-    }>, args: unknown) => boolean | void | Promise<boolean | void>;
+    }>, args: unknown, agent: AgentLike) => boolean | void | Promise<boolean | void>;
     onToolResult?: (message: Extract<Message, {
         role: Role.ToolResult;
-    }>) => void | Promise<void>;
+    }>, agent: AgentLike) => void | Promise<void>;
     [key: string]: unknown;
 };
-export type RunOptions = {
-    once?: boolean;
-};
 export type Adapter = (config: Record<string, unknown>, context: Message[], tools: Tool[]) => Promise<Message[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki-moe/agent-ts",
-  "version": "3.0.0",
+  "version": "5.0.0",
   "description": "Minimal Agent library, zero dependencies",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",