postgresai 0.16.0-dev.3 → 0.16.0-dev.4

package/dist/bin/postgres-ai.js

@@ -13425,7 +13425,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.3",
+  version: "0.16.0-dev.4",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16256,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-dev.3";
+var version = "0.16.0-dev.4";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -17267,83 +17267,47 @@ async function fetchReportFileData(params) {
   }
 }
 
-// lib/dblab.ts
-function isNumericProjectRef(ref) {
-  return /^[0-9]+$/.test(ref.trim());
-}
-async function resolveDblabInstanceId(params) {
-  const { apiKey, apiBaseUrl, orgId, debug } = params;
-  if (!apiKey) {
-    throw new Error("API key is required");
-  }
-  const ref = String(params.project ?? "").trim();
-  if (!ref) {
-    throw new Error("project is required (--project <id|alias>)");
-  }
-  const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/dblab_instances`);
-  url.searchParams.set("select", "id,project_id,project_name,project_alias,project_label_or_name,org_id");
-  if (typeof orgId === "number") {
-    url.searchParams.set("org_id", `eq.${orgId}`);
-  }
-  const headers = {
-    "access-token": apiKey,
-    "Content-Type": "application/json",
-    Connection: "close"
-  };
-  if (debug) {
-    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
-    console.error(`Debug: GET URL: ${url.toString()}`);
-    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-  }
-  const response = await fetch(url.toString(), { method: "GET", headers });
-  const text = await response.text();
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    console.error(`Debug: Response body: ${text}`);
-  }
-  if (!response.ok) {
-    throw new Error(formatHttpError("Failed to resolve project's DBLab instance", response.status, text));
-  }
-  let rows;
-  try {
-    const parsed = JSON.parse(text);
-    rows = Array.isArray(parsed) ? parsed : [];
-  } catch {
-    throw new Error(`Failed to parse DBLab instances response: ${text}`);
-  }
-  const numeric = isNumericProjectRef(ref);
-  const needle = ref.toLowerCase();
-  const match = rows.find((r) => {
-    if (numeric) {
-      return String(r.project_id ?? "") === ref;
-    }
-    return r.project_alias != null && String(r.project_alias).toLowerCase() === needle || r.project_name != null && String(r.project_name).toLowerCase() === needle || r.project_label_or_name != null && String(r.project_label_or_name).toLowerCase() === needle;
-  });
-  if (!match) {
-    throw new Error(`No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`);
-  }
-  return String(match.id);
-}
-async function callDblabApi(params) {
-  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
+// lib/joe.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+import * as crypto from "node:crypto";
+var JOE_COMMANDS = [
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "terminate",
+  "reset",
+  "describe"
+];
+var TERMINAL_STATES = new Set([
+  "done",
+  "error",
+  "timed_out"
+]);
+var AI_ENABLED_COMMANDS = new Set([
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "describe"
+]);
+var EXECUTING_COMMANDS = new Set([
+  "exec",
+  "explain"
+]);
+var DEFAULT_BUDGET_MS = 25000;
+var DEFAULT_POLL_INTERVAL_MS = 800;
+async function callRpc(params) {
+  const { apiKey, apiBaseUrl, fn, body, operation, debug } = params;
   if (!apiKey) {
     throw new Error("API key is required");
   }
-  if (!instanceId) {
-    throw new Error("instanceId is required");
-  }
   const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/rpc/dblab_api_call`);
