@arki-moe/agent-ts 5.2.0 → 5.4.0

package/README.md

@@ -33,9 +33,14 @@ const agent = new Agent("openai", {
 });
 agent.registerTool(getTimeTool);
 
-// run: Executes tool chain automatically, returns new messages, context is maintained automatically
-const msgs = await agent.run("What time is it?");
-console.log(msgs);
+// run: Executes tool chain automatically, returns new messages and usage, context is maintained automatically
+const result = await agent.run("What time is it?");
+console.log(result.messages);
+console.log(result.usage, result.usageSum);
+
+// run also accepts multiple user messages or Message objects
+await agent.run(["Hello", "What's next?"]);
+await agent.run({ role: Role.System, content: "You are brief." });
 
 // context is a public property that can be read directly
 console.log(agent.context);
@@ -56,7 +61,8 @@ 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)` - Execute tool chain automatically, returns all new `Message[]`
+- `agent.run(message)` - Execute tool chain automatically, returns `{ messages, usage, usageSum }`
+  - `message` can be `string | string[] | Message | Message[]`
 
 ### Config
 

package/dist/adapter/openai.d.ts

@@ -1,2 +1,2 @@
-import { type Message, type Tool } from "../types";
-export declare function openaiAdapter(config: Record<string, unknown>, context: Message[], tools: Tool[]): Promise<Message[]>;
+import { type AdapterResult, type Message, type Tool } from "../types";
+export declare function openaiAdapter(config: Record<string, unknown>, context: Message[], tools: Tool[]): Promise<AdapterResult>;

package/dist/adapter/openai.js

@@ -27,6 +27,18 @@ function toOpenAIMessages(context) {
         return out;
     }, []);
 }
+function toUsage(usage) {
+    if (!usage)
+        return undefined;
+    const promptTokens = usage.prompt_tokens;
+    const completionTokens = usage.completion_tokens;
+    const totalTokens = usage.total_tokens;
+    if (typeof promptTokens !== "number"
+        || typeof completionTokens !== "number"
+        || typeof totalTokens !== "number")
+        return undefined;
+    return { promptTokens, completionTokens, totalTokens };
+}
 async function openaiAdapter(config, context, tools) {
     const baseUrl = config.baseUrl ?? "https://api.openai.com";
     const apiKey = config.apiKey || process.env.OPENAI_API_KEY || "";
@@ -47,9 +59,10 @@ async function openaiAdapter(config, context, tools) {
         tools: tools.length ? tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters ?? {} } })) : undefined,
         tool_choice: tools.length ? (toolChoice ?? "auto") : undefined,
         stream: onStream ? true : undefined,
+        stream_options: onStream ? { include_usage: true } : undefined,
     };
     if (await check())
-        return [];
+        return { messages: [] };
     const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/chat/completions`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
@@ -71,6 +84,7 @@ async function openaiAdapter(config, context, tools) {
     }
     if (onStream) {
         let content = "";
+        let usage;
         const toolCalls = new Map();
         const upsertToolCall = (tc) => {
             const index = typeof tc?.index === "number" ? tc.index : toolCalls.size;
@@ -99,6 +113,11 @@ async function openaiAdapter(config, context, tools) {
             catch {
                 throw new Error(`OpenAI API returned invalid JSON: ${dataLine.slice(0, 200)}`);
             }
+            if (parsed?.usage) {
+                const nextUsage = toUsage(parsed.usage);
+                if (nextUsage)
+                    usage = nextUsage;
+            }
             const delta = parsed?.choices?.[0]?.delta;
             if (!delta)
                 return;
@@ -114,22 +133,25 @@ async function openaiAdapter(config, context, tools) {
             await check();
         }, check);
         if (toolCalls.size > 0) {
-            return [...toolCalls.entries()]
-                .sort((a, b) => a[0] - b[0])
-                .map(([index, tc]) => {
-                if (!tc.name)
-                    throw new Error(`OpenAI streaming tool call missing function name at index ${index}`);
-                return {
-                    role: types_1.Role.ToolCall,
-                    toolName: tc.name,
-                    callId: tc.id ?? `call_${index}`,
-                    argsText: tc.args.length ? tc.args : "{}",
-                };
-            });
+            return {
+                messages: [...toolCalls.entries()]
+                    .sort((a, b) => a[0] - b[0])
+                    .map(([index, tc]) => {
+                    if (!tc.name)
+                        throw new Error(`OpenAI streaming tool call missing function name at index ${index}`);
+                    return {
+                        role: types_1.Role.ToolCall,
+                        toolName: tc.name,
+                        callId: tc.id ?? `call_${index}`,
+                        argsText: tc.args.length ? tc.args : "{}",
+                    };
+                }),
+                usage,
+            };
         }
         if (!content)
-            return [];
-        return [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }];
+            return { messages: [], usage };
+        return { messages: [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }], usage };
     }
     const text = await res.text();
     let data;
