@parall/claude-agent 1.51.0 → 1.52.0

package/src/input-lifecycle.ts

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import type { DispatchInputLifecycle, GatewayLogger, RuntimeInputState } from '@parall/agent-core';
+
+export type ClaudeInputDelivery = {
+  deliveryKey: string;
+  commandUuid: string;
+  lifecycle?: DispatchInputLifecycle;
+  injected: boolean;
+  drained: boolean;
+  terminal?: 'completed' | 'failed' | 'settled';
+  reportedState?: RuntimeInputState;
+  resultFailed: 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
+   * failed-input report here would trigger the immediate failed-input
+   * redrive straight back into the still-choked LLM
+   * (agent-turn-outcome-design.md §6).
+   */
+  suppressFailReport?: boolean;
+};
+
+/**
+ * Per-process registry that maps Parall WorkItem batches to Claude stdin
+ * UUIDs. It owns lifecycle transition rules; process/stdout orchestration
+ * stays in ClaudeCodeAdapter.
+ */
+export class ClaudeInputRegistry {
+  private readonly byKey = new Map<string, ClaudeInputDelivery>();
+  private readonly byCommand = new Map<string, ClaudeInputDelivery>();
+
+  getByKey(deliveryKey: string): ClaudeInputDelivery | undefined {
+    return this.byKey.get(deliveryKey);
+  }
+
+  getByCommand(commandUuid: string): ClaudeInputDelivery | undefined {
+    return this.byCommand.get(commandUuid);
+  }
+
+  values(): IterableIterator<ClaudeInputDelivery> {
+    return this.byKey.values();
+  }
+
+  hasPendingInjections(): boolean {
+    return [...this.byKey.values()].some((delivery) => delivery.injected && !delivery.drained);
+  }
+
+  register(
+    deliveryKey: string,
+    lifecycle: DispatchInputLifecycle | undefined,
+    injected: boolean,
+  ): ClaudeInputDelivery {
+    if (this.byKey.has(deliveryKey)) {
+      throw new Error(`duplicate Claude delivery key ${deliveryKey}`);
+    }
+    const delivery: ClaudeInputDelivery = {
+      deliveryKey,
+      commandUuid: randomUUID(),
+      lifecycle,
+      injected,
+      drained: !injected,
+      resultFailed: false,
+    };
+    this.byKey.set(deliveryKey, delivery);
+    this.byCommand.set(delivery.commandUuid, delivery);
+    return delivery;
+  }
+
+  remove(delivery: ClaudeInputDelivery): void {
+    if (this.byKey.get(delivery.deliveryKey) === delivery) {
+      this.byKey.delete(delivery.deliveryKey);
+    }
+    if (this.byCommand.get(delivery.commandUuid) === delivery) {
+      this.byCommand.delete(delivery.commandUuid);
+    }
+  }
+
+  async apply(
+    delivery: ClaudeInputDelivery,
+    state: 'queued' | 'started' | 'completed' | 'cancelled' | 'discarded',
+  ): Promise<void> {
+    if (delivery.terminal || state === 'queued') return;
+
+    if (state === 'started') {
+      if (delivery.reportedState) return;
+      await delivery.lifecycle?.update('started');
+      delivery.reportedState = 'started';
+      return;
+    }
+
+    if (state === 'cancelled' || state === 'discarded' || delivery.resultFailed) {
+      await this.fail(delivery);
+      return;
+    }
+
+    if (delivery.reportedState !== 'completed') {
+      await delivery.lifecycle?.update('completed');
+      delivery.reportedState = 'completed';
+    }
+    delivery.terminal = 'completed';
+  }
+
+  async fail(delivery: ClaudeInputDelivery): Promise<void> {
+    if (delivery.terminal) return;
+    if (delivery.suppressFailReport) {
+      delivery.terminal = 'settled';
+      return;
+    }
+    try {
+      if (delivery.reportedState !== 'failed') {
+        const result = await delivery.lifecycle?.update('failed');
+        delivery.reportedState = 'failed';
+        delivery.terminal = result?.retry === false ? 'settled' : 'failed';
+      }
+    } finally {
+      delivery.terminal ??= 'failed';
+    }
+  }
+
+  async failBestEffort(delivery: ClaudeInputDelivery, log?: GatewayLogger): Promise<void> {
+    try {
+      await this.fail(delivery);
+    } catch (err) {
+      log?.warn?.(
+        `failed to report Claude input ${delivery.commandUuid} as failed: ${String(err)}`,
+      );
+    }
+  }
+
+  async failAllBestEffort(log?: GatewayLogger): Promise<void> {
+    await Promise.all(
+      [...this.byKey.values()]
+        .filter((delivery) => !delivery.terminal)
+        .map((delivery) => this.failBestEffort(delivery, log)),
+    );
+  }
+}

