@parall/claude-agent 1.31.0 → 1.32.0

package/src/dispatch.ts

@@ -1,11 +1,11 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { randomUUID } from "node:crypto";
-import { execSync, spawn } from "node:child_process";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execSync, spawn } from 'node:child_process';
 import {
   appendPreparedLocalAttachmentRefs,
   pinLocalAttachmentPaths,
-} from "@parall/agent-core/internal/attachment-input";
+} from '@parall/agent-core/internal/attachment-input';
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -13,26 +13,23 @@ import type {
   ForkOpts,
   GatewayLogger,
   RuntimeEvent,
-} from "@parall/agent-core";
-import type { ClaudeAgentConfig } from "./config.js";
-import { parseClaudeStreamJson, type ClaudeParsedEvent } from "./output-parser.js";
-import {
-  ClaudeSessionManager,
-  type ClaudeProcessHandle,
-} from "./session-manager.js";
+} from '@parall/agent-core';
+import type { ClaudeAgentConfig } from './config.js';
+import { parseClaudeStreamJson, type ClaudeParsedEvent } from './output-parser.js';
+import { ClaudeSessionManager, type ClaudeProcessHandle } from './session-manager.js';
 
 type ClaudeCodeAdapterOptions = Pick<
   ClaudeAgentConfig,
-  | "additionalDirs"
-  | "allowApiKey"
-  | "allowedTools"
-  | "appendSystemPrompt"
-  | "claudeBin"
-  | "claudeHome"
-  | "disallowedTools"
-  | "model"
-  | "permissionMode"
-  | "workspaceDir"
+  | 'additionalDirs'
+  | 'allowApiKey'
+  | 'allowedTools'
+  | 'appendSystemPrompt'
+  | 'claudeBin'
+  | 'claudeHome'
+  | 'disallowedTools'
+  | 'model'
+  | 'permissionMode'
+  | 'workspaceDir'
 > & {
   sessionManager: ClaudeSessionManager;
   apiUrl: string;
@@ -43,7 +40,7 @@ type ClaudeCodeAdapterOptions = Pick<
   stepIdFilePathForSession?: (sessionKey: string) => string;
 };
 
-const IS_WIN32 = process.platform === "win32";
+const IS_WIN32 = process.platform === 'win32';
 
 function quoteWin32Arg(arg: string): string {
   if (!/[\s"&|^<>()]/.test(arg)) return arg;
@@ -52,15 +49,17 @@ function quoteWin32Arg(arg: string): string {
 
 function killWin32Tree(pid: number): boolean {
   try {
-    execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: "ignore" });
+    execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
     return true;
-  } catch { return false; }
+  } catch {
+    return false;
+  }
 }
 
 export function buildSpawnEnv(
   parentEnv: NodeJS.ProcessEnv,
   claudeHome: string,
-  context: DispatchOpts["context"],
+  context: DispatchOpts['context'],
   opts: { allowApiKey: boolean; effortLevel?: string },
 ): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...parentEnv };
@@ -74,12 +73,12 @@ export function buildSpawnEnv(
     PRLL_API_URL: context.apiUrl,
     PRLL_API_KEY: context.apiKey,
     PRLL_ORG_ID: context.orgId,
-    PRLL_SESSION_ID: context.sessionId ?? "",
-    PRLL_CHAT_ID: context.chatId ?? "",
-    PRLL_TRIGGER_MESSAGE_ID: context.triggerMessageId ?? "",
-    PRLL_NO_REPLY: context.noReply ? "1" : "",
-    PRLL_CONTEXT_FILE: context.contextFilePath ?? "",
-    PRLL_STEP_ID_FILE: context.stepIdFilePath ?? "",
+    PRLL_SESSION_ID: context.sessionId ?? '',
+    PRLL_CHAT_ID: context.chatId ?? '',
+    PRLL_TRIGGER_MESSAGE_ID: context.triggerMessageId ?? '',
+    PRLL_NO_REPLY: context.noReply ? '1' : '',
+    PRLL_CONTEXT_FILE: context.contextFilePath ?? '',
+    PRLL_STEP_ID_FILE: context.stepIdFilePath ?? '',
   };
   if (opts.effortLevel) {
     result.CLAUDE_CODE_EFFORT_LEVEL = opts.effortLevel;
@@ -113,8 +112,12 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     this._model = opts.model;
   }
 
