@parall/codex-agent 1.44.0 → 1.45.0

package/src/turn-sink.ts

@@ -0,0 +1,48 @@
+import type { RuntimeEvent } from '@parall/agent-core';
+import { EventMapper } from './event-mapping.js';
+
+export type TurnEventEnvelope =
+  | { kind: 'runtime'; event: RuntimeEvent }
+  | { kind: 'turn_end'; threadId?: string }
+  | { kind: 'error'; message: string };
+
+/** Per-turn buffered sink backed by an unbounded promise queue. */
+export class TurnSink {
+  readonly mapper = new EventMapper();
+  private readonly queue: TurnEventEnvelope[] = [];
+  private resolver: ((value: TurnEventEnvelope) => void) | null = null;
+  private closed = false;
+
+  push(envelope: TurnEventEnvelope) {
+    if (this.closed) return;
+    if (this.resolver) {
+      const r = this.resolver;
+      this.resolver = null;
+      r(envelope);
+      return;
+    }
+    this.queue.push(envelope);
+  }
+
+  next(): Promise<TurnEventEnvelope> {
+    // Drain any queued envelopes first, even after close(). Otherwise a final
+    // error envelope enqueued right before close() (e.g. by
+    // handleSubprocessClose) is silently dropped because the consumer would
+    // see turn_end before it.
+    const pending = this.queue.shift();
+    if (pending) return Promise.resolve(pending);
+    if (this.closed) {
+      return Promise.resolve({ kind: 'turn_end' });
+    }
+    return new Promise((resolve) => {
+      this.resolver = resolve;
+    });
+  }
+
+  close() {
+    this.closed = true;
+    const r = this.resolver;
+    this.resolver = null;
+    r?.({ kind: 'turn_end' });
+  }
+}

package/src/workspace.ts

@@ -1,6 +1,5 @@
 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,
@@ -10,6 +9,8 @@ import {
   writeSkillFiles,
 } from '@parall/agent-core';
 import type { AgentIdentity } from '@parall/agent-core';
+import type { AuthorshipProof } from './legacy-workspace-config-migration.js';
+import { runLegacyWorkspaceConfigMigration } from './legacy-workspace-config-migration.js';
 
 /**
  * Config-lock timings, exported for tests.
@@ -37,10 +38,10 @@ function sleepSync(ms: number): void {
 
 /**
  * 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
@@ -83,11 +84,12 @@ function sleepSync(ms: number): void {
  * 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.
  */
@@ -322,9 +324,9 @@ function bakeryEnqueue(queueDir: string): string | null {
 /**
  * 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
@@ -404,123 +406,6 @@ function resolveWriteTarget(filePath: string): string {
   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: string,
-  workspaceDir: string,
-  log?: { warn: (msg: string) => void },
-): void {
-  withConfigLock(codexHome, log, () => ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log));
-}
-
-function ensureWorkspaceTrustedLocked(
-  codexHome: string,
-  workspaceDir: string,
-  log?: { warn: (msg: string) => void },
-): void {
-  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 as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
-    }
-
-    // Structured read — know exactly what state we're in.
-    let parsed: Record<string, unknown> | undefined;
-    if (content) {
-      try {
-        parsed = parseToml(content) as Record<string, unknown>;
-      } 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 as Record<string, Record<string, unknown>> | undefined;
-    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
@@ -547,15 +432,71 @@ export function isParallProxyMode(env: NodeJS.ProcessEnv = process.env): boolean
  *
  * Provider-managed: overwritten on every boot (env vars are the SSOT).
  */
+/**
+ * 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: string): string {
+  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}"`;
+}
+
+/** Injectable auth-command inputs — production callers pass nothing. */
+export interface ParallProviderAuthOptions {
+  platform?: NodeJS.Platform;
+  nodeBin?: string;
+}
+
+/**
+ * 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?: ParallProviderAuthOptions): string[] {
+  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: string,
   apiUrl: string,
   log?: { warn: (msg: string) => void },
+  opts?: ParallProviderAuthOptions,
 ): void {
-  withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl));
+  withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl, opts));
 }
 
-function ensureParallProviderLocked(codexHome: string, apiUrl: string): void {
+function ensureParallProviderLocked(
+  codexHome: string,
+  apiUrl: string,
+  opts?: ParallProviderAuthOptions,
+): void {
   const configPath = path.join(codexHome, 'config.toml');
   const baseUrl = apiUrl.replace(/\/$/, '') + '/api/llm/v1';
 
@@ -572,14 +513,13 @@ function ensureParallProviderLocked(codexHome: string, apiUrl: string): void {
     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);
@@ -609,23 +549,34 @@ function findSectionEnd(content: string, fromIndex: number): number {
   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: string): string {
+  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: string,
   agentIdentity?: AgentIdentity,
   capabilityFragments?: string[],
-): void {
+): string {
   const parts = [
     buildIdentity(agentIdentity),
     BRIDGE_WORKSPACE_INSTRUCTIONS,
@@ -638,14 +589,17 @@ export function writeCodexSystemPrompt(
   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(
@@ -653,12 +607,59 @@ export function ensureCodexWorkspace(
   log?: { warn: (msg: string) => void },
   agentIdentity?: AgentIdentity,
   capabilityFragments?: string[],
-): void {
+): string {
   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: string,
+  log?: { warn: (msg: string) => void },
+): AuthorshipProof {
+  const proofPath = systemPromptCopyPath(workspaceDir);
+  try {
+    return { kind: 'present', prompt: fs.readFileSync(proofPath, 'utf8') };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'absent' };
+    log?.warn(`could not read the authorship proof ${proofPath}: ${String(err)}`);
+    return { kind: 'unreadable' };
+  }
 }