@narimangardi/agent-loop 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nariman Gardi
+
+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,126 @@
+# agent-loop
+
+A tiny, zero-dependency, provider-agnostic **agent tool-loop** for TypeScript.
+The whole thing is one small class: ask an LLM, run the tools it asks for, feed
+the results back, repeat until it answers. Bring your own model.
+
+I built an AI-agent workshop ([Atelier](https://gardi.dev/projects/atelier))
+where agents do real work on a git repo — and wrote the agent loop from scratch
+rather than reaching for an SDK. This is that core, pulled out and generalized:
+no framework, no provider lock-in, nothing to learn but one interface.
+
+## Install
+
+```bash
+npm i @narimangardi/agent-loop
+```
+
+## Use it
+
+Define some tools, plug in a provider, and run:
+
+```ts
+import { Agent } from '@narimangardi/agent-loop';
+import type { Tool } from '@narimangardi/agent-loop';
+
+const getWeather: Tool<{ city: string }> = {
+  name: 'get_weather',
+  description: 'Get the current weather for a city.',
+  parameters: {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city'],
+  },
+  execute: async ({ city }) => `It's 24°C and clear in ${city}.`,
+};
+
+const agent = new Agent({
+  provider: openai, // see "Plug in a model" below
+  tools: [getWeather],
+  system: 'You are a concise assistant.',
+});
+
+const result = await agent.run('What should I wear in Erbil today?');
+console.log(result.text);   // the final answer
+console.log(result.steps);  // how many round-trips it took
+```
+
+## How it works
+
+`run()` is the entire loop:
+
+1. Send the conversation + tool specs to the provider.
+2. If the provider returns a **message**, that's the answer — return it.
+3. If it returns **tool calls**, run each tool and append the results.
+4. Go back to step 1 (up to `maxSteps`, default 10).
+
+Unknown tools and thrown errors are handed back to the model as text, so it can
+recover instead of crashing the loop.
+
+## Plug in a model
+
+There's one interface to implement — map your LLM's tool-calling API to a
+`CompletionResponse`:
+
+```ts
+import type { Provider } from '@narimangardi/agent-loop';
+
+const openai: Provider = {
+  async complete({ messages, tools }) {
+    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify({
+        model: 'gpt-4o-mini',
+        messages: toOpenAiMessages(messages), // small adapter you write
+        tools: tools.map((t) => ({ type: 'function', function: t })),
+      }),
+    });
+
+    const { choices } = await res.json();
+    const message = choices[0].message;
+
+    if (message.tool_calls?.length) {
+      return {
+        kind: 'tool_calls',
+        toolCalls: message.tool_calls.map((c: any) => ({
+          id: c.id,
+          name: c.function.name,
+          arguments: JSON.parse(c.function.arguments),
+        })),
+      };
+    }
+
+    return { kind: 'message', content: message.content };
+  },
+};
+```
+
+The same shape works for Anthropic, Gemini, Ollama, or anything else — it's just
+"messages + tools in, message-or-tool-calls out."
+
+## Limitations
+
+Deliberately small. Worth knowing:
+
+- **No streaming.** `run()` resolves once, with the final text.
+- **One run per call.** Multi-turn chat is yours to drive (keep calling `run`,
+  or hold the returned `messages`).
+- **No retries / rate-limit handling.** Wrap your `Provider` for that.
+- **No argument validation.** Tools receive whatever the model sends; validate
+  inside `execute` if you need to.
+
+## Development
+
+```bash
+npm install
+npm test        # vitest
+npm run build   # tsup → dist (esm + cjs + d.ts)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.cjs

