@deepagents/text2sql 0.13.0 → 0.14.0

package/dist/lib/adapters/groundings/index.js

@@ -221,7 +221,7 @@ var InfoGrounding = class extends AbstractGrounding {
 // packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
 import { groq as groq2 } from "@ai-sdk/groq";
 import { tool } from "ai";
-import dedent from "dedent";
+import dedent2 from "dedent";
 import z from "zod";
 import "@deepagents/agent";
 
@@ -239,6 +239,7 @@ import spawn2 from "nano-spawn";
 import {
   createBashTool
 } from "bash-tool";
+import dedent from "dedent";
 import YAML from "yaml";
 import { DatabaseSync } from "node:sqlite";
 import { groq } from "@ai-sdk/groq";
@@ -460,7 +461,7 @@ function assistantText(content, options) {
     parts: [{ type: "text", text: content }]
   });
 }
-var LAZY_ID = Symbol("lazy-id");
+var LAZY_ID = Symbol.for("@deepagents/context:lazy-id");
 function isLazyFragment(fragment2) {
   return LAZY_ID in fragment2;
 }
@@ -847,7 +848,7 @@ var ContextEngine = class {
   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`)
+      (it) => it.name === this.#branchName || it.name.startsWith(`${this.#branchName}-v`)
     );
     const newBranchName = `${this.#branchName}-v${samePrefix.length + 1}`;
     const newBranch = {
@@ -875,6 +876,15 @@ var ContextEngine = class {
       createdAt: newBranch.createdAt
     };
   }
+  /**
+   * Rewind to a message without clearing pending messages.
+   * Used internally when saving an update to an existing message.
+   */
+  async #rewindForUpdate(messageId) {
+    const pendingBackup = [...this.#pendingMessages];
+    await this.rewind(messageId);
+    this.#pendingMessages = pendingBackup;
+  }
   /**
    * Get the current chat ID.
    */
@@ -959,7 +969,18 @@ var ContextEngine = class {
         messages.push(message(msg.data).codec?.decode());
       }
     }
+    for (let i = 0; i < this.#pendingMessages.length; i++) {
+      const fragment2 = this.#pendingMessages[i];
+      if (isLazyFragment(fragment2)) {
+        this.#pendingMessages[i] = await this.#resolveLazyFragment(fragment2);
+      }
+    }
     for (const fragment2 of this.#pendingMessages) {
+      if (!fragment2.codec) {
+        throw new Error(
+          `Fragment "${fragment2.name}" is missing codec. Lazy fragments must be resolved before decode.`
+        );
+      }
       const decoded = fragment2.codec.decode();
       messages.push(decoded);
     }
@@ -990,9 +1011,24 @@ var ContextEngine = class {
         this.#pendingMessages[i] = await this.#resolveLazyFragment(fragment2);
       }
     }