@@ -141,16 +163,20 @@ async function openaiAdapter(config, context, tools) {
     }
     if (data.error)
         throw new Error(`OpenAI API error: ${data.error.message}`);
+    const usage = toUsage(data.usage);
     const msg = data.choices?.[0]?.message;
     if (!msg)
         throw new Error("OpenAI API returned empty response");
     if (msg.tool_calls?.length) {
-        return msg.tool_calls.map((tc) => ({
-            role: types_1.Role.ToolCall,
-            toolName: tc.function.name,
-            callId: tc.id,
-            argsText: tc.function.arguments ?? "{}",
-        }));
+        return {
+            messages: msg.tool_calls.map((tc) => ({
+                role: types_1.Role.ToolCall,
+                toolName: tc.function.name,
+                callId: tc.id,
+                argsText: tc.function.arguments ?? "{}",
+            })),
+            usage,
+        };
     }
-    return [{ role: types_1.Role.Ai, content: msg.content ?? "" }];
+    return { messages: [{ role: types_1.Role.Ai, content: msg.content ?? "" }], usage };
 }

package/dist/adapter/openrouter.d.ts

@@ -1,2 +1,2 @@
-import { type Message, type Tool } from "../types";
-export declare function openrouterAdapter(config: Record<string, unknown>, context: Message[], tools: Tool[]): Promise<Message[]>;
+import { type AdapterResult, type Message, type Tool } from "../types";
+export declare function openrouterAdapter(config: Record<string, unknown>, context: Message[], tools: Tool[]): Promise<AdapterResult>;

package/dist/adapter/openrouter.js

@@ -27,6 +27,18 @@ function toOpenRouterMessages(context) {
         return out;
     }, []);
 }
+function toUsage(usage) {
+    if (!usage)
+        return undefined;
+    const promptTokens = usage.prompt_tokens;
+    const completionTokens = usage.completion_tokens;
+    const totalTokens = usage.total_tokens;
+    if (typeof promptTokens !== "number"
+        || typeof completionTokens !== "number"
+        || typeof totalTokens !== "number")
+        return undefined;
+    return { promptTokens, completionTokens, totalTokens };
+}
 async function openrouterAdapter(config, context, tools) {
     const baseUrl = config.baseUrl ?? "https://openrouter.ai/api/v1";
     const apiKey = config.apiKey || process.env.OPENROUTER_API_KEY || "";
@@ -49,6 +61,7 @@ async function openrouterAdapter(config, context, tools) {
         tools: tools.length ? tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters ?? {} } })) : undefined,
         tool_choice: tools.length ? (toolChoice ?? "auto") : undefined,
         stream: onStream ? true : undefined,
