planche 0.7.20 → 0.8.1

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { randomUUID as randomUUID3 } from "crypto";
 import { createRequire as createRequire2 } from "module";
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { parseArgs } from "util";
 
 // src/gateway.ts
@@ -234,8 +234,8 @@ function toClientConfig(config) {
 var SEARCH_PATH_STATEMENT = /^\s*SET\s+(SESSION\s+|LOCAL\s+)?search_path\b/i;
 var quoteIdent = (name) => `"${name.replaceAll('"', '""')}"`;
 var PostgresDriver = class {
-  constructor(client, config) {
-    this.client = client;
+  constructor(client2, config) {
+    this.client = client2;
     this.config = config;
     this.label = `${config.user}@${config.host}:${config.port}/${config.database}`;
   }
@@ -346,17 +346,17 @@ var PostgresDriver = class {
 };
 var postgresDriverFactory = {
   async open(config) {
-    const client = new pg.Client(toClientConfig(config));
-    await client.connect();
-    client.on("error", (err) => console.error("[postgres] Connection error:", err.message));
-    const driver = new PostgresDriver(client, config);
+    const client2 = new pg.Client(toClientConfig(config));
+    await client2.connect();
+    client2.on("error", (err) => console.error("[postgres] Connection error:", err.message));
+    const driver = new PostgresDriver(client2, config);
     await driver.loadTypeNames();
     return driver;
   },
   async test(config) {
-    const client = new pg.Client(toClientConfig(config));
-    await client.connect();
-    await client.end();
+    const client2 = new pg.Client(toClientConfig(config));
+    await client2.connect();
+    await client2.end();
   },
   parseConfig(body) {
     const host = typeof body.host === "string" ? body.host.trim() : "";
@@ -653,8 +653,8 @@ var MssqlDriver = class {
    * decide whether it is editable and address rows by primary key.
    */
   async describe(text) {
-    const cached2 = this.sources.get(text);
-    if (cached2 !== void 0) return cached2;
+    const cached4 = this.sources.get(text);
+    if (cached4 !== void 0) return cached4;
     let result = null;
     try {
       const req = this.pool.request();
@@ -811,8 +811,8 @@ var OracleDriver = class {
   }
   async tableColumns(schema, table) {
     const key = `${schema}.${table}`;
-    const cached2 = this.columns.get(key);
-    if (cached2 !== void 0) return cached2;
+    const cached4 = this.columns.get(key);
+    if (cached4 !== void 0) return cached4;
     let out = null;
     try {
       const res = await this.conn.execute(
@@ -1065,8 +1065,8 @@ var D1Driver = class {
     return result;
   }
   async tableColumns(table) {
-    const cached2 = this.columns.get(table);
-    if (cached2 !== void 0) return cached2;
+    const cached4 = this.columns.get(table);
+    if (cached4 !== void 0) return cached4;
     let out = null;
     try {
       const info = await this.raw(`PRAGMA table_info("${table.replaceAll('"', '""')}")`);
@@ -1504,8 +1504,8 @@ var DoDriver = class {
    * like one and as a name otherwise.
    */
   targetFor(database) {
-    const cached2 = this.targets.get(database);
-    if (cached2) return cached2;
+    const cached4 = this.targets.get(database);
+    if (cached4) return cached4;
     const slash = database.indexOf("/");
     if (slash <= 0 || slash === database.length - 1) {
       throw new DoError(
@@ -1519,8 +1519,8 @@ var DoDriver = class {
   }
   async tableColumns(database, target, table) {
     const key = `${database} ${table}`;
-    const cached2 = this.columns.get(key);
-    if (cached2 !== void 0) return cached2;
+    const cached4 = this.columns.get(key);
+    if (cached4 !== void 0) return cached4;
     let out = null;
     try {
       const info = await this.transport.run(target, `PRAGMA table_info("${table.replaceAll('"', '""')}")`);
@@ -1975,7 +1975,7 @@ function describeSshError(err, ssh) {
 }
 async function openSshTunnel(requested, target) {
   const ssh = await resolveConfig(requested);
-  const client = new Client();
+  const client2 = new Client();
   const connectConfig = toConnectConfig(ssh);
   let verifyError;
   connectConfig.hostVerifier = (key, verified) => {
@@ -2005,22 +2005,22 @@ async function openSshTunnel(requested, target) {
     });
   };
   await new Promise((resolve5, reject) => {
-    client.once("ready", resolve5);
-    client.once("error", (err) => reject(verifyError ?? describeSshError(err, ssh)));
+    client2.once("ready", resolve5);
+    client2.once("error", (err) => reject(verifyError ?? describeSshError(err, ssh)));
     try {
-      client.connect(connectConfig);
+      client2.connect(connectConfig);
     } catch (err) {
       reject(describeSshError(err, ssh));
     }
   });
-  client.on("error", (err) => console.error(`[ssh] ${ssh.host}:${ssh.port}: ${err.message}`));
+  client2.on("error", (err) => console.error(`[ssh] ${ssh.host}:${ssh.port}: ${err.message}`));
   const sockets = /* @__PURE__ */ new Set();
   let forwardError;
   const server = createServer((socket) => {
     sockets.add(socket);
     socket.once("close", () => sockets.delete(socket));
     socket.on("error", () => socket.destroy());
-    client.forwardOut(socket.localAddress ?? "127.0.0.1", socket.localPort ?? 0, target.host, target.port, (err, stream) => {
+    client2.forwardOut(socket.localAddress ?? "127.0.0.1", socket.localPort ?? 0, target.host, target.port, (err, stream) => {
       if (err) {
         const local = /^(localhost|127\.0\.0\.1|::1)$/i.test(target.host);
         const hint = local ? `"${target.host}" is resolved on the jump host itself; use the database's real address (e.g. the RDS endpoint) as the database host` : "is the database reachable from the jump host, and does it allow TCP forwarding?";
@@ -2039,7 +2039,7 @@ async function openSshTunnel(requested, target) {
     server.once("error", reject);
     server.listen(0, "127.0.0.1", () => resolve5());
   }).catch((err) => {
-    client.end();
+    client2.end();
     throw new TunnelError(`Could not open local tunnel port: ${err.message}`, 400);
   });
   const { port } = server.address();
@@ -2049,11 +2049,11 @@ async function openSshTunnel(requested, target) {
     closed = true;
     for (const s of sockets) s.destroy();
     server.close(() => {
-      client.end();
+      client2.end();
       resolve5();
     });
   });
-  client.once("close", () => void close());
+  client2.once("close", () => void close());
   return {
     host: "127.0.0.1",
     port,
@@ -2076,11 +2076,11 @@ var PRO_FEATURES = [
   "compare_schemas",
   "compare_data",
   "copy_table",
-  "dry_run",
   "federated",
   "scratchpad",
   "column_link",
-  "sync"
+  "sync",
+  "ai_explain"
 ];
 
 // src/usage.ts
@@ -2203,12 +2203,12 @@ function parseDriverConfig(body) {
   const ssh = parseSshConfig(body.ssh);
   return ssh ? { ...config, ssh } : config;
 }
-async function withTunnel(config, run) {
-  if (isDirectDriver(config) || !config.ssh) return run(config, void 0);
+async function withTunnel(config, run2) {
+  if (isDirectDriver(config) || !config.ssh) return run2(config, void 0);
   const tunnel = await openSshTunnel(config.ssh, { host: config.host, port: config.port });
   recordUsage("ssh_tunnel");
   try {
-    return await run({ ...config, host: tunnel.host, port: tunnel.port, ssh: void 0 }, tunnel);
+    return await run2({ ...config, host: tunnel.host, port: tunnel.port, ssh: void 0 }, tunnel);
   } catch (err) {
     await tunnel.close();
     throw tunnel.forwardError ? new TunnelError(tunnel.forwardError, 400) : err;
@@ -2330,7 +2330,7 @@ function describeProfile(entry) {
 
 // src/index.ts
 import { existsSync as existsSync4 } from "fs";
-import { join as join7, resolve as resolve4 } from "path";
+import { join as join11, resolve as resolve4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/install.ts
@@ -2550,10 +2550,610 @@ async function updateNotice(current) {
   return isNewer(latest, current) ? `planche ${latest} is available (you have ${current}) \u2014 update with: planche upgrade` : null;
 }
 
+// src/ai-cli.ts
+import { execFile as execFileCb2, spawn } from "child_process";
+import { mkdtemp, readFile as readFile5, rm, writeFile as writeFile3 } from "fs/promises";
+import { tmpdir } from "os";
+import { join as join8 } from "path";
+import { promisify as promisify2 } from "util";
+
+// src/ai-config.ts
+import { chmod, mkdir as mkdir3, readFile as readFile4, rename as rename2, unlink, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir7 } from "os";
+import { join as join7 } from "path";
+
+// ../shared/ai.ts
+var AI_DEFAULT_MODEL = {
+  // Anthropic's most capable general model. Explaining a failure is the paid
+  // half of the product, so the default is not chosen to be cheap.
+  anthropic: "claude-opus-5",
+  // Same API, same models; only where the credential comes from differs.
+  "anthropic-profile": "claude-opus-5",
+  openai: "gpt-4o",
+  gemini: "gemini-2.5-flash",
+  // Not a model but the command to run: the CLI decides the model itself.
+  cli: "claude"
+};
+
+// src/ai-anthropic.ts
+import { execFile as execFileCb } from "child_process";
+import { access } from "fs/promises";
+import { homedir as homedir6 } from "os";
+import { join as join6 } from "path";
+import { promisify } from "util";
+import Anthropic from "@anthropic-ai/sdk";
+function toMessages(turns) {
+  const out = [];
+  for (const turn of turns) {
+    if (turn.role === "user") {
+      out.push({ role: "user", content: turn.content });
+      continue;
+    }
+    if (turn.role === "assistant") {
+      const blocks = [];
+      if (turn.content.trim()) blocks.push({ type: "text", text: turn.content });
+      for (const call of turn.toolCalls ?? []) {
+        blocks.push({ type: "tool_use", id: call.id, name: call.name, input: call.input });
+      }
+      if (blocks.length > 0) out.push({ role: "assistant", content: blocks });
+      continue;
+    }
+    const result = {
+      type: "tool_result",
+      tool_use_id: turn.toolCallId,
+      content: turn.content,
+      ...turn.isError ? { is_error: true } : {}
+    };
+    const last = out[out.length - 1];
+    if (last && last.role === "user" && Array.isArray(last.content)) {
+      last.content.push(result);
+    } else {
+      out.push({ role: "user", content: [result] });
+    }
+  }
+  return out;
+}
+var execFile = promisify(execFileCb);
+async function anthropicProfileAvailable() {
+  try {
+    await execFile("ant", ["auth", "status"], { timeout: 1e4 });
+    return true;
+  } catch {
+    try {
+      await access(join6(homedir6(), ".config", "anthropic"));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+async function runAnthropic(config, req) {
+  const client2 = new Anthropic({
+    ...config.key ? { apiKey: config.key } : {},
+    ...config.baseUrl ? { baseURL: config.baseUrl } : {}
+  });
+  const tools2 = (req.tools ?? []).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema
+  }));
+  try {
+    const response = await client2.messages.create({
+      model: config.model,
+      max_tokens: MAX_TOKENS,
+      system: req.system,
+      messages: toMessages(turnsOf(req)),
+      ...tools2.length > 0 ? { tools: tools2 } : {}
+    });
+    const text = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+    const toolCalls = response.content.filter((block) => block.type === "tool_use").map((block) => ({ id: block.id, name: block.name, input: block.input ?? {} }));
+    if (!text && toolCalls.length === 0) throw new AiError(502, "The model returned nothing.");
+    return {
+      text,
+      toolCalls,
+      stop: response.stop_reason === "tool_use" ? "tool_use" : response.stop_reason === "max_tokens" ? "length" : "end"
+    };
+  } catch (err) {
+    if (err instanceof AiError) throw err;
+    const noCredential = 'This machine has no Anthropic credential the SDK could use. Run "ant auth login", or set a key instead.';
+    if (err instanceof Anthropic.AuthenticationError) {
+      throw new AiError(401, config.key ? "The AI key was rejected." : noCredential);
+    }
+    if (!config.key && err instanceof Error && /resolve authentication/i.test(err.message)) {
+      throw new AiError(401, noCredential);
+    }
+    if (err instanceof Anthropic.RateLimitError) throw new AiError(429, "The provider is rate limiting this key.");
+    if (err instanceof Anthropic.BadRequestError) throw new AiError(400, err.message);
+    if (err instanceof Anthropic.APIError) throw new AiError(502, `The provider answered ${err.status}: ${err.message}`);
+    throw new AiError(502, err instanceof Error ? err.message : String(err));
+  }
+}
+
+// src/ai-config.ts
+var PLANCHE_DIR4 = join7(homedir7(), ".planche");
+var AI_FILE = join7(PLANCHE_DIR4, "ai.json");
+function envConfig() {
+  const key = process.env.PLANCHE_AI_KEY?.trim() || process.env.ANTHROPIC_API_KEY?.trim() || process.env.OPENAI_API_KEY?.trim() || process.env.GEMINI_API_KEY?.trim();
+  if (!key) return null;
+  const named = process.env.PLANCHE_AI_PROVIDER?.trim();
+  const provider = named === "openai" || named === "anthropic" || named === "gemini" || named === "cli" || named === "anthropic-profile" ? named : process.env.GEMINI_API_KEY?.trim() ? "gemini" : process.env.OPENAI_API_KEY?.trim() && !process.env.ANTHROPIC_API_KEY?.trim() ? "openai" : "anthropic";
+  return {
+    provider,
+    model: process.env.PLANCHE_AI_MODEL?.trim() || AI_DEFAULT_MODEL[provider],
+    baseUrl: process.env.PLANCHE_AI_BASE_URL?.trim() || void 0,
+    key
+  };
+}
+var session = null;
+var cached2;
+async function fileConfig() {
+  if (cached2 !== void 0) return cached2;
+  try {
+    const raw = JSON.parse(await readFile4(AI_FILE, "utf8"));
+    const provider = raw.provider === "openai" || raw.provider === "gemini" ? raw.provider : "anthropic";
+    cached2 = typeof raw.key === "string" && raw.key ? {
+      provider,
+      model: typeof raw.model === "string" && raw.model ? raw.model : AI_DEFAULT_MODEL[provider],
+      baseUrl: typeof raw.baseUrl === "string" && raw.baseUrl ? raw.baseUrl : void 0,
+      key: raw.key
+    } : null;
+  } catch {
+    cached2 = null;
+  }
+  return cached2;
+}
+async function aiConfig() {
+  return envConfig() ?? session ?? await fileConfig();
+}
+async function aiConfigView() {
+  const env = envConfig();
+  const file = env ? null : await fileConfig();
+  const config = env ?? session ?? file;
+  const storage = env ? "environment" : session ? "session" : file ? "file" : "none";
+  return {
+    configured: config !== null,
+    provider: config?.provider ?? "anthropic",
+    model: config?.model ?? AI_DEFAULT_MODEL.anthropic,
+    baseUrl: config?.baseUrl,
+    fromEnvironment: env !== null,
+    storage,
+    path: AI_FILE,
+    clis: await installedClis(),
+    anthropicProfile: await anthropicProfileAvailable()
+  };
+}
+function defaultModelFor(provider) {
+  return AI_DEFAULT_MODEL[provider];
+}
+async function saveAiConfig(config, remember) {
+  if (!remember) {
+    session = config;
+    await forgetStoredConfig();
+    return false;
+  }
+  session = null;
+  await mkdir3(PLANCHE_DIR4, { recursive: true });
+  const temp = `${AI_FILE}.${process.pid}.tmp`;
+  await writeFile2(temp, JSON.stringify(config, null, 2), { mode: 384 });
+  await chmod(temp, 384);
+  await rename2(temp, AI_FILE);
+  cached2 = config;
+  return true;
+}
+async function forgetStoredConfig() {
+  cached2 = null;
+  try {
+    await unlink(AI_FILE);
+  } catch {
+  }
+}
+async function forgetAiConfig() {
+  session = null;
+  await forgetStoredConfig();
+}
+var aiConfigPath = AI_FILE;
+
+// src/ai-gemini.ts
+var DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta";
+function toContents(turns) {
+  const out = [];
+  for (const turn of turns) {
+    if (turn.role === "user") {
+      out.push({ role: "user", parts: [{ text: turn.content }] });
+    } else if (turn.role === "assistant") {
+      const parts = [];
+      if (turn.content.trim()) parts.push({ text: turn.content });
+      for (const call of turn.toolCalls ?? []) parts.push({ functionCall: { name: call.name, args: call.input } });
+      if (parts.length > 0) out.push({ role: "model", parts });
+    } else {
+      const part = {
+        functionResponse: { name: turn.toolCallId, response: { result: turn.content, ...turn.isError ? { error: true } : {} } }
+      };
+      const last = out[out.length - 1];
+      if (last && last.role === "user" && last.parts.every((p) => p.functionResponse)) last.parts.push(part);
+      else out.push({ role: "user", parts: [part] });
+    }
+  }
+  return out;
+}
+async function runGemini(config, req) {
+  const base = (config.baseUrl || DEFAULT_BASE).replace(/\/+$/, "");
+  const url = `${base}/models/${encodeURIComponent(config.model)}:generateContent?key=${encodeURIComponent(config.key)}`;
+  const tools2 = req.tools ?? [];
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        systemInstruction: { parts: [{ text: req.system }] },
+        contents: toContents(turnsOf(req)),
+        ...tools2.length > 0 ? {
+          tools: [
+            {
+              functionDeclarations: tools2.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.inputSchema
+              }))
+            }
+          ]
+        } : {},
+        generationConfig: {
+          // A JSON mime type and function calling cannot both be asked for.
+          ...tools2.length > 0 ? {} : { responseMimeType: "application/json" },
+          maxOutputTokens: MAX_TOKENS
+        }
+      })
+    });
+  } catch (err) {
+    throw new AiError(502, err instanceof Error ? err.message : String(err));
+  }
+  const data = await response.json().catch(() => null);
+  if (!response.ok) {
+    const message = data?.error?.message ?? `${response.status} ${response.statusText}`;
+    if (response.status === 400 || response.status === 401 || response.status === 403) {
+      throw new AiError(401, `The AI key was rejected: ${message}`);
+    }
+    if (response.status === 429) throw new AiError(429, "The provider is rate limiting this key.");
+    throw new AiError(502, `The provider answered ${response.status}: ${message}`);
+  }
+  const candidate = data?.candidates?.[0];
+  const parts = candidate?.content?.parts ?? [];
+  const text = parts.map((p) => p.text ?? "").join("");
+  const toolCalls = parts.filter((p) => typeof p.functionCall?.name === "string").map((p) => ({ id: p.functionCall.name, name: p.functionCall.name, input: p.functionCall.args ?? {} }));
+  if (!text && toolCalls.length === 0) throw new AiError(502, "The model returned nothing.");
+  return {
+    text,
+    toolCalls,
+    stop: toolCalls.length > 0 ? "tool_use" : candidate?.finishReason === "MAX_TOKENS" ? "length" : "end"
+  };
+}
+
+// src/ai-openai.ts
+import OpenAI from "openai";
+function toMessages2(system, turns) {
+  const out = [{ role: "system", content: system }];
+  for (const turn of turns) {
+    if (turn.role === "user") {
+      out.push({ role: "user", content: turn.content });
+    } else if (turn.role === "assistant") {
+      const calls = turn.toolCalls ?? [];
+      out.push({
+        role: "assistant",
+        content: turn.content || null,
+        ...calls.length > 0 ? {
+          tool_calls: calls.map((call) => ({
+            id: call.id,
+            type: "function",
+            function: { name: call.name, arguments: JSON.stringify(call.input) }
+          }))
+        } : {}
+      });
+    } else {
+      out.push({ role: "tool", tool_call_id: turn.toolCallId, content: turn.content });
+    }
+  }
+  return out;
+}
+function parseArguments(raw) {
+  try {
+    const parsed = JSON.parse(raw || "{}");
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function runOpenAI(config, req) {
+  const client2 = new OpenAI({ apiKey: config.key, ...config.baseUrl ? { baseURL: config.baseUrl } : {} });
+  const tools2 = (req.tools ?? []).map((tool) => ({
+    type: "function",
+    function: { name: tool.name, description: tool.description, parameters: tool.inputSchema }
+  }));
+  try {
+    const response = await client2.chat.completions.create({
+      model: config.model,
+      max_completion_tokens: MAX_TOKENS,
+      // JSON mode and tools are mutually exclusive here: forcing a JSON object
+      // leaves the model no way to answer with a call. The one-shot prompts
+      // ask for JSON, a tool run does not.
+      ...tools2.length > 0 ? { tools: tools2 } : { response_format: { type: "json_object" } },
+      messages: toMessages2(req.system, turnsOf(req))
+    });
+    const choice = response.choices[0];
+    const text = choice?.message?.content ?? "";
+    const toolCalls = (choice?.message?.tool_calls ?? []).filter((call) => call.type === "function").map((call) => ({ id: call.id, name: call.function.name, input: parseArguments(call.function.arguments) }));
+    if (!text && toolCalls.length === 0) throw new AiError(502, "The model returned nothing.");
+    return {
+      text,
+      toolCalls,
+      stop: choice?.finish_reason === "tool_calls" ? "tool_use" : choice?.finish_reason === "length" ? "length" : "end"
+    };
+  } catch (err) {
+    if (err instanceof AiError) throw err;
+    if (err instanceof OpenAI.APIError) {
+      const status = err.status === 401 || err.status === 429 || err.status === 400 ? err.status : 502;
+      throw new AiError(status, err.status === 401 ? "The AI key was rejected." : err.message);
+    }
+    throw new AiError(502, err instanceof Error ? err.message : String(err));
+  }
+}
+
+// src/ai-run.ts
+var AiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AiError";
+  }
+  status;
+};
+var MAX_TOKENS = 8e3;
+function turnsOf(req) {
+  if (req.messages && req.messages.length > 0) return req.messages;
+  return [{ role: "user", content: req.user ?? "" }];
+}
+async function runPrompt(req) {
+  const config = await aiConfig();
+  if (!config) throw new AiError(501, "No AI key is configured on this agent.");
+  const model = req.model?.trim() || config.model;
+  const run2 = config.provider === "cli" ? runCli : config.provider === "openai" ? runOpenAI : config.provider === "gemini" ? runGemini : runAnthropic;
+  const result = await run2({ ...config, model }, req);
+  return {
+    success: true,
+    text: result.text,
+    model,
+    ...result.toolCalls.length > 0 ? { toolCalls: result.toolCalls } : {},
+    stop: result.stop
+  };
+}
+
+// src/ai-cli.ts
+var execFile2 = promisify2(execFileCb2);
+var CLI_COMMANDS = ["claude", "codex"];
+var TIMEOUT_MS = 18e4;
+var mcp = null;
+function configureCliBridge(url, token) {
+  mcp = { url, token };
+}
+function mcpUrl() {
+  return mcp?.url ?? null;
+}
+function isCliCommand(name) {
+  return CLI_COMMANDS.includes(name);
+}
+async function installedClis() {
+  const found = [];
+  for (const name of CLI_COMMANDS) {
+    try {
+      await execFile2(name, ["--version"], { timeout: 1e4 });
+      found.push(name);
+    } catch {
+    }
+  }
+  return found;
+}
+function run(command, args, prompt) {
+  return new Promise((resolve5, reject) => {
+    const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let out = "";
+    let err = "";
+    const timer2 = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new AiError(504, `${command} did not answer within ${TIMEOUT_MS / 1e3}s.`));
+    }, TIMEOUT_MS);
+    child.stdout.on("data", (d) => out += d);
+    child.stderr.on("data", (d) => err += d);
+    child.on("error", (e) => {
+      clearTimeout(timer2);
+      reject(new AiError(501, `${command} could not be started: ${e.message}`));
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer2);
+      if (code === 0) resolve5(out);
+      else reject(new AiError(502, `${command} exited ${code}: ${err.trim().slice(0, 400) || "no output"}`));
+    });
+    child.stdin.end(prompt);
+  });
+}
+function unwrap(text) {
+  const fenced = text.trim().match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
+  return (fenced ? fenced[1] : text).trim();
+}
+async function runCli(config, req) {
+  const command = config.model.trim();
+  const wantsTools = (req.tools?.length ?? 0) > 0;
+  if (wantsTools && command !== "claude") {
+    throw new AiError(400, `${command} cannot be given Planche's tools. Use the claude CLI for the AI panel, or a provider with an API key.`);
+  }
+  if (wantsTools && !mcp) {
+    throw new AiError(501, "This agent cannot offer its tools to a CLI. Restart it, or use a provider with an API key.");
+  }
+  if (!isCliCommand(command)) {
+    throw new AiError(400, `Unknown CLI "${command}". Use one of: ${CLI_COMMANDS.join(", ")}.`);
+  }
+  const turns = turnsOf(req);
+  const prompt = [req.system, "", turns.map((t) => "content" in t ? t.content : "").join("\n\n")].join("\n");
+  let text;
+  if (command === "claude") {
+    if (!wantsTools) {
+      text = await run("claude", ["-p"], prompt);
+    } else {
+      const dir = await mkdtemp(join8(tmpdir(), "planche-mcp-"));
+      const file = join8(dir, "mcp.json");
+      try {
+        await writeFile3(
+          file,
+          JSON.stringify({
+            mcpServers: {
+              planche: { type: "http", url: mcp.url, headers: { Authorization: `Bearer ${mcp.token}` } }
+            }
+          }),
+          { mode: 384 }
+        );
+        text = await run("claude", ["-p", "--strict-mcp-config", "--mcp-config", file], prompt);
+      } finally {
+        await rm(dir, { recursive: true, force: true });
+      }
+    }
+  } else {
+    const dir = await mkdtemp(join8(tmpdir(), "planche-cli-"));
+    const file = join8(dir, "answer.txt");
+    try {
+      await run("codex", ["exec", "--skip-git-repo-check", "-o", file, "-"], prompt);
+      text = await readFile5(file, "utf8");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+  const answer = unwrap(text);
+  if (!answer) throw new AiError(502, `${command} returned nothing.`);
+  return { text: answer, toolCalls: [], stop: "end" };
+}
+
+// src/mcp-token.ts
+import { chmod as chmod2, mkdir as mkdir4, readFile as readFile6, rm as rm2, writeFile as writeFile4 } from "fs/promises";
+import { randomBytes } from "crypto";
+import { homedir as homedir8 } from "os";
+import { join as join9 } from "path";
+var DIR = join9(homedir8(), ".planche");
+var FILE = join9(DIR, "mcp-token");
+var mcpTokenPath = FILE;
+var cached3 = null;
+async function readMcpToken() {
+  if (cached3) return cached3;
+  try {
+    const text = (await readFile6(FILE, "utf8")).trim();
+    cached3 = text || null;
+  } catch {
+    cached3 = null;
+  }
+  return cached3;
+}
+async function ensureMcpToken() {
+  const existing = await readMcpToken();
+  if (existing) return existing;
+  const token = randomBytes(32).toString("base64url");
+  await mkdir4(DIR, { recursive: true, mode: 448 });
+  await writeFile4(FILE, `${token}
+`, { mode: 384 });
+  await chmod2(FILE, 384);
+  cached3 = token;
+  return token;
+}
+async function forgetMcpToken() {
+  cached3 = null;
+  await rm2(FILE, { force: true });
+}
+
 // src/server.ts
 import express from "express";
 import { createHash as createHash2, randomUUID as randomUUID2, timingSafeEqual as timingSafeEqual2 } from "crypto";
 
+// src/bridge.ts
+var CALL_TIMEOUT_MS = 12e4;
+var client = null;
+var tools = [];
+var pending = /* @__PURE__ */ new Map();
+var nextId = 0;
+function bridgeTools() {
+  return tools;
+}
+function attachBridge(res) {
+  client?.end();
+  client = res;
+  res.on("close", () => {
+    if (client !== res) return;
+    client = null;
+    tools = [];
+  });
+}
+function setBridgeTools(next) {
+  tools = next;
+}
+function callThroughBridge(name, input) {
+  const target = client;
+  if (!target) {
+    return Promise.resolve({ content: "Planche is not open in a browser, so its tools cannot run.", isError: true });
+  }
+  const id = `call-${++nextId}`;
+  return new Promise((resolve5) => {
+    const timer2 = setTimeout(() => {
+      pending.delete(id);
+      resolve5({ content: `The app did not answer "${name}" within ${CALL_TIMEOUT_MS / 1e3}s.`, isError: true });
+    }, CALL_TIMEOUT_MS);
+    pending.set(id, { resolve: resolve5, timer: timer2 });
+    target.write(`data: ${JSON.stringify({ id, name, input })}
+
+`);
+  });
+}
+function resolveBridgeCall(id, content, isError) {
+  const waiting = pending.get(id);
+  if (!waiting) return;
+  pending.delete(id);
+  clearTimeout(waiting.timer);
+  waiting.resolve({ content, isError });
+}
+
+// src/mcp.ts
+var FALLBACK_PROTOCOL = "2025-06-18";
+async function handleMcp(req, res) {
+  const msg = req.body ?? {};
+  const reply = (result) => res.json({ jsonrpc: "2.0", id: msg.id, result });
+  switch (msg.method) {
+    case "initialize":
+      reply({
+        protocolVersion: typeof msg.params?.protocolVersion === "string" ? msg.params.protocolVersion : FALLBACK_PROTOCOL,
+        capabilities: { tools: {} },
+        serverInfo: { name: "planche", version: "1" }
+      });
+      return;
+    case "tools/list":
+      reply({
+        tools: bridgeTools().map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema
+        }))
+      });
+      return;
+    case "tools/call": {
+      const name = typeof msg.params?.name === "string" ? msg.params.name : "";
+      const args = msg.params?.arguments ?? {};
+      const { content, isError } = await callThroughBridge(name, args);
+      reply({ content: [{ type: "text", text: content }], isError });
+      return;
+    }
+    default:
+      if (msg.id === void 0) {
+        res.status(202).end();
+        return;
+      }
+      reply({});
+  }
+}
+
 // src/tunneling.ts
 import { randomUUID } from "crypto";
 
@@ -2844,7 +3444,7 @@ var ConnectionManager = class {
 
 // src/server.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { join as join6 } from "path";
+import { join as join10 } from "path";
 function errorStatus(err) {
   const status = err?.status;
   return typeof status === "number" && status >= 400 && status < 600 ? status : 400;
@@ -2910,7 +3510,7 @@ function accessControl(allowed) {
     }
     res.setHeader("Access-Control-Allow-Origin", origin);
     res.setHeader("Vary", "Origin");
-    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
     res.setHeader("Access-Control-Max-Age", "600");
     if (req.headers["access-control-request-private-network"] === "true") {
@@ -2982,7 +3582,7 @@ function createAgent(options) {
     options.onUnpaired(pairing, origin);
     return true;
   }
-  app.get("/health", (req, res) => {
+  app.get("/health", async (req, res) => {
     const body = {
       success: true,
       name: "planche",
@@ -2991,6 +3591,8 @@ function createAgent(options) {
       activeConnections: manager.activeConnections,
       uptime: process.uptime()
     };
+    const ai = await aiConfigView();
+    body.ai = { configured: ai.configured, model: ai.model, tools: true };
     if (options.install) body.install = options.install;
     if (options.gateway) body.gateway = { name: options.gateway.name, profiles: options.gateway.profiles.length };
     if (req.headers.authorization !== void 0) {
@@ -3015,16 +3617,29 @@ function createAgent(options) {
     const body = { success: true, token: options.authToken };
     res.json(body);
   });
+  async function mcpAuthorized(req) {
+    if (req.path !== "/mcp") return false;
+    const given = bearerOf(req.headers.authorization);
+    const expected = await readMcpToken();
+    if (!given || !expected) return false;
+    return secretEquals(given, expected);
+  }
   app.use((req, res, next) => {
     if (throttle.locked(peerOf(req))) {
       fail(res, 429, "Too many failed authentication attempts; try again shortly");
       return;
     }
-    if (!authorized(req)) {
-      fail(res, 401, "Unauthorized: invalid or missing auth token");
+    if (authorized(req)) {
+      next();
       return;
     }
-    next();
+    void mcpAuthorized(req).then((ok) => {
+      if (ok) {
+        next();
+        return;
+      }
+      fail(res, 401, "Unauthorized: invalid or missing auth token");
+    });
   });
   app.use(express.json({ limit: options.bodyLimit }));
   app.get("/profiles", (_req, res) => {
@@ -3098,6 +3713,114 @@ function createAgent(options) {
     await flushUsage();
     res.json(await usageSnapshot());
   });
+  app.get("/ai/config", async (_req, res) => {
+    res.json({ success: true, ...await aiConfigView() });
+  });
+  app.put("/ai/config", async (req, res) => {
+    const current = await aiConfigView();
+    if (current.fromEnvironment) {
+      fail(res, 409, "This agent's AI settings come from its environment and cannot be changed from the app.");
+      return;
+    }
+    const body = req.body ?? {};
+    const provider = body.provider === "openai" || body.provider === "gemini" || body.provider === "cli" || body.provider === "anthropic-profile" ? body.provider : "anthropic";
+    const keyless = provider === "cli" || provider === "anthropic-profile";
+    const key = typeof body.key === "string" ? body.key.trim() : "";
+    if (!key && !keyless) {
+      fail(res, 400, "key is required");
+      return;
+    }
+    const model = typeof body.model === "string" && body.model.trim() ? body.model.trim() : defaultModelFor(provider);
+    if (provider === "cli" && !isCliCommand(model)) {
+      fail(res, 400, `model must name an installed CLI: ${CLI_COMMANDS.join(", ")}`);
+      return;
+    }
+    const baseUrl = typeof body.baseUrl === "string" ? body.baseUrl.trim() : "";
+    if (baseUrl && !/^https?:\/\//i.test(baseUrl)) {
+      fail(res, 400, "baseUrl must be an http(s) URL");
+      return;
+    }
+    const written = await saveAiConfig({
+      provider,
+      model,
+      baseUrl: baseUrl || void 0,
+      key
+    }, body.remember === true);
+    console.log(
+      provider === "cli" ? `[agent] AI answers will come from the local "${model}" CLI; no key is held.` : provider === "anthropic-profile" ? "[agent] AI answers will use this machine's own Anthropic credential; no key is held." : written ? `[agent] AI key saved to ${aiConfigPath} (owner-only). Remove it with "Forget key" in Settings, or by deleting that file.` : "[agent] AI key accepted for this session only; it is not written to disk."
+    );
+    res.json({ success: true, ...await aiConfigView() });
+  });
+  app.delete("/ai/config", async (_req, res) => {
+    await forgetAiConfig();
+    res.json({ success: true, ...await aiConfigView() });
+  });
+  app.post("/ai/run", async (req, res) => {
+    const body = req.body ?? {};
+    const hasTurns = Array.isArray(body.messages) && body.messages.length > 0;
+    const hasUser = typeof body.user === "string" && body.user.trim() !== "";
+    if (typeof body.system !== "string" || !hasTurns && !hasUser) {
+      fail(res, 400, "system and one of user/messages are required");
+      return;
+    }
+    try {
+      res.json(await runPrompt({
+        system: body.system,
+        ...hasUser ? { user: body.user } : {},
+        ...hasTurns ? { messages: body.messages } : {},
+        ...Array.isArray(body.tools) && body.tools.length > 0 ? { tools: body.tools } : {},
+        model: typeof body.model === "string" ? body.model : void 0
+      }));
+    } catch (err) {
+      const e = err instanceof AiError ? err : new AiError(502, String(err));
+      fail(res, e.status, e.message);
+    }
+  });
+  app.post("/mcp", async (req, res) => {
+    await handleMcp(req, res);
+  });
+  app.get("/bridge/events", (req, res) => {
+    res.writeHead(200, {
+      "content-type": "text/event-stream",
+      "cache-control": "no-store",
+      connection: "keep-alive"
+    });
+    res.write(": open\n\n");
+    attachBridge(res);
+  });
+  app.post("/bridge/tools", (req, res) => {
+    const tools2 = req.body?.tools;
+    if (!Array.isArray(tools2)) {
+      fail(res, 400, "tools must be an array");
+      return;
+    }
+    setBridgeTools(tools2);
+    res.json({ success: true });
+  });
+  app.post("/bridge/result", (req, res) => {
+    const { id, content, isError } = req.body ?? {};
+    if (typeof id !== "string") {
+      fail(res, 400, "id is required");
+      return;
+    }
+    resolveBridgeCall(id, typeof content === "string" ? content : "", isError === true);
+    res.json({ success: true });
+  });
+  app.post("/mcp/setup", async (_req, res) => {
+    const url = mcpUrl();
+    if (!url) {
+      fail(res, 503, "The agent is not listening yet.");
+      return;
+    }
+    const body = { success: true, url, token: await ensureMcpToken(), path: mcpTokenPath };
+    console.log(`[agent] MCP token handed to the app; stored at ${mcpTokenPath} (owner-only).`);
+    res.json(body);
+  });
+  app.delete("/mcp/setup", async (_req, res) => {
+    await forgetMcpToken();
+    console.log(`[agent] MCP token revoked; ${mcpTokenPath} removed.`);
+    res.json({ success: true });
+  });
   app.post("/cancel", async (req, res) => {
     try {
       const connectionId = req.body?.connectionId;
@@ -3171,7 +3894,7 @@ function serveApp(app, appDir) {
     "form-action 'none'",
     "frame-ancestors 'none'"
   ].join("; ");
-  const indexFile = join6(appDir, "index.html");
+  const indexFile = join10(appDir, "index.html");
   const indexHtml = existsSync3(indexFile) ? readFileSync3(indexFile, "utf8").replace("<head>", '<head>\n    <meta name="planche-agent" content="same-origin" />') : null;
   const headers = (res) => {
     res.setHeader("Content-Security-Policy", csp);
@@ -3207,7 +3930,7 @@ var DEV_ORIGINS = [
 ];
 function bundledAppDir() {
   const dir = fileURLToPath2(new URL("../app/", import.meta.url));
-  return existsSync4(join7(dir, "index.html")) ? dir : null;
+  return existsSync4(join11(dir, "index.html")) ? dir : null;
 }
 function isLoopbackUrl(url) {
   try {
@@ -3230,7 +3953,7 @@ async function appIsReachable(url, timeoutMs = 2500) {
 }
 function resolveAppDir(explicit) {
   const dir = explicit ? resolve4(explicit) : fileURLToPath2(new URL("../app/", import.meta.url));
-  if (!existsSync4(join7(dir, "index.html"))) {
+  if (!existsSync4(join11(dir, "index.html"))) {
     console.error(explicit ? `--app-dir has no index.html: ${dir}` : `This build does not include the web app (${dir}). Install the published package, or pass --app-dir <dir>.`);
     process.exit(2);
   }
@@ -3242,6 +3965,7 @@ function usage() {
 Usage: planche [options]
        planche upgrade [version]   Update a standalone install in place
        planche uninstall [--yes]   Remove it again (settings in ~/.planche are kept)
+       planche mcp [setup|forget]  Print the MCP client configuration, or revoke its token
 
 Options:
   -p, --port <n>       Port to listen on (default: 8888, env PLANCHE_PORT)
@@ -3284,10 +4008,36 @@ function openInBrowser(url) {
   try {
     const env = { ...process.env };
     delete env.PLANCHE_AUTH_TOKEN;
-    spawn(cmd, args, { stdio: "ignore", detached: true, env }).on("error", () => void 0).unref();
+    spawn2(cmd, args, { stdio: "ignore", detached: true, env }).on("error", () => void 0).unref();
   } catch {
   }
 }
+async function runMcpCommand(action, port) {
+  if (action === "forget") {
+    await forgetMcpToken();
+    console.log(`Removed ${mcpTokenPath}. Any client configured with it now gets 401.`);
+    return 0;
+  }
+  if (action !== void 0 && action !== "setup") {
+    console.error("Usage: planche mcp [setup|forget]");
+    return 1;
+  }
+  const token = await ensureMcpToken();
+  const url = `http://127.0.0.1:${port}/mcp`;
+  console.log("Add Planche to an agent that speaks MCP over HTTP:\n");
+  console.log(`  claude mcp add --transport http planche ${url} \\
+    -H "Authorization: Bearer ${token}"
+`);
+  console.log("Or as JSON:\n");
+  console.log(`  ${JSON.stringify({ mcpServers: { planche: { type: "http", url, headers: { Authorization: `Bearer ${token}` } } } })}
+`);
+  console.log(`The token is stored at ${mcpTokenPath} (owner-only) and survives restarts, unlike the`);
+  console.log("agent's own token. It reaches this one route and nothing else: calls run inside the");
+  console.log("open browser tab, under its guard rails, and every write stops there for approval.");
+  console.log("Planche must be open with the AI panel showing, or there are no tools to call.");
+  console.log(`Revoke it with "planche mcp forget".`);
+  return 0;
+}
 async function main() {
   const [subcommand] = process.argv.slice(2);
   if (subcommand === "upgrade") {
@@ -3296,6 +4046,9 @@ async function main() {
   if (subcommand === "uninstall") {
     process.exit(await runUninstall(process.argv.includes("--yes") || process.argv.includes("-y")));
   }
+  if (subcommand === "mcp") {
+    process.exit(await runMcpCommand(process.argv[3], Number(process.env.PLANCHE_PORT ?? 8888)));
+  }
   const major = Number(process.versions.node.split(".")[0]);
   if (major < 22) {
     console.error(`planche needs Node.js 22 or newer (you are running ${process.version}).`);
@@ -3432,6 +4185,7 @@ async function main() {
     console.log(`${DEFAULT_APP_URL === hostedAppUrl ? "planche.dev" : hostedAppUrl} is unreachable \u2014 serving the app bundled with this agent (v${VERSION}) instead.`);
   }
   const server = app.listen(port, listenAddr, () => {
+    configureCliBridge(`http://127.0.0.1:${port}/mcp`, authToken);
     console.log(divider);
     console.log(`Planche agent ${VERSION} listening on ${agentUrl}`);
     console.log(divider);