package/src/output-parser.ts

@@ -1,9 +1,44 @@
 import type { Readable } from 'node:stream';
 import type { RuntimeEvent } from '@parall/agent-core';
 
+/**
+ * Structured snapshot of the `result` frame's LLM-layer discriminators and
+ * accounting — the raw material for turn-outcome classification
+ * (agent-turn-outcome-design.md §4.1). Every field is optional: older CLIs
+ * omit some, and classification degrades gracefully.
+ */
+export type ClaudeResultMeta = {
+  subtype?: string;
+  terminalReason?: string;
+  apiErrorStatus?: number;
+  stopReason?: string;
+  /** The frame's `result` text — synthetic failure notices land here. */
+  resultText?: string;
+  isError: boolean;
+  numTurns?: number;
+  durationMs?: number;
+  durationApiMs?: number;
+  totalCostUsd?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
+  /** First model key of `modelUsage` — the model the CLI actually used. */
+  model?: string;
+};
+
 export type ClaudeParsedEvent =
   | RuntimeEvent
-  | { type: 'session_id'; sessionId: string }
+  | { type: 'runtime_init'; sessionId?: string; capabilities: string[] }
+  | {
+      type: 'command_lifecycle';
+      commandUuid: string;
+      state: 'queued' | 'started' | 'completed' | 'cancelled' | 'discarded';
+    }
+  // Synthetic-notice channel: an `assistant` frame carrying an `error` field
+  // 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 }
   // 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
@@ -21,7 +56,17 @@ export type ClaudeParsedEvent =
   // CLI emits at startup when `--resume` (with or without `--fork-session`)
   // targets a dangling-tail transcript reports 0 — consumers use it to
   // discriminate that poison frame from a real turn boundary.