+    for (const fragment2 of this.#pendingMessages) {
+      if (fragment2.id) {
+        const existing = await this.#store.getMessage(fragment2.id);
+        if (existing && existing.parentId) {
+          await this.#rewindForUpdate(existing.parentId);
+          fragment2.id = crypto.randomUUID();
+          break;
+        }
+      }
+    }
     let parentId = this.#branch.headMessageId;
     const now = Date.now();
     for (const fragment2 of this.#pendingMessages) {
+      if (!fragment2.codec) {
+        throw new Error(
+          `Fragment "${fragment2.name}" is missing codec. Lazy fragments must be resolved before encode.`
+        );
+      }
       const messageData = {
         id: fragment2.id ?? crypto.randomUUID(),
         chatId: this.#chatId,
@@ -1352,33 +1388,28 @@ var ContextEngine = class {
     return void 0;
   }
   /**
-   * Extract skill path mappings from available_skills fragments.
-   * Returns array of { host, sandbox } for mounting in sandbox filesystem.
-   *
-   * Reads the original `paths` configuration stored in fragment metadata
-   * by the skills() fragment helper.
+   * Extract skill mounts from available_skills fragments.
+   * Returns unified mount array where entries with `name` are individual skills.
    *
    * @example
    * ```ts
    * const context = new ContextEngine({ store, chatId, userId })
    *   .set(skills({ paths: [{ host: './skills', sandbox: '/skills' }] }));
    *
-   * const mounts = context.getSkillMounts();
-   * // [{ host: './skills', sandbox: '/skills' }]
+   * const { mounts } = context.getSkillMounts();
+   * // mounts: [{ name: 'bi-dashboards', host: './skills/bi-dashboards/SKILL.md', sandbox: '/skills/bi-dashboards/SKILL.md' }]
+   *
+   * // Extract skills only (entries with name)
+   * const skills = mounts.filter(m => m.name);
    * ```
    */
   getSkillMounts() {
-    const mounts = [];
     for (const fragment2 of this.#fragments) {
-      if (fragment2.name === "available_skills" && fragment2.metadata && Array.isArray(fragment2.metadata.paths)) {
-        for (const mapping of fragment2.metadata.paths) {
-          if (typeof mapping === "object" && mapping !== null && typeof mapping.host === "string" && typeof mapping.sandbox === "string") {
-            mounts.push({ host: mapping.host, sandbox: mapping.sandbox });
-          }
-        }
+      if (fragment2.name === "available_skills" && fragment2.metadata?.mounts) {
+        return { mounts: fragment2.metadata.mounts };
       }
     }
-    return mounts;
+    return { mounts: [] };
   }
   /**
    * Inspect the full context state for debugging.
@@ -1447,91 +1478,53 @@ function runGuardrailChain(part, guardrails, context) {
   let currentPart = part;
   for (const guardrail2 of guardrails) {
     const result = guardrail2.handle(currentPart, context);
-    if (result.type === "fail") {
+    if (result.type === "fail" || result.type === "stop") {
       return result;
     }
     currentPart = result.part;
   }
   return pass(currentPart);
 }
-var STORE_DDL = `
--- Chats table
--- createdAt/updatedAt: DEFAULT for insert, inline SET for updates
-CREATE TABLE IF NOT EXISTS chats (
-  id TEXT PRIMARY KEY,
-  userId TEXT NOT NULL,
-  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);
-CREATE INDEX IF NOT EXISTS idx_chats_userId ON chats(userId);
-
--- 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);
+var SKILLS_INSTRUCTIONS = dedent`A skill is a set of local instructions to follow that is stored in a \`SKILL.md\` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.
 
--- 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'
-);
-`;
+### How to use skills
+- Discovery: The list below shows the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
+- Trigger rules: If the user names a skill (with \`$SkillName\` or plain text) OR the task clearly matches a skill's description shown below, you must use that skill for that turn before doing anything else. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
+- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
+- How to use a skill (progressive disclosure):
+  1) After deciding to use a skill, open its \`SKILL.md\`. Read only enough to follow the workflow.
+  2) If \`SKILL.md\` points to extra folders such as \`references/\`, load only the specific files needed for the request; don't bulk-load everything.
+  3) If \`scripts/\` exist, prefer running or patching them instead of retyping large code blocks.
+  4) If \`assets/\` or templates exist, reuse them instead of recreating from scratch.
+- Coordination and sequencing:
+  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
+  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
+- Context hygiene:
+  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
+  - Avoid deep reference-chasing: prefer opening only files directly linked from \`SKILL.md\` unless you're blocked.
+  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
+- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.`;
+var ddl_sqlite_default = "-- Context Store DDL for SQLite\n-- This schema implements a DAG-based message history with branching and checkpoints.\n\n-- Performance PRAGMAs (session-level, run on each connection)\nPRAGMA journal_mode = WAL;\nPRAGMA synchronous = NORMAL;\nPRAGMA cache_size = -64000;\nPRAGMA temp_store = MEMORY;\nPRAGMA mmap_size = 268435456;\n\n-- Integrity\nPRAGMA foreign_keys = ON;\n\n-- Chats table\n-- createdAt/updatedAt: DEFAULT for insert, inline SET for updates\nCREATE TABLE IF NOT EXISTS chats (\n  id TEXT PRIMARY KEY,\n  userId TEXT NOT NULL,\n  title TEXT,\n  metadata TEXT,\n  createdAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),\n  updatedAt INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000)\n);\n\nCREATE INDEX IF NOT EXISTS idx_chats_updatedAt ON chats(updatedAt);\nCREATE INDEX IF NOT EXISTS idx_chats_userId ON chats(userId);\n-- Composite index for listChats(): WHERE userId = ? ORDER BY updatedAt DESC\nCREATE INDEX IF NOT EXISTS idx_chats_userId_updatedAt ON chats(userId, updatedAt DESC);\n\n-- Messages table (nodes in the DAG)\nCREATE TABLE IF NOT EXISTS messages (\n  id TEXT PRIMARY KEY,\n  chatId TEXT NOT NULL,\n  parentId TEXT,\n  name TEXT NOT NULL,\n  type TEXT,\n  data TEXT NOT NULL,\n  createdAt INTEGER NOT NULL,\n  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,\n  FOREIGN KEY (parentId) REFERENCES messages(id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_messages_chatId ON messages(chatId);\nCREATE INDEX IF NOT EXISTS idx_messages_parentId ON messages(parentId);\n-- Composite index for recursive CTE parent traversal in getMessageChain()\nCREATE INDEX IF NOT EXISTS idx_messages_chatId_parentId ON messages(chatId, parentId);\n\n-- Branches table (pointers to head messages)\nCREATE TABLE IF NOT EXISTS branches (\n  id TEXT PRIMARY KEY,\n  chatId TEXT NOT NULL,\n  name TEXT NOT NULL,\n  headMessageId TEXT,\n  isActive INTEGER NOT NULL DEFAULT 0,\n  createdAt INTEGER NOT NULL,\n  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,\n  FOREIGN KEY (headMessageId) REFERENCES messages(id),\n  UNIQUE(chatId, name)\n);\n\nCREATE INDEX IF NOT EXISTS idx_branches_chatId ON branches(chatId);\n-- Composite index for getActiveBranch(): WHERE chatId = ? AND isActive = 1\nCREATE INDEX IF NOT EXISTS idx_branches_chatId_isActive ON branches(chatId, isActive);\n\n-- Checkpoints table (pointers to message nodes)\nCREATE TABLE IF NOT EXISTS checkpoints (\n  id TEXT PRIMARY KEY,\n  chatId TEXT NOT NULL,\n  name TEXT NOT NULL,\n  messageId TEXT NOT NULL,\n  createdAt INTEGER NOT NULL,\n  FOREIGN KEY (chatId) REFERENCES chats(id) ON DELETE CASCADE,\n  FOREIGN KEY (messageId) REFERENCES messages(id),\n  UNIQUE(chatId, name)\n);\n\nCREATE INDEX IF NOT EXISTS idx_checkpoints_chatId ON checkpoints(chatId);\n\n-- FTS5 virtual table for full-text search\n-- messageId/chatId/name are UNINDEXED (stored but not searchable, used for filtering/joining)\n-- Only 'content' is indexed for full-text search\nCREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(\n  messageId UNINDEXED,\n  chatId UNINDEXED,\n  name UNINDEXED,\n  content,\n  tokenize='porter unicode61'\n);\n";
 var SqliteContextStore = class extends ContextStore {
   #db;
+  #statements = /* @__PURE__ */ new Map();
+  /**
+   * Get or create a prepared statement.
+   * Statements are cached for the lifetime of the store to avoid
+   * repeated SQL parsing and compilation overhead.
+   */
+  #stmt(sql) {
+    let stmt = this.#statements.get(sql);
+    if (!stmt) {
+      stmt = this.#db.prepare(sql);
+      this.#statements.set(sql, stmt);
+    }
+    return stmt;
+  }
   constructor(path3) {
     super();
     this.#db = new DatabaseSync(path3);
-    this.#db.exec("PRAGMA foreign_keys = ON");
-    this.#db.exec(STORE_DDL);
+    this.#db.exec(ddl_sqlite_default);
   }
   /**
    * Execute a function within a transaction.
@@ -1552,11 +1545,12 @@ var SqliteContextStore = class extends ContextStore {
   // Chat Operations
   // ==========================================================================
   async createChat(chat) {
-    this.#useTransaction(() => {
-      this.#db.prepare(
+    return this.#useTransaction(() => {
+      const row = this.#db.prepare(
         `INSERT INTO chats (id, userId, title, metadata)
-           VALUES (?, ?, ?, ?)`
-      ).run(
+           VALUES (?, ?, ?, ?)
+           RETURNING *`
+      ).get(
         chat.id,
         chat.userId,
         chat.title ?? null,
@@ -1566,6 +1560,14 @@ var SqliteContextStore = class extends ContextStore {
         `INSERT INTO branches (id, chatId, name, headMessageId, isActive, createdAt)
            VALUES (?, ?, 'main', NULL, 1, ?)`
       ).run(crypto.randomUUID(), chat.id, Date.now());
+      return {
+        id: row.id,
+        userId: row.userId,
+        title: row.title ?? void 0,
+        metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt
+      };
     });
   }
   async upsertChat(chat) {
@@ -1708,21 +1710,16 @@ var SqliteContextStore = class extends ContextStore {
   // Message Operations (Graph Nodes)
   // ==========================================================================
   async addMessage(message2) {
-    this.#db.prepare(
+    if (message2.parentId === message2.id) {
+      throw new Error(`Message ${message2.id} cannot be its own parent`);
+    }
+    this.#stmt(
       `INSERT INTO messages (id, chatId, parentId, name, type, data, createdAt)
-         VALUES (
-           ?1,
-           ?2,
-           CASE WHEN ?3 = ?1 THEN (SELECT parentId FROM messages WHERE id = ?1) ELSE ?3 END,
-           ?4,
-           ?5,
-           ?6,
-           ?7
-         )
-         ON CONFLICT(id) DO UPDATE SET
-           name = excluded.name,
-           type = excluded.type,
-           data = excluded.data`
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         name = excluded.name,
+         type = excluded.type,
+         data = excluded.data`
     ).run(
       message2.id,
       message2.chatId,
@@ -1733,14 +1730,16 @@ var SqliteContextStore = class extends ContextStore {
       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(
+    this.#stmt(`DELETE FROM messages_fts WHERE messageId = ?`).run(message2.id);
+    this.#stmt(
       `INSERT INTO messages_fts(messageId, chatId, name, content)
-         VALUES (?, ?, ?, ?)`
+       VALUES (?, ?, ?, ?)`
     ).run(message2.id, message2.chatId, message2.name, content);
   }
   async getMessage(messageId) {
-    const row = this.#db.prepare("SELECT * FROM messages WHERE id = ?").get(messageId);
+    const row = this.#stmt("SELECT * FROM messages WHERE id = ?").get(
+      messageId
+    );
     if (!row) {
       return void 0;
     }
@@ -1755,15 +1754,16 @@ var SqliteContextStore = class extends ContextStore {
     };
   }
   async getMessageChain(headId) {
-    const rows = this.#db.prepare(
+    const rows = this.#stmt(
       `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`
+        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
+        WHERE c.depth < 100000
+      )
+      SELECT * FROM chain
+      ORDER BY depth DESC`
     ).all(headId);
     return rows.map((row) => ({
       id: row.id,
@@ -1776,7 +1776,7 @@ var SqliteContextStore = class extends ContextStore {
     }));
   }
   async hasChildren(messageId) {
-    const row = this.#db.prepare(
+    const row = this.#stmt(
       "SELECT EXISTS(SELECT 1 FROM messages WHERE parentId = ?) as hasChildren"
     ).get(messageId);
     return row.hasChildren === 1;
@@ -1823,7 +1823,9 @@ var SqliteContextStore = class extends ContextStore {
     };
   }
   async getActiveBranch(chatId) {
-    const row = this.#db.prepare("SELECT * FROM branches WHERE chatId = ? AND isActive = 1").get(chatId);
+    const row = this.#stmt(
+      "SELECT * FROM branches WHERE chatId = ? AND isActive = 1"
+    ).get(chatId);
     if (!row) {
       return void 0;
     }
@@ -1841,45 +1843,43 @@ var SqliteContextStore = class extends ContextStore {
     this.#db.prepare("UPDATE branches SET isActive = 1 WHERE id = ?").run(branchId);
   }
   async updateBranchHead(branchId, messageId) {
-    this.#db.prepare("UPDATE branches SET headMessageId = ? WHERE id = ?").run(messageId, branchId);
+    this.#stmt("UPDATE branches SET headMessageId = ? WHERE id = ?").run(
+      messageId,
+      branchId
+    );
   }
   async listBranches(chatId) {
-    const branches = this.#db.prepare(
+    const rows = this.#db.prepare(
       `SELECT
           b.id,
           b.name,
           b.headMessageId,
           b.isActive,
-          b.createdAt
+          b.createdAt,
+          COALESCE(
+            (
+              WITH RECURSIVE chain AS (
+                SELECT id, parentId FROM messages WHERE id = b.headMessageId
+                UNION ALL
+                SELECT m.id, m.parentId FROM messages m
+                INNER JOIN chain c ON m.id = c.parentId
+              )
+              SELECT COUNT(*) FROM chain
+            ),
+            0
+          ) as messageCount
         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
-      });
-    }
-    return result;
+    return rows.map((row) => ({
+      id: row.id,
+      name: row.name,
+      headMessageId: row.headMessageId,
+      isActive: row.isActive === 1,
+      messageCount: row.messageCount,
+      createdAt: row.createdAt
+    }));
   }
   // ==========================================================================
   // Checkpoint Operations
@@ -2147,8 +2147,10 @@ var Agent = class _Agent {
         execute: async ({ writer }) => {
           let currentResult = result;
           let attempt = 0;
+          const { mounts } = context.getSkillMounts();
           const guardrailContext = {
-            availableTools: Object.keys(this.tools)
+            availableTools: Object.keys(this.tools),
+            availableSkills: mounts
           };
           while (attempt < maxRetries) {
             if (config?.abortSignal?.aborted) {
@@ -2176,10 +2178,20 @@ var Agent = class _Agent {
                 );
                 break;
               }
+              if (checkResult.type === "stop") {
+                console.log(
+                  chalk2.red(
+                    `[${this.#options.name}] Guardrail stopped - unrecoverable error, no retry`
+                  )
+                );
+                writer.write(part);
+                writer.write({ type: "finish" });
+                return;
+              }
               if (checkResult.part.type === "text-delta") {
                 accumulatedText += checkResult.part.delta;
               }
-              writer.write(checkResult.part);
+              writer.write(part);
             }
             if (!guardrailFailed) {
               writer.write({ type: "finish" });
@@ -2307,7 +2319,7 @@ var ReportGrounding = class extends AbstractGrounding {
       }),
       fragment(
         "instructions",
-        dedent`
+        dedent2`
           Write a business context that helps another agent answer questions accurately.
 
           For EACH table, do queries ONE AT A TIME: