framework-agents 0.0.0-stage → 0.1.1

package/dist/chunk-LUGUQQLR.js

@@ -0,0 +1,1033 @@
+// src/types/index.ts
+import { z as z2 } from "zod";
+
+// src/types/content.ts
+import { z } from "zod";
+var TextBlockSchema = z.object({ type: z.literal("text"), text: z.string() });
+var ReasoningBlockSchema = z.object({ type: z.literal("reasoning"), reasoning: z.string() });
+var ImageBlockSchema = z.object({
+  type: z.literal("image"),
+  url: z.string().optional(),
+  data: z.string().optional(),
+  mimeType: z.string().optional(),
+  fileId: z.string().optional()
+});
+var AudioBlockSchema = z.object({
+  type: z.literal("audio"),
+  url: z.string().optional(),
+  data: z.string().optional(),
+  mimeType: z.string().optional(),
+  fileId: z.string().optional()
+});
+var FileBlockSchema = z.object({
+  type: z.literal("file"),
+  url: z.string().optional(),
+  data: z.string().optional(),
+  mimeType: z.string().optional(),
+  fileId: z.string().optional()
+});
+var ToolCallBlockSchema = z.object({
+  type: z.literal("tool_call"),
+  id: z.string(),
+  name: z.string(),
+  args: z.unknown()
+});
+var NonStandardBlockSchema = z.object({ type: z.literal("non_standard"), value: z.unknown() });
+var ContentBlockSchema = z.discriminatedUnion("type", [
+  TextBlockSchema,
+  ReasoningBlockSchema,
+  ImageBlockSchema,
+  AudioBlockSchema,
+  FileBlockSchema,
+  ToolCallBlockSchema,
+  NonStandardBlockSchema
+]);
+function wireTextOf(content) {
+  if (typeof content === "string") return content;
+  return content.filter((b) => b.type !== "reasoning").map((b) => b.type === "text" ? b.text : "").join("");
+}
+function hasImages(content) {
+  return typeof content !== "string" && content.some((b) => b.type === "image");
+}
+function imagesOf(content) {
+  if (typeof content === "string") return [];
+  return content.filter((b) => b.type === "image").map((b) => ({ url: b.url, data: b.data, mimeType: b.mimeType }));
+}
+
+// src/types/index.ts
+var ChatMessageSchema = z2.object({
+  id: z2.string().optional(),
+  role: z2.enum(["system", "user", "assistant", "tool"]),
+  content: z2.union([z2.string(), z2.array(ContentBlockSchema)]),
+  /** Provider user-identification; behavior varies, optional. */
+  name: z2.string().optional(),
+  toolCallId: z2.string().optional(),
+  toolName: z2.string().optional(),
+  /** Pinned messages survive conversation-manager trimming. */
+  pinned: z2.boolean().optional()
+});
+var AgentError = class extends Error {
+  code;
+  retryable;
+  constructor(code, message, retryable = false) {
+    super(message);
+    this.name = "AgentError";
+    this.code = code;
+    this.retryable = retryable;
+  }
+};
+
+// src/middleware/index.ts
+import { z as z3 } from "zod";
+
+// src/tools/index.ts
+function defaultToResult(output) {
+  return { content: typeof output === "string" ? output : JSON.stringify(output) };
+}
+function defineTool(tool) {
+  if (!tool.name) throw new Error("Tool must have a name");
+  return tool;
+}
+
+// src/middleware/index.ts
+import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+var ToolRejection = class extends Error {
+  feedback;
+  constructor(feedback) {
+    super(feedback);
+    this.name = "ToolRejection";
+    this.feedback = feedback;
+  }
+};
+var HitlInterrupt = class extends Error {
+  interruptId;
+  tool;
+  args;
+  constructor(interruptId, tool, args) {
+    super(`Approval needed for tool "${tool}" (interrupt ${interruptId})`);
+    this.name = "HitlInterrupt";
+    this.interruptId = interruptId;
+    this.tool = tool;
+    this.args = args;
+  }
+};
+function todoListMiddleware() {
+  let todos = [];
+  return {
+    name: "todo-list",
+    tools: [
+      defineTool({
+        name: "write_todos",
+        description: "Track multi-step progress. Set exactly one item active at a time; mark completed as you finish.",
+        schema: z3.object({ todos: z3.array(z3.object({ content: z3.string(), status: z3.enum(["pending", "active", "completed"]) })) }),
+        execute: async ({ todos: next }) => {
+          todos = next;
+          const open = todos.filter((t) => t.status !== "completed").length;
+          return `Todos updated (${open} open):
+${todos.map((t) => `- [${t.status === "completed" ? "x" : " "}] ${t.content}`).join("\n")}`;
+        }
+      })
+    ],
+    beforeModel: (req, ctx) => {
+      if (ctx.step === 0) todos = [];
+      const hinted = req.messages[0]?.content;
+      const hint = "For multi-step tasks, plan with write_todos first; keep exactly one item active.";
+      if (typeof hinted === "string" && !hinted.includes("write_todos")) {
+        return { ...req, messages: [{ ...req.messages[0], content: `${hinted}
+${hint}` }, ...req.messages.slice(1)] };
+      }
+      return void 0;
+    },
+    listTodos: () => [...todos]
+  };
+}
+function filesystemTools(root) {
+  const base = resolve(root);
+  const resolveIn = (p) => {
+    const full = resolve(base, p);
+    if (full !== base && !full.startsWith(`${base}/`)) throw new AgentError("FS_ESCAPE", `Path escapes root: ${p}`, false);
+    return full;
+  };
+  return [
+    defineTool({
+      name: "ls",
+      description: "List files in a directory (relative to workspace root).",
+      schema: z3.object({ path: z3.string().optional() }),
+      execute: async ({ path }) => (await readdir(resolveIn(path ?? "."))).join("\n")
+    }),
+    defineTool({
+      name: "read_file",
+      description: "Read a file's full text.",
+      schema: z3.object({ path: z3.string() }),
+      execute: async ({ path }) => readFile(resolveIn(path), "utf8")
+    }),
+    defineTool({
+      name: "write_file",
+      description: "Write (create or overwrite) a file.",
+      schema: z3.object({ path: z3.string(), content: z3.string() }),
+      execute: async ({ path, content }) => {
+        const full = resolveIn(path);
+        await mkdir(dirname(full), { recursive: true });
+        await writeFile(full, content, "utf8");
+        return `wrote ${path} (${content.length} chars)`;
+      }
+    }),
+    defineTool({
+      name: "edit_file",
+      description: "Replace the first occurrence of oldString with newString in a file.",
+      schema: z3.object({ path: z3.string(), oldString: z3.string(), newString: z3.string() }),
+      execute: async ({ path, oldString, newString: ns }) => {
+        const full = resolveIn(path);
+        const content = await readFile(full, "utf8");
+        if (!content.includes(oldString)) throw new AgentError("FS_NO_MATCH", `oldString not found in ${path}`, false);
+        await writeFile(full, content.replace(oldString, ns), "utf8");
+        return `edited ${path}`;
+      }
+    })
+  ];
+}
+function filesystemMiddleware(opts) {
+  return { name: "filesystem", tools: filesystemTools(opts.root) };
+}
+
+// src/conversation/index.ts
+var NullConversationManager = class {
+  name = "null";
+  removedCount = 0;
+  apply(messages) {
+    return messages;
+  }
+  reduce(messages) {
+    return messages;
+  }
+};
+
+// src/state/index.ts
+function assertJsonSerializable(key, value) {
+  try {
+    JSON.stringify(value);
+  } catch {
+    throw new Error(`AgentState: value for "${key}" is not JSON-serializable`);
+  }
+  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new Error(`AgentState: value for "${key}" is not JSON-serializable`);
+  }
+  if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
+    throw new Error(`AgentState: value for "${key}" is a ${value.constructor.name}; use a plain object/array`);
+  }
+  if (typeof value === "object" && value !== null && !(Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+    throw new Error(`AgentState: value for "${key}" has a custom prototype; plain objects round-trip, class instances don't`);
+  }
+}
+var AgentState = class _AgentState {
+  data;
+  constructor(initial = {}) {
+    for (const [k, v] of Object.entries(initial)) assertJsonSerializable(k, v);
+    this.data = { ...initial };
+  }
+  get(key) {
+    if (key === void 0) return { ...this.data };
+    return this.data[key];
+  }
+  set(key, value) {
+    assertJsonSerializable(key, value);
+    this.data[key] = value;
+  }
+  delete(key) {
+    delete this.data[key];
+  }
+  /** Plain-object copy for snapshots/persistence. */
+  toJSON() {
+    return JSON.parse(JSON.stringify(this.data));
+  }
+  static fromJSON(raw) {
+    return new _AgentState(raw);
+  }
+};
+
+// src/sessions/index.ts
+import { mkdir as mkdir2, readdir as readdir2, readFile as readFile2, rm, writeFile as writeFile2 } from "fs/promises";
+import { join } from "path";
+var LocalFileStorage = class {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  path(key) {
+    const segments = key.split("/").filter((seg) => seg !== "");
+    if (segments.includes("..") || key.includes("\0")) {
+      throw new AgentError("STORAGE_KEY_INVALID", `Invalid storage key: ${JSON.stringify(key)}`, false);
+    }
+    return join(this.root, ...segments);
+  }
+  async read(key) {
+    try {
+      return await readFile2(this.path(key), "utf8");
+    } catch {
+      return void 0;
+    }
+  }
+  async write(key, value) {
+    const full = this.path(key);
+    await mkdir2(join(full, ".."), { recursive: true });
+    await writeFile2(full, value, "utf8");
+  }
+  async deletePrefix(prefix) {
+    await rm(this.path(prefix), { recursive: true, force: true });
+  }
+  async list(prefix) {
+    const out = [];
+    const walk = async (dir, rel) => {
+      let entries;
+      try {
+        entries = await readdir2(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        if (e.isDirectory()) await walk(join(dir, e.name), `${rel}${e.name}/`);
+        else out.push(`${prefix}${rel}${e.name}`);
+      }
+    };
+    await walk(this.path(prefix), "");
+    return out.sort();
+  }
+};
+var SESSION_PRESET = ["messages", "state"];
+function selectSnapshotFields(full, opts = {}) {
+  const base = new Set(opts.preset === "session" ? SESSION_PRESET : []);
+  for (const f of opts.include ?? []) base.add(f);
+  for (const f of opts.exclude ?? []) base.delete(f);
+  const data = {};
+  if (base.has("messages")) data.messages = full.messages;
+  if (base.has("state")) data.state = full.state;
+  if (base.has("systemPrompt")) data.systemPrompt = full.systemPrompt;
+  return data;
+}
+function uuid() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+}
+var SessionManager = class {
+  sessionId;
+  agentId;
+  storage;
+  constructor(opts) {
+    this.sessionId = opts.sessionId ?? uuid();
+    this.agentId = opts.agentId ?? "default";
+    this.storage = opts.storage;
+  }
+  scope() {
+    return `session/${this.sessionId}/scopes/agent/${this.agentId}/snapshots`;
+  }
+  async saveLatest(data) {
+    await this.storage.write(`${this.scope()}/snapshot_latest.json`, JSON.stringify({ data }));
+  }
+  async loadLatest() {
+    const raw = await this.storage.read(`${this.scope()}/snapshot_latest.json`);
+    if (!raw) return void 0;
+    try {
+      return JSON.parse(raw).data;
+    } catch {
+      return void 0;
+    }
+  }
+  /** Immutable checkpoint; returns its id. */
+  async saveSnapshot(data, appData) {
+    const snapshot = { id: uuid(), createdAt: (/* @__PURE__ */ new Date()).toISOString(), data, appData };
+    await this.storage.write(`${this.scope()}/immutable_history/snapshot_${snapshot.id}.json`, JSON.stringify(snapshot));
+    return snapshot.id;
+  }
+  async listSnapshotIds() {
+    const keys = await this.storage.list(`${this.scope()}/immutable_history/`);
+    return keys.map((k) => k.match(/snapshot_(.+)\.json$/)?.[1]).filter((id) => !!id).sort();
+  }
+  async restoreSnapshot(id) {
+    const raw = await this.storage.read(`${this.scope()}/immutable_history/snapshot_${id}.json`);
+    if (!raw) return void 0;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+  }
+  async deleteSession() {
+    await this.storage.deletePrefix(`session/${this.sessionId}/`);
+  }
+};
+
+// src/structured/index.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+function responseFormatName(format) {
+  return format.name ?? "structured_response";
+}
+function responseFormatJsonSchema(format) {
+  return zodToJsonSchema(format.schema, { $refStrategy: "none" });
+}
+function parseStructured(format, raw) {
+  const parsed = format.schema.safeParse(raw);
+  if (parsed.success) return parsed.data;
+  throw new AgentError(
+    "STRUCTURED_INVALID",
+    `Structured output failed validation for "${responseFormatName(format)}": ${parsed.error.message}`,
+    true
+  );
+}
+
+// src/agent/index.ts
+import { zodToJsonSchema as zodToJsonSchema2 } from "zod-to-json-schema";
+
+// src/memory/index.ts
+import { mkdir as mkdir3, readFile as readFile3, rename, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+var InMemoryMemory = class {
+  messages = [];
+  maxMessages;
+  constructor(maxMessages = 50) {
+    this.maxMessages = maxMessages;
+  }
+  async load() {
+    return [...this.messages];
+  }
+  async save(messages) {
+    this.messages = [...this.messages, ...messages].slice(-this.maxMessages);
+  }
+  async clear() {
+    this.messages = [];
+  }
+};
+
+// src/models/pricing.ts
+var PRICES = {
+  "Qwen/Qwen3.5-9B": { inputPerMillion: 0.2, outputPerMillion: 0.8 },
+  "meta-llama/Llama-3.3-70B-Instruct-Turbo": { inputPerMillion: 0.88, outputPerMillion: 0.88 },
+  "deepseek-ai/DeepSeek-V4.1-Flash": { inputPerMillion: 0.2, outputPerMillion: 0.6 },
+  "zai-org/GLM-5.3-Flash": { inputPerMillion: 0.2, outputPerMillion: 0.6 },
+  "gpt-4o-mini": { inputPerMillion: 0.15, outputPerMillion: 0.6 },
+  "claude-sonnet-4-6": { inputPerMillion: 3, outputPerMillion: 15 },
+  "qwen2.5": { inputPerMillion: 0, outputPerMillion: 0 }
+};
+function priceFor(modelId) {
+  if (/^ollama:/.test(modelId)) return { inputPerMillion: 0, outputPerMillion: 0 };
+  const bare = modelId.includes(":") ? modelId.split(":").slice(1).join(":") : modelId;
+  if (bare in PRICES) return PRICES[bare];
+  return void 0;
+}
+function usageCost(usage, modelId, override) {
+  const price = override ?? priceFor(modelId);
+  if (!price) return void 0;
+  return (usage.inputTokens * price.inputPerMillion + usage.outputTokens * price.outputPerMillion) / 1e6;
+}
+
+// src/runtime/index.ts
+function toAbortError() {
+  return new AgentError("ABORTED", "Run aborted", false);
+}
+async function runWithBudget(fn, budget = {}) {
+  const { signal, timeoutMs } = budget;
+  try {
+    signal?.throwIfAborted();
+  } catch {
+    throw toAbortError();
+  }
+  if (!timeoutMs && !signal) return fn();
+  let timer;
+  try {
+    return await Promise.race([
+      fn(),
+      new Promise((_, reject) => {
+        if (timeoutMs) {
+          timer = setTimeout(() => reject(new AgentError("TIMEOUT", `Exceeded ${timeoutMs}ms`, true)), timeoutMs);
+        }
+        signal?.addEventListener(
+          "abort",
+          () => {
+            if (timer) clearTimeout(timer);
+            reject(toAbortError());
+          },
+          { once: true }
+        );
+      })
+    ]);
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") throw toAbortError();
+    throw err;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// src/agent/index.ts
+var DEFAULT_SYSTEM = "You are a helpful agent. Use tools when needed. Be concise.";
+var DEFAULT_MAX_STEPS = 6;
+var toolJsonSchemas = /* @__PURE__ */ new WeakMap();
+function toolParameters(t) {
+  if (!toolJsonSchemas.has(t)) {
+    try {
+      toolJsonSchemas.set(t, zodToJsonSchema2(t.schema, { $refStrategy: "none" }));
+    } catch {
+      toolJsonSchemas.set(t, void 0);
+    }
+  }
+  return toolJsonSchemas.get(t);
+}
+var Agent = class _Agent {
+  options;
+  seeded = false;
+  restored = false;
+  lastMessages = [];
+  revisions = [];
+  agentState;
+  instanceSessionId;
+  constructor(options) {
+    this.options = {
+      name: options.name ?? "agent",
+      description: options.description ?? "",
+      systemPrompt: options.systemPrompt ?? DEFAULT_SYSTEM,
+      model: options.model,
+      // Middleware-contributed tools (filesystem, todos, subagents) come first.
+      // withTools()/branch() pass an already-merged list back in, so dedupe
+      // by name (first occurrence wins) to keep clones from advertising
+      // every middleware tool twice.
+      tools: [...(options.middleware ?? []).flatMap((m) => m.tools ?? []), ...options.tools ?? []].filter((t, i, all) => all.findIndex((o) => o.name === t.name) === i),
+      memory: options.memory,
+      maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
+      maxToolCalls: options.maxToolCalls,
+      budgets: options.budgets,
+      outputVersion: options.outputVersion ?? "v0",
+      responseFormat: options.responseFormat,
+      middleware: options.middleware ?? [],
+      initialMessages: options.initialMessages ?? [],
+      conversationManager: options.conversationManager ?? new NullConversationManager(),
+      sessionManager: options.sessionManager,
+      events: options.events
+    };
+    this.agentState = options.state instanceof AgentState ? options.state : new AgentState(options.state ?? {});
+  }
+  /** Public identity for orchestration menus and logs. */
+  get name() {
+    return this.options.name;
+  }
+  get description() {
+    return this.options.description;
+  }
+  get model() {
+    return this.options.model;
+  }
+  /** Member tools (copy) — introspection for orchestration/menus. */
+  get tools() {
+    return [...this.options.tools];
+  }
+  /**
+   * Clone with extra tools. Memory, session, and state are NOT carried over
+   * (fresh per clone); model, tools, middleware, and formats are shared.
+   * Used by coordinators (swarm handoffs) that inject control tools.
+   */
+  withTools(...extra) {
+    return new _Agent({
+      name: this.options.name,
+      description: this.options.description,
+      systemPrompt: this.options.systemPrompt,
+      model: this.options.model,
+      tools: [...this.options.tools, ...extra],
+      maxSteps: this.options.maxSteps,
+      maxToolCalls: this.options.maxToolCalls,
+      budgets: this.options.budgets,
+      outputVersion: this.options.outputVersion,
+      responseFormat: this.options.responseFormat,
+      middleware: [...this.options.middleware],
+      conversationManager: this.options.conversationManager,
+      events: this.options.events
+    });
+  }
+  /** Key-value state (never sent to the model). */
+  get state() {
+    return this.agentState;
+  }
+  /** Session handle: the manager's id, or a generated per-instance id. */
+  get sessionId() {
+    if (this.options.sessionManager) return this.options.sessionManager.sessionId;
+    this.instanceSessionId ??= Math.random().toString(16).slice(2, 10);
+    return this.instanceSessionId;
+  }
+  /** Full conversation history from the last run (system + memory + new turns). */
+  get messages() {
+    return [...this.lastMessages];
+  }
+  /** Version timeline: runs, edits, branches, resumes (append-only). */
+  get timeline() {
+    return [...this.revisions];
+  }
+  record(kind, label) {
+    this.revisions.push({ rev: this.revisions.length + 1, kind, ...label ? { label } : {}, at: (/* @__PURE__ */ new Date()).toISOString() });
+  }
+  /**
+   * Edit a message in the current history (by id or index) and keep the
+   * version in the timeline. History + memory stay in sync.
+   */
+  async editMessage(idOrIndex, content) {
+    const idx = typeof idOrIndex === "number" ? idOrIndex : this.lastMessages.findIndex((m) => m.id === idOrIndex);
+    if (idx < 0 || idx >= this.lastMessages.length) {
+      throw new AgentError("MESSAGE_NOT_FOUND", `No message ${String(idOrIndex)} in history`, false);
+    }
+    if (typeof this.lastMessages[idx].content !== "string" && this.lastMessages[idx].content.some((b) => b.type === "tool_call")) {
+      throw new AgentError("MESSAGE_NOT_EDITABLE", `Message ${String(idOrIndex)} contains tool calls; branch() from a point before it instead`, false);
+    }
+    const updated = { ...this.lastMessages[idx], content };
+    this.lastMessages = [...this.lastMessages.slice(0, idx), updated, ...this.lastMessages.slice(idx + 1)];
+    if (this.options.memory) {
+      await this.options.memory.clear();
+      await this.options.memory.save(this.lastMessages.filter((m) => m.role !== "system"));
+    }
+    this.record("edit", `message ${updated.id ?? idx}`);
+    return updated;
+  }
+  /**
+   * Branch the current history into an independent agent. Model, tools,
+   * middleware, and formats are shared; state is copied; memory is fresh
+   * (seeded with this history); sessions are NOT carried over (to avoid
+   * double-persist collisions). Both timelines record the branch.
+   */
+  async branch(label, overrides = {}) {
+    const memory = new InMemoryMemory();
+    await memory.save(this.lastMessages.filter((m) => m.role !== "system"));
+    const child = new _Agent({
+      name: this.options.name,
+      description: this.options.description,
+      systemPrompt: this.options.systemPrompt,
+      model: this.options.model,
+      tools: [...this.options.tools],
+      memory,
+      maxSteps: this.options.maxSteps,
+      maxToolCalls: this.options.maxToolCalls,
+      budgets: this.options.budgets,
+      outputVersion: this.options.outputVersion,
+      responseFormat: this.options.responseFormat,
+      middleware: [...this.options.middleware],
+      state: this.agentState.toJSON(),
+      conversationManager: this.options.conversationManager,
+      events: this.options.events,
+      ...overrides
+    });
+    child.lastMessages = [...this.lastMessages];
+    child.revisions = [...this.revisions];
+    child.record("branch", label);
+    this.record("branch", label);
+    return child;
+  }
+  /**
+   * Pause mid-conversation: persist history + state under threadId without
+   * needing an interrupt. Pair with resume() (empty decisions continue).
+   */
+  async pause(threadId, opts) {
+    await opts.checkpointer.save(threadId, {
+      messages: [...this.lastMessages],
+      state: this.agentState.toJSON(),
+      pending: []
+    });
+    return { threadId, messages: this.lastMessages.length };
+  }
+  /** Manual checkpoint: messages + state (+ system prompt on request) + appData. */
+  takeSnapshot(opts = { preset: "session" }) {
+    return {
+      id: `snapshot-${Date.now().toString(36)}`,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      data: selectSnapshotFields(
+        { messages: [...this.lastMessages], state: this.agentState.toJSON(), systemPrompt: this.options.systemPrompt },
+        opts
+      ),
+      ...opts.appData ? { appData: opts.appData } : {}
+    };
+  }
+  /** Restore fields present in the snapshot; absent fields keep current values. */
+  async loadSnapshot(snapshot) {
+    if (snapshot.data.state) {
+      for (const [k, v] of Object.entries(snapshot.data.state)) this.agentState.set(k, v);
+    }
+    if (snapshot.data.messages) {
+      this.lastMessages = [...snapshot.data.messages];
+      if (this.options.memory) {
+        await this.options.memory.clear();
+        await this.options.memory.save(snapshot.data.messages.filter((m) => m.role !== "system"));
+      }
+    }
+  }
+  /**
+   * Resume a suspended run: restores the checkpoint, seeds human decisions,
+   * and continues the loop without new input. Decisions are keyed by
+   * `hitlKey(tool, args)` for an exact match, or by bare tool name to cover
+   * every re-issued call of that tool (models re-issue with regenerated arg
+   * text, so exact keys alone would never converge).
+   */
+  async resume(threadId, decisions = {}, opts) {
+    const cp = await opts.checkpointer.load(threadId);
+    if (!cp) throw new AgentError("CHECKPOINT_MISSING", `No checkpoint for thread "${threadId}"`, false);
+    if (cp.state) {
+      for (const [k, v] of Object.entries(cp.state)) this.agentState.set(k, v);
+    }
+    this.lastMessages = [...cp.messages];
+    if (this.options.memory) {
+      await this.options.memory.clear();
+      await this.options.memory.save(cp.messages.filter((m) => m.role !== "system"));
+    }
+    const invocationState = { ...opts.invocationState ?? {}, __hitlDecisions: decisions };
+    const gen = this.iterateContinuation(opts.signal, invocationState, { checkpointer: opts.checkpointer, threadId });
+    for (; ; ) {
+      const next = await runWithBudget(() => gen.next(), { signal: opts.signal });
+      if (next.done) {
+        this.record("resume", threadId);
+        return next.value;
+      }
+    }
+  }
+  buildRuntime(invocationState) {
+    const { model, memory, systemPrompt, events, middleware, conversationManager, sessionManager } = this.options;
+    const format = this.options.responseFormat;
+    const strategy = format ? format.strategy && format.strategy !== "auto" ? format.strategy : model.capabilities?.structuredOutput ? "provider" : "tool" : void 0;
+    const tools = strategy === "tool" && format ? [...this.options.tools, structuredTool(format)] : this.options.tools;
+    const toolCtx = { agentName: this.options.name, state: this.agentState, invocationState };
+    const ctxFor = (step) => ({ step, invocationState });
+    return {
+      model,
+      memory,
+      systemPrompt,
+      events,
+      middleware,
+      conversationManager,
+      sessionManager,
+      tools,
+      format,
+      strategy,
+      maxSteps: this.options.maxSteps,
+      maxToolCalls: this.options.maxToolCalls,
+      budgets: this.options.budgets,
+      outputVersion: this.options.outputVersion,
+      state: this.agentState,
+      toolCtx,
+      ctxFor
+    };
+  }
+  /** Continue the loop from restored history (no new user message). */
+  async *iterateContinuation(signal, invocationState, checkpoint) {
+    const rt = this.buildRuntime(invocationState);
+    const messages = [
+      { role: "system", content: rt.systemPrompt },
+      ...rt.memory ? await rt.memory.load() : this.lastMessages.filter((m) => m.role !== "system")
+    ];
+    return yield* this.runLoop(messages, rt, signal, invocationState, checkpoint);
+  }
+  async run(input, signalOrOpts) {
+    const opts = signalOrOpts instanceof AbortSignal ? { signal: signalOrOpts } : signalOrOpts ?? {};
+    const stream = this.stream(input, opts);
+    for (; ; ) {
+      const next = await stream.next();
+      if (next.done) {
+        this.record("run", typeof input === "string" ? input.slice(0, 60) : "blocks");
+        return next.value;
+      }
+    }
+  }
+  async *stream(input, signalOrOpts, invocationState) {
+    const opts = signalOrOpts instanceof AbortSignal ? { signal: signalOrOpts, invocationState } : signalOrOpts ?? {};
+    const checkpoint = opts.checkpointer && opts.threadId ? { checkpointer: opts.checkpointer, threadId: opts.threadId } : void 0;
+    const gen = this.iterate(input, opts.signal, opts.invocationState ?? {}, checkpoint);
+    for (; ; ) {
+      const next = await runWithBudget(() => gen.next(), { signal: opts.signal });
+      if (next.done) return next.value;
+      yield next.value;
+    }
+  }
+  async *iterate(input, signal, invocationState = {}, checkpoint) {
+    const rt = this.buildRuntime(invocationState);
+    const { memory, systemPrompt } = this.options;
+    const sessionManager = this.options.sessionManager;
+    if (sessionManager && !this.restored) {
+      this.restored = true;
+      const latest = await sessionManager.loadLatest();
+      if (latest?.state) {
+        for (const [k, v] of Object.entries(latest.state)) this.agentState.set(k, v);
+      }
+      if (latest?.messages?.length) {
+        this.lastMessages = [...latest.messages];
+        if (memory && (await memory.load()).length === 0) {
+          await memory.save(latest.messages.filter((m) => m.role !== "system"));
+        }
+      }
+    }
+    if (!this.seeded && this.options.initialMessages.length > 0) {
+      this.seeded = true;
+      if (memory && (await memory.load()).length === 0) {
+        await memory.save(this.options.initialMessages.filter((m) => m.role !== "system"));
+      } else if (!memory && this.lastMessages.length === 0) {
+        this.lastMessages = [...this.options.initialMessages];
+      }
+    }
+    const messages = [
+      { role: "system", content: systemPrompt },
+      ...memory ? await memory.load() : this.lastMessages.filter((m) => m.role !== "system"),
+      { role: "user", content: input }
+    ];
+    return yield* this.runLoop(messages, rt, signal, invocationState, checkpoint);
+  }
+  async *runLoop(messages, rt, signal, invocationState, checkpoint) {
+    const { model, memory, systemPrompt, events, middleware, conversationManager, sessionManager, tools, format, strategy, toolCtx, ctxFor } = rt;
+    const toolCalls = [];
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    const startedAt = Date.now();
+    let text = "";
+    let structuredResponse;
+    let hasStructured = false;
+    try {
+      for (let step = 0; step < rt.maxSteps; step++) {
+        signal?.throwIfAborted();
+        if (conversationManager.beforeModel) {
+          const managed2 = await conversationManager.beforeModel(messages, step);
+          if (managed2 !== messages) {
+            messages.length = 0;
+            messages.push(...managed2);
+          }
+        }
+        events?.onStep?.({ step, messages });
+        yield { type: "step", step };
+        let req = {
+          messages,
+          tools: tools.map((t) => ({ name: t.name, description: t.description, ...toolParameters(t) ? { parametersSchema: toolParameters(t) } : {} })),
+          ...strategy === "provider" && format ? { responseFormat: { name: responseFormatName(format), schema: responseFormatJsonSchema(format) } } : {}
+        };
+        for (const mw of middleware) req = await mw.beforeModel?.(req, ctxFor(step)) ?? req;
+        const pending = [];
+        const callModel = (r) => model.complete({
+          ...r,
+          // Propagate the run's abort into the in-flight provider request.
+          ...signal ? { signal } : {},
+          onToken: (d) => {
+            events?.onToken?.(d);
+            pending.push({ type: "token", delta: d });
+          },
+          onThinking: (d) => {
+            events?.onThinking?.(d);
+            pending.push({ type: "thinking", delta: d });
+          }
+        });
+        const modelChain = middleware.filter((mw) => mw.wrapModel).reduceRight(
+          (next, mw) => (r) => mw.wrapModel(r, next, ctxFor(step)),
+          callModel
+        );
+        let completion = await modelChain(req);
+        for (const e of pending.splice(0)) {
+          if (e.delta !== "") yield e;
+        }
+        for (const mw of [...middleware].reverse()) completion = await mw.afterModel?.(completion, req, ctxFor(step)) ?? completion;
+        usage.inputTokens += completion.usage.inputTokens;
+        usage.outputTokens += completion.usage.outputTokens;
+        usage.reasoningTokens = (usage.reasoningTokens ?? 0) + (completion.usage.reasoningTokens ?? 0);
+        checkBudgets(rt, usage, startedAt, model.id);
+        if (completion.toolCalls.length === 0) {
+          text = completion.text;
+          if (strategy === "provider" && format) {
+            try {
+              structuredResponse = parseStructured(format, JSON.parse(text));
+              hasStructured = true;
+            } catch (err) {
+              const retryable = err instanceof AgentError ? err.retryable : true;
+              const message = err instanceof Error ? err.message : String(err);
+              if (step < rt.maxSteps - 1 && retryable) {
+                messages.push({ role: "assistant", content: text });
+                messages.push({
+                  role: "user",
+                  content: `Your last response was not valid for "${responseFormatName(format)}": ${message}. Reply with corrected JSON only.`
+                });
+                continue;
+              }
+              throw err instanceof AgentError ? err : new AgentError("STRUCTURED_INVALID", `Invalid structured output: ${message}`, true);
+            }
+          }
+          messages.push(
+            rt.outputVersion === "v1" && completion.thinking ? {
+              role: "assistant",
+              content: [
+                { type: "reasoning", reasoning: completion.thinking },
+                { type: "text", text }
+              ]
+            } : { role: "assistant", content: text }
+          );
+          break;
+        }
+        messages.push({
+          role: "assistant",
+          content: completion.toolCalls.map((c) => ({ type: "tool_call", id: c.id, name: c.name, args: c.args }))
+        });
+        for (const call of completion.toolCalls) {
+          if (rt.maxToolCalls != null && toolCalls.length >= rt.maxToolCalls) {
+            throw new AgentError(
+              "BUDGET_EXCEEDED",
+              `Exceeded maxToolCalls (${rt.maxToolCalls})`,
+              false
+            );
+          }
+          const tool = tools.find((t) => t.name === call.name);
+          if (!tool) {
+            messages.push({
+              role: "tool",
+              content: `Unknown tool: ${call.name}`,
+              toolCallId: call.id,
+              toolName: call.name
+            });
+            continue;
+          }
+          let toolCall = { name: call.name, args: call.args };
+          let output;
+          try {
+            for (const mw of middleware) toolCall = await mw.beforeTool?.(toolCall, ctxFor(step)) ?? toolCall;
+            events?.onToolCall?.({ tool: toolCall.name, args: toolCall.args });
+            yield { type: "tool_call", name: toolCall.name, args: toolCall.args };
+            const invoke = () => tool.execute(toolCall.args, toolCtx);
+            const chain = middleware.filter((mw) => mw.aroundTool).reduceRight(
+              (next, mw) => () => mw.aroundTool(toolCall, next, ctxFor(step)),
+              invoke
+            );
+            output = await chain();
+          } catch (err) {
+            if (err instanceof HitlInterrupt) throw err;
+            if (err instanceof ToolRejection) {
+              output = err.feedback;
+            } else {
+              if (err instanceof AgentError) throw err;
+              throw new AgentError(
+                "TOOL_EXECUTION",
+                `Tool "${toolCall.name}" failed: ${err instanceof Error ? err.message : String(err)}`,
+                false
+              );
+            }
+          }
+          for (const mw of [...middleware].reverse()) output = await mw.afterTool?.(toolCall, output, ctxFor(step)) ?? output;
+          const result = (tool.toResult ?? defaultToResult)(output);
+          toolCalls.push({ id: call.id, name: toolCall.name, args: toolCall.args, output, ...result.artifact !== void 0 ? { artifact: result.artifact } : {} });
+          if (strategy === "tool" && format && toolCall.name === responseFormatName(format) && !hasStructured) {
+            try {
+              structuredResponse = parseStructured(format, output);
+              hasStructured = true;
+            } catch {
+            }
+          }
+          events?.onToolResult?.({ tool: toolCall.name, output });
+          yield { type: "tool_result", name: toolCall.name, output };
+          messages.push({
+            role: "tool",
+            content: result.content,
+            toolCallId: call.id,
+            toolName: toolCall.name
+          });
+        }
+        if (step === rt.maxSteps - 1) {
+          text = toolCalls.length ? `Completed ${toolCalls.length} tool call(s). Last output: ${JSON.stringify(toolCalls.at(-1)?.output)}` : "";
+          messages.push({ role: "assistant", content: text });
+        }
+      }
+    } catch (err) {
+      if (err instanceof HitlInterrupt && checkpoint) {
+        const pendingArgs = JSON.stringify(err.args ?? {});
+        let cut = messages.length;
+        for (let i = messages.length - 1; i >= 0; i--) {
+          const m = messages[i];
+          if (m.role === "assistant" && typeof m.content !== "string" && m.content.some((b) => b.type === "tool_call" && b.name === err.tool && JSON.stringify(b.args ?? {}) === pendingArgs)) {
+            cut = i;
+            break;
+          }
+        }
+        await checkpoint.checkpointer.save(checkpoint.threadId, {
+          messages: messages.slice(0, cut),
+          state: rt.state.toJSON(),
+          pending: [{ interruptId: err.interruptId, tool: err.tool, args: err.args }]
+        });
+      }
+      throw err;
+    }
+    if (format && !hasStructured) {
+      throw new AgentError(
+        "STRUCTURED_NO_MATCH",
+        `No valid "${responseFormatName(format)}" produced within ${rt.maxSteps} steps`,
+        false
+      );
+    }
+    const managed = await conversationManager.apply(messages);
+    if (memory) {
+      await memory.clear();
+      await memory.save(managed.filter((m) => m.role !== "system"));
+    }
+    this.lastMessages = managed;
+    if (sessionManager) {
+      await sessionManager.saveLatest({
+        messages: managed,
+        state: rt.state.toJSON(),
+        systemPrompt
+      });
+    }
+    events?.onDone?.({ text, toolCalls });
+    yield { type: "done", text };
+    const costUsd = usageCost(usage, model.id, rt.budgets?.prices);
+    return {
+      text,
+      messages: [...managed],
+      toolCalls,
+      usage: { ...usage, ...costUsd !== void 0 ? { costUsd } : {} },
+      invocationState,
+      ...hasStructured ? { structuredResponse } : {}
+    };
+  }
+};
+function checkBudgets(rt, usage, startedAt, modelId) {
+  const budgets = rt.budgets;
+  if (!budgets) return;
+  const total = usage.inputTokens + usage.outputTokens;
+  if (budgets.maxTokens != null && total > budgets.maxTokens) {
+    throw new AgentError("BUDGET_EXCEEDED", `Exceeded maxTokens (${budgets.maxTokens}, used ${total})`, false);
+  }
+  if (budgets.maxCostUsd != null) {
+    const prices = budgets.prices ?? priceFor(modelId);
+    if (!prices) {
+      throw new AgentError("BUDGET_NO_PRICE", `Cannot enforce maxCostUsd: no price for model "${modelId}" (set budgets.prices)`, false);
+    }
+    const cost = usageCost(usage, modelId, prices);
+    if (cost != null && cost > budgets.maxCostUsd) {
+      throw new AgentError("BUDGET_EXCEEDED", `Exceeded maxCostUsd ($${budgets.maxCostUsd}, used $${cost.toFixed(4)})`, false);
+    }
+  }
+  if (budgets.deadlineMs != null && Date.now() - startedAt > budgets.deadlineMs) {
+    throw new AgentError("BUDGET_EXCEEDED", `Exceeded deadline (${budgets.deadlineMs}ms)`, false);
+  }
+}
+function structuredTool(format) {
+  const name = responseFormatName(format);
+  const maxAttempts = format.maxAttempts ?? 2;
+  let attempts = 0;
+  return defineTool({
+    name,
+    description: `Return the final answer as structured "${name}". Call exactly once with valid arguments.`,
+    schema: format.schema,
+    execute: async (args) => {
+      attempts += 1;
+      const parsed = format.schema.safeParse(args);
+      if (parsed.success) return parsed.data;
+      if (attempts >= maxAttempts) {
+        throw new AgentError("STRUCTURED_NO_MATCH", `Invalid "${name}" after ${attempts} attempts: ${parsed.error.message}`, false);
+      }
+      return `Error: invalid "${name}": ${parsed.error.message}. Fix the arguments and call again.`;
+    }
+  });
+}
+
+export {
+  wireTextOf,
+  hasImages,
+  imagesOf,
+  AgentError,
+  todoListMiddleware,
+  filesystemMiddleware,
+  LocalFileStorage,
+  SessionManager,
+  Agent
+};