@marcoscale98/pi-extensible-workflows 5.17.0-fork.1 → 6.2.1-fork.1

package/dist/src/host-recovery.d.ts

@@ -1,8 +1,8 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { FairAgentScheduler, WorkflowAgentExecutor, type AgentDefinition, type AgentExecutionRoot, type AgentProviderFailure, type AgentProviderRecovery } from "./agent-execution.js";
+import { type ExtensionAPI, type ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { FairAgentScheduler, WorkflowAgentExecutor, type AgentExecutionRoot, type AgentProviderFailure, type AgentProviderRecovery } from "./agent-execution.js";
 import { RunStore, type PersistedRun } from "./persistence.js";
-import { WorkflowError, type AgentIdentity, type AgentResourcePolicy, type BudgetApprovalRequest, type JsonValue, type LaunchSnapshot, type ModelSpec, type RunState, type ShellIdentity, type ShellOptions, type ShellResult, type WorkflowMetadata, type WorkflowWorktreeReference } from "./types.js";
+import { WorkflowError, type AgentIdentity, type AgentResourcePolicy, type BudgetApprovalRequest, type JsonValue, type LaunchSnapshot, type ModelSpec, type RunState, type ShellIdentity, type ShellOptions, type ShellResult, type ToolIdentity, type WorkflowMetadata, type WorkflowWorktreeReference } from "./types.js";
 import { type WorkflowRegistryApi } from "./registry.js";
 import { RunLifecycle, WorkflowEventPublisher, type WorkflowRunRecord, type WorkflowToolUpdate } from "./host-runtime.js";
 import { type CompletionDeliveryContext, type CompletionDeliveryResult } from "./host-delivery.js";
@@ -21,8 +21,10 @@ export type WorkflowRecoveryContext = {
     } | undefined;
     modelRegistry: ModelRegistryCapability | undefined;
     deliveryContext: CompletionDeliveryContext;
+    toolContext?: ExtensionToolContext | undefined;
     signal?: AbortSignal;
     resolvedAliases?: Readonly<Record<string, string>>;
+    resolvedDynamicAliasNames?: readonly string[];
     blockedAliases?: ReadonlySet<string>;
     blockedAliasTargets?: Readonly<Record<string, string>>;
 };