+        stream_options: onStream ? { include_usage: true } : undefined,
     };
     const headers = {
         "Content-Type": "application/json",
@@ -59,7 +72,7 @@ async function openrouterAdapter(config, context, tools) {
     if (title)
         headers["X-Title"] = title;
     if (await check())
-        return [];
+        return { messages: [] };
     const res = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
         method: "POST",
         headers,
@@ -81,6 +94,7 @@ async function openrouterAdapter(config, context, tools) {
     }
     if (onStream) {
         let content = "";
+        let usage;
         const toolCalls = new Map();
         const upsertToolCall = (tc) => {
             const index = typeof tc?.index === "number" ? tc.index : toolCalls.size;
@@ -109,6 +123,11 @@ async function openrouterAdapter(config, context, tools) {
             catch {
                 throw new Error(`OpenRouter API returned invalid JSON: ${dataLine.slice(0, 200)}`);
             }
+            if (parsed?.usage) {
+                const nextUsage = toUsage(parsed.usage);
+                if (nextUsage)
+                    usage = nextUsage;
+            }
             const delta = parsed?.choices?.[0]?.delta;
             if (!delta)
                 return;
@@ -124,22 +143,25 @@ async function openrouterAdapter(config, context, tools) {
             await check();
         }, check);
         if (toolCalls.size > 0) {
-            return [...toolCalls.entries()]
-                .sort((a, b) => a[0] - b[0])
-                .map(([index, tc]) => {
-                if (!tc.name)
-                    throw new Error(`OpenRouter streaming tool call missing function name at index ${index}`);
-                return {
-                    role: types_1.Role.ToolCall,
-                    toolName: tc.name,
-                    callId: tc.id ?? `call_${index}`,
-                    argsText: tc.args.length ? tc.args : "{}",
-                };
-            });
+            return {
+                messages: [...toolCalls.entries()]
+                    .sort((a, b) => a[0] - b[0])
+                    .map(([index, tc]) => {
+                    if (!tc.name)
+                        throw new Error(`OpenRouter streaming tool call missing function name at index ${index}`);
+                    return {
+                        role: types_1.Role.ToolCall,
+                        toolName: tc.name,
+                        callId: tc.id ?? `call_${index}`,
+                        argsText: tc.args.length ? tc.args : "{}",
+                    };
+                }),
+                usage,
+            };
         }
         if (!content)
-            return [];
-        return [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }];
+            return { messages: [], usage };
+        return { messages: [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }], usage };
     }
     const text = await res.text();
     let data;
@@ -151,16 +173,20 @@ async function openrouterAdapter(config, context, tools) {
     }
     if (data.error)
         throw new Error(`OpenRouter API error: ${data.error.message}`);
+    const usage = toUsage(data.usage);
     const msg = data.choices?.[0]?.message;
     if (!msg)
         throw new Error("OpenRouter API returned empty response");
     if (msg.tool_calls?.length) {
-        return msg.tool_calls.map((tc) => ({
-            role: types_1.Role.ToolCall,
-            toolName: tc.function.name,
-            callId: tc.id,
-            argsText: tc.function.arguments ?? "{}",
-        }));
+        return {
+            messages: msg.tool_calls.map((tc) => ({
+                role: types_1.Role.ToolCall,
+                toolName: tc.function.name,
+                callId: tc.id,
+                argsText: tc.function.arguments ?? "{}",
+            })),
+            usage,
+        };
     }
-    return [{ role: types_1.Role.Ai, content: msg.content ?? "" }];
+    return { messages: [{ role: types_1.Role.Ai, content: msg.content ?? "" }], usage };
 }

package/dist/adapter/selfhost_chat_completions.d.ts

@@ -1,2 +1,2 @@
-import { type Message, type Tool } from "../types";
-export declare function selfhostChatCompletionsAdapter(config: Record<string, unknown>, context: Message[], tools: Tool[]): Promise<Message[]>;
+import { type AdapterResult, type Message, type Tool } from "../types";
+export declare function selfhostChatCompletionsAdapter(config: Record<string, unknown>, context: Message[], tools: Tool[]): Promise<AdapterResult>;

package/dist/adapter/selfhost_chat_completions.js

@@ -27,6 +27,18 @@ function toOpenAIMessages(context) {
         return out;
     }, []);
 }
+function toUsage(usage) {
+    if (!usage)
+        return undefined;
+    const promptTokens = usage.prompt_tokens;
+    const completionTokens = usage.completion_tokens;
+    const totalTokens = usage.total_tokens;
+    if (typeof promptTokens !== "number"
+        || typeof completionTokens !== "number"
+        || typeof totalTokens !== "number")
+        return undefined;
+    return { promptTokens, completionTokens, totalTokens };
+}
 async function selfhostChatCompletionsAdapter(config, context, tools) {
     const baseUrl = config.baseUrl ?? "http://localhost:1234";
     const apiKey = config.apiKey || process.env.SELFHOST_API_KEY || "";
@@ -47,9 +59,10 @@ async function selfhostChatCompletionsAdapter(config, context, tools) {
         tools: tools.length ? tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters ?? {} } })) : undefined,
         tool_choice: tools.length ? (toolChoice ?? "auto") : undefined,
         stream: onStream ? true : undefined,
+        stream_options: onStream ? { include_usage: true } : undefined,
     };
     if (await check())
