gauss-ai 4.0.0

package/dist/chunk-BI2G665F.js

@@ -0,0 +1,4588 @@
+import {
+  CircuitBreaker,
+  DEFAULT_CIRCUIT_BREAKER_CONFIG,
+  DEFAULT_TOOL_CACHE_CONFIG,
+  PluginManager,
+  ToolCache
+} from "./chunk-X2GHUHAF.js";
+import {
+  generateText,
+  stepCountIs,
+  streamText,
+  tool
+} from "./chunk-K6SAETGP.js";
+
+// src/adapters/runtime/detect-runtime.ts
+function detectRuntimeName() {
+  if (typeof globalThis !== "undefined") {
+    if ("Deno" in globalThis) return "deno";
+    if ("Bun" in globalThis) return "bun";
+    if (typeof globalThis.process?.versions?.node === "string") return "node";
+    if (typeof globalThis.fetch === "function" && !("process" in globalThis)) return "edge";
+  }
+  return "unknown";
+}
+async function createRuntimeAdapterAsync(name) {
+  const resolved = name ?? detectRuntimeName();
+  switch (resolved) {
+    case "deno": {
+      const { DenoRuntimeAdapter: D } = await import("./deno-runtime.adapter-F744HY7K.js");
+      return new D();
+    }
+    case "bun": {
+      const { BunRuntimeAdapter: B } = await import("./bun-runtime.adapter-MQDAJLQM.js");
+      return new B();
+    }
+    case "edge": {
+      const { EdgeRuntimeAdapter: E } = await import("./edge-runtime.adapter-UQCW2F7X.js");
+      return new E();
+    }
+    case "node":
+    case "unknown":
+    default: {
+      const { NodeRuntimeAdapter: N } = await import("./node-runtime.adapter-5L7PJ6W2.js");
+      return new N();
+    }
+  }
+}
+
+// src/agent/event-bus.ts
+var EventBus = class _EventBus {
+  sessionId;
+  listeners = /* @__PURE__ */ new Map();
+  maxListenersPerEvent;
+  maxBubblesPerSecond;
+  // Hierarchical relationships
+  parent = null;
+  children = /* @__PURE__ */ new Map();
+  namespace = null;
+  // Namespaced listeners: namespace -> Set<handler>
+  namespacedListeners = /* @__PURE__ */ new Map();
+  // Anti-storm: track bubble counts per child per second window
+  bubbleCounts = /* @__PURE__ */ new Map();
+  constructor(sessionId, options) {
+    this.sessionId = sessionId;
+    this.maxListenersPerEvent = options?.maxListenersPerEvent ?? 100;
+    this.maxBubblesPerSecond = options?.maxBubblesPerSecond ?? 100;
+  }
+  /** Subscribe to a specific event type or '*' for all events. Returns unsubscribe fn. */
+  on(eventType, handler) {
+    let set = this.listeners.get(eventType);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(eventType, set);
+    }
+    if (set.size >= this.maxListenersPerEvent) {
+      throw new Error(
+        `EventBus: max listeners (${this.maxListenersPerEvent}) reached for "${String(eventType)}"`
+      );
+    }
+    set.add(handler);
+    return () => this.off(eventType, handler);
+  }
+  /** Unsubscribe a handler from a specific event type. */
+  off(eventType, handler) {
+    const set = this.listeners.get(eventType);
+    if (!set) return;
+    set.delete(handler);
+    if (set.size === 0) this.listeners.delete(eventType);
+  }
+  /** Emit an event, auto-filling timestamp and sessionId. Also bubbles to parent. */
+  emit(type, data) {
+    const event = {
+      type,
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+      data
+    };
+    this.dispatchLocal(event);
+    this.bubbleToParent(event);
+  }
+  /** Remove all listeners for a given event type, or all listeners if no type specified. */
+  removeAllListeners(eventType) {
+    if (eventType) {
+      this.listeners.delete(eventType);
+    } else {
+      this.listeners.clear();
+    }
+  }
+  /** Return the number of listeners for a given event type. */
+  listenerCount(eventType) {
+    return this.listeners.get(eventType)?.size ?? 0;
+  }
+  // ===========================================================================
+  // Hierarchical API
+  // ===========================================================================
+  /** Create a child bus with a given namespace. */
+  createChild(childNamespace) {
+    if (this.children.has(childNamespace)) {
+      throw new Error(`EventBus: child namespace "${childNamespace}" already exists`);
+    }
+    const child = new _EventBus(this.sessionId, {
+      maxListenersPerEvent: this.maxListenersPerEvent,
+      maxBubblesPerSecond: this.maxBubblesPerSecond
+    });
+    child.parent = this;
+    child.namespace = childNamespace;
+    this.children.set(childNamespace, child);
+    return child;
+  }
+  /** Broadcast an event from this bus to ALL children recursively (capturing phase). */
+  broadcast(type, data) {
+    const event = {
+      type,
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+      data
+    };
+    for (const child of this.children.values()) {
+      child.dispatchLocal(event);
+      child.broadcast(type, data);
+    }
+  }
+  /** Subscribe to events bubbled from a specific child namespace. */
+  onNamespaced(childNamespace, handler) {
+    let set = this.namespacedListeners.get(childNamespace);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.namespacedListeners.set(childNamespace, set);
+    }
+    set.add(handler);
+    return () => {
+      set.delete(handler);
+      if (set.size === 0) this.namespacedListeners.delete(childNamespace);
+    };
+  }
+  /** Get all child buses. */
+  getChildren() {
+    return new Map(this.children);
+  }
+  /** Get the parent bus, or null for root. */
+  getParent() {
+    return this.parent;
+  }
+  // ===========================================================================
+  // Internal helpers
+  // ===========================================================================
+  /** Dispatch an event to local listeners (specific + wildcard). */
+  dispatchLocal(event) {
+    const specific = this.listeners.get(event.type);
+    if (specific) {
+      for (const handler of specific) handler(event);
+    }
+    const wildcard = this.listeners.get("*");
+    if (wildcard) {
+      for (const handler of wildcard) handler(event);
+    }
+  }
+  /** Bubble an event to the parent bus with _source and _bubbled metadata. */
+  bubbleToParent(event) {
+    if (!this.parent || !this.namespace) return;
+    if (!this.parent.checkBubbleRate(this.namespace)) return;
+    const bubbledData = typeof event.data === "object" && event.data !== null ? { ...event.data, _source: this.namespace, _bubbled: true } : { _value: event.data, _source: this.namespace, _bubbled: true };
+    const bubbledEvent = {
+      type: event.type,
+      timestamp: event.timestamp,
+      sessionId: event.sessionId,
+      data: bubbledData
+    };
+    this.parent.dispatchLocal(bubbledEvent);
+    const nsListeners = this.parent.namespacedListeners.get(this.namespace);
+    if (nsListeners) {
+      for (const handler of nsListeners) handler(bubbledEvent);
+    }
+    this.parent.bubbleToParent(bubbledEvent);
+  }
+  /** Check if a child is within the allowed bubble rate. Returns true if allowed. */
+  checkBubbleRate(childNamespace) {
+    const now = Date.now();
+    let tracker = this.bubbleCounts.get(childNamespace);
+    if (!tracker || now - tracker.windowStart >= 1e3) {
+      tracker = { count: 0, windowStart: now };
+      this.bubbleCounts.set(childNamespace, tracker);
+    }
+    tracker.count++;
+    if (tracker.count > this.maxBubblesPerSecond) {
+      if (tracker.count === this.maxBubblesPerSecond + 1) {
+        console.warn(
+          `EventBus: anti-storm \u2014 child "${childNamespace}" exceeded ${this.maxBubblesPerSecond} bubbles/sec, dropping events`
+        );
+      }
+      return false;
+    }
+    return true;
+  }
+};
+
+// src/context/token-tracker.ts
+var TokenTracker = class {
+  constructor(counter, budget) {
+    this.counter = counter;
+    this.budget = budget;
+  }
+  inputTokens = 0;
+  outputTokens = 0;
+  addInput(tokens) {
+    this.inputTokens += tokens;
+  }
+  addOutput(tokens) {
+    this.outputTokens += tokens;
+  }
+  getUsage() {
+    const totalTokens = this.inputTokens + this.outputTokens;
+    return {
+      inputTokens: this.inputTokens,
+      outputTokens: this.outputTokens,
+      totalTokens,
+      estimatedCost: this.counter.estimateCost(
+        this.inputTokens,
+        this.outputTokens,
+        ""
+      ),
+      isOverBudget: this.isOverBudget()
+    };
+  }
+  isOverBudget() {
+    return this.inputTokens > this.budget.maxInputTokens || this.outputTokens > this.budget.maxOutputTokens || this.inputTokens + this.outputTokens > this.budget.maxTotalTokens;
+  }
+  isNearBudget(threshold) {
+    const t = threshold ?? this.budget.warningThreshold;
+    return this.inputTokens > this.budget.maxInputTokens * t || this.outputTokens > this.budget.maxOutputTokens * t || this.inputTokens + this.outputTokens > this.budget.maxTotalTokens * t;
+  }
+  getRemainingBudget() {
+    const total = this.inputTokens + this.outputTokens;
+    return {
+      inputTokens: Math.max(0, this.budget.maxInputTokens - this.inputTokens),
+      outputTokens: Math.max(0, this.budget.maxOutputTokens - this.outputTokens),
+      totalTokens: Math.max(0, this.budget.maxTotalTokens - total)
+    };
+  }
+  reset() {
+    this.inputTokens = 0;
+    this.outputTokens = 0;
+  }
+};
+
+// src/agent/tool-manager.ts
+import { z as z18 } from "zod";
+
+// src/agent/approval-manager.ts
+var ApprovalManager = class {
+  config;
+  sessionId;
+  eventHandler;
+  constructor(config, sessionId, eventHandler) {
+    this.config = config;
+    this.sessionId = sessionId;
+    this.eventHandler = eventHandler;
+  }
+  /**
+   * Synchronous check whether a tool is auto-approved by configuration.
+   *
+   * - "approve-all": returns true unless tool is in `requireApproval`
+   * - "deny-all": returns true only if tool is in `autoApprove`
+   */
+  shouldApprove(toolName) {
+    if (this.config.defaultMode === "approve-all") {
+      return !this.config.requireApproval.includes(toolName);
+    }
+    return this.config.autoApprove.includes(toolName);
+  }
+  /**
+   * Requests approval via the configured callback, emitting lifecycle events.
+   */
+  async requestApproval(request) {
+    this.emit("tool:approval-required", request);
+    const approved = await this.config.onApprovalRequired(request);
+    if (approved) {
+      this.emit("tool:approved", { toolName: request.toolName, toolCallId: request.toolCallId });
+    } else {
+      this.emit("tool:denied", { toolName: request.toolName, toolCallId: request.toolCallId });
+    }
+    return {
+      approved,
+      reason: approved ? void 0 : "Approval denied by callback"
+    };
+  }
+  /**
+   * Combined check: auto-approves when policy allows, otherwise delegates
+   * to the async approval flow.
+   */
+  async checkAndApprove(toolName, toolCallId, args, stepIndex) {
+    if (this.shouldApprove(toolName)) {
+      return { approved: true };
+    }
+    return this.requestApproval({
+      toolName,
+      toolCallId,
+      args,
+      sessionId: this.sessionId,
+      stepIndex
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+  emit(type, data) {
+    this.eventHandler?.({
+      type,
+      timestamp: Date.now(),
+      sessionId: this.sessionId,
+      data
+    });
+  }
+};
+
+// src/tools/filesystem/ls.tool.ts
+import { z } from "zod";
+var zoneSchema = z.enum(["transient", "persistent"]).default("transient").describe("Filesystem zone to operate in");
+function createLsTool(fs) {
+  return tool({
+    description: "List files and directories at the given path. Returns names, sizes, and types. Use recursive to walk subdirectories.",
+    inputSchema: z.object({
+      path: z.string().describe("Directory path to list"),
+      recursive: z.boolean().optional().default(false).describe("Whether to list subdirectories recursively"),
+      zone: zoneSchema.optional()
+    }),
+    execute: async ({ path, recursive, zone }) => {
+      const entries = await fs.list(
+        path,
+        { recursive },
+        zone ?? "transient"
+      );
+      if (entries.length === 0) return "Directory is empty.";
+      const lines = entries.map((e) => {
+        const tag = e.isDirectory ? "[dir] " : "      ";
+        return `${tag}${e.path}  (${e.size} bytes)`;
+      });
+      return lines.join("\n");
+    }
+  });
+}
+
+// src/tools/filesystem/read-file.tool.ts
+import { z as z2 } from "zod";
+var MAX_CHARS = 5e4;
+function createReadFileTool(fs) {
+  return tool({
+    description: "Read the contents of a file and return it as a string. Very large files are truncated to 50000 characters.",
+    inputSchema: z2.object({
+      path: z2.string().describe("File path to read"),
+      zone: z2.enum(["transient", "persistent"]).default("transient").optional().describe("Filesystem zone")
+    }),
+    execute: async ({ path, zone }) => {
+      const content = await fs.read(path, zone ?? "transient");
+      if (content.length <= MAX_CHARS) return content;
+      return content.slice(0, MAX_CHARS) + `
+
+[Truncated: showing ${MAX_CHARS} of ${content.length} characters]`;
+    }
+  });
+}
+
+// src/tools/filesystem/write-file.tool.ts
+import { z as z3 } from "zod";
+function createWriteFileTool(fs) {
+  return tool({
+    description: "Create or overwrite a file with the given content. Parent directories are created automatically.",
+    inputSchema: z3.object({
+      path: z3.string().describe("File path to write"),
+      content: z3.string().describe("Content to write to the file"),
+      zone: z3.enum(["transient", "persistent"]).default("transient").optional().describe("Filesystem zone")
+    }),
+    execute: async ({ path, content, zone }) => {
+      await fs.write(path, content, zone ?? "transient");
+      return `File written: ${path} (${content.length} bytes)`;
+    }
+  });
+}
+
+// src/tools/filesystem/edit-file.tool.ts
+import { z as z4 } from "zod";
+function createEditFileTool(fs) {
+  return tool({
+    description: "Perform a surgical string replacement in a file. Replaces the first occurrence of oldStr with newStr. Fails if oldStr is not found.",
+    inputSchema: z4.object({
+      path: z4.string().describe("File path to edit"),
+      oldStr: z4.string().describe("Exact string to find and replace"),
+      newStr: z4.string().describe("Replacement string"),
+      zone: z4.enum(["transient", "persistent"]).default("transient").optional().describe("Filesystem zone")
+    }),
+    execute: async ({ path, oldStr, newStr, zone }) => {
+      const z22 = zone ?? "transient";
+      const content = await fs.read(path, z22);
+      if (!content.includes(oldStr)) {
+        throw new Error(`oldStr not found in ${path}`);
+      }
+      const updated = content.replace(oldStr, newStr);
+      await fs.write(path, updated, z22);
+      return `File edited: ${path}`;
+    }
+  });
+}
+
+// src/tools/filesystem/glob.tool.ts
+import { z as z5 } from "zod";
+function createGlobTool(fs) {
+  return tool({
+    description: "Find files matching a glob pattern (e.g. '**/*.ts'). Returns a list of matching file paths.",
+    inputSchema: z5.object({
+      pattern: z5.string().describe("Glob pattern to match files"),
+      zone: z5.enum(["transient", "persistent"]).default("transient").optional().describe("Filesystem zone")
+    }),
+    execute: async ({ pattern, zone }) => {
+      const matches = await fs.glob(pattern, zone ?? "transient");
+      if (matches.length === 0) return "No files matched the pattern.";
+      return matches.join("\n");
+    }
+  });
+}
+
+// src/tools/filesystem/grep.tool.ts
+import { z as z6 } from "zod";
+function createGrepTool(fs) {
+  return tool({
+    description: "Search file contents for a regex or string pattern. Returns matching lines with file paths and line numbers.",
+    inputSchema: z6.object({
+      pattern: z6.string().describe("Regex or string pattern to search for"),
+      path: z6.string().optional().describe("Directory or file to search in"),
+      caseSensitive: z6.boolean().optional().default(true),
+      maxResults: z6.number().int().optional().default(50).describe("Maximum number of results to return"),
+      zone: z6.enum(["transient", "persistent"]).default("transient").optional().describe("Filesystem zone")
+    }),
+    execute: async ({ pattern, path, caseSensitive, maxResults, zone }) => {
+      const results = await fs.search(
+        pattern,
+        { caseSensitive, maxResults, includeLineNumbers: true, filePattern: path },
+        zone ?? "transient"
+      );
+      if (results.length === 0) return "No matches found.";
+      const lines = results.map(
+        (r) => `${r.filePath}:${r.lineNumber}: ${r.lineContent}`
+      );
+      return lines.join("\n");
+    }
+  });
+}
+
+// src/tools/filesystem/index.ts
+function createFilesystemTools(fs) {
+  return {
+    ls: createLsTool(fs),
+    read_file: createReadFileTool(fs),
+    write_file: createWriteFileTool(fs),
+    edit_file: createEditFileTool(fs),
+    glob: createGlobTool(fs),
+    grep: createGrepTool(fs)
+  };
+}
+
+// src/tools/planning/write-todos.tool.ts
+import { z as z7 } from "zod";
+
+// src/tools/planning/shared.ts
+var TODOS_PATH = "todos.json";
+async function loadTodos(fs) {
+  const exists = await fs.exists(TODOS_PATH, "persistent");
+  if (!exists) return [];
+  const raw = await fs.read(TODOS_PATH, "persistent");
+  return JSON.parse(raw);
+}
+
+// src/tools/planning/write-todos.tool.ts
+var TodoInputSchema = z7.object({
+  id: z7.string().describe("Unique identifier (kebab-case)"),
+  title: z7.string().describe("Short title of the task"),
+  description: z7.string().optional(),
+  status: z7.enum(["pending", "in_progress", "done", "blocked"]).optional(),
+  dependencies: z7.array(z7.string()).optional(),
+  priority: z7.enum(["low", "medium", "high", "critical"]).optional()
+});
+function createWriteTodosTool(fs) {
+  return tool({
+    description: "Create or update a task plan. Each todo has an id, title, optional description, status, dependencies, and priority.",
+    inputSchema: z7.object({
+      todos: z7.array(TodoInputSchema).describe("Todos to create or update")
+    }),
+    execute: async ({ todos }) => {
+      const existing = await loadTodos(fs);
+      const byId = new Map(existing.map((t) => [t.id, t]));
+      let created = 0;
+      let updated = 0;
+      for (const input of todos) {
+        const now = Date.now();
+        const prev = byId.get(input.id);
+        if (prev) {
+          byId.set(input.id, { ...prev, ...input, updatedAt: now });
+          updated++;
+        } else {
+          byId.set(input.id, {
+            status: "pending",
+            dependencies: [],
+            priority: "medium",
+            createdAt: now,
+            updatedAt: now,
+            ...input
+          });
+          created++;
+        }
+      }
+      const all = Array.from(byId.values());
+      await fs.write(TODOS_PATH, JSON.stringify(all, null, 2), "persistent");
+      return `Plan updated: ${created} created, ${updated} updated, ${all.length} total.`;
+    }
+  });
+}
+
+// src/tools/planning/review-todos.tool.ts
+import { z as z8 } from "zod";
+function createReviewTodosTool(fs) {
+  return tool({
+    description: "Review current task plan and optionally update todo statuses. Returns the full plan with progress.",
+    inputSchema: z8.object({
+      updates: z8.array(
+        z8.object({
+          id: z8.string().describe("Todo ID to update"),
+          status: z8.enum(["pending", "in_progress", "done", "blocked"])
+        })
+      ).optional().describe("Optional status updates to apply")
+    }),
+    execute: async ({ updates }) => {
+      const todos = await loadTodos(fs);
+      if (todos.length === 0) return "No todos found. Use write_todos first.";
+      if (updates?.length) {
+        const byId = new Map(todos.map((t) => [t.id, t]));
+        for (const u of updates) {
+          const t = byId.get(u.id);
+          if (!t) continue;
+          t.status = u.status;
+          t.updatedAt = Date.now();
+          if (u.status === "done") t.completedAt = Date.now();
+        }
+        await fs.write(
+          TODOS_PATH,
+          JSON.stringify(todos, null, 2),
+          "persistent"
+        );
+      }
+      return formatPlan(todos);
+    }
+  });
+}
+function formatPlan(todos) {
+  const counts = { pending: 0, in_progress: 0, done: 0, blocked: 0 };
+  for (const t of todos) counts[t.status]++;
+  const header = `Plan: ${todos.length} total | ${counts.done} done, ${counts.in_progress} in-progress, ${counts.pending} pending, ${counts.blocked} blocked`;
+  const lines = todos.map(
+    (t) => `[${t.status}] ${t.id}: ${t.title}` + (t.dependencies?.length ? ` (deps: ${t.dependencies.join(", ")})` : "")
+  );
+  return [header, "---", ...lines].join("\n");
+}
+
+// src/tools/planning/plan-create.tool.ts
+import { z as z10 } from "zod";
+
+// src/domain/plan.schema.ts
+import { z as z9 } from "zod";
+var StepExecutionModeSchema = z9.enum([
+  "sequential",
+  "parallel",
+  "conditional",
+  "loop"
+]);
+var StepStatusSchema = z9.enum([
+  "idle",
+  "pending",
+  "running",
+  "completed",
+  "failed",
+  "skipped",
+  "blocked",
+  "cancelled"
+]);
+var StepPrioritySchema = z9.enum(["low", "medium", "high", "critical"]);
+var PlanStatusSchema = z9.enum([
+  "draft",
+  "active",
+  "paused",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+var STEP_STATUS_TRANSITIONS = {
+  idle: ["pending", "skipped", "cancelled"],
+  pending: ["running", "blocked", "skipped", "cancelled"],
+  running: ["completed", "failed", "cancelled"],
+  completed: [],
+  failed: ["pending"],
+  // retry
+  skipped: [],
+  blocked: ["pending", "cancelled"],
+  cancelled: []
+};
+var ResourceRequirementsSchema = z9.object({
+  /** Budget massimo di token (input + output) per questo step */
+  maxTokenBudget: z9.number().positive().optional(),
+  /** Timeout in millisecondi */
+  timeoutMs: z9.number().positive().optional(),
+  /** Numero massimo di retry in caso di fallimento */
+  maxRetries: z9.number().int().min(0).optional().default(0),
+  /** Modello preferito (override del default del piano) */
+  preferredModel: z9.string().optional(),
+  /** Livello di concorrenza massimo per sotto-step paralleli */
+  maxConcurrency: z9.number().int().positive().optional().default(5)
+});
+var IOFieldSchema = z9.object({
+  name: z9.string().describe("Nome del campo"),
+  type: z9.enum(["string", "number", "boolean", "array", "object", "any"]).describe("Tipo del campo"),
+  description: z9.string().optional(),
+  required: z9.boolean().default(true)
+});
+var StepContractSchema = z9.object({
+  /** Campi di input attesi — cosa serve allo step per eseguire */
+  inputs: z9.array(IOFieldSchema).default([]),
+  /** Campi di output prodotti — cosa produce lo step */
+  outputs: z9.array(IOFieldSchema).default([])
+});
+var StepResultSchema = z9.object({
+  /** Output testuale prodotto */
+  output: z9.string().optional(),
+  /** Dati strutturati di output (match con contract.outputs) */
+  data: z9.record(z9.string(), z9.unknown()).optional(),
+  /** Uso token */
+  tokenUsage: z9.object({ input: z9.number(), output: z9.number() }).optional(),
+  /** Durata in ms */
+  durationMs: z9.number().optional(),
+  /** Errore se fallito */
+  error: z9.string().optional()
+});
+var StepConditionSchema = z9.object({
+  /** Espressione condizionale (riferimenti a output di step precedenti) */
+  expression: z9.string().describe(
+    "Espressione valutabile, es: 'steps.auth-design.status === completed'"
+  ),
+  /** ID dello step da eseguire se la condizione è vera */
+  ifTrueStepId: z9.string().optional(),
+  /** ID dello step da eseguire se la condizione è falsa */
+  ifFalseStepId: z9.string().optional()
+});
+var LoopConfigSchema = z9.object({
+  /** Condizione di continuazione */
+  condition: z9.string().describe(
+    "Espressione per continuare il loop, es: 'iteration < 3 && !steps.validate.data.allPassing'"
+  ),
+  /** Numero massimo di iterazioni (safety) */
+  maxIterations: z9.number().int().positive().default(10),
+  /** ID dello step che funge da corpo del loop */
+  bodyStepIds: z9.array(z9.string()).min(1)
+});
+var BaseSubStepSchema = z9.object({
+  id: z9.string().describe("ID univoco del sotto-step (kebab-case)"),
+  title: z9.string().describe("Titolo breve del sotto-step"),
+  description: z9.string().optional(),
+  status: StepStatusSchema.default("idle"),
+  executionMode: StepExecutionModeSchema.default("sequential"),
+  contract: StepContractSchema.optional(),
+  resources: ResourceRequirementsSchema.optional(),
+  result: StepResultSchema.optional(),
+  /** Istruzioni/prompt per l'agente che esegue questo sotto-step */
+  prompt: z9.string().optional(),
+  /** Tool specifici richiesti per questo sotto-step */
+  requiredTools: z9.array(z9.string()).default([])
+});
+var SubStepSchema = BaseSubStepSchema.extend({
+  children: z9.lazy(() => z9.array(SubStepSchema)).optional()
+});
+var StepSchema = z9.object({
+  id: z9.string().describe("ID univoco dello step (kebab-case)"),
+  title: z9.string().describe("Titolo breve dello step"),
+  description: z9.string().optional().describe("Descrizione dettagliata"),
+  /** Modalità di esecuzione */
+  executionMode: StepExecutionModeSchema.default("sequential"),
+  /** Stato corrente */
+  status: StepStatusSchema.default("idle"),
+  /** Priorità */
+  priority: StepPrioritySchema.default("medium"),
+  /** Contratto input/output strutturato */
+  contract: StepContractSchema.default({ inputs: [], outputs: [] }),
+  /** Requisiti di risorse */
+  resources: ResourceRequirementsSchema.optional(),
+  /** Dipendenze esplicite: ID di step nella stessa fase o in fasi precedenti */
+  dependencies: z9.array(z9.string()).default([]),
+  /** Istruzioni/prompt per l'agente */
+  prompt: z9.string().optional().describe(
+    "Prompt specifico per l'agente che esegue questo step"
+  ),
+  /** Tool specifici richiesti */
+  requiredTools: z9.array(z9.string()).default([]),
+  /** Sotto-step (gerarchia ricorsiva) */
+  subSteps: z9.array(SubStepSchema).default([]),
+  /** Condizione (solo se executionMode === 'conditional') */
+  condition: StepConditionSchema.optional(),
+  /** Configurazione loop (solo se executionMode === 'loop') */
+  loopConfig: LoopConfigSchema.optional(),
+  /** Risultato dell'esecuzione */
+  result: StepResultSchema.optional(),
+  /** Timestamp */
+  createdAt: z9.number().default(() => Date.now()),
+  updatedAt: z9.number().default(() => Date.now()),
+  startedAt: z9.number().optional(),
+  completedAt: z9.number().optional(),
+  /** Metadati arbitrari */
+  metadata: z9.record(z9.string(), z9.unknown()).optional()
+});
+var PhaseSchema = z9.object({
+  id: z9.string().describe("ID univoco della fase (kebab-case)"),
+  title: z9.string().describe("Titolo della fase"),
+  description: z9.string().optional(),
+  /** Come eseguire gli step dentro questa fase */
+  executionMode: StepExecutionModeSchema.default("sequential"),
+  /** Stato derivato dagli step contenuti */
+  status: StepStatusSchema.default("idle"),
+  /** Step contenuti in questa fase */
+  steps: z9.array(StepSchema).min(1).describe("Step della fase"),
+  /** Ordine (per fasi sequenziali nel piano) */
+  order: z9.number().int().min(0).default(0),
+  /** Dipendenze da altre fasi (ID) */
+  dependencies: z9.array(z9.string()).default([]),
+  /** Requisiti di risorse per l'intera fase */
+  resources: ResourceRequirementsSchema.optional(),
+  /** Timestamp */
+  createdAt: z9.number().default(() => Date.now()),
+  updatedAt: z9.number().default(() => Date.now())
+});
+var PlanMetadataSchema = z9.object({
+  /** Chi ha creato il piano (agente o umano) */
+  createdBy: z9.string().default("agent"),
+  /** Versione del piano (incrementa ad ogni modifica) */
+  version: z9.number().int().min(1).default(1),
+  /** Tag liberi per classificazione */
+  tags: z9.array(z9.string()).default([]),
+  /** Obiettivo di alto livello che il piano deve raggiungere */
+  goal: z9.string().describe("Obiettivo principale del piano"),
+  /** Contesto/vincoli aggiuntivi */
+  constraints: z9.array(z9.string()).default([]),
+  /** Stima dei token totali per l'intero piano */
+  estimatedTotalTokens: z9.number().optional(),
+  /** Stima della durata totale in ms */
+  estimatedDurationMs: z9.number().optional()
+});
+var PlanSchema = z9.object({
+  id: z9.string().describe("ID univoco del piano (kebab-case)"),
+  title: z9.string().describe("Titolo del piano"),
+  description: z9.string().optional().describe("Descrizione del piano"),
+  /** Stato globale del piano */
+  status: PlanStatusSchema.default("draft"),
+  /** Metadata del piano */
+  metadata: PlanMetadataSchema,
+  /** Fasi del piano (ordinate) */
+  phases: z9.array(PhaseSchema).min(1).describe("Fasi del piano"),
+  /** Configurazione risorse globali */
+  globalResources: ResourceRequirementsSchema.optional(),
+  /** Timestamp */
+  createdAt: z9.number().default(() => Date.now()),
+  updatedAt: z9.number().default(() => Date.now()),
+  startedAt: z9.number().optional(),
+  completedAt: z9.number().optional()
+});
+var PlanEventTypeSchema = z9.enum([
+  "plan:created",
+  "plan:started",
+  "plan:paused",
+  "plan:resumed",
+  "plan:completed",
+  "plan:failed",
+  "plan:cancelled",
+  "plan:updated",
+  "phase:started",
+  "phase:completed",
+  "phase:failed",
+  "step:started",
+  "step:completed",
+  "step:failed",
+  "step:skipped",
+  "step:blocked",
+  "step:retrying",
+  "substep:started",
+  "substep:completed",
+  "substep:failed"
+]);
+var PlanEventSchema = z9.object({
+  type: PlanEventTypeSchema,
+  planId: z9.string(),
+  phaseId: z9.string().optional(),
+  stepId: z9.string().optional(),
+  subStepId: z9.string().optional(),
+  timestamp: z9.number().default(() => Date.now()),
+  data: z9.record(z9.string(), z9.unknown()).optional()
+});
+var StepProgressSchema = z9.object({
+  stepId: z9.string(),
+  title: z9.string(),
+  status: StepStatusSchema,
+  /** Progresso dei sotto-step (0.0 - 1.0) */
+  progress: z9.number().min(0).max(1).default(0),
+  /** Numero sotto-step completati / totali */
+  subStepsDone: z9.number().int().min(0).default(0),
+  subStepsTotal: z9.number().int().min(0).default(0)
+});
+var PhaseProgressSchema = z9.object({
+  phaseId: z9.string(),
+  title: z9.string(),
+  status: StepStatusSchema,
+  progress: z9.number().min(0).max(1).default(0),
+  steps: z9.array(StepProgressSchema)
+});
+var PlanProgressSchema = z9.object({
+  planId: z9.string(),
+  title: z9.string(),
+  status: PlanStatusSchema,
+  /** Progresso globale (0.0 - 1.0) */
+  progress: z9.number().min(0).max(1).default(0),
+  /** Conteggi globali */
+  totalSteps: z9.number().int().min(0),
+  completedSteps: z9.number().int().min(0),
+  failedSteps: z9.number().int().min(0),
+  /** Dettaglio per fase */
+  phases: z9.array(PhaseProgressSchema),
+  /** Durata totale fino ad ora */
+  elapsedMs: z9.number().optional(),
+  /** Token usati fino ad ora */
+  tokenUsage: z9.object({ input: z9.number(), output: z9.number() }).optional()
+});
+function validatePlan(plan) {
+  const errors = [];
+  const warnings = [];
+  const allStepIds = /* @__PURE__ */ new Set();
+  const allPhaseIds = /* @__PURE__ */ new Set();
+  for (const phase of plan.phases) {
+    if (allPhaseIds.has(phase.id)) {
+      errors.push(`ID fase duplicato: "${phase.id}"`);
+    }
+    allPhaseIds.add(phase.id);
+    for (const step of phase.steps) {
+      if (allStepIds.has(step.id)) {
+        errors.push(`ID step duplicato: "${step.id}"`);
+      }
+      allStepIds.add(step.id);
+      collectSubStepIds(step.subSteps, allStepIds, errors);
+    }
+  }
+  for (const phase of plan.phases) {
+    for (const dep of phase.dependencies) {
+      if (!allPhaseIds.has(dep)) {
+        errors.push(`Fase "${phase.id}" dipende da fase inesistente "${dep}"`);
+      }
+      if (dep === phase.id) {
+        errors.push(`Fase "${phase.id}" dipende da se stessa`);
+      }
+    }
+    for (const step of phase.steps) {
+      for (const dep of step.dependencies) {
+        if (!allStepIds.has(dep)) {
+          errors.push(
+            `Step "${step.id}" dipende da step inesistente "${dep}"`
+          );
+        }
+        if (dep === step.id) {
+          errors.push(`Step "${step.id}" dipende da se stesso`);
+        }
+      }
+      if (step.executionMode === "conditional" && !step.condition) {
+        errors.push(
+          `Step "${step.id}" \xE8 condizionale ma manca la configurazione condition`
+        );
+      }
+      if (step.executionMode === "loop" && !step.loopConfig) {
+        errors.push(
+          `Step "${step.id}" \xE8 loop ma manca la configurazione loopConfig`
+        );
+      }
+      if (step.contract.inputs.length === 0 && step.dependencies.length > 0) {
+        warnings.push(
+          `Step "${step.id}" ha dipendenze ma nessun input definito nel contratto`
+        );
+      }
+    }
+  }
+  const phaseDepErrors = detectCycles(
+    plan.phases.map((p) => p.id),
+    plan.phases.reduce(
+      (acc, p) => {
+        acc[p.id] = p.dependencies;
+        return acc;
+      },
+      {}
+    )
+  );
+  errors.push(...phaseDepErrors);
+  return { valid: errors.length === 0, errors, warnings };
+}
+function collectSubStepIds(subSteps, allIds, errors) {
+  for (const ss of subSteps) {
+    if (allIds.has(ss.id)) {
+      errors.push(`ID sotto-step duplicato: "${ss.id}"`);
+    }
+    allIds.add(ss.id);
+    if (ss.children) {
+      collectSubStepIds(ss.children, allIds, errors);
+    }
+  }
+}
+function detectCycles(nodeIds, deps) {
+  const errors = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  const visit = (id) => {
+    if (stack.has(id)) {
+      errors.push(`Ciclo rilevato che coinvolge "${id}"`);
+      return;
+    }
+    if (visited.has(id)) return;
+    stack.add(id);
+    for (const dep of deps[id] ?? []) {
+      visit(dep);
+    }
+    stack.delete(id);
+    visited.add(id);
+  };
+  for (const id of nodeIds) {
+    visit(id);
+  }
+  return errors;
+}
+function isValidStepTransition(from, to) {
+  return STEP_STATUS_TRANSITIONS[from]?.includes(to) ?? false;
+}
+function calculateProgress(plan) {
+  let totalSteps = 0;
+  let completedSteps = 0;
+  let failedSteps = 0;
+  const phaseProgresses = plan.phases.map((phase) => {
+    const stepProgresses = phase.steps.map((step) => {
+      totalSteps++;
+      const subTotal = countSubSteps(step.subSteps);
+      const subDone = countCompletedSubSteps(step.subSteps);
+      if (step.status === "completed") completedSteps++;
+      if (step.status === "failed") failedSteps++;
+      const stepProgress = step.status === "completed" ? 1 : step.status === "running" && subTotal > 0 ? subDone / subTotal : 0;
+      return {
+        stepId: step.id,
+        title: step.title,
+        status: step.status,
+        progress: stepProgress,
+        subStepsDone: subDone,
+        subStepsTotal: subTotal
+      };
+    });
+    const phaseTotal = stepProgresses.length;
+    const phaseProgress = phaseTotal > 0 ? stepProgresses.reduce((sum, s) => sum + s.progress, 0) / phaseTotal : 0;
+    const phaseStatus = derivePhaseStatus(phase.steps);
+    return {
+      phaseId: phase.id,
+      title: phase.title,
+      status: phaseStatus,
+      progress: phaseProgress,
+      steps: stepProgresses
+    };
+  });
+  const globalProgress = totalSteps > 0 ? completedSteps / totalSteps : 0;
+  const elapsedMs = plan.startedAt ? Date.now() - plan.startedAt : void 0;
+  return {
+    planId: plan.id,
+    title: plan.title,
+    status: plan.status,
+    progress: globalProgress,
+    totalSteps,
+    completedSteps,
+    failedSteps,
+    phases: phaseProgresses,
+    elapsedMs
+  };
+}
+function countSubSteps(subSteps) {
+  let count = 0;
+  for (const ss of subSteps) {
+    count++;
+    if (ss.children) count += countSubSteps(ss.children);
+  }
+  return count;
+}
+function countCompletedSubSteps(subSteps) {
+  let count = 0;
+  for (const ss of subSteps) {
+    if (ss.status === "completed") count++;
+    if (ss.children) count += countCompletedSubSteps(ss.children);
+  }
+  return count;
+}
+function derivePhaseStatus(steps) {
+  if (steps.every((s) => s.status === "completed")) return "completed";
+  if (steps.some((s) => s.status === "failed")) return "failed";
+  if (steps.some((s) => s.status === "running")) return "running";
+  if (steps.some((s) => s.status === "pending")) return "pending";
+  if (steps.some((s) => s.status === "blocked")) return "blocked";
+  return "idle";
+}
+
+// src/tools/planning/plan-shared.ts
+var PLAN_PATH = "plan.json";
+async function loadPlan(fs) {
+  const exists = await fs.exists(PLAN_PATH, "persistent");
+  if (!exists) return null;
+  const raw = await fs.read(PLAN_PATH, "persistent");
+  return JSON.parse(raw);
+}
+async function savePlan(fs, plan) {
+  await fs.write(PLAN_PATH, JSON.stringify(plan, null, 2), "persistent");
+}
+
+// src/tools/planning/plan-create.tool.ts
+var StepInputSchema = z10.object({
+  id: z10.string().describe("ID univoco dello step (kebab-case)"),
+  title: z10.string().describe("Titolo breve"),
+  description: z10.string().optional(),
+  executionMode: StepExecutionModeSchema.optional(),
+  priority: StepPrioritySchema.optional(),
+  prompt: z10.string().optional().describe("Istruzioni per l'agente"),
+  dependencies: z10.array(z10.string()).optional(),
+  requiredTools: z10.array(z10.string()).optional(),
+  inputs: z10.array(IOFieldSchema).optional().describe("Contratto input"),
+  outputs: z10.array(IOFieldSchema).optional().describe("Contratto output"),
+  maxTokenBudget: z10.number().optional(),
+  timeoutMs: z10.number().optional(),
+  subSteps: z10.array(z10.object({
+    id: z10.string(),
+    title: z10.string(),
+    description: z10.string().optional(),
+    prompt: z10.string().optional()
+  })).optional()
+});
+var PhaseInputSchema = z10.object({
+  id: z10.string().describe("ID univoco della fase (kebab-case)"),
+  title: z10.string().describe("Titolo della fase"),
+  description: z10.string().optional(),
+  executionMode: StepExecutionModeSchema.optional(),
+  dependencies: z10.array(z10.string()).optional(),
+  steps: z10.array(StepInputSchema).min(1)
+});
+function createPlanCreateTool(fs) {
+  return tool({
+    description: "Crea un piano strutturato gerarchico con fasi, step e sotto-step. Ogni step ha contratti input/output, priorit\xE0, risorse e dipendenze. Supporta esecuzione sequenziale, parallela, condizionale e loop.",
+    inputSchema: z10.object({
+      id: z10.string().describe("ID univoco del piano (kebab-case)"),
+      title: z10.string().describe("Titolo del piano"),
+      description: z10.string().optional(),
+      goal: z10.string().describe("Obiettivo principale del piano"),
+      tags: z10.array(z10.string()).optional(),
+      constraints: z10.array(z10.string()).optional(),
+      phases: z10.array(PhaseInputSchema).min(1).describe("Fasi del piano"),
+      maxTokenBudget: z10.number().optional(),
+      timeoutMs: z10.number().optional()
+    }),
+    execute: async (input) => {
+      const now = Date.now();
+      const phases = input.phases.map((p, idx) => ({
+        id: p.id,
+        title: p.title,
+        description: p.description,
+        executionMode: p.executionMode ?? "sequential",
+        status: "idle",
+        order: idx,
+        dependencies: p.dependencies ?? [],
+        steps: p.steps.map((s) => ({
+          id: s.id,
+          title: s.title,
+          description: s.description,
+          executionMode: s.executionMode ?? "sequential",
+          status: "idle",
+          priority: s.priority ?? "medium",
+          contract: {
+            inputs: s.inputs ?? [],
+            outputs: s.outputs ?? []
+          },
+          resources: s.maxTokenBudget || s.timeoutMs ? {
+            maxTokenBudget: s.maxTokenBudget,
+            timeoutMs: s.timeoutMs,
+            maxRetries: 0,
+            maxConcurrency: 5
+          } : void 0,
+          dependencies: s.dependencies ?? [],
+          prompt: s.prompt,
+          requiredTools: s.requiredTools ?? [],
+          subSteps: (s.subSteps ?? []).map((ss) => ({
+            id: ss.id,
+            title: ss.title,
+            description: ss.description,
+            prompt: ss.prompt,
+            status: "idle",
+            executionMode: "sequential",
+            requiredTools: []
+          })),
+          createdAt: now,
+          updatedAt: now
+        })),
+        createdAt: now,
+        updatedAt: now
+      }));
+      const plan = PlanSchema.parse({
+        id: input.id,
+        title: input.title,
+        description: input.description,
+        status: "draft",
+        metadata: {
+          goal: input.goal,
+          createdBy: "agent",
+          version: 1,
+          tags: input.tags ?? [],
+          constraints: input.constraints ?? []
+        },
+        phases,
+        globalResources: input.maxTokenBudget || input.timeoutMs ? {
+          maxTokenBudget: input.maxTokenBudget,
+          timeoutMs: input.timeoutMs,
+          maxRetries: 0,
+          maxConcurrency: 5
+        } : void 0,
+        createdAt: now,
+        updatedAt: now
+      });
+      const validation = validatePlan(plan);
+      if (!validation.valid) {
+        return `Errore nella creazione del piano:
+${validation.errors.join("\n")}`;
+      }
+      await savePlan(fs, plan);
+      const totalSteps = plan.phases.reduce((sum, p) => sum + p.steps.length, 0);
+      const warnings = validation.warnings.length > 0 ? `
+Warning: ${validation.warnings.join("; ")}` : "";
+      return `Piano "${plan.title}" creato con successo.
+ID: ${plan.id}
+Fasi: ${plan.phases.length}
+Step totali: ${totalSteps}
+Stato: ${plan.status}` + warnings;
+    }
+  });
+}
+
+// src/tools/planning/plan-update.tool.ts
+import { z as z11 } from "zod";
+function createPlanUpdateTool(fs) {
+  return tool({
+    description: "Modifica un piano esistente a runtime: aggiorna stato, aggiungi/rimuovi step, modifica prompt, priorit\xE0, dipendenze. Supporta transizioni di stato validate.",
+    inputSchema: z11.object({
+      action: z11.enum([
+        "update_step",
+        "add_step",
+        "remove_step",
+        "update_phase",
+        "add_phase",
+        "update_plan_status",
+        "set_result"
+      ]).describe("Tipo di modifica"),
+      // Per update_step / add_step / remove_step
+      phaseId: z11.string().optional().describe("ID della fase target"),
+      stepId: z11.string().optional().describe("ID dello step target"),
+      // Campi aggiornabili
+      status: StepStatusSchema.optional(),
+      title: z11.string().optional(),
+      description: z11.string().optional(),
+      prompt: z11.string().optional(),
+      priority: StepPrioritySchema.optional(),
+      executionMode: StepExecutionModeSchema.optional(),
+      dependencies: z11.array(z11.string()).optional(),
+      requiredTools: z11.array(z11.string()).optional(),
+      inputs: z11.array(IOFieldSchema).optional(),
+      outputs: z11.array(IOFieldSchema).optional(),
+      // Per set_result
+      resultOutput: z11.string().optional(),
+      resultData: z11.record(z11.string(), z11.unknown()).optional(),
+      // Per add_phase
+      phaseTitle: z11.string().optional(),
+      phaseOrder: z11.number().optional(),
+      // Per update_plan_status
+      planStatus: z11.enum(["draft", "active", "paused", "completed", "failed", "cancelled"]).optional()
+    }),
+    execute: async (input) => {
+      const plan = await loadPlan(fs);
+      if (!plan) return "Nessun piano trovato. Usa plan_create prima.";
+      const now = Date.now();
+      switch (input.action) {
+        case "update_step": {
+          if (!input.stepId) return "stepId richiesto per update_step";
+          const { phase, step } = findStep(plan, input.stepId);
+          if (!step) return `Step "${input.stepId}" non trovato`;
+          if (input.status && input.status !== step.status) {
+            if (!isValidStepTransition(step.status, input.status)) {
+              return `Transizione non valida: "${step.status}" \u2192 "${input.status}" per step "${step.id}"`;
+            }
+            step.status = input.status;
+            if (input.status === "running") step.startedAt = now;
+            if (input.status === "completed" || input.status === "failed") {
+              step.completedAt = now;
+            }
+          }
+          if (input.title) step.title = input.title;
+          if (input.description) step.description = input.description;
+          if (input.prompt) step.prompt = input.prompt;
+          if (input.priority) step.priority = input.priority;
+          if (input.executionMode) step.executionMode = input.executionMode;
+          if (input.dependencies) step.dependencies = input.dependencies;
+          if (input.requiredTools) step.requiredTools = input.requiredTools;
+          if (input.inputs) step.contract.inputs = input.inputs;
+          if (input.outputs) step.contract.outputs = input.outputs;
+          step.updatedAt = now;
+          plan.updatedAt = now;
+          plan.metadata.version++;
+          await savePlan(fs, plan);
+          return `Step "${step.id}" aggiornato (v${plan.metadata.version}).`;
+        }
+        case "add_step": {
+          if (!input.phaseId) return "phaseId richiesto per add_step";
+          if (!input.stepId || !input.title) return "stepId e title richiesti per add_step";
+          const phase = plan.phases.find((p) => p.id === input.phaseId);
+          if (!phase) return `Fase "${input.phaseId}" non trovata`;
+          const newStep = {
+            id: input.stepId,
+            title: input.title,
+            description: input.description,
+            executionMode: input.executionMode ?? "sequential",
+            status: "idle",
+            priority: input.priority ?? "medium",
+            contract: {
+              inputs: input.inputs ?? [],
+              outputs: input.outputs ?? []
+            },
+            dependencies: input.dependencies ?? [],
+            prompt: input.prompt,
+            requiredTools: input.requiredTools ?? [],
+            subSteps: [],
+            createdAt: now,
+            updatedAt: now
+          };
+          phase.steps.push(newStep);
+          phase.updatedAt = now;
+          plan.updatedAt = now;
+          plan.metadata.version++;
+          const validation = validatePlan(plan);
+          if (!validation.valid) {
+            phase.steps.pop();
+            return `Errore: lo step creerebbe problemi:
+${validation.errors.join("\n")}`;
+          }
+          await savePlan(fs, plan);
+          return `Step "${input.stepId}" aggiunto alla fase "${input.phaseId}" (v${plan.metadata.version}).`;
+        }
+        case "remove_step": {
+          if (!input.stepId) return "stepId richiesto per remove_step";
+          const { phase } = findStep(plan, input.stepId);
+          if (!phase) return `Step "${input.stepId}" non trovato`;
+          phase.steps = phase.steps.filter((s) => s.id !== input.stepId);
+          phase.updatedAt = now;
+          plan.updatedAt = now;
+          plan.metadata.version++;
+          await savePlan(fs, plan);
+          return `Step "${input.stepId}" rimosso (v${plan.metadata.version}).`;
+        }
+        case "update_phase": {
+          if (!input.phaseId) return "phaseId richiesto per update_phase";
+          const phase = plan.phases.find((p) => p.id === input.phaseId);
+          if (!phase) return `Fase "${input.phaseId}" non trovata`;
+          if (input.title) phase.title = input.title;
+          if (input.description) phase.description = input.description;
+          if (input.executionMode) phase.executionMode = input.executionMode;
+          if (input.dependencies) phase.dependencies = input.dependencies;
+          phase.updatedAt = now;
+          plan.updatedAt = now;
+          plan.metadata.version++;
+          await savePlan(fs, plan);
+          return `Fase "${phase.id}" aggiornata (v${plan.metadata.version}).`;
+        }
+        case "add_phase": {
+          if (!input.phaseId || !input.phaseTitle) {
+            return "phaseId e phaseTitle richiesti per add_phase";
+          }
+          const newPhase = {
+            id: input.phaseId,
+            title: input.phaseTitle,
+            description: input.description,
+            executionMode: input.executionMode ?? "sequential",
+            status: "idle",
+            steps: [],
+            order: input.phaseOrder ?? plan.phases.length,
+            dependencies: input.dependencies ?? [],
+            createdAt: now,
+            updatedAt: now
+          };
+          plan.phases.push(newPhase);
+          plan.updatedAt = now;
+          plan.metadata.version++;
+          await savePlan(fs, plan);
+          return `Fase "${input.phaseId}" aggiunta (v${plan.metadata.version}). Aggiungi step con add_step.`;
+        }
+        case "update_plan_status": {
+          if (!input.planStatus) return "planStatus richiesto";
+          plan.status = input.planStatus;
+          if (input.planStatus === "active" && !plan.startedAt) {
+            plan.startedAt = now;
+          }
+          if (input.planStatus === "completed" || input.planStatus === "failed") {
+            plan.completedAt = now;
+          }
+          plan.updatedAt = now;
+          plan.metadata.version++;
+          await savePlan(fs, plan);
+          return `Piano aggiornato a stato "${input.planStatus}" (v${plan.metadata.version}).`;
+        }
+        case "set_result": {
+          if (!input.stepId) return "stepId richiesto per set_result";
+          const { step } = findStep(plan, input.stepId);
+          if (!step) return `Step "${input.stepId}" non trovato`;
+          step.result = {
+            output: input.resultOutput,
+            data: input.resultData
+          };
+          step.updatedAt = now;
+          plan.updatedAt = now;
+          await savePlan(fs, plan);
+          return `Risultato salvato per step "${input.stepId}".`;
+        }
+        default:
+          return `Azione "${input.action}" non supportata.`;
+      }
+    }
+  });
+}
+function findStep(plan, stepId) {
+  for (const phase of plan.phases) {
+    const step = phase.steps.find((s) => s.id === stepId);
+    if (step) return { phase, step };
+  }
+  return {};
+}
+
+// src/tools/planning/plan-status.tool.ts
+import { z as z12 } from "zod";
+function createPlanStatusTool(fs) {
+  return tool({
+    description: "Mostra lo stato corrente del piano con progress tree. Visualizza avanzamento per fase, step e sotto-step.",
+    inputSchema: z12.object({
+      verbose: z12.boolean().optional().default(false).describe("Se true, mostra anche i sotto-step")
+    }),
+    execute: async ({ verbose }) => {
+      const plan = await loadPlan(fs);
+      if (!plan) return "Nessun piano trovato. Usa plan_create prima.";
+      const progress = calculateProgress(plan);
+      return formatProgressTree(progress, plan, verbose);
+    }
+  });
+}
+function formatProgressTree(progress, plan, verbose) {
+  const lines = [];
+  const pct = (n) => `${Math.round(n * 100)}%`;
+  lines.push(
+    `\u{1F4CB} ${progress.title} [${progress.status}] \u2014 ${pct(progress.progress)} completato`
+  );
+  lines.push(
+    `   Step: ${progress.completedSteps}/${progress.totalSteps} completati` + (progress.failedSteps > 0 ? `, ${progress.failedSteps} falliti` : "")
+  );
+  if (progress.elapsedMs) {
+    lines.push(`   Tempo: ${Math.round(progress.elapsedMs / 1e3)}s`);
+  }
+  if (progress.tokenUsage) {
+    lines.push(
+      `   Token: ${progress.tokenUsage.input + progress.tokenUsage.output} totali`
+    );
+  }
+  lines.push(`   Versione: v${plan.metadata.version}`);
+  lines.push("");
+  for (const phase of progress.phases) {
+    const phaseIcon = statusIcon(phase.status);
+    lines.push(
+      `${phaseIcon} Fase: ${phase.title} [${phase.status}] \u2014 ${pct(phase.progress)}`
+    );
+    for (const step of phase.steps) {
+      const stepIcon = statusIcon(step.status);
+      const subInfo = step.subStepsTotal > 0 ? ` (${step.subStepsDone}/${step.subStepsTotal} sotto-step)` : "";
+      lines.push(
+        `  ${stepIcon} ${step.stepId}: ${step.title} [${step.status}]${subInfo}`
+      );
+      if (verbose) {
+        const planPhase = plan.phases.find(
+          (p) => p.steps.some((s) => s.id === step.stepId)
+        );
+        const planStep = planPhase?.steps.find((s) => s.id === step.stepId);
+        if (planStep?.subSteps.length) {
+          for (const ss of planStep.subSteps) {
+            const ssIcon = statusIcon(ss.status);
+            lines.push(`    ${ssIcon} ${ss.id}: ${ss.title} [${ss.status}]`);
+          }
+        }
+        if (planStep?.dependencies.length) {
+          lines.push(`    \u21B3 dipende da: ${planStep.dependencies.join(", ")}`);
+        }
+        if (planStep?.contract.outputs.length) {
+          const outs = planStep.contract.outputs.map((o) => o.name).join(", ");
+          lines.push(`    \u21B3 produce: ${outs}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function statusIcon(status) {
+  const icons = {
+    idle: "\u26AA",
+    pending: "\u{1F535}",
+    running: "\u{1F504}",
+    completed: "\u2705",
+    failed: "\u274C",
+    skipped: "\u23ED\uFE0F",
+    blocked: "\u{1F6AB}",
+    cancelled: "\u{1F534}"
+  };
+  return icons[status] ?? "\u2753";
+}
+
+// src/tools/planning/plan-visualize.tool.ts
+import { z as z13 } from "zod";
+function createPlanVisualizeTool(fs) {
+  return tool({
+    description: "Visualizza il piano come diagramma ASCII o Mermaid. Mostra la gerarchia fasi/step e le dipendenze.",
+    inputSchema: z13.object({
+      format: z13.enum(["ascii", "mermaid"]).default("ascii").describe("Formato di output")
+    }),
+    execute: async ({ format }) => {
+      const plan = await loadPlan(fs);
+      if (!plan) return "Nessun piano trovato. Usa plan_create prima.";
+      return format === "mermaid" ? renderMermaid(plan) : renderAscii(plan);
+    }
+  });
+}
+function renderMermaid(plan) {
+  const lines = [];
+  lines.push("```mermaid");
+  lines.push("graph TD");
+  lines.push(`  subgraph ${sanitize(plan.title)}`);
+  for (const phase of plan.phases) {
+    const phaseLabel = `phase_${phase.id}`;
+    lines.push(`    subgraph ${phaseLabel}["${phase.title} (${phase.executionMode})"]`);
+    for (const step of phase.steps) {
+      const shape = stepShape(step);
+      lines.push(`      ${step.id}${shape}`);
+    }
+    if (phase.executionMode === "sequential") {
+      for (let i = 1; i < phase.steps.length; i++) {
+        const prev = phase.steps[i - 1];
+        const curr = phase.steps[i];
+        if (!curr.dependencies.includes(prev.id)) {
+          lines.push(`      ${prev.id} --> ${curr.id}`);
+        }
+      }
+    }
+    lines.push("    end");
+  }
+  for (const phase of plan.phases) {
+    for (const step of phase.steps) {
+      for (const dep of step.dependencies) {
+        lines.push(`  ${dep} --> ${step.id}`);
+      }
+    }
+  }
+  for (const phase of plan.phases) {
+    for (const depPhaseId of phase.dependencies) {
+      const depPhase = plan.phases.find((p) => p.id === depPhaseId);
+      if (depPhase) {
+        const lastStep = depPhase.steps[depPhase.steps.length - 1];
+        const firstStep = phase.steps[0];
+        if (lastStep && firstStep) {
+          lines.push(`  ${lastStep.id} ==> ${firstStep.id}`);
+        }
+      }
+    }
+  }
+  lines.push("  end");
+  lines.push("```");
+  lines.push("");
+  lines.push("Legenda:");
+  lines.push("  [step] = sequenziale");
+  lines.push("  {step} = condizionale");
+  lines.push("  ((step)) = loop");
+  lines.push("  ==> = dipendenza tra fasi");
+  return lines.join("\n");
+}
+function stepShape(step) {
+  const label = `${step.title}`;
+  switch (step.executionMode) {
+    case "conditional":
+      return `{${label}}`;
+    case "loop":
+      return `((${label}))`;
+    case "parallel":
+      return `[/${label}/]`;
+    default:
+      return `["${label}"]`;
+  }
+}
+function sanitize(s) {
+  return s.replace(/[^a-zA-Z0-9_\- àèéìòù]/g, "_");
+}
+function renderAscii(plan) {
+  const lines = [];
+  const W = 72;
+  lines.push("\u2554" + "\u2550".repeat(W) + "\u2557");
+  lines.push(
+    "\u2551" + centerPad(`\u{1F4CB} ${plan.title}`, W) + "\u2551"
+  );
+  lines.push(
+    "\u2551" + centerPad(`Stato: ${plan.status} | v${plan.metadata.version}`, W) + "\u2551"
+  );
+  lines.push("\u2560" + "\u2550".repeat(W) + "\u2563");
+  for (let pi = 0; pi < plan.phases.length; pi++) {
+    const phase = plan.phases[pi];
+    const modeLabel = phase.executionMode === "parallel" ? "\u26A1 PARALLEL" : "\u2192 SEQ";
+    lines.push(
+      "\u2551" + leftPad(
+        `  Fase ${pi + 1}: ${phase.title} [${modeLabel}]`,
+        W
+      ) + "\u2551"
+    );
+    lines.push("\u2551" + " ".repeat(2) + "\u2500".repeat(W - 2) + "\u2551");
+    for (const step of phase.steps) {
+      const icon = statusIconAscii(step.status);
+      const depStr = step.dependencies.length > 0 ? ` \u2190 [${step.dependencies.join(", ")}]` : "";
+      const modeBadge = step.executionMode !== "sequential" ? ` (${step.executionMode})` : "";
+      lines.push(
+        "\u2551" + leftPad(
+          `    ${icon} ${step.id}: ${step.title}${modeBadge}${depStr}`,
+          W
+        ) + "\u2551"
+      );
+      for (const ss of step.subSteps) {
+        const ssIcon = statusIconAscii(ss.status);
+        lines.push(
+          "\u2551" + leftPad(`      ${ssIcon} \u2514\u2500 ${ss.id}: ${ss.title}`, W) + "\u2551"
+        );
+      }
+      if (step.contract.outputs.length > 0) {
+        const outs = step.contract.outputs.map((o) => o.name).join(", ");
+        lines.push(
+          "\u2551" + leftPad(`         \u21B3 output: ${outs}`, W) + "\u2551"
+        );
+      }
+    }
+    if (pi < plan.phases.length - 1) {
+      lines.push("\u2551" + " ".repeat(W) + "\u2551");
+      const nextPhase = plan.phases[pi + 1];
+      if (nextPhase.dependencies.includes(phase.id)) {
+        lines.push("\u2551" + centerPad("\u2502", W) + "\u2551");
+        lines.push("\u2551" + centerPad("\u25BC", W) + "\u2551");
+      } else {
+        lines.push("\u2551" + centerPad("\u250A", W) + "\u2551");
+      }
+      lines.push("\u2551" + " ".repeat(W) + "\u2551");
+    }
+  }
+  lines.push("\u255A" + "\u2550".repeat(W) + "\u255D");
+  return lines.join("\n");
+}
+function statusIconAscii(status) {
+  const icons = {
+    idle: "\u25CB",
+    pending: "\u25C9",
+    running: "\u25BA",
+    completed: "\u2713",
+    failed: "\u2717",
+    skipped: "\u2298",
+    blocked: "\u2297",
+    cancelled: "\u2296"
+  };
+  return icons[status] ?? "?";
+}
+function centerPad(text, width) {
+  const visLen = [...text].length;
+  if (visLen >= width) return text.slice(0, width);
+  const left = Math.floor((width - visLen) / 2);
+  const right = width - visLen - left;
+  return " ".repeat(left) + text + " ".repeat(right);
+}
+function leftPad(text, width) {
+  const visLen = [...text].length;
+  if (visLen >= width) return text.slice(0, width);
+  return text + " ".repeat(width - visLen);
+}
+
+// src/utils/abstract-builder.ts
+var AbstractBuilder = class {
+  build() {
+    this.validate();
+    return this.construct();
+  }
+};
+
+// src/adapters/filesystem/glob-utils.ts
+var regexCache = /* @__PURE__ */ new Map();
+var MAX_CACHE_SIZE = 500;
+function globToRegex(pattern) {
+  const cached = regexCache.get(pattern);
+  if (cached) return cached;
+  let result = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const char = pattern[i];
+    if (char === "*" && pattern[i + 1] === "*") {
+      result += ".*";
+      i += pattern[i + 2] === "/" ? 3 : 2;
+    } else if (char === "*") {
+      result += "[^/]*";
+      i++;
+    } else if (char === "?") {
+      result += "[^/]";
+      i++;
+    } else if (".+^${}()|[]\\".includes(char)) {
+      result += "\\" + char;
+      i++;
+    } else {
+      result += char;
+      i++;
+    }
+  }
+  const regex = new RegExp("^" + result + "$");
+  if (regexCache.size >= MAX_CACHE_SIZE) {
+    const oldest = regexCache.keys().next().value;
+    regexCache.delete(oldest);
+  }
+  regexCache.set(pattern, regex);
+  return regex;
+}
+
+// src/adapters/filesystem/virtual-fs.adapter.ts
+var VirtualFilesystem = class {
+  zones = {
+    transient: /* @__PURE__ */ new Map(),
+    persistent: /* @__PURE__ */ new Map()
+  };
+  basePath;
+  onSync;
+  constructor(options = {}) {
+    this.basePath = options.basePath ?? "";
+    this.onSync = options.onSync;
+  }
+  async read(path, zone = "transient") {
+    const entry = this.zones[zone].get(normalizePath(path));
+    if (!entry || entry.isDirectory) {
+      throw new Error(`File not found: ${path}`);
+    }
+    return entry.content;
+  }
+  async write(path, content, zone = "transient") {
+    const normalized = normalizePath(path);
+    this.ensureParentDirs(normalized, zone);
+    const now = Date.now();
+    const existing = this.zones[zone].get(normalized);
+    this.zones[zone].set(normalized, {
+      content,
+      isDirectory: false,
+      createdAt: existing?.createdAt ?? now,
+      modifiedAt: now
+    });
+  }
+  async exists(path, zone = "transient") {
+    return this.zones[zone].has(normalizePath(path));
+  }
+  async delete(path, zone = "transient") {
+    const normalized = normalizePath(path);
+    const store = this.zones[zone];
+    const prefix = normalized.endsWith("/") ? normalized : normalized + "/";
+    for (const key of store.keys()) {
+      if (key === normalized || key.startsWith(prefix)) {
+        store.delete(key);
+      }
+    }
+  }
+  async list(path, options = {}, zone = "transient") {
+    const normalized = normalizePath(path);
+    const prefix = normalized === "" ? "" : normalized + "/";
+    const maxDepth = options.maxDepth ?? (options.recursive ? Infinity : 1);
+    const results = [];
+    for (const [key, entry] of this.zones[zone]) {
+      if (!key.startsWith(prefix) || key === normalized) continue;
+      const relative = key.slice(prefix.length);
+      if (!options.includeHidden && relative.split("/").some((s) => s.startsWith("."))) continue;
+      const depth = relative.split("/").length;
+      if (depth > maxDepth) continue;
+      results.push({
+        name: relative.split("/").pop(),
+        path: key,
+        isDirectory: entry.isDirectory,
+        size: entry.content.length,
+        modifiedAt: entry.modifiedAt
+      });
+    }
+    return results;
+  }
+  async stat(path, zone = "transient") {
+    const entry = this.zones[zone].get(normalizePath(path));
+    if (!entry) throw new Error(`Not found: ${path}`);
+    return {
+      size: entry.content.length,
+      isDirectory: entry.isDirectory,
+      isFile: !entry.isDirectory,
+      createdAt: entry.createdAt,
+      modifiedAt: entry.modifiedAt
+    };
+  }
+  async glob(pattern, zone = "transient") {
+    const regex = globToRegex(pattern);
+    const results = [];
+    for (const [key, entry] of this.zones[zone]) {
+      if (!entry.isDirectory && regex.test(key)) {
+        results.push(key);
+      }
+    }
+    return results;
+  }
+  async search(pattern, options = {}, zone = "transient") {
+    const flags = options.caseSensitive === false ? "gi" : "g";
+    const regex = new RegExp(pattern, flags);
+    const fileRegex = options.filePattern ? globToRegex(options.filePattern) : null;
+    const results = [];
+    const max = options.maxResults ?? Infinity;
+    for (const [filePath, entry] of this.zones[zone]) {
+      if (entry.isDirectory) continue;
+      if (fileRegex && !fileRegex.test(filePath)) continue;
+      const lines = entry.content.split("\n");
+      for (let i = 0; i < lines.length && results.length < max; i++) {
+        regex.lastIndex = 0;
+        const match = regex.exec(lines[i]);
+        if (match) {
+          results.push({
+            filePath,
+            lineNumber: i + 1,
+            lineContent: lines[i],
+            matchStart: match.index,
+            matchEnd: match.index + match[0].length
+          });
+        }
+      }
+      if (results.length >= max) break;
+    }
+    return results;
+  }
+  async syncToPersistent() {
+    if (!this.onSync) {
+      throw new Error("syncToPersistent requires an onSync callback");
+    }
+    for (const [filePath, entry] of this.zones.persistent) {
+      if (entry.isDirectory) continue;
+      const fullPath = this.basePath ? this.basePath + "/" + filePath : filePath;
+      await this.onSync(fullPath, entry.content);
+    }
+  }
+  async clearTransient() {
+    this.zones.transient.clear();
+  }
+  ensureParentDirs(filePath, zone) {
+    const parts = filePath.split("/");
+    const now = Date.now();
+    for (let i = 1; i < parts.length; i++) {
+      const dirPath = parts.slice(0, i).join("/");
+      if (dirPath && !this.zones[zone].has(dirPath)) {
+        this.zones[zone].set(dirPath, {
+          content: "",
+          isDirectory: true,
+          createdAt: now,
+          modifiedAt: now
+        });
+      }
+    }
+  }
+};
+function normalizePath(p) {
+  const segments = p.replace(/\/+/g, "/").split("/");
+  const resolved = [];
+  for (const seg of segments) {
+    if (seg === "." || seg === "") continue;
+    if (seg === "..") {
+      resolved.pop();
+    } else {
+      resolved.push(seg);
+    }
+  }
+  return resolved.join("/");
+}
+
+// src/tools/planning/index.ts
+function createPlanningTools(fs) {
+  return {
+    // Legacy (retrocompatibilità)
+    write_todos: createWriteTodosTool(fs),
+    review_todos: createReviewTodosTool(fs),
+    // Structured planning
+    plan_create: createPlanCreateTool(fs),
+    plan_update: createPlanUpdateTool(fs),
+    plan_status: createPlanStatusTool(fs),
+    plan_visualize: createPlanVisualizeTool(fs)
+  };
+}
+
+// src/tools/policy/index.ts
+import { z as z14 } from "zod";
+var policyRuleSchema = z14.object({
+  id: z14.string().min(1),
+  effect: z14.enum(["allow", "deny"]),
+  resourcePattern: z14.string().min(1),
+  serverPattern: z14.string().optional(),
+  toolPattern: z14.string().optional(),
+  priority: z14.number().int().optional(),
+  reason: z14.string().optional(),
+  context: z14.object({
+    sessionId: z14.string().optional(),
+    userId: z14.string().optional(),
+    tenantId: z14.string().optional()
+  }).optional()
+});
+function normalizeRule(input) {
+  const context = input.context ? {
+    ...input.context.sessionId ? { sessionId: input.context.sessionId } : {},
+    ...input.context.userId ? { userId: input.context.userId } : {},
+    ...input.context.tenantId ? { tenantId: input.context.tenantId } : {}
+  } : void 0;
+  return {
+    id: input.id,
+    effect: input.effect,
+    resourcePattern: input.resourcePattern,
+    ...input.serverPattern ? { serverPattern: input.serverPattern } : {},
+    ...input.toolPattern ? { toolPattern: input.toolPattern } : {},
+    ...input.priority !== void 0 ? { priority: input.priority } : {},
+    ...input.reason ? { reason: input.reason } : {},
+    ...context ? { context } : {}
+  };
+}
+function createPolicyTools(policyEngine) {
+  return {
+    policy_list_rules: tool({
+      description: "List current policy rules sorted by priority",
+      inputSchema: z14.object({}),
+      execute: async () => {
+        const rules = await policyEngine.listRules();
+        return { rules, count: rules.length };
+      }
+    }),
+    policy_add_rule: tool({
+      description: "Add a new policy rule (allow or deny)",
+      inputSchema: policyRuleSchema,
+      execute: async (input) => {
+        const rule = normalizeRule(input);
+        await policyEngine.addRule(rule);
+        return { ok: true, ruleId: rule.id };
+      }
+    }),
+    policy_remove_rule: tool({
+      description: "Remove an existing policy rule by id",
+      inputSchema: z14.object({ id: z14.string().min(1) }),
+      execute: async ({ id }) => {
+        const removed = await policyEngine.removeRule(id);
+        return { ok: true, removed, ruleId: id };
+      }
+    }),
+    policy_list_audit: tool({
+      description: "List policy audit records (most recent first)",
+      inputSchema: z14.object({ limit: z14.number().int().positive().optional() }),
+      execute: async ({ limit }) => {
+        const audit = await policyEngine.getAuditLog(limit);
+        return { audit, count: audit.length };
+      }
+    }),
+    policy_clear_audit: tool({
+      description: "Clear policy audit records",
+      inputSchema: z14.object({}),
+      execute: async () => {
+        await policyEngine.clearAuditLog();
+        return { ok: true };
+      }
+    })
+  };
+}
+
+// src/tools/subagent/dispatch.tool.ts
+import { z as z15 } from "zod";
+
+// src/tools/subagent/subagent-registry.ts
+var TERMINAL_STATES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "timeout",
+  "cancelled"
+]);
+var VALID_TRANSITIONS = /* @__PURE__ */ new Map([
+  ["queued", /* @__PURE__ */ new Set(["running", "cancelled"])],
+  ["running", /* @__PURE__ */ new Set(["streaming", "completed", "failed", "timeout", "cancelled"])],
+  ["streaming", /* @__PURE__ */ new Set(["completed", "failed", "timeout", "cancelled"])],
+  ["completed", /* @__PURE__ */ new Set()],
+  ["failed", /* @__PURE__ */ new Set()],
+  ["timeout", /* @__PURE__ */ new Set()],
+  ["cancelled", /* @__PURE__ */ new Set()]
+]);
+var DEFAULT_LIMITS = {
+  maxConcurrentPerParent: 5,
+  maxConcurrentGlobal: 50,
+  maxDepth: 3,
+  defaultTimeoutMs: 3e5,
+  maxTimeoutMs: 6e5,
+  maxQueueSize: 100,
+  gcTtlMs: 6e4,
+  gcIntervalMs: 3e4,
+  maxStepsPerSubagent: 20
+};
+var SubagentQueueFullError = class extends Error {
+  constructor(queueSize, maxSize) {
+    super(
+      `Subagent queue is full (${queueSize}/${maxSize}). Try again after some tasks complete.`
+    );
+    this.name = "SubagentQueueFullError";
+  }
+};
+var SubagentDepthExceededError = class extends Error {
+  constructor(currentDepth, maxDepth) {
+    super(
+      `Maximum subagent nesting depth exceeded (${currentDepth}/${maxDepth}).`
+    );
+    this.name = "SubagentDepthExceededError";
+  }
+};
+var SubagentQuotaExceededError = class extends Error {
+  constructor(parentId, reason) {
+    super(`Quota exceeded for parent "${parentId}": ${reason}`);
+    this.name = "SubagentQuotaExceededError";
+  }
+};
+var SubagentRegistry = class {
+  handles = /* @__PURE__ */ new Map();
+  parentIndex = /* @__PURE__ */ new Map();
+  limits;
+  eventBus;
+  telemetry;
+  hooks;
+  generateId;
+  gcTimer = null;
+  /** Listeners waiting for a specific task to reach terminal state */
+  completionListeners = /* @__PURE__ */ new Map();
+  /** Scheduler reference — set via setScheduler() after construction */
+  scheduler = null;
+  constructor(eventBus, options) {
+    this.eventBus = eventBus;
+    this.limits = { ...DEFAULT_LIMITS, ...options?.limits };
+    this.telemetry = options?.telemetry;
+    this.hooks = options?.hooks;
+    this.generateId = options?.generateId ?? (() => crypto.randomUUID());
+  }
+  /** Wire the scheduler (called during setup) */
+  setScheduler(scheduler) {
+    this.scheduler = scheduler;
+  }
+  get resourceLimits() {
+    return this.limits;
+  }
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  start() {
+    this.gcTimer = setInterval(() => this.gc(), this.limits.gcIntervalMs);
+  }
+  async shutdown() {
+    if (this.gcTimer) {
+      clearInterval(this.gcTimer);
+      this.gcTimer = null;
+    }
+    for (const handle of this.handles.values()) {
+      if (!TERMINAL_STATES.has(handle.status)) {
+        this.cancel(handle.taskId, "registry-shutdown");
+      }
+    }
+    this.handles.clear();
+    this.parentIndex.clear();
+    this.completionListeners.clear();
+  }
+  // -------------------------------------------------------------------------
+  // Dispatch
+  // -------------------------------------------------------------------------
+  dispatch(parentId, currentDepth, params) {
+    if (currentDepth >= this.limits.maxDepth) {
+      throw new SubagentDepthExceededError(currentDepth, this.limits.maxDepth);
+    }
+    const parentHandles = this.parentIndex.get(parentId);
+    const parentActive = parentHandles ? [...parentHandles].filter((id) => {
+      const h = this.handles.get(id);
+      return h && !TERMINAL_STATES.has(h.status);
+    }).length : 0;
+    if (parentActive >= this.limits.maxConcurrentPerParent) {
+      throw new SubagentQuotaExceededError(
+        parentId,
+        `max concurrent per parent (${this.limits.maxConcurrentPerParent}) reached`
+      );
+    }
+    const queuedCount = [...this.handles.values()].filter(
+      (h) => h.status === "queued"
+    ).length;
+    if (queuedCount >= this.limits.maxQueueSize) {
+      throw new SubagentQueueFullError(queuedCount, this.limits.maxQueueSize);
+    }
+    const timeoutMs = Math.min(
+      params.timeoutMs ?? this.limits.defaultTimeoutMs,
+      this.limits.maxTimeoutMs
+    );
+    const handle = {
+      taskId: this.generateId(),
+      parentId,
+      depth: currentDepth,
+      createdAt: Date.now(),
+      status: "queued",
+      statusChangedAt: Date.now(),
+      priority: params.priority ?? 5,
+      partialOutput: "",
+      finalOutput: null,
+      error: null,
+      abortController: new AbortController(),
+      prompt: params.prompt,
+      instructions: params.instructions ?? null,
+      timeoutMs,
+      timeoutTimer: null,
+      tokenUsage: { input: 0, output: 0 },
+      metadata: params.metadata ?? {}
+    };
+    this.handles.set(handle.taskId, handle);
+    if (!this.parentIndex.has(parentId)) {
+      this.parentIndex.set(parentId, /* @__PURE__ */ new Set());
+    }
+    this.parentIndex.get(parentId).add(handle.taskId);
+    this.eventBus.emit("subagent:spawn", {
+      taskId: handle.taskId,
+      parentId,
+      depth: currentDepth,
+      prompt: params.prompt,
+      priority: handle.priority
+    });
+    this.eventBus.emit("delegation:start", {
+      taskId: handle.taskId,
+      parentId,
+      depth: currentDepth,
+      prompt: params.prompt,
+      priority: handle.priority,
+      timeoutMs: handle.timeoutMs,
+      metadata: handle.metadata
+    });
+    this.telemetry?.recordMetric("subagent.dispatch.count", 1);
+    this.scheduler?.enqueue(handle);
+    return handle;
+  }
+  // -------------------------------------------------------------------------
+  // Status Transitions
+  // -------------------------------------------------------------------------
+  transition(taskId, newStatus, data) {
+    const handle = this.handles.get(taskId);
+    if (!handle) return;
+    if (TERMINAL_STATES.has(handle.status)) return;
+    const allowedTargets = VALID_TRANSITIONS.get(handle.status);
+    if (!allowedTargets || !allowedTargets.has(newStatus)) return;
+    const previousStatus = handle.status;
+    handle.status = newStatus;
+    handle.statusChangedAt = Date.now();
+    if (data?.partialOutput !== void 0) {
+      handle.partialOutput += data.partialOutput;
+    }
+    if (data?.finalOutput !== void 0) {
+      handle.finalOutput = data.finalOutput;
+    }
+    if (data?.error !== void 0) {
+      handle.error = data.error;
+    }
+    this.eventBus.emit("subagent:status-change", {
+      taskId,
+      previousStatus,
+      newStatus,
+      parentId: handle.parentId
+    });
+    this.eventBus.emit("delegation:iteration", {
+      taskId,
+      parentId: handle.parentId,
+      previousStatus,
+      status: newStatus,
+      durationMs: Date.now() - handle.createdAt,
+      tokenUsage: handle.tokenUsage
+    });
+    this.invokeIterationHook(handle, previousStatus, newStatus);
+    if (TERMINAL_STATES.has(newStatus)) {
+      if (handle.timeoutTimer) {
+        clearTimeout(handle.timeoutTimer);
+        handle.timeoutTimer = null;
+      }
+      this.eventBus.emit("subagent:complete", {
+        taskId,
+        status: newStatus,
+        parentId: handle.parentId,
+        durationMs: Date.now() - handle.createdAt,
+        tokenUsage: handle.tokenUsage
+      });
+      this.eventBus.emit("delegation:complete", {
+        taskId,
+        status: newStatus,
+        parentId: handle.parentId,
+        durationMs: Date.now() - handle.createdAt,
+        tokenUsage: handle.tokenUsage,
+        error: handle.error
+      });
+      this.telemetry?.recordMetric(`subagent.status.${newStatus}`, 1);
+      this.telemetry?.recordMetric(
+        "subagent.completion.duration_ms",
+        Date.now() - handle.createdAt
+      );
+      this.invokeCompletionHook(handle);
+      const listeners = this.completionListeners.get(taskId);
+      if (listeners) {
+        for (const cb of listeners) cb(handle);
+        this.completionListeners.delete(taskId);
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Query
+  // -------------------------------------------------------------------------
+  invokeIterationHook(handle, previousStatus, status) {
+    if (!this.hooks?.onIterationComplete) return;
+    void Promise.resolve(
+      this.hooks.onIterationComplete({
+        taskId: handle.taskId,
+        parentId: handle.parentId,
+        previousStatus,
+        status,
+        partialOutput: handle.partialOutput,
+        finalOutput: handle.finalOutput,
+        error: handle.error,
+        durationMs: Date.now() - handle.createdAt,
+        tokenUsage: handle.tokenUsage,
+        metadata: handle.metadata
+      })
+    ).then((result) => {
+      if (!result) return;
+      if (result.shouldEscalate) {
+        this.eventBus.emit("delegation:blocked", {
+          taskId: handle.taskId,
+          parentId: handle.parentId,
+          reason: result.reason ?? "delegation escalation requested",
+          score: result.score
+        });
+      }
+    }).catch(() => {
+    });
+  }
+  invokeCompletionHook(handle) {
+    if (!this.hooks?.onDelegationComplete) return;
+    void Promise.resolve(
+      this.hooks.onDelegationComplete({
+        taskId: handle.taskId,
+        parentId: handle.parentId,
+        status: handle.status,
+        finalOutput: handle.finalOutput,
+        error: handle.error,
+        durationMs: Date.now() - handle.createdAt,
+        tokenUsage: handle.tokenUsage,
+        metadata: handle.metadata
+      })
+    ).catch(() => {
+    });
+  }
+  get(taskId) {
+    return this.handles.get(taskId);
+  }
+  getByParent(parentId) {
+    const ids = this.parentIndex.get(parentId);
+    if (!ids) return [];
+    return [...ids].map((id) => this.handles.get(id)).filter(Boolean);
+  }
+  get activeCount() {
+    return [...this.handles.values()].filter(
+      (h) => h.status === "running" || h.status === "streaming"
+    ).length;
+  }
+  get queuedCount() {
+    return [...this.handles.values()].filter(
+      (h) => h.status === "queued"
+    ).length;
+  }
+  get totalCount() {
+    return this.handles.size;
+  }
+  // -------------------------------------------------------------------------
+  // Await
+  // -------------------------------------------------------------------------
+  waitForCompletion(taskId, timeoutMs) {
+    const handle = this.handles.get(taskId);
+    if (!handle) {
+      return Promise.reject(new Error(`Task "${taskId}" not found`));
+    }
+    if (TERMINAL_STATES.has(handle.status)) {
+      return Promise.resolve(handle);
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        const listeners = this.completionListeners.get(taskId);
+        if (listeners) {
+          const idx = listeners.indexOf(onComplete);
+          if (idx !== -1) listeners.splice(idx, 1);
+        }
+        resolve(handle);
+      }, timeoutMs);
+      const onComplete = (h) => {
+        clearTimeout(timer);
+        resolve(h);
+      };
+      if (!this.completionListeners.has(taskId)) {
+        this.completionListeners.set(taskId, []);
+      }
+      this.completionListeners.get(taskId).push(onComplete);
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Cancellation
+  // -------------------------------------------------------------------------
+  cancel(taskId, reason = "cancelled") {
+    const handle = this.handles.get(taskId);
+    if (!handle || TERMINAL_STATES.has(handle.status)) return false;
+    handle.abortController.abort(reason);
+    this.transition(taskId, "cancelled", { error: reason });
+    for (const h of this.handles.values()) {
+      if (h.parentId === taskId && !TERMINAL_STATES.has(h.status)) {
+        this.cancel(h.taskId, `parent-cancelled:${reason}`);
+      }
+    }
+    return true;
+  }
+  cancelAll(parentId) {
+    let count = 0;
+    const ids = this.parentIndex.get(parentId);
+    if (!ids) return 0;
+    for (const id of ids) {
+      if (this.cancel(id, "parent-shutdown")) count++;
+    }
+    return count;
+  }
+  // -------------------------------------------------------------------------
+  // Garbage Collection
+  // -------------------------------------------------------------------------
+  /** Exposed for testing */
+  gc() {
+    const now = Date.now();
+    let collected = 0;
+    for (const [taskId, handle] of this.handles) {
+      if (TERMINAL_STATES.has(handle.status) && now - handle.statusChangedAt > this.limits.gcTtlMs) {
+        this.handles.delete(taskId);
+        this.parentIndex.get(handle.parentId)?.delete(taskId);
+        this.completionListeners.delete(taskId);
+        collected++;
+      }
+      if ((handle.status === "running" || handle.status === "streaming") && now - handle.createdAt > handle.timeoutMs * 2) {
+        this.cancel(taskId, "watchdog-timeout");
+      }
+    }
+    if (this.handles.size > this.limits.maxConcurrentGlobal * 10) {
+      for (const [taskId, handle] of this.handles) {
+        if (TERMINAL_STATES.has(handle.status)) {
+          this.handles.delete(taskId);
+          this.parentIndex.get(handle.parentId)?.delete(taskId);
+          this.completionListeners.delete(taskId);
+          collected++;
+        }
+      }
+    }
+    if (collected > 0) {
+      this.telemetry?.recordMetric("subagent.gc.collected", collected);
+    }
+    this.telemetry?.recordMetric("subagent.queue.depth", this.queuedCount);
+    this.telemetry?.recordMetric("subagent.active.count", this.activeCount);
+  }
+};
+function isTerminalStatus(status) {
+  return TERMINAL_STATES.has(status);
+}
+
+// src/tools/subagent/dispatch.tool.ts
+var DispatchSubagentInputSchema = z15.object({
+  prompt: z15.string().min(1).max(1e4).describe("Task description for the subagent"),
+  instructions: z15.string().max(5e3).optional().describe("Optional system instructions for the subagent"),
+  priority: z15.number().int().min(1).max(10).default(5).describe("Priority (1=highest, 10=lowest). Default: 5"),
+  timeoutMs: z15.number().int().min(5e3).max(6e5).optional().describe("Timeout in milliseconds. Default: 300000 (5 min)"),
+  metadata: z15.record(z15.string(), z15.unknown()).optional().describe("Optional metadata to pass to the subagent")
+});
+function createDispatchTool(config) {
+  const { registry, parentId, currentDepth, hooks } = config;
+  return tool({
+    description: "Dispatch a subtask to a specialized subagent. Returns immediately with a taskId. Use poll_subagent to check progress, or await_subagent to wait for completion. You can dispatch multiple tasks in a single step for parallel execution.",
+    inputSchema: DispatchSubagentInputSchema,
+    execute: async (input) => {
+      try {
+        let prompt = input.prompt;
+        let instructions = input.instructions;
+        let priority = input.priority;
+        let timeoutMs = input.timeoutMs;
+        let metadata = input.metadata;
+        if (hooks?.onDelegationStart) {
+          const hookResult = await hooks.onDelegationStart({
+            parentId,
+            currentDepth,
+            prompt,
+            instructions,
+            priority,
+            timeoutMs,
+            metadata
+          });
+          if (hookResult?.allow === false) {
+            return JSON.stringify({
+              blocked: true,
+              error: hookResult.reason ?? "Delegation blocked by supervisor hook"
+            });
+          }
+          if (hookResult?.prompt !== void 0) {
+            prompt = hookResult.prompt;
+          }
+          if (hookResult?.instructions !== void 0) {
+            instructions = hookResult.instructions;
+          }
+          if (hookResult?.priority !== void 0) {
+            priority = hookResult.priority;
+          }
+          if (hookResult?.timeoutMs !== void 0) {
+            timeoutMs = hookResult.timeoutMs;
+          }
+          if (hookResult?.metadata !== void 0) {
+            metadata = hookResult.metadata;
+          }
+        }
+        const handle = registry.dispatch(parentId, currentDepth, {
+          prompt,
+          instructions,
+          priority,
+          timeoutMs,
+          metadata
+        });
+        return JSON.stringify({
+          taskId: handle.taskId,
+          status: "queued",
+          queuePosition: registry.queuedCount,
+          message: "Task dispatched. Use poll_subagent or await_subagent to get results."
+        });
+      } catch (error) {
+        if (error instanceof SubagentQueueFullError || error instanceof SubagentDepthExceededError || error instanceof SubagentQuotaExceededError) {
+          return JSON.stringify({ error: error.message });
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        return JSON.stringify({ error: `Dispatch failed: ${msg}` });
+      }
+    }
+  });
+}
+
+// src/tools/subagent/poll.tool.ts
+import { z as z16 } from "zod";
+var PollSubagentInputSchema = z16.object({
+  taskIds: z16.array(z16.string()).min(1).max(50).describe("Task IDs to check status for"),
+  includePartialOutput: z16.boolean().default(true).describe("Whether to include partial output from streaming tasks"),
+  maxPartialOutputLength: z16.number().int().min(0).max(1e4).default(2e3).describe("Maximum characters of partial output to return per task")
+});
+function createPollTool(config) {
+  const { registry } = config;
+  return tool({
+    description: "Check the status of dispatched subtasks. Returns current status and partial output. Never blocks \u2014 returns immediately.",
+    inputSchema: PollSubagentInputSchema,
+    execute: async (input) => {
+      const summary = {
+        total: 0,
+        queued: 0,
+        running: 0,
+        streaming: 0,
+        completed: 0,
+        failed: 0,
+        timeout: 0,
+        cancelled: 0
+      };
+      const tasks = input.taskIds.map((taskId) => {
+        summary.total++;
+        const handle = registry.get(taskId);
+        if (!handle) {
+          return {
+            taskId,
+            status: "not_found",
+            error: "Task not found",
+            durationMs: 0
+          };
+        }
+        const status = handle.status;
+        if (status in summary) summary[status]++;
+        const result = {
+          taskId,
+          status,
+          durationMs: Date.now() - handle.createdAt
+        };
+        if (input.includePartialOutput && (status === "streaming" || status === "running") && handle.partialOutput) {
+          result.partialOutput = handle.partialOutput.slice(
+            -input.maxPartialOutputLength
+          );
+        }
+        if (status === "completed" && handle.finalOutput) {
+          result.finalOutput = handle.finalOutput;
+        }
+        if ((status === "failed" || status === "timeout" || status === "cancelled") && handle.error) {
+          result.error = handle.error;
+        }
+        if (handle.tokenUsage.input > 0 || handle.tokenUsage.output > 0) {
+          result.tokenUsage = handle.tokenUsage;
+        }
+        return result;
+      });
+      return JSON.stringify({ tasks, summary }, null, 2);
+    }
+  });
+}
+
+// src/tools/subagent/await.tool.ts
+import { z as z17 } from "zod";
+var AwaitSubagentInputSchema = z17.object({
+  taskIds: z17.array(z17.string()).min(1).max(50).describe("Task IDs to wait for"),
+  timeoutMs: z17.number().int().min(1e3).max(6e5).default(6e4).describe("Maximum time to wait in milliseconds. Default: 60000"),
+  pollIntervalMs: z17.number().int().min(50).max(5e3).default(200).describe("Polling interval used for optional completion checks")
+});
+function createAwaitTool(config) {
+  const { registry, hooks } = config;
+  const wait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+  const normalizeCompletionResult = (result) => {
+    if (typeof result === "boolean") {
+      return { isComplete: result };
+    }
+    if (!result) {
+      return { isComplete: false };
+    }
+    return {
+      isComplete: result.isComplete,
+      reason: result.reason
+    };
+  };
+  return tool({
+    description: "Wait for one or more subtasks to complete. Blocks until all are done, timed out, or cancelled. Returns partial results if timeout is reached. Use poll_subagent for non-blocking checks.",
+    inputSchema: AwaitSubagentInputSchema,
+    execute: async (input) => {
+      const results = await Promise.allSettled(
+        input.taskIds.map(async (taskId) => {
+          const handle = registry.get(taskId);
+          if (!handle) {
+            return {
+              taskId,
+              status: "not_found",
+              error: "Task not found. It may have been garbage collected."
+            };
+          }
+          let completionOverride = false;
+          let completionReason;
+          let resolved = handle;
+          if (!hooks?.isTaskComplete) {
+            resolved = await registry.waitForCompletion(
+              taskId,
+              input.timeoutMs
+            );
+          } else {
+            const startedAt = Date.now();
+            let iterations = 0;
+            while (Date.now() - startedAt < input.timeoutMs) {
+              const current = registry.get(taskId);
+              if (!current) {
+                return {
+                  taskId,
+                  status: "not_found",
+                  error: "Task not found. It may have been garbage collected."
+                };
+              }
+              resolved = current;
+              if (isTerminalStatus(current.status)) {
+                break;
+              }
+              try {
+                const decision = normalizeCompletionResult(
+                  await hooks.isTaskComplete({
+                    taskId: current.taskId,
+                    parentId: current.parentId,
+                    status: current.status,
+                    partialOutput: current.partialOutput,
+                    finalOutput: current.finalOutput,
+                    error: current.error,
+                    elapsedMs: Date.now() - current.createdAt,
+                    iterations,
+                    tokenUsage: current.tokenUsage,
+                    metadata: current.metadata
+                  })
+                );
+                if (decision.isComplete) {
+                  completionOverride = true;
+                  completionReason = decision.reason;
+                  break;
+                }
+              } catch {
+              }
+              iterations++;
+              await wait(input.pollIntervalMs);
+            }
+          }
+          const response = {
+            taskId: resolved.taskId,
+            status: resolved.status,
+            output: resolved.finalOutput ?? void 0,
+            error: resolved.error ?? void 0,
+            durationMs: Date.now() - resolved.createdAt,
+            tokenUsage: resolved.tokenUsage
+          };
+          if (completionOverride) {
+            response.completionOverride = true;
+            if (completionReason) {
+              response.completionReason = completionReason;
+            }
+          }
+          return response;
+        })
+      );
+      const formatted = results.map((r) => {
+        if (r.status === "fulfilled") return r.value;
+        return {
+          status: "error",
+          error: r.reason instanceof Error ? r.reason.message : String(r.reason)
+        };
+      });
+      return JSON.stringify(formatted, null, 2);
+    }
+  });
+}
+
+// src/tools/subagent/subagent-scheduler.ts
+var DEFAULT_POOL_CONFIG = {
+  minWorkers: 2,
+  maxWorkers: 20,
+  scaleUpThreshold: 0.8,
+  scaleDownThreshold: 0.3,
+  resizeCooldownMs: 1e4
+};
+var PriorityQueue = class {
+  heap = [];
+  agingIntervalMs;
+  constructor(agingIntervalMs = 5e3) {
+    this.agingIntervalMs = agingIntervalMs;
+  }
+  get size() {
+    return this.heap.length;
+  }
+  enqueue(handle) {
+    const entry = {
+      handle,
+      effectivePriority: handle.priority,
+      enqueuedAt: Date.now()
+    };
+    this.heap.push(entry);
+    this.bubbleUp(this.heap.length - 1);
+  }
+  dequeue() {
+    if (this.heap.length === 0) return null;
+    this.refreshPriorities();
+    const top = this.heap[0];
+    const last = this.heap.pop();
+    if (this.heap.length > 0) {
+      this.heap[0] = last;
+      this.sinkDown(0);
+    }
+    return top.handle;
+  }
+  peek() {
+    return this.heap.length > 0 ? this.heap[0].handle : null;
+  }
+  remove(taskId) {
+    const idx = this.heap.findIndex((e) => e.handle.taskId === taskId);
+    if (idx === -1) return false;
+    const last = this.heap.pop();
+    if (idx < this.heap.length) {
+      this.heap[idx] = last;
+      this.bubbleUp(idx);
+      this.sinkDown(idx);
+    }
+    return true;
+  }
+  refreshPriorities() {
+    const now = Date.now();
+    let dirty = false;
+    for (const entry of this.heap) {
+      const ageBonus = Math.floor(
+        (now - entry.enqueuedAt) / this.agingIntervalMs
+      );
+      const newPriority = Math.max(1, entry.handle.priority - ageBonus);
+      if (newPriority !== entry.effectivePriority) {
+        entry.effectivePriority = newPriority;
+        dirty = true;
+      }
+    }
+    if (dirty) {
+      for (let i = Math.floor(this.heap.length / 2) - 1; i >= 0; i--) {
+        this.sinkDown(i);
+      }
+    }
+  }
+  bubbleUp(idx) {
+    while (idx > 0) {
+      const parentIdx = Math.floor((idx - 1) / 2);
+      if (this.heap[parentIdx].effectivePriority <= this.heap[idx].effectivePriority)
+        break;
+      [this.heap[parentIdx], this.heap[idx]] = [
+        this.heap[idx],
+        this.heap[parentIdx]
+      ];
+      idx = parentIdx;
+    }
+  }
+  sinkDown(idx) {
+    const length = this.heap.length;
+    while (true) {
+      let smallest = idx;
+      const left = 2 * idx + 1;
+      const right = 2 * idx + 2;
+      if (left < length && this.heap[left].effectivePriority < this.heap[smallest].effectivePriority) {
+        smallest = left;
+      }
+      if (right < length && this.heap[right].effectivePriority < this.heap[smallest].effectivePriority) {
+        smallest = right;
+      }
+      if (smallest === idx) break;
+      [this.heap[smallest], this.heap[idx]] = [
+        this.heap[idx],
+        this.heap[smallest]
+      ];
+      idx = smallest;
+    }
+  }
+};
+var SubagentScheduler = class {
+  registry;
+  queue;
+  poolConfig;
+  model;
+  limits;
+  telemetry;
+  currentPoolSize;
+  activeWorkers = 0;
+  lastResizeAt = 0;
+  drainTimer = null;
+  circuitBreakers = /* @__PURE__ */ new Map();
+  cbConfig = {
+    failureThreshold: 3,
+    monitorWindowMs: 6e4,
+    resetTimeoutMs: 3e4
+  };
+  constructor(registry, model, limits, options) {
+    this.registry = registry;
+    this.model = model;
+    this.limits = limits;
+    this.poolConfig = { ...DEFAULT_POOL_CONFIG, ...options?.poolConfig };
+    this.telemetry = options?.telemetry;
+    this.queue = new PriorityQueue();
+    this.currentPoolSize = this.poolConfig.minWorkers;
+    registry.setScheduler(this);
+  }
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  start() {
+    this.drainTimer = setInterval(() => this.drain(), 100);
+  }
+  async shutdown() {
+    if (this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = null;
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Enqueue (called by registry on dispatch)
+  // -------------------------------------------------------------------------
+  enqueue(handle) {
+    this.queue.enqueue(handle);
+    this.drain();
+  }
+  // -------------------------------------------------------------------------
+  // Metrics
+  // -------------------------------------------------------------------------
+  getMetrics() {
+    return {
+      activeWorkers: this.activeWorkers,
+      poolSize: this.currentPoolSize,
+      queueSize: this.queue.size
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Drain loop
+  // -------------------------------------------------------------------------
+  drain() {
+    while (this.queue.size > 0 && this.activeWorkers < this.currentPoolSize) {
+      const handle = this.queue.dequeue();
+      if (!handle) break;
+      if (handle.abortController.signal.aborted) {
+        this.registry.transition(handle.taskId, "cancelled", {
+          error: "cancelled-while-queued"
+        });
+        continue;
+      }
+      const taskType = this.getTaskType(handle);
+      if (this.isCircuitOpen(taskType)) {
+        this.registry.transition(handle.taskId, "failed", {
+          error: "Circuit breaker open for this task type. Too many recent failures."
+        });
+        continue;
+      }
+      this.activeWorkers++;
+      this.executeHandle(handle).finally(() => {
+        this.activeWorkers--;
+        this.maybeResize();
+        this.drain();
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Execute a single handle
+  // -------------------------------------------------------------------------
+  async executeHandle(handle) {
+    this.registry.transition(handle.taskId, "running");
+    const subVfs = new VirtualFilesystem();
+    const fsTools = createFilesystemTools(subVfs);
+    handle.timeoutTimer = setTimeout(() => {
+      handle.abortController.abort("timeout");
+      this.registry.transition(handle.taskId, "timeout", {
+        error: `Subagent timed out after ${handle.timeoutMs}ms`
+      });
+    }, handle.timeoutMs);
+    try {
+      const result = await generateText({
+        model: this.model,
+        system: handle.instructions ?? "You are a specialized subagent. Complete the task and return your findings.",
+        tools: { ...fsTools },
+        stopWhen: stepCountIs(this.limits.maxStepsPerSubagent),
+        prompt: handle.prompt,
+        abortSignal: handle.abortController.signal
+      });
+      const output = result.text || "[Subagent completed with no text output]";
+      const usage = result.usage;
+      if (usage) {
+        handle.tokenUsage.input += usage.inputTokens ?? 0;
+        handle.tokenUsage.output += usage.outputTokens ?? 0;
+      }
+      this.registry.transition(handle.taskId, "completed", {
+        finalOutput: output
+      });
+      this.recordSuccess(this.getTaskType(handle));
+    } catch (error) {
+      if (handle.abortController.signal.aborted) return;
+      const message = error instanceof Error ? error.message : String(error);
+      this.registry.transition(handle.taskId, "failed", {
+        error: message
+      });
+      this.recordFailure(this.getTaskType(handle));
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Pool Sizing
+  // -------------------------------------------------------------------------
+  maybeResize() {
+    const now = Date.now();
+    if (now - this.lastResizeAt < this.poolConfig.resizeCooldownMs) return;
+    const utilization = this.currentPoolSize > 0 ? this.activeWorkers / this.currentPoolSize : 0;
+    let newSize = this.currentPoolSize;
+    if (utilization > this.poolConfig.scaleUpThreshold) {
+      newSize = Math.min(
+        Math.ceil(this.currentPoolSize * 1.5),
+        this.poolConfig.maxWorkers
+      );
+    } else if (utilization < this.poolConfig.scaleDownThreshold) {
+      newSize = Math.max(
+        Math.floor(this.currentPoolSize * 0.75),
+        this.poolConfig.minWorkers
+      );
+    }
+    if (newSize !== this.currentPoolSize) {
+      this.currentPoolSize = newSize;
+      this.lastResizeAt = now;
+      this.telemetry?.recordMetric("subagent.pool.size", newSize);
+    }
+    this.telemetry?.recordMetric(
+      "subagent.pool.utilization",
+      utilization
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Circuit Breaker per task type
+  // -------------------------------------------------------------------------
+  getTaskType(handle) {
+    return handle.instructions ?? "__default__";
+  }
+  isCircuitOpen(taskType) {
+    const state = this.circuitBreakers.get(taskType);
+    if (!state) return false;
+    if (state.state === "open") {
+      if (Date.now() - state.lastFailure > this.cbConfig.resetTimeoutMs) {
+        state.state = "half-open";
+        return false;
+      }
+      return true;
+    }
+    return false;
+  }
+  recordFailure(taskType) {
+    const now = Date.now();
+    let state = this.circuitBreakers.get(taskType);
+    if (!state) {
+      state = { failures: [], state: "closed", lastFailure: 0 };
+      this.circuitBreakers.set(taskType, state);
+    }
+    state.failures.push(now);
+    state.lastFailure = now;
+    state.failures = state.failures.filter(
+      (t) => now - t < this.cbConfig.monitorWindowMs
+    );
+    if (state.failures.length >= this.cbConfig.failureThreshold) {
+      state.state = "open";
+      this.telemetry?.recordMetric(
+        "subagent.circuit_breaker.open",
+        1
+      );
+    }
+  }
+  recordSuccess(taskType) {
+    const state = this.circuitBreakers.get(taskType);
+    if (state?.state === "half-open") {
+      state.state = "closed";
+      state.failures = [];
+    }
+  }
+};
+
+// src/tools/subagent/index.ts
+function createAsyncSubagentTools(config) {
+  const { registry, parentId, currentDepth, hooks } = config;
+  return {
+    dispatch_subagent: createDispatchTool({
+      registry,
+      parentId,
+      currentDepth,
+      hooks
+    }),
+    poll_subagent: createPollTool({ registry }),
+    await_subagent: createAwaitTool({ registry, hooks })
+  };
+}
+
+// src/agent/tool-manager.ts
+var ToolManager = class {
+  config;
+  pluginManager;
+  circuitBreaker;
+  rateLimiter;
+  toolCache;
+  constructor(config, pluginManager, circuitBreaker, rateLimiter, toolCache) {
+    this.config = config;
+    this.pluginManager = pluginManager;
+    this.circuitBreaker = circuitBreaker;
+    this.rateLimiter = rateLimiter;
+    this.toolCache = toolCache;
+  }
+  // ---------------------------------------------------------------------------
+  // Tool registration
+  // ---------------------------------------------------------------------------
+  registerTools(target, source, sourceLabel) {
+    for (const [toolName, toolDef] of Object.entries(source)) {
+      if (toolName in target) {
+        throw new Error(`Tool "${toolName}" already registered (source: ${sourceLabel})`);
+      }
+      target[toolName] = toolDef;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Build catalog
+  // ---------------------------------------------------------------------------
+  async buildToolCatalog(runMetadata) {
+    const tools = {};
+    this.registerTools(tools, createFilesystemTools(this.config.fs), "filesystem");
+    this.registerTools(tools, this.config.extraTools ?? {}, "builder.withTools");
+    this.registerTools(tools, this.pluginManager.collectTools(), "plugins");
+    if (this.config.planning) {
+      this.registerTools(tools, createPlanningTools(this.config.fs), "planning");
+    }
+    if (this.config.subagents) {
+      const limits = {
+        ...DEFAULT_LIMITS,
+        maxDepth: this.config.subagentConfig?.maxDepth ?? DEFAULT_LIMITS.maxDepth,
+        defaultTimeoutMs: this.config.subagentConfig?.timeoutMs ?? DEFAULT_LIMITS.defaultTimeoutMs
+      };
+      const eventBus = new EventBus("subagent-bus");
+      const registry = new SubagentRegistry(eventBus, {
+        limits,
+        hooks: this.config.subagentConfig?.hooks
+      });
+      const scheduler = new SubagentScheduler(registry, this.config.model, limits);
+      scheduler.start();
+      this.registerTools(
+        tools,
+        createAsyncSubagentTools({
+          registry,
+          parentId: "root",
+          maxDepth: limits.maxDepth,
+          currentDepth: 0,
+          hooks: this.config.subagentConfig?.hooks
+        }),
+        "subagents"
+      );
+    }
+    if (this.config.mcp) {
+      const mcpDefs = await this.config.mcp.discoverTools();
+      const mcp = this.config.mcp;
+      const mcpTools = {};
+      const selection = this.extractMcpToolsetSelection(runMetadata);
+      for (const [name, def] of Object.entries(mcpDefs)) {
+        const [serverName = "mcp", ...toolParts] = name.split(":");
+        const shortName = toolParts.length > 0 ? toolParts.join(":") : name;
+        if (!this.shouldIncludeMcpTool(selection, {
+          serverName,
+          fullName: name,
+          shortName
+        })) {
+          continue;
+        }
+        mcpTools[`mcp:${name}`] = tool({
+          description: def.description,
+          inputSchema: z18.object({}).passthrough(),
+          execute: async (args) => {
+            const result = await mcp.executeTool(name, args);
+            if (result.isError) throw new Error(result.content[0]?.text ?? "MCP tool error");
+            return result.content.map((c) => c.text ?? "").join("\n");
+          }
+        });
+      }
+      this.registerTools(tools, mcpTools, "mcp");
+    }
+    if (this.config.policyEngine) {
+      this.registerTools(
+        tools,
+        createPolicyTools(this.config.policyEngine),
+        "policy"
+      );
+    }
+    return tools;
+  }
+  // ---------------------------------------------------------------------------
+  // Wrapping — delegates to standalone pure functions
+  // ---------------------------------------------------------------------------
+  wrapToolsWithApproval(tools, sessionId, eventBus, runtime) {
+    if (!this.config.approvalConfig) return;
+    const approval = new ApprovalManager(
+      this.config.approvalConfig,
+      sessionId,
+      (evt) => eventBus.emit(evt.type, evt.data)
+    );
+    applyApprovalWrapping(tools, approval, runtime);
+  }
+  wrapToolsWithResilience(tools) {
+    applyResilienceWrapping(tools, this.circuitBreaker, this.toolCache);
+  }
+  wrapToolsWithPolicy(tools, sessionId, runMetadata) {
+    if (!this.config.policyEngine) return;
+    const context = this.resolvePolicyContext(sessionId, runMetadata);
+    applyPolicyWrapping(tools, this.config.policyEngine, context);
+  }
+  wrapToolsWithPlugins(tools, pluginCtx) {
+    applyPluginWrapping(tools, this.pluginManager, pluginCtx);
+  }
+  resolvePolicyContext(sessionId, runMetadata) {
+    const base = {
+      sessionId,
+      userId: this.config.userId
+    };
+    const raw = runMetadata?.policyContext;
+    if (!raw || typeof raw !== "object") {
+      return base;
+    }
+    const candidate = raw;
+    return {
+      ...base,
+      ...candidate.sessionId ? { sessionId: candidate.sessionId } : {},
+      ...candidate.userId ? { userId: candidate.userId } : {},
+      ...candidate.tenantId ? { tenantId: candidate.tenantId } : {},
+      ...candidate.metadata && typeof candidate.metadata === "object" ? { metadata: candidate.metadata } : {}
+    };
+  }
+  createRateLimitedModel() {
+    if (!this.rateLimiter) {
+      return this.config.model;
+    }
+    const rateLimiter = this.rateLimiter;
+    const originalModel = this.config.model;
+    return new Proxy(originalModel, {
+      get(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (typeof value === "function" && prop === "doGenerate") {
+          return async function(...args) {
+            await rateLimiter.acquire();
+            return value.apply(target, args);
+          };
+        }
+        if (typeof value === "function" && prop === "doStream") {
+          return async function(...args) {
+            await rateLimiter.acquire();
+            return value.apply(target, args);
+          };
+        }
+        return value;
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // Full preparation pipeline
+  // ---------------------------------------------------------------------------
+  async prepareTools(sessionId, eventBus, runtime, runMetadata) {
+    const tools = await this.buildToolCatalog(runMetadata);
+    const toolNames = Object.keys(tools);
+    const setupCtx = this.createPluginSetupContext(sessionId, toolNames, eventBus);
+    await this.pluginManager.initialize(setupCtx);
+    const pluginCtx = this.createPluginContext(sessionId, toolNames, runMetadata);
+    this.wrapToolsWithApproval(tools, sessionId, eventBus, runtime);
+    this.wrapToolsWithResilience(tools);
+    if (this.config.policyEngine) {
+      this.wrapToolsWithPolicy(tools, sessionId, runMetadata);
+    }
+    this.wrapToolsWithPlugins(tools, pluginCtx);
+    return { tools, pluginCtx };
+  }
+  // ---------------------------------------------------------------------------
+  // Plugin context factories
+  // ---------------------------------------------------------------------------
+  createPluginContext(sessionId, toolNames, runMetadata) {
+    return {
+      sessionId,
+      agentName: this.config.name,
+      config: {
+        instructions: this.config.instructions,
+        maxSteps: this.config.maxSteps
+      },
+      filesystem: this.config.fs,
+      memory: this.config.memory,
+      learning: this.config.learning,
+      toolNames,
+      runMetadata
+    };
+  }
+  createPluginSetupContext(sessionId, toolNames, eventBus) {
+    return {
+      ...this.createPluginContext(sessionId, toolNames),
+      on: (eventType, handler) => eventBus.on(eventType, handler)
+    };
+  }
+  extractMcpToolsetSelection(runMetadata) {
+    const raw = runMetadata?.mcpToolset;
+    if (!raw || typeof raw !== "object") {
+      return void 0;
+    }
+    const normalize = (value) => {
+      if (!Array.isArray(value)) return void 0;
+      const cleaned = value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+      return cleaned.length > 0 ? cleaned : void 0;
+    };
+    const candidate = raw;
+    const selection = {
+      includeServers: normalize(candidate.includeServers),
+      excludeServers: normalize(candidate.excludeServers),
+      includeTools: normalize(candidate.includeTools),
+      excludeTools: normalize(candidate.excludeTools)
+    };
+    if (!selection.includeServers && !selection.excludeServers && !selection.includeTools && !selection.excludeTools) {
+      return void 0;
+    }
+    return selection;
+  }
+  shouldIncludeMcpTool(selection, toolInfo) {
+    if (!selection) {
+      return true;
+    }
+    if (selection.includeServers && !selection.includeServers.includes(toolInfo.serverName)) {
+      return false;
+    }
+    if (selection.excludeServers && selection.excludeServers.includes(toolInfo.serverName)) {
+      return false;
+    }
+    if (selection.includeTools) {
+      const allowed = selection.includeTools.includes(toolInfo.fullName) || selection.includeTools.includes(toolInfo.shortName);
+      if (!allowed) {
+        return false;
+      }
+    }
+    if (selection.excludeTools && (selection.excludeTools.includes(toolInfo.fullName) || selection.excludeTools.includes(toolInfo.shortName))) {
+      return false;
+    }
+    return true;
+  }
+};
+function wrapAllTools(tools, wrapFn) {
+  for (const [name, toolDef] of Object.entries(tools)) {
+    if (!toolDef) continue;
+    const maybeExecutable = toolDef;
+    if (!maybeExecutable.execute) continue;
+    const originalExecute = maybeExecutable.execute.bind(maybeExecutable);
+    maybeExecutable.execute = wrapFn(name, originalExecute);
+  }
+}
+function applyApprovalWrapping(tools, approval, runtime) {
+  let stepIndex = 0;
+  wrapAllTools(tools, (name, originalExecute) => async (...args) => {
+    const { approved, reason } = await approval.checkAndApprove(
+      name,
+      runtime.randomUUID(),
+      args[0],
+      stepIndex++
+    );
+    if (!approved) {
+      return `Tool call denied: ${reason ?? "not approved"}`;
+    }
+    return originalExecute(...args);
+  });
+}
+function applyResilienceWrapping(tools, circuitBreaker, toolCache) {
+  if (circuitBreaker) {
+    wrapAllTools(tools, (_name, originalExecute) => async (...args) => {
+      return circuitBreaker.execute(async () => originalExecute(...args));
+    });
+  }
+  if (toolCache) {
+    wrapAllTools(tools, (name, originalExecute) => async (...args) => {
+      const cacheKey = `${name}:${JSON.stringify(args)}`;
+      if (toolCache.has(cacheKey)) {
+        return toolCache.get(cacheKey);
+      }
+      const result = await originalExecute(...args);
+      toolCache.set(cacheKey, result);
+      return result;
+    });
+  }
+}
+function applyPolicyWrapping(tools, policyEngine, context) {
+  wrapAllTools(tools, (name, originalExecute) => async (...args) => {
+    if (!name.startsWith("mcp:")) {
+      return originalExecute(...args);
+    }
+    const resource = name.slice("mcp:".length);
+    const [serverName = "mcp", ...toolParts] = resource.split(":");
+    const toolName = toolParts.length > 0 ? toolParts.join(":") : resource;
+    const request = {
+      action: "invoke",
+      resource,
+      serverName,
+      toolName
+    };
+    const decision = await policyEngine.evaluate(request, context);
+    if (!decision.allowed) {
+      throw new Error(
+        `MCP policy denied (${decision.auditId}) for ${resource}: ${decision.reason ?? "access denied"}`
+      );
+    }
+    return originalExecute(...args);
+  });
+}
+function applyPluginWrapping(tools, pluginManager, pluginCtx) {
+  if (pluginManager.count === 0) return;
+  wrapAllTools(tools, (name, originalExecute) => async (...args) => {
+    const beforeResult = await pluginManager.runBeforeTool(pluginCtx, {
+      toolName: name,
+      args: args[0]
+    });
+    if (beforeResult.skip) {
+      return beforeResult.result;
+    }
+    const finalArgs = beforeResult.args !== void 0 ? beforeResult.args : args[0];
+    try {
+      const result = await originalExecute(finalArgs, ...args.slice(1));
+      await pluginManager.runAfterTool(pluginCtx, {
+        toolName: name,
+        args: finalArgs,
+        result
+      });
+      return result;
+    } catch (error) {
+      const onErrorResult = await pluginManager.runOnError(pluginCtx, {
+        error,
+        phase: "tool"
+      });
+      if (onErrorResult.suppress) return void 0;
+      throw error;
+    }
+  });
+}
+
+// src/agent/execution-engine.ts
+var ExecutionEngine = class {
+  config;
+  toolManager;
+  pluginManager;
+  eventBus;
+  tokenTracker;
+  middlewareChain;
+  constructor(config, toolManager, pluginManager, eventBus, tokenTracker, middlewareChain) {
+    this.config = config;
+    this.toolManager = toolManager;
+    this.pluginManager = pluginManager;
+    this.eventBus = eventBus;
+    this.tokenTracker = tokenTracker;
+    this.middlewareChain = middlewareChain;
+  }
+  // ---------------------------------------------------------------------------
+  // Middleware context factory
+  // ---------------------------------------------------------------------------
+  createMiddlewareContext(sessionId) {
+    return {
+      sessionId,
+      agentName: this.config.agentName,
+      timestamp: Date.now(),
+      metadata: {}
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Telemetry helper — DRY span lifecycle (try/catch/finally)
+  // ---------------------------------------------------------------------------
+  isDelegationTool(toolName) {
+    return toolName === "dispatch_subagent" || toolName === "poll_subagent" || toolName === "await_subagent";
+  }
+  async applyDelegationMessageFilter(params) {
+    const hook = this.config.delegationHooks?.messageFilter;
+    if (!hook || !this.isDelegationTool(params.toolName)) {
+      return {
+        allow: true,
+        payload: params.payload
+      };
+    }
+    try {
+      const filtered = await hook(params);
+      if (typeof filtered === "boolean") {
+        return {
+          allow: filtered,
+          payload: params.payload
+        };
+      }
+      if (!filtered) {
+        return {
+          allow: true,
+          payload: params.payload
+        };
+      }
+      return {
+        allow: filtered.allow !== false,
+        payload: filtered.payload !== void 0 ? filtered.payload : params.payload,
+        reason: filtered.reason
+      };
+    } catch {
+      return {
+        allow: true,
+        payload: params.payload
+      };
+    }
+  }
+  async withSpan(name, attrs, fn) {
+    const span = this.config.telemetry?.startSpan(name, attrs);
+    try {
+      const result = await fn();
+      span?.setStatus("OK");
+      return result;
+    } catch (error) {
+      span?.setStatus("ERROR", error instanceof Error ? error.message : String(error));
+      throw error;
+    } finally {
+      span?.end();
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Run
+  // ---------------------------------------------------------------------------
+  async run(prompt, sessionId, runtime, options = {}) {
+    const runMetadata = {
+      ...options.pluginMetadata ?? {},
+      ...options.mcpToolset ? { mcpToolset: options.mcpToolset } : {},
+      ...options.policyContext ? { policyContext: options.policyContext } : {}
+    };
+    let pluginCtx = this.toolManager.createPluginContext(
+      sessionId,
+      [],
+      runMetadata
+    );
+    try {
+      const prepared = await this.toolManager.prepareTools(
+        sessionId,
+        this.eventBus,
+        runtime,
+        runMetadata
+      );
+      const tools = prepared.tools;
+      pluginCtx = prepared.pluginCtx;
+      if (this.config.learning) {
+        const userId = this.config.userId ?? sessionId;
+        const [profile, memories] = await Promise.all([
+          this.config.learning.getProfile(userId),
+          this.config.learning.getMemories(userId, { limit: 10 })
+        ]);
+        const learningContext = this.buildLearningContext(profile, memories);
+        if (learningContext) prompt = `${learningContext}
+
+${prompt}`;
+      }
+      const beforeRunResult = await this.pluginManager.runBeforeRun(pluginCtx, { prompt });
+      if (beforeRunResult.prompt !== void 0) {
+        prompt = beforeRunResult.prompt;
+      }
+      const mwCtx = this.createMiddlewareContext(sessionId);
+      let instructions = this.config.instructions;
+      if (this.middlewareChain) {
+        const mwResult = await this.middlewareChain.runBeforeAgent(mwCtx, {
+          prompt,
+          instructions,
+          tools
+        });
+        if (mwResult.aborted) {
+          const earlyText = mwResult.earlyResult ?? "";
+          this.eventBus.emit("agent:stop", {
+            result: { text: earlyText, steps: [], sessionId, toolCalls: [] }
+          });
+          return { text: earlyText, steps: [], sessionId, toolCalls: [] };
+        }
+        prompt = mwResult.prompt;
+        instructions = mwResult.instructions;
+      }
+      this.eventBus.emit("agent:start", { prompt });
+      const cpConfig = this.config.checkpointConfig;
+      if (cpConfig?.enabled) {
+        const cp = await this.config.memory.loadLatestCheckpoint(sessionId);
+        if (cp) this.eventBus.emit("checkpoint:load", { checkpoint: cp });
+      }
+      const agentOptions = {
+        model: this.toolManager.createRateLimitedModel(),
+        system: instructions,
+        tools,
+        stopWhen: stepCountIs(this.config.maxSteps),
+        prompt
+      };
+      if (this.config.output) agentOptions.output = this.config.output;
+      const result = await this.withSpan(
+        "llm.generate",
+        { "llm.model": String(this.config.model) },
+        () => generateText(agentOptions)
+      );
+      const resultObj = result;
+      const usage = resultObj.usage;
+      if (usage) {
+        if (usage.promptTokens) {
+          this.tokenTracker.addInput(usage.promptTokens);
+          this.config.telemetry?.recordMetric("llm.tokens.input", usage.promptTokens);
+        }
+        if (usage.completionTokens) {
+          this.tokenTracker.addOutput(usage.completionTokens);
+          this.config.telemetry?.recordMetric("llm.tokens.output", usage.completionTokens);
+        }
+        if (this.config.costTracker && (usage.promptTokens || usage.completionTokens)) {
+          const modelId = this.config.model.modelId ?? "unknown";
+          const provider = this.config.model.provider ?? "unknown";
+          this.config.costTracker.recordUsage({
+            inputTokens: usage.promptTokens ?? 0,
+            outputTokens: usage.completionTokens ?? 0,
+            model: modelId,
+            provider,
+            timestamp: Date.now()
+          });
+        }
+      }
+      const steps = result.steps ?? [];
+      for (let i = 0; i < steps.length; i++) {
+        let step = steps[i];
+        const stepObj = step;
+        const toolName = stepObj?.toolName ?? `step.${i}`;
+        const toolSpanStart = Date.now();
+        try {
+          await this.withSpan(`tool.${toolName}`, { "tool.name": toolName, "step.index": i }, async () => {
+            const beforeStepResult = await this.pluginManager.runBeforeStep(pluginCtx, {
+              stepIndex: i,
+              step
+            });
+            if (beforeStepResult.skip) return;
+            if (beforeStepResult.step !== void 0) {
+              step = beforeStepResult.step;
+              steps[i] = step;
+            }
+            this.eventBus.emit("step:start", { stepIndex: i, step });
+            const toolCalls = stepObj?.toolCalls ?? [];
+            for (const tc of toolCalls) {
+              const filtered = await this.applyDelegationMessageFilter({
+                direction: "tool:call",
+                toolName: tc.toolName,
+                stepIndex: i,
+                payload: tc.args
+              });
+              if (!filtered.allow) {
+                this.eventBus.emit("delegation:message-filtered", {
+                  direction: "tool:call",
+                  toolName: tc.toolName,
+                  stepIndex: i,
+                  reason: filtered.reason
+                });
+                continue;
+              }
+              this.eventBus.emit("tool:call", {
+                toolName: tc.toolName,
+                toolCallId: tc.toolCallId,
+                args: filtered.payload,
+                stepIndex: i
+              });
+            }
+            const toolResults = stepObj?.toolResults ?? [];
+            for (const tr of toolResults) {
+              const filtered = await this.applyDelegationMessageFilter({
+                direction: "tool:result",
+                toolName: tr.toolName,
+                stepIndex: i,
+                payload: tr.result
+              });
+              if (!filtered.allow) {
+                this.eventBus.emit("delegation:message-filtered", {
+                  direction: "tool:result",
+                  toolName: tr.toolName,
+                  stepIndex: i,
+                  reason: filtered.reason
+                });
+                continue;
+              }
+              this.eventBus.emit("tool:result", {
+                toolName: tr.toolName,
+                toolCallId: tr.toolCallId,
+                result: filtered.payload,
+                stepIndex: i
+              });
+            }
+            this.eventBus.emit("step:end", { stepIndex: i, step });
+            await this.pluginManager.runAfterStep(pluginCtx, {
+              stepIndex: i,
+              step
+            });
+            const toolDurationMs = Date.now() - toolSpanStart;
+            this.config.telemetry?.recordMetric("tool.duration_ms", toolDurationMs, { tool: toolName });
+          });
+        } catch (error) {
+          const onStepError = await this.pluginManager.runOnError(pluginCtx, {
+            error,
+            phase: "step"
+          });
+          if (!onStepError.suppress) throw error;
+        }
+      }
+      if (cpConfig?.enabled) {
+        const checkpoint = {
+          id: runtime.randomUUID(),
+          sessionId,
+          stepIndex: steps.length,
+          conversation: [
+            { role: "user", content: prompt },
+            { role: "assistant", content: result.text ?? "" }
+          ],
+          todos: await this.config.memory.loadTodos(sessionId),
+          filesSnapshot: {},
+          toolResults: {},
+          generatedTokens: 0,
+          lastToolCallId: null,
+          metadata: {},
+          createdAt: Date.now()
+        };
+        await this.config.memory.saveCheckpoint(sessionId, checkpoint);
+        this.eventBus.emit("checkpoint:save", { checkpoint });
+      }
+      const allToolCalls = [];
+      for (let i = 0; i < steps.length; i++) {
+        const s = steps[i];
+        const calls = s?.toolCalls ?? [];
+        for (const tc of calls) {
+          allToolCalls.push({ name: tc.toolName, args: tc.args, stepIndex: i });
+        }
+      }
+      const agentResult = {
+        text: result.text ?? "",
+        steps,
+        sessionId,
+        output: result.output,
+        toolCalls: allToolCalls
+      };
+      if (this.middlewareChain) {
+        const mwAfterResult = await this.middlewareChain.runAfterAgent(mwCtx, {
+          prompt,
+          result: { text: agentResult.text, steps: agentResult.steps, sessionId }
+        });
+        agentResult.text = mwAfterResult.result.text;
+      }
+      this.eventBus.emit("agent:stop", { result: agentResult });
+      await this.pluginManager.runAfterRun(pluginCtx, { result: agentResult });
+      return agentResult;
+    } catch (error) {
+      const onErrorResult = await this.pluginManager.runOnError(pluginCtx, {
+        error,
+        phase: "run"
+      });
+      if (onErrorResult.suppress) {
+        return { text: "", steps: [], sessionId, toolCalls: [] };
+      }
+      this.eventBus.emit("error", { error });
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Stream
+  // ---------------------------------------------------------------------------
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async stream(params, sessionId, runtime, options = {}) {
+    let pluginCtx = this.toolManager.createPluginContext(sessionId, [], options.pluginMetadata);
+    try {
+      const prepared = await this.toolManager.prepareTools(
+        sessionId,
+        this.eventBus,
+        runtime,
+        options.pluginMetadata
+      );
+      const tools = prepared.tools;
+      pluginCtx = prepared.pluginCtx;
+      if (this.config.learning) {
+        const userId = this.config.userId ?? sessionId;
+        const [profile, memories] = await Promise.all([
+          this.config.learning.getProfile(userId),
+          this.config.learning.getMemories(userId, { limit: 10 })
+        ]);
+        const learningContext = this.buildLearningContext(profile, memories);
+        if (learningContext) {
+          params = {
+            ...params,
+            messages: [
+              { role: "system", content: learningContext },
+              ...params.messages
+            ]
+          };
+        }
+      }
+      this.eventBus.emit("agent:start", { messages: params.messages });
+      return this.withSpan("stream", { "stream.messages": params.messages.length }, async () => {
+        const streamAgentOptions = {
+          model: this.toolManager.createRateLimitedModel(),
+          system: this.config.instructions,
+          tools,
+          stopWhen: stepCountIs(this.config.maxSteps)
+        };
+        if (this.config.output) streamAgentOptions.output = this.config.output;
+        const streamResult = streamText(streamAgentOptions);
+        if (this.config.costTracker) {
+          const costTracker = this.config.costTracker;
+          const model = this.config.model;
+          const tokenTracker = this.tokenTracker;
+          return Promise.resolve(streamResult).then((stream) => {
+            const usagePromise = stream.usage ?? stream.totalUsage;
+            if (usagePromise && typeof usagePromise.then === "function") {
+              usagePromise.then((u) => {
+                if (u) {
+                  if (u.promptTokens) tokenTracker.addInput(u.promptTokens);
+                  if (u.completionTokens) tokenTracker.addOutput(u.completionTokens);
+                  if (u.promptTokens || u.completionTokens) {
+                    const modelId = model.modelId ?? "unknown";
+                    const provider = model.provider ?? "unknown";
+                    costTracker.recordUsage({
+                      inputTokens: u.promptTokens ?? 0,
+                      outputTokens: u.completionTokens ?? 0,
+                      model: modelId,
+                      provider,
+                      timestamp: Date.now()
+                    });
+                  }
+                }
+              }).catch((err) => {
+                console.warn("[usage-tracking] Failed to record usage:", err instanceof Error ? err.message : String(err));
+              });
+            }
+            return stream;
+          });
+        }
+        return streamResult;
+      });
+    } catch (error) {
+      const onErrorResult = await this.pluginManager.runOnError(pluginCtx, {
+        error,
+        phase: "stream"
+      });
+      if (onErrorResult.suppress) {
+        return new ReadableStream({ start(c) {
+          c.close();
+        } });
+      }
+      this.eventBus.emit("error", { error });
+      throw error;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Learning context
+  // ---------------------------------------------------------------------------
+  buildLearningContext(profile, memories) {
+    const parts = [];
+    if (profile) {
+      if (profile.context) parts.push(`User context: ${profile.context}`);
+      if (profile.style) parts.push(`Preferred style: ${profile.style}`);
+      if (profile.language) parts.push(`Language: ${profile.language}`);
+    }
+    if (memories.length > 0) {
+      parts.push(`Known facts about this user:
+${memories.map((m) => `- ${m.content}`).join("\n")}`);
+    }
+    return parts.length > 0 ? `[Learning Context]
+${parts.join("\n")}` : "";
+  }
+};
+
+// src/agent/lifecycle.ts
+var SHUTDOWN_TIMEOUT_MS = 3e4;
+var LifecycleManager = class {
+  _isReady = false;
+  _isShuttingDown = false;
+  hooks;
+  runningOperations = /* @__PURE__ */ new Set();
+  constructor(hooks) {
+    this.hooks = hooks;
+  }
+  async startup() {
+    if (this._isReady) return;
+    try {
+      if (this.hooks.onStartup) {
+        await this.hooks.onStartup();
+      }
+      this._isReady = true;
+    } catch (error) {
+      this._isReady = false;
+      throw error;
+    }
+  }
+  async shutdown() {
+    if (this._isShuttingDown) return;
+    this._isShuttingDown = true;
+    this._isReady = false;
+    if (this.runningOperations.size > 0) {
+      const controller = new AbortController();
+      const timeout = new Promise((resolve) => {
+        const timer = setTimeout(resolve, SHUTDOWN_TIMEOUT_MS);
+        controller.signal.addEventListener("abort", () => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+      const allOperations = Promise.all(Array.from(this.runningOperations)).then(() => {
+      }).catch((err) => {
+        console.warn("[shutdown] Error in running operation:", err instanceof Error ? err.message : String(err));
+      });
+      await Promise.race([allOperations, timeout]);
+      controller.abort();
+    }
+    try {
+      if (this.hooks.onShutdown) {
+        await this.hooks.onShutdown();
+      }
+    } finally {
+      this.runningOperations.clear();
+    }
+  }
+  async healthCheck() {
+    if (this.hooks.onHealthCheck) {
+      return this.hooks.onHealthCheck();
+    }
+    return {
+      healthy: this._isReady && !this._isShuttingDown,
+      details: {
+        lifecycle: {
+          status: this._isReady && !this._isShuttingDown ? "up" : "down",
+          message: this._isShuttingDown ? "Agent is shutting down" : this._isReady ? "Agent is ready" : "Agent not started"
+        }
+      }
+    };
+  }
+  get isReady() {
+    return this._isReady;
+  }
+  get isShuttingDown() {
+    return this._isShuttingDown;
+  }
+  /**
+   * Track a running operation for graceful shutdown.
+   * Returns a cleanup function to remove the operation from tracking.
+   */
+  trackOperation(operation) {
+    this.runningOperations.add(operation);
+    const cleanup = () => {
+      this.runningOperations.delete(operation);
+    };
+    operation.finally(cleanup);
+    return operation;
+  }
+};
+
+// src/middleware/chain.ts
+var MiddlewareChain = class {
+  middlewares = [];
+  sorted = true;
+  // ---------------------------------------------------------------------------
+  // Registration
+  // ---------------------------------------------------------------------------
+  use(middleware) {
+    if (this.middlewares.some((m) => m.name === middleware.name)) {
+      throw new Error(`Middleware "${middleware.name}" is already registered`);
+    }
+    this.middlewares.push(middleware);
+    this.sorted = false;
+  }
+  remove(name) {
+    const idx = this.middlewares.findIndex((m) => m.name === name);
+    if (idx === -1) return false;
+    this.middlewares.splice(idx, 1);
+    return true;
+  }
+  list() {
+    this.ensureSorted();
+    return this.middlewares;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------
+  async setup(ctx) {
+    this.ensureSorted();
+    for (const mw of this.middlewares) {
+      if (mw.setup) {
+        await mw.setup(ctx);
+      }
+    }
+  }
+  async teardown(ctx) {
+    for (let i = this.middlewares.length - 1; i >= 0; i--) {
+      const mw = this.middlewares[i];
+      if (mw.teardown) {
+        try {
+          await mw.teardown(ctx);
+        } catch {
+        }
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // beforeAgent — forward order, accumulate mutations
+  // ---------------------------------------------------------------------------
+  async runBeforeAgent(ctx, params) {
+    this.ensureSorted();
+    let current = { ...params };
+    for (const mw of this.middlewares) {
+      if (!mw.beforeAgent) continue;
+      let result;
+      try {
+        result = await mw.beforeAgent(ctx, current);
+      } catch (error) {
+        const shouldContinue = await this.handleError(ctx, {
+          error,
+          phase: "beforeAgent",
+          middlewareName: mw.name
+        });
+        if (!shouldContinue) throw error;
+        continue;
+      }
+      if (!result) continue;
+      if (result.abort) {
+        return {
+          ...current,
+          aborted: true,
+          earlyResult: result.earlyResult
+        };
+      }
+      current = {
+        prompt: result.prompt ?? current.prompt,
+        instructions: result.instructions ?? current.instructions,
+        tools: result.tools ? { ...current.tools, ...result.tools } : current.tools
+      };
+    }
+    return current;
+  }
+  // ---------------------------------------------------------------------------
+  // afterAgent — reverse order, accumulate mutations
+  // ---------------------------------------------------------------------------
+  async runAfterAgent(ctx, params) {
+    this.ensureSorted();
+    let current = { ...params };
+    for (let i = this.middlewares.length - 1; i >= 0; i--) {
+      const mw = this.middlewares[i];
+      if (!mw.afterAgent) continue;
+      let result;
+      try {
+        result = await mw.afterAgent(ctx, current);
+      } catch (error) {
+        const shouldContinue = await this.handleError(ctx, {
+          error,
+          phase: "afterAgent",
+          middlewareName: mw.name
+        });
+        if (!shouldContinue) throw error;
+        continue;
+      }
+      if (result?.text !== void 0) {
+        current = {
+          ...current,
+          result: { ...current.result, text: result.text }
+        };
+      }
+    }
+    return current;
+  }
+  // ---------------------------------------------------------------------------
+  // beforeTool — forward order
+  // ---------------------------------------------------------------------------
+  async runBeforeTool(ctx, params) {
+    this.ensureSorted();
+    let currentArgs = params.args;
+    for (const mw of this.middlewares) {
+      if (!mw.beforeTool) continue;
+      let result;
+      try {
+        result = await mw.beforeTool(ctx, {
+          ...params,
+          args: currentArgs
+        });
+      } catch (error) {
+        const shouldContinue = await this.handleError(ctx, {
+          error,
+          phase: "beforeTool",
+          middlewareName: mw.name
+        });
+        if (!shouldContinue) throw error;
+        continue;
+      }
+      if (!result) continue;
+      if (result.skip) {
+        return { skip: true, mockResult: result.mockResult };
+      }
+      if (result.args !== void 0) {
+        currentArgs = result.args;
+      }
+    }
+    return { args: currentArgs };
+  }
+  // ---------------------------------------------------------------------------
+  // afterTool — reverse order
+  // ---------------------------------------------------------------------------
+  async runAfterTool(ctx, params) {
+    this.ensureSorted();
+    let current = { ...params };
+    for (let i = this.middlewares.length - 1; i >= 0; i--) {
+      const mw = this.middlewares[i];
+      if (!mw.afterTool) continue;
+      let result;
+      try {
+        result = await mw.afterTool(ctx, current);
+      } catch (error) {
+        const shouldContinue = await this.handleError(ctx, {
+          error,
+          phase: "afterTool",
+          middlewareName: mw.name
+        });
+        if (!shouldContinue) throw error;
+        continue;
+      }
+      if (result?.result !== void 0) {
+        current = { ...current, result: result.result };
+      }
+    }
+    return current;
+  }
+  // ---------------------------------------------------------------------------
+  // Error handling — delegates to middleware onError hooks
+  // ---------------------------------------------------------------------------
+  async handleError(ctx, params) {
+    for (const mw of this.middlewares) {
+      if (!mw.onError) continue;
+      try {
+        const result = await mw.onError(ctx, params);
+        if (result?.suppress) return true;
+      } catch {
+      }
+    }
+    return false;
+  }
+  // ---------------------------------------------------------------------------
+  // Internal — sort by priority (stable sort)
+  // ---------------------------------------------------------------------------
+  ensureSorted() {
+    if (this.sorted) return;
+    this.middlewares.sort((a, b) => a.priority - b.priority);
+    this.sorted = true;
+  }
+};
+
+// src/agent/agent-config.ts
+var DEFAULT_APPROVAL_CONFIG = {
+  defaultMode: "approve-all",
+  requireApproval: [],
+  autoApprove: [],
+  onApprovalRequired: async () => true
+};
+var DEFAULT_CHECKPOINT_CONFIG = {
+  enabled: true,
+  baseStepInterval: 5,
+  maxCheckpoints: 10
+};
+function resolveApprovalConfig(partial) {
+  if (!partial) return { ...DEFAULT_APPROVAL_CONFIG };
+  return { ...DEFAULT_APPROVAL_CONFIG, ...partial };
+}
+function resolveCheckpointConfig(partial) {
+  if (!partial) return { ...DEFAULT_CHECKPOINT_CONFIG };
+  return { ...DEFAULT_CHECKPOINT_CONFIG, ...partial };
+}
+
+// src/adapters/memory/in-memory.adapter.ts
+var InMemoryAdapter = class _InMemoryAdapter {
+  static MAX_SESSIONS = 1e3;
+  sessionOrder = /* @__PURE__ */ new Map();
+  todosMap = /* @__PURE__ */ new Map();
+  checkpointsMap = /* @__PURE__ */ new Map();
+  conversationMap = /* @__PURE__ */ new Map();
+  metadataMap = /* @__PURE__ */ new Map();
+  trackSession(sessionId) {
+    this.sessionOrder.delete(sessionId);
+    this.sessionOrder.set(sessionId, true);
+    while (this.sessionOrder.size > _InMemoryAdapter.MAX_SESSIONS) {
+      const oldest = this.sessionOrder.keys().next().value;
+      if (oldest !== void 0) {
+        this.sessionOrder.delete(oldest);
+        this.todosMap.delete(oldest);
+        this.checkpointsMap.delete(oldest);
+        this.conversationMap.delete(oldest);
+        this.metadataMap.delete(oldest);
+      }
+    }
+  }
+  // -- Todos ------------------------------------------------------------------
+  async saveTodos(sessionId, todos) {
+    this.todosMap.set(sessionId, [...todos]);
+    this.trackSession(sessionId);
+  }
+  async loadTodos(sessionId) {
+    return this.todosMap.get(sessionId) ?? [];
+  }
+  // -- Checkpoints ------------------------------------------------------------
+  async saveCheckpoint(sessionId, checkpoint) {
+    const list = this.checkpointsMap.get(sessionId) ?? [];
+    list.push(checkpoint);
+    this.checkpointsMap.set(sessionId, list);
+    this.trackSession(sessionId);
+  }
+  async loadLatestCheckpoint(sessionId) {
+    const list = this.checkpointsMap.get(sessionId);
+    if (!list || list.length === 0) return null;
+    return list[list.length - 1] ?? null;
+  }
+  async listCheckpoints(sessionId) {
+    return this.checkpointsMap.get(sessionId) ?? [];
+  }
+  async deleteOldCheckpoints(sessionId, keepCount) {
+    const list = this.checkpointsMap.get(sessionId);
+    if (!list || list.length <= keepCount) return;
+    this.checkpointsMap.set(sessionId, list.slice(-keepCount));
+  }
+  // -- Conversation -----------------------------------------------------------
+  async saveConversation(sessionId, messages) {
+    this.conversationMap.set(sessionId, [...messages]);
+    this.trackSession(sessionId);
+  }
+  async loadConversation(sessionId) {
+    return this.conversationMap.get(sessionId) ?? [];
+  }
+  // -- Metadata ---------------------------------------------------------------
+  async saveMetadata(sessionId, key, value) {
+    let map = this.metadataMap.get(sessionId);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      this.metadataMap.set(sessionId, map);
+    }
+    map.set(key, value);
+    this.trackSession(sessionId);
+  }
+  async loadMetadata(sessionId, key) {
+    const map = this.metadataMap.get(sessionId);
+    if (!map || !map.has(key)) return null;
+    return map.get(key);
+  }
+  async deleteMetadata(sessionId, key) {
+    this.metadataMap.get(sessionId)?.delete(key);
+  }
+  // -- Utility ----------------------------------------------------------------
+  /** Clear all data for a session */
+  clear(sessionId) {
+    this.todosMap.delete(sessionId);
+    this.checkpointsMap.delete(sessionId);
+    this.conversationMap.delete(sessionId);
+    this.metadataMap.delete(sessionId);
+    this.sessionOrder.delete(sessionId);
+  }
+  /** Clear all sessions */
+  clearAll() {
+    this.todosMap.clear();
+    this.checkpointsMap.clear();
+    this.conversationMap.clear();
+    this.metadataMap.clear();
+    this.sessionOrder.clear();
+  }
+};
+
+// src/adapters/token-counter/approximate.adapter.ts
+var CHARS_PER_TOKEN = 4;
+var ROLE_OVERHEAD_TOKENS = 4;
+var CONTEXT_WINDOW_SIZES = {
+  "gpt-5.2": 128e3,
+  "gpt-5.2-mini": 128e3,
+  "gpt-4-turbo": 128e3,
+  "gpt-4": 8192,
+  "gpt-3.5-turbo": 16385,
+  "claude-3.5-sonnet": 2e5,
+  "claude-3-sonnet": 2e5,
+  "claude-3-haiku": 2e5,
+  "claude-3-opus": 2e5,
+  "claude-4-sonnet": 2e5,
+  "gemini-2.5-flash-preview-05-20": 1e6,
+  "gemini-2.5-flash": 1e6,
+  "gemini-2.5-pro": 1e6,
+  "gemini-1.5-flash": 1e6,
+  "gemini-1.5-pro": 2e6
+};
+var DEFAULT_CONTEXT_WINDOW = 128e3;
+var COST_TABLE = {
+  "gpt-5.2": [2.5, 10],
+  "gpt-5.2-mini": [0.15, 0.6],
+  "claude-3.5-sonnet": [3, 15],
+  "claude-3-haiku": [0.25, 1.25],
+  "gemini-2.5-flash-preview-05-20": [0.075, 0.3],
+  "gemini-2.5-flash": [0.15, 0.6],
+  "gemini-2.5-pro": [1.25, 10]
+};
+var DEFAULT_COST = [1, 3];
+var ApproximateTokenCounter = class {
+  count(text) {
+    if (!text) return 0;
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+  }
+  countMessages(messages) {
+    if (!messages.length) return 0;
+    return messages.reduce(
+      (sum, msg) => sum + this.count(msg.content) + ROLE_OVERHEAD_TOKENS,
+      0
+    );
+  }
+  getContextWindowSize(model) {
+    return CONTEXT_WINDOW_SIZES[model] ?? DEFAULT_CONTEXT_WINDOW;
+  }
+  estimateCost(inputTokens, outputTokens, model) {
+    const [inputRate, outputRate] = COST_TABLE[model] ?? DEFAULT_COST;
+    return inputTokens / 1e6 * inputRate + outputTokens / 1e6 * outputRate;
+  }
+  truncate(text, maxTokens) {
+    if (!text) return text;
+    const maxChars = maxTokens * CHARS_PER_TOKEN;
+    if (text.length <= maxChars) return text;
+    return text.slice(0, maxChars);
+  }
+};
+
+// src/agent/defaults.ts
+function defaultFilesystem() {
+  return new VirtualFilesystem();
+}
+function defaultMemory() {
+  return new InMemoryAdapter();
+}
+function defaultTokenCounter() {
+  return new ApproximateTokenCounter();
+}
+
+// src/adapters/resilience/rate-limiter.ts
+var DEFAULT_RATE_LIMITER_CONFIG = {
+  maxTokens: 10,
+  refillRateMs: 1e3
+};
+var RateLimiter = class {
+  constructor(config = DEFAULT_RATE_LIMITER_CONFIG) {
+    this.config = config;
+    this.tokens = config.maxTokens;
+    this.lastRefillTime = Date.now();
+  }
+  tokens;
+  lastRefillTime;
+  waitQueue = [];
+  processingScheduled = false;
+  /**
+   * Acquire a token, waiting if necessary
+   */
+  async acquire() {
+    if (this.tryAcquire()) {
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.waitQueue.push({ resolve, reject });
+      this.processQueue();
+    });
+  }
+  /**
+   * Try to acquire a token immediately
+   * @returns true if token acquired, false otherwise
+   */
+  tryAcquire() {
+    this.refillTokens();
+    if (this.tokens > 0) {
+      this.tokens--;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get number of available tokens
+   */
+  get availableTokens() {
+    this.refillTokens();
+    return this.tokens;
+  }
+  /**
+   * Reset the rate limiter to initial state
+   */
+  reset() {
+    this.tokens = this.config.maxTokens;
+    this.lastRefillTime = Date.now();
+    this.processingScheduled = false;
+    const queue = [...this.waitQueue];
+    this.waitQueue = [];
+    queue.forEach(({ reject }) => {
+      reject(new RateLimiterError("Rate limiter was reset"));
+    });
+  }
+  refillTokens() {
+    const now = Date.now();
+    const timePassed = now - this.lastRefillTime;
+    if (timePassed >= this.config.refillRateMs) {
+      const tokensToAdd = Math.floor(timePassed / this.config.refillRateMs);
+      this.tokens = Math.min(this.config.maxTokens, this.tokens + tokensToAdd);
+      this.lastRefillTime = now - timePassed % this.config.refillRateMs;
+    }
+  }
+  processQueue() {
+    if (this.waitQueue.length === 0 || this.processingScheduled) {
+      return;
+    }
+    this.processingScheduled = true;
+    const timeUntilNextRefill = this.config.refillRateMs - (Date.now() - this.lastRefillTime);
+    const delay = Math.max(0, timeUntilNextRefill);
+    setTimeout(() => {
+      this.processingScheduled = false;
+      this.refillTokens();
+      while (this.waitQueue.length > 0 && this.tokens > 0) {
+        const waiter = this.waitQueue.shift();
+        this.tokens--;
+        waiter.resolve();
+      }
+      if (this.waitQueue.length > 0) {
+        this.processQueue();
+      }
+    }, delay);
+  }
+};
+var RateLimiterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RateLimiterError";
+  }
+};
+
+// src/agent/agent-builder.ts
+var AgentBuilder = class extends AbstractBuilder {
+  agentConfig;
+  maxStepsOverride;
+  fs;
+  memory;
+  learning;
+  userId;
+  tokenCounter;
+  mcp;
+  policyEngine;
+  runtime;
+  costTracker;
+  planning = false;
+  subagents = false;
+  subagentConfig;
+  approvalConfig;
+  // Resilience patterns
+  circuitBreaker;
+  rateLimiter;
+  toolCache;
+  // Telemetry
+  telemetryAdapter;
+  extraTools = {};
+  plugins = [];
+  lifecycleHooks;
+  eventHandlers = [];
+  /** AI SDK Output specification (e.g. Output.object({schema})) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSpec;
+  constructor(config) {
+    super();
+    this.agentConfig = config;
+  }
+  withFilesystem(fs) {
+    this.fs = fs;
+    return this;
+  }
+  withMemory(memory) {
+    this.memory = memory;
+    return this;
+  }
+  withLearning(learning, userId) {
+    this.learning = learning;
+    this.userId = userId;
+    return this;
+  }
+  withTokenCounter(counter) {
+    this.tokenCounter = counter;
+    return this;
+  }
+  withMcp(mcp) {
+    this.mcp = mcp;
+    return this;
+  }
+  withPolicyEngine(policyEngine) {
+    this.policyEngine = policyEngine;
+    return this;
+  }
+  withRuntime(runtime) {
+    this.runtime = runtime;
+    return this;
+  }
+  withCostTracker(tracker) {
+    this.costTracker = tracker;
+    return this;
+  }
+  withPlanning() {
+    this.planning = true;
+    return this;
+  }
+  withSubagents(config) {
+    this.subagents = true;
+    this.subagentConfig = config;
+    return this;
+  }
+  withApproval(config) {
+    this.approvalConfig = config;
+    return this;
+  }
+  withMaxSteps(steps) {
+    this.maxStepsOverride = steps;
+    return this;
+  }
+  withCircuitBreaker(config) {
+    this.circuitBreaker = new CircuitBreaker({ ...DEFAULT_CIRCUIT_BREAKER_CONFIG, ...config });
+    return this;
+  }
+  withRateLimiter(config) {
+    this.rateLimiter = new RateLimiter({ ...DEFAULT_RATE_LIMITER_CONFIG, ...config });
+    return this;
+  }
+  withToolCache(config) {
+    this.toolCache = new ToolCache({ ...DEFAULT_TOOL_CACHE_CONFIG, ...config });
+    return this;
+  }
+  withTools(tools) {
+    Object.assign(this.extraTools, tools);
+    return this;
+  }
+  withTool(name, tool2) {
+    this.extraTools[name] = tool2;
+    return this;
+  }
+  withPlugin(plugin) {
+    this.plugins.push(plugin);
+    return this;
+  }
+  on(type, handler) {
+    this.eventHandlers.push({ type, handler });
+    return this;
+  }
+  withLifecycle(hooks) {
+    this.lifecycleHooks = hooks;
+    return this;
+  }
+  withTelemetry(adapter) {
+    this.telemetryAdapter = adapter;
+    return this;
+  }
+  /**
+   * Set structured output specification (AI SDK passthrough).
+   * Usage: `.withOutput(Output.object({ schema: z.object({...}) }))`
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  withOutput(output) {
+    this.outputSpec = output;
+    return this;
+  }
+  withInstructions(instructionsOrTemplate, variables) {
+    if (typeof instructionsOrTemplate === "string") {
+      this.agentConfig.instructions = instructionsOrTemplate;
+    } else {
+      this.agentConfig.instructions = instructionsOrTemplate.compile(variables);
+    }
+    return this;
+  }
+  validate() {
+    if (!this.agentConfig.model) throw new Error("model is required");
+    if (!this.agentConfig.instructions) throw new Error("instructions is required");
+  }
+  construct() {
+    const agent = new Agent({
+      model: this.agentConfig.model,
+      instructions: this.agentConfig.instructions,
+      id: this.agentConfig.id,
+      name: this.agentConfig.name,
+      maxSteps: this.maxStepsOverride ?? this.agentConfig.maxSteps ?? 30,
+      fs: this.fs ?? defaultFilesystem(),
+      memory: this.memory ?? defaultMemory(),
+      learning: this.learning,
+      userId: this.userId,
+      tokenCounter: this.tokenCounter ?? defaultTokenCounter(),
+      mcp: this.mcp,
+      policyEngine: this.policyEngine,
+      runtime: this.runtime,
+      costTracker: this.costTracker,
+      planning: this.planning,
+      subagents: this.subagents,
+      subagentConfig: this.subagentConfig,
+      approvalConfig: this.approvalConfig ? resolveApprovalConfig(this.approvalConfig) : void 0,
+      checkpointConfig: resolveCheckpointConfig(
+        this.agentConfig.checkpoint
+      ),
+      extraTools: this.extraTools,
+      plugins: this.plugins,
+      circuitBreaker: this.circuitBreaker,
+      rateLimiter: this.rateLimiter,
+      toolCache: this.toolCache,
+      lifecycleHooks: this.lifecycleHooks,
+      telemetry: this.telemetryAdapter,
+      output: this.outputSpec
+    });
+    for (const { type, handler } of this.eventHandlers) {
+      agent.eventBus.on(type, handler);
+    }
+    return agent;
+  }
+  build() {
+    return super.build();
+  }
+};
+
+// src/agent/agent.ts
+var Agent = class _Agent {
+  sessionId;
+  eventBus;
+  config;
+  _runtime;
+  _runtimePromise = null;
+  tokenTracker;
+  pluginManager;
+  middlewareChain;
+  _toolManager;
+  _executionEngine;
+  lifecycleManager;
+  // Resilience patterns
+  circuitBreaker;
+  rateLimiter;
+  toolCache;
+  // Telemetry
+  telemetry;
+  constructor(config) {
+    this._runtime = config.runtime ?? null;
+    this.sessionId = config.id ?? (this._runtime ? this._runtime.randomUUID() : crypto.randomUUID());
+    this.eventBus = new EventBus(this.sessionId);
+    this.config = config;
+    this.tokenTracker = new TokenTracker(config.tokenCounter, {
+      maxInputTokens: Infinity,
+      maxOutputTokens: Infinity,
+      maxTotalTokens: Infinity,
+      warningThreshold: 0.9
+    });
+    this.pluginManager = new PluginManager();
+    for (const plugin of config.plugins ?? []) {
+      this.pluginManager.register(plugin);
+    }
+    this.middlewareChain = new MiddlewareChain();
+    for (const mw of config.middleware ?? []) {
+      this.middlewareChain.use(mw);
+    }
+    this.circuitBreaker = config.circuitBreaker;
+    this.rateLimiter = config.rateLimiter;
+    this.toolCache = config.toolCache;
+    this.telemetry = config.telemetry;
+    this.lifecycleManager = new LifecycleManager(config.lifecycleHooks ?? {});
+  }
+  // ---------------------------------------------------------------------------
+  // Lazy-initialized heavy managers (created on first access)
+  // ---------------------------------------------------------------------------
+  get toolManager() {
+    return this._toolManager ??= new ToolManager(
+      {
+        model: this.config.model,
+        instructions: this.config.instructions,
+        name: this.config.name,
+        maxSteps: this.config.maxSteps,
+        fs: this.config.fs,
+        memory: this.config.memory,
+        learning: this.config.learning,
+        mcp: this.config.mcp,
+        policyEngine: this.config.policyEngine,
+        userId: this.config.userId,
+        planning: this.config.planning,
+        subagents: this.config.subagents,
+        subagentConfig: this.config.subagentConfig,
+        approvalConfig: this.config.approvalConfig,
+        extraTools: this.config.extraTools
+      },
+      this.pluginManager,
+      this.circuitBreaker,
+      this.rateLimiter,
+      this.toolCache
+    );
+  }
+  get executionEngine() {
+    return this._executionEngine ??= new ExecutionEngine(
+      {
+        model: this.config.model,
+        instructions: this.config.instructions,
+        maxSteps: this.config.maxSteps,
+        memory: this.config.memory,
+        learning: this.config.learning,
+        userId: this.config.userId,
+        agentName: this.config.name,
+        delegationHooks: this.config.subagentConfig?.hooks,
+        checkpointConfig: this.config.checkpointConfig,
+        telemetry: this.config.telemetry,
+        costTracker: this.config.costTracker,
+        output: this.config.output
+      },
+      this.toolManager,
+      this.pluginManager,
+      this.eventBus,
+      this.tokenTracker,
+      this.middlewareChain
+    );
+  }
+  /** Lazy-initialized runtime adapter. Resolves on first use. */
+  async ensureRuntime() {
+    if (this._runtime) return this._runtime;
+    if (!this._runtimePromise) {
+      this._runtimePromise = createRuntimeAdapterAsync().then((rt) => {
+        this._runtime = rt;
+        return rt;
+      });
+    }
+    return this._runtimePromise;
+  }
+  // ---------------------------------------------------------------------------
+  // Static factories
+  // ---------------------------------------------------------------------------
+  static create(config) {
+    return new AgentBuilder(config);
+  }
+  static minimal(config) {
+    return _Agent.create(config).withPlanning().build();
+  }
+  static full(config) {
+    const builder = _Agent.create(config).withPlanning().withSubagents();
+    if (config.memory) builder.withMemory(config.memory);
+    if (config.mcp) builder.withMcp(config.mcp);
+    if (config.tokenCounter) builder.withTokenCounter(config.tokenCounter);
+    return builder.build();
+  }
+  /**
+   * Auto-configuring factory that works in any runtime.
+   * Uses universal adapters (VirtualFilesystem, InMemoryAdapter, ApproximateTokenCounter)
+   * that require zero platform-specific APIs.
+   *
+   * For runtime-specific adapters (LocalFilesystem, DenoFilesystem, OpfsFilesystem, etc.),
+   * use `Agent.create()` and compose manually.
+   */
+  static auto(config) {
+    return _Agent.create(config).withPlanning().build();
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle Management
+  // ---------------------------------------------------------------------------
+  async startup() {
+    return this.lifecycleManager.startup();
+  }
+  async shutdown() {
+    return this.lifecycleManager.shutdown();
+  }
+  async healthCheck() {
+    return this.lifecycleManager.healthCheck();
+  }
+  get isReady() {
+    return this.lifecycleManager.isReady;
+  }
+  get isShuttingDown() {
+    return this.lifecycleManager.isShuttingDown;
+  }
+  // ---------------------------------------------------------------------------
+  // Run & Stream - Delegation to ExecutionEngine
+  // ---------------------------------------------------------------------------
+  async run(prompt, options = {}) {
+    await this.ensureRuntime();
+    return this.executionEngine.run(prompt, this.sessionId, this._runtime, options);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async stream(params, options = {}) {
+    await this.ensureRuntime();
+    return this.executionEngine.stream(params, this.sessionId, this._runtime, options);
+  }
+  // ---------------------------------------------------------------------------
+  // Cleanup
+  // ---------------------------------------------------------------------------
+  async dispose() {
+    try {
+      await this.lifecycleManager.shutdown();
+    } catch {
+    }
+    try {
+      await this.config.telemetry?.flush();
+    } catch {
+    }
+    try {
+      await this.pluginManager.dispose();
+    } finally {
+      try {
+        if (this.config.mcp) await this.config.mcp.closeAll();
+      } finally {
+        this.eventBus.removeAllListeners();
+      }
+    }
+  }
+};
+
+export {
+  AbstractBuilder,
+  VirtualFilesystem,
+  AgentBuilder,
+  Agent
+};
+//# sourceMappingURL=chunk-BI2G665F.js.map