@parall/claude-agent 1.58.2 → 1.60.0

package/src/busy-state.ts

@@ -0,0 +1,159 @@
+import type { RuntimeBusyState } from '@parall/agent-core';
+import type { ClaudeRuntimeTaskEvent } from './output-parser.js';
+
+export type ClaudeBackgroundTask = {
+  taskId: string;
+  description?: string;
+  /** Ambient tasks (e.g. Monitor) never finish on their own. */
+  ambient: boolean;
+};
+
+export type ClaudeTaskNotification = {
+  taskId?: string;
+  status?: string;
+  summary?: string;
+  description?: string;
+  at: number;
+};
+
+/** Default follow-up hold after a background task finishes (ms). */
+export const DEFAULT_FOLLOW_UP_HOLD_MS = 30_000;
+
+/**
+ * Per-process background-work ledger fed by the CLI's task frames
+ * (`system/background_tasks_changed`, `task_started`, `task_notification`).
+ *
+ * `busy` is: a turn is running, OR a background task finished within the
+ * follow-up hold and the CLI has not yet started (or folded) the follow-up
+ * turn it usually runs on that notification. Outstanding background tasks by
+ * themselves are NOT busy — a `make dev` may run forever and must never
+ * block a restart or a shutdown drain.
+ */
+export class ClaudeBusyTracker {
+  readonly backgroundTasks = new Map<string, ClaudeBackgroundTask>();
+  followUpHoldUntil: number | null = null;
+  lastNotification: ClaudeTaskNotification | undefined;
+  /**
+   * Descriptions of tasks that already left the live set: the REPLACE frame
+   * arrives BEFORE the task_notification for the task it removed, and the
+   * notification itself carries only a summary.
+   */
+  private readonly finishedDescriptions = new Map<string, { description: string; at: number }>();
+
+  constructor(private readonly holdMs: number = DEFAULT_FOLLOW_UP_HOLD_MS) {}
+
+  onTaskFrame(frame: ClaudeRuntimeTaskEvent, now = Date.now()): void {
+    switch (frame.subtype) {
+      case 'background_tasks_changed': {
+        // REPLACE semantics: the frame lists every live task after the change.
+        const next = new Map<string, ClaudeBackgroundTask>();
+        for (const task of frame.tasks ?? []) {
+          const prior = this.backgroundTasks.get(task.taskId);
+          next.set(task.taskId, {
+            taskId: task.taskId,
+            description: task.description ?? prior?.description,
+            ambient: task.ambient ?? prior?.ambient ?? false,
+          });
+        }
+        for (const [id, task] of this.backgroundTasks) {
+          if (!next.has(id) && task.description) {
+            this.finishedDescriptions.set(id, { description: task.description, at: now });
+          }
+        }
+        // Nothing older than takeRecentNotification's horizon is ever read
+        // again: tasks that ended without a notification must not accumulate.
+        for (const [id, entry] of this.finishedDescriptions) {
+          if (now - entry.at > this.holdMs * 2) this.finishedDescriptions.delete(id);
+        }
+        this.backgroundTasks.clear();
+        for (const [id, task] of next) this.backgroundTasks.set(id, task);
+        return;
+      }
+      case 'task_started': {
+        if (!frame.taskId || frame.isBackgrounded === false) return;
+        const prior = this.backgroundTasks.get(frame.taskId);
+        this.backgroundTasks.set(frame.taskId, {
+          taskId: frame.taskId,
+          description: frame.description ?? prior?.description,
+          ambient: prior?.ambient ?? false,
+        });
+        return;
+      }
+      case 'task_notification': {
+        const prior = frame.taskId ? this.backgroundTasks.get(frame.taskId) : undefined;
+        const finished = frame.taskId ? this.finishedDescriptions.get(frame.taskId) : undefined;
+        if (frame.taskId) {
+          this.backgroundTasks.delete(frame.taskId);
+          this.finishedDescriptions.delete(frame.taskId);
+        }
+        this.lastNotification = {
+          taskId: frame.taskId,
+          status: frame.status,
+          summary: frame.summary,
+          description: prior?.description ?? finished?.description ?? frame.description,
+          at: now,
+        };
+        // Unconditional: if the notification folds into a running turn the
+        // hold expires harmlessly (bounded by holdMs).
+        this.followUpHoldUntil = now + this.holdMs;
+        return;
+      }
+      default:
+        return;
+    }
+  }
+
+  /** A turn started (dispatch or runtime-initiated): the hold did its job. */
+  clearHold(): void {
+    this.followUpHoldUntil = null;
+  }
+
+  holdActive(now = Date.now()): boolean {
+    return this.activeHoldUntil(now) !== undefined;
+  }
+
+  /** The hold's expiry while it is still pending, else undefined. */
+  activeHoldUntil(now = Date.now()): number | undefined {
+    return this.followUpHoldUntil !== null && this.followUpHoldUntil > now
+      ? this.followUpHoldUntil
+      : undefined;
+  }
+
+  /** The notification a runtime-initiated turn most plausibly follows. */
+  takeRecentNotification(now = Date.now()): ClaudeTaskNotification | undefined {
+    const notification = this.lastNotification;
+    this.lastNotification = undefined;
+    if (!notification) return undefined;
+    // A notification older than two hold windows is not "recent" — the
+    // turn opening now is more likely unrelated; report it as such.
+    return now - notification.at <= this.holdMs * 2 ? notification : undefined;
+  }
+
+  outstanding(): { total: number; ambient: number } {
+    let ambient = 0;
+    for (const task of this.backgroundTasks.values()) if (task.ambient) ambient += 1;
+    return { total: this.backgroundTasks.size, ambient };
+  }
+
+  /** Background shells die with the process. */
+  reset(): void {
+    this.backgroundTasks.clear();
+    this.finishedDescriptions.clear();
+    this.followUpHoldUntil = null;
+    this.lastNotification = undefined;
+  }
+}
+
+export function aggregateBusyState(states: RuntimeBusyState[]): RuntimeBusyState {
+  let activeTurns = 0;
+  let backgroundWork = 0;
+  let holdUntil: number | undefined;
+  for (const state of states) {
+    activeTurns += state.activeTurns;
+    backgroundWork += state.backgroundWork;
+    if (state.holdUntil !== undefined && (holdUntil === undefined || state.holdUntil > holdUntil)) {
+      holdUntil = state.holdUntil;
+    }
+  }
+  return { activeTurns, backgroundWork, ...(holdUntil !== undefined ? { holdUntil } : {}) };
+}

