@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/src/runs/shared/chain-outputs.ts

@@ -1,114 +1,206 @@
-import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
-import type { ChainOutputMap, ChainOutputMapEntry } from "../../shared/types.ts";
-import { DynamicFanoutError, hasDynamicFanoutFields, isSafeOutputName, resolveItemTemplate, type DynamicFanoutConfig, validateDynamicStepShape } from "./dynamic-fanout.ts";
+import { isDynamicParallelStep, isParallelStep, type ChainStep } from "../../shared/settings.ts";
+import type { ReadonlyInput, ChainOutputMap, ChainOutputMapEntry } from "../../shared/types.ts";
+import {
+  DynamicFanoutError,
+  hasDynamicFanoutFields,
+  isSafeOutputName,
+  resolveItemTemplate,
+  type DynamicFanoutConfig,
+  validateDynamicStepShape,
+} from "./dynamic-fanout.ts";
 
 const OUTPUT_REF_PATTERN = /\{outputs\.([^}]*)\}/g;
 
 export class ChainOutputValidationError extends Error {}
 
-function outputNamesForStep(step: ChainStep): string[] {
-	if (isParallelStep(step)) return step.parallel.map((task) => task.as).filter((name): name is string => Boolean(name));
-	if (isDynamicParallelStep(step)) return [step.collect.as];
-	const name = (step as SequentialStep).as;
-	return name ? [name] : [];
+function outputNamesForStep(step: ReadonlyInput<ChainStep>): string[] {
+  if (isParallelStep(step)) {
+    return step.parallel.map((task) => task.as).filter((name): name is string => Boolean(name));
+  }
+  if (isDynamicParallelStep(step)) {
+    return [step.collect.as];
+  }
+  const name = step.as;
+  return name !== undefined && name.length > 0 ? [name] : [];
 }
 
-function taskTemplatesForStep(step: ChainStep): string[] {
-	if (isParallelStep(step)) return step.parallel.map((task) => task.task ?? "{previous}");
-	if (isDynamicParallelStep(step)) return [step.parallel.task ?? "{previous}", step.parallel.label ?? ""].filter(Boolean);
-	return [(step as SequentialStep).task ?? "{previous}"];
+function taskTemplatesForStep(step: ReadonlyInput<ChainStep>): string[] {
+  if (isParallelStep(step)) {
+    return step.parallel.map((task) => task.task ?? "{previous}");
+  }
+  if (isDynamicParallelStep(step)) {
+    return [step.parallel.task ?? "{previous}", step.parallel.label ?? ""].filter(Boolean);
+  }
+  return [step.task ?? "{previous}"];
 }
 
-export function validateChainOutputBindings(steps: ChainStep[], dynamicFanoutConfig: DynamicFanoutConfig = {}): void {
-	const available = new Set<string>();
-	const seen = new Set<string>();
-	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
-		const step = steps[stepIndex]!;
-		if (hasDynamicFanoutFields(step)) {
-			if (!isDynamicParallelStep(step)) {
-				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} requires expand, a single parallel template object, and collect; dynamic expand/collect cannot be mixed with static parallel arrays.`);
-			}
-			try {
-				validateDynamicStepShape(step, stepIndex, dynamicFanoutConfig);
-			} catch (error) {
-				if (error instanceof DynamicFanoutError) throw new ChainOutputValidationError(error.message);
-				throw error;
-			}
-			if (!available.has(step.expand.from.output)) {
-				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} references unknown output '${step.expand.from.output}'. Named outputs are only available after producing step/group completes.`);
-			}
-		}
-		for (const name of outputNamesForStep(step)) {
-			if (!isSafeOutputName(name)) {
-				throw new ChainOutputValidationError(`Invalid chain output name '${name}' at step ${stepIndex + 1}. Use /^[A-Za-z_][A-Za-z0-9_]*$/.`);
-			}
-			if (seen.has(name)) {
-				throw new ChainOutputValidationError(`Duplicate chain output name '${name}'. Each as name must be unique.`);
-			}
-			seen.add(name);
-		}
-		for (const template of taskTemplatesForStep(step)) {
-			for (const match of template.matchAll(OUTPUT_REF_PATTERN)) {
-				const rawReference = match[0];
-				const name = match[1]!;
-				if (!isSafeOutputName(name)) {
-					throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}' at step ${stepIndex + 1}. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
-				}
-				if (!available.has(name)) {
-					throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}' at step ${stepIndex + 1}. Named outputs are only available after producing step/group completes.`);
-				}
-			}
-		}
-		for (const name of outputNamesForStep(step)) {
-			available.add(name);
-		}
-	}
+function validateDynamicSource(
+  step: ReadonlyInput<ChainStep>,
+  stepIndex: number,
+  available: readonly string[],
+  config: DynamicFanoutConfig,
+): void {
+  if (!hasDynamicFanoutFields(step)) {
+    return;
+  }
+  if (!isDynamicParallelStep(step)) {
+    throw new ChainOutputValidationError(
+      `Dynamic chain step ${stepIndex + 1} requires expand, a single parallel template object, and collect; dynamic expand/collect cannot be mixed with static parallel arrays.`,
+    );
+  }
+  try {
+    validateDynamicStepShape(step, stepIndex, config);
+  } catch (error) {
+    if (error instanceof DynamicFanoutError) {
+      throw new ChainOutputValidationError(error.message, { cause: error });
+    }
+    throw error;
+  }
+  if (!available.includes(step.expand.from.output)) {
+    throw new ChainOutputValidationError(
+      `Dynamic chain step ${stepIndex + 1} references unknown output '${step.expand.from.output}'. Named outputs are only available after producing step/group completes.`,
+    );
+  }
 }
 
