fix: improve tool reliability — sql_execute crash, edit context drift, webfetch failures

packages/opencode/script/pre-release-check.ts

@@ -36,7 +36,7 @@ function fail(msg: string) {
 // ---------------------------------------------------------------------------
 // Check 1: Required externals are in package.json dependencies
 // ---------------------------------------------------------------------------
-console.log("\n[1/4] Checking required externals in package.json...")
+console.log("\n[1/5] Checking required externals in package.json...")
 
 const requiredExternals = ["@altimateai/altimate-core"]
 
@@ -51,7 +51,7 @@ for (const ext of requiredExternals) {
 // ---------------------------------------------------------------------------
 // Check 2: Required externals are resolvable in node_modules
 // ---------------------------------------------------------------------------
-console.log("\n[2/4] Checking required externals are installed...")
+console.log("\n[2/5] Checking required externals are installed...")
 
 for (const ext of requiredExternals) {
   try {
@@ -62,10 +62,37 @@ for (const ext of requiredExternals) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Check 2b: Verify altimate-core napi binary has all expected exports
+// ---------------------------------------------------------------------------
+console.log("\n[2b/5] Verifying altimate-core napi exports...")
+
+const CRITICAL_EXPORTS = [
+  "getStatementTypes", "formatSql", "lint", "validate", "transpile",
+  "extractMetadata", "columnLineage", "trackLineage", "diffSchemas",
+  "importDdl", "exportDdl", "optimizeContext", "pruneSchema",
+  "compareQueries", "classifyPii", "checkQueryPii", "parseDbtProject",
+]
+
+try {
+  const core = require("@altimateai/altimate-core")
+  const missing = CRITICAL_EXPORTS.filter((name) => typeof core[name] !== "function")
+  if (missing.length > 0) {
+    fail(
+      `altimate-core binary is missing ${missing.length} export(s): ${missing.join(", ")}.\n` +
+        `    The platform binary may be stale. Fix: rm -rf node_modules && bun install`,
+    )
+  } else {
+    pass(`All ${CRITICAL_EXPORTS.length} critical napi exports verified`)
+  }
+} catch (e: any) {
+  fail(`altimate-core failed to load: ${e.message}`)
+}
+
 // ---------------------------------------------------------------------------
 // Check 3: Build and smoke-test the binary
 // ---------------------------------------------------------------------------
-console.log("\n[3/4] Building local binary...")
+console.log("\n[3/5] Building local binary...")
 
 const buildResult = spawnSync("bun", ["run", "build:local"], {
   cwd: pkgDir,
@@ -105,7 +132,7 @@ if (buildResult.status !== 0) {
   if (!binaryPath) {
     fail("No binary found in dist/ after build")
   } else {
-    console.log("\n[4/4] Smoke-testing compiled binary...")
+    console.log("\n[4/5] Smoke-testing compiled binary...")
 
     // Resolve NODE_PATH like the bin wrapper does — start from pkgDir
     // to include workspace-level node_modules where NAPI modules live

packages/opencode/src/altimate/tools/sql-classify.ts

@@ -2,27 +2,57 @@
 //
 // Uses altimate-core's AST-based getStatementTypes() for accurate classification.
 // Handles CTEs, string literals, procedural blocks, all dialects correctly.
+// Falls back to regex-based heuristics if the napi binary fails to load.
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const core: any = require("@altimateai/altimate-core")
+// Safe import: napi binary may not be available on all platforms
+let getStatementTypes: ((sql: string, dialect?: string | null) => any) | null = null
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const core = require("@altimateai/altimate-core")
+  if (typeof core?.getStatementTypes === "function") {
+    getStatementTypes = core.getStatementTypes
+  }
+} catch {
+  // napi binary failed to load — will use regex fallback
+}
 
-// Categories from altimate-core that indicate write operations
-const WRITE_CATEGORIES = new Set(["dml", "ddl", "dcl", "tcl"])
 // Only SELECT queries are known safe. "other" (SHOW, SET, USE, etc.) is ambiguous — prompt for permission.
 const READ_CATEGORIES = new Set(["query"])
 
 // Hard-deny patterns — blocked regardless of permissions
 const HARD_DENY_TYPES = new Set(["DROP DATABASE", "DROP SCHEMA", "TRUNCATE", "TRUNCATE TABLE"])
 
+// Regex fallback: patterns that indicate write operations (case-insensitive, anchored to statement start)
+const WRITE_PATTERN =
+  /^\s*(INSERT|UPDATE|DELETE|MERGE|CREATE|ALTER|DROP|TRUNCATE|GRANT|REVOKE|CALL|EXEC)\b/i
+const HARD_DENY_PATTERN =
+  /^\s*(DROP\s+(DATABASE|SCHEMA)\b|TRUNCATE(\s+TABLE)?\s)/i
+
+/**
+ * Regex-based fallback classifier for when altimate-core is unavailable.
+ * Conservative: treats anything not clearly a SELECT/WITH/SHOW/EXPLAIN as "write".
+ */
+function classifyFallback(sql: string): { queryType: "read" | "write"; blocked: boolean } {
+  const trimmed = sql.replace(/\/\*[\s\S]*?\*\//g, "").trim()
+  const blocked = HARD_DENY_PATTERN.test(trimmed)
+  const queryType = WRITE_PATTERN.test(trimmed) ? "write" : "read"
+  return { queryType, blocked }
+}
+
 /**
  * Classify a SQL string as "read" or "write" using AST parsing.
  * If ANY statement is a write, returns "write".
  */
 export function classify(sql: string): "read" | "write" {
-  const result = core.getStatementTypes(sql)
-  if (!result?.categories?.length) return "read"
-  // Treat unknown categories (not in WRITE or READ sets) as write to fail safe
-  return result.categories.some((c: string) => !READ_CATEGORIES.has(c)) ? "write" : "read"
+  if (!sql || typeof sql !== "string") return "read"
+  if (!getStatementTypes) return classifyFallback(sql).queryType
+  try {
+    const result = getStatementTypes(sql)
+    if (!result?.categories?.length) return "read"
+    return result.categories.some((c: string) => !READ_CATEGORIES.has(c)) ? "write" : "read"
+  } catch {
+    return classifyFallback(sql).queryType
+  }
 }
 
 /**
@@ -38,15 +68,21 @@ export function classifyMulti(sql: string): "read" | "write" {
  * Returns both the overall query type and whether a hard-deny pattern was found.
  */
 export function classifyAndCheck(sql: string): { queryType: "read" | "write"; blocked: boolean } {
-  const result = core.getStatementTypes(sql)
-  if (!result?.statements?.length) return { queryType: "read", blocked: false }
+  if (!sql || typeof sql !== "string") return { queryType: "read", blocked: false }
+  if (!getStatementTypes) return classifyFallback(sql)
+  try {
+    const result = getStatementTypes(sql)
+    if (!result?.statements?.length) return { queryType: "read", blocked: false }
 
-  const blocked = result.statements.some((s: { statement_type: string }) =>
-    s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()),
-  )
+    const blocked = result.statements.some(
+      (s: { statement_type: string }) =>
+        s.statement_type && HARD_DENY_TYPES.has(s.statement_type.toUpperCase()),
+    )
 
-  const categories = result.categories ?? []
-  // Unknown categories (not in WRITE or READ sets) are treated as write to fail safe
-  const queryType = categories.some((c: string) => !READ_CATEGORIES.has(c)) ? "write" : "read"
-  return { queryType: queryType as "read" | "write", blocked }
+    const categories = result.categories ?? []
+    const queryType = categories.some((c: string) => !READ_CATEGORIES.has(c)) ? "write" : "read"
+    return { queryType: queryType as "read" | "write", blocked }
+  } catch {
+    return classifyFallback(sql)
+  }
 }

packages/opencode/src/tool/edit.ts

@@ -629,6 +629,67 @@ export function trimDiff(diff: string): string {
   return trimmedLines.join("\n")
 }
 
+/**
+ * Build a helpful error message when oldString isn't found.
+ * Includes a snippet of the closest-matching region so the model can self-correct.
+ */
+export function buildNotFoundMessage(content: string, oldString: string): string {
+  const base = "Could not find oldString in the file."
+
+  // Find the first line of oldString and search for it in the file
+  const firstLine = oldString.split("\n")[0].trim()
+  if (!firstLine) return base + " The oldString appears to be empty or whitespace-only."
+
+  const contentLines = content.split("\n")
+  let bestLine = -1
+  let bestScore = 0
+
+  // Search for the line with highest similarity to the first line of oldString
+  for (let i = 0; i < contentLines.length; i++) {
+    const trimmed = contentLines[i].trim()
+    if (!trimmed) continue
+
+    // Skip very short lines — they produce false similarity matches
+    const minLen = Math.min(trimmed.length, firstLine.length)
+    if (minLen < 4) continue
+
+    // Exact substring match is best
+    if (trimmed.includes(firstLine) || firstLine.includes(trimmed)) {
+      bestLine = i
+      bestScore = 1
+      break
+    }
+
+    // Skip if lengths are too different (>3x ratio) — not a meaningful comparison
+    const maxLen = Math.max(trimmed.length, firstLine.length)
+    if (minLen * 3 < maxLen) continue
+
+    // Levenshtein similarity for close matches
+    const score = 1 - levenshtein(trimmed, firstLine) / maxLen
+    if (score > bestScore && score > 0.6) {
+      bestScore = score
+      bestLine = i
+    }
+  }
+
+  if (bestLine === -1) {
+    return base + ` The first line of your oldString ("${firstLine.slice(0, 80)}") was not found anywhere in the file. Re-read the file before editing.`
+  }
+
+  // Show a small window around the best match
+  const start = Math.max(0, bestLine - 1)
+  const end = Math.min(contentLines.length, bestLine + 4)
+  const snippet = contentLines
+    .slice(start, end)
+    .map((l, i) => `  ${start + i + 1} | ${l}`)
+    .join("\n")
+
+  return (
+    base +
+    ` A similar line was found at line ${bestLine + 1}. The file may have changed since you last read it.\n\nNearest match:\n${snippet}\n\nRe-read the file and use the exact current content for oldString.`
+  )
+}
+
 export function replace(content: string, oldString: string, newString: string, replaceAll = false): string {
   if (oldString === newString) {
     throw new Error("No changes to apply: oldString and newString are identical.")
@@ -661,9 +722,7 @@ export function replace(content: string, oldString: string, newString: string, r
   }
 
   if (notFound) {
-    throw new Error(
-      "Could not find oldString in the file. It must match exactly, including whitespace, indentation, and line endings.",
-    )
+    throw new Error(buildNotFoundMessage(content, oldString))
   }
   throw new Error("Found multiple matches for oldString. Provide more surrounding context to make the match unique.")
 }

packages/opencode/src/tool/webfetch.ts

@@ -15,6 +15,51 @@ const BROWSER_UA =
 // Status codes that warrant a retry with a different User-Agent
 const RETRYABLE_STATUSES = new Set([403, 406])
 
+// altimate_change start — session-level URL failure cache (#471)
+// Prevents repeated fetches to URLs that already returned 404/410 in this session.
+// Keyed by URL string. Cleared when the process restarts (new session).
+const failedUrls = new Map<string, { status: number; timestamp: number }>()
+const FAILURE_CACHE_TTL = 5 * 60 * 1000 // 5 minutes
+
+function isUrlCachedFailure(url: string): { status: number } | null {
+  const entry = failedUrls.get(url)
+  if (!entry) return null
+  if (Date.now() - entry.timestamp > FAILURE_CACHE_TTL) {
+    failedUrls.delete(url)
+    return null
+  }
+  return { status: entry.status }
+}
+
+function cacheUrlFailure(url: string, status: number): void {
+  // Only cache permanent-ish failures, not transient ones
+  if (status === 404 || status === 410 || status === 451) {
+    failedUrls.set(url, { status, timestamp: Date.now() })
+  }
+}
+
+/** Build an actionable error message so the model knows whether to retry. */
+function buildFetchError(url: string, status: number, headers?: Headers): string {
+  switch (status) {
+    case 404:
+      return `HTTP 404: ${url} does not exist. Do NOT retry this URL — it will fail again. Try a different URL or search for the correct page.`
+    case 410:
+      return `HTTP 410: ${url} has been permanently removed. Do NOT retry. Find an alternative resource.`
+    case 403:
+      return `HTTP 403: Access to ${url} is forbidden. The server rejected both bot and browser User-Agents. Try a different source.`
+    case 429: {
+      const retryAfter = headers?.get("retry-after")
+      const wait = retryAfter ? ` (retry after ${retryAfter}s)` : ""
+      return `HTTP 429: Rate limited by ${new URL(url).hostname}${wait}. Wait before fetching from this domain again, or use a different source.`
+    }
+    case 451:
+      return `HTTP 451: ${url} is unavailable for legal reasons. Do NOT retry.`
+    default:
+      return `HTTP ${status}: Request to ${url} failed. This may be transient — retry once if needed.`
+  }
+}
+// altimate_change end
+
 export const WebFetchTool = Tool.define("webfetch", {
   description: DESCRIPTION,
   parameters: z.object({
@@ -26,10 +71,23 @@ export const WebFetchTool = Tool.define("webfetch", {
     timeout: z.number().describe("Optional timeout in seconds (max 120)").optional(),
   }),
   async execute(params, ctx) {
-    // Validate URL
+    // altimate_change start — URL validation and failure cache (#471)
+    // Validate URL format
     if (!params.url.startsWith("http://") && !params.url.startsWith("https://")) {
       throw new Error("URL must start with http:// or https://")
     }
+    try {
+      new URL(params.url)
+    } catch {
+      throw new Error(`Invalid URL: "${params.url.slice(0, 200)}" is not a valid URL. Check the format and try again.`)
+    }
+
+    // Check failure cache — avoid re-fetching URLs that already returned 404/410
+    const cached = isUrlCachedFailure(params.url)
+    if (cached) {
+      throw new Error(buildFetchError(params.url, cached.status))
+    }
+    // altimate_change end
 
     await ctx.ask({
       permission: "webfetch",
@@ -83,9 +141,12 @@ export const WebFetchTool = Tool.define("webfetch", {
         response = await fetch(params.url, { signal, headers: browserHeaders })
       }
 
+      // altimate_change start — actionable error messages and failure caching (#471)
       if (!response.ok) {
-        throw new Error(`Request failed with status code: ${response.status}`)
+        cacheUrlFailure(params.url, response.status)
+        throw new Error(buildFetchError(params.url, response.status, response.headers))
       }
+      // altimate_change end
 
       // Check content length
       const contentLength = response.headers.get("content-length")