package/src/compact.ts

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import type { CompactOpts, CompactResult, GatewayLogger } from '@parall/agent-core';
+import type { ProcessState } from './dispatch.js';
+import type { ClaudeInputDelivery } from './input-lifecycle.js';
+import type { ClaudeProcessHandle } from './session-manager.js';
+
+/**
+ * Idle auto-compact on the Claude bridge (idle-auto-compact-design.md §3.4):
+ * write a `/compact` user frame into the long-lived process — the Agent
+ * SDK's documented way to run the built-in — and wait for that command's
+ * lifecycle to settle. The process pump (process-pump.ts) is the only
+ * stdout reader: the command is registered like a dispatch delivery, the
+ * pump routes its frames into the delivery's sink and records the evidence
+ * on it — a `system/compact_boundary` means the CLI folded history (`done`);
+ * a result without one is the CLI declining ("Not enough messages to
+ * compact." — `noop`). The gateway holds the lane, so no dispatch shares the
+ * process while this runs. Nothing here persists steps, sends messages or
+ * touches session status.
+ *
+ * The host is the narrow slice of ClaudeCodeAdapter's process bookkeeping
+ * this needs; the adapter's `compact()` is a thin delegate.
+ */
+export interface ClaudeCompactHost {
+  ensureRuntimeCapability(log: GatewayLogger | undefined): Promise<void>;
+  ensureProcess(sessionKey: string, log: GatewayLogger | undefined): ProcessState;
+  killProcess(sessionKey: string, state: ProcessState): void;
+  writeUserMessage(handle: ClaudeProcessHandle, text: string, commandUuid: string): void;
+  /** Lazy restart re-check once the command settled (the adapter's own gate). */
+  applyPendingRestart(sessionKey: string, state: ProcessState): void;
+}
+
+export async function runClaudeCompact(
+  host: ClaudeCompactHost,
+  { sessionKey, signal, log }: CompactOpts,
+): Promise<CompactResult> {
+  if (signal.aborted) return { status: 'timeout' };
+  let state: ProcessState;
+  try {
+    await host.ensureRuntimeCapability(log);
+    state = host.ensureProcess(sessionKey, log);
+  } catch (err) {
+    return { status: 'failed', detail: `Claude spawn failed: ${String(err)}` };
+  }
+  // Defensive: an injection still owing bookkeeping means a dispatch is
+  // not actually settled on this session — the gateway never gets here in
+  // that state, but a compaction must not steal its frames.
+  if (state.inputs.hasPendingInjections() || state.inputs.hasUnsettledInjections()) {
+    return { status: 'failed', detail: 'injections still pending on the session' };
+  }
+  const delivery = state.inputs.register(`compact:${randomUUID()}`, undefined, false);
+  try {
+    host.writeUserMessage(state.handle, '/compact', delivery.commandUuid);
+  } catch (err) {
+    state.inputs.remove(delivery);
+    host.killProcess(sessionKey, state);
+    return { status: 'failed', detail: `Claude stdin write failed: ${String(err)}` };
+  }
+  try {
+    return await consumeCompact(host, sessionKey, state, delivery, signal, log);
+  } finally {
+    state.inputs.remove(delivery);
+  }
+}
+
+/**
+ * Drain the command's sink until its lifecycle settles. The pump already
+ * did the process bookkeeping (init, lifecycle, EOF); this only reads the
+ * evidence it left on the delivery. On abort the process is SIGTERMed — the
+ * session survives via --resume on the next spawn — and the pump's `killed`
+ * envelope reports `timeout`.
+ */
+async function consumeCompact(
+  host: ClaudeCompactHost,
+  sessionKey: string,
+  state: ProcessState,
+  target: ClaudeInputDelivery,
+  signal: AbortSignal,
+  log: GatewayLogger | undefined,
+): Promise<CompactResult> {
+  const onAbort = () => host.killProcess(sessionKey, state);
+  signal.addEventListener('abort', onAbort, { once: true });
+  // The budget may have expired while the process was being spawned or the
+  // frame written; an abort that already fired never reaches the listener,
+  // and without the kill the sink drain below would never settle — and the
+  // gateway's main-lane hold would leak with it.
+  if (signal.aborted) onAbort();
+  try {
+    while (true) {
+      const next = await target.sink.next();
+      if (next.done) break;
+      const envelope = next.value;
+      if (envelope.kind === 'runtime') continue; // the summary's own frames: progress only
+      if (envelope.kind === 'terminal') break;
+      // The process is gone (eof / killed) or the pump ended this window.
+      const detail = state.handle.stderrChunks.join('').trim();
+      if (detail) log?.warn?.(`subprocess stderr: ${detail}`);
+      if (signal.aborted) return { status: 'timeout', detail: detail || undefined };
+      const exit = await state.handle.exitPromise.catch(
+        () => ({ code: null, signal: null }) as const,
+      );
+      return {
+        status: 'failed',
+        detail:
+          detail ||
+          envelope.message ||
+          `Claude exited with code ${exit.code ?? 'unknown'}${exit.signal ? ` (${exit.signal})` : ''}`,
+      };
+    }
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
+  host.applyPendingRestart(sessionKey, state);
+
+  const { compactBoundary, zeroTurnResultMeta, lastResultMeta } = target.evidence;
+  // The /compact result frame reports num_turns 0 (no model turn ran on the
+  // user's behalf): it is this command's boundary, not the resume poison
+  // frame, so it is read from the zero-turn slot first.
+  const result = zeroTurnResultMeta ?? lastResultMeta;
+  if (compactBoundary) {
+    return {
+      status: 'done',
+      ...(compactBoundary.preTokens !== undefined ? { preTokens: compactBoundary.preTokens } : {}),
+    };
+  }
+  if (result?.isError) {
+    return { status: 'failed', detail: result.resultText || 'compact result reported an error' };
+  }
+  if (target.terminal !== 'completed') {
+    return { status: 'failed', detail: `compact command ${target.terminal}` };
+  }
+  return { status: 'noop', detail: result?.resultText || 'no compact boundary emitted' };
+}