-        return [];
+        return { messages: [] };
     const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/chat/completions`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
@@ -71,6 +84,7 @@ async function selfhostChatCompletionsAdapter(config, context, tools) {
     }
     if (onStream) {
         let content = "";
+        let usage;
         const toolCalls = new Map();
         const upsertToolCall = (tc) => {
             const index = typeof tc?.index === "number" ? tc.index : toolCalls.size;
@@ -99,6 +113,11 @@ async function selfhostChatCompletionsAdapter(config, context, tools) {
             catch {
                 throw new Error(`Self-host chat completions API returned invalid JSON: ${dataLine.slice(0, 200)}`);
             }
+            if (parsed?.usage) {
+                const nextUsage = toUsage(parsed.usage);
+                if (nextUsage)
+                    usage = nextUsage;
+            }
             const delta = parsed?.choices?.[0]?.delta;
             if (!delta)
                 return;
@@ -114,22 +133,25 @@ async function selfhostChatCompletionsAdapter(config, context, tools) {
             await check();
         }, check);
         if (toolCalls.size > 0) {
-            return [...toolCalls.entries()]
-                .sort((a, b) => a[0] - b[0])
-                .map(([index, tc]) => {
-                if (!tc.name)
-                    throw new Error(`Self-host streaming tool call missing function name at index ${index}`);
-                return {
-                    role: types_1.Role.ToolCall,
-                    toolName: tc.name,
-                    callId: tc.id ?? `call_${index}`,
-                    argsText: tc.args.length ? tc.args : "{}",
-                };
-            });
+            return {
+                messages: [...toolCalls.entries()]
+                    .sort((a, b) => a[0] - b[0])
+                    .map(([index, tc]) => {
+                    if (!tc.name)
+                        throw new Error(`Self-host streaming tool call missing function name at index ${index}`);
+                    return {
+                        role: types_1.Role.ToolCall,
+                        toolName: tc.name,
+                        callId: tc.id ?? `call_${index}`,
+                        argsText: tc.args.length ? tc.args : "{}",
+                    };
+                }),
+                usage,
+            };
         }
         if (!content)
-            return [];
-        return [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }];
+            return { messages: [], usage };
+        return { messages: [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }], usage };
     }
     const text = await res.text();
     let data;
@@ -141,16 +163,20 @@ async function selfhostChatCompletionsAdapter(config, context, tools) {
     }
     if (data.error)
         throw new Error(`Self-host chat completions API error: ${data.error.message}`);
+    const usage = toUsage(data.usage);
     const msg = data.choices?.[0]?.message;
     if (!msg)
         throw new Error("Self-host chat completions API returned empty response");
     if (msg.tool_calls?.length) {
-        return msg.tool_calls.map((tc) => ({
-            role: types_1.Role.ToolCall,
-            toolName: tc.function.name,
-            callId: tc.id,
-            argsText: tc.function.arguments ?? "{}",
-        }));
+        return {
+            messages: msg.tool_calls.map((tc) => ({
+                role: types_1.Role.ToolCall,
+                toolName: tc.function.name,
+                callId: tc.id,
+                argsText: tc.function.arguments ?? "{}",
+            })),
+            usage,
+        };
     }
-    return [{ role: types_1.Role.Ai, content: msg.content ?? "" }];
+    return { messages: [{ role: types_1.Role.Ai, content: msg.content ?? "" }], usage };
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import type { AgentConfig, AgentLike, Context, Message, Tool } from "./types";
+import type { AgentConfig, AgentLike, Context, Message, RunInput, Tool, Usage } from "./types";
 export { openaiAdapter } from "./adapter/openai";
 export { openrouterAdapter } from "./adapter/openrouter";
 export { selfhostChatCompletionsAdapter } from "./adapter/selfhost_chat_completions";
-export type { Adapter, AgentConfig, AgentLike, Context, Message, Tool } from "./types";
+export type { Adapter, AgentConfig, AgentLike, Context, Message, RunInput, Tool, Usage, AdapterResult } from "./types";
 export { Role } from "./types";
 export declare class Agent implements AgentLike {
     context: Context;
@@ -15,5 +15,29 @@ export declare class Agent implements AgentLike {
     private onToolResult?;
     constructor(adapterName: string, config: AgentConfig);
     registerTool(tool: Tool): void;
-    run(message: string): Promise<Message[]>;
+    run(message: RunInput): Promise<{
+        messages: Message[];
+        usage?: Usage;
+        usageSum?: Usage;
+    }>;
+    run(message: string): Promise<{
+        messages: Message[];
+        usage?: Usage;
+        usageSum?: Usage;
+    }>;
+    run(message: string[]): Promise<{
+        messages: Message[];
+        usage?: Usage;
+        usageSum?: Usage;
+    }>;
+    run(message: Message): Promise<{
+        messages: Message[];
+        usage?: Usage;
+        usageSum?: Usage;
+    }>;
+    run(message: Message[]): Promise<{
+        messages: Message[];
+        usage?: Usage;
+        usageSum?: Usage;
+    }>;
 }

package/dist/index.js

@@ -19,6 +19,19 @@ const adapters = {
     openrouter: openrouter_1.openrouterAdapter,
     selfhost_chat_completions: selfhost_chat_completions_1.selfhostChatCompletionsAdapter,
 };
+const normalizeRunInput = (input) => {
+    if (typeof input === "string")
+        return [{ role: types_1.Role.User, content: input }];
+    if (Array.isArray(input)) {
+        if (input.length === 0)
+            return [];
+        if (typeof input[0] === "string") {
+            return input.map((content) => ({ role: types_1.Role.User, content }));
+        }
+        return input;
+    }
+    return [input];
+};
 class Agent {
     constructor(adapterName, config) {
         this.context = [];
@@ -35,9 +48,11 @@ class Agent {
     }
     async run(message) {
         const all = [];
+        let usage;
+        let usageSum;
         const { check } = (0, abort_1.createAbortChecker)(this.config.isAbort);
         if (await check())
-            return all;
+            return { messages: [] };
         const sessionContext = [...this.context];
         const persistToContext = (msgs) => {
             this.context.push(...msgs);
@@ -45,13 +60,31 @@ class Agent {
         const pushToSession = (msgs) => {
             sessionContext.push(...msgs);
         };
-        const userMessage = { role: types_1.Role.User, content: message };
-        pushToSession([userMessage]);
-        persistToContext([userMessage]);
+        const inputMessages = normalizeRunInput(message);
+        if (inputMessages.length === 0)
+            return { messages: [] };
+        pushToSession(inputMessages);
+        persistToContext(inputMessages);
+        const addUsage = (next) => {
+            if (!next)
+                return;
+            usage = next;
+            if (!usageSum) {
+                usageSum = { ...next };
+                return;
+            }
+            usageSum = {
+                promptTokens: usageSum.promptTokens + next.promptTokens,
+                completionTokens: usageSum.completionTokens + next.completionTokens,
+                totalTokens: usageSum.totalTokens + next.totalTokens,
+            };
+        };
         const runAdapter = async () => {
             if (await check())
                 return [];
-            const msgs = await this.adapter(this.config, sessionContext, this.tools);
+            const result = await this.adapter(this.config, sessionContext, this.tools);
+            addUsage(result.usage);
+            const msgs = result.messages;
             pushToSession(msgs);
             persistToContext(msgs);
             all.push(...msgs);
@@ -59,16 +92,16 @@ class Agent {
         };
         let msgs = await runAdapter();
         if (await check())
-            return all;
+            return { messages: all, usage, usageSum };
         for (;;) {
             if (await check())
-                return all;
+                return { messages: all, usage, usageSum };
             const last = msgs[msgs.length - 1];
             if (this.endCondition(sessionContext, last))
-                return all;
+                return { messages: all, usage, usageSum };
             const toolCalls = msgs.filter((m) => m.role === types_1.Role.ToolCall);
             if (toolCalls.length === 0)
-                return all;
+                return { messages: all, usage, usageSum };
             const results = await Promise.all(toolCalls.map(async (m) => {
                 if (await check())
                     return null;

package/dist/types.d.ts

@@ -27,10 +27,20 @@ export type Message = {
     isError?: boolean;
 };
 export type Context = Message[];
+export type RunInput = string | string[] | Message | Message[];
+export type Usage = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
 export interface AgentLike {
     context: Context;
     registerTool: (tool: Tool) => void;
-    run: (message: string) => Promise<Message[]>;
+    run: (message: RunInput) => Promise<{
+        messages: Message[];
+        usage?: Usage;
+        usageSum?: Usage;
+    }>;
 }
 export type Tool = {
     name: string;
@@ -52,4 +62,8 @@ export type AgentConfig = {
     }>, agent: AgentLike) => void | Promise<void>;
     [key: string]: unknown;
 };
-export type Adapter = (config: Record<string, unknown>, context: Message[], tools: Tool[]) => Promise<Message[]>;
+export type AdapterResult = {
+    messages: Message[];
+    usage?: Usage;
+};
+export type Adapter = (config: Record<string, unknown>, context: Message[], tools: Tool[]) => Promise<AdapterResult>;

package/package.json

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