-  const bodyObj = {
-    instance_id: instanceId,
-    action,
-    method
-  };
-  if (data !== undefined) {
-    bodyObj.data = data;
-  }
-  const body = JSON.stringify(bodyObj);
+  const url = new URL(`${base}/rpc/${fn}`);
+  const payload = JSON.stringify(body);
   const headers = {
     "access-token": apiKey,
     "Content-Type": "application/json",
@@ -17353,9 +17317,13 @@ async function callDblabApi(params) {
     const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
     console.error(`Debug: POST URL: ${url.toString()}`);
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.error(`Debug: Request body: ${body}`);
+    console.error(`Debug: Request body: ${payload}`);
   }
-  const response = await fetch(url.toString(), { method: "POST", headers, body });
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body: payload
+  });
   const text = await response.text();
   if (debug) {
     console.error(`Debug: Response status: ${response.status}`);
@@ -17364,470 +17332,311 @@ async function callDblabApi(params) {
   if (!response.ok) {
     throw new Error(formatHttpError(operation, response.status, text));
   }
-  if (text.trim() === "") {
-    return null;
-  }
   try {
     return JSON.parse(text);
   } catch {
     throw new Error(`${operation}: failed to parse response: ${text}`);
   }
 }
-async function createClone(params) {
-  const { apiKey, apiBaseUrl, instanceId, cloneId, branch, snapshotId, dbUser, dbPassword, isProtected, debug } = params;
-  const data = { protected: Boolean(isProtected) };
-  if (cloneId)
-    data.id = cloneId;
-  if (branch)
-    data.branch = branch;
-  if (snapshotId)
-    data.snapshot = { id: snapshotId };
-  if (dbUser && dbPassword)
-    data.db = { username: dbUser, password: dbPassword };
-  return callDblabApi({
+async function submitCommand(params) {
+  const { apiKey, apiBaseUrl, command, projectId, sql, args, sessionId, idempotencyKey, debug } = params;
+  if (!JOE_COMMANDS.includes(command)) {
+    throw new Error(`Unknown Joe command: ${command}`);
+  }
+  const body = {
+    project_id: projectId,
+    command,
+    sql: sql ?? null,
+    args: args ?? null,
+    session_id: sessionId ?? null
+  };
+  if (idempotencyKey) {
+    body.idempotency_key = idempotencyKey;
+  }
+  return callRpc({
     apiKey,
     apiBaseUrl,
-    instanceId,
-    action: "/clone",
-    method: "post",
-    data,
-    operation: "Failed to create clone",
+    fn: "joe_command_submit",
+    body,
+    operation: `Failed to submit ${command} command`,
     debug
   });
 }
-async function listClones(params) {
-  const { apiKey, apiBaseUrl, instanceId, debug } = params;
-  return callDblabApi({
+async function getCommandStatus(params) {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc({
     apiKey,
     apiBaseUrl,
-    instanceId,
-    action: "/clones",
-    method: "get",
-    operation: "Failed to list clones",
+    fn: "joe_command_status",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command status",
     debug
   });
 }
-async function getClone(params) {
-  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
-  if (!cloneId)
-    throw new Error("cloneId is required");
-  return callDblabApi({
+async function getCommandResult(params) {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc({
     apiKey,
     apiBaseUrl,
-    instanceId,
-    action: `/clone/${encodeURIComponent(cloneId)}`,
-    method: "get",
-    operation: "Failed to get clone",
+    fn: "joe_command_result",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command result",
     debug
   });
 }
-async function resetClone(params) {
-  const { apiKey, apiBaseUrl, instanceId, cloneId, snapshotId, latest, debug } = params;
-  if (!cloneId)
-    throw new Error("cloneId is required");
-  const data = { latest: latest ?? !snapshotId };
-  if (snapshotId)
-    data.snapshotID = snapshotId;
-  return callDblabApi({
-    apiKey,
-    apiBaseUrl,
-    instanceId,
-    action: `/clone/${encodeURIComponent(cloneId)}/reset`,
-    method: "post",
-    data,
-    operation: "Failed to reset clone",
-    debug
-  });
+function normalizeProjectRow(row) {
+  const projectId = row.project_id ?? row.id ?? 0;
+  return {
+    project_id: Number(projectId),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    label: row.label ?? null,
+    joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
+    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
+    instance_id: row.instance_id == null ? null : Number(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : Number(row.dblab_instance_id)
+  };
 }
-async function destroyClone(params) {
-  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
-  if (!cloneId)
-    throw new Error("cloneId is required");
-  return callDblabApi({
+async function listProjects(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  const body = {};
+  if (typeof orgId === "number") {
+    body.org_id = orgId;
+  }
+  const rows = await callRpc({
     apiKey,
     apiBaseUrl,
-    instanceId,
-    action: `/clone/${encodeURIComponent(cloneId)}`,
-    method: "delete",
-    operation: "Failed to destroy clone",
+    fn: "projects_list",
+    body,
+    operation: "Failed to list projects",
     debug
   });
+  if (!Array.isArray(rows)) {
+    return [];
+  }
+  return rows.map(normalizeProjectRow);
 }
-async function listBranches(params) {
-  const { apiKey, apiBaseUrl, instanceId, debug } = params;
-  return callDblabApi({
-    apiKey,
-    apiBaseUrl,
-    instanceId,
-    action: "/branches",
-    method: "get",
-    operation: "Failed to list branches",
-    debug
-  });
+function isNumericProjectRef(ref) {
+  return /^[0-9]+$/.test(ref.trim());
 }
-async function createBranch(params) {
-  const { apiKey, apiBaseUrl, instanceId, branchName, baseBranch, snapshotId, debug } = params;
-  if (!branchName)
-    throw new Error("branchName is required");
-  const data = { branchName };
-  if (baseBranch)
-    data.baseBranch = baseBranch;
-  if (snapshotId)
-    data.snapshotID = snapshotId;
-  return callDblabApi({
-    apiKey,
-    apiBaseUrl,
-    instanceId,
-    action: "/branch",
-    method: "post",
-    data,
-    operation: "Failed to create branch",
-    debug
+async function resolveProjectId(params) {
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  if (isNumericProjectRef(ref)) {
+    return Number(ref);
+  }
+  const projects = await listProjects({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId,
+    debug: params.debug
   });
+  const needle = ref.toLowerCase();
+  const match = projects.find((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle);
+  if (!match) {
+    throw new Error(`Project not found for alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  return match.project_id;
 }
-async function deleteBranch(params) {
-  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
-  if (!branchName)
-    throw new Error("branchName is required");
-  return callDblabApi({
-    apiKey,
-    apiBaseUrl,
-    instanceId,
-    action: `/branch/${encodeURIComponent(branchName)}`,
-    method: "delete",
-    operation: "Failed to delete branch",
-    debug
-  });
+function sessionStorePath(dir) {
+  return path3.join(dir ?? getConfigDir2(), "joe-sessions.json");
 }
-async function branchLog(params) {
-  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
-  if (!branchName)
-    throw new Error("branchName is required");
-  return callDblabApi({
-    apiKey,
-    apiBaseUrl,
-    instanceId,
-    action: `/branch/${encodeURIComponent(branchName)}/log`,
-    method: "get",
-    operation: "Failed to fetch branch log",
-    debug
-  });
+function readSessionStore(dir) {
+  const file = sessionStorePath(dir);
+  if (!fs3.existsSync(file)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(fs3.readFileSync(file, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return {};
 }
-async function listSnapshots(params) {
-  const { apiKey, apiBaseUrl, instanceId, branchName, dataset, debug } = params;
-  const qs = new URLSearchParams;
-  const branch = branchName?.trim();
-  if (branch)
-    qs.append("branch", branch);
-  if (dataset)
-    qs.append("dataset", dataset);
-  const action = `/snapshots${qs.toString() ? `?${qs.toString()}` : ""}`;
-  return callDblabApi({
-    apiKey,
-    apiBaseUrl,
-    instanceId,
-    action,
-    method: "get",
-    operation: "Failed to list snapshots",
-    debug
-  });
+function readStoredSessionId(projectId, dir) {
+  const store = readSessionStore(dir);
+  const value = store[String(projectId)];
+  return typeof value === "string" && value.length > 0 ? value : null;
 }
-async function createSnapshot(params) {
-  const { apiKey, apiBaseUrl, instanceId, cloneId, message, debug } = params;
-  if (!cloneId)
-    throw new Error("cloneId is required");
-  const data = { cloneID: cloneId };
-  if (message)
-    data.message = message;
-  return callDblabApi({
+function writeStoredSessionId(projectId, sessionId, dir) {
+  const baseDir = dir ?? getConfigDir2();
+  if (!fs3.existsSync(baseDir)) {
+    fs3.mkdirSync(baseDir, { recursive: true, mode: 448 });
+  }
+  const store = readSessionStore(dir);
+  store[String(projectId)] = sessionId;
+  fs3.writeFileSync(sessionStorePath(dir), JSON.stringify(store, null, 2) + `
+`, { mode: 384 });
+}
+function clearStoredSessionId(projectId, dir) {
+  const file = sessionStorePath(dir);
+  if (!fs3.existsSync(file)) {
+    return;
+  }
+  const store = readSessionStore(dir);
+  if (String(projectId) in store) {
+    delete store[String(projectId)];
+    fs3.writeFileSync(file, JSON.stringify(store, null, 2) + `
+`, { mode: 384 });
+  }
+}
+function computeIdempotencyKey(command, projectId, sql, args) {
+  if (EXECUTING_COMMANDS.has(command)) {
+    const canonical = `${projectId}
+${command}
+${sql ?? ""}
+${JSON.stringify(args ?? null)}`;
+    return `joe-${crypto.createHash("sha256").update(canonical).digest("hex")}`;
+  }
+  return `joe-${crypto.randomUUID()}`;
+}
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runCommand(params) {
+  const {
     apiKey,
     apiBaseUrl,
-    instanceId,
-    action: "/branch/snapshot",
-    method: "post",
-    data,
-    operation: "Failed to create snapshot",
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
     debug
-  });
-}
-async function destroySnapshot(params) {
-  const { apiKey, apiBaseUrl, instanceId, snapshotId, force, debug } = params;
-  if (!snapshotId)
-    throw new Error("snapshotId is required");
-  const action = `/snapshot/${encodeURIComponent(snapshotId)}?force=${Boolean(force)}`;
-  return callDblabApi({
+  } = params;
+  const budgetMs = params.budgetMs ?? DEFAULT_BUDGET_MS;
+  const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const now = params.now ?? Date.now;
+  const sleep = params.sleep ?? defaultSleep;
+  const idempotencyKey = params.idempotencyKey ?? computeIdempotencyKey(command, projectId, sql, args);
+  const submitted = await submitCommand({
     apiKey,
     apiBaseUrl,
-    instanceId,
-    action,
-    method: "delete",
-    operation: "Failed to destroy snapshot",
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    idempotencyKey,
     debug
   });
-}
-
-// lib/storage.ts
-import * as fs3 from "fs";
-import * as path3 from "path";
-var MAX_UPLOAD_SIZE = 500 * 1024 * 1024;
-var MAX_DOWNLOAD_SIZE = 500 * 1024 * 1024;
-var MIME_TYPES = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".bmp": "image/bmp",
-  ".ico": "image/x-icon",
-  ".pdf": "application/pdf",
-  ".json": "application/json",
-  ".xml": "application/xml",
-  ".zip": "application/zip",
-  ".gz": "application/gzip",
-  ".tar": "application/x-tar",
-  ".csv": "text/csv",
-  ".txt": "text/plain",
-  ".log": "text/plain",
-  ".sql": "application/sql",
-  ".html": "text/html",
-  ".css": "text/css",
-  ".js": "application/javascript",
-  ".ts": "application/typescript",
-  ".md": "text/markdown",
-  ".yaml": "application/x-yaml",
-  ".yml": "application/x-yaml"
-};
-async function uploadFile(params) {
-  const { apiKey, storageBaseUrl, filePath, debug } = params;
-  if (!apiKey) {
-    throw new Error("API key is required");
-  }
-  if (!storageBaseUrl) {
-    throw new Error("storageBaseUrl is required");
-  }
-  if (!filePath) {
-    throw new Error("filePath is required");
-  }
-  const resolvedPath = path3.resolve(filePath);
-  if (!fs3.existsSync(resolvedPath)) {
-    throw new Error(`File not found: ${resolvedPath}`);
-  }
-  const stat = fs3.statSync(resolvedPath);
-  if (!stat.isFile()) {
-    throw new Error(`Not a file: ${resolvedPath}`);
-  }
-  if (stat.size > MAX_UPLOAD_SIZE) {
-    throw new Error(`File too large: ${stat.size} bytes (max ${MAX_UPLOAD_SIZE})`);
-  }
-  const base = normalizeBaseUrl(storageBaseUrl);
-  if (new URL(base).protocol === "http:") {
-    console.error("Warning: storage URL uses HTTP — API key will be sent unencrypted");
-  }
-  const url = `${base}/upload`;
-  const fileBuffer = fs3.readFileSync(resolvedPath);
-  const fileName = path3.basename(resolvedPath);
-  const ext = path3.extname(fileName).toLowerCase();
-  const mimeType = MIME_TYPES[ext] || "application/octet-stream";
-  const formData = new FormData;
-  formData.append("file", new Blob([fileBuffer], { type: mimeType }), fileName);
-  const headers = {
-    "access-token": apiKey
-  };
-  if (debug) {
-    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
-    console.error(`Debug: Storage base URL: ${base}`);
-    console.error(`Debug: POST URL: ${url}`);
-    console.error(`Debug: File: ${resolvedPath} (${stat.size} bytes, ${mimeType})`);
-    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-  }
-  const response = await fetch(url, {
-    method: "POST",
-    headers,
-    body: formData
-  });
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
-  }
-  const data = await response.text();
-  if (response.ok) {
-    try {
-      return JSON.parse(data);
-    } catch {
-      throw new Error(`Failed to parse upload response: ${data}`);
-    }
-  } else {
-    throw new Error(formatHttpError("Failed to upload file", response.status, data));
-  }
-}
-async function downloadFile(params) {
-  const { apiKey, storageBaseUrl, fileUrl, outputPath, debug } = params;
-  if (!apiKey) {
-    throw new Error("API key is required");
-  }
-  if (!storageBaseUrl) {
-    throw new Error("storageBaseUrl is required");
-  }
-  if (!fileUrl) {
-    throw new Error("fileUrl is required");
-  }
-  const base = normalizeBaseUrl(storageBaseUrl);
-  if (new URL(base).protocol === "http:") {
-    console.error("Warning: storage URL uses HTTP — API key will be sent unencrypted");
-  }
-  let fullUrl;
-  if (fileUrl.startsWith("http://") || fileUrl.startsWith("https://")) {
-    if (!fileUrl.startsWith(base + "/")) {
-      throw new Error(`URL must be under storage base URL: ${base}`);
+  const commandId = submitted.command_id;
+  const newSessionId = submitted.session_id ?? sessionId ?? null;
+  const deadline = now() + budgetMs;
+  let status = submitted.status;
+  while (true) {
+    const statusResp = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug });
+    status = statusResp.status;
+    if (TERMINAL_STATES.has(status)) {
+      break;
     }
-    fullUrl = fileUrl;
-  } else {
-    const relativePath = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
-    fullUrl = `${base}${relativePath}`;
-  }
-  const urlFilename = path3.basename(new URL(fullUrl).pathname);
-  if (!urlFilename) {
-    throw new Error("Cannot derive filename from URL; please specify --output");
-  }
-  const saveTo = outputPath ? path3.resolve(outputPath) : path3.resolve(urlFilename);
-  if (!outputPath) {
-    const normalizedSave = path3.normalize(saveTo);
-    const cwd = path3.normalize(process.cwd());
-    if (normalizedSave !== cwd && !normalizedSave.startsWith(cwd + path3.sep)) {
-      throw new Error("Derived output path escapes current directory; please specify --output");
+    if (now() >= deadline) {
+      return { commandId, sessionId: newSessionId, status, result: null, budgetExpired: true };
     }
+    await sleep(pollIntervalMs);
   }
-  const headers = {
-    "access-token": apiKey
-  };
-  if (debug) {
-    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
-    console.error(`Debug: Storage base URL: ${base}`);
-    console.error(`Debug: GET URL: ${fullUrl}`);
-    console.error(`Debug: Output: ${saveTo}`);
-    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  const result = await getCommandResult({ apiKey, apiBaseUrl, commandId, debug });
+  return { commandId, sessionId: newSessionId, status, result, budgetExpired: false };
+}
+async function executeJoeCommand(params) {
+  const projectId = await resolveProjectId({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    project: params.project,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  let sessionId;
+  if (params.newSession) {
+    clearStoredSessionId(projectId, params.sessionDir);
+    sessionId = null;
+  } else if (params.session) {
+    sessionId = String(params.session);
+  } else {
+    sessionId = readStoredSessionId(projectId, params.sessionDir);
   }
-  const response = await fetch(fullUrl, {
-    method: "GET",
-    headers
+  const outcome = await runCommand({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    command: params.command,
+    projectId,
+    sql: params.sql,
+    args: params.args,
+    sessionId,
+    budgetMs: params.budgetMs,
+    pollIntervalMs: params.pollIntervalMs,
+    debug: params.debug,
+    now: params.now,
+    sleep: params.sleep
   });
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
-  }
-  if (!response.ok) {
-    const data = await response.text();
-    throw new Error(formatHttpError("Failed to download file", response.status, data));
-  }
-  const contentLength = response.headers.get("content-length");
-  if (contentLength && parseInt(contentLength, 10) > MAX_DOWNLOAD_SIZE) {
-    throw new Error(`File too large: ${contentLength} bytes (max ${MAX_DOWNLOAD_SIZE})`);
-  }
-  const arrayBuffer = await response.arrayBuffer();
-  const buffer = Buffer.from(arrayBuffer);
-  const parentDir = path3.dirname(saveTo);
-  if (!fs3.existsSync(parentDir)) {
-    fs3.mkdirSync(parentDir, { recursive: true });
+  if (outcome.sessionId) {
+    writeStoredSessionId(projectId, outcome.sessionId, params.sessionDir);
   }
-  fs3.writeFileSync(saveTo, buffer);
-  return {
-    savedTo: saveTo,
-    size: buffer.length,
-    mimeType: response.headers.get("content-type")
-  };
+  return { ...outcome, command: params.command, projectId };
 }
-var IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico"]);
-function buildMarkdownLink(fileUrl, storageBaseUrl, filename) {
-  const base = normalizeBaseUrl(storageBaseUrl);
-  const normalizedFileUrl = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
-  const fullUrl = fileUrl.startsWith("http://") || fileUrl.startsWith("https://") ? fileUrl : `${base}${normalizedFileUrl}`;
-  const name = filename || path3.basename(new URL(fullUrl).pathname);
-  const safeName = name.replace(/[\[\]()]/g, "\\$&");
-  const ext = path3.extname(name).toLowerCase();
-  if (IMAGE_EXTENSIONS.has(ext)) {
-    return `![${safeName}](${fullUrl})`;
-  }
-  return `[${safeName}](${fullUrl})`;
+
+// lib/dblab.ts
+function isNumericProjectRef2(ref) {
+  return /^[0-9]+$/.test(ref.trim());
 }
-async function uploadAttachments(params) {
-  const { apiKey, storageBaseUrl, attachmentPaths, debug } = params;
-  if (!attachmentPaths || attachmentPaths.length === 0) {
-    return [];
+async function resolveDblabInstanceId(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
   }
-  const out = [];
-  for (const attachmentPath of attachmentPaths) {
-    const result = await uploadFile({
-      apiKey,
-      storageBaseUrl,
-      filePath: attachmentPath,
-      debug
-    });
-    const markdown = buildMarkdownLink(result.url, storageBaseUrl, result.metadata.originalName);
-    out.push({
-      path: attachmentPath,
-      url: result.url,
-      markdown,
-      metadata: result.metadata
-    });
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
   }
-  return out;
-}
-function appendAttachmentsToContent(content, attachments) {
-  if (!attachments || attachments.length === 0) {
-    return content;
+  let projects;
+  try {
+    projects = await listProjects({ apiKey, apiBaseUrl, orgId, debug });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to resolve project's DBLab instance: ${message}`);
   }
-  const links = attachments.map((a) => a.markdown).join(`
-`);
-  if (!content || !content.trim()) {
-    return links;
+  const numeric = isNumericProjectRef2(ref);
+  const needle = ref.toLowerCase();
+  const match = projects.find((p) => {
+    if (numeric) {
+      return String(p.project_id) === ref;
+    }
+    return p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle || p.label !== null && p.label.toLowerCase() === needle;
+  });
+  if (!match) {
+    throw new Error(`No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`);
   }
-  return `${content}
-
-${links}`;
+  if (match.dblab_instance_id == null) {
+    throw new Error(`Project '${ref}' has no active DBLab instance. Register a DBLab instance for it in the Console first.`);
+  }
+  return String(match.dblab_instance_id);
 }
-
-// lib/joe.ts
-import * as fs4 from "fs";
-import * as path4 from "path";
-import * as crypto from "node:crypto";
-var JOE_COMMANDS = [
-  "plan",
-  "explain",
-  "exec",
-  "hypo",
-  "activity",
-  "terminate",
-  "reset",
-  "describe"
-];
-var TERMINAL_STATES = new Set([
-  "done",
-  "error",
-  "timed_out"
-]);
-var AI_ENABLED_COMMANDS = new Set([
-  "plan",
-  "explain",
-  "exec",
-  "hypo",
-  "activity",
-  "describe"
-]);
-var EXECUTING_COMMANDS = new Set([
-  "exec",
-  "explain"
-]);
-var DEFAULT_BUDGET_MS = 25000;
-var DEFAULT_POLL_INTERVAL_MS = 800;
-async function callRpc(params) {
-  const { apiKey, apiBaseUrl, fn, body, operation, debug } = params;
+async function callDblabApi(params) {
+  const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;
   if (!apiKey) {
     throw new Error("API key is required");
   }
+  if (!instanceId) {
+    throw new Error("instanceId is required");
+  }
   const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/rpc/${fn}`);
-  const payload = JSON.stringify(body);
+  const url = new URL(`${base}/rpc/dblab_api_call`);
+  const bodyObj = {
+    instance_id: instanceId,
+    action,
+    method
+  };
+  if (data !== undefined) {
+    bodyObj.data = data;
+  }
+  const body = JSON.stringify(bodyObj);
   const headers = {
     "access-token": apiKey,
     "Content-Type": "application/json",
@@ -17837,267 +17646,438 @@ async function callRpc(params) {
     const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
     console.error(`Debug: POST URL: ${url.toString()}`);
     console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    console.error(`Debug: Request body: ${payload}`);
+    console.error(`Debug: Request body: ${body}`);
   }
-  const response = await fetch(url.toString(), {
-    method: "POST",
-    headers,
-    body: payload
+  const response = await fetch(url.toString(), { method: "POST", headers, body });
+  const text = await response.text();
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${text}`);
+  }
+  if (!response.ok) {
+    throw new Error(formatHttpError(operation, response.status, text));
+  }
+  if (text.trim() === "") {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+async function createClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, branch, snapshotId, dbUser, dbPassword, isProtected, debug } = params;
+  const data = { protected: Boolean(isProtected) };
+  if (cloneId)
+    data.id = cloneId;
+  if (branch)
+    data.branch = branch;
+  if (snapshotId)
+    data.snapshot = { id: snapshotId };
+  if (dbUser && dbPassword)
+    data.db = { username: dbUser, password: dbPassword };
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/clone",
+    method: "post",
+    data,
+    operation: "Failed to create clone",
+    debug
+  });
+}
+async function listClones(params) {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/clones",
+    method: "get",
+    operation: "Failed to list clones",
+    debug
+  });
+}
+async function getClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`,
+    method: "get",
+    operation: "Failed to get clone",
+    debug
+  });
+}
+async function resetClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, snapshotId, latest, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  const data = { latest: latest ?? !snapshotId };
+  if (snapshotId)
+    data.snapshotID = snapshotId;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}/reset`,
+    method: "post",
+    data,
+    operation: "Failed to reset clone",
+    debug
+  });
+}
+async function destroyClone(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/clone/${encodeURIComponent(cloneId)}`,
+    method: "delete",
+    operation: "Failed to destroy clone",
+    debug
   });
-  const text = await response.text();
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    console.error(`Debug: Response body: ${text}`);
-  }
-  if (!response.ok) {
-    throw new Error(formatHttpError(operation, response.status, text));
-  }
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new Error(`${operation}: failed to parse response: ${text}`);
-  }
 }
-async function submitCommand(params) {
-  const { apiKey, apiBaseUrl, command, projectId, sql, args, sessionId, idempotencyKey, debug } = params;
-  if (!JOE_COMMANDS.includes(command)) {
-    throw new Error(`Unknown Joe command: ${command}`);
-  }
-  const body = {
-    project_id: projectId,
-    command,
-    sql: sql ?? null,
-    args: args ?? null,
-    session_id: sessionId ?? null
-  };
-  if (idempotencyKey) {
-    body.idempotency_key = idempotencyKey;
-  }
-  return callRpc({
+async function listBranches(params) {
+  const { apiKey, apiBaseUrl, instanceId, debug } = params;
+  return callDblabApi({
     apiKey,
     apiBaseUrl,
-    fn: "joe_command_submit",
-    body,
-    operation: `Failed to submit ${command} command`,
+    instanceId,
+    action: "/branches",
+    method: "get",
+    operation: "Failed to list branches",
     debug
   });
 }
-async function getCommandStatus(params) {
-  const { apiKey, apiBaseUrl, commandId, debug } = params;
-  if (!commandId) {
-    throw new Error("commandId is required");
-  }
-  return callRpc({
+async function createBranch(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, baseBranch, snapshotId, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  const data = { branchName };
+  if (baseBranch)
+    data.baseBranch = baseBranch;
+  if (snapshotId)
+    data.snapshotID = snapshotId;
+  return callDblabApi({
     apiKey,
     apiBaseUrl,
-    fn: "joe_command_status",
-    body: { command_id: commandId },
-    operation: "Failed to fetch command status",
+    instanceId,
+    action: "/branch",
+    method: "post",
+    data,
+    operation: "Failed to create branch",
     debug
   });
 }
-async function getCommandResult(params) {
-  const { apiKey, apiBaseUrl, commandId, debug } = params;
-  if (!commandId) {
-    throw new Error("commandId is required");
-  }
-  return callRpc({
+async function deleteBranch(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  return callDblabApi({
     apiKey,
     apiBaseUrl,
-    fn: "joe_command_result",
-    body: { command_id: commandId },
-    operation: "Failed to fetch command result",
+    instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}`,
+    method: "delete",
+    operation: "Failed to delete branch",
     debug
   });
 }
-function normalizeProjectRow(row) {
-  const projectId = row.project_id ?? row.id ?? 0;
-  return {
-    project_id: Number(projectId),
-    alias: row.alias ?? null,
-    name: row.name ?? null,
-    label: row.label ?? null,
-    joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
-    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false)
-  };
+async function branchLog(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, debug } = params;
+  if (!branchName)
+    throw new Error("branchName is required");
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: `/branch/${encodeURIComponent(branchName)}/log`,
+    method: "get",
+    operation: "Failed to fetch branch log",
+    debug
+  });
 }
-async function listProjects(params) {
-  const { apiKey, apiBaseUrl, orgId, debug } = params;
-  const body = {};
-  if (typeof orgId === "number") {
-    body.org_id = orgId;
-  }
-  const rows = await callRpc({
+async function listSnapshots(params) {
+  const { apiKey, apiBaseUrl, instanceId, branchName, dataset, debug } = params;
+  const qs = new URLSearchParams;
+  const branch = branchName?.trim();
+  if (branch)
+    qs.append("branch", branch);
+  if (dataset)
+    qs.append("dataset", dataset);
+  const action = `/snapshots${qs.toString() ? `?${qs.toString()}` : ""}`;
+  return callDblabApi({
     apiKey,
     apiBaseUrl,
-    fn: "projects_list",
-    body,
-    operation: "Failed to list projects",
+    instanceId,
+    action,
+    method: "get",
+    operation: "Failed to list snapshots",
     debug
   });
-  if (!Array.isArray(rows)) {
-    return [];
-  }
-  return rows.map(normalizeProjectRow);
 }
-function isNumericProjectRef2(ref) {
-  return /^[0-9]+$/.test(ref.trim());
+async function createSnapshot(params) {
+  const { apiKey, apiBaseUrl, instanceId, cloneId, message, debug } = params;
+  if (!cloneId)
+    throw new Error("cloneId is required");
+  const data = { cloneID: cloneId };
+  if (message)
+    data.message = message;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action: "/branch/snapshot",
+    method: "post",
+    data,
+    operation: "Failed to create snapshot",
+    debug
+  });
+}
+async function destroySnapshot(params) {
+  const { apiKey, apiBaseUrl, instanceId, snapshotId, force, debug } = params;
+  if (!snapshotId)
+    throw new Error("snapshotId is required");
+  const action = `/snapshot/${encodeURIComponent(snapshotId)}?force=${Boolean(force)}`;
+  return callDblabApi({
+    apiKey,
+    apiBaseUrl,
+    instanceId,
+    action,
+    method: "delete",
+    operation: "Failed to destroy snapshot",
+    debug
+  });
+}
+
+// lib/storage.ts
+import * as fs4 from "fs";
+import * as path4 from "path";
+var MAX_UPLOAD_SIZE = 500 * 1024 * 1024;
+var MAX_DOWNLOAD_SIZE = 500 * 1024 * 1024;
+var MIME_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".bmp": "image/bmp",
+  ".ico": "image/x-icon",
+  ".pdf": "application/pdf",
+  ".json": "application/json",
+  ".xml": "application/xml",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar",
+  ".csv": "text/csv",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".sql": "application/sql",
+  ".html": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".ts": "application/typescript",
+  ".md": "text/markdown",
+  ".yaml": "application/x-yaml",
+  ".yml": "application/x-yaml"
+};
+async function uploadFile(params) {
+  const { apiKey, storageBaseUrl, filePath, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!storageBaseUrl) {
+    throw new Error("storageBaseUrl is required");
+  }
+  if (!filePath) {
+    throw new Error("filePath is required");
+  }
+  const resolvedPath = path4.resolve(filePath);
+  if (!fs4.existsSync(resolvedPath)) {
+    throw new Error(`File not found: ${resolvedPath}`);
+  }
+  const stat = fs4.statSync(resolvedPath);
+  if (!stat.isFile()) {
+    throw new Error(`Not a file: ${resolvedPath}`);
+  }
+  if (stat.size > MAX_UPLOAD_SIZE) {
+    throw new Error(`File too large: ${stat.size} bytes (max ${MAX_UPLOAD_SIZE})`);
+  }
+  const base = normalizeBaseUrl(storageBaseUrl);
+  if (new URL(base).protocol === "http:") {
+    console.error("Warning: storage URL uses HTTP — API key will be sent unencrypted");
+  }
+  const url = `${base}/upload`;
+  const fileBuffer = fs4.readFileSync(resolvedPath);
+  const fileName = path4.basename(resolvedPath);
+  const ext = path4.extname(fileName).toLowerCase();
+  const mimeType = MIME_TYPES[ext] || "application/octet-stream";
+  const formData = new FormData;
+  formData.append("file", new Blob([fileBuffer], { type: mimeType }), fileName);
+  const headers = {
+    "access-token": apiKey
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: Storage base URL: ${base}`);
+    console.error(`Debug: POST URL: ${url}`);
+    console.error(`Debug: File: ${resolvedPath} (${stat.size} bytes, ${mimeType})`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: formData
+  });
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(`Failed to parse upload response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to upload file", response.status, data));
+  }
 }
-async function resolveProjectId(params) {
-  const ref = String(params.project ?? "").trim();
-  if (!ref) {
-    throw new Error("project is required (--project <id|alias>)");
+async function downloadFile(params) {
+  const { apiKey, storageBaseUrl, fileUrl, outputPath, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
   }
-  if (isNumericProjectRef2(ref)) {
-    return Number(ref);
+  if (!storageBaseUrl) {
+    throw new Error("storageBaseUrl is required");
   }
-  const projects = await listProjects({
-    apiKey: params.apiKey,
-    apiBaseUrl: params.apiBaseUrl,
-    orgId: params.orgId,
-    debug: params.debug
-  });
-  const needle = ref.toLowerCase();
-  const match = projects.find((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle);
-  if (!match) {
-    throw new Error(`Project not found for alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  if (!fileUrl) {
+    throw new Error("fileUrl is required");
   }
-  return match.project_id;
-}
-function sessionStorePath(dir) {
-  return path4.join(dir ?? getConfigDir2(), "joe-sessions.json");
-}
-function readSessionStore(dir) {
-  const file = sessionStorePath(dir);
-  if (!fs4.existsSync(file)) {
-    return {};
+  const base = normalizeBaseUrl(storageBaseUrl);
+  if (new URL(base).protocol === "http:") {
+    console.error("Warning: storage URL uses HTTP — API key will be sent unencrypted");
   }
-  try {
-    const parsed = JSON.parse(fs4.readFileSync(file, "utf8"));
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed;
+  let fullUrl;
+  if (fileUrl.startsWith("http://") || fileUrl.startsWith("https://")) {
+    if (!fileUrl.startsWith(base + "/")) {
+      throw new Error(`URL must be under storage base URL: ${base}`);
     }
-  } catch {}
-  return {};
-}
-function readStoredSessionId(projectId, dir) {
-  const store = readSessionStore(dir);
-  const value = store[String(projectId)];
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-function writeStoredSessionId(projectId, sessionId, dir) {
-  const baseDir = dir ?? getConfigDir2();
-  if (!fs4.existsSync(baseDir)) {
-    fs4.mkdirSync(baseDir, { recursive: true, mode: 448 });
+    fullUrl = fileUrl;
+  } else {
+    const relativePath = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
+    fullUrl = `${base}${relativePath}`;
   }
-  const store = readSessionStore(dir);
-  store[String(projectId)] = sessionId;
-  fs4.writeFileSync(sessionStorePath(dir), JSON.stringify(store, null, 2) + `
-`, { mode: 384 });
-}
-function clearStoredSessionId(projectId, dir) {
-  const file = sessionStorePath(dir);
-  if (!fs4.existsSync(file)) {
-    return;
+  const urlFilename = path4.basename(new URL(fullUrl).pathname);
+  if (!urlFilename) {
+    throw new Error("Cannot derive filename from URL; please specify --output");
   }
-  const store = readSessionStore(dir);
-  if (String(projectId) in store) {
-    delete store[String(projectId)];
-    fs4.writeFileSync(file, JSON.stringify(store, null, 2) + `
-`, { mode: 384 });
+  const saveTo = outputPath ? path4.resolve(outputPath) : path4.resolve(urlFilename);
+  if (!outputPath) {
+    const normalizedSave = path4.normalize(saveTo);
+    const cwd = path4.normalize(process.cwd());
+    if (normalizedSave !== cwd && !normalizedSave.startsWith(cwd + path4.sep)) {
+      throw new Error("Derived output path escapes current directory; please specify --output");
+    }
+  }
+  const headers = {
+    "access-token": apiKey
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: Storage base URL: ${base}`);
+    console.error(`Debug: GET URL: ${fullUrl}`);
+    console.error(`Debug: Output: ${saveTo}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(fullUrl, {
+    method: "GET",
+    headers
+  });
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  if (!response.ok) {
+    const data = await response.text();
+    throw new Error(formatHttpError("Failed to download file", response.status, data));
+  }
+  const contentLength = response.headers.get("content-length");
+  if (contentLength && parseInt(contentLength, 10) > MAX_DOWNLOAD_SIZE) {
+    throw new Error(`File too large: ${contentLength} bytes (max ${MAX_DOWNLOAD_SIZE})`);
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  const parentDir = path4.dirname(saveTo);
+  if (!fs4.existsSync(parentDir)) {
+    fs4.mkdirSync(parentDir, { recursive: true });
   }
+  fs4.writeFileSync(saveTo, buffer);
+  return {
+    savedTo: saveTo,
+    size: buffer.length,
+    mimeType: response.headers.get("content-type")
+  };
 }
-function computeIdempotencyKey(command, projectId, sql, args) {
-  if (EXECUTING_COMMANDS.has(command)) {
-    const canonical = `${projectId}
-${command}
-${sql ?? ""}
-${JSON.stringify(args ?? null)}`;
-    return `joe-${crypto.createHash("sha256").update(canonical).digest("hex")}`;
+var IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico"]);
+function buildMarkdownLink(fileUrl, storageBaseUrl, filename) {
+  const base = normalizeBaseUrl(storageBaseUrl);
+  const normalizedFileUrl = fileUrl.startsWith("/") ? fileUrl : `/${fileUrl}`;
+  const fullUrl = fileUrl.startsWith("http://") || fileUrl.startsWith("https://") ? fileUrl : `${base}${normalizedFileUrl}`;
+  const name = filename || path4.basename(new URL(fullUrl).pathname);
+  const safeName = name.replace(/[\[\]()]/g, "\\$&");
+  const ext = path4.extname(name).toLowerCase();
+  if (IMAGE_EXTENSIONS.has(ext)) {
+    return `![${safeName}](${fullUrl})`;
   }
-  return `joe-${crypto.randomUUID()}`;
+  return `[${safeName}](${fullUrl})`;
 }
-var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-async function runCommand(params) {
-  const {
-    apiKey,
-    apiBaseUrl,
-    command,
-    projectId,
-    sql,
-    args,
-    sessionId,
-    debug
-  } = params;
-  const budgetMs = params.budgetMs ?? DEFAULT_BUDGET_MS;
-  const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-  const now = params.now ?? Date.now;
-  const sleep = params.sleep ?? defaultSleep;
-  const idempotencyKey = params.idempotencyKey ?? computeIdempotencyKey(command, projectId, sql, args);
-  const submitted = await submitCommand({
-    apiKey,
-    apiBaseUrl,
-    command,
-    projectId,
-    sql,
-    args,
-    sessionId,
-    idempotencyKey,
-    debug
-  });
-  const commandId = submitted.command_id;
-  const newSessionId = submitted.session_id ?? sessionId ?? null;
-  const deadline = now() + budgetMs;
-  let status = submitted.status;
-  while (true) {
-    const statusResp = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug });
-    status = statusResp.status;
-    if (TERMINAL_STATES.has(status)) {
-      break;
-    }
-    if (now() >= deadline) {
-      return { commandId, sessionId: newSessionId, status, result: null, budgetExpired: true };
-    }
-    await sleep(pollIntervalMs);
+async function uploadAttachments(params) {
+  const { apiKey, storageBaseUrl, attachmentPaths, debug } = params;
+  if (!attachmentPaths || attachmentPaths.length === 0) {
+    return [];
   }
-  const result = await getCommandResult({ apiKey, apiBaseUrl, commandId, debug });
-  return { commandId, sessionId: newSessionId, status, result, budgetExpired: false };
+  const out = [];
+  for (const attachmentPath of attachmentPaths) {
+    const result = await uploadFile({
+      apiKey,
+      storageBaseUrl,
+      filePath: attachmentPath,
+      debug
+    });
+    const markdown = buildMarkdownLink(result.url, storageBaseUrl, result.metadata.originalName);
+    out.push({
+      path: attachmentPath,
+      url: result.url,
+      markdown,
+      metadata: result.metadata
+    });
+  }
+  return out;
 }
-async function executeJoeCommand(params) {
-  const projectId = await resolveProjectId({
-    apiKey: params.apiKey,
-    apiBaseUrl: params.apiBaseUrl,
-    project: params.project,
-    orgId: params.orgId,
-    debug: params.debug
-  });
-  let sessionId;
-  if (params.newSession) {
-    clearStoredSessionId(projectId, params.sessionDir);
-    sessionId = null;
-  } else if (params.session) {
-    sessionId = String(params.session);
-  } else {
-    sessionId = readStoredSessionId(projectId, params.sessionDir);
+function appendAttachmentsToContent(content, attachments) {
+  if (!attachments || attachments.length === 0) {
+    return content;
   }
-  const outcome = await runCommand({
-    apiKey: params.apiKey,
-    apiBaseUrl: params.apiBaseUrl,
-    command: params.command,
-    projectId,
-    sql: params.sql,
-    args: params.args,
-    sessionId,
-    budgetMs: params.budgetMs,
-    pollIntervalMs: params.pollIntervalMs,
-    debug: params.debug,
-    now: params.now,
-    sleep: params.sleep
-  });
-  if (outcome.sessionId) {
-    writeStoredSessionId(projectId, outcome.sessionId, params.sessionDir);
+  const links = attachments.map((a) => a.markdown).join(`
+`);
+  if (!content || !content.trim()) {
+    return links;
   }
-  return { ...outcome, command: params.command, projectId };
+  return `${content}
+
+${links}`;
 }
 
 // node_modules/zod/v4/core/core.js
@@ -27070,7 +27050,9 @@ function normalizeProjectRow2(row) {
     name: row.name ?? null,
     label: row.label ?? null,
     joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
-    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false)
+    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
+    instance_id: row.instance_id == null ? null : Number(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : Number(row.dblab_instance_id)
   };
 }
 async function listProjects2(params) {
@@ -27351,50 +27333,28 @@ async function resolveDblabInstanceId2(params) {
   if (!ref) {
     throw new Error("project is required (--project <id|alias>)");
   }
-  const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/dblab_instances`);
-  url.searchParams.set("select", "id,project_id,project_name,project_alias,project_label_or_name,org_id");
-  if (typeof orgId === "number") {
-    url.searchParams.set("org_id", `eq.${orgId}`);
-  }
-  const headers = {
-    "access-token": apiKey,
-    "Content-Type": "application/json",
-    Connection: "close"
-  };
-  if (debug) {
-    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
-    console.error(`Debug: GET URL: ${url.toString()}`);
-    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-  }
-  const response = await fetch(url.toString(), { method: "GET", headers });
-  const text = await response.text();
-  if (debug) {
-    console.error(`Debug: Response status: ${response.status}`);
-    console.error(`Debug: Response body: ${text}`);
-  }
-  if (!response.ok) {
-    throw new Error(formatHttpError("Failed to resolve project's DBLab instance", response.status, text));
-  }
-  let rows;
+  let projects;
   try {
-    const parsed = JSON.parse(text);
-    rows = Array.isArray(parsed) ? parsed : [];
-  } catch {
-    throw new Error(`Failed to parse DBLab instances response: ${text}`);
+    projects = await listProjects({ apiKey, apiBaseUrl, orgId, debug });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to resolve project's DBLab instance: ${message}`);
   }
   const numeric = isNumericProjectRef4(ref);
   const needle = ref.toLowerCase();
-  const match = rows.find((r) => {
+  const match = projects.find((p) => {
     if (numeric) {
-      return String(r.project_id ?? "") === ref;
+      return String(p.project_id) === ref;
     }
-    return r.project_alias != null && String(r.project_alias).toLowerCase() === needle || r.project_name != null && String(r.project_name).toLowerCase() === needle || r.project_label_or_name != null && String(r.project_label_or_name).toLowerCase() === needle;
+    return p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle || p.label !== null && p.label.toLowerCase() === needle;
   });
   if (!match) {
     throw new Error(`No DBLab instance found for project '${ref}'. Run 'pgai projects' to see available projects.`);
   }
-  return String(match.id);
+  if (match.dblab_instance_id == null) {
+    throw new Error(`Project '${ref}' has no active DBLab instance. Register a DBLab instance for it in the Console first.`);
+  }
+  return String(match.dblab_instance_id);
 }
 async function callDblabApi2(params) {
   const { apiKey, apiBaseUrl, instanceId, action, method, data, operation, debug } = params;