@parall/codex-agent 1.44.0 → 1.45.0

package/dist/workspace.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { parse as parseToml } from 'smol-toml';
 import { BRIDGE_WORKSPACE_INSTRUCTIONS, PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity, buildSkillReferences, writeSkillFiles, } from '@parall/agent-core';
+import { runLegacyWorkspaceConfigMigration } from './legacy-workspace-config-migration.js';
 /**
  * Config-lock timings, exported for tests.
  *
@@ -25,10 +25,10 @@ function sleepSync(ms) {
 }
 /**
  * Advisory cross-process lock serializing `<codexHome>/config.toml`
- * read-modify-write. On a local daemon machine every runtime_auth codex
- * bridge child shares the operator's CODEX_HOME, and the daemon starts them
- * together — without a lock, a whole-file rewrite working from a stale read
- * can erase a trust entry another agent appended in between.
+ * read-modify-write. Several bridge children can share one CODEX_HOME (an
+ * operator-set PRLL_CODEX_HOME reaches every child on the machine), and the
+ * daemon starts them together — without a lock, concurrent whole-file
+ * rewrites working from stale reads lose updates.
  *
  * Queue design (why not wx-create + steal): any scheme that renames or
  * unlinks the SHARED lock path can, between its staleness check and the
@@ -71,11 +71,12 @@ function sleepSync(ms) {
  * eviction and the process re-enqueues. On `waitMs` timeout
  * the mutation proceeds without the lock (warn) — blocking would wedge
  * bridge startup. The lock coordinates bridge processes only; codex itself
- * does not observe it, which is why bridge writes to a shared config are
- * additionally kept rare (the trust write is a no-op after the first boot
- * per workspace, and runtime_auth agents never write the provider block)
- * and whole-file writes are atomic (temp + rename) so codex never reads a
- * truncated file.
+ * does not observe it, which is why bridge writes to the global config are
+ * additionally kept rare — the only remaining mutation is the parall
+ * provider block (runtime_auth agents, which share the operator's ~/.codex,
+ * write nothing at all: platform instructions ride the app-server
+ * `developerInstructions` param) — and whole-file writes are atomic
+ * (temp + rename) so codex never reads a truncated file.
  *
  * Exported for tests.
  */
@@ -314,9 +315,9 @@ function bakeryEnqueue(queueDir) {
 /**
  * Whole-file config writes go through temp + rename so a concurrent reader
  * (including codex itself, which does not observe the advisory lock) never
- * sees a truncated file. The trust-append path intentionally keeps
- * appendFileSync — O_APPEND is atomic for these small writes and cannot
- * clobber a concurrent append.
+ * sees a truncated file. This is now the only way the bridge writes the global
+ * config: the append-based trust path it used to share this file with is gone
+ * with `ensureWorkspaceTrusted`, and the provider block is a whole-file rewrite.
  *
  * The rename targets the file's REAL path: `config.toml` managed by a
  * dotfiles setup is often a symlink, and renaming onto the link path would
@@ -402,108 +403,6 @@ function resolveWriteTarget(filePath) {
     }
     throw new Error(`symlink chain deeper than 40 while resolving ${filePath}`);
 }
-/**
- * Ensure the workspace directory is marked as trusted in the global Codex
- * config so that project-level `developer_instructions` are loaded at
- * app-server startup.
- *
- * Uses smol-toml for structured reads (avoids substring false-positives),
- * but writes via raw text manipulation (preserves comments and formatting).
- * Failures are swallowed (warn-only) so a trust write issue never blocks
- * the bridge from starting.
- */
-export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
-    withConfigLock(codexHome, log, () => ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log));
-}
-function ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log) {
-    const configPath = path.join(codexHome, 'config.toml');
-    const normalizedPath = path.resolve(workspaceDir);
-    try {
-        let content = '';
-        try {
-            content = fs.readFileSync(configPath, 'utf8');
-        }
-        catch (err) {
-            if (err.code !== 'ENOENT')
-                throw err;
-        }
-        // Structured read — know exactly what state we're in.
-        let parsed;
-        if (content) {
-            try {
-                parsed = parseToml(content);
-            }
-            catch {
-                // File is already broken TOML — don't make it worse.
-                log?.warn(`Codex config.toml is not valid TOML; skipping trust write for ${normalizedPath}`);
-                return;
-            }
-        }
-        const projects = parsed?.projects;
-        const existingTrust = projects?.[normalizedPath]?.trust_level;
-        if (existingTrust === 'trusted')
-            return;
-        if (existingTrust !== undefined) {
-            // An explicit non-trusted value is a human decision — on a local
-            // runtime_auth daemon this file IS the operator's own ~/.codex config,
-            // and a workspace they deliberately marked untrusted must never be
-            // silently flipped by an agent. Leave it and surface the consequence.
-            log?.warn(`Codex config marks ${normalizedPath} as trust_level=${JSON.stringify(existingTrust)}; respecting the explicit decision — project-level developer_instructions will not load for this workspace`);
-            return;
-        }
-        // TOML basic-string keys require backslash and double-quote escaping.
-        const escapedPath = normalizedPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-        const sectionHeader = `[projects."${escapedPath}"]`;
-        const trustLine = 'trust_level = "trusted"';
-        const headerIdx = content.indexOf(sectionHeader);
-        if (headerIdx !== -1) {
-            // Section exists but trust_level isn't "trusted". Scan all lines
-            // within the section (up to the next `[` header or EOF) for an
-            // existing trust_level key — it may not be the first line after
-            // the header if the user added comments or other keys.
-            const headerLineEnd = content.indexOf('\n', headerIdx);
-            if (headerLineEnd === -1) {
-                content = `${content}\n${trustLine}\n`;
-            }
-            else {
-                const afterHeader = headerLineEnd + 1;
-                const sectionEnd = findSectionEnd(content, afterHeader);
-                const sectionBody = content.substring(afterHeader, sectionEnd);
-                const trustMatch = sectionBody.match(/^[ \t]*trust_level[ \t]*=.*$/m);
-                if (trustMatch) {
-                    const matchStart = afterHeader + trustMatch.index;
-                    const matchEnd = matchStart + trustMatch[0].length;
-                    content = content.substring(0, matchStart) + trustLine + content.substring(matchEnd);
-                }
-                else {
-                    content =
-                        content.substring(0, afterHeader) + trustLine + '\n' + content.substring(afterHeader);
-                }
-            }
-            writeConfigAtomic(configPath, content);
-        }
-        else if (projects?.[normalizedPath] !== undefined) {
-            // smol-toml found the section but indexOf missed it — the header
-            // uses non-canonical TOML formatting. Appending would create a
-            // duplicate table. Skip rather than corrupt the file.
-            log?.warn(`Codex config.toml has non-canonical header for ${normalizedPath}; skipping trust write`);
-        }
-        else if (projects && !content.includes('[projects.')) {
-            // `projects` exists in parsed output but no `[projects.` table
-            // headers in the raw text — it's an inline table. Appending a
-            // standard table header would produce invalid TOML.
-            log?.warn(`Codex config.toml uses inline table for projects; skipping trust write for ${normalizedPath}`);
-        }
-        else {
-            // Section doesn't exist — append.
-            fs.mkdirSync(codexHome, { recursive: true });
-            fs.appendFileSync(configPath, `\n${sectionHeader}\n${trustLine}\n`, 'utf8');
-        }
-    }
-    catch (err) {
-        log?.warn(`failed to write Codex project trust for ${normalizedPath}: ${String(err)}`);
-    }
-}
 /**
  * Returns true when the agent is using the Parall LLM proxy (llm_source=parall)
  * rather than a BYO custom provider or runtime_auth. Detected by checking
@@ -530,10 +429,61 @@ export function isParallProxyMode(env = process.env) {
  *
  * Provider-managed: overwritten on every boot (env vars are the SSOT).
  */
-export function ensureParallProvider(codexHome, apiUrl, log) {
-    withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl));
+/**
+ * Escape a value as a TOML basic (double-quoted) string. Needed for Windows
+ * paths (backslashes) in the auth command; harmless hardening everywhere else.
+ */
+export function tomlBasicString(value) {
+    let out = '';
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (ch === '\\')
+            out += '\\\\';
+        else if (ch === '"')
+            out += '\\"';
+        else if (ch === '\b')
+            out += '\\b';
+        else if (ch === '\t')
+            out += '\\t';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\f')
+            out += '\\f';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (code < 0x20 || code === 0x7f)
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+        else
+            out += ch;
+    }
+    return `"${out}"`;
+}
+/**
+ * The `[model_providers.parall.auth]` body. auth.command is the only path
+ * that actually sends the Bearer header on custom providers (see
+ * codex-responses-api-proxy.md), so both platforms stay in that shape:
+ *   - POSIX keeps the empirically validated `printenv OPENAI_API_KEY`,
+ *     byte-for-byte — do not touch it.
+ *   - Windows has no printenv; reuse the bridge's own Node runtime
+ *     (process.execPath — on disk by construction, and the config is
+ *     provider-managed / rewritten every boot, so a moved Node self-heals).
+ *     The -e script mirrors printenv exactly: missing var → exit 1, value →
+ *     stdout with no trailing newline. Keep the script free of `"` and `\`
+ *     so it stays inert inside a TOML basic string.
+ */
+function parallAuthLines(opts) {
+    const platform = opts?.platform ?? process.platform;
+    if (platform !== 'win32') {
+        return ['command = "printenv"', 'args = ["OPENAI_API_KEY"]'];
+    }
+    const nodeBin = opts?.nodeBin ?? process.execPath;
+    const script = 'const v=process.env.OPENAI_API_KEY;if(v===undefined)process.exit(1);process.stdout.write(v)';
+    return [`command = ${tomlBasicString(nodeBin)}`, `args = ["-e", ${tomlBasicString(script)}]`];
+}
+export function ensureParallProvider(codexHome, apiUrl, log, opts) {
+    withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl, opts));
 }