@@ -48,6 +50,7 @@ export type WorkflowRecoveryDependencies = {
         modelRegistry?: WorkflowRecoveryContext["modelRegistry"];
         signal: AbortSignal;
         resolvedAliases?: Readonly<Record<string, string>>;
+        resolvedDynamicAliasNames?: readonly string[];
         blockedAliases?: ReadonlySet<string>;
         blockedAliasTargets?: Readonly<Record<string, string>>;
         withPreflight: boolean;
@@ -59,17 +62,15 @@ export type WorkflowRecoveryDependencies = {
         knownModels: ReadonlySet<string>;
         availableModels: ReadonlySet<string>;
         currentAliases: Readonly<Record<string, string>>;
+        dynamicAliasNames: readonly string[];
         blockedAliases: ReadonlySet<string>;
         blockedAliasTargets: Readonly<Record<string, string>>;
         snapshot: Readonly<LaunchSnapshot>;
         script: string | undefined;
     }>;
-    resumeRoles: (store: RunStore, snapshot: Readonly<LaunchSnapshot>, cwd: string, trustedProject: boolean) => {
-        definitions: Readonly<Record<string, AgentDefinition>>;
-        capture: (role: string, model: ModelSpec) => Promise<void>;
-    };
-    workflowAgentHandler: (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle, executor: WorkflowAgentExecutor, cwd: string, runId: string, captureRole?: (role: string, model: ModelSpec) => Promise<void>) => (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
+    workflowAgentHandler: (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle, executor: WorkflowAgentExecutor, cwd: string, runId: string) => (prompt: string, options: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: AgentIdentity) => Promise<JsonValue>;
     shellForRun: (store: RunStore, metadata: WorkflowMetadata, lifecycle: RunLifecycle, command: string, options: ShellOptions, signal: AbortSignal, identity: ShellIdentity) => Promise<ShellResult>;
+    toolForRun: (store: RunStore, lifecycle: RunLifecycle, context: ExtensionToolContext | undefined, identifier: string, args: Readonly<Record<string, JsonValue>>, signal: AbortSignal, identity: ToolIdentity) => Promise<JsonValue>;
     resolveWorktree: (store: RunStore, metadata: WorkflowMetadata, owner: string) => Promise<Readonly<WorkflowWorktreeReference>>;
     checkpointBridge: (runId: string, store: RunStore, metadata: WorkflowMetadata, foreground: boolean, ui?: {
         select?: (prompt: string, options: string[]) => Promise<string | undefined>;
@@ -104,8 +105,10 @@ export declare function createWorkflowRecovery(deps: WorkflowRecoveryDependencie
         } | undefined;
         modelRegistry: WorkflowRecoveryContext["modelRegistry"];
         deliveryContext: CompletionDeliveryContext;
+        toolContext?: ExtensionToolContext | undefined;
         signal?: AbortSignal | undefined;
         resolvedAliases?: Readonly<Record<string, string>>;
+        resolvedDynamicAliasNames?: readonly string[];
         blockedAliases?: ReadonlySet<string>;
         blockedAliasTargets?: Readonly<Record<string, string>>;
     }, modeOverride?: boolean, waitForCompletion?: boolean) => Promise<{

package/dist/src/host-recovery.js

@@ -28,17 +28,10 @@ function workflowRecoveryGuidance(action, state) {
         return "Interrupted workflow runs must be resumed from the interactive /workflow picker";
     return `Only failed workflow runs can be retried; source is ${state}`;
 }
-/** A snapshot can only be re-executed when it carries the current identity scheme and every role its script references. */
-function assertResumableSnapshot(snapshot, trustedProject) {
+/** A snapshot can only be re-executed when it carries the current identity scheme and validated concrete agent configurations. */
+function assertResumableSnapshot(snapshot) {
     if (snapshot.identityVersion !== LAUNCH_SNAPSHOT_IDENTITY_VERSION)
         throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow launch snapshot identity version is incompatible");
-    if (snapshot.roles === undefined)
-        throw new WorkflowError("RESUME_INCOMPATIBLE", "Workflow role definitions are missing from the launch snapshot");
-    if ((snapshot.projectRoles?.length ?? 0) > 0 && !trustedProject)
-        throw new WorkflowError("RESUME_INCOMPATIBLE", "Cannot restore project roles in an untrusted project");
-    const missingRole = snapshot.agentTypes.find((role) => !snapshot.roles?.[role]);
-    if (missingRole)
-        throw new WorkflowError("RESUME_INCOMPATIBLE", `Role definition is missing from the launch snapshot: ${missingRole}`);
 }
 function assertExpectedWorkflowState(expectedState, actualState) {
     if (expectedState !== undefined && expectedState !== actualState)
@@ -46,7 +39,7 @@ function assertExpectedWorkflowState(expectedState, actualState) {
 }
 export function persistedFailure(run, error) { const failedAt = workflowFailedAt(error); return { ...run, error: { code: error.code, message: error.message, ...(failedAt ? { failedAt } : {}) }, ...(failedAt ? { failedAt } : {}) }; }
 export function createWorkflowRecovery(deps) {
-    const { pi, home, runs, scheduler, eventPublisher, persistRunState, projectTrusted, resumeHostContext, ensureSessionLease, createAgentExecutor, activeSnapshotTools, frozenResourcePolicy, resolveLaunchPrologue, resumeRoles, workflowAgentHandler, shellForRun, resolveWorktree, checkpointBridge, phaseBridge, logBridge, lifecycleFor, createProviderErrorRecovery, cleanupTerminalRun, deliver, deliverTerminal, workflowToolUpdate, registry, modelSpec } = deps;
+    const { pi, home, runs, scheduler, eventPublisher, persistRunState, projectTrusted, resumeHostContext, ensureSessionLease, createAgentExecutor, activeSnapshotTools, frozenResourcePolicy, resolveLaunchPrologue, workflowAgentHandler, shellForRun, toolForRun, resolveWorktree, checkpointBridge, phaseBridge, logBridge, lifecycleFor, createProviderErrorRecovery, cleanupTerminalRun, deliver, deliverTerminal, workflowToolUpdate, registry, modelSpec } = deps;
     const coordinateRunMutation = deps.coordinateRunMutation ?? ((task) => task());
     const budgetDecisionDelivery = (metadata, request) => `Workflow ${metadata.name} budget adjustment ${request.proposalId} for run ${request.runId} requires approval. Consumed usage: ${JSON.stringify(request.consumed)}. Previous limits: ${JSON.stringify(request.previous)}. Proposed limits: ${JSON.stringify(request.proposed)}. Respond with workflow_respond using proposalId ${request.proposalId}.`;
     const appendBudgetDecisionEvent = async (run, request, type) => {
@@ -70,11 +63,11 @@ export function createWorkflowRecovery(deps) {
         const loaded = await run.store.load();
         const trustedProject = context?.projectTrusted ?? run.projectTrusted();
         const rootModel = context?.model ? { ...run.model, provider: context.model.provider, model: context.model.id } : run.model;
-        const { settingsPath, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd: run.store.cwd, trustedProject, rootModel, ...(context?.modelRegistry ? { modelRegistry: context.modelRegistry } : {}), signal: run.abortController.signal, withPreflight: false });
+        const { settingsPath, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, dynamicAliasNames, blockedAliases, blockedAliasTargets, snapshot } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd: run.store.cwd, trustedProject, rootModel, ...(context?.modelRegistry ? { modelRegistry: context.modelRegistry } : {}), signal: run.abortController.signal, withPreflight: false });
         await run.store.saveSnapshot(snapshot);
         scheduler.updateRunLimit(run.store.runId, snapshot.settings.concurrency);
         scheduler.setRunExtensionSettings(run.store.runId, snapshot.settings.extensionSettings);
-        run.executor = createAgentExecutor({ cwd: run.store.cwd, model: run.model, tools: activeSnapshotTools(snapshot.tools, "session"), resourceSelectors: currentPolicy.effective, extensionSettings: snapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: resumeRoles(run.store, snapshot, run.store.cwd, trustedProject).definitions, runStore: run.store, providerPause: async () => { deliver(`Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentResourcePolicy: frozenResourcePolicy(currentPolicy) });
+        run.executor = createAgentExecutor({ cwd: run.store.cwd, projectTrusted: currentPolicy.projectTrusted, model: run.model, tools: activeSnapshotTools(snapshot.tools, "session"), resourceSelectors: currentPolicy.effective, extensionSettings: snapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, dynamicModelAliasNames: dynamicAliasNames, blockedAliases, blockedAliasTargets, settingsPath, runStore: run.store, providerPause: async () => { deliver(`Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentResourcePolicy: frozenResourcePolicy(currentPolicy) });
         run.executor.setRunContext(workflowRunContext(run.store.cwd, run.store.sessionId, run.store.runId, loaded.snapshot.metadata, loaded.snapshot.args, run.abortController.signal));
         const drift = aliasDrift(previousAliases, currentAliases);
         if (drift.length)
@@ -92,7 +85,7 @@ export function createWorkflowRecovery(deps) {
             await persistRunState(run.store, run.metadata, withoutActiveShells);
         await run.store.validateRetrySource();
         await run.store.validateBorrowedWorktrees();
-        assertResumableSnapshot(loaded.snapshot, trustedProject);
+        assertResumableSnapshot(loaded.snapshot);
         const rootModel = context?.model ? { ...run.model, provider: context.model.provider, model: context.model.id } : run.model;
         const controller = new AbortController();
         if (context?.signal?.aborted)
@@ -101,7 +94,7 @@ export function createWorkflowRecovery(deps) {
             context?.signal?.addEventListener("abort", () => { controller.abort(); }, { once: true });
         }
         run.abortController = controller;
-        const { settingsPath, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot, script } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd: run.store.cwd, trustedProject, rootModel, ...(context?.modelRegistry ? { modelRegistry: context.modelRegistry } : {}), signal: controller.signal, ...(context?.resolvedAliases ? { resolvedAliases: context.resolvedAliases } : {}), ...(context?.blockedAliases ? { blockedAliases: context.blockedAliases } : {}), ...(context?.blockedAliasTargets ? { blockedAliasTargets: context.blockedAliasTargets } : {}), withPreflight: true });
+        const { settingsPath, currentPolicy, previousAliases, knownModels, availableModels, currentAliases, dynamicAliasNames, blockedAliases, blockedAliasTargets, snapshot, script } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd: run.store.cwd, trustedProject, rootModel, ...(context?.modelRegistry ? { modelRegistry: context.modelRegistry } : {}), signal: controller.signal, ...(context?.resolvedAliases ? { resolvedAliases: context.resolvedAliases } : {}), ...(context?.resolvedDynamicAliasNames ? { resolvedDynamicAliasNames: context.resolvedDynamicAliasNames } : {}), ...(context?.blockedAliases ? { blockedAliases: context.blockedAliases } : {}), ...(context?.blockedAliasTargets ? { blockedAliasTargets: context.blockedAliasTargets } : {}), withPreflight: true });
         if (!script)
             throw new WorkflowError("INTERNAL_ERROR", "Resume preflight did not produce a launch script");
         const persistedSnapshot = modeOverride === undefined ? snapshot : createLaunchSnapshot({ ...snapshot, launchMode: foreground ? "foreground" : "background" });
@@ -110,8 +103,7 @@ export function createWorkflowRecovery(deps) {
             await persistRunState(run.store, run.metadata, (current) => ({ ...current, delivery: { ...(current.delivery ?? {}), mode: foreground ? "foreground" : "background", state: foreground ? "attached" : "pending" } }));
         scheduler.updateRunLimit(run.store.runId, snapshot.settings.concurrency);
         scheduler.setRunExtensionSettings(run.store.runId, snapshot.settings.extensionSettings);
-        const roles = resumeRoles(run.store, persistedSnapshot, run.store.cwd, trustedProject);
-        run.executor = createAgentExecutor({ cwd: run.store.cwd, model: rootModel, tools: activeSnapshotTools(snapshot.tools, "session"), resourceSelectors: currentPolicy.effective, extensionSettings: snapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: roles.definitions, runStore: run.store, providerPause: async () => { deliver(`Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentResourcePolicy: frozenResourcePolicy(currentPolicy) });
+        run.executor = createAgentExecutor({ cwd: run.store.cwd, projectTrusted: currentPolicy.projectTrusted, model: rootModel, tools: activeSnapshotTools(snapshot.tools, "session"), resourceSelectors: currentPolicy.effective, extensionSettings: snapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, dynamicModelAliasNames: dynamicAliasNames, blockedAliases, blockedAliasTargets, settingsPath, runStore: run.store, providerPause: async () => { deliver(`Workflow ${snapshot.metadata.name} paused: provider limit.`); await run.lifecycle.providerPause(); }, agentResourcePolicy: frozenResourcePolicy(currentPolicy) });
         const drift = aliasDrift(previousAliases, currentAliases);
         if (drift.length)
             await run.store.appendEvent({ type: "warning", message: `Model alias mappings changed on resume: ${drift.join("; ")}` });
@@ -119,7 +111,7 @@ export function createWorkflowRecovery(deps) {
         run.executor.setRunContext(runContext);
         await scheduler.cancelRun(run.store.runId);
         await run.lifecycle.resume();
-        const execution = runWorkflow(script, loaded.snapshot.args, withWorkflowFunctions({ shell: (command, options, signal, identity) => shellForRun(run.store, run.metadata, run.lifecycle, command, options, signal, identity), agent: workflowAgentHandler(run.store, run.metadata, run.lifecycle, run.executor, run.store.cwd, run.store.runId, roles.capture), worktree: async (owner) => resolveWorktree(run.store, run.metadata, owner), checkpoint: checkpointBridge(run.store.runId, run.store, run.metadata, foreground, hasUI ? ui : undefined), phase: phaseBridge(run.store, run.metadata, run.lifecycle), log: logBridge(run.store, run.lifecycle, run.metadata.name) }, run.store, runContext, registry, snapshot.settings.extensionSettings), controller.signal);
+        const execution = runWorkflow(script, loaded.snapshot.args, withWorkflowFunctions({ tool: (identifier, args, signal, identity) => toolForRun(run.store, run.lifecycle, context?.toolContext, identifier, args, signal, identity), shell: (command, options, signal, identity) => shellForRun(run.store, run.metadata, run.lifecycle, command, options, signal, identity), agent: workflowAgentHandler(run.store, run.metadata, run.lifecycle, run.executor, run.store.cwd, run.store.runId), worktree: async (owner) => resolveWorktree(run.store, run.metadata, owner), checkpoint: checkpointBridge(run.store.runId, run.store, run.metadata, foreground, hasUI ? ui : undefined), phase: phaseBridge(run.store, run.metadata, run.lifecycle), log: logBridge(run.store, run.lifecycle, run.metadata.name) }, run.store, runContext, registry, snapshot.settings.extensionSettings), controller.signal);
         run.execution = execution;
         const completion = execution.result.then(async (value) => {
             await scheduler.flush(run.store.runId);
@@ -292,11 +284,11 @@ export function createWorkflowRecovery(deps) {
             const trustedProject = projectTrusted(context);
             await sourceStore.validateRetrySource();
             await sourceStore.validateBorrowedWorktrees();
-            assertResumableSnapshot(loaded.snapshot, trustedProject);
+            assertResumableSnapshot(loaded.snapshot);
             const modelRegistry = resumeHostContext(context).modelRegistry;
             const hostModel = object(host.model) && typeof host.model.provider === "string" && typeof host.model.id === "string" ? { provider: host.model.provider, id: host.model.id } : { provider: "", id: "" };
             const rootModel = { provider: hostModel.provider, model: hostModel.id, thinking: pi.getThinkingLevel() };
-            const { active, settingsPath, currentPolicy, knownModels, availableModels, currentAliases, blockedAliases, blockedAliasTargets, snapshot: childBaseSnapshot } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd, trustedProject, rootModel, ...(modelRegistry ? { modelRegistry } : {}), signal: signal ?? new AbortController().signal, withPreflight: true });
+            const { active, settingsPath, currentPolicy, knownModels, availableModels, currentAliases, dynamicAliasNames, blockedAliases, blockedAliasTargets, snapshot: childBaseSnapshot } = await resolveLaunchPrologue({ snapshot: loaded.snapshot, cwd, trustedProject, rootModel, ...(modelRegistry ? { modelRegistry } : {}), signal: signal ?? new AbortController().signal, withPreflight: true });
             await sourceStore.validateNamedWorktrees();
             for (const name of loaded.run.retry?.namedWorktrees ?? [])
                 await sourceStore.resolveNamedWorktree(name);
@@ -315,10 +307,10 @@ export function createWorkflowRecovery(deps) {
             const abortController = new AbortController();
             const providerErrorRecovery = createProviderErrorRecovery(context, availableModels, () => { abortController.abort(); });
             const providerPause = async () => { deliver(`Workflow ${loaded.snapshot.metadata.name} paused: provider limit.`); await lifecycle.providerPause(); };
-            const childRun = { executor: createAgentExecutor({ cwd, model, tools: activeSnapshotTools(loaded.snapshot.tools, active), resourceSelectors: currentPolicy.effective, extensionSettings: childBaseSnapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, blockedAliases, blockedAliasTargets, settingsPath, agentDefinitions: loaded.snapshot.roles ?? {}, runStore: childStore, providerPause, agentResourcePolicy: frozenResourcePolicy(currentPolicy) }), store: childStore, metadata: loaded.snapshot.metadata, model, lifecycle, budget: childBudget, abortController, projectTrusted: () => projectTrusted(context), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}) };
+            const childRun = { executor: createAgentExecutor({ cwd, projectTrusted: currentPolicy.projectTrusted, model, tools: activeSnapshotTools(loaded.snapshot.tools, active), resourceSelectors: currentPolicy.effective, extensionSettings: childBaseSnapshot.settings.extensionSettings, availableModels, knownModels, modelAliases: currentAliases, dynamicModelAliasNames: dynamicAliasNames, blockedAliases, blockedAliasTargets, settingsPath, runStore: childStore, providerPause, agentResourcePolicy: frozenResourcePolicy(currentPolicy) }), store: childStore, metadata: loaded.snapshot.metadata, model, lifecycle, budget: childBudget, abortController, projectTrusted: () => projectTrusted(context), checkpointResolvers: new Map(), ...(providerErrorRecovery ? { providerErrorRecovery } : {}) };
             runs.set(childRunId, childRun);
             childCreated = true;
-            return { childRun, parentRunId: loaded.run.id, lineageRootRunId, concurrency: loaded.snapshot.settings.concurrency, ...(childBaseSnapshot.settings.extensionSettings === undefined ? {} : { extensionSettings: childBaseSnapshot.settings.extensionSettings }), hostModel, modelRegistry, currentAliases, blockedAliases, blockedAliasTargets };
+            return { childRun, parentRunId: loaded.run.id, lineageRootRunId, concurrency: loaded.snapshot.settings.concurrency, ...(childBaseSnapshot.settings.extensionSettings === undefined ? {} : { extensionSettings: childBaseSnapshot.settings.extensionSettings }), hostModel, modelRegistry, currentAliases, dynamicAliasNames, blockedAliases, blockedAliasTargets };
         }
         finally {
             if (!childCreated)
@@ -333,7 +325,7 @@ export function createWorkflowRecovery(deps) {
             await eventPublisher.runStarted(prepared.childRun.store, prepared.childRun.metadata);
             const { hasUI, ui } = recoveryUi(context);
             const recoveryContext = resumeHostContext(context);
-            const completed = await coldResumeRun(prepared.childRun, hasUI, ui, projectTrusted(context), { model: prepared.hostModel, modelRegistry: prepared.modelRegistry, deliveryContext: recoveryContext.deliveryContext, resolvedAliases: prepared.currentAliases, blockedAliases: prepared.blockedAliases, blockedAliasTargets: prepared.blockedAliasTargets, ...(signal ? { signal } : {}) }, modeOverride);
+            const completed = await coldResumeRun(prepared.childRun, hasUI, ui, projectTrusted(context), { model: prepared.hostModel, modelRegistry: prepared.modelRegistry, deliveryContext: recoveryContext.deliveryContext, toolContext: recoveryContext.toolContext, resolvedAliases: prepared.currentAliases, resolvedDynamicAliasNames: prepared.dynamicAliasNames, blockedAliases: prepared.blockedAliases, blockedAliasTargets: prepared.blockedAliasTargets, ...(signal ? { signal } : {}) }, modeOverride);
             const completion = runs.get(prepared.childRun.store.runId)?.completion;
             if (completion) {
                 childStarted = true;

package/dist/src/host-runtime.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import { deepFreeze, errorCode, errorText, fail, isWorkflowErrorCode, jsonValue, object } from "./utils.js";
+import { FUNCTION_HANDLE_PREFIX } from "./execution.js";
+import { deepFreeze, errorCode, errorText, fail, isWorkflowErrorCode, jsonDigest, jsonValue, object } from "./utils.js";
 import { validateAgentOptions, validateShellOptions, workflowPrompt } from "./validation.js";
 import { HARD_TERMINAL_RUN_STATES, WORKFLOW_AGENT_STATE_CHANGED_EVENT, WORKFLOW_BUDGET_EVENT, WORKFLOW_CHECKPOINT_STATE_CHANGED_EVENT, WORKFLOW_PHASE_CHANGED_EVENT, WORKFLOW_RUN_COMPLETED_EVENT, WORKFLOW_RUN_FAILED_EVENT, WORKFLOW_RUN_RESUMED_EVENT, WORKFLOW_RUN_STARTED_EVENT, WORKFLOW_RUN_STATE_CHANGED_EVENT, WORKFLOW_WORKTREE_CREATED_EVENT, WorkflowError } from "./types.js";
 import { structuralPath as operationPath } from "./persistence.js";
@@ -130,7 +131,7 @@ export class WorkflowEventPublisher {
             await this.#publish(store, metadata, WORKFLOW_RUN_FAILED_EVENT, { error: safeEventError(error) });
     }
     async agentState(store, metadata, previous, agent) {
-        await this.#publish(store, metadata, WORKFLOW_AGENT_STATE_CHANGED_EVENT, { agentId: agent.id, displayLabel: agent.label ?? agent.name, ...(agent.role ? { role: agent.role } : {}), structuralPath: [...(agent.structuralPath ?? [])], ...(agent.parentId ? { parentId: agent.parentId } : {}), ...(agent.parentBreadcrumb ? { parentBreadcrumb: agent.parentBreadcrumb } : {}), ...(agent.worktreeOwner ? { worktreeOwner: agent.worktreeOwner } : {}), ...(previous ? { previousState: previous.state } : {}), state: agent.state, attempt: agent.attempts });
+        await this.#publish(store, metadata, WORKFLOW_AGENT_STATE_CHANGED_EVENT, { agentId: agent.id, displayLabel: agent.label ?? agent.name, structuralPath: [...(agent.structuralPath ?? [])], ...(agent.parentId ? { parentId: agent.parentId } : {}), ...(agent.parentBreadcrumb ? { parentBreadcrumb: agent.parentBreadcrumb } : {}), ...(agent.worktreeOwner ? { worktreeOwner: agent.worktreeOwner } : {}), ...(previous ? { previousState: previous.state } : {}), state: agent.state, attempt: agent.attempts });
     }
     async agentStates(store, metadata, previous, current) {
         const previousById = new Map(previous.map((agent) => [agent.id, agent]));
@@ -285,6 +286,7 @@ export function nextNamedOccurrence(counters, label) {
 function functionBreadcrumb(name, occurrence) { return occurrence === 1 ? name : `${name} #${String(occurrence)}`; }
 export function withWorkflowFunctions(bridge, store, runContext, registry, settings = Object.freeze({})) {
     const functionAgentOccurrences = new Map();
+    const functionHandles = new Set();
     const functionShellOccurrences = new Map();
     const functionInvokeOccurrences = new Map();
     const functionInvokeBreadcrumbOccurrences = new Map();
@@ -307,6 +309,7 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
             // Own rejection immediately; Promise.all below still propagates it after the function completes.
             void sideEffect.catch(() => undefined);
         };
+        let closed = false;
         const parentBreadcrumb = breadcrumb ?? functionBreadcrumb(name, identity.occurrence);
         const context = {
             settings: deepFreeze(structuredClone(settings)),
@@ -327,7 +330,7 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
                 const nestedIdentity = { path: nestedPath, structuralPath: [...inherited], occurrence, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) };
                 return invokeFunction(targetName, targetInput, signal, nestedIdentity, `${parentBreadcrumb} > ${functionBreadcrumb(breadcrumbName, breadcrumbOccurrence)}`);
             },
-            agent: async (prompt, options) => {
+            agent: Object.assign(async (prompt, options) => {
                 if (!bridge.agent || typeof prompt !== "string")
                     fail("AGENT_FAILED", "No agent bridge is available");
                 const validatedOptions = validateAgentOptions(options === undefined ? {} : options);
@@ -337,7 +340,55 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
                 const occurrence = (functionAgentOccurrences.get(key) ?? 0) + 1;
                 functionAgentOccurrences.set(key, occurrence);
                 return bridge.agent(prompt, validatedOptions, signal, { structuralPath: [...inherited], callSite: `function:${path}`, occurrence, parentBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
-            },
+            }, {
+                create: (...created) => {
+                    if (created.length !== 1 || !object(created[0]))
+                        fail("INVALID_METADATA", "agent.create requires one options object");
+                    const { name, ...rest } = created[0];
+                    if (typeof name !== "string" || !name.trim())
+                        fail("INVALID_METADATA", "agent.create requires a stable explicit name");
+                    const config = deepFreeze(structuredClone(validateAgentOptions(rest)));
+                    const scopedStructuralPath = [...(inheritedHostAgentPath.getStore() ?? [])];
+                    const scopedWorktreeOwner = inheritedHostWorktreeOwner.getStore() ?? worktreeOwner;
+                    const scope = JSON.stringify([scopedStructuralPath, scopedWorktreeOwner ?? null]);
+                    // The registered-function path makes repeated and nested invocations distinct; scope separates branches and worktrees. The digest bounds the journal and turn-copy file names.
+                    const handle = operationPath(FUNCTION_HANDLE_PREFIX, jsonDigest([path, scopedStructuralPath, scopedWorktreeOwner ?? null]), name);
+                    if (functionHandles.has(handle))
+                        fail("INVALID_METADATA", `Duplicate agent handle name: ${name}`);
+                    functionHandles.add(handle);
+                    let turn = 0;
+                    let inflight = false;
+                    // Not a nested promise chain: the caller owns the one returned promise, and inflight clears in finally on every outcome.
+                    const send = async (...sent) => {
+                        if (!bridge.agent)
+                            fail("AGENT_FAILED", "No agent bridge is available");
+                        if (sent.length < 1 || sent.length > 2)
+                            fail("INVALID_METADATA", "send requires a prompt and optional options");
+                        if (closed)
+                            fail("INVALID_METADATA", `Agent handle outlived the function invocation that created it: ${name}`);
+                        if (typeof sent[0] !== "string")
+                            fail("INVALID_METADATA", "send prompt must be a string");
+                        const sendOptions = sent[1] === undefined ? {} : sent[1];
+                        if (!object(sendOptions) || Object.keys(sendOptions).some((key) => key !== "outputSchema" && key !== "timeoutMs"))
+                            fail("INVALID_METADATA", "send options must contain only outputSchema and timeoutMs");
+                        const sendStructuralPath = [...(inheritedHostAgentPath.getStore() ?? [])];
+                        if (JSON.stringify([sendStructuralPath, inheritedHostWorktreeOwner.getStore() ?? worktreeOwner ?? null]) !== scope)
+                            fail("INVALID_METADATA", `Agent handle sends must run in the scope that created the handle: ${name}`);
+                        if (inflight)
+                            fail("INVALID_METADATA", "Concurrent send(...) calls on one agent handle are unsupported; await each turn");
+                        const validatedOptions = validateAgentOptions({ ...config, ...sendOptions });
+                        inflight = true;
+                        turn += 1;
+                        try {
+                            return await bridge.agent(sent[0], validatedOptions, signal, { structuralPath: sendStructuralPath, callSite: `function:${path}:handle:${name}`, occurrence: turn, handle, turn, parentBreadcrumb, ...(scopedWorktreeOwner ? { worktreeOwner: scopedWorktreeOwner } : {}) });
+                        }
+                        finally {
+                            inflight = false;
+                        }
+                    };
+                    return Object.freeze({ name, send });
+                },
+            }),
             shell: async (...args) => {
                 if (!bridge.shell)
                     fail("SHELL_FAILED", "No shell bridge is available");
@@ -363,7 +414,7 @@ export function withWorkflowFunctions(bridge, store, runContext, registry, setti
             phase: (name) => { ownSideEffect(() => bridge.phase?.(name)); },
             log: (message) => { ownSideEffect(() => bridge.log?.(message)); },
         };
-        const result = await inheritedHostAgentPath.run([...structuralPath], async () => registry.invokeFunction(name, input, context, path, { get: () => replayed?.value, put: (_path, value) => { stored = value; } }));
+        const result = await inheritedHostAgentPath.run([...structuralPath], async () => registry.invokeFunction(name, input, context, path, { get: () => replayed?.value, put: (_path, value) => { stored = value; } })).finally(() => { closed = true; });
         await Promise.all(sideEffects);
         if (!replayed)
             await store.complete(path, stored ?? result);

package/dist/src/host-view.d.ts

@@ -84,13 +84,17 @@ export declare function navigatorRunLabels(entries: readonly {
 export declare function agentBreadcrumbParts(agent: AgentRecord, byId: Map<string, AgentRecord>, includeStructuralPath?: boolean): string[];
 export declare function agentBreadcrumb(agent: AgentRecord, byId: Map<string, AgentRecord>, includeStructuralPath?: boolean): string;
 export declare function formatStalledDuration(durationMs: number): string;
+export declare function stalledDuration(agent: Pick<AgentDetailPresentation, "state" | "lastEventAt">, now: number): number | undefined;
+export declare function agentActivityLabel(agent: {
+    readonly activity?: AgentRecord["activity"];
+    readonly toolCalls?: AgentRecord["toolCalls"];
+}): string;
 export interface AgentDetailPresentation {
     readonly state: string;
     readonly activity?: AgentRecord["activity"];
     readonly lastEventAt?: number;
     readonly structuralPath?: readonly string[];
     readonly model?: AgentRecord["model"];
-    readonly role?: string;
     readonly tools?: readonly string[];
     readonly attempts?: number;
     readonly startedAt?: number;
@@ -127,5 +131,6 @@ export declare function formatWorkflowPhaseDashboard(run: PersistedRun, snapshot
 export declare function formatNavigatorColumns(sidebar: readonly string[], detail: readonly string[], width: number, layout?: Readonly<{
     treeOnly?: boolean | undefined;
     detailsOnly?: boolean | undefined;
+    detailOffset?: number | undefined;
 }>): string[];
 export declare function formatCheckpointReview(checkpoint: AwaitingCheckpoint): string;

package/dist/src/host-view.js

@@ -74,6 +74,17 @@ function formatShellActivity(activeShells, startedAt, spinner, styles, now) {
     const timing = started && startedAt !== undefined && !Number.isNaN(started.getTime()) ? ` ${styles.dim(`started=${started.toISOString()} elapsed=${formatWorkflowRuntime(Math.max(0, now - startedAt))}`)}` : "";
     return `${styles.accent(spinner)} shell ${styles.accent("[running]")} ${styles.dim(`(${String(count)} active)`)}${timing}`;
 }
+function formatToolActivity(run, spinner, styles, now) {
+    const calls = run.activeTools ?? [];
+    if (!calls.length)
+        return undefined;
+    const counts = new Map();
+    for (const { name } of calls)
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    const names = [...counts].map(([name, count]) => count > 1 ? `${name} ×${String(count)}` : name).join(", ");
+    const elapsed = formatWorkflowRuntime(Math.max(0, now - Math.min(...calls.map(({ startedAt }) => startedAt))));
+    return `${styles.accent(spinner)} tools ${styles.accent("[running]")} ${sanitizeDisplayText(names)} ${styles.dim(`elapsed=${elapsed}`)}`;
+}
 function formatLogTimestamp(timestamp) {
     if (timestamp === undefined || !Number.isFinite(timestamp))
         return "--:--:--";
@@ -167,12 +178,16 @@ function workflowProgressLines(run, spinner, styles, now, expanded, width, showH
     const shellActivity = scopedShells ? undefined : formatShellActivity(run.activeShells, run.activeShellStartedAt, spinner, styles, now);
     if (shellActivity)
         lines.push(`  ${shellActivity}`);
+    const toolActivity = formatToolActivity(run, spinner, styles, now);
+    if (toolActivity)
+        lines.push(`  ${toolActivity}`);
     const byId = new Map(run.agents.map((agent) => [agent.id, agent]));
     const position = new Map(run.agents.map((agent, index) => [agent, index]));
     const renderAgents = (agents, nested) => renderGroupedAgents(agents, ({ agent, depth }, grouped) => {
-        const icon = agentStateGlyph(agent.state, spinner);
+        const icon = agentStateGlyph(agent.state, "●");
         const indent = "  ".repeat((grouped ? 2 : 1) + depth);
-        const activity = SETTLED_AGENT_STATES.has(agent.state) ? "" : formatAgentActivity(agent, spinner, styles, now);
+        const idleSpinner = agent.state === "running" && !agentActivityLabel(agent) ? styles.accent(spinner) : "";
+        const activity = SETTLED_AGENT_STATES.has(agent.state) ? "" : [idleSpinner, formatAgentActivity(agent, spinner, styles, now)].filter(Boolean).join(" ");
         const name = grouped ? agent.label ?? agent.name : styledAgentBreadcrumb(agent, byId, styles);
         const state = progressStyleForState(agent.state, styles);
         const detail = expanded ? formatWorkflowAgentDetail(agent, now) : "";
@@ -493,7 +508,7 @@ export function workflowProgressBlock(run, theme, progress, refresh, invalidate,
         invalidate() {
             const displayed = currentRun();
             const now = Date.now();
-            if (!progress || !refresh || displayed.state !== "running" || (!displayed.agents.some((agent) => agent.state === "running") && (displayed.activeShells ?? 0) <= 0))
+            if (!progress || !refresh || displayed.state !== "running" || (!displayed.agents.some((agent) => agent.state === "running") && (displayed.activeShells ?? 0) <= 0 && !displayed.activeTools?.length))
                 return;
             if (progress.refresh || now - progress.lastRefreshAt < WORKFLOW_PROGRESS_REFRESH_MS)
                 return;
@@ -606,7 +621,7 @@ export function formatStalledDuration(durationMs) {
     const remainingMinutes = minutes % 60;
     return `${String(hours)}h${remainingMinutes ? ` ${String(remainingMinutes)}m` : ""}`;
 }
-function stalledDuration(agent, now) {
+export function stalledDuration(agent, now) {
     if (agent.state !== "running" || agent.lastEventAt === undefined || !Number.isFinite(agent.lastEventAt))
         return undefined;
     const duration = now - agent.lastEventAt;
@@ -618,7 +633,7 @@ function elapsedDurationMs(agent, end) {
         return Math.max(0, agent.durationMs);
     return agent.startedAt === undefined || !Number.isFinite(agent.startedAt) ? undefined : Math.max(0, end - agent.startedAt);
 }
-function agentActivityLabel(agent) {
+export function agentActivityLabel(agent) {
     const activity = agent.activity;
     if (activity?.kind === "reasoning" || activity?.kind === "text") {
         const name = activity.kind === "reasoning" ? "reasoning" : "responding";
@@ -671,7 +686,6 @@ export function formatAgentDetail(agent, styles = PLAIN_WORKFLOW_PROGRESS_STYLES
         `State: ${state(agent.state)}`,
         ...(agent.structuralPath?.length ? [`Structural path: ${agent.structuralPath.join(" > ")}`] : []),
         ...(model === undefined ? [] : [`Model: ${model}`]),
-        `Role: ${agent.role ?? "(none)"}`,
         `Tools: ${tools}`,
         ...(agent.attempts !== undefined && Number.isFinite(agent.attempts) && agent.attempts > 1 ? [`Attempts: ${String(agent.attempts)}`] : []),
         ...(duration === undefined ? [] : [`Duration: ${formatWorkflowRuntime(duration)}`]),
@@ -731,6 +745,9 @@ export function formatNavigatorDashboard(run, checkpoints, worktrees, now = Date
     const shellActivity = formatShellActivity(run.activeShells, run.activeShellStartedAt, "⠦", PLAIN_WORKFLOW_PROGRESS_STYLES, now);
     if (shellActivity)
         lines.push(`  ${shellActivity}`);
+    const toolActivity = formatToolActivity(run, "⠦", PLAIN_WORKFLOW_PROGRESS_STYLES, now);
+    if (toolActivity)
+        lines.push(`  ${toolActivity}`);
     if (run.error)
         lines.push(`Error: ${run.error.code}: ${run.error.message}`);
     if (run.events?.length)
@@ -776,6 +793,9 @@ export function formatNavigatorRun(loaded, checkpoints, worktrees, now = Date.no
     const shellActivity = formatShellActivity(run.activeShells, run.activeShellStartedAt, "⠦", PLAIN_WORKFLOW_PROGRESS_STYLES, now);
     if (shellActivity)
         lines.push(`  ${shellActivity}`);
+    const toolActivity = formatToolActivity(run, "⠦", PLAIN_WORKFLOW_PROGRESS_STYLES, now);
+    if (toolActivity)
+        lines.push(`  ${toolActivity}`);
     if (run.error)
         lines.push(`Run error: ${run.error.code}: ${run.error.message}`);
     if (run.events?.length)
@@ -791,11 +811,10 @@ export function formatNavigatorRun(loaded, checkpoints, worktrees, now = Date.no
     const byId = new Map(run.agents.map((agent) => [agent.id, agent]));
     lines.push(...renderGroupedAgents(run.agents, ({ agent, index, depth }, grouped) => {
         const model = `${agent.model.provider}/${agent.model.model}${agent.model.thinking ? `:${agent.model.thinking}` : ""}`;
-        const role = agent.role ? ` role=${agent.role}` : "";
         const tools = ` tools=${agent.tools.join(",") || "(none)"}`;
         const accounting = agent.accounting ? ` input=${String(agent.accounting.input)} output=${String(agent.accounting.output)} cache-read=${String(agent.accounting.cacheRead)} cache-write=${String(agent.accounting.cacheWrite)} cost=${formatCost(agent.accounting.cost) || "$0.00"}` : "";
         const indent = "  ".repeat((grouped ? 2 : 1) + depth);
-        const result = [`${indent}#${String(index + 1)} ${grouped ? agent.label ?? agent.name : agentBreadcrumb(agent, byId)} state=${agent.state} model=${model}${agent.requestedModel ? ` requested=${agent.requestedModel}` : ""}${role}${tools} attempts=${String(agent.attempts)} retries=${String(Math.max(0, agent.attempts - 1))}${accounting}`];
+        const result = [`${indent}#${String(index + 1)} ${grouped ? agent.label ?? agent.name : agentBreadcrumb(agent, byId)} state=${agent.state} model=${model}${agent.requestedModel ? ` requested=${agent.requestedModel}` : ""}${tools} attempts=${String(agent.attempts)} retries=${String(Math.max(0, agent.attempts - 1))}${accounting}`];
         for (const attempt of agent.attemptDetails ?? [])
             result.push(`${indent}  attempt ${String(attempt.attempt)}${attempt.error ? ` error=${attempt.error.code}: ${attempt.error.message}` : ""}`);
         for (const call of agent.toolCalls ?? [])
@@ -835,17 +854,17 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
                 return;
             if (child.agent)
                 agents.push(child.agent);
-            else
-                for (const childId of child.children)
-                    visit(childId);
-        };
-        if (node.agent)
-            agents.push(node.agent);
-        else
-            for (const childId of node.children)
+            for (const childId of child.children)
                 visit(childId);
+        };
+        visit(node.id);
         return agents;
     };
+    const usageLines = (agents) => {
+        const spans = agents.flatMap((agent) => agent.startedAt === undefined ? [] : [[agent.startedAt, agent.startedAt + (elapsedDurationMs(agent, now) ?? 0)]]);
+        const elapsed = spans.length ? formatWorkflowRuntime(Math.max(...spans.map(([, end]) => end)) - Math.min(...spans.map(([start]) => start))) : "";
+        return [...formatAgentAccounting(sumAccounting(agents.map((agent) => agent.accounting ?? zeroAccounting()))), ...(elapsed ? [`Elapsed: ${elapsed}`] : [])];
+    };
     const nodeStatus = (node) => phaseStyle(node.state)(node.state);
     const nodeIcon = (node) => node.children.length ? expanded.has(node.id) ? "▾" : "▸" : node.kind === "agent" ? "•" : node.kind === "shell" ? "◇" : " ";
     const treeLine = (node) => {
@@ -866,12 +885,12 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
             const selected = node.phase;
             const counts = selected?.counts ?? phaseAgentCounts(agents);
             const hint = node.children.length ? "enter expand/collapse" : "enter phase details";
-            return [styles.bold(`Selected phase: ${node.label}`), `Status: ${nodeStatus(node)}`, `agents completed=${String(counts.completed)} running=${String(counts.running)} failed=${String(counts.failed)} cancelled=${String(counts.cancelled)} pending=${String(counts.pending)}`, `Agents: ${String(agents.length)}`, ...(selection.actions ? [] : [styles.muted(hint)])];
+            return [styles.bold(`Selected phase: ${node.label}`), `Status: ${nodeStatus(node)}`, `agents completed=${String(counts.completed)} running=${String(counts.running)} failed=${String(counts.failed)} cancelled=${String(counts.cancelled)} pending=${String(counts.pending)}`, `Agents: ${String(agents.length)}`, ...usageLines(agents), ...(selection.actions ? [] : [styles.muted(hint)])];
         }
         if (node.kind === "operation") {
             const states = phaseAgentCounts(agents);
             const hint = node.children.length ? "enter expand/collapse" : "enter phase details";
-            return [styles.bold(`Selected operation: ${node.operationPath.join(" > ")}`), `Phase: ${node.phase?.name ?? node.phaseId}`, `Status: ${nodeStatus(node)}`, `agents completed=${String(states.completed)} running=${String(states.running)} failed=${String(states.failed)} cancelled=${String(states.cancelled)} pending=${String(states.pending)}`, `Agents: ${String(agents.length)}`, ...(selection.actions ? [] : [styles.muted(hint)])];
+            return [styles.bold(`Selected operation: ${node.operationPath.join(" > ")}`), `Phase: ${node.phase?.name ?? node.phaseId}`, `Status: ${nodeStatus(node)}`, `agents completed=${String(states.completed)} running=${String(states.running)} failed=${String(states.failed)} cancelled=${String(states.cancelled)} pending=${String(states.pending)}`, `Agents: ${String(agents.length)}`, ...usageLines(agents), ...(selection.actions ? [] : [styles.muted(hint)])];
         }
         if (node.kind === "shell") {
             return [styles.bold("Selected shell"), formatShellActivity(node.shellActivity?.active, node.shellActivity?.startedAt, "⠦", styles, now) ?? "shell [running]"];
@@ -897,6 +916,9 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
     const shellActivity = scopedShells ? undefined : formatShellActivity(run.activeShells, run.activeShellStartedAt, "⠦", styles, now);
     if (shellActivity)
         lines.push(`  ${shellActivity}`);
+    const toolActivity = formatToolActivity(run, "⠦", styles, now);
+    if (toolActivity)
+        lines.push(`  ${toolActivity}`);
     const actionRows = () => {
         const actions = selection.actions;
         if (!actions)
@@ -904,7 +926,8 @@ export function formatWorkflowPhaseDashboard(run, snapshot, width, selection = {
         return ["", styles.bold(actions.title), ...actions.options.map((option, index) => `${index === actions.index ? "→ " : "  "}${index === actions.index ? styles.accent(option) : option}`)];
     };
     const treeRows = [styles.bold("Tree"), ...(visibleNodes.length ? visibleNodes.map(treeLine) : [styles.muted("(empty)")])];
-    lines.push(...formatNavigatorColumns(treeRows, [...details(selectedNode), ...actionRows()], safeWidth, selection));
+    const detailOffset = Math.max(0, (selection.scrollTop ?? 0) - lines.flatMap(wrap).length);
+    lines.push(...formatNavigatorColumns(treeRows, [...details(selectedNode), ...actionRows()], safeWidth, { ...selection, detailOffset }));
     if (model.unassignedAgents?.length && !tree.nodes.some((node) => node.phaseId === "unassigned"))
         lines.push(...wrap(styles.muted(`Unassigned agents: ${String(model.unassignedAgents.length)}`)));
     return lines.flatMap((line) => wrap(line));
@@ -918,7 +941,10 @@ export function formatNavigatorColumns(sidebar, detail, width, layout = {}) {
     if (safeWidth >= 80) {
         const sidebarWidth = Math.min(42, Math.max(24, Math.floor((safeWidth - 3) * 0.38)));
         const left = sidebar.flatMap((line) => wrapNavigatorLine(line, sidebarWidth));
-        const right = detail.flatMap((line) => wrapNavigatorLine(line, safeWidth - sidebarWidth - 3));
+        const wrapped = detail.flatMap((line) => wrapNavigatorLine(line, safeWidth - sidebarWidth - 3));
+        // Keep the details in view when the tree is scrolled, without making the block taller than the tree.
+        const shift = Math.min(Math.max(0, layout.detailOffset ?? 0), Math.max(0, left.length - wrapped.length));
+        const right = [...Array(shift).fill(""), ...wrapped];
         return Array.from({ length: Math.max(left.length, right.length) }, (_, index) => {
             const cell = left[index] ?? "";
             return `${cell}${" ".repeat(Math.max(0, sidebarWidth - visibleWidth(cell)))} | ${right[index] ?? ""}`;

package/dist/src/host.d.ts

@@ -2,7 +2,7 @@ import { Type } from "@earendil-works/pi-ai";
 import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type BackgroundWidgetAPI } from "./background-widget.js";
 import { type AgentTransport } from "./types.js";
-export type WorkflowExtensionAPI = Pick<ExtensionAPI, "appendEntry" | "getActiveTools" | "getThinkingLevel" | "on" | "registerCommand" | "registerTool" | "sendMessage"> & Pick<BackgroundWidgetAPI, "events" | "registerEntryRenderer" | "registerShortcut">;
+export type WorkflowExtensionAPI = Pick<ExtensionAPI, "appendEntry" | "getActiveTools" | "getThinkingLevel" | "on" | "registerCommand" | "registerTool" | "sendMessage"> & Partial<Pick<ExtensionAPI, "getAllTools">> & Pick<BackgroundWidgetAPI, "events" | "registerEntryRenderer" | "registerShortcut">;
 export { agentBreadcrumb, agentBreadcrumbParts, formatBudgetStatus, formatNavigatorDashboard, formatNavigatorRun, formatStalledDuration, formatWorkflowPhaseDashboard, formatWorkflowProgress, navigatorAttentionSort, truncateWorkflowProgress, } from "./host-view.js";
 export { buildWorkflowPhaseModel, buildWorkflowPhaseTree, navigateWorkflowPhaseTree, preserveWorkflowPhaseSelection, preserveWorkflowPhaseTreeSelection, workflowPhaseTreeInitialExpanded, workflowPhaseTreeVisibleNodes } from "./host-phases.js";
 export type { WorkflowPhaseAgentCounts, WorkflowPhaseModel, WorkflowPhaseSelection, WorkflowPhaseState, WorkflowPhaseTree, WorkflowPhaseTreeDirection, WorkflowPhaseTreeNode, WorkflowPhaseTreeNodeKind, WorkflowPhaseTreeSelection, WorkflowPhaseView, } from "./host-phases.js";
@@ -16,7 +16,7 @@ export declare function formatWorkflowPreview(args: {
     description?: unknown;
 }): string;
 export declare const WORKFLOW_TOOL_LABEL = "Workflow";
-export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow with a named inline or file-backed parallel-to-summary path by default";
+export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow with a named inline or file-backed parallel-to-summary path by default. Scripts call this session's tools as `await tools.<name>(args)`, outside withWorktree: a tool resolves to its text unless its description gives a `tools.<name>(args)` result shape, and failures reject";
 export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow. Prefer a named inline script that fans out independent work with parallel(...), awaits the keyed results before interpolating them into one summarizing agent(...), and returns. Provide exactly one of script or scriptPath and a non-empty name. Registered catalog functions are available as globals inside the script; call them there, for example return await someFunction(args). Advanced controls include registered functions, outputSchema, budgets, checkpoints, worktrees, retry/resume, CLI export, and pipelines. Runs are in the background by default; completion arrives as a follow-up message. Set foreground: true when the caller must wait for the final value. Manage runs from the interactive /workflow picker; use workflow_status, workflow_resume, workflow_retry, workflow_stop, and workflow_respond for explicit tool controls. If a foreground call detaches before its result is accepted, its terminal success or failure is promoted to one follow-up message. Foreground results include the completed run ID. Recovery inherits the source launch mode; legacy snapshots without launchMode recover in the background. Set foreground: true or false on workflow_resume/workflow_retry to override it; foreground recovery waits for terminal value and run details, while background recovery returns immediately and delivers completion or failure as a follow-up. After failure follow-ups, especially CANCELLED or interrupted runs, call workflow_status({ runId }) before recovery or replacement work, then pass its state as expectedState to workflow_retry/workflow_resume so recovery cannot act on a state that changed. Recovery map: agent(..., { retries }) reruns one agent call in the same run for transient failures; workflow_retry({ runId, expectedState?, foreground? }) replays a failed run into a child; workflow_resume({ runId, expectedState?, budget?, foreground? }) continues a budget_exhausted run; parentRunId on a new launch only borrows named worktrees and never replays or resumes.";
 export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     name: Type.TString;