@@ -0,0 +1,99 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Agent: () => Agent,
+  MaxStepsExceededError: () => MaxStepsExceededError,
+  defineTool: () => defineTool
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/agent.ts
+var MaxStepsExceededError = class extends Error {
+  constructor(steps, messages) {
+    super(`Agent did not finish within ${steps} steps`);
+    this.steps = steps;
+    this.messages = messages;
+    this.name = "MaxStepsExceededError";
+  }
+  steps;
+  messages;
+};
+var Agent = class {
+  provider;
+  tools;
+  toolSpecs;
+  system;
+  maxSteps;
+  constructor(options) {
+    const tools = options.tools ?? [];
+    this.provider = options.provider;
+    this.tools = new Map(tools.map((tool) => [tool.name, tool]));
+    this.toolSpecs = tools.map(({ name, description, parameters }) => ({ name, description, parameters }));
+    this.system = options.system;
+    this.maxSteps = options.maxSteps ?? 10;
+  }
+  async run(prompt) {
+    const messages = [];
+    if (this.system !== void 0) messages.push({ role: "system", content: this.system });
+    messages.push({ role: "user", content: prompt });
+    for (let step = 1; step <= this.maxSteps; step++) {
+      const response = await this.provider.complete({ messages, tools: this.toolSpecs });
+      if (response.kind === "message") {
+        messages.push({ role: "assistant", content: response.content });
+        return { text: response.content, steps: step, messages };
+      }
+      messages.push({ role: "assistant", content: null, toolCalls: response.toolCalls });
+      for (const call of response.toolCalls) {
+        messages.push({
+          role: "tool",
+          toolCallId: call.id,
+          name: call.name,
+          content: await this.runTool(call)
+        });
+      }
+    }
+    throw new MaxStepsExceededError(this.maxSteps, messages);
+  }
+  /** Run one tool. Unknown tools and thrown errors come back as text the model can recover from. */
+  async runTool(call) {
+    const tool = this.tools.get(call.name);
+    if (tool === void 0) {
+      return `Error: unknown tool "${call.name}"`;
+    }
+    try {
+      return await tool.execute(call.arguments);
+    } catch (error) {
+      return `Error: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  }
+};
+
+// src/tool.ts
+function defineTool(tool) {
+  return tool;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Agent,
+  MaxStepsExceededError,
+  defineTool
+});

package/dist/index.d.cts

@@ -0,0 +1,101 @@
+/** A single tool call the model wants to make. */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** A message in the running conversation. */
+type Message = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string | null;
+    toolCalls?: ToolCall[];
+} | {
+    role: 'tool';
+    toolCallId: string;
+    name: string;
+    content: string;
+};
+/** A tool the agent can call. `execute` returns the result the model sees. */
+interface Tool<A extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    /** JSON Schema describing the arguments. */
+    parameters: Record<string, unknown>;
+    execute(args: A): string | Promise<string>;
+}
+/** The tool shape sent to the provider (everything except `execute`). */
+interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface CompletionRequest {
+    messages: Message[];
+    tools: ToolSpec[];
+}
+/** What a provider returns: either a final message, or tool calls to run. */
+type CompletionResponse = {
+    kind: 'message';
+    content: string;
+} | {
+    kind: 'tool_calls';
+    toolCalls: ToolCall[];
+};
+/**
+ * The one thing you implement to plug in an LLM. Map your provider's
+ * chat/tool-calling API to a CompletionResponse and you're done.
+ */
+interface Provider {
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+}
+
+interface AgentOptions {
+    provider: Provider;
+    tools?: Tool[];
+    system?: string;
+    /** Max provider round-trips before giving up. Default 10. */
+    maxSteps?: number;
+}
+interface AgentResult {
+    /** The assistant's final text answer. */
+    text: string;
+    /** How many provider round-trips it took. */
+    steps: number;
+    /** The full history, including tool calls and their results. */
+    messages: Message[];
+}
+declare class MaxStepsExceededError extends Error {
+    readonly steps: number;
+    readonly messages: Message[];
+    constructor(steps: number, messages: Message[]);
+}
+/**
+ * The whole agent: ask the provider, run any tools it calls, feed the results
+ * back, repeat until it returns a final answer (or maxSteps is hit).
+ */
+declare class Agent {
+    private readonly provider;
+    private readonly tools;
+    private readonly toolSpecs;
+    private readonly system?;
+    private readonly maxSteps;
+    constructor(options: AgentOptions);
+    run(prompt: string): Promise<AgentResult>;
+    /** Run one tool. Unknown tools and thrown errors come back as text the model can recover from. */
+    private runTool;
+}
+
+/**
+ * Identity helper that gives you argument typing when defining a tool inline:
+ *
+ *   const t = defineTool<{ city: string }>({ ... execute(args) { args.city } })
+ */
+declare function defineTool<A extends Record<string, unknown> = Record<string, unknown>>(tool: Tool<A>): Tool<A>;
+
+export { Agent, type AgentOptions, type AgentResult, type CompletionRequest, type CompletionResponse, MaxStepsExceededError, type Message, type Provider, type Tool, type ToolCall, type ToolSpec, defineTool };

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+/** A single tool call the model wants to make. */
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** A message in the running conversation. */
+type Message = {
+    role: 'system';
+    content: string;
+} | {
+    role: 'user';
+    content: string;
+} | {
+    role: 'assistant';
+    content: string | null;
+    toolCalls?: ToolCall[];
+} | {
+    role: 'tool';
+    toolCallId: string;
+    name: string;
+    content: string;
+};
+/** A tool the agent can call. `execute` returns the result the model sees. */
+interface Tool<A extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    /** JSON Schema describing the arguments. */
+    parameters: Record<string, unknown>;
+    execute(args: A): string | Promise<string>;
+}
+/** The tool shape sent to the provider (everything except `execute`). */
+interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface CompletionRequest {
+    messages: Message[];
+    tools: ToolSpec[];
+}
+/** What a provider returns: either a final message, or tool calls to run. */
+type CompletionResponse = {
+    kind: 'message';
+    content: string;
+} | {
+    kind: 'tool_calls';
+    toolCalls: ToolCall[];
+};
+/**
+ * The one thing you implement to plug in an LLM. Map your provider's
+ * chat/tool-calling API to a CompletionResponse and you're done.
+ */
+interface Provider {
+    complete(request: CompletionRequest): Promise<CompletionResponse>;
+}
+
+interface AgentOptions {
+    provider: Provider;
+    tools?: Tool[];
+    system?: string;
+    /** Max provider round-trips before giving up. Default 10. */
+    maxSteps?: number;
+}
+interface AgentResult {
+    /** The assistant's final text answer. */
+    text: string;
+    /** How many provider round-trips it took. */
+    steps: number;
+    /** The full history, including tool calls and their results. */
+    messages: Message[];
+}
+declare class MaxStepsExceededError extends Error {
+    readonly steps: number;
+    readonly messages: Message[];
+    constructor(steps: number, messages: Message[]);
+}
+/**
+ * The whole agent: ask the provider, run any tools it calls, feed the results
+ * back, repeat until it returns a final answer (or maxSteps is hit).
+ */
+declare class Agent {
+    private readonly provider;
+    private readonly tools;
+    private readonly toolSpecs;
+    private readonly system?;
+    private readonly maxSteps;
+    constructor(options: AgentOptions);
+    run(prompt: string): Promise<AgentResult>;
+    /** Run one tool. Unknown tools and thrown errors come back as text the model can recover from. */
+    private runTool;
+}
+
+/**
+ * Identity helper that gives you argument typing when defining a tool inline:
+ *
+ *   const t = defineTool<{ city: string }>({ ... execute(args) { args.city } })
+ */
+declare function defineTool<A extends Record<string, unknown> = Record<string, unknown>>(tool: Tool<A>): Tool<A>;
+
+export { Agent, type AgentOptions, type AgentResult, type CompletionRequest, type CompletionResponse, MaxStepsExceededError, type Message, type Provider, type Tool, type ToolCall, type ToolSpec, defineTool };

package/dist/index.js

@@ -0,0 +1,70 @@
+// src/agent.ts
+var MaxStepsExceededError = class extends Error {
+  constructor(steps, messages) {
+    super(`Agent did not finish within ${steps} steps`);
+    this.steps = steps;
+    this.messages = messages;
+    this.name = "MaxStepsExceededError";
+  }
+  steps;
+  messages;
+};
+var Agent = class {
+  provider;
+  tools;
+  toolSpecs;
+  system;
+  maxSteps;
+  constructor(options) {
+    const tools = options.tools ?? [];
+    this.provider = options.provider;
+    this.tools = new Map(tools.map((tool) => [tool.name, tool]));
+    this.toolSpecs = tools.map(({ name, description, parameters }) => ({ name, description, parameters }));
+    this.system = options.system;
+    this.maxSteps = options.maxSteps ?? 10;
+  }
+  async run(prompt) {
+    const messages = [];
+    if (this.system !== void 0) messages.push({ role: "system", content: this.system });
+    messages.push({ role: "user", content: prompt });
+    for (let step = 1; step <= this.maxSteps; step++) {
+      const response = await this.provider.complete({ messages, tools: this.toolSpecs });
+      if (response.kind === "message") {
+        messages.push({ role: "assistant", content: response.content });
+        return { text: response.content, steps: step, messages };
+      }
+      messages.push({ role: "assistant", content: null, toolCalls: response.toolCalls });
+      for (const call of response.toolCalls) {
+        messages.push({
+          role: "tool",
+          toolCallId: call.id,
+          name: call.name,
+          content: await this.runTool(call)
+        });
+      }
+    }
+    throw new MaxStepsExceededError(this.maxSteps, messages);
+  }
+  /** Run one tool. Unknown tools and thrown errors come back as text the model can recover from. */
+  async runTool(call) {
+    const tool = this.tools.get(call.name);
+    if (tool === void 0) {
+      return `Error: unknown tool "${call.name}"`;
+    }
+    try {
+      return await tool.execute(call.arguments);
+    } catch (error) {
+      return `Error: ${error instanceof Error ? error.message : String(error)}`;
+    }
+  }
+};
+
+// src/tool.ts
+function defineTool(tool) {
+  return tool;
+}
+export {
+  Agent,
+  MaxStepsExceededError,
+  defineTool
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@narimangardi/agent-loop",
+  "version": "0.1.0",
+  "description": "A tiny, zero-dependency, provider-agnostic agent tool-loop for TypeScript. Build your own AI agent in ~100 lines.",
+  "keywords": ["ai", "agent", "tool-use", "function-calling", "llm", "typescript"],
+  "license": "MIT",
+  "author": "Nariman Gardi <narimanmuhsin0@gmail.com>",
+  "repository": { "type": "git", "url": "git+https://github.com/NarimanGardi/agent-loop.git" },
+  "homepage": "https://github.com/NarimanGardi/agent-loop#readme",
+  "bugs": "https://github.com/NarimanGardi/agent-loop/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}