-export function resolveOutputReferences(template: string, outputs: ChainOutputMap): string {
-	return template.replace(OUTPUT_REF_PATTERN, (rawReference, name: string) => {
-		if (!isSafeOutputName(name)) {
-			throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}'. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
-		}
-		const entry = outputs[name];
-		if (!entry) throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}'.`);
-		return entry.text;
-	});
+function validateTemplateBindings(
+  templates: readonly string[],
+  available: readonly string[],
+  stepIndex: number,
+): void {
+  for (const template of templates) {
+    for (const match of template.matchAll(OUTPUT_REF_PATTERN)) {
+      const rawReference = match[0];
+      const name = match[1];
+      if (!isSafeOutputName(name)) {
+        throw new ChainOutputValidationError(
+          `Invalid chain output reference '${rawReference}' at step ${stepIndex + 1}. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`,
+        );
+      }
+      if (!available.includes(name)) {
+        throw new ChainOutputValidationError(
+          `Unknown chain output reference '${rawReference}' at step ${stepIndex + 1}. Named outputs are only available after producing step/group completes.`,
+        );
+      }
+    }
+  }
 }
 
-export function renderChainTask(template: string, values: {
-	originalTask?: string;
-	previousOutput?: string;
-	chainDir?: string;
-	outputs?: ChainOutputMap;
-	item?: { name: string; value: unknown };
-}, placeholder = "{previous}"): string {
-	const pattern = new RegExp(`${placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}|\\{([^{}]*)\\}`, "g");
-	const previousOutput = values.previousOutput ?? "";
-	let usedPrevious = false;
-	const task = template.replace(pattern, (raw, reference: string | undefined) => {
-		if (values.item && (raw === `{${values.item.name}}` || raw.startsWith(`{${values.item.name}.`))) {
-			return resolveItemTemplate(raw, values.item.name, values.item.value);
-		}
-		if (raw === placeholder) {
-			usedPrevious = true;
-			return previousOutput;
-		}
-		if (reference === "task") return values.originalTask ?? "";
-		if (reference === "chain_dir") return values.chainDir ?? "";
-		if (reference?.startsWith("outputs.")) return resolveOutputReferences(raw, values.outputs ?? {});
-		return raw;
-	});
-	return !usedPrevious && previousOutput.trim()
-		? `${task}\n\n---\nPrevious step output:\n${previousOutput.trim()}`
-		: task;
+export function validateChainOutputBindings(
+  steps: readonly ReadonlyInput<ChainStep>[],
+  dynamicFanoutConfig: DynamicFanoutConfig = {},
+): void {
+  const available: string[] = [];
+  const seen = new Set<string>();
+  for (const [stepIndex, step] of steps.entries()) {
+    validateDynamicSource(step, stepIndex, available, dynamicFanoutConfig);
+    for (const name of outputNamesForStep(step)) {
+      if (!isSafeOutputName(name)) {
+        throw new ChainOutputValidationError(
+          `Invalid chain output name '${name}' at step ${stepIndex + 1}. Use /^[A-Za-z_][A-Za-z0-9_]*$/.`,
+        );
+      }
+      if (seen.has(name)) {
+        throw new ChainOutputValidationError(
+          `Duplicate chain output name '${name}'. Each as name must be unique.`,
+        );
+      }
+      seen.add(name);
+    }
+    validateTemplateBindings(taskTemplatesForStep(step), available, stepIndex);
+    for (const name of outputNamesForStep(step)) {
+      available.push(name);
+    }
+  }
 }
 
-export function outputEntryFromResult(result: { agent: string; output: string; structuredOutput?: unknown }, stepIndex: number): ChainOutputMapEntry {
-	return {
-		text: result.structuredOutput !== undefined ? JSON.stringify(result.structuredOutput) : result.output,
-		...(result.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
-		agent: result.agent,
-		stepIndex,
-	};
+export function resolveOutputReferences(
+  template: string,
+  outputs: ReadonlyInput<ChainOutputMap>,
+): string {
+  return template.replace(OUTPUT_REF_PATTERN, (rawReference, name: string) => {
+    if (!isSafeOutputName(name)) {
+      throw new ChainOutputValidationError(
+        `Invalid chain output reference '${rawReference}'. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`,
+      );
+    }
+    const entry: ChainOutputMapEntry | undefined = Object.hasOwn(outputs, name)
+      ? outputs[name]
+      : undefined;
+    if (!entry) {
+      throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}'.`);
+    }
+    return entry.text;
+  });
+}
+
+interface TaskValues {
+  readonly originalTask?: string;
+  readonly previousOutput?: string;
+  readonly chainDir?: string;
+  readonly outputs?: ReadonlyInput<ChainOutputMap>;
+  readonly item?: { readonly name: string; readonly value: unknown };
+}
+
+function isItemPlaceholder(raw: string, name: string): boolean {
+  return raw === `{${name}}` || raw.startsWith(`{${name}.`);
+}
+
+function renderReference(raw: string, reference: string | undefined, values: TaskValues): string {
+  if (values.item && isItemPlaceholder(raw, values.item.name)) {
+    return resolveItemTemplate(raw, values.item.name, values.item.value);
+  }
+  if (reference === "task") {
+    return values.originalTask ?? "";
+  }
+  if (reference === "chain_dir") {
+    return values.chainDir ?? "";
+  }
+  if (reference !== undefined && reference.startsWith("outputs.")) {
+    return resolveOutputReferences(raw, values.outputs ?? {});
+  }
+  return raw;
+}
+
+export function renderChainTask(
+  template: string,
+  values: TaskValues,
+  placeholder = "{previous}",
+): string {
+  const pattern = new RegExp(
+    `${placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}|\\{([^{}]*)\\}`,
+    "g",
+  );
+  const previousOutput = values.previousOutput ?? "";
+  const usedPrevious = [...template.matchAll(pattern)].some(
+    ([raw]) => raw === placeholder && !(values.item && isItemPlaceholder(raw, values.item.name)),
+  );
+  const task = template.replace(pattern, (raw: string, reference: string | undefined) => {
+    // Item placeholders retain precedence if a caller customizes the previous-output placeholder.
+    if (values.item && isItemPlaceholder(raw, values.item.name)) {
+      return renderReference(raw, reference, values);
+    }
+    if (raw === placeholder) {
+      return previousOutput;
+    }
+    return renderReference(raw, reference, values);
+  });
+  return !usedPrevious && previousOutput.trim().length > 0
+    ? `${task}\n\n---\nPrevious step output:\n${previousOutput.trim()}`
+    : task;
+}
+
+export function outputEntryFromResult(
+  result: { readonly agent: string; readonly output: string; readonly structuredOutput?: unknown },
+  stepIndex: number,
+): ChainOutputMapEntry {
+  return {
+    text:
+      result.structuredOutput !== undefined
+        ? JSON.stringify(result.structuredOutput)
+        : result.output,
+    ...(result.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+    agent: result.agent,
+    stepIndex,
+  };
 }

package/src/runs/shared/child-attempt-types.ts

@@ -0,0 +1,118 @@
+import type {
+  AgentProcessExit,
+  ChildMessageHeader,
+  ObservedMessage,
+  ReadonlyInput,
+  ResourceLimitExceeded,
+  Usage,
+  UsageAccumulator,
+} from "../../shared/types.ts";
+import type { StructuredOutputRuntime } from "./structured-output.ts";
+import type { ClaudeCodeInvocation } from "./claude-types.ts";
+import type { NativeFinalizationConfig, NativeFinalizationEvent } from "./native-finalization.ts";
+import type { MutationToolResult } from "./mutating-tool-guard.ts";
+import type { updateStreamingText } from "./streaming-text.ts";
+
+interface ChildEventFields {
+  readonly assistantMessageEvent?: Parameters<
+    typeof updateStreamingText
+  >[1]["assistantMessageEvent"];
+  readonly toolCallId?: string;
+  readonly toolName?: string;
+  readonly args?: Readonly<Record<string, unknown>>;
+  readonly isError?: boolean;
+}
+
+export type ChildEvent = ChildEventFields &
+  (
+    | { readonly type: "message_end"; readonly message?: ObservedMessage }
+    | { readonly type: "message_start" | "message_update"; readonly message?: ChildMessageHeader }
+    | { readonly type?: string; readonly message?: never }
+  );
+
+export interface NativeAttemptSegment {
+  event: NativeFinalizationEvent;
+  messages: ObservedMessage[];
+  usage: Usage;
+  durationMs: number;
+  execution?: Pick<
+    ChildAttemptResult,
+    "exitCode" | "error" | "interrupted" | "timedOut" | "resourceLimitExceeded" | "terminalFailure"
+  >;
+}
+
+export interface ChildAttemptResult {
+  accounting?: { state: "complete" | "incomplete"; error?: string };
+  nativeSessionId?: string;
+  terminalLeafId?: string | null;
+  terminalEntryId?: string;
+  effectiveConfiguration?: { model?: string; thinking?: string; modelRecordedAt?: number };
+  attemptBaseline?: string[];
+  auditPath?: string;
+  auditSaveError?: string;
+  auditRecords?: Array<{ kind: string; messageNumber?: number; offset: number; length: number }>;
+  nativeReferences?: Array<{ messageNumber?: number; entryId: string }>;
+  messageCount?: number;
+  finalization?: NativeAttemptSegment[];
+  stderr: string;
+  agentProcessExit?: AgentProcessExit;
+  exitCode: number;
+  messages: ObservedMessage[];
+  usage: UsageAccumulator;
+  model?: string;
+  error?: string;
+  finalOutput: string;
+  interrupted?: boolean;
+  timedOut?: boolean;
+  terminalFailure?: boolean;
+  observedCompletedMutation: boolean;
+  resourceLimitExceeded?: ResourceLimitExceeded;
+  durationMs: number;
+}
+
+export interface ChildAttemptControl {
+  readonly pid?: number;
+  readonly stopping: boolean;
+  readonly stop: (outcome: Pick<ChildAttemptResult, "error" | "timedOut" | "interrupted">) => void;
+}
+
+export interface ChildAttemptOptions {
+  readonly args: readonly string[];
+  readonly cwd: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly agent: string;
+  readonly model?: string;
+  readonly maxSubagentDepth?: number;
+  readonly maxExecutionTimeMs?: number;
+  readonly maxTokens?: number;
+  readonly claudeCodeInvocation?: ClaudeCodeInvocation;
+  readonly sessionFile?: string;
+  readonly auditPath?: string;
+  readonly structuredOutput?: StructuredOutputRuntime;
+  readonly reportRuntime?: StructuredOutputRuntime;
+  readonly nativeFinalization?: NativeFinalizationConfig;
+  readonly signal?: AbortSignal;
+  readonly interruptSignal?: AbortSignal;
+  readonly onStart?: (
+    control: ChildAttemptControl,
+    result: ReadonlyInput<ChildAttemptResult>,
+  ) => void;
+  readonly onEvent?: (
+    event: ChildEvent,
+    result: ReadonlyInput<ChildAttemptResult>,
+    mutation?: ReadonlyInput<MutationToolResult>,
+  ) => void;
+  readonly onFailure?: (result: ReadonlyInput<ChildAttemptResult>) => void;
+  readonly onOutput?: (text: string) => void;
+  readonly onRawLine?: (stream: "stdout" | "stderr", line: string) => void;
+  readonly onStderr?: (text: string) => void;
+}
+
+export interface ChildObservation {
+  readonly start: number;
+  readonly end: number;
+  readonly kind: string;
+  readonly number?: number;
+  readonly message?: ObservedMessage;
+  readonly nativeEntryId?: string;
+}