@deepagents/context 0.10.2 → 0.11.0

package/dist/index.js

@@ -1,17 +1,3 @@
-// packages/context/src/index.ts
-import { generateId } from "ai";
-
-// packages/context/src/lib/context.ts
-function isFragment(data) {
-  return typeof data === "object" && data !== null && "name" in data && "data" in data && typeof data.name === "string";
-}
-function isFragmentObject(data) {
-  return typeof data === "object" && data !== null && !Array.isArray(data) && !isFragment(data);
-}
-function isMessageFragment(fragment2) {
-  return fragment2.type === "message";
-}
-
 // packages/context/src/lib/estimate.ts
 import { encode } from "gpt-tokenizer";
 var defaultTokenizer = {
@@ -172,6 +158,99 @@ async function estimate(modelId, renderer, ...fragments) {
   };
 }
 
+// packages/context/src/lib/fragments.ts
+import { generateId } from "ai";
+function isFragment(data) {
+  return typeof data === "object" && data !== null && "name" in data && "data" in data && typeof data.name === "string";
+}
+function isFragmentObject(data) {
+  return typeof data === "object" && data !== null && !Array.isArray(data) && !isFragment(data);
+}
+function isMessageFragment(fragment2) {
+  return fragment2.type === "message";
+}
+function fragment(name, ...children) {
+  return {
+    name,
+    data: children
+  };
+}
+function role(content) {
+  return {
+    name: "role",
+    data: content
+  };
+}
+function user(content) {
+  const message2 = typeof content === "string" ? {
+    id: generateId(),
+    role: "user",
+    parts: [{ type: "text", text: content }]
+  } : content;
+  return {
+    id: message2.id,
+    name: "user",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+function assistant(message2) {
+  return {
+    id: message2.id,
+    name: "assistant",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+function message(content) {
+  const message2 = typeof content === "string" ? {
+    id: generateId(),
+    role: "user",
+    parts: [{ type: "text", text: content }]
+  } : content;
+  return {
+    id: message2.id,
+    name: "message",
+    data: "content",
+    type: "message",
+    persist: true,
+    codec: {
+      decode() {
+        return message2;
+      },
+      encode() {
+        return message2;
+      }
+    }
+  };
+}
+function assistantText(content, options) {
+  const id = options?.id ?? crypto.randomUUID();
+  return assistant({
+    id,
+    role: "assistant",
+    parts: [{ type: "text", text: content }]
+  });
+}
+
 // packages/context/src/lib/renderers/abstract.renderer.ts
 import pluralize from "pluralize";
 import { titlecase } from "stringcase";
@@ -547,13 +626,13 @@ var TomlRenderer = class extends ContextRenderer {
     const entries = this.#renderObjectEntries(obj, newPath);
     return ["", `[${newPath.join(".")}]`, ...entries].join("\n");
   }
-  #renderObjectEntries(obj, path) {
+  #renderObjectEntries(obj, path3) {
     return Object.entries(obj).map(([key, value]) => {
       if (value == null) {
         return "";
       }
       if (isFragmentObject(value)) {
-        const newPath = [...path, key];
+        const newPath = [...path3, key];
         const entries = this.#renderObjectEntries(value, newPath);
         return ["", `[${newPath.join(".")}]`, ...entries].join("\n");
       }
@@ -826,1185 +905,2435 @@ ${entries}`;
 var ContextStore = class {
 };
 
-// packages/context/src/lib/store/sqlite.store.ts
-import { DatabaseSync } from "node:sqlite";
-var STORE_DDL = `
--- Chats table
--- createdAt/updatedAt: DEFAULT for insert, inline SET for updates
-CREATE TABLE IF NOT EXISTS chats (
-  id TEXT PRIMARY KEY,
-  title TEXT,
-  metadata TEXT,
-  createdAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
-  updatedAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
-);
-
-CREATE INDEX IF NOT EXISTS idx_chats_updatedAt ON chats(updatedAt);
-
--- Messages table (nodes in the DAG)
-CREATE TABLE IF NOT EXISTS messages (
-  id TEXT PRIMARY KEY,
-  chatId TEXT NOT NULL,
-  parentId TEXT,
-  name TEXT NOT NULL,
-  type TEXT,
-  data TEXT NOT NULL,
-  createdAt INTEGER NOT NULL,
-  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
-  FOREIGN KEY (parentId) REFERENCES messages(id)
-);
-
-CREATE INDEX IF NOT EXISTS idx_messages_chatId ON messages(chatId);
-CREATE INDEX IF NOT EXISTS idx_messages_parentId ON messages(parentId);
-
--- Branches table (pointers to head messages)
-CREATE TABLE IF NOT EXISTS branches (
-  id TEXT PRIMARY KEY,
-  chatId TEXT NOT NULL,
-  name TEXT NOT NULL,
-  headMessageId TEXT,
-  isActive INTEGER NOT NULL DEFAULT 0,
-  createdAt INTEGER NOT NULL,
-  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
-  FOREIGN KEY (headMessageId) REFERENCES messages(id),
-  UNIQUE(chatId, name)
-);
-
-CREATE INDEX IF NOT EXISTS idx_branches_chatId ON branches(chatId);
-
--- Checkpoints table (pointers to message nodes)
-CREATE TABLE IF NOT EXISTS checkpoints (
-  id TEXT PRIMARY KEY,
-  chatId TEXT NOT NULL,
-  name TEXT NOT NULL,
-  messageId TEXT NOT NULL,
-  createdAt INTEGER NOT NULL,
-  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
-  FOREIGN KEY (messageId) REFERENCES messages(id),
-  UNIQUE(chatId, name)
-);
-
-CREATE INDEX IF NOT EXISTS idx_checkpoints_chatId ON checkpoints(chatId);
-
--- FTS5 virtual table for full-text search
--- messageId/chatId/name are UNINDEXED (stored but not searchable, used for filtering/joining)
--- Only 'content' is indexed for full-text search
-CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
-  messageId UNINDEXED,
-  chatId UNINDEXED,
-  name UNINDEXED,
-  content,
-  tokenize='porter unicode61'
-);
-`;
-var SqliteContextStore = class extends ContextStore {
-  #db;
-  constructor(path) {
-    super();
-    this.#db = new DatabaseSync(path);
-    this.#db.exec("PRAGMA foreign_keys = ON");
-    this.#db.exec(STORE_DDL);
+// packages/context/src/lib/engine.ts
+var ContextEngine = class {
+  /** Non-message fragments (role, hints, etc.) - not persisted in graph */
+  #fragments = [];
+  /** Pending message fragments to be added to graph */
+  #pendingMessages = [];
+  #store;
+  #chatId;
+  #branchName;
+  #branch = null;
+  #chatData = null;
+  #initialized = false;
+  constructor(options) {
+    if (!options.chatId) {
+      throw new Error("chatId is required");
+    }
+    this.#store = options.store;
+    this.#chatId = options.chatId;
+    this.#branchName = options.branch ?? "main";
   }
-  // ==========================================================================
-  // Chat Operations
-  // ==========================================================================
-  async createChat(chat) {
-    this.#db.prepare(
-      `INSERT INTO chats (id, title, metadata)
-         VALUES (?, ?, ?)`
-    ).run(
-      chat.id,
-      chat.title ?? null,
-      chat.metadata ? JSON.stringify(chat.metadata) : null
+  /**
+   * Initialize the chat and branch if they don't exist.
+   */
+  async #ensureInitialized() {
+    if (this.#initialized) {
+      return;
+    }
+    this.#chatData = await this.#store.upsertChat({ id: this.#chatId });
+    const existingBranch = await this.#store.getBranch(
+      this.#chatId,
+      this.#branchName
     );
+    if (existingBranch) {
+      this.#branch = existingBranch;
+    } else {
+      this.#branch = {
+        id: crypto.randomUUID(),
+        chatId: this.#chatId,
+        name: this.#branchName,
+        headMessageId: null,
+        isActive: true,
+        createdAt: Date.now()
+      };
+      await this.#store.createBranch(this.#branch);
+    }
+    this.#initialized = true;
   }
-  async upsertChat(chat) {
-    const row = this.#db.prepare(
-      `INSERT INTO chats (id, title, metadata)
-         VALUES (?, ?, ?)
-         ON CONFLICT(id) DO UPDATE SET id = excluded.id
-         RETURNING *`
-    ).get(
-      chat.id,
-      chat.title ?? null,
-      chat.metadata ? JSON.stringify(chat.metadata) : null
+  /**
+   * Create a new branch from a specific message.
+   * Shared logic between rewind() and btw().
+   */
+  async #createBranchFrom(messageId, switchTo) {
+    const branches = await this.#store.listBranches(this.#chatId);
+    const samePrefix = branches.filter(
+      (b) => b.name === this.#branchName || b.name.startsWith(`${this.#branchName}-v`)
     );
-    return {
-      id: row.id,
-      title: row.title ?? void 0,
-      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
-      createdAt: row.createdAt,
-      updatedAt: row.updatedAt
-    };
-  }
-  async getChat(chatId) {
-    const row = this.#db.prepare("SELECT * FROM chats WHERE id = ?").get(chatId);
-    if (!row) {
-      return void 0;
-    }
-    return {
-      id: row.id,
-      title: row.title ?? void 0,
-      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
-      createdAt: row.createdAt,
-      updatedAt: row.updatedAt
+    const newBranchName = `${this.#branchName}-v${samePrefix.length + 1}`;
+    const newBranch = {
+      id: crypto.randomUUID(),
+      chatId: this.#chatId,
+      name: newBranchName,
+      headMessageId: messageId,
+      isActive: false,
+      createdAt: Date.now()
     };
-  }
-  async updateChat(chatId, updates) {
-    const setClauses = ["updatedAt = strftime('%s', 'now') * 1000"];
-    const params = [];
-    if (updates.title !== void 0) {
-      setClauses.push("title = ?");
-      params.push(updates.title ?? null);
-    }
-    if (updates.metadata !== void 0) {
-      setClauses.push("metadata = ?");
-      params.push(JSON.stringify(updates.metadata));
+    await this.#store.createBranch(newBranch);
+    if (switchTo) {
+      await this.#store.setActiveBranch(this.#chatId, newBranch.id);
+      this.#branch = { ...newBranch, isActive: true };
+      this.#branchName = newBranchName;
+      this.#pendingMessages = [];
     }
-    params.push(chatId);
-    const row = this.#db.prepare(
-      `UPDATE chats SET ${setClauses.join(", ")} WHERE id = ? RETURNING *`
-    ).get(...params);
+    const chain = await this.#store.getMessageChain(messageId);
     return {
-      id: row.id,
-      title: row.title ?? void 0,
-      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
-      createdAt: row.createdAt,
-      updatedAt: row.updatedAt
+      id: newBranch.id,
+      name: newBranch.name,
+      headMessageId: newBranch.headMessageId,
+      isActive: switchTo,
+      messageCount: chain.length,
+      createdAt: newBranch.createdAt
     };
   }
-  async listChats() {
-    const rows = this.#db.prepare(
-      `SELECT
-          c.id,
-          c.title,
-          c.createdAt,
-          c.updatedAt,
-          COUNT(DISTINCT m.id) as messageCount,
-          COUNT(DISTINCT b.id) as branchCount
-        FROM chats c
-        LEFT JOIN messages m ON m.chatId = c.id
-        LEFT JOIN branches b ON b.chatId = c.id
-        GROUP BY c.id
-        ORDER BY c.updatedAt DESC`
-    ).all();
-    return rows.map((row) => ({
-      id: row.id,
-      title: row.title ?? void 0,
-      messageCount: row.messageCount,
-      branchCount: row.branchCount,
-      createdAt: row.createdAt,
-      updatedAt: row.updatedAt
-    }));
+  /**
+   * Get the current chat ID.
+   */
+  get chatId() {
+    return this.#chatId;
   }
-  // ==========================================================================
-  // Message Operations (Graph Nodes)
-  // ==========================================================================
-  async addMessage(message2) {
-    this.#db.prepare(
-      `INSERT INTO messages (id, chatId, parentId, name, type, data, createdAt)
-         VALUES (?, ?, ?, ?, ?, ?, ?)
-         ON CONFLICT(id) DO UPDATE SET
-           parentId = excluded.parentId,
-           name = excluded.name,
-           type = excluded.type,
-           data = excluded.data`
-    ).run(
-      message2.id,
-      message2.chatId,
-      message2.parentId,
-      message2.name,
-      message2.type ?? null,
-      JSON.stringify(message2.data),
-      message2.createdAt
-    );
-    const content = typeof message2.data === "string" ? message2.data : JSON.stringify(message2.data);
-    this.#db.prepare(`DELETE FROM messages_fts WHERE messageId = ?`).run(message2.id);
-    this.#db.prepare(
-      `INSERT INTO messages_fts(messageId, chatId, name, content)
-         VALUES (?, ?, ?, ?)`
-    ).run(message2.id, message2.chatId, message2.name, content);
+  /**
+   * Get the current branch name.
+   */
+  get branch() {
+    return this.#branchName;
   }
-  async getMessage(messageId) {
-    const row = this.#db.prepare("SELECT * FROM messages WHERE id = ?").get(messageId);
-    if (!row) {
-      return void 0;
+  /**
+   * Get metadata for the current chat.
+   * Returns null if the chat hasn't been initialized yet.
+   */
+  get chat() {
+    if (!this.#chatData) {
+      return null;
     }
     return {
-      id: row.id,
-      chatId: row.chatId,
-      parentId: row.parentId,
-      name: row.name,
-      type: row.type ?? void 0,
-      data: JSON.parse(row.data),
-      createdAt: row.createdAt
+      id: this.#chatData.id,
+      createdAt: this.#chatData.createdAt,
+      updatedAt: this.#chatData.updatedAt,
+      title: this.#chatData.title,
+      metadata: this.#chatData.metadata
     };
   }
-  async getMessageChain(headId) {
-    const rows = this.#db.prepare(
-      `WITH RECURSIVE chain AS (
-          SELECT *, 0 as depth FROM messages WHERE id = ?
-          UNION ALL
-          SELECT m.*, c.depth + 1 FROM messages m
-          INNER JOIN chain c ON m.id = c.parentId
-        )
-        SELECT * FROM chain
-        ORDER BY depth DESC`
-    ).all(headId);
-    return rows.map((row) => ({
-      id: row.id,
-      chatId: row.chatId,
-      parentId: row.parentId,
-      name: row.name,
-      type: row.type ?? void 0,
-      data: JSON.parse(row.data),
-      createdAt: row.createdAt
-    }));
+  /**
+   * Add fragments to the context.
+   *
+   * - Message fragments (user/assistant) are queued for persistence
+   * - Non-message fragments (role/hint) are kept in memory for system prompt
+   */
+  set(...fragments) {
+    for (const fragment2 of fragments) {
+      if (isMessageFragment(fragment2)) {
+        this.#pendingMessages.push(fragment2);
+      } else {
+        this.#fragments.push(fragment2);
+      }
+    }
+    return this;
   }
-  async hasChildren(messageId) {
-    const row = this.#db.prepare(
-      "SELECT EXISTS(SELECT 1 FROM messages WHERE parentId = ?) as hasChildren"
-    ).get(messageId);
-    return row.hasChildren === 1;
+  // Unset a fragment by ID (not implemented yet)
+  unset(fragmentId) {
   }
-  // ==========================================================================
-  // Branch Operations
-  // ==========================================================================
-  async createBranch(branch) {
-    this.#db.prepare(
-      `INSERT INTO branches (id, chatId, name, headMessageId, isActive, createdAt)
-         VALUES (?, ?, ?, ?, ?, ?)`
-    ).run(
-      branch.id,
-      branch.chatId,
-      branch.name,
-      branch.headMessageId,
-      branch.isActive ? 1 : 0,
-      branch.createdAt
-    );
+  /**
+   * Render all fragments using the provided renderer.
+   * @internal Use resolve() instead for public API.
+   */
+  render(renderer) {
+    return renderer.render(this.#fragments);
   }
-  async getBranch(chatId, name) {
-    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND name = ?").get(chatId, name);
-    if (!row) {
-      return void 0;
+  /**
+   * Resolve context into AI SDK-ready format.
+   *
+   * - Initializes chat and branch if needed
+   * - Loads message history from the graph (walking parent chain)
+   * - Separates context fragments for system prompt
+   * - Combines with pending messages
+   *
+   * @example
+   * ```ts
+   * const context = new ContextEngine({ store, chatId: 'chat-1' })
+   *   .set(role('You are helpful'), user('Hello'));
+   *
+   * const { systemPrompt, messages } = await context.resolve();
+   * await generateText({ system: systemPrompt, messages });
+   * ```
+   */
+  async resolve(options) {
+    await this.#ensureInitialized();
+    const systemPrompt = options.renderer.render(this.#fragments);
+    const messages = [];
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      for (const msg of chain) {
+        messages.push(message(msg.data).codec?.decode());
+      }
     }
-    return {
-      id: row.id,
-      chatId: row.chatId,
-      name: row.name,
-      headMessageId: row.headMessageId,
-      isActive: row.isActive === 1,
-      createdAt: row.createdAt
-    };
-  }
-  async getActiveBranch(chatId) {
-    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND isActive = 1").get(chatId);
-    if (!row) {
-      return void 0;
+    for (const fragment2 of this.#pendingMessages) {
+      const decoded = fragment2.codec.decode();
+      messages.push(decoded);
     }
-    return {
-      id: row.id,
-      chatId: row.chatId,
-      name: row.name,
-      headMessageId: row.headMessageId,
-      isActive: true,
-      createdAt: row.createdAt
-    };
-  }
-  async setActiveBranch(chatId, branchId) {
-    this.#db.prepare("UPDATE branches SET isActive = 0 WHERE chatId = ?").run(chatId);
-    this.#db.prepare("UPDATE branches SET isActive = 1 WHERE id = ?").run(branchId);
+    return { systemPrompt, messages };
   }
-  async updateBranchHead(branchId, messageId) {
-    this.#db.prepare("UPDATE branches SET headMessageId = ? WHERE id = ?").run(messageId, branchId);
+  /**
+   * Save pending messages to the graph.
+   *
+   * Each message is added as a node with parentId pointing to the previous message.
+   * The branch head is updated to point to the last message.
+   *
+   * @example
+   * ```ts
+   * context.set(user('Hello'));
+   * // AI responds...
+   * context.set(assistant('Hi there!'));
+   * await context.save(); // Persist to graph
+   * ```
+   */
+  async save() {
+    await this.#ensureInitialized();
+    if (this.#pendingMessages.length === 0) {
+      return;
+    }
+    let parentId = this.#branch.headMessageId;
+    const now = Date.now();
+    for (const fragment2 of this.#pendingMessages) {
+      const messageData = {
+        id: fragment2.id ?? crypto.randomUUID(),
+        chatId: this.#chatId,
+        parentId,
+        name: fragment2.name,
+        type: fragment2.type,
+        data: fragment2.codec.encode(),
+        createdAt: now
+      };
+      await this.#store.addMessage(messageData);
+      parentId = messageData.id;
+    }
+    await this.#store.updateBranchHead(this.#branch.id, parentId);
+    this.#branch.headMessageId = parentId;
+    this.#pendingMessages = [];
   }
-  async listBranches(chatId) {
-    const branches = this.#db.prepare(
-      `SELECT
-          b.id,
-          b.name,
-          b.headMessageId,
-          b.isActive,
-          b.createdAt
-        FROM branches b
-        WHERE b.chatId = ?
-        ORDER BY b.createdAt ASC`
-    ).all(chatId);
-    const result = [];
-    for (const branch of branches) {
-      let messageCount = 0;
-      if (branch.headMessageId) {
-        const countRow = this.#db.prepare(
-          `WITH RECURSIVE chain AS (
-              SELECT id, parentId FROM messages WHERE id = ?
-              UNION ALL
-              SELECT m.id, m.parentId FROM messages m
-              INNER JOIN chain c ON m.id = c.parentId
-            )
-            SELECT COUNT(*) as count FROM chain`
-        ).get(branch.headMessageId);
-        messageCount = countRow.count;
+  /**
+   * Estimate token count and cost for the full context.
+   *
+   * Includes:
+   * - System prompt fragments (role, hints, etc.)
+   * - Persisted chat messages (from store)
+   * - Pending messages (not yet saved)
+   *
+   * @param modelId - Model ID (e.g., "openai:gpt-4o", "anthropic:claude-3-5-sonnet")
+   * @param options - Optional settings
+   * @returns Estimate result with token counts, costs, and per-fragment breakdown
+   */
+  async estimate(modelId, options = {}) {
+    await this.#ensureInitialized();
+    const renderer = options.renderer ?? new XmlRenderer();
+    const registry = getModelsRegistry();
+    await registry.load();
+    const model = registry.get(modelId);
+    if (!model) {
+      throw new Error(
+        `Model "${modelId}" not found. Call load() first or check model ID.`
+      );
+    }
+    const tokenizer = registry.getTokenizer(modelId);
+    const fragmentEstimates = [];
+    for (const fragment2 of this.#fragments) {
+      const rendered = renderer.render([fragment2]);
+      const tokens = tokenizer.count(rendered);
+      const cost = tokens / 1e6 * model.cost.input;
+      fragmentEstimates.push({
+        id: fragment2.id,
+        name: fragment2.name,
+        tokens,
+        cost
+      });
+    }
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      for (const msg of chain) {
+        const content = String(msg.data);
+        const tokens = tokenizer.count(content);
+        const cost = tokens / 1e6 * model.cost.input;
+        fragmentEstimates.push({
+          name: msg.name,
+          id: msg.id,
+          tokens,
+          cost
+        });
       }
-      result.push({
-        id: branch.id,
-        name: branch.name,
-        headMessageId: branch.headMessageId,
-        isActive: branch.isActive === 1,
-        messageCount,
-        createdAt: branch.createdAt
+    }
+    for (const fragment2 of this.#pendingMessages) {
+      const content = String(fragment2.data);
+      const tokens = tokenizer.count(content);
+      const cost = tokens / 1e6 * model.cost.input;
+      fragmentEstimates.push({
+        name: fragment2.name,
+        id: fragment2.id,
+        tokens,
+        cost
       });
     }
-    return result;
+    const totalTokens = fragmentEstimates.reduce((sum, f) => sum + f.tokens, 0);
+    const totalCost = fragmentEstimates.reduce((sum, f) => sum + f.cost, 0);
+    return {
+      model: model.id,
+      provider: model.provider,
+      tokens: totalTokens,
+      cost: totalCost,
+      limits: {
+        context: model.limit.context,
+        output: model.limit.output,
+        exceedsContext: totalTokens > model.limit.context
+      },
+      fragments: fragmentEstimates
+    };
   }
-  // ==========================================================================
-  // Checkpoint Operations
-  // ==========================================================================
-  async createCheckpoint(checkpoint) {
-    this.#db.prepare(
-      `INSERT INTO checkpoints (id, chatId, name, messageId, createdAt)
-         VALUES (?, ?, ?, ?, ?)
-         ON CONFLICT(chatId, name) DO UPDATE SET
-           messageId = excluded.messageId,
-           createdAt = excluded.createdAt`
-    ).run(
-      checkpoint.id,
-      checkpoint.chatId,
-      checkpoint.name,
-      checkpoint.messageId,
-      checkpoint.createdAt
-    );
+  /**
+   * Rewind to a specific message by ID.
+   *
+   * Creates a new branch from that message, preserving the original branch.
+   * The new branch becomes active.
+   *
+   * @param messageId - The message ID to rewind to
+   * @returns The new branch info
+   *
+   * @example
+   * ```ts
+   * context.set(user('What is 2 + 2?', { id: 'q1' }));
+   * context.set(assistant('The answer is 5.', { id: 'wrong' })); // Oops!
+   * await context.save();
+   *
+   * // Rewind to the question, creates new branch
+   * const newBranch = await context.rewind('q1');
+   *
+   * // Now add correct answer on new branch
+   * context.set(assistant('The answer is 4.'));
+   * await context.save();
+   * ```
+   */
+  async rewind(messageId) {
+    await this.#ensureInitialized();
+    const message2 = await this.#store.getMessage(messageId);
+    if (!message2) {
+      throw new Error(`Message "${messageId}" not found`);
+    }
+    if (message2.chatId !== this.#chatId) {
+      throw new Error(`Message "${messageId}" belongs to a different chat`);
+    }
+    return this.#createBranchFrom(messageId, true);
   }
-  async getCheckpoint(chatId, name) {
-    const row = this.#db.prepare("SELECT * FROM checkpoints WHERE chatId = ? AND name = ?").get(chatId, name);
-    if (!row) {
-      return void 0;
+  /**
+   * Create a checkpoint at the current position.
+   *
+   * A checkpoint is a named pointer to the current branch head.
+   * Use restore() to return to this point later.
+   *
+   * @param name - Name for the checkpoint
+   * @returns The checkpoint info
+   *
+   * @example
+   * ```ts
+   * context.set(user('I want to learn a new skill.'));
+   * context.set(assistant('Would you like coding or cooking?'));
+   * await context.save();
+   *
+   * // Save checkpoint before user's choice
+   * const cp = await context.checkpoint('before-choice');
+   * ```
+   */
+  async checkpoint(name) {
+    await this.#ensureInitialized();
+    if (!this.#branch?.headMessageId) {
+      throw new Error("Cannot create checkpoint: no messages in conversation");
     }
+    const checkpoint = {
+      id: crypto.randomUUID(),
+      chatId: this.#chatId,
+      name,
+      messageId: this.#branch.headMessageId,
+      createdAt: Date.now()
+    };
+    await this.#store.createCheckpoint(checkpoint);
     return {
-      id: row.id,
-      chatId: row.chatId,
-      name: row.name,
-      messageId: row.messageId,
-      createdAt: row.createdAt
+      id: checkpoint.id,
+      name: checkpoint.name,
+      messageId: checkpoint.messageId,
+      createdAt: checkpoint.createdAt
     };
   }
-  async listCheckpoints(chatId) {
-    const rows = this.#db.prepare(
-      `SELECT id, name, messageId, createdAt
-         FROM checkpoints
-         WHERE chatId = ?
-         ORDER BY createdAt DESC`
-    ).all(chatId);
-    return rows.map((row) => ({
-      id: row.id,
-      name: row.name,
-      messageId: row.messageId,
-      createdAt: row.createdAt
-    }));
+  /**
+   * Restore to a checkpoint by creating a new branch from that point.
+   *
+   * @param name - Name of the checkpoint to restore
+   * @returns The new branch info
+   *
+   * @example
+   * ```ts
+   * // User chose cooking, but wants to try coding path
+   * await context.restore('before-choice');
+   *
+   * context.set(user('I want to learn coding.'));
+   * context.set(assistant('Python is a great starting language!'));
+   * await context.save();
+   * ```
+   */
+  async restore(name) {
+    await this.#ensureInitialized();
+    const checkpoint = await this.#store.getCheckpoint(this.#chatId, name);
+    if (!checkpoint) {
+      throw new Error(
+        `Checkpoint "${name}" not found in chat "${this.#chatId}"`
+      );
+    }
+    return this.rewind(checkpoint.messageId);
+  }
+  /**
+   * Switch to a different branch by name.
+   *
+   * @param name - Branch name to switch to
+   *
+   * @example
+   * ```ts
+   * // List branches (via store)
+   * const branches = await store.listBranches(context.chatId);
+   * console.log(branches); // [{name: 'main', ...}, {name: 'main-v2', ...}]
+   *
+   * // Switch to original branch
+   * await context.switchBranch('main');
+   * ```
+   */
+  async switchBranch(name) {
+    await this.#ensureInitialized();
+    const branch = await this.#store.getBranch(this.#chatId, name);
+    if (!branch) {
+      throw new Error(`Branch "${name}" not found in chat "${this.#chatId}"`);
+    }
+    await this.#store.setActiveBranch(this.#chatId, branch.id);
+    this.#branch = { ...branch, isActive: true };
+    this.#branchName = name;
+    this.#pendingMessages = [];
+  }
+  /**
+   * Create a parallel branch from the current position ("by the way").
+   *
+   * Use this when you want to fork the conversation without leaving
+   * the current branch. Common use case: user wants to ask another
+   * question while waiting for the model to respond.
+   *
+   * Unlike rewind(), this method:
+   * - Uses the current HEAD (no messageId needed)
+   * - Does NOT switch to the new branch
+   * - Keeps pending messages intact
+   *
+   * @returns The new branch info (does not switch to it)
+   * @throws Error if no messages exist in the conversation
+   *
+   * @example
+   * ```ts
+   * // User asked a question, model is generating...
+   * context.set(user('What is the weather?'));
+   * await context.save();
+   *
+   * // User wants to ask something else without waiting
+   * const newBranch = await context.btw();
+   * // newBranch = { name: 'main-v2', ... }
+   *
+   * // Later, switch to the new branch and add the question
+   * await context.switchBranch(newBranch.name);
+   * context.set(user('Also, what time is it?'));
+   * await context.save();
+   * ```
+   */
+  async btw() {
+    await this.#ensureInitialized();
+    if (!this.#branch?.headMessageId) {
+      throw new Error("Cannot create btw branch: no messages in conversation");
+    }
+    return this.#createBranchFrom(this.#branch.headMessageId, false);
+  }
+  /**
+   * Update metadata for the current chat.
+   *
+   * @param updates - Partial metadata to merge (title, metadata)
+   *
+   * @example
+   * ```ts
+   * await context.updateChat({
+   *   title: 'Coding Help Session',
+   *   metadata: { tags: ['python', 'debugging'] }
+   * });
+   * ```
+   */
+  async updateChat(updates) {
+    await this.#ensureInitialized();
+    const storeUpdates = {};
+    if (updates.title !== void 0) {
+      storeUpdates.title = updates.title;
+    }
+    if (updates.metadata !== void 0) {
+      storeUpdates.metadata = {
+        ...this.#chatData?.metadata,
+        ...updates.metadata
+      };
+    }
+    this.#chatData = await this.#store.updateChat(this.#chatId, storeUpdates);
+  }
+  /**
+   * Consolidate context fragments (no-op for now).
+   *
+   * This is a placeholder for future functionality that merges context fragments
+   * using specific rules. Currently, it does nothing.
+   *
+   * @experimental
+   */
+  consolidate() {
+    return void 0;
+  }
+  /**
+   * Inspect the full context state for debugging.
+   * Returns a comprehensive JSON-serializable object with all context information.
+   *
+   * @param options - Inspection options (modelId and renderer required)
+   * @returns Complete inspection data including estimates, rendered output, fragments, and graph
+   *
+   * @example
+   * ```ts
+   * const inspection = await context.inspect({
+   *   modelId: 'openai:gpt-4o',
+   *   renderer: new XmlRenderer(),
+   * });
+   * console.log(JSON.stringify(inspection, null, 2));
+   *
+   * // Or write to file for analysis
+   * await fs.writeFile('context-debug.json', JSON.stringify(inspection, null, 2));
+   * ```
+   */
+  async inspect(options) {
+    await this.#ensureInitialized();
+    const { renderer } = options;
+    const estimateResult = await this.estimate(options.modelId, { renderer });
+    const rendered = renderer.render(this.#fragments);
+    const persistedMessages = [];
+    if (this.#branch?.headMessageId) {
+      const chain = await this.#store.getMessageChain(
+        this.#branch.headMessageId
+      );
+      persistedMessages.push(...chain);
+    }
+    const graph = await this.#store.getGraph(this.#chatId);
+    return {
+      estimate: estimateResult,
+      rendered,
+      fragments: {
+        context: [...this.#fragments],
+        pending: [...this.#pendingMessages],
+        persisted: persistedMessages
+      },
+      graph,
+      meta: {
+        chatId: this.#chatId,
+        branch: this.#branchName,
+        timestamp: Date.now()
+      }
+    };
+  }
+};
+
+// packages/context/src/lib/fragments/domain.ts
+function term(name, definition) {
+  return {
+    name: "term",
+    data: { name, definition }
+  };
+}
+function hint(text) {
+  return {
+    name: "hint",
+    data: text
+  };
+}
+function guardrail(input) {
+  return {
+    name: "guardrail",
+    data: {
+      rule: input.rule,
+      ...input.reason && { reason: input.reason },
+      ...input.action && { action: input.action }
+    }
+  };
+}
+function explain(input) {
+  return {
+    name: "explain",
+    data: {
+      concept: input.concept,
+      explanation: input.explanation,
+      ...input.therefore && { therefore: input.therefore }
+    }
+  };
+}
+function example(input) {
+  return {
+    name: "example",
+    data: {
+      question: input.question,
+      answer: input.answer,
+      ...input.note && { note: input.note }
+    }
+  };
+}
+function clarification(input) {
+  return {
+    name: "clarification",
+    data: {
+      when: input.when,
+      ask: input.ask,
+      reason: input.reason
+    }
+  };
+}
+function workflow(input) {
+  return {
+    name: "workflow",
+    data: {
+      task: input.task,
+      steps: input.steps,
+      ...input.triggers?.length && { triggers: input.triggers },
+      ...input.notes && { notes: input.notes }
+    }
+  };
+}
+function quirk(input) {
+  return {
+    name: "quirk",
+    data: {
+      issue: input.issue,
+      workaround: input.workaround
+    }
+  };
+}
+function styleGuide(input) {
+  return {
+    name: "styleGuide",
+    data: {
+      prefer: input.prefer,
+      ...input.never && { never: input.never },
+      ...input.always && { always: input.always }
+    }
+  };
+}
+function analogy(input) {
+  return {
+    name: "analogy",
+    data: {
+      concepts: input.concepts,
+      relationship: input.relationship,
+      ...input.insight && { insight: input.insight },
+      ...input.therefore && { therefore: input.therefore },
+      ...input.pitfall && { pitfall: input.pitfall }
+    }
+  };
+}
+function glossary(entries) {
+  return {
+    name: "glossary",
+    data: Object.entries(entries).map(([term2, expression]) => ({
+      term: term2,
+      expression
+    }))
+  };
+}
+
+// packages/context/src/lib/fragments/user.ts
+function identity(input) {
+  return {
+    name: "identity",
+    data: {
+      ...input.name && { name: input.name },
+      ...input.role && { role: input.role }
+    }
+  };
+}
+function persona(input) {
+  return {
+    name: "persona",
+    data: {
+      name: input.name,
+      role: input.role,
+      ...input.tone && { tone: input.tone }
+    }
+  };
+}
+function alias(term2, meaning) {
+  return {
+    name: "alias",
+    data: { term: term2, meaning }
+  };
+}
+function preference(aspect, value) {
+  return {
+    name: "preference",
+    data: { aspect, value }
+  };
+}
+function userContext(description) {
+  return {
+    name: "userContext",
+    data: description
+  };
+}
+function correction(subject, clarification2) {
+  return {
+    name: "correction",
+    data: { subject, clarification: clarification2 }
+  };
+}
+
+// packages/context/src/lib/guardrail.ts
+function pass(part) {
+  return { type: "pass", part };
+}
+function fail(feedback) {
+  return { type: "fail", feedback };
+}
+function runGuardrailChain(part, guardrails, context) {
+  let currentPart = part;
+  for (const guardrail2 of guardrails) {
+    const result = guardrail2.handle(currentPart, context);
+    if (result.type === "fail") {
+      return result;
+    }
+    currentPart = result.part;
+  }
+  return pass(currentPart);
+}
+
+// packages/context/src/lib/sandbox/binary-bridges.ts
+import { defineCommand } from "just-bash";
+import spawn from "nano-spawn";
+import * as path from "path";
+import { existsSync } from "fs";
+function createBinaryBridges(...binaries) {
+  return binaries.map((input) => {
+    const config = typeof input === "string" ? { name: input } : input;
+    const { name, binaryPath = name, allowedArgs } = config;
+    return defineCommand(name, async (args, ctx) => {
+      if (allowedArgs) {
+        const invalidArg = args.find((arg) => !allowedArgs.test(arg));
+        if (invalidArg) {
+          return {
+            stdout: "",
+            stderr: `${name}: argument '${invalidArg}' not allowed by security policy`,
+            exitCode: 1
+          };
+        }
+      }
+      try {
+        const realCwd = resolveRealCwd(ctx);
+        const resolvedArgs = args.map((arg) => {
+          if (arg.startsWith("-")) {
+            return arg;
+          }
+          const hasExtension = path.extname(arg) !== "";
+          const hasPathSep = arg.includes(path.sep) || arg.includes("/");
+          const isRelative = arg.startsWith(".");
+          if (hasExtension || hasPathSep || isRelative) {
+            return path.resolve(realCwd, arg);
+          }
+          return arg;
+        });
+        const mergedEnv = {
+          ...process.env,
+          ...ctx.env,
+          PATH: process.env.PATH
+          // Always use host PATH for binary bridges
+        };
+        const result = await spawn(binaryPath, resolvedArgs, {
+          cwd: realCwd,
+          env: mergedEnv
+        });
+        return {
+          stdout: result.stdout,
+          stderr: result.stderr,
+          exitCode: 0
+        };
+      } catch (error) {
+        if (error && typeof error === "object" && "exitCode" in error) {
+          const subprocessError = error;
+          return {
+            stdout: subprocessError.stdout ?? "",
+            stderr: subprocessError.stderr ?? "",
+            exitCode: subprocessError.exitCode ?? 1
+          };
+        }
+        return {
+          stdout: "",
+          stderr: `${name}: ${error instanceof Error ? error.message : String(error)}`,
+          exitCode: 127
+        };
+      }
+    });
+  });
+}
+function resolveRealCwd(ctx) {
+  const fs2 = ctx.fs;
+  let realCwd;
+  if (fs2.root) {
+    realCwd = path.join(fs2.root, ctx.cwd);
+  } else if (typeof fs2.getMountPoint === "function" && typeof fs2.toRealPath === "function") {
+    const real = fs2.toRealPath(ctx.cwd);
+    realCwd = real ?? process.cwd();
+  } else {
+    realCwd = process.cwd();
+  }
+  if (!existsSync(realCwd)) {
+    realCwd = process.cwd();
+  }
+  return realCwd;
+}
+
+// packages/context/src/lib/sandbox/docker-sandbox.ts
+import "bash-tool";
+import spawn2 from "nano-spawn";
+import { createHash } from "node:crypto";
+import { existsSync as existsSync2, readFileSync } from "node:fs";
+var DockerSandboxError = class extends Error {
+  containerId;
+  constructor(message2, containerId) {
+    super(message2);
+    this.name = "DockerSandboxError";
+    this.containerId = containerId;
+  }
+};
+var DockerNotAvailableError = class extends DockerSandboxError {
+  constructor() {
+    super("Docker is not available. Ensure Docker daemon is running.");
+    this.name = "DockerNotAvailableError";
+  }
+};
+var ContainerCreationError = class extends DockerSandboxError {
+  image;
+  cause;
+  constructor(message2, image, cause) {
+    super(`Failed to create container from image "${image}": ${message2}`);
+    this.name = "ContainerCreationError";
+    this.image = image;
+    this.cause = cause;
+  }
+};
+var PackageInstallError = class extends DockerSandboxError {
+  packages;
+  image;
+  packageManager;
+  stderr;
+  constructor(packages, image, packageManager, stderr, containerId) {
+    super(
+      `Package installation failed for [${packages.join(", ")}] using ${packageManager} on ${image}: ${stderr}`,
+      containerId
+    );
+    this.name = "PackageInstallError";
+    this.packages = packages;
+    this.image = image;
+    this.packageManager = packageManager;
+    this.stderr = stderr;
+  }
+};
+var BinaryInstallError = class extends DockerSandboxError {
+  binaryName;
+  url;
+  reason;
+  constructor(binaryName, url, reason, containerId) {
+    super(
+      `Failed to install binary "${binaryName}" from ${url}: ${reason}`,
+      containerId
+    );
+    this.name = "BinaryInstallError";
+    this.binaryName = binaryName;
+    this.url = url;
+    this.reason = reason;
+  }
+};
+var MountPathError = class extends DockerSandboxError {
+  hostPath;
+  containerPath;
+  constructor(hostPath, containerPath) {
+    super(
+      `Mount path does not exist on host: "${hostPath}" -> "${containerPath}"`
+    );
+    this.name = "MountPathError";
+    this.hostPath = hostPath;
+    this.containerPath = containerPath;
+  }
+};
+var DockerfileBuildError = class extends DockerSandboxError {
+  stderr;
+  constructor(stderr) {
+    super(`Dockerfile build failed: ${stderr}`);
+    this.name = "DockerfileBuildError";
+    this.stderr = stderr;
+  }
+};
+var ComposeStartError = class extends DockerSandboxError {
+  composeFile;
+  stderr;
+  constructor(composeFile, stderr) {
+    super(`Docker Compose failed to start: ${stderr}`);
+    this.name = "ComposeStartError";
+    this.composeFile = composeFile;
+    this.stderr = stderr;
+  }
+};
+function isDebianBased(image) {
+  const debianPatterns = ["debian", "ubuntu", "node", "python"];
+  return debianPatterns.some(
+    (pattern) => image.toLowerCase().includes(pattern)
+  );
+}
+function isDockerfileOptions(opts) {
+  return "dockerfile" in opts;
+}
+function isComposeOptions(opts) {
+  return "compose" in opts;
+}
+var DockerSandboxStrategy = class {
+  context;
+  mounts;
+  resources;
+  constructor(mounts = [], resources = {}) {
+    this.mounts = mounts;
+    this.resources = resources;
+  }
+  /**
+   * Template method - defines the algorithm skeleton for creating a sandbox.
+   *
+   * Steps:
+   * 1. Validate mount paths exist on host
+   * 2. Get/build the Docker image (strategy-specific)
+   * 3. Start the container
+   * 4. Configure the container (strategy-specific)
+   * 5. Create and return sandbox methods
+   */
+  async create() {
+    this.validateMounts();
+    const image = await this.getImage();
+    const containerId = await this.startContainer(image);
+    this.context = { containerId, image };
+    try {
+      await this.configure();
+    } catch (error) {
+      await this.stopContainer(containerId);
+      throw error;
+    }
+    return this.createSandboxMethods();
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Common implementations (shared by all strategies)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Validates that all mount paths exist on the host filesystem.
+   */
+  validateMounts() {
+    for (const mount of this.mounts) {
+      if (!existsSync2(mount.hostPath)) {
+        throw new MountPathError(mount.hostPath, mount.containerPath);
+      }
+    }
+  }
+  /**
+   * Builds the docker run command arguments.
+   */
+  buildDockerArgs(image, containerId) {
+    const { memory = "1g", cpus = 2 } = this.resources;
+    const args = [
+      "run",
+      "-d",
+      // Detached mode
+      "--rm",
+      // Remove container when stopped
+      "--name",
+      containerId,
+      `--memory=${memory}`,
+      `--cpus=${cpus}`,
+      "-w",
+      "/workspace"
+      // Set working directory
+    ];
+    for (const mount of this.mounts) {
+      const mode = mount.readOnly !== false ? "ro" : "rw";
+      args.push("-v", `${mount.hostPath}:${mount.containerPath}:${mode}`);
+    }
+    args.push(image, "tail", "-f", "/dev/null");
+    return args;
+  }
+  /**
+   * Starts a Docker container with the given image.
+   */
+  async startContainer(image) {
+    const containerId = `sandbox-${crypto.randomUUID().slice(0, 8)}`;
+    const args = this.buildDockerArgs(image, containerId);
+    try {
+      await spawn2("docker", args);
+    } catch (error) {
+      const err = error;
+      if (err.message?.includes("Cannot connect") || err.message?.includes("docker daemon") || err.stderr?.includes("Cannot connect")) {
+        throw new DockerNotAvailableError();
+      }
+      throw new ContainerCreationError(err.message || String(err), image, err);
+    }
+    return containerId;
+  }
+  /**
+   * Stops a Docker container.
+   */
+  async stopContainer(containerId) {
+    try {
+      await spawn2("docker", ["stop", containerId]);
+    } catch {
+    }
+  }
+  /**
+   * Executes a command in the container.
+   */
+  async exec(command) {
+    try {
+      const result = await spawn2("docker", [
+        "exec",
+        this.context.containerId,
+        "sh",
+        "-c",
+        command
+      ]);
+      return {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: 0
+      };
+    } catch (error) {
+      const err = error;
+      return {
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message || "",
+        exitCode: err.exitCode ?? 1
+      };
+    }
+  }
+  /**
+   * Creates the DockerSandbox interface with all methods.
+   */
+  createSandboxMethods() {
+    const { containerId } = this.context;
+    const sandbox = {
+      executeCommand: async (command) => {
+        return this.exec(command);
+      },
+      readFile: async (path3) => {
+        const result = await sandbox.executeCommand(`base64 "${path3}"`);
+        if (result.exitCode !== 0) {
+          throw new Error(`Failed to read file "${path3}": ${result.stderr}`);
+        }
+        return Buffer.from(result.stdout, "base64").toString("utf-8");
+      },
+      writeFiles: async (files) => {
+        for (const file of files) {
+          const dir = file.path.substring(0, file.path.lastIndexOf("/"));
+          if (dir) {
+            await sandbox.executeCommand(`mkdir -p "${dir}"`);
+          }
+          const base64Content = Buffer.from(file.content).toString("base64");
+          const result = await sandbox.executeCommand(
+            `echo "${base64Content}" | base64 -d > "${file.path}"`
+          );
+          if (result.exitCode !== 0) {
+            throw new Error(
+              `Failed to write file "${file.path}": ${result.stderr}`
+            );
+          }
+        }
+      },
+      dispose: async () => {
+        await this.stopContainer(containerId);
+      }
+    };
+    return sandbox;
+  }
+};
+var RuntimeStrategy = class extends DockerSandboxStrategy {
+  image;
+  packages;
+  binaries;
+  constructor(image = "alpine:latest", packages = [], binaries = [], mounts, resources) {
+    super(mounts, resources);
+    this.image = image;
+    this.packages = packages;
+    this.binaries = binaries;
+  }
+  async getImage() {
+    return this.image;
+  }
+  async configure() {
+    await this.installPackages();
+    await this.installBinaries();
+  }
+  /**
+   * Installs packages using the appropriate package manager (apk/apt-get).
+   */
+  async installPackages() {
+    if (this.packages.length === 0) return;
+    const useApt = isDebianBased(this.image);
+    const installCmd = useApt ? `apt-get update && apt-get install -y ${this.packages.join(" ")}` : `apk add --no-cache ${this.packages.join(" ")}`;
+    try {
+      await spawn2("docker", [
+        "exec",
+        this.context.containerId,
+        "sh",
+        "-c",
+        installCmd
+      ]);
+    } catch (error) {
+      const err = error;
+      throw new PackageInstallError(
+        this.packages,
+        this.image,
+        useApt ? "apt-get" : "apk",
+        err.stderr || err.message,
+        this.context.containerId
+      );
+    }
+  }
+  /**
+   * Installs binaries from URLs.
+   */
+  async installBinaries() {
+    if (this.binaries.length === 0) return;
+    await this.ensureCurl();
+    const arch = await this.detectArchitecture();
+    for (const binary of this.binaries) {
+      await this.installBinary(binary, arch);
+    }
+  }
+  /**
+   * Ensures curl is installed in the container.
+   */
+  async ensureCurl() {
+    const checkResult = await spawn2("docker", [
+      "exec",
+      this.context.containerId,
+      "which",
+      "curl"
+    ]).catch(() => null);
+    if (checkResult) return;
+    const useApt = isDebianBased(this.image);
+    const curlInstallCmd = useApt ? "apt-get update && apt-get install -y curl" : "apk add --no-cache curl";
+    try {
+      await spawn2("docker", [
+        "exec",
+        this.context.containerId,
+        "sh",
+        "-c",
+        curlInstallCmd
+      ]);
+    } catch (error) {
+      const err = error;
+      throw new BinaryInstallError(
+        "curl",
+        "package-manager",
+        `Required for binary downloads: ${err.stderr || err.message}`,
+        this.context.containerId
+      );
+    }
+  }
+  /**
+   * Detects the container's CPU architecture.
+   */
+  async detectArchitecture() {
+    try {
+      const result = await spawn2("docker", [
+        "exec",
+        this.context.containerId,
+        "uname",
+        "-m"
+      ]);
+      return result.stdout.trim();
+    } catch (error) {
+      const err = error;
+      throw new DockerSandboxError(
+        `Failed to detect container architecture: ${err.stderr || err.message}`,
+        this.context.containerId
+      );
+    }
+  }
+  /**
+   * Installs a single binary from URL.
+   */
+  async installBinary(binary, arch) {
+    let url;
+    if (typeof binary.url === "string") {
+      url = binary.url;
+    } else {
+      const archUrl = binary.url[arch];
+      if (!archUrl) {
+        throw new BinaryInstallError(
+          binary.name,
+          `arch:${arch}`,
+          `No URL provided for architecture "${arch}". Available: ${Object.keys(binary.url).join(", ")}`,
+          this.context.containerId
+        );
+      }
+      url = archUrl;
+    }
+    const isTarGz = url.endsWith(".tar.gz") || url.endsWith(".tgz");
+    let installCmd;
+    if (isTarGz) {
+      const binaryPathInArchive = binary.binaryPath || binary.name;
+      installCmd = `
+        set -e
+        TMPDIR=$(mktemp -d)
+        cd "$TMPDIR"
+        curl -fsSL "${url}" -o archive.tar.gz
+        tar -xzf archive.tar.gz
+        BINARY_FILE=$(find . -name "${binaryPathInArchive}" -o -name "${binary.name}" | head -1)
+        if [ -z "$BINARY_FILE" ]; then
+          echo "Binary not found in archive. Contents:" >&2
+          find . -type f >&2
+          exit 1
+        fi
+        chmod +x "$BINARY_FILE"
+        mv "$BINARY_FILE" /usr/local/bin/${binary.name}
+        cd /
+        rm -rf "$TMPDIR"
+      `;
+    } else {
+      installCmd = `
+        curl -fsSL "${url}" -o /usr/local/bin/${binary.name}
+        chmod +x /usr/local/bin/${binary.name}
+      `;
+    }
+    try {
+      await spawn2("docker", [
+        "exec",
+        this.context.containerId,
+        "sh",
+        "-c",
+        installCmd
+      ]);
+    } catch (error) {
+      const err = error;
+      throw new BinaryInstallError(
+        binary.name,
+        url,
+        err.stderr || err.message,
+        this.context.containerId
+      );
+    }
+  }
+};
+var DockerfileStrategy = class extends DockerSandboxStrategy {
+  imageTag;
+  dockerfile;
+  dockerContext;
+  constructor(dockerfile, dockerContext = ".", mounts, resources) {
+    super(mounts, resources);
+    this.dockerfile = dockerfile;
+    this.dockerContext = dockerContext;
+    this.imageTag = this.computeImageTag();
+  }
+  /**
+   * Computes a deterministic image tag based on Dockerfile content.
+   * Same Dockerfile → same tag → Docker skips rebuild if image exists.
+   */
+  computeImageTag() {
+    const content = this.isInlineDockerfile() ? this.dockerfile : readFileSync(this.dockerfile, "utf-8");
+    const hash = createHash("sha256").update(content).digest("hex").slice(0, 12);
+    return `sandbox-${hash}`;
+  }
+  /**
+   * Checks if the dockerfile property is inline content or a file path.
+   */
+  isInlineDockerfile() {
+    return this.dockerfile.includes("\n");
+  }
+  async getImage() {
+    const exists = await this.imageExists();
+    if (!exists) {
+      await this.buildImage();
+    }
+    return this.imageTag;
   }
-  async deleteCheckpoint(chatId, name) {
-    this.#db.prepare("DELETE FROM checkpoints WHERE chatId = ? AND name = ?").run(chatId, name);
+  async configure() {
   }
-  // ==========================================================================
-  // Search Operations
-  // ==========================================================================
-  async searchMessages(chatId, query, options) {
-    const limit = options?.limit ?? 20;
-    const roles = options?.roles;
-    let sql = `
-      SELECT
-        m.id,
-        m.chatId,
-        m.parentId,
-        m.name,
-        m.type,
-        m.data,
-        m.createdAt,
-        fts.rank,
-        snippet(messages_fts, 3, '<mark>', '</mark>', '...', 32) as snippet
-      FROM messages_fts fts
-      JOIN messages m ON m.id = fts.messageId
-      WHERE messages_fts MATCH ?
-        AND fts.chatId = ?
-    `;
-    const params = [query, chatId];
-    if (roles && roles.length > 0) {
-      const placeholders = roles.map(() => "?").join(", ");
-      sql += ` AND fts.name IN (${placeholders})`;
-      params.push(...roles);
+  /**
+   * Checks if the image already exists locally.
+   */
+  async imageExists() {
+    try {
+      await spawn2("docker", ["image", "inspect", this.imageTag]);
+      return true;
+    } catch {
+      return false;
     }
-    sql += " ORDER BY fts.rank LIMIT ?";
-    params.push(limit);
-    const rows = this.#db.prepare(sql).all(...params);
-    return rows.map((row) => ({
-      message: {
-        id: row.id,
-        chatId: row.chatId,
-        parentId: row.parentId,
-        name: row.name,
-        type: row.type ?? void 0,
-        data: JSON.parse(row.data),
-        createdAt: row.createdAt
-      },
-      rank: row.rank,
-      snippet: row.snippet
-    }));
   }
-  // ==========================================================================
-  // Visualization Operations
-  // ==========================================================================
-  async getGraph(chatId) {
-    const messageRows = this.#db.prepare(
-      `SELECT id, parentId, name, data, createdAt
-         FROM messages
-         WHERE chatId = ?
-         ORDER BY createdAt ASC`
-    ).all(chatId);
-    const nodes = messageRows.map((row) => {
-      const data = JSON.parse(row.data);
-      const content = typeof data === "string" ? data : JSON.stringify(data);
+  /**
+   * Builds the Docker image from the Dockerfile.
+   */
+  async buildImage() {
+    try {
+      if (this.isInlineDockerfile()) {
+        const buildCmd = `echo '${this.dockerfile.replace(/'/g, "'\\''")}' | docker build -t ${this.imageTag} -f - ${this.dockerContext}`;
+        await spawn2("sh", ["-c", buildCmd]);
+      } else {
+        await spawn2("docker", [
+          "build",
+          "-t",
+          this.imageTag,
+          "-f",
+          this.dockerfile,
+          this.dockerContext
+        ]);
+      }
+    } catch (error) {
+      const err = error;
+      throw new DockerfileBuildError(err.stderr || err.message);
+    }
+  }
+};
+var ComposeStrategy = class extends DockerSandboxStrategy {
+  projectName;
+  composeFile;
+  service;
+  constructor(composeFile, service, resources) {
+    super([], resources);
+    this.composeFile = composeFile;
+    this.service = service;
+    this.projectName = this.computeProjectName();
+  }
+  /**
+   * Deterministic project name based on compose file content for caching.
+   * Same compose file → same project name → faster subsequent startups.
+   */
+  computeProjectName() {
+    const content = readFileSync(this.composeFile, "utf-8");
+    const hash = createHash("sha256").update(content).digest("hex").slice(0, 8);
+    return `sandbox-${hash}`;
+  }
+  /**
+   * Override: No image to get - compose manages its own images.
+   */
+  async getImage() {
+    return "";
+  }
+  /**
+   * Override: Start all services with docker compose up.
+   */
+  async startContainer(_image) {
+    try {
+      await spawn2("docker", [
+        "compose",
+        "-f",
+        this.composeFile,
+        "-p",
+        this.projectName,
+        "up",
+        "-d"
+      ]);
+    } catch (error) {
+      const err = error;
+      if (err.stderr?.includes("Cannot connect")) {
+        throw new DockerNotAvailableError();
+      }
+      throw new ComposeStartError(this.composeFile, err.stderr || err.message);
+    }
+    return this.projectName;
+  }
+  async configure() {
+  }
+  /**
+   * Override: Execute commands in the target service.
+   */
+  async exec(command) {
+    try {
+      const result = await spawn2("docker", [
+        "compose",
+        "-f",
+        this.composeFile,
+        "-p",
+        this.projectName,
+        "exec",
+        "-T",
+        // -T disables pseudo-TTY
+        this.service,
+        "sh",
+        "-c",
+        command
+      ]);
+      return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
+    } catch (error) {
+      const err = error;
       return {
-        id: row.id,
-        parentId: row.parentId,
-        role: row.name,
-        content: content.length > 50 ? content.slice(0, 50) + "..." : content,
-        createdAt: row.createdAt
+        stdout: err.stdout || "",
+        stderr: err.stderr || err.message || "",
+        exitCode: err.exitCode ?? 1
       };
-    });
-    const branchRows = this.#db.prepare(
-      `SELECT name, headMessageId, isActive
-         FROM branches
-         WHERE chatId = ?
-         ORDER BY createdAt ASC`
-    ).all(chatId);
-    const branches = branchRows.map((row) => ({
-      name: row.name,
-      headMessageId: row.headMessageId,
-      isActive: row.isActive === 1
-    }));
-    const checkpointRows = this.#db.prepare(
-      `SELECT name, messageId
-         FROM checkpoints
-         WHERE chatId = ?
-         ORDER BY createdAt ASC`
-    ).all(chatId);
-    const checkpoints = checkpointRows.map((row) => ({
-      name: row.name,
-      messageId: row.messageId
-    }));
-    return {
-      chatId,
-      nodes,
-      branches,
-      checkpoints
-    };
+    }
   }
-};
-
-// packages/context/src/lib/store/memory.store.ts
-var InMemoryContextStore = class extends SqliteContextStore {
-  constructor() {
-    super(":memory:");
+  /**
+   * Override: Stop all services with docker compose down.
+   */
+  async stopContainer(_containerId) {
+    try {
+      await spawn2("docker", [
+        "compose",
+        "-f",
+        this.composeFile,
+        "-p",
+        this.projectName,
+        "down"
+      ]);
+    } catch {
+    }
   }
 };
+async function createDockerSandbox(options = {}) {
+  let strategy;
+  if (isComposeOptions(options)) {
+    strategy = new ComposeStrategy(
+      options.compose,
+      options.service,
+      options.resources
+    );
+  } else if (isDockerfileOptions(options)) {
+    strategy = new DockerfileStrategy(
+      options.dockerfile,
+      options.context,
+      options.mounts,
+      options.resources
+    );
+  } else {
+    strategy = new RuntimeStrategy(
+      options.image,
+      options.packages,
+      options.binaries,
+      options.mounts,
+      options.resources
+    );
+  }
+  return strategy.create();
+}
+async function useSandbox(options, fn) {
+  const sandbox = await createDockerSandbox(options);
+  try {
+    return await fn(sandbox);
+  } finally {
+    await sandbox.dispose();
+  }
+}
 
-// packages/context/src/lib/visualize.ts
-function visualizeGraph(data) {
-  if (data.nodes.length === 0) {
-    return `[chat: ${data.chatId}]
+// packages/context/src/lib/sandbox/container-tool.ts
+import {
+  createBashTool
+} from "bash-tool";
+async function createContainerTool(options = {}) {
+  let sandboxOptions;
+  let bashOptions;
+  if (isComposeOptions(options)) {
+    const { compose, service, resources, ...rest } = options;
+    sandboxOptions = { compose, service, resources };
+    bashOptions = rest;
+  } else if (isDockerfileOptions(options)) {
+    const { dockerfile, context, mounts, resources, ...rest } = options;
+    sandboxOptions = { dockerfile, context, mounts, resources };
+    bashOptions = rest;
+  } else {
+    const { image, packages, binaries, mounts, resources, ...rest } = options;
+    sandboxOptions = { image, packages, binaries, mounts, resources };
+    bashOptions = rest;
+  }
+  const sandbox = await createDockerSandbox(sandboxOptions);
+  const toolkit = await createBashTool({
+    ...bashOptions,
+    sandbox
+  });
+  return {
+    bash: toolkit.bash,
+    tools: toolkit.tools,
+    sandbox
+  };
+}
 
-(empty)`;
+// packages/context/src/lib/skills/loader.ts
+import * as fs from "node:fs";
+import * as path2 from "node:path";
+import YAML from "yaml";
+function parseFrontmatter(content) {
+  const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+  if (!match) {
+    throw new Error("Invalid SKILL.md: missing or malformed frontmatter");
+  }
+  const [, yamlContent, body] = match;
+  const frontmatter = YAML.parse(yamlContent);
+  if (!frontmatter.name || typeof frontmatter.name !== "string") {
+    throw new Error('Invalid SKILL.md: frontmatter must have a "name" field');
+  }
+  if (!frontmatter.description || typeof frontmatter.description !== "string") {
+    throw new Error('Invalid SKILL.md: frontmatter must have a "description" field');
   }
-  const childrenByParentId = /* @__PURE__ */ new Map();
-  const branchHeads = /* @__PURE__ */ new Map();
-  const checkpointsByMessageId = /* @__PURE__ */ new Map();
-  for (const node of data.nodes) {
-    const children = childrenByParentId.get(node.parentId) ?? [];
-    children.push(node);
-    childrenByParentId.set(node.parentId, children);
+  return {
+    frontmatter,
+    body: body.trim()
+  };
+}
+function loadSkillMetadata(skillMdPath) {
+  const content = fs.readFileSync(skillMdPath, "utf-8");
+  const parsed = parseFrontmatter(content);
+  const skillDir = path2.dirname(skillMdPath);
+  return {
+    name: parsed.frontmatter.name,
+    description: parsed.frontmatter.description,
+    path: skillDir,
+    skillMdPath
+  };
+}
+function discoverSkillsInDirectory(directory) {
+  const skills2 = [];
+  const expandedDir = directory.startsWith("~") ? path2.join(process.env.HOME || "", directory.slice(1)) : directory;
+  if (!fs.existsSync(expandedDir)) {
+    return skills2;
+  }
+  const entries = fs.readdirSync(expandedDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillMdPath = path2.join(expandedDir, entry.name, "SKILL.md");
+    if (!fs.existsSync(skillMdPath)) continue;
+    try {
+      const metadata = loadSkillMetadata(skillMdPath);
+      skills2.push(metadata);
+    } catch (error) {
+      console.warn(`Warning: Failed to load skill at ${skillMdPath}:`, error);
+    }
+  }
+  return skills2;
+}
+
+// packages/context/src/lib/skills/fragments.ts
+function skills(options) {
+  const skillsMap = /* @__PURE__ */ new Map();
+  for (const dir of options.paths) {
+    const discovered = discoverSkillsInDirectory(dir);
+    for (const skill of discovered) {
+      skillsMap.set(skill.name, skill);
+    }
+  }
+  const allSkills = Array.from(skillsMap.values());
+  let filteredSkills = allSkills;
+  if (options.include) {
+    filteredSkills = allSkills.filter((s) => options.include.includes(s.name));
+  }
+  if (options.exclude) {
+    filteredSkills = filteredSkills.filter(
+      (s) => !options.exclude.includes(s.name)
+    );
   }
-  for (const branch of data.branches) {
-    if (branch.headMessageId) {
-      const heads = branchHeads.get(branch.headMessageId) ?? [];
-      heads.push(branch.isActive ? `${branch.name} *` : branch.name);
-      branchHeads.set(branch.headMessageId, heads);
+  const skillFragments = filteredSkills.map((skill) => ({
+    name: "skill",
+    data: {
+      name: skill.name,
+      path: skill.skillMdPath,
+      description: skill.description
     }
+  }));
+  return {
+    name: "available_skills",
+    data: [
+      {
+        name: "instructions",
+        data: SKILLS_INSTRUCTIONS
+      },
+      ...skillFragments
+    ]
+  };
+}
+var SKILLS_INSTRUCTIONS = `When a user's request matches one of the skills listed below, read the skill's SKILL.md file to get detailed instructions before proceeding. Skills provide specialized knowledge and workflows for specific tasks.
+
+To use a skill:
+1. Identify if the user's request matches a skill's description
+2. Read the SKILL.md file at the skill's path to load full instructions
+3. Follow the skill's guidance to complete the task
+
+Skills are only loaded when relevant - don't read skill files unless needed.`;
+
+// packages/context/src/lib/store/sqlite.store.ts
+import { DatabaseSync } from "node:sqlite";
+var STORE_DDL = `
+-- Chats table
+-- createdAt/updatedAt: DEFAULT for insert, inline SET for updates
+CREATE TABLE IF NOT EXISTS chats (
+  id TEXT PRIMARY KEY,
+  title TEXT,
+  metadata TEXT,
+  createdAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
+  updatedAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)
+);
+
+CREATE INDEX IF NOT EXISTS idx_chats_updatedAt ON chats(updatedAt);
+
+-- Messages table (nodes in the DAG)
+CREATE TABLE IF NOT EXISTS messages (
+  id TEXT PRIMARY KEY,
+  chatId TEXT NOT NULL,
+  parentId TEXT,
+  name TEXT NOT NULL,
+  type TEXT,
+  data TEXT NOT NULL,
+  createdAt INTEGER NOT NULL,
+  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
+  FOREIGN KEY (parentId) REFERENCES messages(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_chatId ON messages(chatId);
+CREATE INDEX IF NOT EXISTS idx_messages_parentId ON messages(parentId);
+
+-- Branches table (pointers to head messages)
+CREATE TABLE IF NOT EXISTS branches (
+  id TEXT PRIMARY KEY,
+  chatId TEXT NOT NULL,
+  name TEXT NOT NULL,
+  headMessageId TEXT,
+  isActive INTEGER NOT NULL DEFAULT 0,
+  createdAt INTEGER NOT NULL,
+  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
+  FOREIGN KEY (headMessageId) REFERENCES messages(id),
+  UNIQUE(chatId, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_branches_chatId ON branches(chatId);
+
+-- Checkpoints table (pointers to message nodes)
+CREATE TABLE IF NOT EXISTS checkpoints (
+  id TEXT PRIMARY KEY,
+  chatId TEXT NOT NULL,
+  name TEXT NOT NULL,
+  messageId TEXT NOT NULL,
+  createdAt INTEGER NOT NULL,
+  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,
+  FOREIGN KEY (messageId) REFERENCES messages(id),
+  UNIQUE(chatId, name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoints_chatId ON checkpoints(chatId);
+
+-- FTS5 virtual table for full-text search
+-- messageId/chatId/name are UNINDEXED (stored but not searchable, used for filtering/joining)
+-- Only 'content' is indexed for full-text search
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+  messageId UNINDEXED,
+  chatId UNINDEXED,
+  name UNINDEXED,
+  content,
+  tokenize='porter unicode61'
+);
+`;
+var SqliteContextStore = class extends ContextStore {
+  #db;
+  constructor(path3) {
+    super();
+    this.#db = new DatabaseSync(path3);
+    this.#db.exec("PRAGMA foreign_keys = ON");
+    this.#db.exec(STORE_DDL);
+  }
+  // ==========================================================================
+  // Chat Operations
+  // ==========================================================================
+  async createChat(chat) {
+    this.#db.prepare(
+      `INSERT INTO chats (id, title, metadata)
+         VALUES (?, ?, ?)`
+    ).run(
+      chat.id,
+      chat.title ?? null,
+      chat.metadata ? JSON.stringify(chat.metadata) : null
+    );
   }
-  for (const checkpoint of data.checkpoints) {
-    const cps = checkpointsByMessageId.get(checkpoint.messageId) ?? [];
-    cps.push(checkpoint.name);
-    checkpointsByMessageId.set(checkpoint.messageId, cps);
+  async upsertChat(chat) {
+    const row = this.#db.prepare(
+      `INSERT INTO chats (id, title, metadata)
+         VALUES (?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET id = excluded.id
+         RETURNING *`
+    ).get(
+      chat.id,
+      chat.title ?? null,
+      chat.metadata ? JSON.stringify(chat.metadata) : null
+    );
+    return {
+      id: row.id,
+      title: row.title ?? void 0,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt
+    };
   }
-  const roots = childrenByParentId.get(null) ?? [];
-  const lines = [`[chat: ${data.chatId}]`, ""];
-  function renderNode(node, prefix, isLast, isRoot) {
-    const connector = isRoot ? "" : isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
-    const contentPreview = node.content.replace(/\n/g, " ");
-    let line = `${prefix}${connector}${node.id.slice(0, 8)} (${node.role}): "${contentPreview}"`;
-    const branches = branchHeads.get(node.id);
-    if (branches) {
-      line += ` <- [${branches.join(", ")}]`;
+  async getChat(chatId) {
+    const row = this.#db.prepare("SELECT * FROM chats WHERE id = ?").get(chatId);
+    if (!row) {
+      return void 0;
     }
-    const checkpoints = checkpointsByMessageId.get(node.id);
-    if (checkpoints) {
-      line += ` {${checkpoints.join(", ")}}`;
+    return {
+      id: row.id,
+      title: row.title ?? void 0,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt
+    };
+  }
+  async updateChat(chatId, updates) {
+    const setClauses = ["updatedAt = strftime('%s', 'now') * 1000"];
+    const params = [];
+    if (updates.title !== void 0) {
+      setClauses.push("title = ?");
+      params.push(updates.title ?? null);
     }
-    lines.push(line);
-    const children = childrenByParentId.get(node.id) ?? [];
-    const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "\u2502   ");
-    for (let i = 0; i < children.length; i++) {
-      renderNode(children[i], childPrefix, i === children.length - 1, false);
+    if (updates.metadata !== void 0) {
+      setClauses.push("metadata = ?");
+      params.push(JSON.stringify(updates.metadata));
     }
+    params.push(chatId);
+    const row = this.#db.prepare(
+      `UPDATE chats SET ${setClauses.join(", ")} WHERE id = ? RETURNING *`
+    ).get(...params);
+    return {
+      id: row.id,
+      title: row.title ?? void 0,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt
+    };
   }
-  for (let i = 0; i < roots.length; i++) {
-    renderNode(roots[i], "", i === roots.length - 1, true);
-  }
-  lines.push("");
-  lines.push("Legend: * = active branch, {...} = checkpoint");
-  return lines.join("\n");
-}
-
-// packages/context/src/index.ts
-var ContextEngine = class {
-  /** Non-message fragments (role, hints, etc.) - not persisted in graph */
-  #fragments = [];
-  /** Pending message fragments to be added to graph */
-  #pendingMessages = [];
-  #store;
-  #chatId;
-  #branchName;
-  #branch = null;
-  #chatData = null;
-  #initialized = false;
-  constructor(options) {
-    if (!options.chatId) {
-      throw new Error("chatId is required");
-    }
-    this.#store = options.store;
-    this.#chatId = options.chatId;
-    this.#branchName = options.branch ?? "main";
+  async listChats() {
+    const rows = this.#db.prepare(
+      `SELECT
+          c.id,
+          c.title,
+          c.createdAt,
+          c.updatedAt,
+          COUNT(DISTINCT m.id) as messageCount,
+          COUNT(DISTINCT b.id) as branchCount
+        FROM chats c
+        LEFT JOIN messages m ON m.chatId = c.id
+        LEFT JOIN branches b ON b.chatId = c.id
+        GROUP BY c.id
+        ORDER BY c.updatedAt DESC`
+    ).all();
+    return rows.map((row) => ({
+      id: row.id,
+      title: row.title ?? void 0,
+      messageCount: row.messageCount,
+      branchCount: row.branchCount,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt
+    }));
   }
-  /**
-   * Initialize the chat and branch if they don't exist.
-   */
-  async #ensureInitialized() {
-    if (this.#initialized) {
-      return;
-    }
-    this.#chatData = await this.#store.upsertChat({ id: this.#chatId });
-    const existingBranch = await this.#store.getBranch(
-      this.#chatId,
-      this.#branchName
+  // ==========================================================================
+  // Message Operations (Graph Nodes)
+  // ==========================================================================
+  async addMessage(message2) {
+    this.#db.prepare(
+      `INSERT INTO messages (id, chatId, parentId, name, type, data, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           parentId = excluded.parentId,
+           name = excluded.name,
+           type = excluded.type,
+           data = excluded.data`
+    ).run(
+      message2.id,
+      message2.chatId,
+      message2.parentId,
+      message2.name,
+      message2.type ?? null,
+      JSON.stringify(message2.data),
+      message2.createdAt
     );
-    if (existingBranch) {
-      this.#branch = existingBranch;
-    } else {
-      this.#branch = {
-        id: crypto.randomUUID(),
-        chatId: this.#chatId,
-        name: this.#branchName,
-        headMessageId: null,
-        isActive: true,
-        createdAt: Date.now()
-      };
-      await this.#store.createBranch(this.#branch);
-    }
-    this.#initialized = true;
+    const content = typeof message2.data === "string" ? message2.data : JSON.stringify(message2.data);
+    this.#db.prepare(`DELETE FROM messages_fts WHERE messageId = ?`).run(message2.id);
+    this.#db.prepare(
+      `INSERT INTO messages_fts(messageId, chatId, name, content)
+         VALUES (?, ?, ?, ?)`
+    ).run(message2.id, message2.chatId, message2.name, content);
   }
-  /**
-   * Create a new branch from a specific message.
-   * Shared logic between rewind() and btw().
-   */
-  async #createBranchFrom(messageId, switchTo) {
-    const branches = await this.#store.listBranches(this.#chatId);
-    const samePrefix = branches.filter(
-      (b) => b.name === this.#branchName || b.name.startsWith(`${this.#branchName}-v`)
-    );
-    const newBranchName = `${this.#branchName}-v${samePrefix.length + 1}`;
-    const newBranch = {
-      id: crypto.randomUUID(),
-      chatId: this.#chatId,
-      name: newBranchName,
-      headMessageId: messageId,
-      isActive: false,
-      createdAt: Date.now()
-    };
-    await this.#store.createBranch(newBranch);
-    if (switchTo) {
-      await this.#store.setActiveBranch(this.#chatId, newBranch.id);
-      this.#branch = { ...newBranch, isActive: true };
-      this.#branchName = newBranchName;
-      this.#pendingMessages = [];
+  async getMessage(messageId) {
+    const row = this.#db.prepare("SELECT * FROM messages WHERE id = ?").get(messageId);
+    if (!row) {
+      return void 0;
     }
-    const chain = await this.#store.getMessageChain(messageId);
     return {
-      id: newBranch.id,
-      name: newBranch.name,
-      headMessageId: newBranch.headMessageId,
-      isActive: switchTo,
-      messageCount: chain.length,
-      createdAt: newBranch.createdAt
+      id: row.id,
+      chatId: row.chatId,
+      parentId: row.parentId,
+      name: row.name,
+      type: row.type ?? void 0,
+      data: JSON.parse(row.data),
+      createdAt: row.createdAt
     };
   }
-  /**
-   * Get the current chat ID.
-   */
-  get chatId() {
-    return this.#chatId;
+  async getMessageChain(headId) {
+    const rows = this.#db.prepare(
+      `WITH RECURSIVE chain AS (
+          SELECT *, 0 as depth FROM messages WHERE id = ?
+          UNION ALL
+          SELECT m.*, c.depth + 1 FROM messages m
+          INNER JOIN chain c ON m.id = c.parentId
+        )
+        SELECT * FROM chain
+        ORDER BY depth DESC`
+    ).all(headId);
+    return rows.map((row) => ({
+      id: row.id,
+      chatId: row.chatId,
+      parentId: row.parentId,
+      name: row.name,
+      type: row.type ?? void 0,
+      data: JSON.parse(row.data),
+      createdAt: row.createdAt
+    }));
   }
-  /**
-   * Get the current branch name.
-   */
-  get branch() {
-    return this.#branchName;
+  async hasChildren(messageId) {
+    const row = this.#db.prepare(
+      "SELECT EXISTS(SELECT 1 FROM messages WHERE parentId = ?) as hasChildren"
+    ).get(messageId);
+    return row.hasChildren === 1;
+  }
+  // ==========================================================================
+  // Branch Operations
+  // ==========================================================================
+  async createBranch(branch) {
+    this.#db.prepare(
+      `INSERT INTO branches (id, chatId, name, headMessageId, isActive, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?)`
+    ).run(
+      branch.id,
+      branch.chatId,
+      branch.name,
+      branch.headMessageId,
+      branch.isActive ? 1 : 0,
+      branch.createdAt
+    );
   }
-  /**
-   * Get metadata for the current chat.
-   * Returns null if the chat hasn't been initialized yet.
-   */
-  get chat() {
-    if (!this.#chatData) {
-      return null;
+  async getBranch(chatId, name) {
+    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND name = ?").get(chatId, name);
+    if (!row) {
+      return void 0;
     }
     return {
-      id: this.#chatData.id,
-      createdAt: this.#chatData.createdAt,
-      updatedAt: this.#chatData.updatedAt,
-      title: this.#chatData.title,
-      metadata: this.#chatData.metadata
+      id: row.id,
+      chatId: row.chatId,
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: row.isActive === 1,
+      createdAt: row.createdAt
     };
   }
-  /**
-   * Add fragments to the context.
-   *
-   * - Message fragments (user/assistant) are queued for persistence
-   * - Non-message fragments (role/hint) are kept in memory for system prompt
-   */
-  set(...fragments) {
-    for (const fragment2 of fragments) {
-      if (isMessageFragment(fragment2)) {
-        this.#pendingMessages.push(fragment2);
-      } else {
-        this.#fragments.push(fragment2);
-      }
+  async getActiveBranch(chatId) {
+    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND isActive = 1").get(chatId);
+    if (!row) {
+      return void 0;
     }
-    return this;
+    return {
+      id: row.id,
+      chatId: row.chatId,
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: true,
+      createdAt: row.createdAt
+    };
   }
-  /**
-   * Render all fragments using the provided renderer.
-   * @internal Use resolve() instead for public API.
-   */
-  render(renderer) {
-    return renderer.render(this.#fragments);
+  async setActiveBranch(chatId, branchId) {
+    this.#db.prepare("UPDATE branches SET isActive = 0 WHERE chatId = ?").run(chatId);
+    this.#db.prepare("UPDATE branches SET isActive = 1 WHERE id = ?").run(branchId);
   }
-  /**
-   * Resolve context into AI SDK-ready format.
-   *
-   * - Initializes chat and branch if needed
-   * - Loads message history from the graph (walking parent chain)
-   * - Separates context fragments for system prompt
-   * - Combines with pending messages
-   *
-   * @example
-   * ```ts
-   * const context = new ContextEngine({ store, chatId: 'chat-1' })
-   *   .set(role('You are helpful'), user('Hello'));
-   *
-   * const { systemPrompt, messages } = await context.resolve();
-   * await generateText({ system: systemPrompt, messages });
-   * ```
-   */
-  async resolve(options) {
-    await this.#ensureInitialized();
-    const systemPrompt = options.renderer.render(this.#fragments);
-    const messages = [];
-    if (this.#branch?.headMessageId) {
-      const chain = await this.#store.getMessageChain(
-        this.#branch.headMessageId
-      );
-      for (const msg of chain) {
-        messages.push(message(msg.data).codec?.decode());
+  async updateBranchHead(branchId, messageId) {
+    this.#db.prepare("UPDATE branches SET headMessageId = ? WHERE id = ?").run(messageId, branchId);
+  }
+  async listBranches(chatId) {
+    const branches = this.#db.prepare(
+      `SELECT
+          b.id,
+          b.name,
+          b.headMessageId,
+          b.isActive,
+          b.createdAt
+        FROM branches b
+        WHERE b.chatId = ?
+        ORDER BY b.createdAt ASC`
+    ).all(chatId);
+    const result = [];
+    for (const branch of branches) {
+      let messageCount = 0;
+      if (branch.headMessageId) {
+        const countRow = this.#db.prepare(
+          `WITH RECURSIVE chain AS (
+              SELECT id, parentId FROM messages WHERE id = ?
+              UNION ALL
+              SELECT m.id, m.parentId FROM messages m
+              INNER JOIN chain c ON m.id = c.parentId
+            )
+            SELECT COUNT(*) as count FROM chain`
+        ).get(branch.headMessageId);
+        messageCount = countRow.count;
       }
+      result.push({
+        id: branch.id,
+        name: branch.name,
+        headMessageId: branch.headMessageId,
+        isActive: branch.isActive === 1,
+        messageCount,
+        createdAt: branch.createdAt
+      });
     }
-    for (const fragment2 of this.#pendingMessages) {
-      const decoded = fragment2.codec.decode();
-      messages.push(decoded);
-    }
-    return { systemPrompt, messages };
+    return result;
   }
-  /**
-   * Save pending messages to the graph.
-   *
-   * Each message is added as a node with parentId pointing to the previous message.
-   * The branch head is updated to point to the last message.
-   *
-   * @example
-   * ```ts
-   * context.set(user('Hello'));
-   * // AI responds...
-   * context.set(assistant('Hi there!'));
-   * await context.save(); // Persist to graph
-   * ```
-   */
-  async save() {
-    await this.#ensureInitialized();
-    if (this.#pendingMessages.length === 0) {
-      return;
-    }
-    let parentId = this.#branch.headMessageId;
-    const now = Date.now();
-    for (const fragment2 of this.#pendingMessages) {
-      const messageData = {
-        id: fragment2.id ?? crypto.randomUUID(),
-        chatId: this.#chatId,
-        parentId,
-        name: fragment2.name,
-        type: fragment2.type,
-        data: fragment2.codec.encode(),
-        createdAt: now
-      };
-      await this.#store.addMessage(messageData);
-      parentId = messageData.id;
-    }
-    await this.#store.updateBranchHead(this.#branch.id, parentId);
-    this.#branch.headMessageId = parentId;
-    this.#pendingMessages = [];
+  // ==========================================================================
+  // Checkpoint Operations
+  // ==========================================================================
+  async createCheckpoint(checkpoint) {
+    this.#db.prepare(
+      `INSERT INTO checkpoints (id, chatId, name, messageId, createdAt)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(chatId, name) DO UPDATE SET
+           messageId = excluded.messageId,
+           createdAt = excluded.createdAt`
+    ).run(
+      checkpoint.id,
+      checkpoint.chatId,
+      checkpoint.name,
+      checkpoint.messageId,
+      checkpoint.createdAt
+    );
   }
-  /**
-   * Estimate token count and cost for the full context.
-   *
-   * Includes:
-   * - System prompt fragments (role, hints, etc.)
-   * - Persisted chat messages (from store)
-   * - Pending messages (not yet saved)
-   *
-   * @param modelId - Model ID (e.g., "openai:gpt-4o", "anthropic:claude-3-5-sonnet")
-   * @param options - Optional settings
-   * @returns Estimate result with token counts, costs, and per-fragment breakdown
-   */
-  async estimate(modelId, options = {}) {
-    await this.#ensureInitialized();
-    const renderer = options.renderer ?? new XmlRenderer();
-    const registry = getModelsRegistry();
-    await registry.load();
-    const model = registry.get(modelId);
-    if (!model) {
-      throw new Error(
-        `Model "${modelId}" not found. Call load() first or check model ID.`
-      );
-    }
-    const tokenizer = registry.getTokenizer(modelId);
-    const fragmentEstimates = [];
-    for (const fragment2 of this.#fragments) {
-      const rendered = renderer.render([fragment2]);
-      const tokens = tokenizer.count(rendered);
-      const cost = tokens / 1e6 * model.cost.input;
-      fragmentEstimates.push({
-        id: fragment2.id,
-        name: fragment2.name,
-        tokens,
-        cost
-      });
-    }
-    if (this.#branch?.headMessageId) {
-      const chain = await this.#store.getMessageChain(
-        this.#branch.headMessageId
-      );
-      for (const msg of chain) {
-        const content = String(msg.data);
-        const tokens = tokenizer.count(content);
-        const cost = tokens / 1e6 * model.cost.input;
-        fragmentEstimates.push({
-          name: msg.name,
-          id: msg.id,
-          tokens,
-          cost
-        });
-      }
-    }
-    for (const fragment2 of this.#pendingMessages) {
-      const content = String(fragment2.data);
-      const tokens = tokenizer.count(content);
-      const cost = tokens / 1e6 * model.cost.input;
-      fragmentEstimates.push({
-        name: fragment2.name,
-        id: fragment2.id,
-        tokens,
-        cost
-      });
+  async getCheckpoint(chatId, name) {
+    const row = this.#db.prepare("SELECT * FROM checkpoints WHERE chatId = ? AND name = ?").get(chatId, name);
+    if (!row) {
+      return void 0;
     }
-    const totalTokens = fragmentEstimates.reduce((sum, f) => sum + f.tokens, 0);
-    const totalCost = fragmentEstimates.reduce((sum, f) => sum + f.cost, 0);
     return {
-      model: model.id,
-      provider: model.provider,
-      tokens: totalTokens,
-      cost: totalCost,
-      limits: {
-        context: model.limit.context,
-        output: model.limit.output,
-        exceedsContext: totalTokens > model.limit.context
-      },
-      fragments: fragmentEstimates
+      id: row.id,
+      chatId: row.chatId,
+      name: row.name,
+      messageId: row.messageId,
+      createdAt: row.createdAt
     };
   }
-  /**
-   * Rewind to a specific message by ID.
-   *
-   * Creates a new branch from that message, preserving the original branch.
-   * The new branch becomes active.
-   *
-   * @param messageId - The message ID to rewind to
-   * @returns The new branch info
-   *
-   * @example
-   * ```ts
-   * context.set(user('What is 2 + 2?', { id: 'q1' }));
-   * context.set(assistant('The answer is 5.', { id: 'wrong' })); // Oops!
-   * await context.save();
-   *
-   * // Rewind to the question, creates new branch
-   * const newBranch = await context.rewind('q1');
-   *
-   * // Now add correct answer on new branch
-   * context.set(assistant('The answer is 4.'));
-   * await context.save();
-   * ```
-   */
-  async rewind(messageId) {
-    await this.#ensureInitialized();
-    const message2 = await this.#store.getMessage(messageId);
-    if (!message2) {
-      throw new Error(`Message "${messageId}" not found`);
-    }
-    if (message2.chatId !== this.#chatId) {
-      throw new Error(`Message "${messageId}" belongs to a different chat`);
-    }
-    return this.#createBranchFrom(messageId, true);
+  async listCheckpoints(chatId) {
+    const rows = this.#db.prepare(
+      `SELECT id, name, messageId, createdAt
+         FROM checkpoints
+         WHERE chatId = ?
+         ORDER BY createdAt DESC`
+    ).all(chatId);
+    return rows.map((row) => ({
+      id: row.id,
+      name: row.name,
+      messageId: row.messageId,
+      createdAt: row.createdAt
+    }));
   }
-  /**
-   * Create a checkpoint at the current position.
-   *
-   * A checkpoint is a named pointer to the current branch head.
-   * Use restore() to return to this point later.
-   *
-   * @param name - Name for the checkpoint
-   * @returns The checkpoint info
-   *
-   * @example
-   * ```ts
-   * context.set(user('I want to learn a new skill.'));
-   * context.set(assistant('Would you like coding or cooking?'));
-   * await context.save();
-   *
-   * // Save checkpoint before user's choice
-   * const cp = await context.checkpoint('before-choice');
-   * ```
-   */
-  async checkpoint(name) {
-    await this.#ensureInitialized();
-    if (!this.#branch?.headMessageId) {
-      throw new Error("Cannot create checkpoint: no messages in conversation");
+  async deleteCheckpoint(chatId, name) {
+    this.#db.prepare("DELETE FROM checkpoints WHERE chatId = ? AND name = ?").run(chatId, name);
+  }
+  // ==========================================================================
+  // Search Operations
+  // ==========================================================================
+  async searchMessages(chatId, query, options) {
+    const limit = options?.limit ?? 20;
+    const roles = options?.roles;
+    let sql = `
+      SELECT
+        m.id,
+        m.chatId,
+        m.parentId,
+        m.name,
+        m.type,
+        m.data,
+        m.createdAt,
+        fts.rank,
+        snippet(messages_fts, 3, '<mark>', '</mark>', '...', 32) as snippet
+      FROM messages_fts fts
+      JOIN messages m ON m.id = fts.messageId
+      WHERE messages_fts MATCH ?
+        AND fts.chatId = ?
+    `;
+    const params = [query, chatId];
+    if (roles && roles.length > 0) {
+      const placeholders = roles.map(() => "?").join(", ");
+      sql += ` AND fts.name IN (${placeholders})`;
+      params.push(...roles);
     }
-    const checkpoint = {
-      id: crypto.randomUUID(),
-      chatId: this.#chatId,
-      name,
-      messageId: this.#branch.headMessageId,
-      createdAt: Date.now()
-    };
-    await this.#store.createCheckpoint(checkpoint);
+    sql += " ORDER BY fts.rank LIMIT ?";
+    params.push(limit);
+    const rows = this.#db.prepare(sql).all(...params);
+    return rows.map((row) => ({
+      message: {
+        id: row.id,
+        chatId: row.chatId,
+        parentId: row.parentId,
+        name: row.name,
+        type: row.type ?? void 0,
+        data: JSON.parse(row.data),
+        createdAt: row.createdAt
+      },
+      rank: row.rank,
+      snippet: row.snippet
+    }));
+  }
+  // ==========================================================================
+  // Visualization Operations
+  // ==========================================================================
+  async getGraph(chatId) {
+    const messageRows = this.#db.prepare(
+      `SELECT id, parentId, name, data, createdAt
+         FROM messages
+         WHERE chatId = ?
+         ORDER BY createdAt ASC`
+    ).all(chatId);
+    const nodes = messageRows.map((row) => {
+      const data = JSON.parse(row.data);
+      const content = typeof data === "string" ? data : JSON.stringify(data);
+      return {
+        id: row.id,
+        parentId: row.parentId,
+        role: row.name,
+        content: content.length > 50 ? content.slice(0, 50) + "..." : content,
+        createdAt: row.createdAt
+      };
+    });
+    const branchRows = this.#db.prepare(
+      `SELECT name, headMessageId, isActive
+         FROM branches
+         WHERE chatId = ?
+         ORDER BY createdAt ASC`
+    ).all(chatId);
+    const branches = branchRows.map((row) => ({
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: row.isActive === 1
+    }));
+    const checkpointRows = this.#db.prepare(
+      `SELECT name, messageId
+         FROM checkpoints
+         WHERE chatId = ?
+         ORDER BY createdAt ASC`
+    ).all(chatId);
+    const checkpoints = checkpointRows.map((row) => ({
+      name: row.name,
+      messageId: row.messageId
+    }));
     return {
-      id: checkpoint.id,
-      name: checkpoint.name,
-      messageId: checkpoint.messageId,
-      createdAt: checkpoint.createdAt
+      chatId,
+      nodes,
+      branches,
+      checkpoints
     };
   }
-  /**
-   * Restore to a checkpoint by creating a new branch from that point.
-   *
-   * @param name - Name of the checkpoint to restore
-   * @returns The new branch info
-   *
-   * @example
-   * ```ts
-   * // User chose cooking, but wants to try coding path
-   * await context.restore('before-choice');
-   *
-   * context.set(user('I want to learn coding.'));
-   * context.set(assistant('Python is a great starting language!'));
-   * await context.save();
-   * ```
-   */
-  async restore(name) {
-    await this.#ensureInitialized();
-    const checkpoint = await this.#store.getCheckpoint(this.#chatId, name);
-    if (!checkpoint) {
-      throw new Error(
-        `Checkpoint "${name}" not found in chat "${this.#chatId}"`
-      );
+};
+
+// packages/context/src/lib/store/memory.store.ts
+var InMemoryContextStore = class extends SqliteContextStore {
+  constructor() {
+    super(":memory:");
+  }
+};
+
+// packages/context/src/lib/visualize.ts
+function visualizeGraph(data) {
+  if (data.nodes.length === 0) {
+    return `[chat: ${data.chatId}]
+
+(empty)`;
+  }
+  const childrenByParentId = /* @__PURE__ */ new Map();
+  const branchHeads = /* @__PURE__ */ new Map();
+  const checkpointsByMessageId = /* @__PURE__ */ new Map();
+  for (const node of data.nodes) {
+    const children = childrenByParentId.get(node.parentId) ?? [];
+    children.push(node);
+    childrenByParentId.set(node.parentId, children);
+  }
+  for (const branch of data.branches) {
+    if (branch.headMessageId) {
+      const heads = branchHeads.get(branch.headMessageId) ?? [];
+      heads.push(branch.isActive ? `${branch.name} *` : branch.name);
+      branchHeads.set(branch.headMessageId, heads);
+    }
+  }
+  for (const checkpoint of data.checkpoints) {
+    const cps = checkpointsByMessageId.get(checkpoint.messageId) ?? [];
+    cps.push(checkpoint.name);
+    checkpointsByMessageId.set(checkpoint.messageId, cps);
+  }
+  const roots = childrenByParentId.get(null) ?? [];
+  const lines = [`[chat: ${data.chatId}]`, ""];
+  function renderNode(node, prefix, isLast, isRoot) {
+    const connector = isRoot ? "" : isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const contentPreview = node.content.replace(/\n/g, " ");
+    let line = `${prefix}${connector}${node.id.slice(0, 8)} (${node.role}): "${contentPreview}"`;
+    const branches = branchHeads.get(node.id);
+    if (branches) {
+      line += ` <- [${branches.join(", ")}]`;
+    }
+    const checkpoints = checkpointsByMessageId.get(node.id);
+    if (checkpoints) {
+      line += ` {${checkpoints.join(", ")}}`;
+    }
+    lines.push(line);
+    const children = childrenByParentId.get(node.id) ?? [];
+    const childPrefix = isRoot ? "" : prefix + (isLast ? "    " : "\u2502   ");
+    for (let i = 0; i < children.length; i++) {
+      renderNode(children[i], childPrefix, i === children.length - 1, false);
     }
-    return this.rewind(checkpoint.messageId);
   }
-  /**
-   * Switch to a different branch by name.
-   *
-   * @param name - Branch name to switch to
-   *
-   * @example
-   * ```ts
-   * // List branches (via store)
-   * const branches = await store.listBranches(context.chatId);
-   * console.log(branches); // [{name: 'main', ...}, {name: 'main-v2', ...}]
-   *
-   * // Switch to original branch
-   * await context.switchBranch('main');
-   * ```
-   */
-  async switchBranch(name) {
-    await this.#ensureInitialized();
-    const branch = await this.#store.getBranch(this.#chatId, name);
-    if (!branch) {
-      throw new Error(`Branch "${name}" not found in chat "${this.#chatId}"`);
+  for (let i = 0; i < roots.length; i++) {
+    renderNode(roots[i], "", i === roots.length - 1, true);
+  }
+  lines.push("");
+  lines.push("Legend: * = active branch, {...} = checkpoint");
+  return lines.join("\n");
+}
+
+// packages/context/src/lib/agent.ts
+import {
+  Output,
+  convertToModelMessages,
+  createUIMessageStream,
+  generateId as generateId2,
+  generateText,
+  smoothStream,
+  stepCountIs,
+  streamText
+} from "ai";
+import chalk from "chalk";
+import "zod";
+import "@deepagents/agent";
+var Agent = class _Agent {
+  #options;
+  #guardrails = [];
+  tools;
+  constructor(options) {
+    this.#options = options;
+    this.tools = options.tools || {};
+    this.#guardrails = options.guardrails || [];
+  }
+  async generate(contextVariables, config) {
+    if (!this.#options.context) {
+      throw new Error(`Agent ${this.#options.name} is missing a context.`);
     }
-    await this.#store.setActiveBranch(this.#chatId, branch.id);
-    this.#branch = { ...branch, isActive: true };
-    this.#branchName = name;
-    this.#pendingMessages = [];
+    if (!this.#options.model) {
+      throw new Error(`Agent ${this.#options.name} is missing a model.`);
+    }
+    const { messages, systemPrompt } = await this.#options.context.resolve({
+      renderer: new XmlRenderer()
+    });
+    return generateText({
+      abortSignal: config?.abortSignal,
+      providerOptions: this.#options.providerOptions,
+      model: this.#options.model,
+      system: systemPrompt,
+      messages: convertToModelMessages(messages),
+      stopWhen: stepCountIs(25),
+      tools: this.#options.tools,
+      experimental_context: contextVariables,
+      toolChoice: this.#options.toolChoice,
+      onStepFinish: (step) => {
+        const toolCall = step.toolCalls.at(-1);
+        if (toolCall) {
+          console.log(
+            `Debug: ${chalk.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
+          );
+        }
+      }
+    });
   }
   /**
-   * Create a parallel branch from the current position ("by the way").
-   *
-   * Use this when you want to fork the conversation without leaving
-   * the current branch. Common use case: user wants to ask another
-   * question while waiting for the model to respond.
-   *
-   * Unlike rewind(), this method:
-   * - Uses the current HEAD (no messageId needed)
-   * - Does NOT switch to the new branch
-   * - Keeps pending messages intact
+   * Stream a response from the agent.
    *
-   * @returns The new branch info (does not switch to it)
-   * @throws Error if no messages exist in the conversation
+   * When guardrails are configured, `toUIMessageStream()` is wrapped to provide
+   * self-correction behavior. Direct access to fullStream/textStream bypasses guardrails.
    *
    * @example
-   * ```ts
-   * // User asked a question, model is generating...
-   * context.set(user('What is the weather?'));
-   * await context.save();
+   * ```typescript
+   * const stream = await agent.stream({});
    *
-   * // User wants to ask something else without waiting
-   * const newBranch = await context.btw();
-   * // newBranch = { name: 'main-v2', ... }
+   * // With guardrails - use toUIMessageStream for protection
+   * await printer.readableStream(stream.toUIMessageStream());
    *
-   * // Later, switch to the new branch and add the question
-   * await context.switchBranch(newBranch.name);
-   * context.set(user('Also, what time is it?'));
-   * await context.save();
+   * // Or use printer.stdout which uses toUIMessageStream internally
+   * await printer.stdout(stream);
    * ```
    */
-  async btw() {
-    await this.#ensureInitialized();
-    if (!this.#branch?.headMessageId) {
-      throw new Error("Cannot create btw branch: no messages in conversation");
+  async stream(contextVariables, config) {
+    if (!this.#options.context) {
+      throw new Error(`Agent ${this.#options.name} is missing a context.`);
     }
-    return this.#createBranchFrom(this.#branch.headMessageId, false);
-  }
-  /**
-   * Update metadata for the current chat.
-   *
-   * @param updates - Partial metadata to merge (title, metadata)
-   *
-   * @example
-   * ```ts
-   * await context.updateChat({
-   *   title: 'Coding Help Session',
-   *   metadata: { tags: ['python', 'debugging'] }
-   * });
-   * ```
-   */
-  async updateChat(updates) {
-    await this.#ensureInitialized();
-    const storeUpdates = {};
-    if (updates.title !== void 0) {
-      storeUpdates.title = updates.title;
+    if (!this.#options.model) {
+      throw new Error(`Agent ${this.#options.name} is missing a model.`);
     }
-    if (updates.metadata !== void 0) {
-      storeUpdates.metadata = {
-        ...this.#chatData?.metadata,
-        ...updates.metadata
-      };
+    const result = await this.#createRawStream(contextVariables, config);
+    if (this.#guardrails.length === 0) {
+      return result;
     }
-    this.#chatData = await this.#store.updateChat(this.#chatId, storeUpdates);
+    return this.#wrapWithGuardrails(result, contextVariables, config);
   }
   /**
-   * Consolidate context fragments (no-op for now).
-   *
-   * This is a placeholder for future functionality that merges context fragments
-   * using specific rules. Currently, it does nothing.
-   *
-   * @experimental
+   * Create a raw stream without guardrail processing.
    */
-  consolidate() {
-    return void 0;
+  async #createRawStream(contextVariables, config) {
+    const { messages, systemPrompt } = await this.#options.context.resolve({
+      renderer: new XmlRenderer()
+    });
+    const runId = generateId2();
+    return streamText({
+      abortSignal: config?.abortSignal,
+      providerOptions: this.#options.providerOptions,
+      model: this.#options.model,
+      system: systemPrompt,
+      messages: convertToModelMessages(messages),
+      stopWhen: stepCountIs(25),
+      experimental_transform: config?.transform ?? smoothStream(),
+      tools: this.#options.tools,
+      experimental_context: contextVariables,
+      toolChoice: this.#options.toolChoice,
+      onStepFinish: (step) => {
+        const toolCall = step.toolCalls.at(-1);
+        if (toolCall) {
+          console.log(
+            `Debug: (${runId}) ${chalk.bold.yellow("ToolCalled")}: ${toolCall.toolName}(${JSON.stringify(toolCall.input)})`
+          );
+        }
+      }
+    });
   }
   /**
-   * Inspect the full context state for debugging.
-   * Returns a comprehensive JSON-serializable object with all context information.
-   *
-   * @param options - Inspection options (modelId and renderer required)
-   * @returns Complete inspection data including estimates, rendered output, fragments, and graph
-   *
-   * @example
-   * ```ts
-   * const inspection = await context.inspect({
-   *   modelId: 'openai:gpt-4o',
-   *   renderer: new XmlRenderer(),
-   * });
-   * console.log(JSON.stringify(inspection, null, 2));
+   * Wrap a StreamTextResult with guardrail protection on toUIMessageStream().
    *
-   * // Or write to file for analysis
-   * await fs.writeFile('context-debug.json', JSON.stringify(inspection, null, 2));
-   * ```
+   * When a guardrail fails:
+   * 1. Accumulated text + feedback is appended as the assistant's self-correction
+   * 2. The feedback is written to the output stream (user sees the correction)
+   * 3. A new stream is started and the model continues from the correction
    */
-  async inspect(options) {
-    await this.#ensureInitialized();
-    const { renderer } = options;
-    const estimateResult = await this.estimate(options.modelId, { renderer });
-    const rendered = renderer.render(this.#fragments);
-    const persistedMessages = [];
-    if (this.#branch?.headMessageId) {
-      const chain = await this.#store.getMessageChain(
-        this.#branch.headMessageId
-      );
-      persistedMessages.push(...chain);
-    }
-    const graph = await this.#store.getGraph(this.#chatId);
-    return {
-      estimate: estimateResult,
-      rendered,
-      fragments: {
-        context: [...this.#fragments],
-        pending: [...this.#pendingMessages],
-        persisted: persistedMessages
-      },
-      graph,
-      meta: {
-        chatId: this.#chatId,
-        branch: this.#branchName,
-        timestamp: Date.now()
-      }
+  #wrapWithGuardrails(result, contextVariables, config) {
+    const maxRetries = config?.maxRetries ?? this.#options.maxGuardrailRetries ?? 3;
+    const context = this.#options.context;
+    const originalToUIMessageStream = result.toUIMessageStream.bind(result);
+    result.toUIMessageStream = (options) => {
+      return createUIMessageStream({
+        generateId: generateId2,
+        execute: async ({ writer }) => {
+          let currentResult = result;
+          let attempt = 0;
+          const guardrailContext = {
+            availableTools: Object.keys(this.tools)
+          };
+          while (attempt < maxRetries) {
+            if (config?.abortSignal?.aborted) {
+              writer.write({ type: "finish" });
+              return;
+            }
+            attempt++;
+            let accumulatedText = "";
+            let guardrailFailed = false;
+            let failureFeedback = "";
+            const uiStream = currentResult === result ? originalToUIMessageStream(options) : currentResult.toUIMessageStream(options);
+            for await (const part of uiStream) {
+              const checkResult = runGuardrailChain(
+                part,
+                this.#guardrails,
+                guardrailContext
+              );
+              if (checkResult.type === "fail") {
+                guardrailFailed = true;
+                failureFeedback = checkResult.feedback;
+                console.log(
+                  chalk.yellow(
+                    `[${this.#options.name}] Guardrail triggered (attempt ${attempt}/${maxRetries}): ${failureFeedback.slice(0, 50)}...`
+                  )
+                );
+                break;
+              }
+              if (checkResult.part.type === "text-delta") {
+                accumulatedText += checkResult.part.delta;
+              }
+              writer.write(checkResult.part);
+            }
+            if (!guardrailFailed) {
+              writer.write({ type: "finish" });
+              return;
+            }
+            if (attempt >= maxRetries) {
+              console.error(
+                chalk.red(
+                  `[${this.#options.name}] Guardrail retry limit (${maxRetries}) exceeded.`
+                )
+              );
+              writer.write({ type: "finish" });
+              return;
+            }
+            writer.write({
+              type: "text-delta",
+              id: generateId2(),
+              delta: ` ${failureFeedback}`
+            });
+            const selfCorrectionText = accumulatedText + " " + failureFeedback;
+            context.set(assistantText(selfCorrectionText));
+            await context.save();
+            currentResult = await this.#createRawStream(
+              contextVariables,
+              config
+            );
+          }
+        },
+        onError: (error) => {
+          const message2 = error instanceof Error ? error.message : String(error);
+          return `Stream failed: ${message2}`;
+        }
+      });
     };
+    return result;
+  }
+  clone(overrides) {
+    return new _Agent({
+      ...this.#options,
+      ...overrides
+    });
   }
 };
-function hint(text) {
-  return {
-    name: "hint",
-    data: text
-  };
-}
-function fragment(name, ...children) {
-  return {
-    name,
-    data: children
-  };
-}
-function role(content) {
-  return {
-    name: "role",
-    data: content
-  };
+function agent(options) {
+  return new Agent(options);
 }
-function user(content) {
-  const message2 = typeof content === "string" ? {
-    id: generateId(),
-    role: "user",
-    parts: [{ type: "text", text: content }]
-  } : content;
+function structuredOutput(options) {
   return {
-    id: message2.id,
-    name: "user",
-    data: "content",
-    type: "message",
-    persist: true,
-    codec: {
-      decode() {
-        return message2;
-      },
-      encode() {
-        return message2;
+    async generate(contextVariables, config) {
+      if (!options.context) {
+        throw new Error(
+          `structuredOutput "${options.name}" is missing a context.`
+        );
       }
-    }
-  };
-}
-function assistant(message2) {
-  return {
-    id: message2.id,
-    name: "assistant",
-    data: "content",
-    type: "message",
-    persist: true,
-    codec: {
-      decode() {
-        return message2;
-      },
-      encode() {
-        return message2;
+      if (!options.model) {
+        throw new Error(
+          `structuredOutput "${options.name}" is missing a model.`
+        );
       }
-    }
-  };
-}
-function message(content) {
-  const message2 = typeof content === "string" ? {
-    id: generateId(),
-    role: "user",
-    parts: [{ type: "text", text: content }]
-  } : content;
-  return {
-    id: message2.id,
-    name: "message",
-    data: "content",
-    type: "message",
-    persist: true,
-    codec: {
-      decode() {
-        return message2;
-      },
-      encode() {
-        return message2;
+      const { messages, systemPrompt } = await options.context.resolve({
+        renderer: new XmlRenderer()
+      });
+      const result = await generateText({
+        abortSignal: config?.abortSignal,
+        providerOptions: options.providerOptions,
+        model: options.model,
+        system: systemPrompt,
+        messages: convertToModelMessages(messages),
+        stopWhen: stepCountIs(25),
+        experimental_context: contextVariables,
+        experimental_output: Output.object({ schema: options.schema })
+      });
+      return result.experimental_output;
+    },
+    async stream(contextVariables, config) {
+      if (!options.context) {
+        throw new Error(
+          `structuredOutput "${options.name}" is missing a context.`
+        );
       }
+      if (!options.model) {
+        throw new Error(
+          `structuredOutput "${options.name}" is missing a model.`
+        );
+      }
+      const { messages, systemPrompt } = await options.context.resolve({
+        renderer: new XmlRenderer()
+      });
+      return streamText({
+        abortSignal: config?.abortSignal,
+        providerOptions: options.providerOptions,
+        model: options.model,
+        system: systemPrompt,
+        messages: convertToModelMessages(messages),
+        stopWhen: stepCountIs(25),
+        experimental_transform: config?.transform ?? smoothStream(),
+        experimental_context: contextVariables,
+        experimental_output: Output.object({ schema: options.schema })
+      });
     }
   };
 }
-function assistantText(content, options) {
-  const id = options?.id ?? crypto.randomUUID();
-  return assistant({
-    id,
-    role: "assistant",
-    parts: [{ type: "text", text: content }]
-  });
-}
 export {
+  BinaryInstallError,
+  ComposeStartError,
+  ComposeStrategy,
+  ContainerCreationError,
   ContextEngine,
+  ContextRenderer,
   ContextStore,
+  DockerNotAvailableError,
+  DockerSandboxError,
+  DockerSandboxStrategy,
+  DockerfileBuildError,
+  DockerfileStrategy,
   InMemoryContextStore,
   MarkdownRenderer,
   ModelsRegistry,
+  MountPathError,
+  PackageInstallError,
+  RuntimeStrategy,
   SqliteContextStore,
   TomlRenderer,
   ToonRenderer,
   XmlRenderer,
+  agent,
+  alias,
+  analogy,
   assistant,
   assistantText,
+  clarification,
+  correction,
+  createBinaryBridges,
+  createContainerTool,
+  createDockerSandbox,
   defaultTokenizer,
+  discoverSkillsInDirectory,
   estimate,
+  example,
+  explain,
+  fail,
   fragment,
   getModelsRegistry,
+  glossary,
+  guardrail,
   hint,
+  identity,
+  isComposeOptions,
+  isDockerfileOptions,
+  isFragment,
+  isFragmentObject,
   isMessageFragment,
+  loadSkillMetadata,
   message,
+  parseFrontmatter,
+  pass,
+  persona,
+  preference,
+  quirk,
   role,
+  runGuardrailChain,
+  skills,
+  structuredOutput,
+  styleGuide,
+  term,
+  useSandbox,
   user,
-  visualizeGraph
+  userContext,
+  visualizeGraph,
+  workflow
 };
 //# sourceMappingURL=index.js.map