@chatpanel/bridge 0.10.29 → 0.10.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/bridge",
-  "version": "0.10.29",
+  "version": "0.10.30",
   "type": "module",
   "description": "Local bridge that exposes the AI coding agents installed on your machine \u2014 Claude Code (CLI), Codex (CLI), and Antigravity CLI (formerly Gemini CLI, which remains available for business/enterprise) \u2014 to the ChatPanel Chrome extension over a localhost SSE endpoint. Bring your own agent.",
   "keywords": [

package/src/engines/antigravity.js

@@ -18,9 +18,9 @@ import { findAgentBin } from '../env.js';
 import { buildCliPrompt } from './prompt.js';
 import { killOnAbort, spawnGroupOpts } from '../proc.js';
 import { pushExtraArgs, FORBIDDEN } from './args.js';
+import { resolveWorkdir } from '../workdir.js';
 
 const IDLE_MS = Number(process.env.CHATPANEL_AGY_TIMEOUT_MS) || 180_000;
-const SCRATCH = path.join(os.tmpdir(), 'chatpanel-agy-scratch');
 
 // `agy models` lists available models. Parse ids best-effort; free text is still
 // accepted by the picker, and [] just means "type a model or use the default".
@@ -81,12 +81,7 @@ function writeImages(images, dir) {
 }
 
 export async function chat({ messages, system, options, images }, emit, { signal } = {}) {
-  try {
-    mkdirSync(SCRATCH, { recursive: true });
-  } catch {
-    /* best effort */
-  }
-  const cwd = options.workingDir ? path.resolve(options.workingDir) : SCRATCH;
+  const cwd = resolveWorkdir(options.workingDir);
 
   // Images: write into the cwd (workspace) and reference with `@<file>` — agy
   // reads @-referenced files (incl. images) inline as multimodal input, so no

package/src/engines/claude.js

@@ -21,6 +21,7 @@ import { resolveClaude, buildSpawnSpec, isCompiledBinary, selfMcpStdio } from '.
 import { buildCliPrompt } from './prompt.js';
 import { killOnAbort } from '../proc.js';
 import { pushExtraArgs, FORBIDDEN } from './args.js';
+import { displayPath, resolveWorkdir } from '../workdir.js';
 
 // Write base64 data-URL images to temp files. Claude Code reads them with its
 // Read tool (which feeds images to the model as vision), so we just reference the
@@ -141,7 +142,7 @@ function runClaude({ prompt, args, cwd, emit, signal }) {
         } catch {
           continue; // not a JSON event line
         }
-        const r = handleMessage(msg, emit, streamedAny);
+        const r = handleMessage(msg, emit, streamedAny, cwd);
         if (r.streamed) streamedAny = true;
         if (r.result != null) resultText = r.result;
       }
@@ -168,7 +169,7 @@ function runClaude({ prompt, args, cwd, emit, signal }) {
 // Map one stream-json message to emit() calls. Returns { streamed, result }.
 // The CLI's stream-json mirrors the SDK message shapes. Exported so the custom
 // engine can reuse it for agents that emit Claude-style stream-json.
-export function handleMessage(msg, emit, alreadyStreamed) {
+export function handleMessage(msg, emit, alreadyStreamed, cwdForSteps = '') {
   const out = { streamed: false, result: null };
   if (msg.type === 'stream_event') {
     const ev = msg.event;
@@ -183,7 +184,7 @@ export function handleMessage(msg, emit, alreadyStreamed) {
   } else if (msg.type === 'assistant') {
     for (const block of msg.message?.content || []) {
       if (block.type === 'tool_use') {
-        emit({ type: 'tool', name: block.name, summary: toolSummary(block) });
+        emit({ type: 'tool', name: block.name, summary: toolSummary(block, cwdForSteps) });
       } else if (block.type === 'text' && !alreadyStreamed) {
         out.streamed = true;
         emit({ type: 'delta', text: block.text });
@@ -214,7 +215,7 @@ export function handleMessage(msg, emit, alreadyStreamed) {
 export async function chat({ messages, system, options, images }, emit, { signal } = {}) {
   const permissionMode = options.permissionMode || 'default';
   // Explicit project dir, else null → CLI runs in home (or WSL home).
-  const cwd = options.workingDir ? path.resolve(options.workingDir) : null;
+  const cwd = resolveWorkdir(options.workingDir);
 
   const tag = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   const args = ['--print', '--output-format', 'stream-json', '--include-partial-messages', '--verbose'];
@@ -308,10 +309,12 @@ export async function complete({ prompt, system, model }) {
   return (text || resultText || '').trim();
 }
 
-function toolSummary(block) {
+function toolSummary(block, cwd = '') {
   const i = block.input || {};
   if (i.command) return String(i.command).slice(0, 60);
-  if (i.file_path) return path.basename(i.file_path);
+  // Relative to the working directory rather than a bare basename: "src/foo.js" says
+  // where the file is, "foo.js" left the user guessing which of four roots it meant.
+  if (i.file_path) return displayPath(i.file_path, cwd);
   if (i.pattern) return i.pattern;
   if (i.url) return i.url;
   if (i.description) return String(i.description).slice(0, 80); // Task (subagent) — what it's for
@@ -346,7 +349,7 @@ async function sdkChat({ messages, system, options }, emit, { signal } = {}) {
   }
 
   const permissionMode = options.permissionMode || 'default';
-  const cwd = options.workingDir ? path.resolve(options.workingDir) : os.homedir();
+  const cwd = resolveWorkdir(options.workingDir);
   const writesAllowed = permissionMode === 'acceptEdits' || permissionMode === 'bypassPermissions';
   const readonly = new Set(READONLY_TOOLS);
   const canUseTool = async (toolName) =>
@@ -374,7 +377,7 @@ async function sdkChat({ messages, system, options }, emit, { signal } = {}) {
   });
   try {
     for await (const message of iterator) {
-      const r = handleMessage(message, emit, streamedAny);
+      const r = handleMessage(message, emit, streamedAny, cwd);
       if (r.streamed) streamedAny = true;
       if (r.result != null) resultText = r.result;
     }

package/src/engines/codex.js

@@ -23,6 +23,7 @@ import path from 'node:path';
 import { findAgentBin, selfMcpStdio } from '../env.js';
 import { buildCliPrompt } from './prompt.js';
 import { pushExtraArgs, FORBIDDEN } from './args.js';
+import { resolveWorkdir } from '../workdir.js';
 
 // Idle timeout: re-armed on every stdout/stderr chunk, so a long run that keeps
 // streaming never trips it — only true silence does. Override with
@@ -30,7 +31,6 @@ import { pushExtraArgs, FORBIDDEN } from './args.js';
 const IDLE_MS = Number(process.env.CHATPANEL_CODEX_TIMEOUT_MS) || 180_000;
 const REASONING = process.env.CHATPANEL_CODEX_EFFORT ?? 'low'; // '' → respect config
 
-const SCRATCH = path.join(os.tmpdir(), 'chatpanel-codex-scratch');
 
 // Codex has no "list models" command — its model lives in CODEX_HOME/config.toml
 // (e.g. `model = "gpt-5.5"`). Surface the user's REAL configured model(s), read
@@ -49,13 +49,6 @@ export async function listModels() {
 }
 const ISO_HOME = path.join(os.homedir(), '.chatpanel', 'codex-home');
 
-function ensureScratch() {
-  try {
-    mkdirSync(SCRATCH, { recursive: true });
-  } catch {
-    /* best effort */
-  }
-}
 
 // Build (once) an isolated CODEX_HOME that has only a link to your auth, so the
 // global skills/config don't load. Returns the path, or null on failure.
@@ -139,13 +132,12 @@ async function writeImages(images, tag) {
 }
 
 export async function chat({ messages, system, options, images }, emit, { signal } = {}) {
-  ensureScratch();
   const tag = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   const outFile = path.join(os.tmpdir(), `chatpanel-codex-${tag}.txt`);
   const imageFiles = await writeImages(images, tag);
   const cleanupImages = () => imageFiles.forEach((f) => unlink(f).catch(() => {}));
 
-  const cwd = options.workingDir ? path.resolve(options.workingDir) : SCRATCH;
+  const cwd = resolveWorkdir(options.workingDir);
   const args = ['exec', '--json', '--skip-git-repo-check', '-o', outFile];
   // Headless exec has no human to approve actions. With MCP/browser tools armed
   // Codex would otherwise raise an approval prompt it can't show — and cancel the

package/src/engines/custom.js

@@ -23,6 +23,7 @@ import { killOnAbort } from '../proc.js';
 import { buildCliPrompt } from './prompt.js';
 import { pushExtraArgs, FORBIDDEN } from './args.js';
 import { createStreamParser, STREAM_FORMATS, stripAnsi } from './stream-formats.js';
+import { resolveWorkdir } from '../workdir.js';
 
 // Write base64 data-URL images to temp files so a custom CLI can take them via
 // its configured `imageArg` template (e.g. "-i {path}", "@{path}"). Returns paths.
@@ -383,7 +384,7 @@ export async function runSpec(spec, { messages, system, options = {}, images },
   }
 
   const prompt = buildCliPrompt(messages, system);
-  let cwd = options.workingDir ? path.resolve(options.workingDir) : null;
+  let cwd = resolveWorkdir(options.workingDir);
   const label = spec.label || spec.command;
   // Output dialect — resolved against the stream-format registry, so a new agent
   // brings a format by NAME instead of a new branch in this runner. Unknown /

package/src/server.js

@@ -9,6 +9,7 @@
 //                     {type:'delta', text}    incremental assistant text
 //                     {type:'tool',  name, summary}
 //                     {type:'status'|'reasoning', text?}
+//                     {type:'workdir', path, isDefault}  where this run writes
 //                     {type:'done',  text?}    (text only if not streamed)
 //                     {type:'error', error}
 //   POST /v1/chat/completions, /v1/completions, /v1/responses
@@ -37,6 +38,7 @@ import { connectorsFor } from './connectors.js';
 import * as custom from './engines/custom.js';
 import { installService, uninstallService, serviceStatus, restartService } from './service.js';
 import { skillIndex, listRecords, readRecord, readPackageFile, skillsHealth } from './skills.js';
+import { DEFAULT_WORKSPACE, isDefaultWorkdir, resolveWorkdir, writeScopeNote } from './workdir.js';
 import { AGENT_CLIS, enrichPath, enrichAgentEnv, findAgentBin, resolveCommand } from './env.js';
 import { stripHidden } from './sanitize.js';
 import { checkForUpdate, selfUpdate } from './update.js';
@@ -64,7 +66,7 @@ import {
 // Hardcoded (not read from package.json) so it survives Bun's single-file
 // --compile, where package.json isn't on a readable FS. CI fails the publish if
 // this drifts from package.json, so the two can't silently diverge.
-const VERSION = '0.10.29';
+const VERSION = '0.10.30';
 const HOST = process.env.CHATPANEL_BRIDGE_HOST || '127.0.0.1';
 const PORT = Number(process.env.CHATPANEL_BRIDGE_PORT) || 4319;
 
@@ -366,7 +368,13 @@ async function handleHealth(res) {
   // an older bridge simply omits it, which is what stops a newer extension assuming the
   // endpoints exist. Never let a scan failure cost the caller its health check.
   const skills = await skillsHealth().catch(() => null);
-  json(res, 200, { ok: true, version: VERSION, agents, update, ...(skills ? { skills } : {}) });
+  // So Settings can show what a blank "Working directory" actually resolves to, instead
+  // of leaving the user to discover it from where their files did not appear.
+  json(res, 200, {
+    ok: true, version: VERSION, agents, update,
+    workspace: DEFAULT_WORKSPACE,
+    ...(skills ? { skills } : {}),
+  });
 }
 
 // --------------------------------------------------------------------------
@@ -480,6 +488,21 @@ async function handleChat(req, res) {
   const safeEmit = (obj) => { if (!closed) emit(obj); };
   emit({ type: 'run', id: runId });
 
+  // WHERE THIS RUN WILL WRITE, said before it starts. "The agent created a file and I
+  // cannot find it" was the single most confusing thing about a CLI agent, and the answer
+  // used to depend on which engine answered — the filesystem root, the home directory, or
+  // a temp folder the OS clears on its own schedule. Now there is one answer and it is
+  // announced. Additive: a client that does not know `workdir` ignores it, and the same
+  // information is repeated as a `status` line, which every client already renders.
+  {
+    const dir = resolveWorkdir(body.options?.workingDir);
+    const chosen = !isDefaultWorkdir(body.options?.workingDir);
+    const scope = writeScopeNote(body.agent, body.options?.permissionMode, dir);
+    emit({ type: 'workdir', path: dir, isDefault: !chosen, writeScope: scope || undefined });
+    emit({ type: 'status', text: `Working in ${dir}${chosen ? '' : ' (default)'}` });
+    if (scope) emit({ type: 'status', text: scope });
+  }
+
   // Browser-tools relay: when the extension sends page-tool specs, host an MCP
   // server for this turn and tell the engine to point the CLI at it.
   const options = { ...(body.options || {}) };

package/src/skills.js

@@ -36,7 +36,7 @@
 import { readFile as fsReadFile, readdir, stat, realpath } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import os from 'node:os';
-import { join, resolve, sep } from 'node:path';
+import { delimiter, join, resolve, sep } from 'node:path';
 import { isSafeSkillPath, normalizeSkill, SKILL_FILE_KINDS } from './events/skill-manifest.js';
 
 const MAX_SKILL_MD = 512 * 1024;   // a procedure document, not a corpus
@@ -81,8 +81,12 @@ export const AGENT_SKILL_DIRS = Object.freeze([
  * that edits another tool's configuration directory is a tool people uninstall.
  */
 export function skillRoots(env = process.env, home = os.homedir()) {
+  // Split on the PLATFORM's list separator, not a fixed set. Splitting on ':' everywhere
+  // cut "C:\\Users\\me\\skills" into "C" and "\\Users\\me\\skills" on Windows, which is the
+  // one platform where a drive letter makes that character part of an ordinary path.
   const extra = String(env.CHATPANEL_SKILL_DIRS || '')
-    .split(/[:;\n]/)
+    .split(/\r?\n/)
+    .flatMap((line) => line.split(delimiter))
     .map((s) => s.trim())
     .filter(Boolean);
   return [
@@ -213,6 +217,9 @@ async function loadSkill(dir, relPath, source) {
   }
   const { meta, body } = parseFrontmatter(text);
   const hash = `sha256-${createHash('sha256').update(text).digest('hex').slice(0, 32)}`;
+  // relPath is an IDENTITY, not a filesystem path: it is built with '/' on every platform
+  // so a skill's origin.id is the same string on Windows and macOS. Do not "fix" this to
+  // path.sep — that would make the same skill look like two different ones per platform.
   const dirName = relPath.split('/').pop();
   const files = await packageFiles(dir);
   const skill = skillRecord({ meta, body, dirName, relPath, source, files, hash });
@@ -278,6 +285,8 @@ export async function readPackageFile(index, name, relPath) {
   const hit = index.get(String(name || ''));
   if (!hit) return { error: 'unknown skill' };
   if (!isSafeSkillPath(relPath)) return { error: 'unsafe path' };
+  // '/' by wire contract — the HTTP path is URL-shaped, and isSafeSkillPath already
+  // refuses backslashes, so a Windows-style separator never reaches here.
   const kind = String(relPath).split('/')[0];
   if (!SKILL_FILE_KINDS.includes(kind)) return { error: 'unsafe path' };
 

package/src/workdir.js

@@ -0,0 +1,108 @@
+// workdir.js — where an agent's files actually go.
+//
+// This existed five times with four different answers, none of them told to the user:
+//
+//   claude (CLI)   cwd: null  → inherits the BRIDGE's cwd, which under launchd is `/`
+//   claude (SDK)   ~
+//   codex          /tmp/chatpanel-codex-scratch
+//   antigravity    /tmp/chatpanel-agy-scratch
+//   custom         cwd: null  → `/` again
+//
+// So "the agent created a file and I cannot find it" was not user error. Depending on
+// which agent answered, the file was at the filesystem root, in the home directory, or in
+// a temp folder the OS deletes on its own schedule.
+//
+// One default, and it is neither `/` nor a temp directory: `~/.chatpanel/workspace`.
+// Persistent, predictable, obviously ChatPanel's, and somewhere a person can navigate to.
+// A user who wants files elsewhere sets Working directory on the agent — which is what
+// that field was always for; it just had an invisible and inconsistent fallback.
+//
+// The path is REPORTED, not just chosen: /health carries it so Settings can show what a
+// blank field resolves to, and every run announces it, because a default nobody can see
+// is the same problem in a nicer location.
+
+import { mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Where files land when an agent has no Working directory set. */
+export const DEFAULT_WORKSPACE = path.join(os.homedir(), '.chatpanel', 'workspace');
+
+/**
+ * Resolve an agent's working directory, creating it if needed.
+ *
+ * Always returns a real, absolute path — never null. Inheriting the bridge's own cwd is
+ * what produced `/`, and a process spawned at `/` either refuses to write or writes
+ * somewhere nobody will look.
+ *
+ * Creation failure is not fatal: the agent may not need to write at all, and refusing to
+ * answer a question because a directory could not be made would be a worse failure than
+ * the one it prevents. The caller still gets the path, and the CLI reports its own error
+ * if it turns out to matter.
+ */
+export function resolveWorkdir(workingDir) {
+  const dir = workingDir && String(workingDir).trim()
+    ? path.resolve(String(workingDir).trim())
+    : DEFAULT_WORKSPACE;
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    /* reported by whatever tries to write */
+  }
+  return dir;
+}
+
+/** True when this run is using the default rather than a directory the user chose. */
+export function isDefaultWorkdir(workingDir) {
+  return !(workingDir && String(workingDir).trim());
+}
+
+/**
+ * How a path should read in a tool step.
+ *
+ * `path.basename` was used here, so a step said "foo.js" and left the user to guess which
+ * of the four possible roots it meant. Relative-to-cwd says where it is without pasting an
+ * absolute path into every line; anything OUTSIDE the working directory keeps its full
+ * path, because that is exactly the case worth noticing.
+ *
+ * `impl` is the path flavour, injected so the Windows and POSIX rules can both be tested
+ * on whichever machine happens to run the suite. The bridge ships to macOS, Linux AND
+ * Windows, and a display rule that is only ever exercised on one of them is a display rule
+ * that is wrong on the other two.
+ */
+export function displayPath(filePath, cwd, impl = path) {
+  const p = String(filePath || '');
+  if (!p) return '';
+  if (!cwd || !impl.isAbsolute(p)) return p;
+  const rel = impl.relative(cwd, p);
+  if (!rel) return '.';
+  // Two ways out of the working directory, and Windows only has one of them in common
+  // with POSIX: `..` for a sibling, and a wholly different ROOT (another drive, a UNC
+  // share) for which `relative` hands back an absolute path rather than any `..` at all.
+  if (rel.startsWith('..') || impl.isAbsolute(rel)) return p;
+  return rel;
+}
+
+/**
+ * Whether this engine+mode confines writes to the working directory, and how to say so.
+ *
+ * Codex's `acceptEdits` maps to `--sandbox workspace-write`, which permits writes ONLY
+ * inside the cwd. That is correct sandboxing and it is also the most confusing failure the
+ * bridge produces: the agent reports that it could not write a file, the user checks that
+ * "auto-edit files" is on, and nothing anywhere mentions that the boundary is a DIRECTORY
+ * rather than a permission. It bit hardest before there was a sensible default, when a
+ * blank field meant a temp folder — so every attempt to edit a real project was outside
+ * the sandbox by construction.
+ *
+ * Stated up front rather than detected on failure: a denial does not necessarily fail the
+ * run (Codex reports it as a failed tool call and carries on), so there is no reliable
+ * error to attach an explanation to.
+ */
+export function writeScopeNote(engineId, permissionMode, cwd) {
+  if (engineId !== 'codex') return '';
+  if (permissionMode === 'bypassPermissions') return '';
+  if (permissionMode !== 'acceptEdits') {
+    return 'Codex is read-only in this mode — set Permissions to “auto-edit files” to let it write.';
+  }
+  return `Codex may only create or edit files inside ${cwd}. To work on another project, set this agent’s Working directory to it.`;
+}