@parall/claude-agent 1.24.0 → 1.26.0

package/src/index.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 import * as os from "node:os";
-import { ParallAgentGateway, parseShutdownDeadlineMs } from "@parall/agent-core";
+import { ParallAgentGateway, createPlatformConfigManager, isPlatformManagedProfile, parseShutdownDeadlineMs } from "@parall/agent-core";
 import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
 import {
   buildClaudeRuntimeKey,
+  contextFilePathForSession,
   resolveClaudeAgentConfig,
   resolveWsUrl,
   sessionStateFilePathForRuntime,
@@ -77,11 +78,21 @@ async function main() {
     wsUrl: resolvedWsUrl,
   });
 
+  const configMgr = createPlatformConfigManager({ client, stateDir: config.stateDir, runtimeType: "claude-code", log });
+  const platformDefaults = await configMgr.fetch();
+  let platformManaged = isPlatformManagedProfile(me.agent_profile);
+  const resolvedModel = platformManaged ? (platformDefaults.model ?? config.model) : config.model;
+  const resolvedEffort = platformManaged
+    ? (platformDefaults.thinkingEffort ?? (process.env.CLAUDE_CODE_EFFORT_LEVEL?.trim() || undefined))
+    : (process.env.CLAUDE_CODE_EFFORT_LEVEL?.trim() || undefined);
+  if (platformDefaults.model) log.info(`platform config: model=${platformDefaults.model} (${platformManaged ? "applied" : "ignored, model_management=self"})`);
+  if (platformDefaults.thinkingEffort) log.info(`platform config: thinking_effort=${platformDefaults.thinkingEffort} (${platformManaged ? "applied" : "ignored, model_management=self"})`);
+
   const adapter = new ClaudeCodeAdapter({
     claudeBin: config.claudeBin,
     claudeHome: config.claudeHome,
     workspaceDir: config.workspaceDir,
-    model: config.model,
+    model: resolvedModel,
     permissionMode: config.permissionMode,
     allowedTools: config.allowedTools,
     disallowedTools: config.disallowedTools,
@@ -89,7 +100,18 @@ async function main() {
     appendSystemPrompt: config.appendSystemPrompt,
     allowApiKey: config.allowApiKey,
     sessionManager,
+    // Static Parall credentials. The long-lived subprocess must authenticate
+    // against Parall's API across many dispatches, so these cannot come from
+    // a per-dispatch DispatchContext.
+    apiUrl: config.apiUrl,
+    apiKey: config.apiKey,
+    orgId: config.orgId,
+    contextFilePathForSession: (sessionKey) => contextFilePathForSession(config.stateDir, sessionKey),
+    stepIdFilePathForSession: (sessionKey) => stepIdFilePathForSession(config.stateDir, sessionKey),
   });
+  if (resolvedEffort) {
+    adapter.updateConfig({ effort: resolvedEffort });
+  }
 
   const gateway = new ParallAgentGateway({
     accountId: agentUserId,
@@ -113,7 +135,33 @@ async function main() {
     dispatchAdapter: adapter,
     log,
     shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
+    contextFilePathForSession: (sessionKey) => contextFilePathForSession(config.stateDir, sessionKey),
     stepIdFilePathForSession: (sessionKey) => stepIdFilePathForSession(config.stateDir, sessionKey),
+    onConfigUpdate: async () => {
+      const refreshed = await getAgentMeWithLegacyFallback(client, config.orgId);
+      platformManaged = isPlatformManagedProfile(refreshed.agent_profile);
+      const updated = await configMgr.fetch();
+      const localEffort = process.env.CLAUDE_CODE_EFFORT_LEVEL?.trim() || null;
+      adapter.updateConfig({
+        model: platformManaged ? (updated.model ?? config.model) : (config.model ?? null),
+        effort: platformManaged ? (updated.thinkingEffort ?? localEffort) : localEffort,
+      });
+    },
+    onSessionReady: async () => {
+      const refreshed = await getAgentMeWithLegacyFallback(client, config.orgId);
+      platformManaged = isPlatformManagedProfile(refreshed.agent_profile);
+      const updated = await configMgr.fetch();
+      const localEffort = process.env.CLAUDE_CODE_EFFORT_LEVEL?.trim() || null;
+      adapter.updateConfig({
+        model: platformManaged ? (updated.model ?? config.model) : (config.model ?? null),
+        effort: platformManaged ? (updated.thinkingEffort ?? localEffort) : localEffort,
+      });
+    },
+    // Long-lived `claude` subprocesses outlive a single dispatch, so the
+    // gateway's shuttingDown flag alone does not tear them down. Piggyback on
+    // onBeforeDisconnect to close stdin and SIGTERM any survivors after
+    // in-flight drains finish.
+    onBeforeDisconnect: () => adapter.shutdown(),
   });
 
   const abortController = new AbortController();

package/src/output-parser.ts

@@ -3,7 +3,18 @@ import type { RuntimeEvent } from "@parall/agent-core";
 
 export type ClaudeParsedEvent =
   | RuntimeEvent
-  | { type: "session_id"; sessionId: string };
+  | { type: "session_id"; sessionId: string }
+  // turn_end is emitted for every `result` frame (both `is_error: true` and
+  // `is_error: false`); `isError` carries the frame's status so the consumer
+  // can tell a clean turn boundary from a failed one without inspecting the
+  // error event that preceded it. In stream-json input mode a single
+  // `claude` subprocess processes many sequential user turns on one
+  // long-lived stdout stream, so the per-dispatch caller needs a signal to
+  // stop consuming after exactly one turn without tearing down the shared
+  // stream. For a short-lived `--print <prompt>` invocation the final
+  // `result` frame arrives right before stdout EOF, so this event is
+  // redundant there — safe to ignore.
+  | { type: "turn_end"; sessionId?: string; isError: boolean };
 
 type ToolUseMeta = {
   toolName: string;
@@ -184,11 +195,25 @@ export async function* parseClaudeStreamJson(readable: Readable): AsyncGenerator
       continue;
     }
 
-    if (eventRecord.type === "result" && eventRecord.is_error === true) {
-      const message = asTrimmedString(eventRecord.result)
-        || asTrimmedString(eventRecord.error)
-        || "Claude dispatch failed";
-      yield { type: "error", message };
+    if (eventRecord.type === "result") {
+      const isError = eventRecord.is_error === true;
+      if (isError) {
+        const message = asTrimmedString(eventRecord.result)
+          || asTrimmedString(eventRecord.error)
+          || "Claude dispatch failed";
+        yield { type: "error", message };
+      }
+      // Turn boundary: the subprocess lives across many turns, so any
+      // tool_use entries that never matched a tool_result this turn
+      // (tool crashed mid-call, Claude aborted, etc.) must not leak into
+      // the next turn's accounting. Drop them here rather than letting
+      // the map grow unbounded or mislabel durations on id collisions.
+      toolUses.clear();
+      yield {
+        type: "turn_end",
+        sessionId: asTrimmedString(eventRecord.session_id),
+        isError,
+      };
     }
   }
 }

package/src/session-manager.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { ForkSessionHandle } from "@parall/agent-core";
 
 type PersistedMainSession = {
@@ -12,9 +13,16 @@ type ClaudeSessionManagerLogger = {
   warn(message: string): void;
 };
 
+export type ClaudeProcessHandle = {
+  proc: ChildProcessWithoutNullStreams;
+  exitPromise: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+  stderrChunks: string[];
+};
+
 export class ClaudeSessionManager {
   private readonly sessionIds = new Map<string, string>();
   private readonly pendingForkParents = new Map<string, string>();
+  private readonly processes = new Map<string, ClaudeProcessHandle>();
 
   constructor(
     private readonly mainSessionKey: string,
@@ -57,6 +65,142 @@ export class ClaudeSessionManager {
   cleanupFork(sessionKey: string) {
     this.pendingForkParents.delete(sessionKey);
     this.sessionIds.delete(sessionKey);
+    const handle = this.processes.get(sessionKey);
+    if (handle) {
+      this.processes.delete(sessionKey);
+      this.closeHandle(handle, `fork ${sessionKey} cleanup`);
+    }
+  }
+
+  getProcess(sessionKey: string): ClaudeProcessHandle | undefined {
+    return this.processes.get(sessionKey);
+  }
+
+  registerProcess(sessionKey: string, handle: ClaudeProcessHandle) {
+    const existing = this.processes.get(sessionKey);
+    if (existing && existing !== handle) {
+      this.logger?.warn(
+        `claude-agent: replacing existing process handle for ${sessionKey}; closing previous`,
+      );
+      this.closeHandle(existing, `replaced for ${sessionKey}`);
+    }
+    this.processes.set(sessionKey, handle);
+    // Auto-clear on exit so the map does not accumulate dead handles.
+    handle.exitPromise
+      .finally(() => {
+        const current = this.processes.get(sessionKey);
+        if (current === handle) {
+          this.processes.delete(sessionKey);
+        }
+      })
+      .catch(() => {
+        // exitPromise is resolved, never rejected, but guard anyway.
+      });
+  }
+
+  clearProcess(sessionKey: string, handle?: ClaudeProcessHandle) {
+    const current = this.processes.get(sessionKey);
+    if (!current) return;
+    if (handle && current !== handle) return;
+    this.processes.delete(sessionKey);
+  }
+
+  /** Grace period (ms) between SIGTERM and SIGKILL during shutdown. */
+  private static readonly SHUTDOWN_GRACE_MS = 5_000;
+
+  async shutdownAll(): Promise<void> {
+    const handles = [...this.processes.entries()];
+    this.processes.clear();
+    await Promise.all(
+      handles.map(([sessionKey, handle]) => this.shutdownOne(sessionKey, handle)),
+    );
+  }
+
+  private async shutdownOne(sessionKey: string, handle: ClaudeProcessHandle): Promise<void> {
+    this.closeHandle(handle, `shutdown ${sessionKey}`);
+    // Wait for SIGTERM to take effect, but bound the wait: if the child
+    // ignores SIGTERM (buggy tool, uninterruptible syscall, etc.) we must
+    // not block the whole agent exit forever. Escalate to SIGKILL after the
+    // grace window and then wait once more for the kernel to reap it.
+    const timedOut = await this.raceWithTimeout(
+      handle.exitPromise,
+      ClaudeSessionManager.SHUTDOWN_GRACE_MS,
+    );
+    if (!timedOut) return;
+
+    if (handle.proc.exitCode === null && handle.proc.signalCode === null) {
+      this.logger?.warn(
+        `claude-agent: SIGTERM timed out for ${sessionKey}, escalating to SIGKILL`,
+      );
+      try {
+        handle.proc.kill("SIGKILL");
+      } catch (error) {
+        this.logger?.warn(
+          `claude-agent: SIGKILL failed for ${sessionKey}: ${String(error)}`,
+        );
+      }
+    }
+    // Bound the post-SIGKILL wait too: on the rare kernel path where even
+    // SIGKILL delivery is delayed (uninterruptible D-state, zombie reaping
+    // stuck on a parent bookkeeping path), gateway disconnect must still
+    // make progress. Warn and move on if the reap is not observed in time.
+    const killTimedOut = await this.raceWithTimeout(
+      handle.exitPromise,
+      ClaudeSessionManager.SHUTDOWN_GRACE_MS,
+    );
+    if (killTimedOut) {
+      this.logger?.warn(
+        `claude-agent: subprocess for ${sessionKey} not reaped after SIGKILL within ${ClaudeSessionManager.SHUTDOWN_GRACE_MS}ms; continuing shutdown`,
+      );
+    }
+  }
+
+  /**
+   * Wait up to `ms` for `promise`. Resolves `false` if the promise settled
+   * in time, `true` if the timeout fired first. Never rejects.
+   */
+  private raceWithTimeout(promise: Promise<unknown>, ms: number): Promise<boolean> {
+    return new Promise<boolean>((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        resolve(true);
+      }, ms);
+      // Don't keep the event loop alive purely on the timeout.
+      if (typeof timer.unref === "function") timer.unref();
+      promise
+        .catch(() => {
+          /* exitPromise does not reject; guard anyway */
+        })
+        .finally(() => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(false);
+        });
+    });
+  }
+
+  private closeHandle(handle: ClaudeProcessHandle, reason: string) {
+    try {
+      if (!handle.proc.stdin.destroyed) {
+        handle.proc.stdin.end();
+      }
+    } catch (error) {
+      this.logger?.warn(
+        `claude-agent: failed to close stdin (${reason}): ${String(error)}`,
+      );
+    }
+    if (handle.proc.exitCode === null && handle.proc.signalCode === null) {
+      try {
+        handle.proc.kill("SIGTERM");
+      } catch (error) {
+        this.logger?.warn(
+          `claude-agent: failed to SIGTERM claude subprocess (${reason}): ${String(error)}`,
+        );
+      }
+    }
   }
 
   private restore() {

package/src/workspace.ts

@@ -5,6 +5,8 @@ import {
   PRLL_BEHAVIOR,
   PRLL_REFERENCE_GUIDE,
   buildIdentity,
+  buildSkillReferences,
+  writeSkillFiles,
 } from "@parall/agent-core";
 import type { AgentIdentity } from "@parall/agent-core";
 import { ensureLocalAttachmentGitExclude } from "@parall/agent-core/internal/attachment-input";
@@ -14,35 +16,21 @@ export function ensureClaudeWorkspace(
   log?: { warn: (msg: string) => void },
   agentIdentity?: AgentIdentity,
 ) {
-  const CLAUDE_MD = [
+  const systemPrompt = [
     buildIdentity(agentIdentity),
     BRIDGE_WORKSPACE_INSTRUCTIONS,
     PRLL_BEHAVIOR,
     PRLL_REFERENCE_GUIDE,
+    buildSkillReferences(workspaceDir),
   ].join("\n\n");
+
   fs.mkdirSync(workspaceDir, { recursive: true });
   fs.mkdirSync(path.join(workspaceDir, ".claude"), { recursive: true });
 
-  // CLAUDE.md is bridge-managed: always overwrite so a hosted PVC keeps the
-  // current guardrails (e.g. the `no-reply` instruction). Operators must not
-  // hand-edit this file — workspace customizations should go into AGENTS.md
-  // / SOUL.md / TOOLS.md, which are env-driven and untouched here. Surface a
-  // warning when we replace a file whose content diverges, so an operator
-  // who did edit it locally gets a signal instead of silently losing changes.
-  const claudeMdPath = path.join(workspaceDir, "CLAUDE.md");
-  if (log) {
-    try {
-      const existing = fs.readFileSync(claudeMdPath, "utf8");
-      if (existing !== CLAUDE_MD) {
-        log.warn(
-          `claude-agent: overwriting divergent ${claudeMdPath} with bridge-managed template ` +
-            `(local edits to CLAUDE.md are not preserved — customize AGENTS.md / SOUL.md / TOOLS.md instead)`,
-        );
-      }
-    } catch {
-      // file missing or unreadable — first-boot case, no warning needed
-    }
-  }
-  fs.writeFileSync(claudeMdPath, CLAUDE_MD, "utf8");
+  const parallDir = path.join(workspaceDir, ".parall");
+  fs.mkdirSync(parallDir, { recursive: true });
+  fs.writeFileSync(path.join(parallDir, "system-prompt.md"), systemPrompt, "utf8");
+
+  writeSkillFiles(path.join(parallDir, "skills"));
   ensureLocalAttachmentGitExclude(workspaceDir);
 }