typed-agents 1.0.0

package/LICENSE

@@ -0,0 +1,19 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+Copyright 2026 typed-agents
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,201 @@
+<div align="center">
+
+# 🤖 typed-agents
+
+> A TypeScript framework for building AI Agents and Tools with decorators, behavior files, composable sub-agents, streaming, and persistent state.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](LICENSE)
+[![Node](https://img.shields.io/badge/Node.js-18+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Ollama](https://img.shields.io/badge/Ollama-compatible-black?style=flat-square)](https://ollama.com/)
+
+</div>
+
+---
+
+## ✨ Features
+
+| | |
+|---|---|
+| 🎨 **Decorator-based** | Define agents and tools with `@agent` and `@tool` — zero boilerplate |
+| 🔁 **Multi-step reasoning** | Agents loop through LLM calls and tool executions automatically |
+| 🧩 **Agent composition** | Nest agents as tools inside other agents via `compose()` |
+| 📄 **Behavior engine** | Define agent personality and rules in plain `.md` files |
+| 💾 **State persistence** | Resume interrupted runs from memory or disk |
+| ⚡ **Sub-agent caching** | Avoid redundant sub-agent calls with built-in SHA-256 caching |
+| 🔄 **Retry & backoff** | Automatic exponential backoff for LLM and tool calls |
+| 📡 **Event system** | Subscribe to lifecycle events at every stage of a run |
+| 🔌 **Pluggable clients** | Ships with `OllamaClient`, extendable via `LLMClient` interface |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Define a Tool
+
+```ts
+import { tool } from "./tools/toolDecorator";
+import { z } from "zod";
+
+class MyTools {
+  @tool({
+    name: "get_weather",
+    description: "Returns the weather for a given city",
+    inputSchema: z.object({ city: z.string() }),
+  })
+  async getWeather({ city }: { city: string }) {
+    return `Sunny in ${city}, 24°C`;
+  }
+}
+```
+
+### 2. Define an Agent
+
+```ts
+import { agent } from "./agents/agentDecorator";
+import { OllamaClient } from "./clients/ollamaClient";
+
+@agent({
+  name: "weather-agent",
+  llmClient: new OllamaClient("granite4:3b"),
+  tools: [MyTools],
+  maxSteps: 5,
+})
+class WeatherAgent {}
+```
+
+### 3. Run it
+
+```ts
+import { runAgent } from "./runtime/agentRunner";
+
+const result = await runAgent(WeatherAgent, "What's the weather in Rome?");
+console.log(result);
+```
+
+---
+
+## 🧩 Agent Composition
+
+Agents can be used as tools inside other agents. The orchestrator delegates tasks to specialized sub-agents automatically.
+
+```ts
+@agent({ name: "researcher", llmClient: new OllamaClient("granite4:3b") })
+class Researcher {}
+
+@agent({
+  name: "orchestrator",
+  llmClient: new OllamaClient("granite4:3b"),
+  tools: [
+    "auto",
+    compose(Researcher, { description: "Deep-dive research on any topic" }),
+  ],
+  maxSteps: 8,
+})
+class Orchestrator {}
+
+await runAgent(Orchestrator, "Research the future of AI in Italy");
+```
+
+> `"auto"` automatically registers all tools in the global registry.
+
+---
+
+## 📄 Behavior Files
+
+Skip writing raw system prompts. Define how your agent thinks and speaks in a plain `.md` file:
+
+```md
+# role
+You are a strict and concise research assistant.
+
+# rules
+- Never make up information
+- Always cite sources when possible
+
+# planning
+Break down complex tasks before answering.
+
+# answer
+Respond in bullet points. Be brief and factual.
+```
+
+```ts
+@agent({
+  name: "researcher",
+  llmClient: new OllamaClient("granite4:3b"),
+  behavior: "./behaviors/researcher.md",  // or an array of files
+})
+class Researcher {}
+```
+
+Behavior files support **`extends`** for inheritance and can be **merged** from multiple sources.
+
+---
+
+## 💾 State Persistence
+
+Run long tasks without fear of losing progress. Persist state to disk and resume anytime.
+
+```ts
+const result = await runAgent(MyAgent, "Do something long", true, undefined, {
+  persist: true,        // saves to ./.agent-runs/
+  persistCache: true,   // persists sub-agent result cache too
+});
+```
+
+```ts
+// Resume a previous run with its ID
+await runAgent(MyAgent, "", true, undefined, {
+  resumeId: "your-run-id",
+});
+```
+
+| Mode | Description |
+|---|---|
+| `"none"` | No persistence *(default)* |
+| `"memory"` | In-memory, lost on restart |
+| `"file"` | Written to disk, fully resumable |
+
+---
+
+## 📡 Event System
+
+Hook into every stage of an agent's lifecycle for logging, monitoring, or custom side effects.
+
+```ts
+const runtime = new AgentRuntime(true);
+
+runtime.on("agent:start",  (e) => console.log("▶️ Started:", e.payload.agent));
+runtime.on("tool:call",    (e) => console.log("🔧 Tool:", e.payload.name));
+runtime.on("tool:result",  (e) => console.log("✅ Result:", e.payload.result));
+runtime.on("agent:finish", (e) => console.log("🏁 Done:", e.payload.output));
+
+await runtime.run(MyAgent, "Hello!");
+```
+
+**Available events:** `agent:start` · `agent:step` · `agent:finish` · `agent:max_steps` · `agent:resume` · `llm:response` · `tool:call` · `tool:result` · `retry:attempt` · `state:saved`
+
+---
+
+## ⚙️ Requirements
+
+- **Node.js** 18+
+- **TypeScript** with `experimentalDecorators` and `emitDecoratorMetadata` enabled
+- **[Ollama](https://ollama.com)** running locally — or bring your own `LLMClient` implementation
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+---
+
+## 📜 License
+
+Distributed under the **Apache License 2.0**. See [`LICENSE`](LICENSE) for details.

package/dist/agents/agent.decorator.d.ts

@@ -0,0 +1,19 @@
+import "reflect-metadata";
+import { AgentOptions, AgentMetadata } from "./agent.types";
+/**
+ * Class decorator to declare an agent and attach normalized metadata.
+ *
+ * This decorator stores the agent settings (name, model, tools, etc.) as
+ * metadata so that runtime factory code can discover an agent class.
+ *
+ * @param options - User-provided agent configuration.
+ */
+export declare function agent(options: AgentOptions): <T extends new (...args: never[]) => object>(constructor: T) => void;
+/**
+ * Reads agent metadata attached to a class or instance by the `@agent()` decorator.
+ *
+ * @param target - Constructor or object to inspect for metadata.
+ * @returns The agent metadata, or undefined if not decorated.
+ */
+export declare function getAgentMetadata<T extends object>(target: T): AgentMetadata | undefined;
+//# sourceMappingURL=agent.decorator.d.ts.map

package/dist/agents/agent.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.decorator.d.ts","sourceRoot":"","sources":["../../src/agents/agent.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAI5D;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,IACxB,CAAC,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,MAAM,EAAE,aAAa,CAAC,UAa5E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,MAAM,EAAE,CAAC,GACR,aAAa,GAAG,SAAS,CAI3B"}

package/dist/agents/agent.decorator.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agent = agent;
+exports.getAgentMetadata = getAgentMetadata;
+require("reflect-metadata");
+const AGENT_METADATA_KEY = Symbol("typed-agents:agent");
+/**
+ * Class decorator to declare an agent and attach normalized metadata.
+ *
+ * This decorator stores the agent settings (name, model, tools, etc.) as
+ * metadata so that runtime factory code can discover an agent class.
+ *
+ * @param options - User-provided agent configuration.
+ */
+function agent(options) {
+    return function (constructor) {
+        const metadata = {
+            name: options.name,
+            model: options.model,
+            llmClient: options.llmClient,
+            tools: options.tools ?? [],
+            maxSteps: options.maxSteps ?? 5,
+            systemPrompt: options.systemPrompt,
+            behavior: options.behavior,
+        };
+        Reflect.defineMetadata(AGENT_METADATA_KEY, metadata, constructor);
+    };
+}
+/**
+ * Reads agent metadata attached to a class or instance by the `@agent()` decorator.
+ *
+ * @param target - Constructor or object to inspect for metadata.
+ * @returns The agent metadata, or undefined if not decorated.
+ */
+function getAgentMetadata(target) {
+    return Reflect.getMetadata(AGENT_METADATA_KEY, target);
+}
+//# sourceMappingURL=agent.decorator.js.map

package/dist/agents/agent.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.decorator.js","sourceRoot":"","sources":["../../src/agents/agent.decorator.ts"],"names":[],"mappings":";;AAaA,sBAcC;AAQD,4CAMC;AAzCD,4BAA0B;AAG1B,MAAM,kBAAkB,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,SAAgB,KAAK,CAAC,OAAqB;IACzC,OAAO,UAAsD,WAAc;QACzE,MAAM,QAAQ,GAAkB;YAC9B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC;YAC/B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC;QAEF,OAAO,CAAC,cAAc,CAAC,kBAAkB,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IACpE,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC9B,MAAS;IAET,OAAO,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,MAAM,CAExC,CAAC;AAChB,CAAC"}

package/dist/agents/agent.runtime.d.ts

@@ -0,0 +1,133 @@
+import { LLMClient, StreamChunk } from "../clients/llm.client";
+import { type AgentEvent, type RunOptions, type PersistConfig } from "./agent.types";
+/**
+ * Core runtime engine for executing agent classes decorated with `@agent()`.
+ *
+ * Manages the full agent lifecycle: initialization, ReAct loop, tool execution,
+ * persistence, planning/reflection, and event emission. Supports both buffered
+ * and streaming execution modes.
+ */
+export declare class AgentRuntime {
+    private showLogs;
+    private emitter;
+    private subAgentCache;
+    private persister;
+    private cacheDir;
+    /**
+     * Creates a new AgentRuntime instance with optional persistence configuration.
+     *
+     * @param showLogs - Whether to enable console logging for events and operations.
+     * @param persistConfig - Configuration for state persistence (none, memory, or file).
+     */
+    constructor(showLogs: boolean, persistConfig?: PersistConfig);
+    /**
+     * Clears the internal cache of sub-agent results.
+     * Useful for resetting state between runs or when tools change.
+     */
+    clearSubAgentCache(): void;
+    /**
+     * Registers an event handler for a specific agent event type.
+     *
+     * @param event - The event type to listen for (e.g., "agent:start", "tool:call").
+     * @param handler - Callback function invoked when the event is emitted.
+     */
+    on<K extends AgentEvent["type"]>(event: K, handler: (event: Extract<AgentEvent, {
+        type: K;
+    }>) => void): void;
+    /**
+     * Emits an agent event to all registered listeners and optionally logs it.
+     *
+     * @param event - The event object to emit.
+     */
+    private emit;
+    /**
+     * Saves the current agent state to the configured persister.
+     *
+     * @param runId - Unique identifier for the run.
+     * @param context - Current agent context to serialize.
+     * @param isFinished - Whether the run is complete.
+     */
+    private saveState;
+    /**
+     * Saves the sub-agent cache to a JSON file in the cache directory.
+     *
+     * @param runId - Run ID used to name the cache file.
+     */
+    private saveCache;
+    /**
+     * Loads the sub-agent cache from a JSON file if it exists.
+     *
+     * @param runId - Run ID to identify the cache file.
+     */
+    private loadCache;
+    /**
+     * Resolves the LLM client to use, prioritizing injected client, then metadata client, then creating one from model.
+     *
+     * @param metadata - Agent metadata containing client or model info.
+     * @param injected - Optionally injected client (overrides others).
+     * @returns The resolved LLMClient instance.
+     * @throws Error if no client or model is available.
+     */
+    private resolveClient;
+    /**
+     * Builds the initial message array for the agent conversation.
+     *
+     * @param systemPrompt - The system prompt to include.
+     * @param prompt - The user input prompt.
+     * @returns Array of LLMMessage objects.
+     */
+    private buildInitialMessages;
+    /**
+     * Asks the LLM to produce a plan before the main execution loop.
+     * Best-effort: a failure here does not abort the run.
+     *
+     * @param context - Current agent context.
+     * @param client - LLM client to use for planning.
+     * @param options - Run options (for temperature, etc.).
+     */
+    private executePlanningStep;
+    /**
+     * After a tool result, asks the LLM to self-reflect and optionally adjust.
+     * Only triggered in "reflect" planning mode.
+     *
+     * @param context - Current agent context.
+     * @param client - LLM client to use for reflection.
+     */
+    private executeReflectionStep;
+    /**
+     * Executes an agent class in buffered mode, returning the final output string.
+     *
+     * This method handles the full ReAct loop: planning (if enabled), LLM calls,
+     * tool execution, reflection, persistence, and event emission. Supports resuming
+     * from a previous run ID.
+     *
+     * @param agentClass - The agent class decorated with `@agent()`.
+     * @param prompt - The user input prompt to start the conversation.
+     * @param injectedClient - Optional LLM client to override the agent's default.
+     * @param options - Runtime options (maxSteps, temperature, persistence, etc.).
+     * @returns The final output string from the agent.
+     * @throws Error if agent metadata is missing or run resumption fails.
+     */
+    run(agentClass: new () => object, prompt: string, injectedClient?: LLMClient, options?: RunOptions): Promise<string>;
+    /**
+     * Streaming variant of `run`. Yields:
+     * - AgentEvent  for every lifecycle event (steps, tool calls, planning…)
+     * - StreamChunk { type: "text_delta" } for incremental LLM text tokens
+     *
+     * Falls back to buffered `invoke` if the client does not implement `invokeStream`.
+     *
+     * Usage example:
+     *   for await (const event of runtime.runStream(MyAgent, prompt)) {
+     *     if (event.type === "text_delta") process.stdout.write(event.delta);
+     *   }
+     *
+     * @param agentClass - The agent class decorated with `@agent()`.
+     * @param prompt - The user input prompt.
+     * @param injectedClient - Optional LLM client override.
+     * @param options - Runtime options.
+     * @returns Async generator yielding events and stream chunks.
+     * @throws Error if agent metadata is missing.
+     */
+    runStream(agentClass: new () => object, prompt: string, injectedClient?: LLMClient, options?: RunOptions): AsyncGenerator<AgentEvent | StreamChunk>;
+}
+//# sourceMappingURL=agent.runtime.d.ts.map

package/dist/agents/agent.runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.runtime.d.ts","sourceRoot":"","sources":["../../src/agents/agent.runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAc,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAK3E,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,aAAa,EAEnB,MAAM,eAAe,CAAC;AAsCvB;;;;;;GAMG;AACH,qBAAa,YAAY;IAarB,OAAO,CAAC,QAAQ;IAZlB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,QAAQ,CAAuB;IAEvC;;;;;OAKG;gBAEO,QAAQ,EAAE,OAAO,EACzB,aAAa,GAAE,aAAgC;IAcjD;;;OAGG;IACI,kBAAkB,IAAI,IAAI;IAKjC;;;;;OAKG;IACH,EAAE,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,KAAK,IAAI,GACzD,IAAI;IAIP;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAOZ;;;;;;OAMG;YACW,SAAS;IAsBvB;;;;OAIG;YACW,SAAS;IASvB;;;;OAIG;YACW,SAAS;IAcvB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAarB;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAS5B;;;;;;;OAOG;YACW,mBAAmB;IA0BjC;;;;;;OAMG;YACW,qBAAqB;IA0BnC;;;;;;;;;;;;;OAaG;IACG,GAAG,CACP,UAAU,EAAE,UAAU,MAAM,EAC5B,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,SAAS,EAC1B,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,MAAM,CAAC;IA0MlB;;;;;;;;;;;;;;;;;;OAkBG;IACI,SAAS,CACd,UAAU,EAAE,UAAU,MAAM,EAC5B,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,SAAS,EAC1B,OAAO,GAAE,UAAe,GACvB,cAAc,CAAC,UAAU,GAAG,WAAW,CAAC;CAiL5C"}