-  | { type: 'turn_end'; sessionId?: string; isError: boolean; numTurns?: number };
+  //
+  // `resultMeta` carries the frame's full discriminator/usage snapshot for
+  // turn-outcome classification.
+  | {
+      type: 'turn_end';
+      sessionId?: string;
+      userMessageUuid?: string;
+      isError: boolean;
+      numTurns?: number;
+      resultMeta?: ClaudeResultMeta;
+    };
 
 type ToolUseMeta = {
   toolName: string;
@@ -121,14 +166,50 @@ export async function* parseClaudeStreamJson(
 
     if (eventRecord.type === 'system' && eventRecord.subtype === 'init') {
       const sessionId = asTrimmedString(eventRecord.session_id);
-      if (sessionId) {
-        yield { type: 'session_id', sessionId };
+      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;
+    }
+
+    if (eventRecord.type === 'command_lifecycle') {
+      const commandUuid = asTrimmedString(eventRecord.command_uuid);
+      const state = asTrimmedString(eventRecord.state);
+      if (
+        commandUuid &&
+        (state === 'queued' ||
+          state === 'started' ||
+          state === 'completed' ||
+          state === 'cancelled' ||
+          state === 'discarded')
+      ) {
+        yield { type: 'command_lifecycle', commandUuid, state };
       }
       continue;
     }
 
     if (eventRecord.type === 'assistant') {
-      if (eventRecord.error) continue;
+      if (eventRecord.error) {
+        // Not a model message — surface the notice text for turn-outcome
+        // classification instead of silently dropping the frame.
+        const message =
+          asTrimmedString(eventRecord.error) ??
+          asTrimmedString((eventRecord.error as { message?: unknown })?.message);
+        if (message) yield { type: 'assistant_error', message };
+        continue;
+      }
+      // Verbose stream-json includes nested subagent frames. Their final
+      // tool_result returns through the root conversation; projecting their
+      // internal assistant/tool stream here would attribute background work
+      // to whichever root input currently owns stdout.
+      if (asTrimmedString(eventRecord.parent_tool_use_id)) continue;
 
       const message = eventRecord.message;
       const content =
@@ -179,6 +260,7 @@ export async function* parseClaudeStreamJson(
     }
 
     if (eventRecord.type === 'user') {
+      if (asTrimmedString(eventRecord.parent_tool_use_id)) continue;
       const message = eventRecord.message;
       const content =
         message && typeof message === 'object'
@@ -226,12 +308,62 @@ export async function* parseClaudeStreamJson(
       // the map grow unbounded or mislabel durations on id collisions.
       toolUses.clear();
       const numTurns = asFiniteNumber(eventRecord.num_turns);
+      const userMessageUuid =
+        asTrimmedString(eventRecord.user_message_uuid) || asTrimmedString(eventRecord.command_uuid);
       yield {
         type: 'turn_end',
         sessionId: asTrimmedString(eventRecord.session_id),
+        ...(userMessageUuid ? { userMessageUuid } : {}),
         isError,
         ...(numTurns !== undefined ? { numTurns } : {}),
+        resultMeta: extractResultMeta(eventRecord, isError, numTurns),
       };
     }
   }
 }
+
+/** Snapshot the result frame's discriminator + usage fields (all optional). */
+function extractResultMeta(
+  frame: Record<string, unknown>,
+  isError: boolean,
+  numTurns: number | undefined,
+): ClaudeResultMeta {
+  const usage =
+    frame.usage && typeof frame.usage === 'object'
+      ? (frame.usage as Record<string, unknown>)
+      : undefined;
+  const modelUsage =
+    frame.modelUsage && typeof frame.modelUsage === 'object'
+      ? Object.keys(frame.modelUsage as Record<string, unknown>)
+      : [];
+  const meta: ClaudeResultMeta = { isError };
+  if (numTurns !== undefined) meta.numTurns = numTurns;
+  const subtype = asTrimmedString(frame.subtype);
+  if (subtype) meta.subtype = subtype;
+  const terminalReason = asTrimmedString(frame.terminal_reason);
+  if (terminalReason) meta.terminalReason = terminalReason;
+  const apiErrorStatus = asFiniteNumber(frame.api_error_status);
+  if (apiErrorStatus !== undefined) meta.apiErrorStatus = apiErrorStatus;
+  const stopReason = asTrimmedString(frame.stop_reason);
+  if (stopReason) meta.stopReason = stopReason;
+  const resultText = asTrimmedString(frame.result);
+  if (resultText) meta.resultText = resultText;
+  const durationMs = asFiniteNumber(frame.duration_ms);
+  if (durationMs !== undefined) meta.durationMs = durationMs;
+  const durationApiMs = asFiniteNumber(frame.duration_api_ms);
+  if (durationApiMs !== undefined) meta.durationApiMs = durationApiMs;
+  const totalCostUsd = asFiniteNumber(frame.total_cost_usd);
+  if (totalCostUsd !== undefined) meta.totalCostUsd = totalCostUsd;
+  if (usage) {
+    const inputTokens = asFiniteNumber(usage.input_tokens);
+    if (inputTokens !== undefined) meta.inputTokens = inputTokens;
+    const outputTokens = asFiniteNumber(usage.output_tokens);
+    if (outputTokens !== undefined) meta.outputTokens = outputTokens;
+    const cacheReadTokens = asFiniteNumber(usage.cache_read_input_tokens);
+    if (cacheReadTokens !== undefined) meta.cacheReadTokens = cacheReadTokens;
+    const cacheCreationTokens = asFiniteNumber(usage.cache_creation_input_tokens);
+    if (cacheCreationTokens !== undefined) meta.cacheCreationTokens = cacheCreationTokens;
+  }
+  if (modelUsage.length > 0) meta.model = modelUsage[0];
+  return meta;
+}

package/src/turn-outcome.ts

@@ -0,0 +1,177 @@
+import type { TurnOutcomeEvent, TurnUsage } from '@parall/agent-core';
+import type { ClaudeResultMeta } from './output-parser.js';
+
+/**
+ * Claude turn-outcome classifier (agent-turn-outcome-design.md §4.1).
+ *
+ * Detection order is a hard rule: structured fields first
+ * (api_error_status / terminal_reason / is_error), behavioral heuristics
+ * second (zero-usage synthetic turns), message regex last — and regex only
+ * ever refines a classification, so a CLI wording change degrades to the
+ * generic `api_error`, never to a wrong `ok` or a wrong deferral.
+ * Classification uncertainty must never defer: deferring a real message is
+ * costlier than losing one automatic recovery.
+ */
+
+const LIMIT_TEXT = /you'?ve (hit|reached) your .*limit|usage limit reached|weekly limit/i;
+const AUTH_TEXT =
+  /not logged in|please run \/login|authentication_error|invalid api key|oauth token (has )?expired|\[action required\]/i;
+const CONTEXT_TEXT = /prompt is too long|context (window|length) exceeded|request too large/i;
+
+const DETAIL_MAX = 500;
+
+/**
+ * Parse the reset time out of a limit notice like
+ * `You've hit your session limit · resets 1:20am (Asia/Shanghai)` /
+ * `… resets at 11pm (UTC)`. Returns the NEXT occurrence of that wall-clock
+ * time in the given zone as an ISO string, or undefined when the wording
+ * doesn't match — the server then applies its default deferral window.
+ */
+function minutesOfDayInZone(fmt: Intl.DateTimeFormat, at: Date): number {
+  const parts = Object.fromEntries(
+    fmt
+      .formatToParts(at)
+      .filter((p) => p.type !== 'literal')
+      .map((p) => [p.type, Number(p.value)]),
+  ) as Record<string, number>;
+  // "24" can appear for midnight under hour12:false on some ICU versions.
+  const hour = parts.hour === 24 ? 0 : parts.hour;
+  return hour * 60 + parts.minute;
+}
+
+export function parseClaudeResetTime(text: string, now: Date): string | undefined {
+  const m = /resets\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*\(([^)]+)\)/i.exec(text);
+  if (!m) return undefined;
+  let hour = Number(m[1]);
+  const minute = m[2] ? Number(m[2]) : 0;
+  const meridiem = m[3]?.toLowerCase();
+  const timeZone = m[4].trim();
+  if (!Number.isFinite(hour) || hour > 23 || minute > 59) return undefined;
+  if (meridiem === 'pm' && hour < 12) hour += 12;
+  if (meridiem === 'am' && hour === 12) hour = 0;
+
+  // Intl throws on unknown zone names — treat that as no parse.
+  let fmt: Intl.DateTimeFormat;
+  let nowMinutesOfDay: number;
+  try {
+    fmt = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hour12: false,
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+    nowMinutesOfDay = minutesOfDayInZone(fmt, now);
+  } catch {
+    return undefined;
+  }
+  const targetMinutesOfDay = hour * 60 + minute;
+  let deltaMinutes = targetMinutesOfDay - nowMinutesOfDay;
+  if (deltaMinutes <= 0) deltaMinutes += 24 * 60;
+  // Anchor on the real instant (drop seconds so the result lands exactly on
+  // the notice's minute), advance by the wall-clock delta, then CORRECT for
+  // any DST transition inside the interval: wall-clock minutes ≠ elapsed UTC
+  // minutes across a shift, so re-read the candidate's wall-clock in the
+  // zone and nudge by the difference (two rounds absorb a single transition;
+  // a spring-forward nonexistent time settles within an hour, which the
+  // server-side clamp tolerates).
+  const anchored = now.getTime() - (now.getSeconds() * 1000 + now.getMilliseconds());
+  let target = anchored + deltaMinutes * 60_000;
+  for (let i = 0; i < 2; i++) {
+    let diff = targetMinutesOfDay - minutesOfDayInZone(fmt, new Date(target));
+    if (diff > 720) diff -= 1440;
+    if (diff < -720) diff += 1440;
+    if (diff === 0) break;
+    target += diff * 60_000;
+  }
+  if (target <= now.getTime()) target += 24 * 60 * 60_000;
+  return new Date(target).toISOString();
+}
+
+function usageOf(meta: ClaudeResultMeta): TurnUsage | undefined {
+  const usage: TurnUsage = {};
+  if (meta.inputTokens !== undefined) usage.inputTokens = meta.inputTokens;
+  if (meta.outputTokens !== undefined) usage.outputTokens = meta.outputTokens;
+  if (meta.cacheReadTokens !== undefined) usage.cacheReadTokens = meta.cacheReadTokens;
+  if (meta.cacheCreationTokens !== undefined) usage.cacheCreationTokens = meta.cacheCreationTokens;
+  if (meta.totalCostUsd !== undefined) usage.costUsd = meta.totalCostUsd;
+  if (meta.durationMs !== undefined) usage.durationMs = meta.durationMs;
+  if (meta.durationApiMs !== undefined) usage.durationApiMs = meta.durationApiMs;
+  return Object.keys(usage).length > 0 ? usage : undefined;
+}
+
+/**
+ * Classify one finished Claude turn from its result-frame snapshot plus any
+ * synthetic notice texts observed during the turn (assistant_error frames,
+ * zero-usage assistant text like the session-limit notice).
+ */
+export function classifyClaudeTurn(
+  meta: ClaudeResultMeta | undefined,
+  noticeTexts: string[],
+  now: Date = new Date(),
+): TurnOutcomeEvent {
+  if (!meta) {
+    // No result frame reached us (subprocess died mid-turn) — the dispatch
+    // layer's own error path reports the crash; classify what we know.
+    return { type: 'turn_outcome', outcome: 'runtime_crash' };
+  }
+  const usage = usageOf(meta);
+  const evidence = [meta.resultText, ...noticeTexts].filter(Boolean).join('\n');
+  const base = {
+    type: 'turn_outcome' as const,
+    ...(usage ? { usage } : {}),
+    ...(meta.model ? { model: meta.model } : {}),
+    raw: {
+      ...(meta.subtype ? { subtype: meta.subtype } : {}),
+      ...(meta.terminalReason ? { terminal_reason: meta.terminalReason } : {}),
+      ...(meta.apiErrorStatus !== undefined ? { api_error_status: meta.apiErrorStatus } : {}),
+      ...(meta.stopReason ? { stop_reason: meta.stopReason } : {}),
+    },
+  };
+  const withDetail = (
+    outcome: TurnOutcomeEvent['outcome'],
+    retryAt?: string,
+  ): TurnOutcomeEvent => ({
+    ...base,
+    outcome,
+    ...(evidence ? { detail: evidence.slice(0, DETAIL_MAX) } : {}),
+    ...(retryAt ? { retryAt } : {}),
+  });
+
+  // 1) Structured HTTP status.
+  if (meta.apiErrorStatus === 401 || meta.apiErrorStatus === 403) return withDetail('auth');
+  if (meta.apiErrorStatus === 413) return withDetail('context_overflow');
+  if (meta.apiErrorStatus === 429) {
+    return withDetail('usage_limit', evidence ? parseClaudeResetTime(evidence, now) : undefined);
+  }
+
+  // 2) Text families — refine only; they can never turn a failure into ok.
+  const failed =
+    meta.isError ||
+    // Claude CLI 2.1.220 sets terminal_reason=completed on clean result
+    // frames. Any other terminal reason stays fail-closed.
+    (meta.terminalReason !== undefined && meta.terminalReason !== 'completed') ||
+    (meta.subtype !== undefined && meta.subtype !== 'success');
+  const syntheticQuiet =
+    !failed &&
+    // A "successful" turn that never touched the API and produced no tool
+    // activity is the synthetic-notice shape (limit/auth text emitted
+    // locally by the CLI): zero usage + stop_sequence.
+    meta.stopReason === 'stop_sequence' &&
+    (meta.inputTokens ?? 0) === 0 &&
+    (meta.outputTokens ?? 0) === 0 &&
+    (meta.durationApiMs ?? 0) === 0;
+  if (failed || syntheticQuiet || noticeTexts.length > 0) {
+    if (CONTEXT_TEXT.test(evidence)) return withDetail('context_overflow');
+    if (LIMIT_TEXT.test(evidence)) {
+      return withDetail('usage_limit', parseClaudeResetTime(evidence, now));
+    }
+    if (AUTH_TEXT.test(evidence)) return withDetail('auth');
+    // Reached only when this block was entered (failed / syntheticQuiet /
+    // a captured synthetic notice) but no text family matched. A CLI wording
+    // change must degrade to api_error — never fall through to `ok` and settle
+    // a refused turn as success (the read-no-reply class this PR closes).
+    return withDetail('api_error');
+  }
+
+  return { ...base, outcome: 'ok' };
+}