@arki-moe/agent-ts 1.0.0 → 1.0.2

package/README.md

@@ -1,11 +1,13 @@
-# agent.ts
+# agent-ts
+
+[![npm](https://img.shields.io/npm/v/@arki-moe/agent-ts.svg)](https://www.npmjs.com/package/@arki-moe/agent-ts) [![npm](https://img.shields.io/npm/dm/@arki-moe/agent-ts.svg)](https://www.npmjs.com/package/@arki-moe/agent-ts)
 
 Minimal Agent library, zero dependencies
 
 ## Usage Example
 
 ```ts
-import { Agent, Role, type Tool } from "agent-ts";
+import { Agent, Role, type Tool } from "@arki-moe/agent-ts";
 
 const getTimeTool: Tool = {
   name: "get_time",
@@ -33,10 +35,46 @@ console.log(msgs2);
 console.log(agent.context);
 ```
 
+## Supported Adapters
+
+| Adapter | Required | Optional |
+|---------|----------|----------|
+| `openai` | `apiKey` (or `OPENAI_API_KEY` env), `model` | `system`, `baseUrl` |
+| `openrouter` | `apiKey` (or `OPENROUTER_API_KEY` env), `model` | `system`, `baseUrl`, `httpReferer`, `title` |
+
+When `apiKey` is not provided in config, adapters read from the corresponding environment variable. An error is thrown only when both are missing.
+
 ## API
 
 - `Agent(adapterName, config)` - Create Agent, config contains `apiKey`, `model`, `system` (optional), etc.
 - `agent.context` - Public property, complete conversation history
 - `agent.registerTool(tool)` - Register tool
-- `agent.step(message)` - Call model once, returns new `Message[]`
-- `agent.run(message)` - Execute tool chain automatically, returns all new `Message[]`
+- `agent.step(message?)` - Call model once, returns new `Message[]`
+- `agent.run(message, endCondition?)` - Execute tool chain automatically, returns all new `Message[]`
+- `agent.fork()` - Create a new agent with a copied context
+
+`agent.step` and `agent.run` always append new messages to `agent.context`.
+`endCondition` receives `(context, last)` and stops the run when it returns `true`. Defaults to `last.role === Role.Ai`.
+
+`agent.fork()` shallow-copies the context array, but message objects are shared. This means:
+- Shallow copy: `forked.context !== agent.context`, so pushing new messages does not affect the other agent.
+- Shared messages: modifying a message object in one context will be visible in the other.
+
+Example:
+
+```ts
+const forked = agent.fork();
+forked.context.push({ role: Role.User, content: "hi" });
+// agent.context length is unchanged
+
+forked.context[0].content = "changed";
+// agent.context[0].content is also "changed" because messages are shared
+```
+
+## Scripts
+
+| Command | Description |
+|---------|--------------|
+| `pnpm run build` | Compile TypeScript to `dist/` |
+| `pnpm run check` | Type check (no emit) |
+| `pnpm test` | Run tests (API key read from env var for real API tests) |

package/dist/adapter/openai.js

@@ -27,10 +27,10 @@ function toOpenAIMessages(context) {
 }
 async function openaiAdapter(config, context, tools) {
     const baseUrl = config.baseUrl ?? "https://api.openai.com";
-    const apiKey = config.apiKey ?? "";
+    const apiKey = config.apiKey || process.env.OPENAI_API_KEY || "";
     const model = config.model ?? "gpt-5-nano";
     if (!apiKey)
-        throw new Error("OpenAI adapter requires apiKey in config");
+        throw new Error("OpenAI adapter requires apiKey in config or OPENAI_API_KEY env");
     const contextMessages = toOpenAIMessages(context);
     const systemContent = config.system;
     const messages = systemContent

package/dist/adapter/openrouter.d.ts

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

package/dist/adapter/openrouter.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openrouterAdapter = openrouterAdapter;
+const types_1 = require("../types");
+const ROLE_TO_OPENROUTER = {
+    [types_1.Role.System]: "system",
+    [types_1.Role.User]: "user",
+    [types_1.Role.Ai]: "assistant",
+};
+function toOpenRouterMessages(context) {
+    return context.reduce((out, m) => {
+        if (m.role === types_1.Role.System || m.role === types_1.Role.User || m.role === types_1.Role.Ai)
+            return [...out, { role: ROLE_TO_OPENROUTER[m.role], content: m.content }];
+        if (m.role === types_1.Role.ToolResult)
+            return [...out, { role: "tool", content: m.content, tool_call_id: m.callId }];
+        if (m.role === types_1.Role.ToolCall) {
+            const tc = { id: m.callId, type: "function", function: { name: m.toolName, arguments: m.argsText ?? "{}" } };
+            const last = out[out.length - 1];
+            if (last?.tool_calls) {
+                last.tool_calls.push(tc);
+                return out;
+            }
+            return [...out, { role: "assistant", tool_calls: [tc] }];
+        }
+        return out;
+    }, []);
+}
+async function openrouterAdapter(config, context, tools) {
+    const baseUrl = config.baseUrl ?? "https://openrouter.ai/api/v1";
+    const apiKey = config.apiKey || process.env.OPENROUTER_API_KEY || "";
+    const model = config.model ?? "gpt-5-nano";
+    const httpReferer = config.httpReferer;
+    const title = config.title;
+    if (!apiKey)
+        throw new Error("OpenRouter adapter requires apiKey in config or OPENROUTER_API_KEY env");
+    const contextMessages = toOpenRouterMessages(context);
+    const systemContent = config.system;
+    const messages = systemContent
+        ? [{ role: "system", content: systemContent }, ...contextMessages]
+        : contextMessages;
+    const body = {
+        model,
+        messages,
+        tools: tools.length ? tools.map((t) => ({ type: "function", function: { name: t.name, description: t.description, parameters: t.parameters ?? {} } })) : undefined,
+        tool_choice: tools.length ? "auto" : undefined,
+    };
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+    };
+    if (httpReferer)
+        headers["HTTP-Referer"] = httpReferer;
+    if (title)
+        headers["X-Title"] = title;
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        let errMsg = `OpenRouter API HTTP ${res.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed?.error?.message)
+                errMsg = parsed.error.message;
+        }
+        catch {
+            if (text)
+                errMsg += `: ${text.slice(0, 200)}`;
+        }
+        throw new Error(errMsg);
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`OpenRouter API returned invalid JSON: ${text.slice(0, 200)}`);
+    }
+    if (data.error)
+        throw new Error(`OpenRouter API error: ${data.error.message}`);
+    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 [{ role: types_1.Role.Ai, content: msg.content ?? "" }];
+}

package/dist/index.d.ts

@@ -1,14 +1,17 @@
 import type { Context, Message, Tool } from "./types";
 export { openaiAdapter } from "./adapter/openai";
+export { openrouterAdapter } from "./adapter/openrouter";
 export type { Adapter, Context, Message, Tool } from "./types";
 export { Role } from "./types";
 export declare class Agent {
     context: Context;
     private adapter;
+    private adapterName;
     private config;
     private tools;
     constructor(adapterName: string, config: Record<string, unknown>);
     registerTool(tool: Tool): void;
-    step(message: Message): Promise<Message[]>;
-    run(message: Message): Promise<Message[]>;
+    step(message?: Message): Promise<Message[]>;
+    run(message: Message, endCondition?: (context: Message[], last: Message) => boolean): Promise<Message[]>;
+    fork(): Agent;
 }

package/dist/index.js

@@ -1,19 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Agent = exports.Role = exports.openaiAdapter = void 0;
+exports.Agent = exports.Role = exports.openrouterAdapter = exports.openaiAdapter = void 0;
 const openai_1 = require("./adapter/openai");
+const openrouter_1 = require("./adapter/openrouter");
 const types_1 = require("./types");
 var openai_2 = require("./adapter/openai");
 Object.defineProperty(exports, "openaiAdapter", { enumerable: true, get: function () { return openai_2.openaiAdapter; } });
+var openrouter_2 = require("./adapter/openrouter");
+Object.defineProperty(exports, "openrouterAdapter", { enumerable: true, get: function () { return openrouter_2.openrouterAdapter; } });
 var types_2 = require("./types");
 Object.defineProperty(exports, "Role", { enumerable: true, get: function () { return types_2.Role; } });
 const adapters = {
     openai: openai_1.openaiAdapter,
+    openrouter: openrouter_1.openrouterAdapter,
 };
 class Agent {
     constructor(adapterName, config) {
         this.context = [];
         this.tools = [];
+        this.adapterName = adapterName;
         this.adapter = adapters[adapterName] ?? (() => { throw new Error(`Adapter "${adapterName}" not found`); })();
         this.config = config;
     }
@@ -21,20 +26,20 @@ class Agent {
         this.tools.push(tool);
     }
     async step(message) {
-        this.context.push(message);
+        if (message) {
+            this.context.push(message);
+        }
         const msgs = await this.adapter(this.config, this.context, this.tools);
         this.context.push(...msgs);
         return msgs;
     }
-    async run(message) {
-        this.context.push(message);
+    async run(message, endCondition = (_context, last) => last.role === types_1.Role.Ai) {
         const all = [];
+        let msgs = await this.step(message);
+        all.push(...msgs);
         for (;;) {
-            const msgs = await this.adapter(this.config, this.context, this.tools);
-            this.context.push(...msgs);
-            all.push(...msgs);
             const last = msgs[msgs.length - 1];
-            if (last.role === types_1.Role.Ai)
+            if (endCondition(this.context, last))
                 return all;
             for (const m of msgs) {
                 if (m.role !== types_1.Role.ToolCall)
@@ -57,7 +62,16 @@ class Agent {
                 this.context.push(result);
                 all.push(result);
             }
+            msgs = await this.step();
+            all.push(...msgs);
         }
     }
+    fork() {
+        const agent = new Agent(this.adapterName, this.config);
+        agent.adapter = this.adapter;
+        agent.tools = [...this.tools];
+        agent.context = [...this.context];
+        return agent;
+    }
 }
 exports.Agent = Agent;

package/package.json

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