Merge pull request #209 from activeloopai/fix/skip-missing-table-reads

fix(reads): skip lazy SELECTs for absent tables via listTables pre-check

Author: khustup2

src/commands/context.ts

@@ -61,13 +61,16 @@ export async function runContextCommand(args: string[]): Promise<void> {
     cfg.tableName,
   );
 
+  const known = await api.knownTablesOrNull();
+  const tableExists = known ? (name: string) => known.includes(name) : undefined;
   const block = await renderContextBlock(
     (sql: string) => api.query(sql) as Promise<Array<Record<string, unknown>>>,
     {
       rulesTable: cfg.rulesTableName,
       goalsTable: cfg.goalsTableName,
       currentUser: cfg.userName,
     },
+    { tableExists },
   );
 
   if (!block) {

src/deeplake-api.ts

@@ -413,6 +413,22 @@ export class DeeplakeApi {
     return tables;
   }
 
+  /**
+   * Like listTables() but returns null when the list could NOT be trusted
+   * (the fetch failed / was non-cacheable). Callers gating a read on table
+   * existence use this to tell a genuinely-empty workspace ([]) apart from a
+   * failed lookup (null): on [] they can safely skip the read (no table → no
+   * 42P01), on null they must fall back to SELECT-then-catch so a transient
+   * lookup blip doesn't drop a read of a table that really exists.
+   */
+  async knownTablesOrNull(): Promise<string[] | null> {
+    if (this._tablesCache) return [...this._tablesCache];
+    const { tables, cacheable } = await this._fetchTables();
+    if (!cacheable) return null;
+    this._tablesCache = [...tables];
+    return [...tables];
+  }
+
   private async _fetchTables(): Promise<{ tables: string[]; cacheable: boolean }> {
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       try {

src/hooks/cursor/session-start.ts

@@ -184,14 +184,18 @@ async function main(): Promise<void> {
         // to the user (model-only), so the full block is fine. Renderer
         // absorbs its own errors and returns "" on any failure (including
         // missing rules table — see context-renderer.ts).
+        // Trusted table list (cached) so the renderer skips the rules/goals
+        // SELECT when the table isn't there yet — avoids a 42P01 server-side.
+        const known = await api.knownTablesOrNull();
+        const tableExists = known ? (name: string) => known.includes(name) : undefined;
         rulesBlock = await renderContextBlock(
           (sql: string) => api.query(sql) as Promise<Array<Record<string, unknown>>>,
           {
             rulesTable: config.rulesTableName,
             goalsTable: config.goalsTableName,
             currentUser: config.userName,
           },
-          { log },
+          { log, tableExists },
         );
       }
     } catch (e: any) {

src/hooks/hermes/session-start.ts

@@ -154,14 +154,18 @@ async function main(): Promise<void> {
         }
         // Read-only renderer. Hermes's context field is invisible to
         // the user (model-only). Renderer absorbs its own errors.
+        // Trusted table list (cached) so the renderer skips the rules/goals
+        // SELECT when the table isn't there yet — avoids a 42P01 server-side.
+        const known = await api.knownTablesOrNull();
+        const tableExists = known ? (name: string) => known.includes(name) : undefined;
         rulesBlock = await renderContextBlock(
           (sql: string) => api.query(sql) as Promise<Array<Record<string, unknown>>>,
           {
             rulesTable: config.rulesTableName,
             goalsTable: config.goalsTableName,
             currentUser: config.userName,
           },
-          { log },
+          { log, tableExists },
         );
       }
     } catch (e: any) {

src/hooks/session-start.ts

@@ -210,14 +210,19 @@ async function main(): Promise<void> {
         // It absorbs its own errors (missing table, network, etc.)
         // and returns "" on any failure — SessionStart MUST NOT fail
         // because of a bad rules read.
+        // Trusted table list (cached — ensureTable above already warmed it)
+        // so the renderer can skip the rules/goals SELECT when the table
+        // isn't there yet, avoiding a 42P01 server-side on every SessionStart.
+        const known = await api.knownTablesOrNull();
+        const tableExists = known ? (name: string) => known.includes(name) : undefined;
         rulesBlock = await renderContextBlock(
           (sql: string) => api.query(sql) as Promise<Array<Record<string, unknown>>>,
           {
             rulesTable: config.rulesTableName,
             goalsTable: config.goalsTableName,
             currentUser: config.userName,
           },
-          { log },
+          { log, tableExists },
         );
       }
     } catch (e: any) {

src/hooks/shared/context-renderer.ts

@@ -47,6 +47,15 @@ export interface RenderOptions {
   maxGoals?: number;
   /** Optional logger for debugging — receives line-by-line trace events. */
   log?: (msg: string) => void;
+  /**
+   * Optional existence predicate built from a trusted table list (see
+   * DeeplakeApi.knownTablesOrNull). When provided and it reports a table
+   * absent, we skip the SELECT entirely — a fresh workspace that never
+   * created hivemind_rules / hivemind_goals would otherwise log a 42P01
+   * server-side on every SessionStart. When omitted (e.g. the table list
+   * couldn't be fetched), we fall back to the SELECT-then-catch path below.
+   */
+  tableExists?: (name: string) => boolean;
 }
 
 /**
@@ -82,25 +91,35 @@ export async function renderContextBlock(
     // Over-fetch so the "X more" truncation hint can give a useful
     // count. 4× the display cap balances "this user has a lot" against
     // unbounded reads on a busy org.
+    const tableExists = opts.tableExists;
+
     let rules: RuleRow[] = [];
-    try {
-      rules = await listRules(query, input.rulesTable, {
-        status: "active",
-        limit: Math.max(maxRules * 4, maxRules + 1),
-      });
-    } catch (rulesErr: unknown) {
-      const rmsg = rulesErr instanceof Error ? rulesErr.message : String(rulesErr);
-      log(`render-context-block: rules unavailable (continuing): ${rmsg}`);
+    if (tableExists && !tableExists(input.rulesTable)) {
+      log(`render-context-block: rules table "${input.rulesTable}" not present — skipping read`);
+    } else {
+      try {
+        rules = await listRules(query, input.rulesTable, {
+          status: "active",
+          limit: Math.max(maxRules * 4, maxRules + 1),
+        });
+      } catch (rulesErr: unknown) {
+        const rmsg = rulesErr instanceof Error ? rulesErr.message : String(rulesErr);
+        log(`render-context-block: rules unavailable (continuing): ${rmsg}`);
+      }
     }
 
     let goals: OpenGoalRow[] = [];
-    try {
-      goals = await listOpenGoals(query, input.goalsTable, input.currentUser, {
-        limit: Math.max(maxGoals * 4, maxGoals + 1),
-      });
-    } catch (goalsErr: unknown) {
-      const gmsg = goalsErr instanceof Error ? goalsErr.message : String(goalsErr);
-      log(`render-context-block: goals unavailable (continuing): ${gmsg}`);
+    if (tableExists && !tableExists(input.goalsTable)) {
+      log(`render-context-block: goals table "${input.goalsTable}" not present — skipping read`);
+    } else {
+      try {
+        goals = await listOpenGoals(query, input.goalsTable, input.currentUser, {
+          limit: Math.max(maxGoals * 4, maxGoals + 1),
+        });
+      } catch (goalsErr: unknown) {
+        const gmsg = goalsErr instanceof Error ? goalsErr.message : String(goalsErr);
+        log(`render-context-block: goals unavailable (continuing): ${gmsg}`);
+      }
     }
 
     const rulesShown = rules.slice(0, maxRules);

src/skillify/auto-pull.ts

@@ -89,6 +89,14 @@ export async function autoPullSkills(deps: AutoPullDeps = {}): Promise<AutoPullR
 
   // Build the query function. Tests inject one; real callers get the API client.
   let query: QueryFn;
+  // Deferred table-existence discovery — resolved INSIDE the timeout budget
+  // below, NOT here, so a slow `GET /tables` can't make SessionStart block
+  // past timeoutMs. Resolves to a predicate that lets runPull skip the SELECT
+  // (and the server-side 42P01) when `skills` doesn't exist yet on a fresh
+  // workspace, or undefined when the list can't be fetched / a test injects
+  // its own query (runPull then falls back to its isMissingTableError catch).
+  let discoverTableExists: () => Promise<((name: string) => boolean) | undefined> =
+    async () => undefined;
   if (deps.queryFn) {
     query = deps.queryFn;
   } else {
@@ -100,22 +108,32 @@ export async function autoPullSkills(deps: AutoPullDeps = {}): Promise<AutoPullR
       config.skillsTableName,
     );
     query = (sql: string) => api.query(sql) as Promise<Record<string, unknown>[]>;
+    discoverTableExists = async () => {
+      const known = await api.knownTablesOrNull();
+      return known ? (name: string) => known.includes(name) : undefined;
+    };
   }
 
   const install = deps.install ?? "global";
   const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 
   try {
     const summary = await withTimeout(
-      runPull({
-        query,
-        tableName: config.skillsTableName,
-        install,
-        cwd: install === "project" ? (deps.cwd ?? process.cwd()) : undefined,
-        users: [],
-        dryRun: false,
-        force: false,
-      }),
+      // Table discovery + pull share one budget: if `GET /tables` hangs the
+      // whole thing times out and we degrade, instead of blocking startup.
+      (async () => {
+        const tableExists = await discoverTableExists();
+        return runPull({
+          query,
+          tableName: config.skillsTableName,
+          install,
+          cwd: install === "project" ? (deps.cwd ?? process.cwd()) : undefined,
+          users: [],
+          dryRun: false,
+          force: false,
+          tableExists,
+        });
+      })(),
       timeoutMs,
     );
     log(`pulled scanned=${summary.scanned} wrote=${summary.wrote} skipped=${summary.skipped}`);

src/skillify/pull.ts

@@ -59,6 +59,15 @@ export interface PullOptions {
   dryRun?: boolean;
   /** Overwrite even when local version >= remote. Backs up the existing file. */
   force?: boolean;
+  /**
+   * Optional existence predicate built from a trusted table list (see
+   * DeeplakeApi.knownTablesOrNull). When it reports the skills table absent
+   * we skip the SELECT and treat it as empty — a fresh workspace lazily
+   * creates `skills` on first INSERT, so reading it first otherwise logs a
+   * 42P01 server-side on every SessionStart auto-pull. Omitted (or the list
+   * couldn't be fetched) falls back to the SELECT-then-catch path below.
+   */
+  tableExists?: (name: string) => boolean;
 }
 
 export interface PullResultEntry {
@@ -463,21 +472,29 @@ export async function runPull(opts: PullOptions): Promise<PullSummary> {
   // hasn't been lazy-migrated by an INSERT yet) retry once with the
   // legacy SELECT shape so the pull keeps working until the next write.
   let rows: Record<string, unknown>[] = [];
-  try {
-    rows = await opts.query(sql);
-  } catch (e: any) {
-    if (isMissingTableError(e?.message)) {
-      rows = [];
-    } else if (isMissingContributorsColumnError(e?.message)) {
-      const legacySql = buildPullSql({
-        tableName: opts.tableName,
-        users: opts.users,
-        skillName: opts.skillName,
-        includeContributors: false,
-      });
-      rows = await opts.query(legacySql);
-    } else {
-      throw e;
+  if (opts.tableExists && !opts.tableExists(opts.tableName)) {
+    // Known-absent from a trusted table list: skip the SELECT so a fresh
+    // workspace doesn't log a 42P01 server-side. Leaves rows empty, the same
+    // outcome as the isMissingTableError catch below, minus the round-trip
+    // and the error.
+    rows = [];
+  } else {
+    try {
+      rows = await opts.query(sql);
+    } catch (e: any) {
+      if (isMissingTableError(e?.message)) {
+        rows = [];
+      } else if (isMissingContributorsColumnError(e?.message)) {
+        const legacySql = buildPullSql({
+          tableName: opts.tableName,
+          users: opts.users,
+          skillName: opts.skillName,
+          includeContributors: false,
+        });
+        rows = await opts.query(legacySql);
+      } else {
+        throw e;
+      }
     }
   }
   const latest = selectLatestPerName(rows);

tests/claude-code/cli-context.test.ts

@@ -8,6 +8,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
  */
 
 const queryMock = vi.fn();
+const knownTablesMock = vi.fn();
 
 vi.mock("../../src/config.js", () => ({
   loadConfig: vi.fn(),
@@ -23,6 +24,7 @@ vi.mock("../../src/deeplake-api.js", () => ({
       _tableName: string,
     ) { /* nothing */ }
     query(sql: string) { return queryMock(sql); }
+    async knownTablesOrNull() { return knownTablesMock(); }
   },
 }));
 
@@ -55,6 +57,9 @@ beforeEach(() => {
   logged = [];
   erred = [];
   queryMock.mockReset().mockResolvedValue([]);
+  // Default: untrusted table list (null) → renderer SELECTs unconditionally.
+  // Individual tests override to return a trusted list and exercise gating.
+  knownTablesMock.mockReset().mockResolvedValue(null);
   loadConfigMock.mockReset().mockReturnValue(VALID_CONFIG);
   logSpy = vi.spyOn(console, "log").mockImplementation((...a: any[]) => { logged.push(a.join(" ")); });
   errSpy = vi.spyOn(console, "error").mockImplementation((...a: any[]) => { erred.push(a.join(" ")); });
@@ -151,6 +156,32 @@ describe("runContextCommand — output", () => {
     expect(erred.some(l => l.includes("(no active rules or open goals)"))).toBe(true);
   });
 
+  it("gates the SELECTs on knownTablesOrNull when the table list is trusted", async () => {
+    // A non-null table list lets renderContextBlock skip the SELECT for any
+    // absent table (avoids a 42P01 server-side). Both present here, so both
+    // SELECTs still run — and the tableExists predicate is exercised.
+    knownTablesMock.mockResolvedValue(["hivemind_rules", "hivemind_goals"]);
+    queryMock.mockResolvedValueOnce([{
+      id: "row-1", rule_id: "rule-1", text: "no DROP TABLE on prod",
+      scope: "team", status: "active", assigned_by: "alice@activeloop.ai",
+      version: 1, created_at: "2026-05-20T10:00:00Z",
+      agent: "manual", plugin_version: "0.7.99",
+    }]);
+    queryMock.mockResolvedValueOnce([]); // goals empty
+    await runContextCommand([]);
+    expect(logged.some(l => l.includes("no DROP TABLE on prod"))).toBe(true);
+    expect(queryMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("skips every SELECT when the trusted table list omits rules + goals", async () => {
+    // Fresh workspace: knownTablesOrNull returns [] → no SELECT may fire
+    // (each would log a 42P01 server-side). Empty render → stderr diagnostic.
+    knownTablesMock.mockResolvedValue([]);
+    await runContextCommand([]);
+    expect(queryMock).not.toHaveBeenCalled();
+    expect(erred.some(l => l.includes("(no active rules or open goals)"))).toBe(true);
+  });
+
   it("uses the configured table names from cfg (not hardcoded)", async () => {
     loadConfigMock.mockReturnValueOnce({
       ...VALID_CONFIG,