@arki-moe/agent-ts 4.0.0 → 5.1.0

package/README.md

@@ -13,6 +13,7 @@ const getTimeTool: Tool = {
   name: "get_time",
   description: "Get the current time in ISO format",
   parameters: { type: "object", properties: {} },
+  data: { category: "time" },
   execute: (_args, _agent) => new Date().toISOString(),
 };
 
@@ -54,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
 
@@ -65,13 +66,18 @@ 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[]`. |
+| `isAbort` | `() => boolean \| Promise<boolean>` | Abort hook polled during `run`; return `true` to stop early and return partial results. |
 | `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.
+
+`isAbort` is polled on the hot path (including streaming). When it returns `true`, `agent.run` stops and returns whatever messages it has so far. Streaming abort returns a partial AI message with `isPartial: true`.
+
 ## Scripts
 
 | Command | Description |

package/dist/abort.d.ts

@@ -0,0 +1,5 @@
+export type AbortChecker = {
+    check: () => Promise<boolean>;
+    isAborted: () => boolean;
+};
+export declare function createAbortChecker(isAbort?: () => boolean | Promise<boolean>): AbortChecker;

package/dist/abort.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAbortChecker = createAbortChecker;
+function createAbortChecker(isAbort) {
+    let aborted = false;
+    const check = async () => {
+        if (!isAbort)
+            return false;
+        try {
+            const result = await Promise.resolve(isAbort());
+            if (result)
+                aborted = true;
+            return result;
+        }
+        catch {
+            aborted = true;
+            return true;
+        }
+    };
+    const isAborted = () => aborted;
+    return { check, isAborted };
+}

package/dist/adapter/openai.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openaiAdapter = openaiAdapter;
+const abort_1 = require("../abort");
 const types_1 = require("../types");
 const sse_1 = require("./sse");
 const ROLE_TO_OPENAI = {
@@ -31,6 +32,7 @@ async function openaiAdapter(config, context, tools) {
     const apiKey = config.apiKey || process.env.OPENAI_API_KEY || "";
     const model = config.model ?? "gpt-5-nano";
     const onStream = config.onStream;
+    const { check, isAborted } = (0, abort_1.createAbortChecker)(config.isAbort);
     if (!apiKey)
         throw new Error("OpenAI adapter requires apiKey in config or OPENAI_API_KEY env");
     const contextMessages = toOpenAIMessages(context);
@@ -45,6 +47,8 @@ async function openaiAdapter(config, context, tools) {
         tool_choice: tools.length ? "auto" : undefined,
         stream: onStream ? true : undefined,
     };
+    if (await check())
+        return [];
     const res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/chat/completions`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
@@ -106,7 +110,8 @@ async function openaiAdapter(config, context, tools) {
                 content += delta.content;
                 await Promise.resolve(onStream(delta.content));
             }
-        });
+            await check();
+        }, check);
         if (toolCalls.size > 0) {
             return [...toolCalls.entries()]
                 .sort((a, b) => a[0] - b[0])
@@ -121,7 +126,9 @@ async function openaiAdapter(config, context, tools) {
                 };
             });
         }
-        return [{ role: types_1.Role.Ai, content }];
+        if (!content)
+            return [];
+        return [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }];
     }
     const text = await res.text();
     let data;

package/dist/adapter/openrouter.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openrouterAdapter = openrouterAdapter;
+const abort_1 = require("../abort");
 const types_1 = require("../types");
 const sse_1 = require("./sse");
 const ROLE_TO_OPENROUTER = {
@@ -33,6 +34,7 @@ async function openrouterAdapter(config, context, tools) {
     const httpReferer = config.httpReferer;
     const title = config.title;
     const onStream = config.onStream;
+    const { check, isAborted } = (0, abort_1.createAbortChecker)(config.isAbort);
     if (!apiKey)
         throw new Error("OpenRouter adapter requires apiKey in config or OPENROUTER_API_KEY env");
     const contextMessages = toOpenRouterMessages(context);
@@ -55,6 +57,8 @@ async function openrouterAdapter(config, context, tools) {
         headers["HTTP-Referer"] = httpReferer;
     if (title)
         headers["X-Title"] = title;
+    if (await check())
+        return [];
     const res = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
         method: "POST",
         headers,
@@ -116,7 +120,8 @@ async function openrouterAdapter(config, context, tools) {
                 content += delta.content;
                 await Promise.resolve(onStream(delta.content));
             }
-        });
+            await check();
+        }, check);
         if (toolCalls.size > 0) {
             return [...toolCalls.entries()]
                 .sort((a, b) => a[0] - b[0])
@@ -131,7 +136,9 @@ async function openrouterAdapter(config, context, tools) {
                 };
             });
         }
-        return [{ role: types_1.Role.Ai, content }];
+        if (!content)
+            return [];
+        return [{ role: types_1.Role.Ai, content, isPartial: isAborted() ? true : undefined }];
     }
     const text = await res.text();
     let data;

package/dist/adapter/sse.d.ts

@@ -1 +1 @@
-export declare function readSse(res: Response, onData: (data: string) => void | Promise<void>): Promise<void>;
+export declare function readSse(res: Response, onData: (data: string) => void | Promise<void>, isAbort?: () => boolean | Promise<boolean>): Promise<void>;

package/dist/adapter/sse.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readSse = readSse;
-async function readSse(res, onData) {
+async function readSse(res, onData, isAbort) {
     const body = res.body;
     if (!body)
         throw new Error("Response body is empty");
@@ -10,12 +10,16 @@ async function readSse(res, onData) {
     let buffer = "";
     let dataLines = [];
     for (;;) {
+        if (isAbort && (await isAbort()))
+            return;
         const { value, done } = await reader.read();
         if (done)
             break;
         buffer += decoder.decode(value, { stream: true });
         let newlineIndex = buffer.indexOf("\n");
         while (newlineIndex !== -1) {
+            if (isAbort && (await isAbort()))
+                return;
             let line = buffer.slice(0, newlineIndex);
             buffer = buffer.slice(newlineIndex + 1);
             if (line.endsWith("\r"))
@@ -34,6 +38,8 @@ async function readSse(res, onData) {
         }
     }
     if (buffer) {
+        if (isAbort && (await isAbort()))
+            return;
         let line = buffer;
         if (line.endsWith("\r"))
             line = line.slice(0, -1);
@@ -41,6 +47,8 @@ async function readSse(res, onData) {
             dataLines.push(line.slice(5).trimStart());
     }
     if (dataLines.length > 0) {
+        if (isAbort && (await isAbort()))
+            return;
         const data = dataLines.join("\n");
         await onData(data);
     }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import type { AgentConfig, AgentLike, 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, AgentLike, Context, Message, RunOptions, Tool } from "./types";
+export type { Adapter, AgentConfig, AgentLike, Context, Message, Tool } from "./types";
 export { Role } from "./types";
 export declare class Agent implements AgentLike {
     context: Context;
@@ -14,5 +14,5 @@ export declare class Agent implements AgentLike {
     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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = exports.Role = exports.openrouterAdapter = exports.openaiAdapter = void 0;
 const openai_1 = require("./adapter/openai");
 const openrouter_1 = require("./adapter/openrouter");
+const abort_1 = require("./abort");
 const types_1 = require("./types");
 var openai_2 = require("./adapter/openai");
 Object.defineProperty(exports, "openaiAdapter", { enumerable: true, get: function () { return openai_2.openaiAdapter; } });
@@ -28,9 +29,11 @@ class Agent {
     registerTool(tool) {
         this.tools.push(tool);
     }
-    async run(message, options = {}) {
-        const once = options.once ?? false;
+    async run(message) {
         const all = [];
+        const { check } = (0, abort_1.createAbortChecker)(this.config.isAbort);
+        if (await check())
+            return all;
         const sessionContext = [...this.context];
         const persistToContext = (msgs) => {
             this.context.push(...msgs);
@@ -40,9 +43,10 @@ class Agent {
         };
         const userMessage = { role: types_1.Role.User, content: message };
         pushToSession([userMessage]);
-        if (!once)
-            persistToContext([userMessage]);
+        persistToContext([userMessage]);
         const runAdapter = async () => {
+            if (await check())
+                return [];
             const msgs = await this.adapter(this.config, sessionContext, this.tools);
             pushToSession(msgs);
             persistToContext(msgs);
@@ -50,7 +54,11 @@ class Agent {
             return msgs;
         };
         let msgs = await runAdapter();
+        if (await check())
+            return all;
         for (;;) {
+            if (await check())
+                return all;
             const last = msgs[msgs.length - 1];
             if (this.endCondition(sessionContext, last))
                 return all;
@@ -58,6 +66,8 @@ class Agent {
             if (toolCalls.length === 0)
                 return all;
             const results = await Promise.all(toolCalls.map(async (m) => {
+                if (await check())
+                    return null;
                 const tool = this.tools.find((t) => t.name === m.toolName);
                 if (!tool)
                     throw new Error(`Tool "${m.toolName}" is not registered`);

package/dist/types.d.ts

@@ -14,6 +14,7 @@ export type Message = {
 } | {
     role: Role.Ai;
     content: string;
+    isPartial?: boolean;
 } | {
     role: Role.ToolCall;
     toolName: string;
@@ -29,17 +30,19 @@ export type Context = Message[];
 export interface AgentLike {
     context: Context;
     registerTool: (tool: Tool) => void;
-    run: (message: string, options?: RunOptions) => Promise<Message[]>;
+    run: (message: string) => Promise<Message[]>;
 }
 export type Tool = {
     name: string;
     description: string;
     parameters: 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>;
+    isAbort?: () => boolean | Promise<boolean>;
     onToolCall?: (message: Extract<Message, {
         role: Role.ToolCall;
     }>, args: unknown, agent: AgentLike) => boolean | void | Promise<boolean | void>;
@@ -48,7 +51,4 @@ export type AgentConfig = {
     }>, 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": "4.0.0",
+  "version": "5.1.0",
   "description": "Minimal Agent library, zero dependencies",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",