@parall/claude-agent 1.58.2 → 1.60.0

package/src/input-lifecycle.ts

@@ -1,5 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import type { DispatchInputLifecycle, GatewayLogger, RuntimeInputState } from '@parall/agent-core';
+import {
+  type ClaudeTurnSink,
+  newTurnEvidence,
+  newTurnSink,
+  type TurnEvidence,
+} from './turn-sink.js';
 
 export type ClaudeInputDelivery = {
   deliveryKey: string;
@@ -10,6 +16,14 @@ export type ClaudeInputDelivery = {
   terminal?: 'completed' | 'failed' | 'settled';
   reportedState?: RuntimeInputState;
   resultFailed: boolean;
+  /** Envelopes the stdout pump routed to this delivery; drained by its dispatch. */
+  sink: ClaudeTurnSink;
+  /** Turn-outcome evidence gathered while this delivery owned stdout. */
+  evidence: TurnEvidence;
+  /** Dispatch inactivity signal of the dispatch draining (or about to drain) this delivery. */
+  noteActivity?: () => void;
+  /** runtime_session already pushed to this delivery's sink. */
+  sessionAnnounced: boolean;
   /**
    * The turn settled as usage_limit: the lane-level deferred complete will
    * re-deliver this input at retry_at without burning redrive budget. A
@@ -55,21 +69,42 @@ export class ClaudeInputRegistry {
     return [...this.byKey.values()].some((delivery) => delivery.injected && !delivery.drained);
   }
 
+  /**
+   * Injected inputs whose lifecycle has NOT reached a terminal state. A
+   * terminal delivery still counts as pending (its buffered copy owes frame
+   * boundary bookkeeping) but owes the server nothing — the lane complete
+   * defers on this predicate, never on hasPendingInjections, so a bookkeeping
+   * copy that never drains cannot hold the lane open past its lease. Drained
+   * is deliberately NOT part of this predicate: a discarded bookkeeping copy
+   * (drained, non-terminal) is still a running input — completing its lane
+   * would release the member for redrive mid-processing.
+   */
+  hasUnsettledInjections(): boolean {
+    return [...this.byKey.values()].some((delivery) => delivery.injected && !delivery.terminal);
+  }
+
   register(
     deliveryKey: string,
     lifecycle: DispatchInputLifecycle | undefined,
     injected: boolean,
+    noteActivity?: () => void,
+    log?: GatewayLogger,
   ): ClaudeInputDelivery {
     if (this.byKey.has(deliveryKey)) {
       throw new Error(`duplicate Claude delivery key ${deliveryKey}`);
     }
+    const commandUuid = randomUUID();
     const delivery: ClaudeInputDelivery = {
       deliveryKey,
-      commandUuid: randomUUID(),
+      commandUuid,
       lifecycle,
       injected,
       drained: !injected,
       resultFailed: false,
+      sink: newTurnSink(`delivery ${deliveryKey}`, log),
+      evidence: newTurnEvidence(),
+      noteActivity,
+      sessionAnnounced: false,
     };
     this.byKey.set(deliveryKey, delivery);
     this.byCommand.set(delivery.commandUuid, delivery);
@@ -83,6 +118,25 @@ export class ClaudeInputRegistry {
     if (this.byCommand.get(delivery.commandUuid) === delivery) {
       this.byCommand.delete(delivery.commandUuid);
     }
+    // The sink stays open: apply() removes a drained delivery at its
+    // terminal BEFORE the pump pushes the terminal envelope its drain is
+    // waiting for. Only the pump closes sinks (process gone).
+  }
+
+  /**
+   * The buffered copy backing this delivery was discarded without a
+   * dispatch (already rendered into a frame the model saw), so the normal
+   * bookkeeping drain never comes. Its frame-boundary obligation is void:
+   * mark it drained so nothing waits on it, and drop it once terminal. A
+   * still-running input keeps its registration — byCommand must keep routing
+   * its lifecycle frames — and is dropped when its terminal state arrives
+   * (see apply/fail).
+   */
+  discardBookkeeping(deliveryKey: string): void {
+    const delivery = this.byKey.get(deliveryKey);
+    if (!delivery) return;
+    delivery.drained = true;
+    if (delivery.terminal) this.remove(delivery);
   }
 
   async apply(
@@ -108,12 +162,17 @@ export class ClaudeInputRegistry {
       delivery.reportedState = 'completed';
     }
     delivery.terminal = 'completed';
+    // A discarded bookkeeping copy (drained without a dispatch) has no
+    // drain left to remove this entry — drop it at its terminal so it can
+    // never shadow a redelivered batch in findOverlapping.
+    if (delivery.drained) this.remove(delivery);
   }
 
   async fail(delivery: ClaudeInputDelivery): Promise<void> {
     if (delivery.terminal) return;
     if (delivery.suppressFailReport) {
       delivery.terminal = 'settled';
+      if (delivery.drained) this.remove(delivery);
       return;
     }
     try {
@@ -124,6 +183,7 @@ export class ClaudeInputRegistry {
       }
     } finally {
       delivery.terminal ??= 'failed';
+      if (delivery.drained) this.remove(delivery);
     }
   }
 

package/src/output-parser.ts

@@ -27,9 +27,52 @@ export type ClaudeResultMeta = {
   model?: string;
 };
 
+/**
+ * The CLI's background-work frames (`system` subtypes). Every field is
+ * optional except the subtype.
+ * Observed on 2.1.227/2.1.258: `background_tasks_changed` (REPLACE
+ * semantics — every live task after the change), `task_started`,
+ * `task_progress`, `task_updated`, `task_notification` (a task finished or
+ * was stopped), `status`, `session_state_changed` (env-gated).
+ */
+export type ClaudeRuntimeTaskEvent = {
+  type: 'runtime_task';
+  subtype:
+    | 'background_tasks_changed'
+    | 'task_started'
+    | 'task_progress'
+    | 'task_updated'
+    | 'task_notification'
+    | 'status'
+    | 'session_state_changed';
+  taskId?: string;
+  toolUseId?: string;
+  description?: string;
+  taskType?: string;
+  status?: string;
+  summary?: string;
+  isBackgrounded?: boolean;
+  tasks?: Array<{ taskId: string; taskType?: string; description?: string; ambient?: boolean }>;
+};
+
+const RUNTIME_TASK_SUBTYPES = new Set<ClaudeRuntimeTaskEvent['subtype']>([
+  'background_tasks_changed',
+  'task_started',
+  'task_progress',
+  'task_updated',
+  'task_notification',
+  'status',
+  'session_state_changed',
+]);
+
 export type ClaudeParsedEvent =
   | RuntimeEvent
   | { type: 'runtime_init'; sessionId?: string; capabilities: string[] }
+  | ClaudeRuntimeTaskEvent
+  // A root `user` frame that carries text instead of tool results (the
+  // CLI's own injected notices, e.g. a `<task-notification>`). Never a
+  // RuntimeEvent: the model's turn already carries its consequence.
+  | { type: 'user_text'; text: string }
   // Internal-only progress marker for a valid CLI frame whose content must
   // not be projected into the root RuntimeEvent stream (for example, nested
   // subagent output). The dispatch consumer uses it only to refresh runtime
@@ -44,6 +87,10 @@ export type ClaudeParsedEvent =
   // is not a model message — surfaced so the turn-outcome classifier can see
   // the text without it entering the RuntimeEvent stream.
   | { type: 'assistant_error'; message: string }
+  // `system` frame with subtype `compact_boundary`: the CLI folded history
+  // (a manual `/compact` — the idle auto-compact path — or its own
+  // auto-compact mid-turn). Evidence only; never a RuntimeEvent.
+  | { type: 'compact_boundary'; trigger?: string; preTokens?: number }
   // 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
@@ -169,21 +216,49 @@ export async function* parseClaudeStreamJson(
     const eventTimestampMs = parseEventTimestampMs(event) ?? now;
     const eventRecord = event as Record<string, unknown>;
 
-    if (eventRecord.type === 'system' && eventRecord.subtype === 'init') {
-      const sessionId = asTrimmedString(eventRecord.session_id);
-      const capabilities = Array.isArray(eventRecord.capabilities)
-        ? eventRecord.capabilities
-            .map((capability) => asTrimmedString(capability))
-            .filter((capability): capability is string => Boolean(capability))
-        : [];
+    if (eventRecord.type === 'system' && eventRecord.subtype === 'compact_boundary') {
+      const meta =
+        eventRecord.compact_metadata && typeof eventRecord.compact_metadata === 'object'
+          ? (eventRecord.compact_metadata as Record<string, unknown>)
+          : undefined;
+      const trigger = asTrimmedString(meta?.trigger);
+      const preTokens = asFiniteNumber(meta?.pre_tokens);
       yield {
-        type: 'runtime_init',
-        ...(sessionId ? { sessionId } : {}),
-        capabilities,
+        type: 'compact_boundary',
+        ...(trigger ? { trigger } : {}),
+        ...(preTokens !== undefined ? { preTokens } : {}),
       };
       continue;
     }
 
+    if (eventRecord.type === 'system') {
+      if (eventRecord.subtype === 'init') {
+        const sessionId = asTrimmedString(eventRecord.session_id);
+        const capabilities = Array.isArray(eventRecord.capabilities)
+          ? eventRecord.capabilities
+              .map((capability) => asTrimmedString(capability))
+              .filter((capability): capability is string => Boolean(capability))
+          : [];
+        yield {
+          type: 'runtime_init',
+          ...(sessionId ? { sessionId } : {}),
+          capabilities,
+        };
+        continue;
+      }
+      const subtype = asTrimmedString(eventRecord.subtype) as
+        | ClaudeRuntimeTaskEvent['subtype']
+        | undefined;
+      if (subtype && RUNTIME_TASK_SUBTYPES.has(subtype)) {
+        yield parseRuntimeTask(subtype, eventRecord);
+        continue;
+      }
+      // hook_started / hook_response / thinking_tokens /
+      // ...: valid CLI progress with no projection.
+      yield { type: 'runtime_activity' };
+      continue;
+    }
+
     if (eventRecord.type === 'command_lifecycle') {
       const commandUuid = asTrimmedString(eventRecord.command_uuid);
       const state = asTrimmedString(eventRecord.state);
@@ -277,7 +352,17 @@ export async function* parseClaudeStreamJson(
         message && typeof message === 'object'
           ? (message as { content?: unknown }).content
           : undefined;
+      if (typeof content === 'string') {
+        const text = content.trim();
+        if (text) yield { type: 'user_text', text };
+        continue;
+      }
       if (!Array.isArray(content)) continue;
+      if (!content.some((block) => (block as { type?: unknown })?.type === 'tool_result')) {
+        const text = stringifyContent(content).trim();
+        if (text) yield { type: 'user_text', text };
+        continue;
+      }
 
       for (const block of content) {
         if (!block || typeof block !== 'object') continue;
@@ -329,8 +414,53 @@ export async function* parseClaudeStreamJson(
         ...(numTurns !== undefined ? { numTurns } : {}),
         resultMeta: extractResultMeta(eventRecord, isError, numTurns),
       };
+      continue;
+    }
+
+    // Any other well-formed frame (rate_limit_event, stream_event, ...) is
+    // CLI progress: refresh activity, never project.
+    yield { type: 'runtime_activity' };
+  }
+}
+
+function parseRuntimeTask(
+  subtype: ClaudeRuntimeTaskEvent['subtype'],
+  frame: Record<string, unknown>,
+): ClaudeRuntimeTaskEvent {
+  const event: ClaudeRuntimeTaskEvent = { type: 'runtime_task', subtype };
+  const taskId = asTrimmedString(frame.task_id);
+  if (taskId) event.taskId = taskId;
+  const toolUseId = asTrimmedString(frame.tool_use_id);
+  if (toolUseId) event.toolUseId = toolUseId;
+  const description = asTrimmedString(frame.description);
+  if (description) event.description = description;
+  const taskType = asTrimmedString(frame.task_type);
+  if (taskType) event.taskType = taskType;
+  const status =
+    asTrimmedString(frame.status) ??
+    asTrimmedString((frame.patch as { status?: unknown } | undefined)?.status) ??
+    asTrimmedString(frame.state);
+  if (status) event.status = status;
+  const summary = asTrimmedString(frame.summary);
+  if (summary) event.summary = summary;
+  if (typeof frame.is_backgrounded === 'boolean') event.isBackgrounded = frame.is_backgrounded;
+  if (Array.isArray(frame.tasks)) {
+    event.tasks = [];
+    for (const task of frame.tasks) {
+      if (!task || typeof task !== 'object') continue;
+      const record = task as Record<string, unknown>;
+      const id = asTrimmedString(record.task_id);
+      if (!id) continue;
+      const entry: NonNullable<ClaudeRuntimeTaskEvent['tasks']>[number] = { taskId: id };
+      const entryType = asTrimmedString(record.task_type);
+      if (entryType) entry.taskType = entryType;
+      const entryDescription = asTrimmedString(record.description);
+      if (entryDescription) entry.description = entryDescription;
+      if (record.ambient === true) entry.ambient = true;
+      event.tasks.push(entry);
     }
   }
+  return event;
 }
 
 /** Snapshot the result frame's discriminator + usage fields (all optional). */