@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

package/dist/builtin/workflows/src/shared/authoring-contract-ui.d.ts

@@ -67,19 +67,48 @@ export interface WorkflowRunContext<TInputs extends WorkflowInputValues = Workfl
      */
     tool: WorkflowToolPrimitive;
 }
-/**
- * `ctx.tool` primitive signature. Runs an async function and caches the result.
- */
-export interface WorkflowToolPrimitive {
-    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolOptions): Promise<TValue>;
+/** Serializable process details copied from an exhausted `ctx.tool` callback error. */
+export interface WorkflowToolError extends WorkflowSerializableObject {
+    readonly name: string;
+    readonly message: string;
+    readonly exitCode?: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+}
+export interface WorkflowToolSuccess<TValue extends WorkflowSerializableValue> extends WorkflowSerializableObject {
+    readonly ok: true;
+    readonly value: TValue;
+    readonly attempts: number;
+    readonly cached: boolean;
 }
-/** Options for `ctx.tool`. */
+export interface WorkflowToolFailure extends WorkflowSerializableObject {
+    readonly ok: false;
+    readonly error: WorkflowToolError;
+    readonly attempts: number;
+    readonly cached: boolean;
+}
+/** Typed result returned when `failureMode: "return"` is selected. */
+export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> = WorkflowToolSuccess<TValue> | WorkflowToolFailure;
+/** Options for `ctx.tool`. Throwing after exhausted retries remains the default. */
 export interface WorkflowToolOptions {
+    readonly failureMode?: "throw" | "return";
     readonly retriesAllowed?: boolean;
     readonly maxAttempts?: number;
     readonly intervalMs?: number;
     readonly backoffRate?: number;
 }
+export type WorkflowToolReturnOptions = WorkflowToolOptions & {
+    readonly failureMode: "return";
+};
+export type WorkflowToolThrowOptions = WorkflowToolOptions & {
+    readonly failureMode?: "throw";
+};
+/** `ctx.tool` runs an async function and durably caches its serializable result. */
+export interface WorkflowToolPrimitive {
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options: WorkflowToolReturnOptions): Promise<WorkflowToolOutcome<TValue>>;
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolThrowOptions): Promise<TValue>;
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolOptions): Promise<TValue | WorkflowToolOutcome<TValue>>;
+}
 export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues, TDefinitionBrand extends object = {}> = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<TOutputs> | TOutputs;
 export interface WorkflowRuntimeConfig {
     readonly maxDepth: number;
@@ -210,15 +239,37 @@ export interface StageSnapshot extends WorkflowSerializableObject {
     readonly result?: WorkflowSerializableValue;
     readonly error?: string;
 }
+export interface ToolNodeSnapshot extends WorkflowSerializableObject {
+    readonly kind: "tool";
+    /** Stable durable node identity. */
+    readonly id: string;
+    readonly name: string;
+    readonly argsHash: string;
+    readonly ordinal: number;
+    readonly parentIds: readonly string[];
+    readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
+    readonly topologyState?: "unavailable";
+    readonly replayed?: boolean;
+    readonly executionOrder?: number;
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+    readonly resultSummary?: string;
+    readonly error?: string;
+    readonly attachable: false;
+}
 export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
     readonly runId: string;
     readonly status: RunStatus;
     readonly result?: Partial<TOutputs>;
     readonly error?: string;
+    /** Tool node whose rejection supplied the selected terminal failure. */
+    readonly failedToolNodeId?: string;
     /** True when the run reached its terminal status through ctx.exit(). */
     readonly exited?: boolean;
     readonly exitReason?: string;
     readonly stages: readonly StageSnapshot[];
+    /** Always populated by the runtime; optional for legacy structural literals. */
+    readonly toolNodes?: readonly ToolNodeSnapshot[];
 }
 export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> & WorkflowSerializableObject;
 export interface GitWorktreeSetupOptions extends WorkflowSerializableObject {

package/dist/builtin/workflows/src/shared/authoring-contract-ui.ts

@@ -115,26 +115,68 @@ export interface WorkflowRunContext<
   tool: WorkflowToolPrimitive;
 }
 
