@arki-moe/agent-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arki.moe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# agent.ts
+
+Minimal Agent library, zero dependencies
+
+## Usage Example
+
+```ts
+import { Agent, Role, type Tool } from "agent-ts";
+
+const getTimeTool: Tool = {
+  name: "get_time",
+  description: "Get the current time in ISO format",
+  parameters: { type: "object", properties: {} },
+  execute: () => new Date().toISOString(),
+};
+
+const agent = new Agent("openai", {
+  apiKey: "sk-...",
+  model: "gpt-5-nano",
+  system: "You are a helpful assistant. Reply concisely.", // optional: system role
+});
+agent.registerTool(getTimeTool);
+
+// run: Executes tool chain automatically, returns new messages, context is maintained automatically
+const msgs = await agent.run({ role: Role.User, content: "What time is it?" });
+console.log(msgs);
+
+// step: Single-step inference, returns new messages from the model
+const msgs2 = await agent.step({ role: Role.User, content: "Hello" });
+console.log(msgs2);
+
+// context is a public property that can be read directly
+console.log(agent.context);
+```
+
+## 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[]`

package/dist/adapter/openai.d.ts

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

package/dist/adapter/openai.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openaiAdapter = openaiAdapter;
+const types_1 = require("../types");
+const ROLE_TO_OPENAI = {
+    [types_1.Role.System]: "system",
+    [types_1.Role.User]: "user",
+    [types_1.Role.Ai]: "assistant",
+};
+function toOpenAIMessages(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_OPENAI[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 openaiAdapter(config, context, tools) {
+    const baseUrl = config.baseUrl ?? "https://api.openai.com";
+    const apiKey = config.apiKey ?? "";
+    const model = config.model ?? "gpt-5-nano";
+    if (!apiKey)
+        throw new Error("OpenAI adapter requires apiKey in config");
+    const contextMessages = toOpenAIMessages(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 res = await fetch(`${baseUrl.replace(/\/$/, "")}/v1/chat/completions`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        let errMsg = `OpenAI 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(`OpenAI API returned invalid JSON: ${text.slice(0, 200)}`);
+    }
+    if (data.error)
+        throw new Error(`OpenAI API error: ${data.error.message}`);
+    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 [{ role: types_1.Role.Ai, content: msg.content ?? "" }];
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { Context, Message, Tool } from "./types";
+export { openaiAdapter } from "./adapter/openai";
+export type { Adapter, Context, Message, Tool } from "./types";
+export { Role } from "./types";
+export declare class Agent {
+    context: Context;
+    private adapter;
+    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[]>;
+}

package/dist/index.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = exports.Role = exports.openaiAdapter = void 0;
+const openai_1 = require("./adapter/openai");
+const types_1 = require("./types");
+var openai_2 = require("./adapter/openai");
+Object.defineProperty(exports, "openaiAdapter", { enumerable: true, get: function () { return openai_2.openaiAdapter; } });
+var types_2 = require("./types");
+Object.defineProperty(exports, "Role", { enumerable: true, get: function () { return types_2.Role; } });
+const adapters = {
+    openai: openai_1.openaiAdapter,
+};
+class Agent {
+    constructor(adapterName, config) {
+        this.context = [];
+        this.tools = [];
+        this.adapter = adapters[adapterName] ?? (() => { throw new Error(`Adapter "${adapterName}" not found`); })();
+        this.config = config;
+    }
+    registerTool(tool) {
+        this.tools.push(tool);
+    }
+    async step(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);
+        const all = [];
+        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)
+                return all;
+            for (const m of msgs) {
+                if (m.role !== types_1.Role.ToolCall)
+                    continue;
+                const tool = this.tools.find((t) => t.name === m.toolName);
+                if (!tool)
+                    throw new Error(`Tool "${m.toolName}" is not registered`);
+                let content;
+                let isError = false;
+                try {
+                    const args = JSON.parse(m.argsText || "{}");
+                    const out = await Promise.resolve(tool.execute(args));
+                    content = typeof out === "string" ? out : JSON.stringify(out);
+                }
+                catch (err) {
+                    isError = true;
+                    content = err instanceof Error ? err.message : String(err);
+                }
+                const result = { role: types_1.Role.ToolResult, callId: m.callId, content, isError };
+                this.context.push(result);
+                all.push(result);
+            }
+        }
+    }
+}
+exports.Agent = Agent;

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+export declare enum Role {
+    System = "system",
+    User = "user",
+    Ai = "ai",
+    ToolCall = "tool_call",
+    ToolResult = "tool_result"
+}
+export type Message = {
+    role: Role.System;
+    content: string;
+} | {
+    role: Role.User;
+    content: string;
+} | {
+    role: Role.Ai;
+    content: string;
+} | {
+    role: Role.ToolCall;
+    toolName: string;
+    callId: string;
+    argsText: string;
+} | {
+    role: Role.ToolResult;
+    callId: string;
+    content: string;
+    isError?: boolean;
+};
+export type Context = Message[];
+export type Tool = {
+    name: string;
+    description: string;
+    parameters: unknown;
+    execute: (args: unknown) => Promise<unknown> | unknown;
+};
+export type Adapter = (config: Record<string, unknown>, context: Message[], tools: Tool[]) => Promise<Message[]>;

package/dist/types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Role = void 0;
+var Role;
+(function (Role) {
+    Role["System"] = "system";
+    Role["User"] = "user";
+    Role["Ai"] = "ai";
+    Role["ToolCall"] = "tool_call";
+    Role["ToolResult"] = "tool_result";
+})(Role || (exports.Role = Role = {}));

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@arki-moe/agent-ts",
+  "version": "1.0.0",
+  "description": "Minimal Agent library, zero dependencies",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc --noEmit -p tsconfig.check.json",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "openai",
+    "ai",
+    "chat"
+  ],
+  "author": "haruamamiya",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arki-moe/agent-ts.git"
+  },
+  "packageManager": "pnpm@10.23.0",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}