-  get currentModel(): string | undefined { return this._model; }
-  get currentEffort(): string | undefined { return this._effortLevel; }
+  get currentModel(): string | undefined {
+    return this._model;
+  }
+  get currentEffort(): string | undefined {
+    return this._effortLevel;
+  }
 
   updateConfig(config: { model?: string | null; effort?: string | null }): void {
     const modelChanged = config.model !== undefined && config.model !== this._model;
@@ -142,11 +145,28 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     }
   }
 
+  abortDispatch(sessionKey: string): void {
+    this.pendingInjections.delete(sessionKey);
+    const state = this.processes.get(sessionKey);
+    if (!state || state.done) return;
+    state.done = true;
+    try {
+      state.handle.proc.stdin.end();
+    } catch {
+      /* best-effort */
+    }
+  }
+
   hasPendingInjections(sessionKey: string): boolean {
     return (this.pendingInjections.get(sessionKey) ?? 0) > 0;
   }
 
-  async *dispatch({ event, bodyForAgent, sessionKey, context }: DispatchOpts): AsyncIterable<RuntimeEvent> {
+  async *dispatch({
+    event,
+    bodyForAgent,
+    sessionKey,
+    context,
+  }: DispatchOpts): AsyncIterable<RuntimeEvent> {
     const pending = this.pendingInjections.get(sessionKey) ?? 0;
     if (pending > 0) {
       this.pendingInjections.delete(sessionKey);
@@ -167,9 +187,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       promptBody = prepared.body;
       releasePreparedAttachments = pinLocalAttachmentPaths(prepared.attachments.images);
     } catch (err) {
-      context.log?.warn?.(
-        `failed to prepare local attachments: ${String(err)}`,
-      );
+      context.log?.warn?.(`failed to prepare local attachments: ${String(err)}`);
     }
 
     try {
@@ -186,8 +204,14 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
   getSessionHistoryPath(sessionKey: string): string | undefined {
     const sessionId = this.opts.sessionManager.getSessionId(sessionKey);
     if (!sessionId) return undefined;
-    const projectSlug = this.opts.workspaceDir.replace(/[/.]/g, "-");
-    const filePath = path.join(this.opts.claudeHome, ".claude", "projects", projectSlug, `${sessionId}.jsonl`);
+    const projectSlug = this.opts.workspaceDir.replace(/[/.]/g, '-');
+    const filePath = path.join(
+      this.opts.claudeHome,
+      '.claude',
+      'projects',
+      projectSlug,
+      `${sessionId}.jsonl`,
+    );
     return fs.existsSync(filePath) ? filePath : undefined;
   }
 
@@ -217,7 +241,9 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     await this.opts.sessionManager.shutdownAll();
   }
 
-  private static readonly STEER_TURN_TIMEOUT_MS = 10_000;
+  // Steer-turn read timeout. Overridable via PRLL_STEER_TURN_TIMEOUT_MS (ms),
+  // chiefly so tests can exercise the timeout path without a 10s wait.
+  private readonly steerTurnTimeoutMs = Number(process.env.PRLL_STEER_TURN_TIMEOUT_MS) || 10_000;
 
   /**
    * Consume a steer turn whose message was already written to stdin via
@@ -235,20 +261,31 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
   ): AsyncGenerator<RuntimeEvent> {
     const state = this.processes.get(sessionKey);
     if (!state || state.done) {
-      throw new Error("process dead during steer consumption");
+      throw new Error('process dead during steer consumption');
     }
 
     const groupKey = randomUUID();
 
-    const parserNext = state.parser.next();
+    // Reuse a pull already issued by a prior steer timeout instead of issuing a
+    // fresh one. A burst of N steers all takes the pending-skip path, which calls
+    // this method N times in a loop. Issuing a new state.parser.next() on each
+    // call while a previous pull is still in flight queues multiple reads on the
+    // same async generator, but only one can be stashed in the single-slot
+    // state.steerReadPending — every earlier pull is then consumed-and-dropped,
+    // silently losing parser events. When a dropped event is a tool_call, its
+    // tool_result later orphans into "call_id does not match any tool_call".
+    // Threading the single in-flight pull through every call keeps at most one
+    // outstanding read and loses nothing.
+    const parserNext = state.steerReadPending ?? state.parser.next();
+    state.steerReadPending = undefined;
     const firstRead = await Promise.race([
-      parserNext.then((r) => ({ kind: "value" as const, result: r })),
-      new Promise<{ kind: "timeout" }>((resolve) =>
-        setTimeout(() => resolve({ kind: "timeout" }), ClaudeCodeAdapter.STEER_TURN_TIMEOUT_MS),
+      parserNext.then((r) => ({ kind: 'value' as const, result: r })),
+      new Promise<{ kind: 'timeout' }>((resolve) =>
+        setTimeout(() => resolve({ kind: 'timeout' }), this.steerTurnTimeoutMs),
       ),
     ]);
 
-    if (firstRead.kind === "timeout") {
+    if (firstRead.kind === 'timeout') {
       state.steerReadPending = parserNext;
       log?.info?.(`steer turn timeout — steer was incorporated into previous turn`);
       return;
@@ -260,21 +297,25 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       if (next.done) {
         state.done = true;
         this.processes.delete(sessionKey);
-        throw new Error("process exited while consuming steer turn");
+        throw new Error('process exited while consuming steer turn');
       }
       const parsed = next.value;
 
-      if (parsed.type === "session_id") {
+      if (parsed.type === 'session_id') {
         this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
-        yield { type: "runtime_session", runtimeSessionId: parsed.sessionId, runtimeLaneKey: sessionKey };
-      } else if (parsed.type === "turn_end") {
+        yield {
+          type: 'runtime_session',
+          runtimeSessionId: parsed.sessionId,
+          runtimeLaneKey: sessionKey,
+        };
+      } else if (parsed.type === 'turn_end') {
         if (state.needsRestart) this.killProcess(sessionKey, state);
         return;
-      } else if (parsed.type === "error") {
+      } else if (parsed.type === 'error') {
         yield parsed;
-      } else if (parsed.type === "text") {
+      } else if (parsed.type === 'text') {
         yield { ...parsed, project: false, groupKey };
-      } else if (parsed.type === "runtime_session") {
+      } else if (parsed.type === 'runtime_session') {
         yield parsed;
       } else {
         yield { ...parsed, groupKey };
@@ -292,7 +333,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     try {
       state = this.ensureProcess(sessionKey, log);
     } catch (err) {
-      yield { type: "error", message: `Claude spawn failed: ${String(err)}` };
+      yield { type: 'error', message: `Claude spawn failed: ${String(err)}` };
       return;
     }
     const groupKey = randomUUID();
@@ -301,7 +342,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     try {
       this.writeUserMessage(state.handle, promptBody);
     } catch (err) {
-      yield { type: "error", message: `Claude stdin write failed: ${String(err)}` };
+      yield { type: 'error', message: `Claude stdin write failed: ${String(err)}` };
       this.killProcess(sessionKey, state);
       return;
     }
@@ -311,18 +352,22 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       state.steerReadPending = undefined;
       if (!orphaned.done) {
         const parsed = orphaned.value;
-        if (parsed.type === "session_id") {
+        if (parsed.type === 'session_id') {
           this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
-          yield { type: "runtime_session", runtimeSessionId: parsed.sessionId, runtimeLaneKey: sessionKey };
-        } else if (parsed.type === "turn_end") {
+          yield {
+            type: 'runtime_session',
+            runtimeSessionId: parsed.sessionId,
+            runtimeLaneKey: sessionKey,
+          };
+        } else if (parsed.type === 'turn_end') {
           if (state.needsRestart) this.killProcess(sessionKey, state);
           return;
-        } else if (parsed.type === "error") {
+        } else if (parsed.type === 'error') {
           sawError = true;
           yield parsed;
-        } else if (parsed.type === "text") {
+        } else if (parsed.type === 'text') {
           yield { ...parsed, project: false, groupKey };
-        } else if (parsed.type === "runtime_session") {
+        } else if (parsed.type === 'runtime_session') {
           yield parsed;
         } else {
           yield { ...parsed, groupKey };
@@ -336,16 +381,19 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
       if (next.done) {
         state.done = true;
         this.processes.delete(sessionKey);
-        const detail = state.handle.stderrChunks.join("").trim();
-        const exit = await state.handle.exitPromise.catch(() => ({ code: null, signal: null } as const));
+        const detail = state.handle.stderrChunks.join('').trim();
+        const exit = await state.handle.exitPromise.catch(
+          () => ({ code: null, signal: null }) as const,
+        );
         if (detail) {
           log?.warn?.(`subprocess stderr: ${detail}`);
         }
         if (!sawError) {
           yield {
-            type: "error",
-            message: detail
-              || `Claude exited with code ${exit.code ?? "unknown"}${exit.signal ? ` (${exit.signal})` : ""}`,
+            type: 'error',
+            message:
+              detail ||
+              `Claude exited with code ${exit.code ?? 'unknown'}${exit.signal ? ` (${exit.signal})` : ''}`,
           };
         }
         return;
@@ -353,35 +401,35 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
 
       const parsed = next.value;
 
-      if (parsed.type === "session_id") {
+      if (parsed.type === 'session_id') {
         this.opts.sessionManager.recordSessionId(sessionKey, parsed.sessionId);
         yield {
-          type: "runtime_session",
+          type: 'runtime_session',
           runtimeSessionId: parsed.sessionId,
           runtimeLaneKey: sessionKey,
         };
         continue;
       }
 
-      if (parsed.type === "turn_end") {
+      if (parsed.type === 'turn_end') {
         if (state.needsRestart) {
           this.killProcess(sessionKey, state);
         }
         return;
       }
 
-      if (parsed.type === "error") {
+      if (parsed.type === 'error') {
         sawError = true;
         yield parsed;
         continue;
       }
 
-      if (parsed.type === "text") {
+      if (parsed.type === 'text') {
         yield { ...parsed, project: false, groupKey };
         continue;
       }
 
-      if (parsed.type === "runtime_session") {
+      if (parsed.type === 'runtime_session') {
         yield parsed;
         continue;
       }
@@ -392,7 +440,7 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
 
   private ensureProcess(sessionKey: string, log: GatewayLogger | undefined): ProcessState {
     if (this.shuttingDown) {
-      throw new Error("adapter shutting down, refusing new process");
+      throw new Error('adapter shutting down, refusing new process');
     }
 
     const existing = this.processes.get(sessionKey);
@@ -425,39 +473,43 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     );
 
     log?.info(
-      `spawn long-lived ${this.opts.claudeBin} (session ${sessionKey}, model=${this._model || "default"}, effort=${this._effortLevel || "default"}, mode=${this.opts.permissionMode})`,
+      `spawn long-lived ${this.opts.claudeBin} (session ${sessionKey}, model=${this._model || 'default'}, effort=${this._effortLevel || 'default'}, mode=${this.opts.permissionMode})`,
     );
 
     const proc = spawn(
       IS_WIN32 ? quoteWin32Arg(this.opts.claudeBin) : this.opts.claudeBin,
-      IS_WIN32 ? args.map(quoteWin32Arg) : args, {
-      cwd: this.opts.workspaceDir,
-      env,
-      stdio: ["pipe", "pipe", "pipe"],
-      shell: IS_WIN32,
-    });
+      IS_WIN32 ? args.map(quoteWin32Arg) : args,
+      {
+        cwd: this.opts.workspaceDir,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: IS_WIN32,
+      },
+    );
 
     if (!proc.stdout || !proc.stderr || !proc.stdin) {
-      throw new Error("Claude subprocess did not provide stdio pipes");
+      throw new Error('Claude subprocess did not provide stdio pipes');
     }
 
     const stderrChunks: string[] = [];
-    proc.stderr.on("data", (chunk: Buffer) => {
+    proc.stderr.on('data', (chunk: Buffer) => {
       stderrChunks.push(chunk.toString());
     });
-    proc.stdin.on("error", () => {
+    proc.stdin.on('error', () => {
       proc.stdin.destroy();
       if (proc.exitCode === null && proc.signalCode === null) {
         if (!IS_WIN32 || !proc.pid || !killWin32Tree(proc.pid)) {
-          proc.kill("SIGTERM");
+          proc.kill('SIGTERM');
         }
       }
     });
 
-    const exitPromise = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
-      proc.once("close", (code, signal) => resolve({ code, signal }));
-      proc.once("error", () => resolve({ code: null, signal: null }));
-    });
+    const exitPromise = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(
+      (resolve) => {
+        proc.once('close', (code, signal) => resolve({ code, signal }));
+        proc.once('error', () => resolve({ code: null, signal: null }));
+      },
+    );
 
     return { proc, exitPromise, stderrChunks };
   }
@@ -470,22 +522,26 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
     }
     try {
       state.handle.proc.stdin.end();
-    } catch { /* best-effort */ }
+    } catch {
+      /* best-effort */
+    }
     if (state.handle.proc.exitCode === null && state.handle.proc.signalCode === null) {
       try {
         if (!IS_WIN32 || !state.handle.proc.pid || !killWin32Tree(state.handle.proc.pid)) {
-          state.handle.proc.kill("SIGTERM");
+          state.handle.proc.kill('SIGTERM');
         }
-      } catch { /* best-effort */ }
+      } catch {
+        /* best-effort */
+      }
     }
   }
 
   private writeUserMessage(handle: ClaudeProcessHandle, text: string) {
     const payload = JSON.stringify({
-      type: "user",
+      type: 'user',
       message: {
-        role: "user",
-        content: [{ type: "text", text }],
+        role: 'user',
+        content: [{ type: 'text', text }],
       },
     });
     handle.proc.stdin.write(`${payload}\n`);
@@ -493,60 +549,60 @@ export class ClaudeCodeAdapter implements DispatchAdapter {
 
   private buildArgs(sessionKey: string): string[] {
     const args = [
-      "--verbose",
-      "--input-format",
-      "stream-json",
-      "--output-format",
-      "stream-json",
-      "--permission-mode",
+      '--verbose',
+      '--input-format',
+      'stream-json',
+      '--output-format',
+      'stream-json',
+      '--permission-mode',
       this.opts.permissionMode,
     ];
 
     if (this._model) {
-      args.push("--model", this._model);
+      args.push('--model', this._model);
     }
 
     if (this.opts.allowedTools.length > 0) {
-      args.push("--allowedTools", this.opts.allowedTools.join(","));
+      args.push('--allowedTools', this.opts.allowedTools.join(','));
     }
 
     if (this.opts.disallowedTools.length > 0) {
-      args.push("--disallowedTools", this.opts.disallowedTools.join(","));
+      args.push('--disallowedTools', this.opts.disallowedTools.join(','));
     }
 
     args.push(
-      "--append-system-prompt-file",
-      path.join(this.opts.workspaceDir, ".parall", "system-prompt.md"),
+      '--append-system-prompt-file',
+      path.join(this.opts.workspaceDir, '.parall', 'system-prompt.md'),
     );
 
     if (this.opts.appendSystemPrompt) {
-      args.push("--append-system-prompt", this.opts.appendSystemPrompt);
+      args.push('--append-system-prompt', this.opts.appendSystemPrompt);
     }
 
     if (this.opts.additionalDirs.length > 0) {
-      args.push("--add-dir", ...this.opts.additionalDirs);
+      args.push('--add-dir', ...this.opts.additionalDirs);
     }
 
     args.push(...this.opts.sessionManager.getResumeArgs(sessionKey));
     return args;
   }
 
-  private buildPlaceholderContext(sessionKey: string): DispatchOpts["context"] {
+  private buildPlaceholderContext(sessionKey: string): DispatchOpts['context'] {
     return {
-      accountId: "",
+      accountId: '',
       apiUrl: this.opts.apiUrl,
       apiKey: this.opts.apiKey,
       orgId: this.opts.orgId,
-      agentUserId: "",
-      runtimeType: "",
-      runtimeKey: "",
-      sessionId: "",
-      chatId: "",
-      triggerMessageId: "",
+      agentUserId: '',
+      runtimeType: '',
+      runtimeKey: '',
+      sessionId: '',
+      chatId: '',
+      triggerMessageId: '',
       noReply: false,
-      contextFilePath: this.opts.contextFilePathForSession?.(sessionKey) ?? "",
-      stepIdFilePath: this.opts.stepIdFilePathForSession?.(sessionKey) ?? "",
-      client: undefined as unknown as DispatchOpts["context"]["client"],
+      contextFilePath: this.opts.contextFilePathForSession?.(sessionKey) ?? '',
+      stepIdFilePath: this.opts.stepIdFilePathForSession?.(sessionKey) ?? '',
+      client: undefined as unknown as DispatchOpts['context']['client'],
     };
   }
 }