-/**
- * `ctx.tool` primitive signature. Runs an async function and caches the result.
- */
-export interface WorkflowToolPrimitive {
-  <TValue extends WorkflowSerializableValue>(
-    name: string,
-    args: Readonly<Record<string, WorkflowSerializableValue>>,
-    fn: () => Promise<TValue>,
-    options?: WorkflowToolOptions,
-  ): Promise<TValue>;
+/** Serializable process details copied from an exhausted `ctx.tool` callback error. */
+export interface WorkflowToolError extends WorkflowSerializableObject {
+  readonly name: string;
+  readonly message: string;
+  readonly exitCode?: number;
+  readonly stdout?: string;
+  readonly stderr?: string;
+}
+
+export interface WorkflowToolSuccess<TValue extends WorkflowSerializableValue> extends WorkflowSerializableObject {
+  readonly ok: true;
+  readonly value: TValue;
+  readonly attempts: number;
+  readonly cached: boolean;
+}
+
+export interface WorkflowToolFailure extends WorkflowSerializableObject {
+  readonly ok: false;
+  readonly error: WorkflowToolError;
+  readonly attempts: number;
+  readonly cached: boolean;
 }
 
-/** Options for `ctx.tool`. */
+/** Typed result returned when `failureMode: "return"` is selected. */
+export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> =
+  | WorkflowToolSuccess<TValue>
+  | WorkflowToolFailure;
+
+/** Options for `ctx.tool`. Throwing after exhausted retries remains the default. */
 export interface WorkflowToolOptions {
+  readonly failureMode?: "throw" | "return";
   readonly retriesAllowed?: boolean;
   readonly maxAttempts?: number;
   readonly intervalMs?: number;
   readonly backoffRate?: number;
 }
 
+export type WorkflowToolReturnOptions = WorkflowToolOptions & { readonly failureMode: "return" };
+export type WorkflowToolThrowOptions = WorkflowToolOptions & { readonly failureMode?: "throw" };
+
+/** `ctx.tool` runs an async function and durably caches its serializable result. */
+export interface WorkflowToolPrimitive {
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options: WorkflowToolReturnOptions,
+  ): Promise<WorkflowToolOutcome<TValue>>;
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options?: WorkflowToolThrowOptions,
+  ): Promise<TValue>;
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options?: WorkflowToolOptions,
+  ): Promise<TValue | WorkflowToolOutcome<TValue>>;
+}
+
 export type WorkflowRunFn<
   TInputs extends WorkflowInputValues = WorkflowInputValues,
   TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
@@ -290,15 +332,38 @@ export interface StageSnapshot extends WorkflowSerializableObject {
   readonly error?: string;
 }
 
+export interface ToolNodeSnapshot extends WorkflowSerializableObject {
+  readonly kind: "tool";
+  /** Stable durable node identity. */
+  readonly id: string;
+  readonly name: string;
+  readonly argsHash: string;
+  readonly ordinal: number;
+  readonly parentIds: readonly string[];
+  readonly status: "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
+  readonly topologyState?: "unavailable";
+  readonly replayed?: boolean;
+  readonly executionOrder?: number;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly resultSummary?: string;
+  readonly error?: string;
+  readonly attachable: false;
+}
+
 export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
   readonly runId: string;
   readonly status: RunStatus;
   readonly result?: Partial<TOutputs>;
   readonly error?: string;
+  /** Tool node whose rejection supplied the selected terminal failure. */
+  readonly failedToolNodeId?: string;
   /** True when the run reached its terminal status through ctx.exit(). */
   readonly exited?: boolean;
   readonly exitReason?: string;
   readonly stages: readonly StageSnapshot[];
+  /** Always populated by the runtime; optional for legacy structural literals. */
+  readonly toolNodes?: readonly ToolNodeSnapshot[];
 }
 
 export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> & WorkflowSerializableObject;

package/dist/builtin/workflows/src/shared/expanded-workflow-graph.ts

