@opperai/agents 0.1.0

package/dist/index.cjs

@@ -0,0 +1,2656 @@
+'use strict';
+
+var crypto = require('crypto');
+var zod = require('zod');
+var opperai = require('opperai');
+var zodToJsonSchema = require('zod-to-json-schema');
+var index_js = require('@modelcontextprotocol/sdk/client/index.js');
+var sse_js = require('@modelcontextprotocol/sdk/client/sse.js');
+var stdio_js = require('@modelcontextprotocol/sdk/client/stdio.js');
+var streamableHttp_js = require('@modelcontextprotocol/sdk/client/streamableHttp.js');
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/base/result.ts
+exports.Result = void 0; exports.ok = void 0; exports.err = void 0;
+var init_result = __esm({
+  "src/base/result.ts"() {
+    exports.Result = {
+      ok(value) {
+        return { ok: true, value };
+      },
+      err(error) {
+        return { ok: false, error };
+      },
+      isOk(result) {
+        return result.ok;
+      },
+      isErr(result) {
+        return !result.ok;
+      },
+      map(result, mapper) {
+        if (result.ok) {
+          return exports.Result.ok(mapper(result.value));
+        }
+        return result;
+      },
+      mapError(result, mapper) {
+        if (!result.ok) {
+          return exports.Result.err(mapper(result.error));
+        }
+        return result;
+      },
+      unwrapOr(result, fallback) {
+        return result.ok ? result.value : fallback;
+      }
+    };
+    exports.ok = exports.Result.ok;
+    exports.err = exports.Result.err;
+  }
+});
+exports.ToolMetadataSchema = void 0; exports.ToolCallRecordSchema = void 0; var toolResultBaseSchema; exports.ToolResultSuccessSchema = void 0; exports.ToolResultFailureSchema = void 0; exports.ToolResultSchema = void 0; exports.ToolResultFactory = void 0; exports.createToolCallRecord = void 0; exports.validateToolInput = void 0; exports.coerceToolDefinition = void 0; exports.isToolProvider = void 0; exports.normalizeToolEntries = void 0;
+var init_tool = __esm({
+  "src/base/tool.ts"() {
+    init_result();
+    exports.ToolMetadataSchema = zod.z.record(zod.z.string(), zod.z.unknown());
+    exports.ToolCallRecordSchema = zod.z.object({
+      id: zod.z.string().optional().default(() => crypto.randomUUID()),
+      toolName: zod.z.string(),
+      input: zod.z.unknown(),
+      output: zod.z.unknown().optional(),
+      success: zod.z.boolean().optional(),
+      error: zod.z.union([zod.z.string(), zod.z.object({ message: zod.z.string() }).passthrough()]).optional(),
+      startedAt: zod.z.number().default(() => Date.now()),
+      finishedAt: zod.z.number().optional(),
+      metadata: exports.ToolMetadataSchema.default({})
+    });
+    toolResultBaseSchema = zod.z.object({
+      toolName: zod.z.string(),
+      metadata: exports.ToolMetadataSchema.default({}),
+      startedAt: zod.z.number().optional(),
+      finishedAt: zod.z.number().optional()
+    });
+    exports.ToolResultSuccessSchema = toolResultBaseSchema.extend({
+      success: zod.z.literal(true),
+      output: zod.z.any()
+    }).refine((data) => data.output !== void 0, {
+      message: "output is required"
+    });
+    exports.ToolResultFailureSchema = toolResultBaseSchema.extend({
+      success: zod.z.literal(false),
+      error: zod.z.union([zod.z.string(), zod.z.instanceof(Error)])
+    });
+    exports.ToolResultSchema = zod.z.union([
+      exports.ToolResultSuccessSchema,
+      exports.ToolResultFailureSchema
+    ]);
+    exports.ToolResultFactory = {
+      success(toolName, output, init = {}) {
+        const result = {
+          success: true,
+          toolName,
+          output,
+          ...init.startedAt !== void 0 && { startedAt: init.startedAt },
+          finishedAt: init.finishedAt ?? Date.now(),
+          metadata: init.metadata ?? {}
+        };
+        exports.ToolResultSuccessSchema.parse(result);
+        return result;
+      },
+      failure(toolName, error, init = {}) {
+        const result = {
+          success: false,
+          toolName,
+          error,
+          ...init.startedAt !== void 0 && { startedAt: init.startedAt },
+          finishedAt: init.finishedAt ?? Date.now(),
+          metadata: init.metadata ?? {}
+        };
+        exports.ToolResultFailureSchema.parse(result);
+        return result;
+      },
+      isSuccess(result) {
+        return result.success;
+      },
+      isFailure(result) {
+        return !result.success;
+      }
+    };
+    exports.createToolCallRecord = (input) => exports.ToolCallRecordSchema.parse(input);
+    exports.validateToolInput = (schema, payload) => {
+      const parsed = schema.safeParse(payload);
+      if (!parsed.success) {
+        return exports.err(parsed.error);
+      }
+      return exports.ok(parsed.data);
+    };
+    exports.coerceToolDefinition = (definition) => {
+      if (!definition.name || definition.name.trim().length === 0) {
+        throw new Error("Tool definition requires a non-empty name");
+      }
+      if (!definition.metadata) {
+        definition.metadata = {};
+      }
+      return definition;
+    };
+    exports.isToolProvider = (value) => {
+      if (typeof value !== "object" || value === null) {
+        return false;
+      }
+      const candidate = value;
+      return typeof candidate.setup === "function" && typeof candidate.teardown === "function";
+    };
+    exports.normalizeToolEntries = (entries) => {
+      const tools = [];
+      const providers = [];
+      for (const entry of entries) {
+        if (exports.isToolProvider(entry)) {
+          providers.push(entry);
+        } else {
+          tools.push(entry);
+        }
+      }
+      return { tools, providers };
+    };
+  }
+});
+
+// src/base/context.ts
+var context_exports = {};
+__export(context_exports, {
+  AgentContext: () => exports.AgentContext,
+  ExecutionCycleSchema: () => exports.ExecutionCycleSchema,
+  UsageSchema: () => exports.UsageSchema
+});
+exports.UsageSchema = void 0; exports.ExecutionCycleSchema = void 0; exports.AgentContext = void 0;
+var init_context = __esm({
+  "src/base/context.ts"() {
+    init_tool();
+    exports.UsageSchema = zod.z.object({
+      requests: zod.z.number().int().nonnegative().default(0),
+      inputTokens: zod.z.number().int().nonnegative().default(0),
+      outputTokens: zod.z.number().int().nonnegative().default(0),
+      totalTokens: zod.z.number().int().nonnegative().default(0),
+      cost: zod.z.object({
+        generation: zod.z.number().nonnegative().default(0),
+        platform: zod.z.number().nonnegative().default(0),
+        total: zod.z.number().nonnegative().default(0)
+      }).default({ generation: 0, platform: 0, total: 0 })
+    });
+    exports.ExecutionCycleSchema = zod.z.object({
+      iteration: zod.z.number().int().nonnegative(),
+      thought: zod.z.unknown().nullable().optional(),
+      toolCalls: zod.z.array(exports.ToolCallRecordSchema).default([]),
+      results: zod.z.array(zod.z.unknown()).default([]),
+      timestamp: zod.z.number().default(() => Date.now())
+    });
+    exports.AgentContext = class {
+      agentName;
+      sessionId;
+      parentSpanId;
+      iteration = 0;
+      goal;
+      executionHistory = [];
+      toolCalls = [];
+      usage;
+      metadata;
+      startedAt;
+      updatedAt;
+      constructor(options) {
+        const now = Date.now();
+        this.agentName = options.agentName;
+        this.sessionId = options.sessionId ?? crypto.randomUUID();
+        this.parentSpanId = options.parentSpanId ?? null;
+        this.goal = options.goal;
+        this.metadata = { ...options.metadata ?? {} };
+        this.startedAt = now;
+        this.updatedAt = now;
+        this.usage = exports.UsageSchema.parse({});
+      }
+      updateUsage(delta) {
+        const next = exports.UsageSchema.parse(delta);
+        this.usage = {
+          requests: this.usage.requests + next.requests,
+          inputTokens: this.usage.inputTokens + next.inputTokens,
+          outputTokens: this.usage.outputTokens + next.outputTokens,
+          totalTokens: this.usage.totalTokens + next.totalTokens,
+          cost: {
+            generation: this.usage.cost.generation + next.cost.generation,
+            platform: this.usage.cost.platform + next.cost.platform,
+            total: this.usage.cost.total + next.cost.total
+          }
+        };
+        this.touch();
+      }
+      addCycle(cycle) {
+        const parsed = exports.ExecutionCycleSchema.parse(cycle);
+        this.executionHistory.push(parsed);
+        this.touch();
+        return parsed;
+      }
+      recordToolCall(call) {
+        const parsed = exports.ToolCallRecordSchema.parse(call);
+        this.toolCalls.push(parsed);
+        this.touch();
+        return parsed;
+      }
+      getContextSize() {
+        return this.usage.totalTokens;
+      }
+      getLastNCycles(count = 3) {
+        if (count <= 0) {
+          return [];
+        }
+        return this.executionHistory.slice(-count);
+      }
+      getLastIterationsSummary(count = 2) {
+        return this.getLastNCycles(count).map((cycle) => {
+          const thought = typeof cycle.thought === "object" && cycle.thought !== null ? { ...cycle.thought } : { text: cycle.thought };
+          return {
+            iteration: cycle.iteration,
+            thought,
+            toolCalls: cycle.toolCalls.map((call) => ({
+              toolName: call.toolName,
+              ...call.success !== void 0 && { success: call.success }
+            })),
+            results: [...cycle.results]
+          };
+        });
+      }
+      setMetadata(key, value) {
+        this.metadata[key] = value;
+        this.touch();
+      }
+      clearHistory() {
+        this.executionHistory.length = 0;
+        this.toolCalls.length = 0;
+        this.touch();
+      }
+      snapshot() {
+        return {
+          agentName: this.agentName,
+          sessionId: this.sessionId,
+          parentSpanId: this.parentSpanId,
+          iteration: this.iteration,
+          goal: this.goal,
+          executionHistory: [...this.executionHistory],
+          usage: { ...this.usage },
+          toolCalls: [...this.toolCalls],
+          metadata: { ...this.metadata },
+          startedAt: this.startedAt,
+          updatedAt: this.updatedAt
+        };
+      }
+      touch() {
+        this.updatedAt = Date.now();
+      }
+    };
+  }
+});
+
+// src/utils/logger.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  LogLevel2[LogLevel2["SILENT"] = 4] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
+var formatMeta = (meta) => {
+  if (!meta) {
+    return "";
+  }
+  try {
+    return ` ${JSON.stringify(meta)}`;
+  } catch {
+    return " [unserializable meta]";
+  }
+};
+var writeToStdout = (level, message, meta) => {
+  const suffix = formatMeta(meta);
+  process.stdout.write(`[${level}] ${message}${suffix}
+`);
+};
+var ConsoleLogger = class {
+  level;
+  constructor(level = 1 /* INFO */) {
+    this.level = level;
+  }
+  debug(message, meta) {
+    if (this.level <= 0 /* DEBUG */) {
+      writeToStdout("DEBUG", message, meta);
+    }
+  }
+  info(message, meta) {
+    if (this.level <= 1 /* INFO */) {
+      writeToStdout("INFO", message, meta);
+    }
+  }
+  warn(message, meta) {
+    if (this.level <= 2 /* WARN */) {
+      console.warn(`[WARN] ${message}`, meta ? meta : "");
+    }
+  }
+  error(message, error, meta) {
+    if (this.level <= 3 /* ERROR */) {
+      if (error) {
+        console.error(`[ERROR] ${message}`, error, meta ? meta : "");
+      } else {
+        console.error(`[ERROR] ${message}`, meta ? meta : "");
+      }
+    }
+  }
+  getLevel() {
+    return this.level;
+  }
+  setLevel(level) {
+    this.level = level;
+  }
+};
+var SilentLogger = class {
+  debug(message, meta) {
+  }
+  info(message, meta) {
+  }
+  warn(message, meta) {
+  }
+  error(message, error, meta) {
+  }
+  getLevel() {
+    return 4 /* SILENT */;
+  }
+  setLevel(level) {
+  }
+};
+var defaultLogger = new ConsoleLogger(2 /* WARN */);
+function getDefaultLogger() {
+  return defaultLogger;
+}
+function setDefaultLogger(logger) {
+  defaultLogger = logger;
+}
+
+// src/base/hooks.ts
+var HookEvents = {
+  AgentStart: "agent:start",
+  AgentEnd: "agent:end",
+  LoopStart: "loop:start",
+  LoopEnd: "loop:end",
+  LlmCall: "llm:call",
+  LlmResponse: "llm:response",
+  ThinkEnd: "think:end",
+  BeforeTool: "tool:before",
+  AfterTool: "tool:after",
+  ToolError: "tool:error",
+  MemoryRead: "memory:read",
+  MemoryWrite: "memory:write",
+  MemoryError: "memory:error"
+};
+var HookManager = class {
+  registry = /* @__PURE__ */ new Map();
+  logger;
+  constructor(logger) {
+    this.logger = logger ?? getDefaultLogger();
+  }
+  on(event, handler) {
+    const existing = this.registry.get(event) ?? /* @__PURE__ */ new Set();
+    existing.add(handler);
+    this.registry.set(event, existing);
+    return () => existing.delete(handler);
+  }
+  once(event, handler) {
+    const disposable = async (payload) => {
+      await handler(payload);
+      this.off(event, disposable);
+    };
+    return this.on(event, disposable);
+  }
+  off(event, handler) {
+    const listeners = this.registry.get(event);
+    if (!listeners) {
+      return;
+    }
+    listeners.delete(handler);
+    if (listeners.size === 0) {
+      this.registry.delete(event);
+    }
+  }
+  clear() {
+    this.registry.clear();
+  }
+  listenerCount(event) {
+    if (event) {
+      return this.registry.get(event)?.size ?? 0;
+    }
+    let total = 0;
+    for (const listeners of this.registry.values()) {
+      total += listeners.size;
+    }
+    return total;
+  }
+  async emit(event, payload) {
+    const listeners = Array.from(
+      this.registry.get(event) ?? /* @__PURE__ */ new Set()
+    );
+    if (listeners.length === 0) {
+      return;
+    }
+    for (const [index, listener] of listeners.entries()) {
+      try {
+        await Promise.resolve(listener(payload));
+      } catch (error) {
+        this.logger.warn(`Hook handler failed for event "${event}"`, {
+          event,
+          handlerIndex: index,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  }
+  registerMany(registrations) {
+    const cleanups = registrations.map(
+      ({ event, handler }) => this.on(event, handler)
+    );
+    return () => cleanups.forEach((dispose) => dispose());
+  }
+};
+var createHookManager = (logger) => new HookManager(logger);
+
+// src/base/agent.ts
+init_tool();
+var MemoryEntryMetadataSchema = zod.z.object({
+  createdAt: zod.z.number(),
+  updatedAt: zod.z.number(),
+  accessCount: zod.z.number().default(0)
+});
+var MemoryEntrySchema = zod.z.object({
+  key: zod.z.string(),
+  description: zod.z.string(),
+  value: zod.z.unknown(),
+  metadata: MemoryEntryMetadataSchema
+});
+var InMemoryStore = class {
+  store = /* @__PURE__ */ new Map();
+  /**
+   * Check if memory has any entries
+   */
+  async hasEntries() {
+    return this.store.size > 0;
+  }
+  /**
+   * List memory catalog (summaries without values) for LLM consumption
+   */
+  async listEntries() {
+    const catalog = [];
+    for (const entry of this.store.values()) {
+      catalog.push({
+        key: entry.key,
+        description: entry.description,
+        metadata: { ...entry.metadata }
+      });
+    }
+    return catalog;
+  }
+  /**
+   * Read values from memory by keys
+   */
+  async read(keys) {
+    const keysToRead = keys ?? Array.from(this.store.keys());
+    const snapshot = {};
+    for (const key of keysToRead) {
+      const entry = this.store.get(key);
+      if (entry) {
+        entry.metadata.accessCount += 1;
+        entry.metadata.updatedAt = Date.now();
+        snapshot[key] = entry.value;
+      }
+    }
+    return snapshot;
+  }
+  /**
+   * Write a value to memory with description
+   */
+  async write(key, value, description, metadata) {
+    const now = Date.now();
+    const existing = this.store.get(key);
+    const entry = {
+      key,
+      description: description ?? existing?.description ?? key,
+      value,
+      metadata: existing ? {
+        createdAt: existing.metadata.createdAt,
+        updatedAt: now,
+        accessCount: existing.metadata.accessCount,
+        ...metadata ?? {}
+      } : {
+        createdAt: now,
+        updatedAt: now,
+        accessCount: 0,
+        ...metadata ?? {}
+      }
+    };
+    this.store.set(key, entry);
+    return { ...entry, metadata: { ...entry.metadata } };
+  }
+  /**
+   * Delete a memory entry by key
+   */
+  async delete(key) {
+    return this.store.delete(key);
+  }
+  /**
+   * Clear all memory entries
+   */
+  async clear() {
+    const count = this.store.size;
+    this.store.clear();
+    return count;
+  }
+  /**
+   * Get the current size of the memory store
+   *
+   * @returns Number of entries in memory
+   */
+  get size() {
+    return this.store.size;
+  }
+};
+var createInMemoryStore = () => new InMemoryStore();
+
+// src/base/agent.ts
+var DEFAULT_MODEL = "gcp/gemini-flash-latest";
+var BaseAgent = class {
+  /**
+   * Agent name
+   */
+  name;
+  /**
+   * Agent description
+   */
+  description;
+  /**
+   * Agent instructions
+   */
+  instructions;
+  /**
+   * Maximum iterations for the agent loop
+   */
+  maxIterations;
+  /**
+   * Model identifier
+   */
+  model;
+  /**
+   * Input validation schema
+   */
+  inputSchema;
+  /**
+   * Output validation schema
+   */
+  outputSchema;
+  /**
+   * Whether memory is enabled
+   */
+  enableMemory;
+  /**
+   * Memory instance for persistent storage (null if disabled or initialization failed)
+   */
+  memory;
+  /**
+   * Agent metadata
+   */
+  metadata;
+  /**
+   * Hook manager for lifecycle events
+   */
+  hooks;
+  /**
+   * Registry of available tools
+   */
+  tools;
+  /**
+   * Baseline tools registered directly on the agent
+   */
+  baseTools;
+  /**
+   * Registered tool providers that can expand into tools at runtime
+   */
+  toolProviders;
+  /**
+   * Active tools supplied by providers for the current execution
+   */
+  providerToolRegistry;
+  /**
+   * Opper client configuration
+   */
+  opperConfig;
+  constructor(config) {
+    this.name = config.name;
+    this.description = config.description;
+    this.instructions = config.instructions;
+    this.maxIterations = config.maxIterations ?? 25;
+    this.model = config.model ?? DEFAULT_MODEL;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this.enableMemory = config.enableMemory ?? false;
+    this.metadata = { ...config.metadata ?? {} };
+    this.hooks = new HookManager();
+    this.tools = /* @__PURE__ */ new Map();
+    this.baseTools = /* @__PURE__ */ new Map();
+    this.toolProviders = /* @__PURE__ */ new Set();
+    this.providerToolRegistry = /* @__PURE__ */ new Map();
+    this.opperConfig = {
+      apiKey: config.opperConfig?.apiKey ?? process.env["OPPER_API_KEY"],
+      baseUrl: config.opperConfig?.baseUrl,
+      ...config.opperConfig
+    };
+    this.memory = this.initializeMemory(config);
+    if (config.tools) {
+      this.registerTools(config.tools);
+    }
+  }
+  /**
+   * Initialize memory subsystem with graceful degradation
+   *
+   * @param config - Agent configuration
+   * @returns Memory instance or null
+   */
+  initializeMemory(config) {
+    if (!this.enableMemory && !config.memory) {
+      return null;
+    }
+    try {
+      return config.memory ?? new InMemoryStore();
+    } catch (error) {
+      console.warn(
+        `[${this.name}] Memory initialization failed, continuing without memory:`,
+        error
+      );
+      return null;
+    }
+  }
+  /**
+   * Main entry point for agent execution.
+   * Orchestrates lifecycle: context initialization, hook triggering, loop execution, teardown.
+   *
+   * @param input - Input to process
+   * @param parentSpanId - Optional parent span ID for tracing
+   * @returns Processed output
+   */
+  async process(input, parentSpanId) {
+    const validatedInput = this.inputSchema ? this.inputSchema.parse(input) : input;
+    const context = await this.initializeContext(validatedInput, parentSpanId);
+    try {
+      await this.activateToolProviders();
+      await this.triggerHook(HookEvents.AgentStart, { context });
+      const result = await this.runLoop(validatedInput, context);
+      const validatedOutput = this.outputSchema ? this.outputSchema.parse(result) : result;
+      await this.triggerHook(HookEvents.AgentEnd, {
+        context,
+        result: validatedOutput
+      });
+      return validatedOutput;
+    } catch (error) {
+      await this.triggerHook(HookEvents.AgentEnd, {
+        context,
+        error
+      });
+      throw error;
+    } finally {
+      await this.deactivateToolProviders();
+      await this.teardownContext(context);
+    }
+  }
+  /**
+   * Initialize agent context before execution.
+   * Can be overridden for custom initialization logic.
+   *
+   * @param input - Agent input
+   * @param parentSpanId - Optional parent span ID
+   * @returns Initialized context
+   */
+  async initializeContext(input, parentSpanId) {
+    const context = new (await Promise.resolve().then(() => (init_context(), context_exports))).AgentContext({
+      agentName: this.name,
+      parentSpanId: parentSpanId ?? null,
+      goal: input,
+      metadata: { ...this.metadata }
+    });
+    return context;
+  }
+  /**
+   * Teardown agent context after execution.
+   * Can be overridden for custom cleanup logic.
+   *
+   * @param context - Agent context to teardown
+   */
+  async teardownContext(context) {
+  }
+  /**
+   * Add a tool to the agent's tool registry.
+   *
+   * @param tool - Tool to add
+   */
+  addTool(tool2) {
+    const coerced = exports.coerceToolDefinition(tool2);
+    if (this.tools.has(coerced.name)) {
+      console.warn(
+        `[${this.name}] Tool "${coerced.name}" already registered. Overwriting existing definition.`
+      );
+    }
+    const typedTool = coerced;
+    this.baseTools.set(coerced.name, typedTool);
+    this.tools.set(coerced.name, typedTool);
+  }
+  /**
+   * Remove a tool from the agent's tool registry.
+   *
+   * @param toolName - Name of tool to remove
+   * @returns True if tool was removed, false if not found
+   */
+  removeTool(toolName) {
+    this.baseTools.delete(toolName);
+    return this.tools.delete(toolName);
+  }
+  /**
+   * Get a tool by name.
+   *
+   * @param toolName - Name of tool to retrieve
+   * @returns Tool instance or undefined
+   */
+  getTool(toolName) {
+    return this.tools.get(toolName);
+  }
+  /**
+   * Get all registered tools.
+   *
+   * @returns Array of all tools
+   */
+  getTools() {
+    return Array.from(this.tools.values());
+  }
+  /**
+   * Register a tool provider that expands into tools at runtime.
+   *
+   * @param provider - Tool provider to add
+   */
+  addToolProvider(provider) {
+    this.toolProviders.add(provider);
+  }
+  /**
+   * Convert this agent into a tool that can be used by other agents.
+   *
+   * @param toolName - Optional custom name for the tool (defaults to agent name)
+   * @param toolDescription - Optional custom description (defaults to agent description)
+   * @returns Tool wrapping this agent
+   */
+  asTool(toolName, toolDescription) {
+    const tool2 = {
+      name: toolName ?? this.name,
+      description: toolDescription ?? this.description ?? `Agent: ${this.name}`,
+      ...this.inputSchema && { schema: this.inputSchema },
+      metadata: {
+        isAgent: true,
+        agentName: this.name
+      },
+      execute: async (input, executionContext) => {
+        try {
+          const parentSpanId = executionContext.spanId ?? executionContext.agentContext.parentSpanId ?? void 0;
+          const result = await this.process(input, parentSpanId);
+          return exports.ToolResultFactory.success(tool2.name, result);
+        } catch (error) {
+          return exports.ToolResultFactory.failure(
+            tool2.name,
+            error instanceof Error ? error : new Error(String(error))
+          );
+        }
+      }
+    };
+    return tool2;
+  }
+  /**
+   * Register a hook handler for a specific event.
+   *
+   * @param event - Hook event name
+   * @param handler - Hook handler function
+   * @returns Cleanup function to unregister the hook
+   */
+  registerHook(event, handler) {
+    return this.hooks.on(event, handler);
+  }
+  /**
+   * Trigger a hook event with a payload.
+   * Swallows errors to prevent hook failures from breaking agent execution.
+   *
+   * @param event - Hook event name
+   * @param payload - Event payload
+   */
+  async triggerHook(event, payload) {
+    try {
+      await this.hooks.emit(event, payload);
+    } catch (error) {
+      console.warn(`Hook error for event ${event}:`, error);
+    }
+  }
+  /**
+   * Execute a tool with proper context, hooks, and error handling.
+   *
+   * @param toolName - Name of tool to execute
+   * @param input - Tool input
+   * @param context - Agent context
+   * @param options - Optional execution options (signal, span ID)
+   * @returns Tool execution result
+   */
+  async executeTool(toolName, input, context, options) {
+    const tool2 = this.tools.get(toolName);
+    if (!tool2) {
+      const failure = exports.ToolResultFactory.failure(
+        toolName,
+        new Error(`Tool "${toolName}" not found in agent registry`)
+      );
+      const timestamp = Date.now();
+      context.recordToolCall({
+        toolName,
+        input,
+        success: false,
+        error: failure.error instanceof Error ? failure.error.message : String(failure.error),
+        startedAt: timestamp,
+        finishedAt: timestamp,
+        metadata: {}
+      });
+      await this.triggerHook(HookEvents.ToolError, {
+        context,
+        toolName,
+        error: failure.error
+      });
+      return failure;
+    }
+    const executionContext = {
+      agentContext: context,
+      ...options?.signal && { signal: options.signal },
+      ...options?.spanId && { spanId: options.spanId },
+      metadata: {}
+    };
+    const startedAt = Date.now();
+    try {
+      await this.triggerHook(HookEvents.BeforeTool, {
+        context,
+        tool: tool2,
+        input
+      });
+      const result = await tool2.execute(input, executionContext);
+      const finishedAt = Date.now();
+      const record = context.recordToolCall({
+        toolName: tool2.name,
+        input,
+        ...result.success && { output: result.output },
+        success: result.success,
+        ...!result.success && {
+          error: result.error instanceof Error ? result.error.message : String(result.error)
+        },
+        startedAt,
+        finishedAt,
+        metadata: {}
+      });
+      await this.triggerHook(HookEvents.AfterTool, {
+        context,
+        tool: tool2,
+        result,
+        record
+      });
+      return result;
+    } catch (error) {
+      const failure = exports.ToolResultFactory.failure(
+        toolName,
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          startedAt,
+          finishedAt: Date.now()
+        }
+      );
+      const record = context.recordToolCall({
+        toolName: tool2.name,
+        input,
+        success: false,
+        error: failure.error instanceof Error ? failure.error.message : String(failure.error),
+        startedAt,
+        finishedAt: failure.finishedAt,
+        metadata: {}
+      });
+      await this.triggerHook(HookEvents.ToolError, {
+        context,
+        tool: tool2,
+        toolName: tool2.name,
+        error
+      });
+      await this.triggerHook(HookEvents.AfterTool, {
+        context,
+        tool: tool2,
+        result: failure,
+        record
+      });
+      return failure;
+    }
+  }
+  registerTools(entries) {
+    const { tools, providers } = exports.normalizeToolEntries(entries);
+    for (const tool2 of tools) {
+      this.addTool(tool2);
+    }
+    for (const provider of providers) {
+      this.toolProviders.add(provider);
+    }
+  }
+  async activateToolProviders() {
+    const activationPromises = Array.from(this.toolProviders).filter((provider) => !this.providerToolRegistry.has(provider)).map(async (provider) => {
+      try {
+        const baseAgent = this;
+        const providedTools = await provider.setup(baseAgent) ?? [];
+        const normalizedTools = providedTools.map(
+          (tool2) => exports.coerceToolDefinition(tool2)
+        );
+        this.providerToolRegistry.set(provider, normalizedTools);
+        for (const tool2 of normalizedTools) {
+          if (this.tools.has(tool2.name)) {
+            console.warn(
+              `[${this.name}] Tool "${tool2.name}" from provider overwrites existing tool.`
+            );
+          }
+          this.tools.set(tool2.name, tool2);
+        }
+      } catch (error) {
+        console.warn(
+          `[${this.name}] Failed to activate tool provider:`,
+          error
+        );
+      }
+    });
+    await Promise.allSettled(activationPromises);
+  }
+  async deactivateToolProviders() {
+    const teardownEntries = Array.from(this.providerToolRegistry.entries());
+    this.providerToolRegistry.clear();
+    const teardownPromises = teardownEntries.map(async ([provider, tools]) => {
+      for (const tool2 of tools) {
+        this.tools.delete(tool2.name);
+        const baseTool = this.baseTools.get(tool2.name);
+        if (baseTool) {
+          this.tools.set(tool2.name, baseTool);
+        }
+      }
+      try {
+        await provider.teardown();
+      } catch (error) {
+        console.warn(
+          `[${this.name}] Error while tearing down tool provider:`,
+          error
+        );
+      }
+    });
+    await Promise.allSettled(teardownPromises);
+  }
+};
+
+// src/index.ts
+init_context();
+init_result();
+init_tool();
+var ThoughtSchema = zod.z.object({
+  /**
+   * The reasoning or internal monologue of the agent
+   */
+  reasoning: zod.z.string(),
+  /**
+   * Planned next action(s)
+   */
+  plan: zod.z.string().optional(),
+  /**
+   * Confidence level (0-1)
+   */
+  confidence: zod.z.number().min(0).max(1).optional(),
+  /**
+   * Additional metadata
+   */
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+});
+var ToolCallSchema = zod.z.object({
+  /**
+   * Unique identifier for this tool call
+   */
+  id: zod.z.string(),
+  /**
+   * Name of the tool to invoke
+   */
+  toolName: zod.z.string(),
+  /**
+   * Arguments to pass to the tool
+   */
+  arguments: zod.z.unknown()
+});
+var MemoryUpdateSchema = zod.z.object({
+  /**
+   * Value to store for this key
+   */
+  value: zod.z.unknown(),
+  /**
+   * Optional description of the memory entry
+   */
+  description: zod.z.string().optional(),
+  /**
+   * Optional metadata for the memory entry
+   */
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+});
+var AgentDecisionSchema = zod.z.object({
+  /**
+   * Agent's internal reasoning
+   */
+  reasoning: zod.z.string(),
+  /**
+   * Tool calls to execute (if any)
+   * Empty array signals task completion
+   */
+  toolCalls: zod.z.array(ToolCallSchema).default([]),
+  /**
+   * Memory keys to read during this iteration
+   */
+  memoryReads: zod.z.array(zod.z.string()).default([]),
+  /**
+   * Memory entries to write/update (key -> payload)
+   */
+  memoryUpdates: zod.z.record(MemoryUpdateSchema).default({})
+});
+var ToolExecutionSummarySchema = zod.z.object({
+  /**
+   * Tool name
+   */
+  toolName: zod.z.string(),
+  /**
+   * Whether execution succeeded
+   */
+  success: zod.z.boolean(),
+  /**
+   * Output if successful
+   */
+  output: zod.z.unknown().optional(),
+  /**
+   * Error message if failed
+   */
+  error: zod.z.string().optional()
+});
+var isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isZodSchema = (value) => typeof value === "object" && value !== null && "_def" in value && typeof value.parse === "function";
+var readTokenCount = (usage, key) => {
+  if (!usage) {
+    return 0;
+  }
+  const value = usage[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+};
+var extractUsage = (response) => {
+  const usageRecord = isPlainRecord(response.usage) ? response.usage : void 0;
+  return {
+    inputTokens: readTokenCount(usageRecord, "input_tokens"),
+    outputTokens: readTokenCount(usageRecord, "output_tokens")
+  };
+};
+var extractCost = (response) => {
+  const costRecord = isPlainRecord(response.cost) ? response.cost : void 0;
+  return {
+    generation: readTokenCount(costRecord, "generation"),
+    platform: readTokenCount(costRecord, "platform"),
+    total: readTokenCount(costRecord, "total")
+  };
+};
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  initialDelayMs: 1e3,
+  backoffMultiplier: 2,
+  maxDelayMs: 1e4
+};
+var OpperClient = class {
+  client;
+  logger;
+  retryConfig;
+  constructor(apiKey, options = {}) {
+    this.client = new opperai.Opper({
+      httpBearer: apiKey ?? process.env["OPPER_HTTP_BEARER"] ?? ""
+    });
+    this.logger = options.logger ?? getDefaultLogger();
+    this.retryConfig = {
+      ...DEFAULT_RETRY_CONFIG,
+      ...options.retryConfig ?? {}
+    };
+  }
+  /**
+   * Make a call to Opper with retry logic
+   */
+  async call(options) {
+    return this.withRetry(async () => {
+      const inputSchema = this.toJsonSchema(options.inputSchema);
+      const outputSchema = this.toJsonSchema(options.outputSchema);
+      const response = await this.client.call({
+        name: options.name,
+        instructions: options.instructions,
+        input: options.input,
+        ...inputSchema && { inputSchema },
+        ...outputSchema && { outputSchema },
+        ...options.model && { model: options.model },
+        ...options.parentSpanId && { parentSpanId: options.parentSpanId }
+      });
+      const usagePayload = extractUsage(response);
+      const costPayload = extractCost(response);
+      const usage = {
+        inputTokens: usagePayload.inputTokens,
+        outputTokens: usagePayload.outputTokens,
+        totalTokens: usagePayload.inputTokens + usagePayload.outputTokens,
+        cost: costPayload
+      };
+      const result = {
+        ...response.jsonPayload !== void 0 && response.jsonPayload !== null ? { jsonPayload: response.jsonPayload } : {},
+        ...response.message !== void 0 && response.message !== null ? { message: response.message } : {},
+        spanId: response.spanId,
+        usage
+      };
+      return result;
+    }, options.name);
+  }
+  /**
+   * Create a span for tracing
+   */
+  async createSpan(options) {
+    return this.withRetry(async () => {
+      const span = await this.client.spans.create({
+        name: options.name,
+        ...options.input !== void 0 && { input: options.input },
+        ...options.parentSpanId && { parentId: options.parentSpanId }
+      });
+      return {
+        id: span.id,
+        name: options.name,
+        input: options.input
+      };
+    }, `create-span:${options.name}`);
+  }
+  /**
+   * Update a span with output or error
+   */
+  async updateSpan(spanId, output, options) {
+    return this.withRetry(async () => {
+      const serializedOutput = output !== void 0 && output !== null ? typeof output === "object" ? JSON.stringify(output) : String(output) : void 0;
+      await this.client.spans.update(spanId, {
+        ...serializedOutput !== void 0 && { output: serializedOutput },
+        ...options?.error && { error: options.error }
+      });
+    }, `update-span:${spanId}`);
+  }
+  /**
+   * Get the underlying Opper client
+   */
+  getClient() {
+    return this.client;
+  }
+  /**
+   * Execute a function with retry logic and exponential backoff
+   */
+  async withRetry(fn, operationName) {
+    let lastError;
+    let delay = this.retryConfig.initialDelayMs;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt === this.retryConfig.maxRetries) {
+          break;
+        }
+        if (!this.isRetryableError(error)) {
+          throw lastError;
+        }
+        this.logger.warn(
+          `Opper operation "${operationName}" failed (attempt ${attempt + 1}/${this.retryConfig.maxRetries + 1}), retrying in ${delay}ms`,
+          {
+            error: lastError.message,
+            attempt: attempt + 1,
+            delayMs: delay
+          }
+        );
+        await this.sleep(delay);
+        delay = Math.min(
+          delay * this.retryConfig.backoffMultiplier,
+          this.retryConfig.maxDelayMs
+        );
+      }
+    }
+    this.logger.error(
+      `Opper operation "${operationName}" failed after ${this.retryConfig.maxRetries + 1} attempts`,
+      lastError
+    );
+    throw lastError;
+  }
+  /**
+   * Check if an error is retryable
+   */
+  isRetryableError(error) {
+    if (!(error instanceof Error)) {
+      return false;
+    }
+    const errorMessage = error.message.toLowerCase();
+    const retryablePatterns = [
+      "network",
+      "timeout",
+      "econnreset",
+      "enotfound",
+      "econnrefused",
+      "etimedout",
+      "rate limit",
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ];
+    return retryablePatterns.some((pattern) => errorMessage.includes(pattern));
+  }
+  /**
+   * Convert Zod schema to JSON Schema
+   */
+  toJsonSchema(schema) {
+    if (!schema) {
+      return void 0;
+    }
+    if (isZodSchema(schema)) {
+      try {
+        return zodToJsonSchema.zodToJsonSchema(schema);
+      } catch (error) {
+        this.logger.warn("Failed to convert Zod schema to JSON Schema", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return void 0;
+      }
+    }
+    if (isPlainRecord(schema)) {
+      return schema;
+    }
+    this.logger.warn("Unsupported schema type provided to OpperClient", {
+      schemaType: typeof schema
+    });
+    return void 0;
+  }
+  /**
+   * Sleep for specified milliseconds
+   */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+function createOpperClient(apiKey, options) {
+  return new OpperClient(apiKey, options);
+}
+var SchemaValidationError = class extends Error {
+  issues;
+  constructor(message, issues) {
+    super(message);
+    this.name = "SchemaValidationError";
+    this.issues = issues;
+  }
+};
+var validateSchema = (schema, value, options = {}) => {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    throw new SchemaValidationError(
+      options.message ?? "Schema validation failed",
+      result.error.issues
+    );
+  }
+  return result.data;
+};
+var isSchemaValid = (schema, value) => {
+  return schema.safeParse(value).success;
+};
+var schemaToJson = (schema, options = {}) => {
+  return zodToJsonSchema.zodToJsonSchema(schema, options);
+};
+var getSchemaDefault = (schema) => {
+  const result = schema.safeParse(void 0);
+  return result.success ? result.data : void 0;
+};
+var mergeSchemaDefaults = (schema, value) => {
+  const defaults = getSchemaDefault(schema);
+  if (defaults && typeof defaults === "object") {
+    return validateSchema(schema, { ...defaults, ...value });
+  }
+  return validateSchema(schema, value);
+};
+
+// src/core/agent.ts
+var isToolSuccessResult = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return candidate.success === true && typeof candidate.toolName === "string" && "output" in candidate;
+};
+var Agent = class extends BaseAgent {
+  opperClient;
+  logger;
+  verbose;
+  constructor(config) {
+    super(config);
+    this.logger = config.logger ?? getDefaultLogger();
+    this.verbose = config.verbose ?? false;
+    if (this.verbose) {
+      try {
+        this.logger.setLevel?.(1 /* INFO */);
+      } catch {
+      }
+    }
+    this.opperClient = config.opperClient ?? new OpperClient(this.opperConfig.apiKey, {
+      logger: this.logger
+    });
+  }
+  /**
+   * Serialize input for passing to LLM or spans
+   */
+  serializeInput(input) {
+    if (typeof input === "string") {
+      return input;
+    }
+    if (typeof input === "object" && input !== null) {
+      return JSON.stringify(input);
+    }
+    return String(input);
+  }
+  /**
+   * Main agent loop: think → tool execution → memory handling → repeat until complete
+   */
+  async runLoop(input, context) {
+    this.log("Starting agent loop", {
+      goal: input,
+      maxIterations: this.maxIterations,
+      tools: Array.from(this.tools.keys())
+    });
+    const parentSpan = await this.opperClient.createSpan({
+      name: `${this.name}_execution`,
+      input: this.serializeInput(input),
+      ...context.parentSpanId ? { parentSpanId: context.parentSpanId } : {}
+    });
+    context.parentSpanId = parentSpan.id;
+    try {
+      while (context.iteration < this.maxIterations) {
+        const currentIteration = context.iteration + 1;
+        this.log(`Iteration ${currentIteration}/${this.maxIterations}`, {
+          toolsAvailable: this.tools.size
+        });
+        await this.triggerHook(HookEvents.LoopStart, { context });
+        let loopComplete = false;
+        try {
+          const { decision, spanId: thinkSpanId } = await this.think(
+            input,
+            context
+          );
+          const memoryResults = await this.handleMemoryActions(
+            decision,
+            context,
+            thinkSpanId
+          );
+          const toolCallStartIndex = context.toolCalls.length;
+          const toolResults = await this.executeToolCalls(
+            decision,
+            context,
+            thinkSpanId
+          );
+          const combinedResults = [...memoryResults, ...toolResults];
+          const newToolCalls = context.toolCalls.slice(toolCallStartIndex);
+          context.addCycle({
+            iteration: currentIteration,
+            thought: {
+              reasoning: decision.reasoning,
+              memoryReads: decision.memoryReads,
+              memoryUpdates: decision.memoryUpdates
+            },
+            toolCalls: newToolCalls,
+            results: combinedResults,
+            timestamp: Date.now()
+          });
+          context.iteration = currentIteration;
+          const hasToolCalls = decision.toolCalls.length > 0;
+          const hasMemoryReads = this.enableMemory && (decision.memoryReads?.length ?? 0) > 0;
+          loopComplete = !hasToolCalls && !hasMemoryReads;
+        } finally {
+          await this.triggerHook(HookEvents.LoopEnd, { context });
+        }
+        if (loopComplete) {
+          this.log("Loop complete, generating final result", {
+            iteration: context.iteration + 1
+          });
+          break;
+        }
+      }
+      if (context.iteration >= this.maxIterations) {
+        throw new Error(
+          `Agent exceeded maximum iterations (${this.maxIterations}) without completing the task`
+        );
+      }
+      const result = await this.generateFinalResult(input, context);
+      await this.opperClient.updateSpan(parentSpan.id, result);
+      return result;
+    } catch (error) {
+      await this.opperClient.updateSpan(parentSpan.id, void 0, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      throw error;
+    }
+  }
+  /**
+   * Think step: Call LLM to decide next action
+   */
+  async think(input, context) {
+    const spanName = "think";
+    this.log("Think step", { iteration: context.iteration });
+    await this.triggerHook(HookEvents.LlmCall, { context, callType: "think" });
+    try {
+      const instructions = this.buildThinkInstructions();
+      const thinkContext = await this.buildThinkContext(input, context);
+      const response = await this.opperClient.call({
+        name: spanName,
+        instructions,
+        input: thinkContext,
+        outputSchema: AgentDecisionSchema,
+        model: this.model,
+        ...context.parentSpanId && { parentSpanId: context.parentSpanId }
+      });
+      context.updateUsage({
+        requests: 1,
+        inputTokens: response.usage.inputTokens,
+        outputTokens: response.usage.outputTokens,
+        totalTokens: response.usage.totalTokens,
+        cost: response.usage.cost
+      });
+      const decision = AgentDecisionSchema.parse(response.jsonPayload);
+      await this.triggerHook(HookEvents.LlmResponse, {
+        context,
+        callType: "think",
+        response
+      });
+      await this.triggerHook(HookEvents.ThinkEnd, {
+        context,
+        thought: { reasoning: decision.reasoning }
+      });
+      this.log("Think result", {
+        reasoning: decision.reasoning,
+        toolCalls: decision.toolCalls.length,
+        memoryReads: decision.memoryReads?.length ?? 0,
+        memoryWrites: Object.keys(decision.memoryUpdates ?? {}).length
+      });
+      return { decision, spanId: response.spanId };
+    } catch (error) {
+      this.logger.error("Think step failed", error);
+      throw new Error(
+        `Think step failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Build static instructions for the think step
+   */
+  buildThinkInstructions() {
+    let instructions = `You are in a Think-Act reasoning loop.
+
+YOUR TASK:
+1. Analyze the current situation
+2. Decide if the goal is complete or more actions are needed
+3. If more actions needed: specify tools to call
+4. If goal complete: return empty tool_calls list
+
+IMPORTANT:
+- Return empty toolCalls array when task is COMPLETE
+- Only use available tools
+- Provide clear reasoning for each decision`;
+    if (this.enableMemory) {
+      instructions += `
+
+MEMORY SYSTEM:
+You have access to a persistent memory system that works across iterations.
+
+Memory Operations:
+1. READ: Add keys to memoryReads when you need to load existing entries
+2. WRITE: Populate memoryUpdates with key-value pairs (with optional description/metadata)
+   Example: memoryUpdates = { "favorite_color": { "value": "blue", "description": "User likes blue" } }
+
+When to use memory:
+- Save important calculations, decisions, or user preferences
+- Load memory when you need information from earlier in the conversation
+- Use descriptive keys like "budget_total", "user_favorite_city", etc.
+- When a key appears in memory_catalog and you need its value, add it to memoryReads before continuing
+
+The memory you write persists across all process() calls on this agent.`;
+    }
+    return instructions;
+  }
+  /**
+   * Build dynamic context for the think step
+   */
+  async buildThinkContext(input, context) {
+    const availableTools = Array.from(this.tools.values()).map((tool2) => ({
+      name: tool2.name,
+      description: tool2.description || "",
+      // Convert Zod schema to JSON Schema for LLM consumption
+      parameters: tool2.schema ? schemaToJson(tool2.schema) : {}
+    }));
+    const executionHistory = context.getLastNCycles(3).map((cycle) => {
+      const thought = typeof cycle.thought === "object" && cycle.thought !== null ? cycle.thought["reasoning"] || "" : String(cycle.thought || "");
+      const results = Array.isArray(cycle.results) ? cycle.results.map((r) => {
+        const result = r;
+        let actualOutput = result.output;
+        if (result.success && isToolSuccessResult(actualOutput)) {
+          actualOutput = actualOutput.output;
+        }
+        return {
+          tool: result.toolName,
+          success: result.success,
+          // Serialize result properly - use JSON for objects, String for primitives
+          result: result.success ? typeof actualOutput === "object" ? JSON.stringify(actualOutput) : String(actualOutput) : void 0,
+          error: !result.success ? result.error : void 0
+        };
+      }) : [];
+      return {
+        iteration: cycle.iteration,
+        thought,
+        results
+      };
+    });
+    let memoryCatalog = null;
+    if (this.enableMemory && this.memory && await this.memory.hasEntries()) {
+      memoryCatalog = await this.memory.listEntries();
+    }
+    const loadedMemory = context.metadata["current_memory"] ?? null;
+    return {
+      goal: this.serializeInput(input),
+      agent_description: this.description || "",
+      instructions: this.instructions || "No specific instructions.",
+      available_tools: availableTools,
+      execution_history: executionHistory,
+      current_iteration: context.iteration + 1,
+      max_iterations: this.maxIterations,
+      memory_catalog: memoryCatalog,
+      loaded_memory: loadedMemory
+    };
+  }
+  /**
+   * Execute all tool calls from a decision
+   */
+  async executeToolCalls(decision, context, parentSpanId) {
+    if (decision.toolCalls.length === 0) {
+      return [];
+    }
+    this.log(`Executing ${decision.toolCalls.length} tool call(s)`);
+    const results = [];
+    for (const toolCall of decision.toolCalls) {
+      this.log(`Action: ${toolCall.toolName}`, {
+        parameters: toolCall.arguments
+      });
+      const toolSpan = await this.opperClient.createSpan({
+        name: `tool_${toolCall.toolName}`,
+        input: toolCall.arguments,
+        ...parentSpanId ? { parentSpanId } : context.parentSpanId ? { parentSpanId: context.parentSpanId } : {}
+      });
+      try {
+        const result = await this.executeTool(
+          toolCall.toolName,
+          toolCall.arguments,
+          context,
+          { spanId: toolSpan.id }
+        );
+        if (result.success) {
+          await this.opperClient.updateSpan(toolSpan.id, result.output);
+        } else {
+          await this.opperClient.updateSpan(toolSpan.id, void 0, {
+            error: result.error instanceof Error ? result.error.message : String(result.error)
+          });
+        }
+        const summary = {
+          toolName: toolCall.toolName,
+          success: result.success,
+          ...result.success && { output: result.output },
+          ...!result.success && {
+            error: result.error instanceof Error ? result.error.message : String(result.error)
+          }
+        };
+        results.push(ToolExecutionSummarySchema.parse(summary));
+        this.log(
+          `Tool ${toolCall.toolName} ${result.success ? "succeeded" : "failed"}`,
+          {
+            success: result.success
+          }
+        );
+      } catch (error) {
+        await this.opperClient.updateSpan(toolSpan.id, void 0, {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        const summary = {
+          toolName: toolCall.toolName,
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+        results.push(ToolExecutionSummarySchema.parse(summary));
+        this.logger.warn(`Tool ${toolCall.toolName} threw error`, {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return results;
+  }
+  /**
+   * Handle memory operations from a decision
+   * Supports read and write operations with graceful degradation
+   */
+  async handleMemoryActions(decision, context, parentSpanId) {
+    if (!this.enableMemory || !this.memory) {
+      return [];
+    }
+    const hasReads = Array.isArray(decision.memoryReads) && decision.memoryReads.length > 0;
+    const updateEntries = Object.entries(decision.memoryUpdates ?? {}).filter(
+      ([key, update]) => typeof key === "string" && key.length > 0 && typeof update === "object" && update !== null && "value" in update
+    );
+    const hasWrites = updateEntries.length > 0;
+    if (!hasReads && !hasWrites) {
+      return [];
+    }
+    this.log("Handling memory operations", {
+      reads: decision.memoryReads?.length ?? 0,
+      writes: updateEntries.length
+    });
+    const spanParentId = parentSpanId ?? context.parentSpanId ?? void 0;
+    const summaries = [];
+    if (hasReads) {
+      try {
+        const keySet = new Set(
+          decision.memoryReads.filter(
+            (key) => typeof key === "string" && key.length > 0
+          )
+        );
+        const keys = Array.from(keySet);
+        if (keys.length > 0) {
+          const memoryReadSpan = await this.opperClient.createSpan({
+            name: "memory_read",
+            input: keys,
+            ...spanParentId && { parentSpanId: spanParentId }
+          });
+          const memoryData = await this.memory.read(keys);
+          await this.opperClient.updateSpan(memoryReadSpan.id, memoryData);
+          context.setMetadata("current_memory", memoryData);
+          this.log(`Loaded ${Object.keys(memoryData).length} memory entries`, {
+            keys
+          });
+          summaries.push(
+            ToolExecutionSummarySchema.parse({
+              toolName: "memory_read",
+              success: true,
+              output: { keys, data: memoryData }
+            })
+          );
+          for (const key of keys) {
+            await this.triggerHook(HookEvents.MemoryRead, {
+              context,
+              key,
+              value: memoryData[key]
+            });
+          }
+        }
+      } catch (error) {
+        await this.triggerHook(HookEvents.MemoryError, {
+          context,
+          operation: "read",
+          error
+        });
+        this.logger.warn("Memory read failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        summaries.push(
+          ToolExecutionSummarySchema.parse({
+            toolName: "memory_read",
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+          })
+        );
+      }
+    }
+    if (hasWrites) {
+      try {
+        const memoryWriteSpan = await this.opperClient.createSpan({
+          name: "memory_write",
+          input: updateEntries.map(([key]) => key),
+          ...spanParentId && { parentSpanId: spanParentId }
+        });
+        for (const [key, update] of updateEntries) {
+          const castUpdate = update;
+          await this.memory.write(
+            key,
+            castUpdate.value,
+            castUpdate.description ?? key,
+            castUpdate.metadata
+          );
+          await this.triggerHook(HookEvents.MemoryWrite, {
+            context,
+            key,
+            value: castUpdate.value
+          });
+        }
+        await this.opperClient.updateSpan(
+          memoryWriteSpan.id,
+          `Successfully wrote ${updateEntries.length} keys`
+        );
+        this.log(`Wrote ${updateEntries.length} memory entries`);
+        summaries.push(
+          ToolExecutionSummarySchema.parse({
+            toolName: "memory_write",
+            success: true,
+            output: {
+              keys: updateEntries.map(([key]) => key)
+            }
+          })
+        );
+      } catch (error) {
+        await this.triggerHook(HookEvents.MemoryError, {
+          context,
+          operation: "write",
+          error
+        });
+        this.logger.warn("Memory write failed", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        summaries.push(
+          ToolExecutionSummarySchema.parse({
+            toolName: "memory_write",
+            success: false,
+            error: error instanceof Error ? error.message : String(error)
+          })
+        );
+      }
+    }
+    return summaries;
+  }
+  /**
+   * Generate final result based on execution history
+   */
+  async generateFinalResult(input, context) {
+    this.log("Generating final result", { totalIterations: context.iteration });
+    const finalContext = {
+      goal: this.serializeInput(input),
+      instructions: this.instructions || "No specific instructions.",
+      execution_history: context.executionHistory.map((cycle) => {
+        const results = Array.isArray(cycle.results) ? cycle.results : [];
+        return {
+          iteration: cycle.iteration,
+          actions_taken: results.map(
+            (r) => r.toolName
+          ),
+          results: results.filter((r) => r.success).map((r) => {
+            const result = r;
+            let actualOutput = result.output;
+            if (isToolSuccessResult(actualOutput)) {
+              actualOutput = actualOutput.output;
+            }
+            return {
+              tool: result.toolName,
+              // Serialize result properly - use JSON for objects, String for primitives
+              result: typeof actualOutput === "object" ? JSON.stringify(actualOutput) : String(actualOutput)
+            };
+          })
+        };
+      }),
+      total_iterations: context.iteration
+    };
+    const instructions = `Generate the final result based on the execution history.
+Follow any instructions provided for formatting and style.`;
+    try {
+      const callOptions = {
+        name: "generate_final_result",
+        instructions,
+        input: finalContext,
+        model: this.model
+      };
+      if (context.parentSpanId) {
+        callOptions.parentSpanId = context.parentSpanId;
+      }
+      if (this.outputSchema) {
+        callOptions.outputSchema = this.outputSchema;
+      }
+      const response = await this.opperClient.call(callOptions);
+      context.updateUsage({
+        requests: 1,
+        inputTokens: response.usage.inputTokens,
+        outputTokens: response.usage.outputTokens,
+        totalTokens: response.usage.totalTokens,
+        cost: response.usage.cost
+      });
+      if (this.outputSchema) {
+        const parsed = this.outputSchema.parse(response.jsonPayload);
+        this.log("Final result generated (schema-validated)");
+        return parsed;
+      }
+      this.log("Final result generated");
+      return response.message;
+    } catch (error) {
+      this.logger.error("Failed to generate final result", error);
+      throw new Error(
+        `Failed to generate final result: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Log helper
+   */
+  log(message, data) {
+    if (this.verbose) {
+      this.logger.info(`[${this.name}] ${message}`, data);
+    }
+  }
+};
+var DEFAULT_CLIENT_INFO = {
+  name: "opper-agent-ts-mcp-client",
+  version: "0.0.0"
+};
+var MCPClient = class _MCPClient {
+  config;
+  client;
+  transport;
+  connected;
+  toolCache;
+  constructor(config, options = {}) {
+    this.config = config;
+    this.client = new index_js.Client(options.clientInfo ?? DEFAULT_CLIENT_INFO, {
+      enforceStrictCapabilities: false
+    });
+    this.transport = null;
+    this.connected = false;
+    this.toolCache = null;
+  }
+  static fromConfig(config, options) {
+    return new _MCPClient(config, options);
+  }
+  async connect() {
+    if (this.connected) {
+      return;
+    }
+    const transport = this.createTransport();
+    this.transport = transport;
+    try {
+      await this.client.connect(transport);
+      this.connected = true;
+    } catch (error) {
+      await transport.close().catch(() => {
+      });
+      this.transport = null;
+      throw error;
+    }
+  }
+  async disconnect() {
+    if (!this.connected) {
+      return;
+    }
+    await this.client.close().catch(() => {
+    });
+    await this.transport?.close().catch(() => {
+    });
+    this.transport = null;
+    this.connected = false;
+    this.toolCache = null;
+  }
+  async listTools() {
+    const session = this.ensureConnected();
+    if (this.toolCache) {
+      return this.toolCache;
+    }
+    const response = await session.listTools({});
+    const tools = response.tools?.map((tool2) => {
+      const parameters = tool2.inputSchema ?? {};
+      const outputSchema = tool2["outputSchema"];
+      const normalized = {
+        name: tool2.name,
+        description: tool2.description ?? "",
+        parameters
+      };
+      if (outputSchema) {
+        normalized.outputSchema = outputSchema;
+      }
+      return normalized;
+    }) ?? [];
+    this.toolCache = tools;
+    return tools;
+  }
+  async callTool(toolName, args) {
+    const session = this.ensureConnected();
+    const response = await session.callTool({
+      name: toolName,
+      arguments: args
+    });
+    return response;
+  }
+  get isConnected() {
+    return this.connected;
+  }
+  ensureConnected() {
+    if (!this.connected) {
+      throw new Error(`MCP server "${this.config.name}" is not connected`);
+    }
+    return this.client;
+  }
+  createTransport() {
+    if (this.config.transport === "stdio") {
+      const stdioOptions = {
+        command: this.config.command
+      };
+      if (this.config.args.length > 0) {
+        stdioOptions.args = this.config.args;
+      }
+      if (Object.keys(this.config.env).length > 0) {
+        stdioOptions.env = this.config.env;
+      }
+      if (this.config.cwd) {
+        stdioOptions.cwd = this.config.cwd;
+      }
+      if (this.config.stderr) {
+        stdioOptions.stderr = this.config.stderr;
+      }
+      return new stdio_js.StdioClientTransport(stdioOptions);
+    }
+    if (this.config.transport === "streamable-http") {
+      const options2 = {};
+      const headers2 = this.config.headers;
+      if (headers2 && Object.keys(headers2).length > 0) {
+        options2.requestInit = { headers: headers2 };
+      }
+      if (this.config.sessionId) {
+        options2.sessionId = this.config.sessionId;
+      }
+      return new streamableHttp_js.StreamableHTTPClientTransport(
+        new URL(this.config.url),
+        options2
+      );
+    }
+    const headers = this.config.headers ?? {};
+    const headerEntries = Object.entries(headers);
+    const options = {};
+    if (headerEntries.length > 0) {
+      options.eventSourceInit = {
+        fetch: async (url, init) => {
+          const mergedHeaders = new Headers(init?.headers ?? {});
+          for (const [key, value] of headerEntries) {
+            mergedHeaders.set(key, value);
+          }
+          if (!mergedHeaders.has("Accept")) {
+            mergedHeaders.set("Accept", "text/event-stream");
+          }
+          return fetch(url, {
+            ...init,
+            headers: mergedHeaders
+          });
+        }
+      };
+    }
+    if (headerEntries.length > 0 || this.config.method === "POST") {
+      options.requestInit = {
+        ...this.config.method ? { method: this.config.method } : {},
+        ...headerEntries.length > 0 ? { headers } : {}
+      };
+    }
+    return new sse_js.SSEClientTransport(new URL(this.config.url), options);
+  }
+};
+var MCPTransportSchema = zod.z.enum(["stdio", "http-sse", "streamable-http"]);
+var MCPBaseConfigSchema = zod.z.object({
+  name: zod.z.string().min(1, "name is required"),
+  transport: MCPTransportSchema,
+  timeout: zod.z.number().positive("timeout must be positive").default(30),
+  metadata: zod.z.record(zod.z.string(), zod.z.unknown()).default({})
+});
+var MCPStdIoConfigSchema = MCPBaseConfigSchema.extend({
+  transport: zod.z.literal("stdio"),
+  command: zod.z.string().min(1, "command is required for stdio transport"),
+  args: zod.z.array(zod.z.string()).default([]),
+  env: zod.z.record(zod.z.string(), zod.z.string()).default({}),
+  cwd: zod.z.string().optional(),
+  stderr: zod.z.union([zod.z.literal("inherit"), zod.z.literal("pipe"), zod.z.literal("ignore")]).optional()
+});
+var MCPHttpSseConfigSchema = MCPBaseConfigSchema.extend({
+  transport: zod.z.literal("http-sse"),
+  url: zod.z.string().url("url must be a valid HTTP(S) URL"),
+  headers: zod.z.record(zod.z.string(), zod.z.string()).default({}),
+  method: zod.z.enum(["GET", "POST"]).default("GET")
+});
+var MCPStreamableHttpConfigSchema = MCPBaseConfigSchema.extend({
+  transport: zod.z.literal("streamable-http"),
+  url: zod.z.string().url("url must be a valid HTTP(S) URL"),
+  headers: zod.z.record(zod.z.string(), zod.z.string()).default({}),
+  sessionId: zod.z.string().optional()
+});
+var MCPConfigVariants = zod.z.discriminatedUnion("transport", [
+  MCPStdIoConfigSchema,
+  MCPHttpSseConfigSchema,
+  MCPStreamableHttpConfigSchema
+]);
+var MCPServerConfigSchema = MCPConfigVariants.superRefine(
+  (value, ctx) => {
+    if (value.transport === "http-sse" || value.transport === "streamable-http") {
+      if (!value.url) {
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: `url is required for ${value.transport} transport`,
+          path: ["url"]
+        });
+      } else if (!value.url.startsWith("http://") && !value.url.startsWith("https://")) {
+        ctx.addIssue({
+          code: zod.z.ZodIssueCode.custom,
+          message: "url must start with http:// or https://",
+          path: ["url"]
+        });
+      }
+    }
+  }
+);
+var MCPconfig = (config) => MCPServerConfigSchema.parse(config);
+var createMCPServerConfig = MCPconfig;
+
+// src/mcp/provider.ts
+init_tool();
+var isRecord = (value) => typeof value === "object" && value !== null;
+var MCPToolProvider = class {
+  configs;
+  namePrefix;
+  clientOptions;
+  clientFactory;
+  logger;
+  clients;
+  constructor(configs, options = {}) {
+    if (configs.length === 0) {
+      throw new Error(
+        "MCPToolProvider requires at least one server configuration"
+      );
+    }
+    this.configs = configs;
+    this.namePrefix = options.namePrefix ?? void 0;
+    this.clientOptions = options.clientOptions ?? void 0;
+    this.clientFactory = options.clientFactory ?? ((config, factoryOptions) => MCPClient.fromConfig(config, factoryOptions));
+    this.logger = options.logger ?? {
+      warn: (message, context) => console.warn(`[MCPToolProvider] ${message}`, context),
+      error: (message, context) => console.error(`[MCPToolProvider] ${message}`, context),
+      debug: () => {
+      }
+    };
+    this.clients = /* @__PURE__ */ new Map();
+  }
+  async setup(agent) {
+    const tools = [];
+    for (const config of this.configs) {
+      let client = null;
+      try {
+        client = this.clientFactory(config, this.clientOptions);
+        await client.connect();
+        this.clients.set(config.name, client);
+        const mcpTools = await client.listTools();
+        for (const mcpTool of mcpTools) {
+          tools.push(this.wrapTool(config, client, mcpTool));
+        }
+        this.logger?.debug?.("Registered MCP server tools", {
+          server: config.name,
+          toolCount: mcpTools.length
+        });
+      } catch (error) {
+        this.logger?.warn?.("Failed to initialize MCP server", {
+          server: config.name,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        if (client) {
+          await client.disconnect().catch(() => {
+          });
+          this.clients.delete(config.name);
+        }
+      }
+    }
+    return tools;
+  }
+  async teardown() {
+    const disconnects = Array.from(this.clients.entries()).map(
+      async ([serverName, client]) => {
+        try {
+          await client.disconnect();
+          this.logger?.debug?.("Disconnected MCP server", {
+            server: serverName
+          });
+        } catch (error) {
+          this.logger?.warn?.("Error disconnecting MCP server", {
+            server: serverName,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        } finally {
+          this.clients.delete(serverName);
+        }
+      }
+    );
+    await Promise.allSettled(disconnects);
+  }
+  wrapTool(config, client, mcpTool) {
+    const prefix = this.namePrefix ?? config.name;
+    const toolName = `${prefix}:${mcpTool.name}`;
+    return {
+      name: toolName,
+      description: mcpTool.description,
+      metadata: {
+        provider: "mcp",
+        server: config.name,
+        originalToolName: mcpTool.name,
+        parameters: mcpTool.parameters,
+        outputSchema: mcpTool.outputSchema
+      },
+      execute: async (input, context) => {
+        const startedAt = Date.now();
+        const args = isRecord(input) ? input : input === void 0 ? {} : { value: input };
+        try {
+          const result = await client.callTool(mcpTool.name, args);
+          return exports.ToolResultFactory.success(toolName, result, {
+            metadata: {
+              provider: "mcp",
+              server: config.name,
+              tool: mcpTool.name
+            },
+            startedAt,
+            finishedAt: Date.now()
+          });
+        } catch (error) {
+          const failure = error instanceof Error ? error : new Error(String(error));
+          return exports.ToolResultFactory.failure(toolName, failure, {
+            metadata: {
+              provider: "mcp",
+              server: config.name,
+              tool: mcpTool.name
+            },
+            startedAt,
+            finishedAt: Date.now()
+          });
+        }
+      }
+    };
+  }
+};
+var mcp = (...configs) => {
+  if (configs.length === 0) {
+    throw new Error("At least one MCP server configuration is required");
+  }
+  const parsedConfigs = configs.map(
+    (config) => MCPServerConfigSchema.parse(config)
+  );
+  return new MCPToolProvider(parsedConfigs);
+};
+
+// src/utils/tool-decorators.ts
+init_tool();
+var reflectWithMetadata = Reflect;
+var ReflectMetadata = {
+  define: (metadataKey, metadataValue, target, propertyKey) => {
+    if (typeof reflectWithMetadata.defineMetadata === "function") {
+      reflectWithMetadata.defineMetadata(
+        metadataKey,
+        metadataValue,
+        target,
+        propertyKey
+      );
+    }
+  },
+  get: (metadataKey, target, propertyKey) => {
+    if (typeof reflectWithMetadata.getMetadata === "function") {
+      return reflectWithMetadata.getMetadata(metadataKey, target, propertyKey);
+    }
+    return void 0;
+  }
+};
+var TOOL_METADATA_KEY = "opper:tool";
+var toolMetadataStore = /* @__PURE__ */ new WeakMap();
+function setToolMetadata(target, propertyKey, metadata) {
+  ReflectMetadata.define(TOOL_METADATA_KEY, metadata, target, propertyKey);
+  let metadataForTarget = toolMetadataStore.get(target);
+  if (!metadataForTarget) {
+    metadataForTarget = /* @__PURE__ */ new Map();
+    toolMetadataStore.set(target, metadataForTarget);
+  }
+  metadataForTarget.set(
+    propertyKey,
+    metadata
+  );
+}
+function getToolMetadata(target, propertyKey) {
+  const metadata = ReflectMetadata.get(
+    TOOL_METADATA_KEY,
+    target,
+    propertyKey
+  );
+  if (metadata) {
+    return metadata;
+  }
+  const metadataForTarget = toolMetadataStore.get(target);
+  return metadataForTarget?.get(propertyKey);
+}
+function isStage3DecoratorContext(value) {
+  return typeof value === "object" && value !== null && "kind" in value;
+}
+function createExecuteWrapper(toolName, method, options, callTargetRef) {
+  return async (input, context) => {
+    const startedAt = Date.now();
+    try {
+      if (options.schema) {
+        options.schema.parse(input);
+      }
+      const invocationTarget = callTargetRef.current;
+      const result = await Promise.resolve(
+        method.call(invocationTarget, input, context)
+      );
+      return exports.ToolResultFactory.success(toolName, result, {
+        startedAt,
+        finishedAt: Date.now(),
+        ...options.metadata && { metadata: options.metadata }
+      });
+    } catch (error) {
+      return exports.ToolResultFactory.failure(
+        toolName,
+        error instanceof Error ? error : new Error(String(error)),
+        {
+          startedAt,
+          finishedAt: Date.now(),
+          ...options.metadata && { metadata: options.metadata }
+        }
+      );
+    }
+  };
+}
+function normalizePropertyKey(propertyKey) {
+  return typeof propertyKey === "symbol" ? propertyKey.description ?? propertyKey.toString() : propertyKey;
+}
+function createToolDefinition(options, methodName, propertyKey, method, callTargetRef) {
+  const name = options.name ?? methodName;
+  const description = options.description ?? extractJSDocDescription(method) ?? `Tool: ${normalizePropertyKey(propertyKey)}`;
+  return {
+    name,
+    description,
+    ...options.schema && { schema: options.schema },
+    ...options.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
+    metadata: {
+      ...options.metadata,
+      isDecorated: true,
+      propertyKey: normalizePropertyKey(propertyKey)
+    },
+    execute: createExecuteWrapper(name, method, options, callTargetRef)
+  };
+}
+function createFunctionTool(fn, options = {}) {
+  const name = options.name ?? (fn.name || "anonymous_tool");
+  const description = options.description ?? extractJSDocDescription(fn) ?? `Tool: ${name}`;
+  const tool2 = {
+    name,
+    description,
+    ...options.schema && { schema: options.schema },
+    ...options.timeoutMs !== void 0 && { timeoutMs: options.timeoutMs },
+    metadata: {
+      ...options.metadata,
+      isFunction: true,
+      functionName: fn.name
+    },
+    execute: async (input, context) => {
+      const startedAt = Date.now();
+      try {
+        if (options.schema) {
+          options.schema.parse(input);
+        }
+        let result;
+        if (options.timeoutMs !== void 0) {
+          result = await executeWithTimeout(
+            fn(input, context),
+            options.timeoutMs,
+            name
+          );
+        } else {
+          result = await Promise.resolve(fn(input, context));
+        }
+        return exports.ToolResultFactory.success(name, result, {
+          startedAt,
+          finishedAt: Date.now(),
+          ...options.metadata && { metadata: options.metadata }
+        });
+      } catch (error) {
+        return exports.ToolResultFactory.failure(
+          name,
+          error instanceof Error ? error : new Error(String(error)),
+          {
+            startedAt,
+            finishedAt: Date.now(),
+            ...options.metadata && { metadata: options.metadata }
+          }
+        );
+      }
+    }
+  };
+  return tool2;
+}
+function tool(options) {
+  const decoratorOptions = options ?? {};
+  function decorator(...decoratorArgs) {
+    if (decoratorArgs.length === 2 && isStage3DecoratorContext(decoratorArgs[1])) {
+      const [method, context] = decoratorArgs;
+      if (context.kind !== "method") {
+        throw new Error("@tool can only be applied to methods.");
+      }
+      if (context.name === void 0) {
+        throw new Error("@tool requires a named method to attach metadata.");
+      }
+      const propertyKey2 = context.name;
+      const inferredName = typeof propertyKey2 === "string" && propertyKey2.length > 0 ? propertyKey2 : method.name || "anonymous_tool";
+      const callTargetRef2 = {};
+      const toolMetadata2 = createToolDefinition(
+        decoratorOptions,
+        inferredName,
+        propertyKey2,
+        method,
+        callTargetRef2
+      );
+      const registerMetadata = (target2) => {
+        callTargetRef2.current = target2;
+        setToolMetadata(target2, propertyKey2, toolMetadata2);
+      };
+      if (typeof context.addInitializer === "function") {
+        context.addInitializer(function() {
+          const target2 = context.static ? this : Object.getPrototypeOf(this);
+          if (target2) {
+            registerMetadata(target2);
+          }
+        });
+      }
+      return;
+    }
+    const [target, propertyKey, descriptor] = decoratorArgs;
+    const resolvedDescriptor = descriptor ?? Object.getOwnPropertyDescriptor(target, propertyKey) ?? (() => {
+      const value = target[propertyKey];
+      if (typeof value === "function") {
+        return { value };
+      }
+      return void 0;
+    })();
+    if (!resolvedDescriptor || typeof resolvedDescriptor.value !== "function") {
+      throw new Error(
+        `@tool can only be applied to methods, not ${typeof resolvedDescriptor?.value}`
+      );
+    }
+    const originalMethod = resolvedDescriptor.value;
+    const callTargetRef = { current: target };
+    const toolMetadata = createToolDefinition(
+      decoratorOptions,
+      normalizePropertyKey(propertyKey),
+      propertyKey,
+      originalMethod,
+      callTargetRef
+    );
+    setToolMetadata(target, propertyKey, toolMetadata);
+    return resolvedDescriptor;
+  }
+  return decorator;
+}
+function extractTools(instance) {
+  const tools = [];
+  const prototype = Object.getPrototypeOf(instance);
+  const propertyKeys = [
+    ...Object.getOwnPropertyNames(prototype),
+    ...Object.getOwnPropertySymbols(prototype)
+  ];
+  for (const propertyKey of propertyKeys) {
+    if (propertyKey === "constructor") continue;
+    const toolMetadata = getToolMetadata(prototype, propertyKey);
+    if (toolMetadata) {
+      const instanceMethod = instance[propertyKey];
+      if (typeof instanceMethod !== "function") {
+        continue;
+      }
+      const tool2 = {
+        ...toolMetadata,
+        execute: async (input, context) => {
+          const startedAt = Date.now();
+          try {
+            if (toolMetadata.schema) {
+              toolMetadata.schema.parse(input);
+            }
+            const result = await Promise.resolve(
+              instanceMethod.call(instance, input, context)
+            );
+            return exports.ToolResultFactory.success(toolMetadata.name, result, {
+              startedAt,
+              finishedAt: Date.now(),
+              ...toolMetadata.metadata && { metadata: toolMetadata.metadata }
+            });
+          } catch (error) {
+            return exports.ToolResultFactory.failure(
+              toolMetadata.name,
+              error instanceof Error ? error : new Error(String(error)),
+              {
+                startedAt,
+                finishedAt: Date.now(),
+                ...toolMetadata.metadata && {
+                  metadata: toolMetadata.metadata
+                }
+              }
+            );
+          }
+        }
+      };
+      tools.push(tool2);
+    }
+  }
+  return tools;
+}
+async function executeWithTimeout(promise, timeoutMs, toolName) {
+  return Promise.race([
+    Promise.resolve(promise),
+    new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`Tool "${toolName}" timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+    })
+  ]);
+}
+function extractJSDocDescription(fn) {
+  const source = fn.toString();
+  const match = /\/\*\*\s*\n\s*\*\s*(.+?)\s*\n/.exec(source);
+  return match?.[1];
+}
+
+// src/utils/tool-runner.ts
+init_tool();
+var ToolRunner = class {
+  /**
+   * Execute a tool with the given input and context
+   *
+   * @param tool - Tool to execute
+   * @param input - Input data
+   * @param context - Agent execution context
+   * @param options - Execution options
+   * @returns Tool execution result
+   */
+  static async execute(tool2, input, context, options = {}) {
+    if (options.signal?.aborted) {
+      return exports.ToolResultFactory.failure(
+        tool2.name,
+        new Error(`Tool "${tool2.name}" execution was aborted`)
+      );
+    }
+    if (tool2.schema) {
+      const validation = tool2.schema.safeParse(input);
+      if (!validation.success) {
+        return exports.ToolResultFactory.failure(
+          tool2.name,
+          new Error(
+            `Invalid input for tool "${tool2.name}": ${validation.error.message}`
+          )
+        );
+      }
+    }
+    const executionContext = {
+      agentContext: context,
+      ...options.signal && { signal: options.signal },
+      metadata: options.metadata ?? {}
+    };
+    try {
+      const timeoutMs = options.timeoutMs ?? tool2.timeoutMs;
+      let result;
+      if (timeoutMs !== void 0) {
+        result = await this.executeWithTimeout(
+          Promise.resolve(tool2.execute(input, executionContext)),
+          timeoutMs,
+          tool2.name
+        );
+      } else {
+        result = await Promise.resolve(tool2.execute(input, executionContext));
+      }
+      return result;
+    } catch (error) {
+      return exports.ToolResultFactory.failure(
+        tool2.name,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+  /**
+   * Execute multiple tools in parallel
+   *
+   * @param executions - Array of tool execution tuples [tool, input, context, options?]
+   * @returns Array of results in same order as input
+   */
+  static async executeParallel(executions) {
+    return Promise.all(
+      executions.map(
+        ([tool2, input, context, options]) => this.execute(tool2, input, context, options)
+      )
+    );
+  }
+  /**
+   * Execute multiple tools sequentially, stopping on first failure
+   *
+   * @param executions - Array of tool execution tuples
+   * @returns Array of results up to first failure (inclusive)
+   */
+  static async executeSequential(executions) {
+    const results = [];
+    for (const [tool2, input, context, options] of executions) {
+      const result = await this.execute(tool2, input, context, options);
+      results.push(result);
+      if (!result.success) {
+        break;
+      }
+    }
+    return results;
+  }
+  /**
+   * Execute a tool with timeout
+   *
+   * @param promise - Tool execution promise
+   * @param timeoutMs - Timeout in milliseconds
+   * @param toolName - Tool name for error messages
+   * @returns Result or rejects with timeout error
+   */
+  static async executeWithTimeout(promise, timeoutMs, toolName) {
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(
+            new Error(`Tool "${toolName}" timed out after ${timeoutMs}ms`)
+          );
+        }, timeoutMs);
+      })
+    ]);
+  }
+  /**
+   * Validate tool input without executing
+   *
+   * @param tool - Tool to validate input for
+   * @param input - Input to validate
+   * @returns true if valid, Error if invalid
+   */
+  static validate(tool2, input) {
+    if (!tool2.schema) {
+      return true;
+    }
+    const validation = tool2.schema.safeParse(input);
+    if (!validation.success) {
+      return new Error(
+        `Invalid input for tool "${tool2.name}": ${validation.error.message}`
+      );
+    }
+    return true;
+  }
+  /**
+   * Check if a result indicates success
+   *
+   * @param result - Tool result to check
+   * @returns true if success, false if failure
+   */
+  static isSuccess(result) {
+    return result.success === true;
+  }
+  /**
+   * Check if a result indicates failure
+   *
+   * @param result - Tool result to check
+   * @returns true if failure, false if success
+   */
+  static isFailure(result) {
+    return result.success === false;
+  }
+};
+
+exports.Agent = Agent;
+exports.AgentDecisionSchema = AgentDecisionSchema;
+exports.BaseAgent = BaseAgent;
+exports.ConsoleLogger = ConsoleLogger;
+exports.DEFAULT_MODEL = DEFAULT_MODEL;
+exports.DEFAULT_RETRY_CONFIG = DEFAULT_RETRY_CONFIG;
+exports.HookEvents = HookEvents;
+exports.HookManager = HookManager;
+exports.InMemoryStore = InMemoryStore;
+exports.LogLevel = LogLevel;
+exports.MCPClient = MCPClient;
+exports.MCPServerConfigSchema = MCPServerConfigSchema;
+exports.MCPToolProvider = MCPToolProvider;
+exports.MCPconfig = MCPconfig;
+exports.MemoryEntryMetadataSchema = MemoryEntryMetadataSchema;
+exports.MemoryEntrySchema = MemoryEntrySchema;
+exports.MemoryUpdateSchema = MemoryUpdateSchema;
+exports.OpperClient = OpperClient;
+exports.SchemaValidationError = SchemaValidationError;
+exports.SilentLogger = SilentLogger;
+exports.ThoughtSchema = ThoughtSchema;
+exports.ToolCallSchema = ToolCallSchema;
+exports.ToolExecutionSummarySchema = ToolExecutionSummarySchema;
+exports.ToolRunner = ToolRunner;
+exports.createFunctionTool = createFunctionTool;
+exports.createHookManager = createHookManager;
+exports.createInMemoryStore = createInMemoryStore;
+exports.createMCPServerConfig = createMCPServerConfig;
+exports.createOpperClient = createOpperClient;
+exports.extractTools = extractTools;
+exports.getDefaultLogger = getDefaultLogger;
+exports.getSchemaDefault = getSchemaDefault;
+exports.isSchemaValid = isSchemaValid;
+exports.mcp = mcp;
+exports.mergeSchemaDefaults = mergeSchemaDefaults;
+exports.schemaToJson = schemaToJson;
+exports.setDefaultLogger = setDefaultLogger;
+exports.tool = tool;
+exports.validateSchema = validateSchema;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map