@parall/codex-agent 1.23.0 → 1.24.0

package/dist/dispatch.d.ts

@@ -38,7 +38,7 @@ export declare class CodexAppServerAdapter implements DispatchAdapter {
      */
     private setActiveTurn;
     constructor(opts: CodexAppServerAdapterOptions);
-    dispatch({ bodyForAgent, sessionKey, context }: DispatchOpts): AsyncIterable<RuntimeEvent>;
+    dispatch({ event, bodyForAgent, sessionKey, context }: DispatchOpts): AsyncIterable<RuntimeEvent>;
     forkSession({ sessionKey: parentSessionKey }: ForkOpts): Promise<ForkSessionHandle | null>;
     cleanupFork({ fork }: CleanupForkOpts): void;
     private logForkFailure;

package/dist/dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IA6B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA5BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAExD,QAAQ,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IA0J3F,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuBhG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKhB,IAAI;YAaI,aAAa;YAcb,OAAO;IA2DrB,OAAO,CAAC,qBAAqB;YAiCf,UAAU;IAgDxB,OAAO,CAAC,iBAAiB;CA2B1B"}
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,aAAa,EACb,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,KAAK,4BAA4B,GAAG,IAAI,CACtC,gBAAgB,EACd,gBAAgB,GAChB,UAAU,GACV,WAAW,GACX,OAAO,GACP,iBAAiB,GACjB,SAAS,GACT,cAAc,CACjB,GAAG;IACF,cAAc,EAAE,mBAAmB,CAAC;IACpC,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IA6B/C,OAAO,CAAC,QAAQ,CAAC,IAAI;IA5BjC,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;gBAYQ,IAAI,EAAE,4BAA4B;IAExD,QAAQ,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,aAAa,CAAC,YAAY,CAAC;IAgLlG,WAAW,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAuBhG,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe;IAIrC,OAAO,CAAC,cAAc;IAKhB,IAAI;YAaI,aAAa;YAcb,OAAO;IA2DrB,OAAO,CAAC,qBAAqB;YAiCf,UAAU;IAgDxB,OAAO,CAAC,iBAAiB;CA2B1B"}

package/dist/dispatch.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { execSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import { appendPreparedLocalAttachmentRefs, ensureLocalAttachmentGitExclude, pinLocalAttachmentPaths, } from "@parall/agent-core/internal/attachment-input";
 import { normalizeApprovalPolicy, normalizeSandbox } from "./config.js";
 import { EventMapper } from "./event-mapping.js";
 import { JsonRpcStdioClient } from "./jsonrpc-client.js";
@@ -48,7 +49,7 @@ export class CodexAppServerAdapter {
     constructor(opts) {
         this.opts = opts;
     }
-    async *dispatch({ bodyForAgent, sessionKey, context }) {
+    async *dispatch({ event, bodyForAgent, sessionKey, context }) {
         await this.ensureStarted(context.log);
         // After ensureStarted resolves the subprocess could still die before we
         // capture the client (handleSubprocessClose nulls this.client). Yield a
@@ -113,14 +114,37 @@ export class CodexAppServerAdapter {
         this.setActiveTurn(threadId, sink, log);
         const groupKey = randomUUID();
         let sawTurnEnd = false;
+        let releasePreparedAttachments = () => { };
         try {
+            let preparedBody = bodyForAgent;
+            let preparedImages = [];
+            try {
+                const prepared = await appendPreparedLocalAttachmentRefs(bodyForAgent, event, context, {
+                    workspaceDir: this.opts.workspaceDir,
+                    log,
+                });
+                preparedBody = prepared.body;
+                preparedImages = prepared.attachments.images;
+                releasePreparedAttachments = pinLocalAttachmentPaths(preparedImages);
+            }
+            catch (err) {
+                log?.warn?.(`codex-agent[${context.accountId}]: failed to prepare local attachments: ${errToString(err)}`);
+            }
+            // `localImage` is a first-class variant of `UserInput` in the Codex
+            // app-server protocol (codex-rs/app-server-protocol/src/protocol/v2.rs
+            // — it sits alongside `text` and `image`), so we send the combined
+            // text+localImage input directly. If a future Codex release breaks
+            // this contract, we want a hard error surfaced to the operator, not a
+            // silent fallback that hides real protocol drift.
+            const turnInput = buildTurnInput(preparedBody, preparedImages);
+            const startTurn = (targetThreadId) => client.sendRequest("turn/start", {
+                threadId: targetThreadId,
+                input: turnInput,
+            });
             // Start the turn. If the stored threadId is dead, we retry once with a fresh thread.
             let turnStartResult;
             try {
-                turnStartResult = await client.sendRequest("turn/start", {
-                    threadId,
-                    input: buildTurnInput(bodyForAgent),
-                });
+                turnStartResult = await startTurn(threadId);
             }
             catch (err) {
                 const message = errToString(err);
@@ -148,10 +172,7 @@ export class CodexAppServerAdapter {
                 }
                 this.setActiveTurn(freshThreadId, sink, log);
                 try {
-                    turnStartResult = await client.sendRequest("turn/start", {
-                        threadId: freshThreadId,
-                        input: buildTurnInput(bodyForAgent),
-                    });
+                    turnStartResult = await startTurn(freshThreadId);
                 }
                 catch (retryErr) {
                     // Retry also failed — likely transient or systemic, not a stale-thread
@@ -179,24 +200,25 @@ export class CodexAppServerAdapter {
                     yield { type: "error", message: envelope.message };
                     continue;
                 }
-                const event = envelope.event;
-                if (event.type === "error") {
-                    yield event;
+                const runtimeEvent = envelope.event;
+                if (runtimeEvent.type === "error") {
+                    yield runtimeEvent;
                     continue;
                 }
-                if (event.type === "text") {
+                if (runtimeEvent.type === "text") {
                     // Layer 0 symmetric output contract: Codex's plain text is never
                     // projected as a chat message. Outbound messages must come from the
                     // agent explicitly invoking `@parall/cli messages send` / `dm` via
                     // the shell/exec tool. Text events are still yielded so agent-core
                     // records them as suppressed session steps for audit.
-                    yield { ...event, project: false, groupKey };
+                    yield { ...runtimeEvent, project: false, groupKey };
                     continue;
                 }
-                yield { ...event, groupKey };
+                yield { ...runtimeEvent, groupKey };
             }
         }
         finally {
+            releasePreparedAttachments();
             this.activeTurns.delete(threadId);
             if (!sawTurnEnd) {
                 // Defensive: if we bailed early, make sure we leave no dangling sink.
@@ -455,15 +477,6 @@ class TurnSink {
         r?.({ kind: "turn_end" });
     }
 }
-/**
- * Codex app-server's `turn/start` expects `input` as an array of content
- * items (each `{ type: "text", text: "..." }` or similar), not a raw string.
- * Wrap the event body so the protocol contract is honoured — sending a bare
- * string has worked historically via undocumented coercion but isn't stable.
- */
-function buildTurnInput(body) {
-    return [{ type: "text", text: body }];
-}
 function ensureGitRepo(workingDirectory) {
     fs.mkdirSync(workingDirectory, { recursive: true });
     // Only `git init` if the workspace isn't already inside any git repo. A
@@ -472,6 +485,7 @@ function ensureGitRepo(workingDirectory) {
     // and silently creating a nested repo there would mangle their layout.
     try {
         execSync("git rev-parse --is-inside-work-tree", { cwd: workingDirectory, stdio: "pipe" });
+        ensureLocalAttachmentGitExclude(workingDirectory);
         return;
     }
     catch {
@@ -487,11 +501,18 @@ function ensureGitRepo(workingDirectory) {
     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.
     }
 }
+function buildTurnInput(body, images) {
+    return [
+        { type: "text", text: body },
+        ...images.map((image) => ({ type: "localImage", path: image.localPath })),
+    ];
+}
 function extractThreadId(result) {
     if (!result || typeof result !== "object")
         return undefined;

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import * as os from "node:os";
 import { ParallAgentGateway, parseShutdownDeadlineMs } from "@parall/agent-core";
-import { ParallClient, ParallWs } from "@parall/sdk";
+import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
 import { buildCodexRuntimeKey, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from "./config.js";
 import { CodexAppServerAdapter } from "./dispatch.js";
 import { CodexSessionManager } from "./session-manager.js";
@@ -13,6 +13,18 @@ function createLogger(prefix) {
         error: (msg) => console.error(`[${prefix}] ${msg}`),
     };
 }
+async function getAgentMeWithLegacyFallback(client, orgId) {
+    try {
+        return await client.getAgentMe(orgId);
+    }
+    catch (err) {
+        if (!(err instanceof ApiError && err.status === 404)) {
+            throw err;
+        }
+        const user = await client.getMe();
+        return { ...user, agent_profile: null };
+    }
+}
 async function main() {
     const config = resolveCodexAgentConfig(process.env);
     const log = createLogger("codex-agent");
@@ -21,9 +33,13 @@ async function main() {
         token: config.apiKey,
         swimlaneName: config.swimlaneName,
     });
-    const me = await client.getMe();
+    const me = await getAgentMeWithLegacyFallback(client, config.orgId);
     const agentUserId = me.id;
-    ensureCodexWorkspace(config.workspaceDir, log, { userId: agentUserId, displayName: me.display_name });
+    ensureCodexWorkspace(config.workspaceDir, log, {
+        userId: agentUserId,
+        displayName: me.display_name,
+        description: me.agent_profile?.description ?? undefined,
+    });
     const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
     const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
     const sessionManager = new CodexSessionManager(runtimeKey, sessionStateFilePath, log);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "src"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.23.0",
-    "@parall/cli": "1.23.0",
-    "@parall/sdk": "1.23.0"
+    "@parall/agent-core": "1.24.0",
+    "@parall/cli": "1.24.0",
+    "@parall/sdk": "1.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch.ts

@@ -2,7 +2,12 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { execSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as path from "node:path";
+import {
+  appendPreparedLocalAttachmentRefs,
+  ensureLocalAttachmentGitExclude,
+  pinLocalAttachmentPaths,
+} from "@parall/agent-core/internal/attachment-input";
+import type { PreparedLocalImage } from "@parall/agent-core/internal/attachment-input";
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -82,7 +87,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
 
   constructor(private readonly opts: CodexAppServerAdapterOptions) {}
 
-  async *dispatch({ bodyForAgent, sessionKey, context }: DispatchOpts): AsyncIterable<RuntimeEvent> {
+  async *dispatch({ event, bodyForAgent, sessionKey, context }: DispatchOpts): AsyncIterable<RuntimeEvent> {
     await this.ensureStarted(context.log);
     // After ensureStarted resolves the subprocess could still die before we
     // capture the client (handleSubprocessClose nulls this.client). Yield a
@@ -145,15 +150,39 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.setActiveTurn(threadId, sink, log);
     const groupKey = randomUUID();
     let sawTurnEnd = false;
+    let releasePreparedAttachments = () => {};
 
     try {
+      let preparedBody = bodyForAgent;
+      let preparedImages: PreparedLocalImage[] = [];
+      try {
+        const prepared = await appendPreparedLocalAttachmentRefs(bodyForAgent, event, context, {
+          workspaceDir: this.opts.workspaceDir,
+          log,
+        });
+        preparedBody = prepared.body;
+        preparedImages = prepared.attachments.images;
+        releasePreparedAttachments = pinLocalAttachmentPaths(preparedImages);
+      } catch (err) {
+        log?.warn?.(`codex-agent[${context.accountId}]: failed to prepare local attachments: ${errToString(err)}`);
+      }
+      // `localImage` is a first-class variant of `UserInput` in the Codex
+      // app-server protocol (codex-rs/app-server-protocol/src/protocol/v2.rs
+      // — it sits alongside `text` and `image`), so we send the combined
+      // text+localImage input directly. If a future Codex release breaks
+      // this contract, we want a hard error surfaced to the operator, not a
+      // silent fallback that hides real protocol drift.
+      const turnInput = buildTurnInput(preparedBody, preparedImages);
+      const startTurn = (targetThreadId: string): Promise<unknown> =>
+        client.sendRequest("turn/start", {
+          threadId: targetThreadId,
+          input: turnInput,
+        });
+
       // Start the turn. If the stored threadId is dead, we retry once with a fresh thread.
       let turnStartResult: unknown;
       try {
-        turnStartResult = await client.sendRequest("turn/start", {
-          threadId,
-          input: buildTurnInput(bodyForAgent),
-        });
+        turnStartResult = await startTurn(threadId);
       } catch (err) {
         const message = errToString(err);
         // For the main session we attempt one fresh-thread retry. Codex CLI's
@@ -179,10 +208,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
         }
         this.setActiveTurn(freshThreadId, sink, log);
         try {
-          turnStartResult = await client.sendRequest("turn/start", {
-            threadId: freshThreadId,
-            input: buildTurnInput(bodyForAgent),
-          });
+          turnStartResult = await startTurn(freshThreadId);
         } catch (retryErr) {
           // Retry also failed — likely transient or systemic, not a stale-thread
           // issue. Don't clobber the persisted threadId; next dispatch will try
@@ -211,23 +237,24 @@ export class CodexAppServerAdapter implements DispatchAdapter {
           yield { type: "error", message: envelope.message };
           continue;
         }
-        const event = envelope.event;
-        if (event.type === "error") {
-          yield event;
+        const runtimeEvent = envelope.event;
+        if (runtimeEvent.type === "error") {
+          yield runtimeEvent;
           continue;
         }
-        if (event.type === "text") {
+        if (runtimeEvent.type === "text") {
           // Layer 0 symmetric output contract: Codex's plain text is never
           // projected as a chat message. Outbound messages must come from the
           // agent explicitly invoking `@parall/cli messages send` / `dm` via
           // the shell/exec tool. Text events are still yielded so agent-core
           // records them as suppressed session steps for audit.
-          yield { ...event, project: false, groupKey };
+          yield { ...runtimeEvent, project: false, groupKey };
           continue;
         }
-        yield { ...event, groupKey };
+        yield { ...runtimeEvent, groupKey };
       }
     } finally {
+      releasePreparedAttachments();
       this.activeTurns.delete(threadId!);
       if (!sawTurnEnd) {
         // Defensive: if we bailed early, make sure we leave no dangling sink.
@@ -505,16 +532,6 @@ class TurnSink {
   }
 }
 
-/**
- * Codex app-server's `turn/start` expects `input` as an array of content
- * items (each `{ type: "text", text: "..." }` or similar), not a raw string.
- * Wrap the event body so the protocol contract is honoured — sending a bare
- * string has worked historically via undocumented coercion but isn't stable.
- */
-function buildTurnInput(body: string): Array<{ type: "text"; text: string }> {
-  return [{ type: "text", text: body }];
-}
-
 function ensureGitRepo(workingDirectory: string): void {
   fs.mkdirSync(workingDirectory, { recursive: true });
   // Only `git init` if the workspace isn't already inside any git repo. A
@@ -523,6 +540,7 @@ function ensureGitRepo(workingDirectory: string): void {
   // and silently creating a nested repo there would mangle their layout.
   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.
@@ -537,11 +555,23 @@ function ensureGitRepo(workingDirectory: string): void {
   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.
   }
 }
 
+type CodexTurnInput =
+  | { type: "text"; text: string }
+  | { type: "localImage"; path: string };
+
+function buildTurnInput(body: string, images: PreparedLocalImage[]): CodexTurnInput[] {
+  return [
+    { type: "text", text: body },
+    ...images.map((image) => ({ type: "localImage" as const, path: image.localPath })),
+  ];
+}
+
 function extractThreadId(result: unknown): string | undefined {
   if (!result || typeof result !== "object") return undefined;
   const r = result as Record<string, unknown>;

package/src/index.ts

@@ -2,7 +2,7 @@
 
 import * as os from "node:os";
 import { ParallAgentGateway, parseShutdownDeadlineMs } from "@parall/agent-core";
-import { ParallClient, ParallWs } from "@parall/sdk";
+import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
 import {
   buildCodexRuntimeKey,
   resolveCodexAgentConfig,
@@ -22,6 +22,18 @@ function createLogger(prefix: string) {
   };
 }
 
+async function getAgentMeWithLegacyFallback(client: ParallClient, orgId: string) {
+  try {
+    return await client.getAgentMe(orgId);
+  } catch (err) {
+    if (!(err instanceof ApiError && err.status === 404)) {
+      throw err;
+    }
+    const user = await client.getMe();
+    return { ...user, agent_profile: null };
+  }
+}
+
 async function main() {
   const config = resolveCodexAgentConfig(process.env);
   const log = createLogger("codex-agent");
@@ -32,9 +44,13 @@ async function main() {
     swimlaneName: config.swimlaneName,
   });
 
-  const me = await client.getMe();
+  const me = await getAgentMeWithLegacyFallback(client, config.orgId);
   const agentUserId = me.id;
-  ensureCodexWorkspace(config.workspaceDir, log, { userId: agentUserId, displayName: me.display_name });
+  ensureCodexWorkspace(config.workspaceDir, log, {
+    userId: agentUserId,
+    displayName: me.display_name,
+    description: me.agent_profile?.description ?? undefined,
+  });
   const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
   const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
   const sessionManager = new CodexSessionManager(