@@ -1,8 +1,8 @@
-import type {
-  RunSnapshot,
-  StageSnapshot,
-  StoreSnapshot,
-} from "./store-types.js";
+import type { RunSnapshot, StageSnapshot, StoreSnapshot, ToolNodeSnapshot } from "./store-types.js";
+import {
+  authoritativeWorkflowChildRunId,
+  reciprocalWorkflowRootRunId,
+} from "./workflow-run-ownership.js";
 
 export interface ExpandedWorkflowStageTarget {
   readonly runId: string;
@@ -15,29 +15,72 @@ export interface ExpandedWorkflowStage extends StageSnapshot {
   readonly workflowGraphTarget: ExpandedWorkflowStageTarget;
 }
 
+export interface ExpandedWorkflowTool extends ToolNodeSnapshot {
+  readonly runId: string;
+  readonly runName: string;
+  readonly depth: number;
+}
+
+export type ExpandedWorkflowNode =
+  | { readonly kind: "stage"; readonly stage: ExpandedWorkflowStage }
+  | { readonly kind: "tool"; readonly tool: ExpandedWorkflowTool };
+
 export interface ExpandedWorkflowGraph {
+  /** Stage-only inspection/control nodes; excludes tool projections. */
   readonly stages: readonly ExpandedWorkflowStage[];
+  readonly tools: readonly ExpandedWorkflowTool[];
+  readonly nodes: readonly ExpandedWorkflowNode[];
+  /** All stage-compatible render projections, including non-attachable tool cards. */
+  readonly renderStages: readonly ExpandedWorkflowStage[];
+  /** Stage targets only; tool nodes intentionally have no chat/control target. */
   readonly targets: ReadonlyMap<string, ExpandedWorkflowStageTarget>;
 }
 
 interface ExpandedRunResult {
   readonly stages: ExpandedWorkflowStage[];
+  readonly tools: ExpandedWorkflowTool[];
+  readonly nodes: ExpandedWorkflowNode[];
   readonly terminalIds: readonly string[];
 }
 
-function virtualStageId(runId: string, stageId: string, isRootRun: boolean): string {
-  return isRootRun ? stageId : `${runId}:${stageId}`;
+type LocalItem =
+  | { readonly kind: "stage"; readonly stage: StageSnapshot; readonly sourceIndex: number }
+  | { readonly kind: "tool"; readonly tool: ToolNodeSnapshot; readonly sourceIndex: number };
+
+function virtualNodeId(runId: string, nodeId: string, isRootRun: boolean): string {
+  return isRootRun ? nodeId : `${runId}:${nodeId}`;
+}
+
+function localItems(run: RunSnapshot): LocalItem[] {
+  const stages = run.stages.map((stage, sourceIndex) => ({ kind: "stage" as const, stage, sourceIndex }));
+  const tools = (run.toolNodes ?? []).map((tool, sourceIndex) => ({ kind: "tool" as const, tool, sourceIndex }));
+  return [...stages, ...tools].sort((left, right) => {
+    const leftOrder = left.kind === "stage" ? left.stage.executionOrder : left.tool.executionOrder;
+    const rightOrder = right.kind === "stage" ? right.stage.executionOrder : right.tool.executionOrder;
+    if (leftOrder !== undefined || rightOrder !== undefined) return (leftOrder ?? Number.MAX_SAFE_INTEGER) - (rightOrder ?? Number.MAX_SAFE_INTEGER);
+    if (left.kind !== right.kind) return left.kind === "stage" ? -1 : 1;
+    return left.sourceIndex - right.sourceIndex;
+  });
+}
+
+function itemId(item: LocalItem): string {
+  return item.kind === "stage" ? item.stage.id : item.tool.id;
+}
+
+function itemParents(item: LocalItem): readonly string[] {
+  return item.kind === "stage" ? item.stage.parentIds : item.tool.parentIds;
+}
+
+function localTerminalIds(items: readonly LocalItem[]): readonly string[] {
+  const parents = new Set(items.flatMap((item) => [...itemParents(item)]));
+  const terminals = items.map(itemId).filter((id) => !parents.has(id));
+  return terminals.length > 0 ? terminals : items.map(itemId);
 }
 
 function isTerminalNonCompletedBoundary(stage: StageSnapshot): boolean {
   return stage.status === "failed" || stage.status === "skipped";
 }
 
-function childRunIdFor(stage: StageSnapshot): string | undefined {
-  if (isTerminalNonCompletedBoundary(stage)) return undefined;
-  if (stage.status === "completed") return stage.workflowChild?.runId ?? stage.workflowChildRun?.runId;
-  return stage.workflowChildRun?.runId;
-}
 
 function childAliasFor(stage: StageSnapshot): string | undefined {
   if (isTerminalNonCompletedBoundary(stage)) return undefined;
@@ -45,142 +88,189 @@ function childAliasFor(stage: StageSnapshot): string | undefined {
   return stage.workflowChildRun?.alias;
 }
 
-function localTerminalStageIds(stages: readonly StageSnapshot[]): readonly string[] {
-  const parentIds = new Set<string>();
-  for (const stage of stages) {
-    for (const parentId of stage.parentIds) parentIds.add(parentId);
-  }
-  const terminals = stages
-    .filter((stage) => !parentIds.has(stage.id))
-    .map((stage) => stage.id);
-  return terminals.length > 0 ? terminals : stages.map((stage) => stage.id);
-}
-
-/**
- * Build a view-only expanded graph for a run and any nested child workflow
- * runs it references. Child stages are cloned with virtual ids so their local
- * parent ids do not collide with parent-run stage ids; each virtual node keeps
- * a target mapping back to the actual `{ runId, stageId }` for attach/control.
- *
- * Imported workflows are flattened: a boundary stage that wraps a child run
- * with its own stages is NOT emitted as its own node. Instead the child's
- * stages stand in for it, so a nested workflow reads as a flat layout with no
- * extra "information" node marking the import boundary. The boundary's incoming
- * parents become the child roots' parents, and stages downstream of the
- * boundary rewire to the child's terminal stages. A boundary whose child run
- * produced no stages of its own is kept as a single node so the import stays
- * visible. Boundary stages are non-attachable, so dropping them loses no
- * interactive capability.
- */
-export function expandWorkflowGraph(
-  snapshot: StoreSnapshot,
-  rootRunId: string,
-): ExpandedWorkflowGraph {
+function projectedToolStatus(tool: ToolNodeSnapshot): StageSnapshot["status"] {
+  if (tool.status === "cached") return "completed";
+  if (tool.status === "cancelled") return "skipped";
+  return tool.status;
+}
+
+export function expandWorkflowGraph(snapshot: StoreSnapshot, rootRunId: string): ExpandedWorkflowGraph {
   const runById = new Map(snapshot.runs.map((run) => [run.id, run]));
   const root = runById.get(rootRunId);
-  if (!root) return { stages: [], targets: new Map() };
-
+  if (!root) return { stages: [], renderStages: [], tools: [], nodes: [], targets: new Map() };
   const targets = new Map<string, ExpandedWorkflowStageTarget>();
-  // Cycle guard only. This relies on the store invariant that each child run is
-  // referenced by exactly one parent stage (runIds are unique and a child run
-  // has a single boundary stage), so removing a run from `visiting` on exit
-  // cannot double-expand a shared child into duplicate virtual stage ids. If
-  // that invariant is ever relaxed, dedupe expanded stages by virtual id here.
+  const rootOwnerByRunId = new Map<string, string | undefined>();
+  const rootOwnerFor = (runId: string): string | undefined => {
+    if (rootOwnerByRunId.has(runId)) return rootOwnerByRunId.get(runId);
+    const owner = reciprocalWorkflowRootRunId(runById, runId);
+    rootOwnerByRunId.set(runId, owner);
+    return owner;
+  };
   const visiting = new Set<string>();
+  const expandedChildren = new Set<string>();
 
-  const expandRun = (
-    run: RunSnapshot,
-    depth: number,
-    incomingParentIds: readonly string[],
-  ): ExpandedRunResult => {
-    if (visiting.has(run.id)) return { stages: [], terminalIds: [] };
+  const expandRun = (run: RunSnapshot, depth: number, incomingParentIds: readonly string[]): ExpandedRunResult => {
+    if (visiting.has(run.id)) return { stages: [], tools: [], nodes: [], terminalIds: [] };
     visiting.add(run.id);
-
     const isRootRun = run.id === rootRunId;
-    const expandedStages: ExpandedWorkflowStage[] = [];
-    const replacementTerminals = new Map<string, readonly string[]>();
-
-    for (const stage of run.stages) {
-      const id = virtualStageId(run.id, stage.id, isRootRun);
-      const resolvedParentIds = stage.parentIds.length === 0
-        ? [...incomingParentIds]
-        : stage.parentIds.flatMap((parentId) =>
-            replacementTerminals.get(parentId) ?? [virtualStageId(run.id, parentId, isRootRun)],
-          );
-
-      const childRunId = childRunIdFor(stage);
-      const childRun = childRunId === undefined ? undefined : runById.get(childRunId);
-
-      // Flatten the imported workflow in place: when the boundary wraps a child
-      // run that has its own stages, splice those stages in instead of emitting
-      // the boundary node. Child roots inherit the boundary's incoming parents,
-      // and downstream stages rewire to the child's terminals below.
-      if (childRun !== undefined && childRun.stages.length > 0) {
-        const childExpanded = expandRun(childRun, depth + 1, resolvedParentIds);
-        expandedStages.push(...childExpanded.stages);
-        replacementTerminals.set(
-          stage.id,
-          childExpanded.terminalIds.length > 0 ? childExpanded.terminalIds : resolvedParentIds,
-        );
+    const items = localItems(run);
+    const stages: ExpandedWorkflowStage[] = [];
+    const tools: ExpandedWorkflowTool[] = [];
+    const nodes: ExpandedWorkflowNode[] = [];
+    const stageById = new Map(run.stages.map((stage) => [stage.id, stage]));
+    const boundaryExpansions = new Map<string, ExpandedRunResult | null>();
+
+    const validChildRunFor = (stage: StageSnapshot): RunSnapshot | undefined => {
+      const childRunId = authoritativeWorkflowChildRunId(stage);
+      if (childRunId === undefined) return undefined;
+      const childRun = runById.get(childRunId);
+      const runRoot = rootOwnerFor(run.id);
+      if (
+        childRun === undefined ||
+        expandedChildren.has(childRun.id) ||
+        localItems(childRun).length === 0 ||
+        childRun.parentRunId !== run.id ||
+        childRun.parentStageId !== stage.id ||
+        runRoot === undefined ||
+        rootOwnerFor(childRun.id) !== runRoot
+      ) {
+        return undefined;
+      }
+      return childRun;
+    };
+
+    const resolvedParentIdsFor = (item: LocalItem): string[] => {
+      const parentIds = itemParents(item);
+      if (parentIds.length === 0) return [...incomingParentIds];
+      return parentIds.flatMap((parentId) => {
+        const parentStage = stageById.get(parentId);
+        const parentExpansion = parentStage === undefined
+          ? undefined
+          : boundaryExpansionFor(parentStage);
+        return parentExpansion?.terminalIds.length
+          ? [...parentExpansion.terminalIds]
+          : [virtualNodeId(run.id, parentId, isRootRun)];
+      });
+    };
+
+    const boundaryExpansionFor = (stage: StageSnapshot): ExpandedRunResult | undefined => {
+      const cached = boundaryExpansions.get(stage.id);
+      if (cached !== undefined) return cached ?? undefined;
+      const childRun = validChildRunFor(stage);
+      if (childRun === undefined) return undefined;
+      boundaryExpansions.set(stage.id, null);
+      expandedChildren.add(childRun.id);
+      const stageItem: LocalItem = { kind: "stage", stage, sourceIndex: 0 };
+      const childExpanded = expandRun(childRun, depth + 1, resolvedParentIdsFor(stageItem));
+      if (childExpanded.stages.length === 0 || childExpanded.terminalIds.length === 0) return undefined;
+      boundaryExpansions.set(stage.id, childExpanded);
+      return childExpanded;
+    };
+
+    for (const item of items) {
+      const sourceId = itemId(item);
+      const id = virtualNodeId(run.id, sourceId, isRootRun);
+      const resolvedParentIds = resolvedParentIdsFor(item);
+
+      if (item.kind === "tool") {
+        const tool: ExpandedWorkflowTool = {
+          ...item.tool,
+          id,
+          parentIds: Object.freeze(resolvedParentIds),
+          runId: run.id,
+          runName: run.name,
+          depth,
+        };
+        const projectionTarget: ExpandedWorkflowStageTarget = {
+          runId: run.id,
+          stageId: item.tool.id,
+          runName: run.name,
+          depth,
+        };
+        const projection: ExpandedWorkflowStage = {
+          id,
+          name: item.tool.name,
+          status: projectedToolStatus(item.tool),
+          parentIds: Object.freeze(resolvedParentIds),
+          executionOrder: item.tool.executionOrder,
+          nodeKind: "tool",
+          toolStatus: item.tool.status,
+          startedAt: item.tool.startedAt,
+          endedAt: item.tool.endedAt,
+          result: item.tool.resultSummary,
+          error: item.tool.error,
+          toolEvents: [],
+          attachable: false,
+          workflowGraphTarget: projectionTarget,
+        };
+        tools.push(tool);
+        stages.push(projection);
+        nodes.push({ kind: "tool", tool });
+        continue;
+      }
+
+      const childExpanded = boundaryExpansionFor(item.stage);
+      if (childExpanded !== undefined) {
+        stages.push(...childExpanded.stages);
+        tools.push(...childExpanded.tools);
+        nodes.push(...childExpanded.nodes);
         continue;
       }
 
-      // Regular stage, or a boundary whose child produced no stages of its own:
-      // emit it so the import still appears as exactly one node.
       const target: ExpandedWorkflowStageTarget = {
         runId: run.id,
-        stageId: stage.id,
+        stageId: item.stage.id,
         runName: run.name,
         depth,
       };
       targets.set(id, target);
-      expandedStages.push({
-        ...stage,
+      const stage: ExpandedWorkflowStage = {
+        ...item.stage,
         id,
         parentIds: Object.freeze(resolvedParentIds),
         workflowGraphTarget: target,
-      });
+      };
+      stages.push(stage);
+      nodes.push({ kind: "stage", stage });
     }
 
-    const terminalIds = localTerminalStageIds(run.stages).flatMap((stageId) =>
-      replacementTerminals.get(stageId) ?? [virtualStageId(run.id, stageId, isRootRun)],
-    );
-
+    const terminalIds = localTerminalIds(items).flatMap((sourceId) => {
+      const stage = stageById.get(sourceId);
+      const replacement = stage === undefined ? undefined : boundaryExpansionFor(stage);
+      return replacement?.terminalIds.length
+        ? [...replacement.terminalIds]
+        : [virtualNodeId(run.id, sourceId, isRootRun)];
+    });
     visiting.delete(run.id);
-    return { stages: expandedStages, terminalIds };
+    return { stages, tools, nodes, terminalIds };
   };
 
   const expanded = expandRun(root, 0, []);
-  return { stages: expanded.stages, targets };
+  return {
+    stages: expanded.stages.filter((stage) => stage.nodeKind !== "tool"),
+    renderStages: expanded.stages,
+    tools: expanded.tools,
+    nodes: expanded.nodes,
+    targets,
+  };
 }
 
-export function expandedStageTarget(
-  graph: ExpandedWorkflowGraph,
-  virtualStageIdValue: string,
-): ExpandedWorkflowStageTarget | undefined {
+export function expandedStageTarget(graph: ExpandedWorkflowGraph, virtualStageIdValue: string): ExpandedWorkflowStageTarget | undefined {
   return graph.targets.get(virtualStageIdValue);
 }
 
-export function stageMatchesExpandedIdentifier(
-  stage: ExpandedWorkflowStage,
-  target: string,
-): boolean {
-  return (
-    stage.id === target ||
-    stage.name === target ||
-    stage.id.startsWith(target) ||
-    stage.workflowGraphTarget.stageId === target ||
-    stage.workflowGraphTarget.stageId.startsWith(target) ||
-    stage.workflowGraphTarget.runId === target ||
-    stage.workflowGraphTarget.runId.startsWith(target)
-  );
+export function stageMatchesExpandedIdentifier(stage: ExpandedWorkflowStage, target: string): boolean {
+  const graphTarget = stage.workflowGraphTarget;
+  return stage.id === target || stage.name === target || stage.id.startsWith(target)
+    || graphTarget.stageId === target || graphTarget.stageId.startsWith(target)
+    || graphTarget.runId === target || graphTarget.runId.startsWith(target);
 }
 
 export function expandedStageLabel(stage: ExpandedWorkflowStage): string {
-  const runPrefix = stage.workflowGraphTarget.runId.slice(0, 8);
-  const stagePrefix = stage.workflowGraphTarget.stageId.slice(0, 8);
-  const depthPrefix = stage.workflowGraphTarget.depth > 0
-    ? `${childAliasFor(stage) ?? stage.workflowGraphTarget.runName}:`
-    : "";
+  const target = stage.workflowGraphTarget;
+  if (stage.nodeKind === "tool") return `${stage.name} (tool)`;
+  const runPrefix = target.runId.slice(0, 8);
+  const stagePrefix = target.stageId.slice(0, 8);
+  const depthPrefix = target.depth > 0 ? `${childAliasFor(stage) ?? target.runName}:` : "";
   return `${depthPrefix}${stage.name} (${runPrefix}/${stagePrefix})`;
 }

package/dist/builtin/workflows/src/shared/intercom-group.ts

@@ -4,6 +4,11 @@ import type { StageOptions } from "./types.js";
 /** The implicit group shared by every ungrouped session. */
 export const DEFAULT_INTERCOM_GROUP = "default";
 
+/** Stable non-default home group for every stage in one top-level workflow invocation. */
+export function workflowInvocationIntercomGroup(rootRunId: string): string {
+  return `workflow:${rootRunId}`;
+}
+
 /** Normalize authored or agent-serialized auto-group sentinels without changing real group names. */
 export function normalizeAutoGroupSentinel(group: string | true): string | true {
   if (group === true) return true;
@@ -19,17 +24,19 @@ export function normalizeGroup(value?: string | null): string {
 }
 
 /**
- * Resolve a stage's `group` option to a concrete home-group string, or undefined
- * when the stage did not request a group (so the intercom layer falls back to
- * env/config/default). A named string is trimmed; a bare `true` that survives to
- * this point (a single, non-parallel stage) mints one fresh UUID for that stage.
- * Parallel sets resolve `true` to one shared UUID upstream, so it never reaches
- * here as `true`.
+ * Resolve a stage's home group. An explicit authored group wins over the
+ * workflow invocation group. A named string is trimmed; a bare `true` that
+ * survives to this point (a single, non-parallel stage) mints one fresh UUID
+ * for that stage. Parallel sets resolve `true` to one shared UUID upstream.
+ * Without a workflow group, omission keeps the legacy env/config/default path.
  */
-export function resolveStageGroup(stageOptions?: { group?: string | true }): string | undefined {
-  if (!stageOptions) return undefined;
+export function resolveStageGroup(
+  stageOptions?: { group?: string | true },
+  workflowGroup?: string,
+): string | undefined {
+  if (!stageOptions) return workflowGroup;
   const group = stageOptions.group;
-  if (group === undefined) return undefined;
+  if (group === undefined) return workflowGroup;
   if (group === true) return randomUUID();
   const trimmed = group.trim();
   return trimmed.length > 0 ? trimmed : undefined;
@@ -42,7 +49,7 @@ export function resolveStageGroup(stageOptions?: { group?: string | true }): str
  */
 export function stageHasIntercomAccess(stageOptions?: StageOptions): boolean {
   if (!stageOptions) return true;
-  if (stageOptions.noTools === "all" || stageOptions.noTools === "builtin") return false;
+  if (stageOptions.noTools === "all") return false;
   const tools = stageOptions.tools;
   if (Array.isArray(tools) && !tools.includes("intercom")) return false;
   const excluded = stageOptions.excludedTools;