-function ensureParallProviderLocked(codexHome, apiUrl) {
+function ensureParallProviderLocked(codexHome, apiUrl, opts) {
     const configPath = path.join(codexHome, 'config.toml');
     const baseUrl = apiUrl.replace(/\/$/, '') + '/api/llm/v1';
     try {
@@ -550,14 +500,13 @@ function ensureParallProviderLocked(codexHome, apiUrl) {
         const providerBlock = [
             sectionHeader,
             'name = "Parall Proxy"',
-            `base_url = "${baseUrl}"`,
+            `base_url = ${tomlBasicString(baseUrl)}`,
             'wire_api = "responses"',
             'supports_websockets = false',
             'requires_openai_auth = false',
             '',
             authHeader,
-            'command = "printenv"',
-            'args = ["OPENAI_API_KEY"]',
+            ...parallAuthLines(opts),
         ].join('\n');
         const headerIdx = content.indexOf(sectionHeader);
         if (headerIdx !== -1) {
@@ -585,18 +534,28 @@ function findSectionEnd(content, fromIndex) {
     const nextHeader = content.indexOf('\n[', fromIndex);
     return nextHeader === -1 ? content.length : nextHeader;
 }
-// writeCodexSystemPrompt (re)writes the standing platform prompt surfaces:
-// .parall/system-prompt.md (human-inspectable copy) and the workspace
-// .codex/config.toml developer_instructions (what the CLI actually loads).
+/** Human-inspectable copy of the prompt; also the migration's authorship proof. */
+function systemPromptCopyPath(workspaceDir) {
+    return path.join(workspaceDir, '.parall', 'system-prompt.md');
+}
+// writeCodexSystemPrompt (re)builds the platform prompt and refreshes its
+// human-inspectable reference copy (.parall/system-prompt.md). Delivery to
+// the CLI is the app-server per-thread `developerInstructions` param — NOT
+// a workspace config file.
 // capabilityFragments are platform-derived capability declarations
 // (agents.capabilities[].fragment) — placed after the platform reference
 // guide, before skill references; empty/absent = no capability section.
-// Split out from ensureCodexWorkspace so the bridge can rewrite on
-// platform-config heat-update; the app-server reads workspace config at
-// process start, so the caller pairs a CHANGED fragment set with
-// adapter.requestProcessRestart(). Throws on failure BY DESIGN — at boot the
-// prompt is mandatory, so a write failure must fail startup loudly; the
-// refresh hot path wraps this in try/catch and retries next refresh.
+// Split out from ensureCodexWorkspace so the bridge can rebuild the prompt on
+// a platform-config heat-update and hand the new value to
+// adapter.updateConfig, which carries it into the NEXT thread/start. A thread
+// that is already open keeps the instructions it was started with — codex
+// bakes them into the thread at start and neither thread/resume nor
+// thread/fork replaces them (verified against a live 0.144.1 app-server; the
+// retired workspace-config channel behaved identically). See
+// docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+// Throws on failure BY DESIGN — at boot the prompt is mandatory, so a write
+// failure must fail startup loudly; the refresh hot path wraps this in
+// try/catch and retries next refresh.
 export function writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments) {
     const parts = [
         buildIdentity(agentIdentity),
@@ -609,18 +568,60 @@ export function writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFr
     }
     parts.push(buildSkillReferences(workspaceDir));
     const systemPrompt = parts.join('\n\n');
-    const parallDir = path.join(workspaceDir, '.parall');
-    fs.mkdirSync(parallDir, { recursive: true });
-    fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), systemPrompt, 'utf8');
-    const codexConfigDir = path.join(workspaceDir, '.codex');
-    fs.mkdirSync(codexConfigDir, { recursive: true });
-    const toml = `developer_instructions = """\n${systemPrompt.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""\n`;
-    fs.writeFileSync(path.join(codexConfigDir, 'config.toml'), toml, 'utf8');
+    // Reference copy the agent can read as a file. The prompt itself is
+    // delivered per-thread via the app-server `developerInstructions` param —
+    // deliberately NOT via workspace `.codex/config.toml`, which codex only
+    // loads for workspaces marked trusted in the operator's global config:
+    // that coupled the platform prompt to codex's interactive workspace-trust
+    // concept and forced the bridge to write trust entries into the
+    // operator's own ~/.codex on shared homes.
+    fs.mkdirSync(path.join(workspaceDir, '.parall'), { recursive: true });
+    fs.writeFileSync(systemPromptCopyPath(workspaceDir), systemPrompt, 'utf8');
+    return systemPrompt;
 }
 export function ensureCodexWorkspace(workspaceDir, log, agentIdentity, capabilityFragments) {
     fs.mkdirSync(workspaceDir, { recursive: true });
+    // The ONE ordering rule this bootstrap has to get right.
+    //
+    // `.parall/system-prompt.md` is the migration's authorship proof, and
+    // writeCodexSystemPrompt below overwrites it. It is therefore legacy-era
+    // evidence for exactly one boot, so the migration must take its one-way claim
+    // and consume the proof BEFORE that write. The migration refuses to delete
+    // anything once the claim exists, so no later boot can judge the legacy config
+    // against a prompt this bridge wrote itself. A claim that cannot be persisted
+    // throws from here — the boot dies with the evidence intact rather than
+    // manufacturing a prompt a later boot would mistake for it.
+    //
+    // The proof goes in as a THUNK: reading it warns when it exists but cannot be
+    // read, and a boot that already lost (or never had) the claim must stay
+    // silent. Handing over an evaluated value would fire that warning before the
+    // claim is even checked.
+    runLegacyWorkspaceConfigMigration(workspaceDir, () => readAuthorshipProof(workspaceDir, log), log);
     // Boot: let a write failure PROPAGATE (fatal) — startup must not proceed
     // without the platform prompt. The refresh path tolerates failure.
-    writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
+    const systemPrompt = writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
     writeSkillFiles(path.join(workspaceDir, '.parall', 'skills'));
+    return systemPrompt;
+}
+/**
+ * The previous boot's prompt copy — the migration's authorship proof.
+ *
+ * ENOENT is the ordinary first boot in a workspace: absent, no warning. Any
+ * other error means the proof EXISTS but could not be read, which is a
+ * different fact and must not be reported as "never bootstrapped here" — the
+ * migration would otherwise preserve a genuinely stale config while telling the
+ * operator the wrong reason. Both map to "don't delete"; only the diagnostic
+ * differs.
+ */
+function readAuthorshipProof(workspaceDir, log) {
+    const proofPath = systemPromptCopyPath(workspaceDir);
+    try {
+        return { kind: 'present', prompt: fs.readFileSync(proofPath, 'utf8') };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { kind: 'absent' };
+        log?.warn(`could not read the authorship proof ${proofPath}: ${String(err)}`);
+        return { kind: 'unreadable' };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.44.0",
+  "version": "1.45.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -25,13 +25,13 @@
     "src"
   ],
   "dependencies": {
-    "smol-toml": "^1.6.1",
-    "@parall/agent-core": "1.44.0",
-    "@parall/cli": "1.44.0",
-    "@parall/sdk": "1.44.0"
+    "@parall/agent-core": "1.45.0",
+    "@parall/cli": "1.45.0",
+    "@parall/sdk": "1.45.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "smol-toml": "^1.6.1",
     "typescript": "^5.7.0"
   },
   "scripts": {

package/src/app-server-process.ts

@@ -0,0 +1,59 @@
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { ensureLocalAttachmentGitExclude } from '@parall/agent-core/internal/attachment-input';
+
+/**
+ * OS-level plumbing for the `codex app-server` child process: the cwd invariant
+ * it requires (a git repo), and the Windows spawn/kill quirks.
+ */
+
+export const IS_WIN32 = process.platform === 'win32';
+
+export function quoteWin32Arg(arg: string): string {
+  if (!/[\s"&|^<>()]/.test(arg)) return arg;
+  return `"${arg.replace(/"/g, '""')}"`;
+}
+
+export function killWin32Tree(pid: number): boolean {
+  try {
+    execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function ensureGitRepo(workingDirectory: string): void {
+  fs.mkdirSync(workingDirectory, { recursive: true });
+  // Only `git init` if the workspace isn't already inside any git repo. A
+  // bare existsSync(.git) check would miss the common case of a user pointing
+  // PRLL_WORKSPACE_DIR at a subdirectory of their existing project,
+  // and silently creating a nested repo there would mangle their layout.
+  //
+  // The exclude write sits inside this try, so in principle its failure would
+  // read as "not a repo" and fall through to `git init` in the user's existing
+  // repository. It cannot: the helper swallows its own errors. Deliberately left
+  // as-is rather than fixed under review — latent, not live, and out of this
+  // PR's scope: docs/tech-debt/codex-ensure-git-repo-exclude-coupling.md.
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd: workingDirectory, stdio: 'pipe' });
+    ensureLocalAttachmentGitExclude(workingDirectory);
+    return;
+  } catch {
+    // Not inside a repo — fall through to init.
+  }
+  const env = {
+    ...process.env,
+    GIT_AUTHOR_NAME: 'parall-codex-agent',
+    GIT_AUTHOR_EMAIL: 'agent@parall.local',
+    GIT_COMMITTER_NAME: 'parall-codex-agent',
+    GIT_COMMITTER_EMAIL: 'agent@parall.local',
+  };
+  try {
+    execSync('git init', { cwd: workingDirectory, stdio: 'pipe', env });
+    execSync('git commit --allow-empty -m init', { cwd: workingDirectory, stdio: 'pipe', env });
+    ensureLocalAttachmentGitExclude(workingDirectory);
+  } catch {
+    // Non-fatal: codex app-server may still accept a bare directory. Let it raise at turn time.
+  }
+}

package/src/app-server-protocol.ts

@@ -0,0 +1,46 @@
+import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
+
+/**
+ * Wire shapes of the `codex app-server` JSON-RPC payloads: what we send as turn
+ * input, and how we read ids back out of responses and notifications. The
+ * protocol has shifted between CLI versions, so the tolerant field probing lives
+ * here rather than being spread through the adapter.
+ */
+
+export type CodexTurnInput = { type: 'text'; text: string } | { type: 'localImage'; path: string };
+
+export function buildTurnInput(body: string, images: PreparedLocalImage[]): CodexTurnInput[] {
+  return [
+    { type: 'text', text: body },
+    ...images.map((image) => ({ type: 'localImage' as const, path: image.localPath })),
+  ];
+}
+
+export function extractThreadId(result: unknown): string | undefined {
+  if (!result || typeof result !== 'object') return undefined;
+  const r = result as Record<string, unknown>;
+  if (typeof r.threadId === 'string') return r.threadId;
+  const thread = r.thread as Record<string, unknown> | undefined;
+  if (thread && typeof thread.id === 'string') return thread.id;
+  return undefined;
+}
+
+export function extractTurnId(result: unknown): string | undefined {
+  if (!result || typeof result !== 'object') return undefined;
+  const r = result as Record<string, unknown>;
+  if (typeof r.turnId === 'string') return r.turnId;
+  const turn = r.turn as Record<string, unknown> | undefined;
+  if (turn && typeof turn.id === 'string') return turn.id;
+  return undefined;
+}
+
+export function extractThreadIdFromNotification(params: unknown): string | undefined {
+  if (!params || typeof params !== 'object') return undefined;
+  const p = params as Record<string, unknown>;
+  if (typeof p.threadId === 'string') return p.threadId;
+  const thread = p.thread as Record<string, unknown> | undefined;
+  if (thread && typeof thread.id === 'string') return thread.id;
+  const meta = (p._meta ?? p.meta) as Record<string, unknown> | undefined;
+  if (meta && typeof meta.threadId === 'string') return meta.threadId;
+  return undefined;
+}