@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/workflows/src/extension/workflow-targets.ts

@@ -0,0 +1,181 @@
+import { getEnvValue, WORKFLOW_STAGE_SUBAGENT_GUARD_ENV } from "@bastani/atomic";
+import type { RunStatus } from "../shared/store-types.js";
+import { store } from "../shared/store.js";
+import { expandWorkflowGraph, expandedStageLabel, stageMatchesExpandedIdentifier } from "../shared/expanded-workflow-graph.js";
+import { topLevelWorkflowRuns } from "../shared/run-visibility.js";
+import type { OverlayPiSurface } from "../tui/overlay-adapter.js";
+import type { PiExecuteContext } from "./public-types.js";
+import type { WorkflowToolArgs } from "./public-types.js";
+import type { PiUISurface } from "./wiring.js";
+
+export function formatAlreadyEndedRetainedMessage(runId: string): string {
+  return `Run ${runId.slice(0, 8)} already ended; retained for inspection.`;
+}
+
+export function stageFailureMessage(
+  runId: string,
+  resultReason: string,
+  action: "pause" | "interrupt",
+): string {
+  switch (resultReason) {
+    case "not_found":
+      return `Run not found: ${runId}`;
+    case "already_ended":
+      return `Run already ended: ${runId}`;
+    case "stage_not_found":
+      return `Stage not found for run: ${runId}`;
+    default:
+      return `No active stages to ${action} for run: ${runId}`;
+  }
+}
+
+export function inFlightRunCount(): number {
+  return topLevelWorkflowRuns(store.runs()).filter((run) => run.endedAt === undefined).length;
+}
+
+export function topLevelExpandedSnapshots() {
+  const snapshot = store.snapshot();
+  return topLevelWorkflowRuns(snapshot.runs).map((run) => ({
+    ...structuredClone(run),
+    stages: expandWorkflowGraph(snapshot, run.id).stages.map((stage) => structuredClone(stage)),
+  }));
+}
+
+export function reloadBlockedMessage(count = inFlightRunCount()): string {
+  return `Reload skipped: ${count} workflow run(s) still in flight. Wait for them to finish, or pause/kill them before reloading workflow resources.`;
+}
+
+export function allStageConflictMessage(action: "pause" | "interrupt" | "kill"): string {
+  return `Cannot ${action} --all with a stageId; omit stageId or target a single run.`;
+}
+
+export class WorkflowReloadBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowReloadBlockedError";
+  }
+}
+
+export function reloadFailureMessage(error: unknown): string {
+  if (error instanceof WorkflowReloadBlockedError) return error.message;
+  return `Reload failed: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+function hasWorkflowStageSubagentGuardEnv(): boolean {
+  return getEnvValue(WORKFLOW_STAGE_SUBAGENT_GUARD_ENV) === "1";
+}
+
+export function isWorkflowStageToolContext(ctx: PiExecuteContext): boolean {
+  return hasWorkflowStageSubagentGuardEnv() || ctx.orchestrationContext?.kind === "workflow-stage";
+}
+
+export function isRunStatus(value: string): value is RunStatus {
+  switch (value) {
+    case "pending":
+    case "running":
+    case "paused":
+    case "completed":
+    case "skipped":
+    case "cancelled":
+    case "blocked":
+    case "failed":
+    case "killed":
+      return true;
+    default:
+      return false;
+  }
+}
+
+export type RunIdResolution =
+  | { kind: "exact"; runId: string }
+  | { kind: "ambiguous"; matches: string[] }
+  | { kind: "not_found" };
+
+export function resolveRunIdPrefix(target: string): RunIdResolution {
+  const runs = store.runs();
+  const exact = runs.find((r) => r.id === target);
+  if (exact) return { kind: "exact", runId: exact.id };
+  const prefixed = runs.filter((r) => r.id.startsWith(target));
+  if (prefixed.length === 0) return { kind: "not_found" };
+  if (prefixed.length === 1) return { kind: "exact", runId: prefixed[0]!.id };
+  return { kind: "ambiguous", matches: prefixed.map((r) => r.id) };
+}
+
+export type ToolRunTarget =
+  | { kind: "all" }
+  | { kind: "run"; runId: string }
+  | { kind: "ambiguous"; target: string; matches: string[] }
+  | { kind: "not_found"; target: string; message: string };
+
+export function resolveToolRunTarget(
+  args: WorkflowToolArgs,
+  emptyMessage: string,
+): ToolRunTarget {
+  const rawTarget = args.runId?.trim() ?? "";
+  if (args.all === true || rawTarget === "--all") return { kind: "all" };
+  const target = rawTarget || store.activeRunId() || "";
+  if (!target) return { kind: "not_found", target: rawTarget, message: emptyMessage };
+  const resolved = resolveRunIdPrefix(target);
+  if (resolved.kind === "exact") return { kind: "run", runId: resolved.runId };
+  if (resolved.kind === "ambiguous") return { kind: "ambiguous", target, matches: resolved.matches };
+  return { kind: "not_found", target, message: `Run not found: ${target}` };
+}
+
+export type ToolStageTarget =
+  | { ok: true; runId?: string; stageId?: string }
+  | { ok: false; message: string };
+
+export function resolveStageTarget(runId: string, stageTarget?: string): ToolStageTarget {
+  const target = stageTarget?.trim();
+  if (!target) return { ok: true, runId };
+  const graph = expandWorkflowGraph(store.snapshot(), runId);
+  const exactId = graph.stages.find(
+    (stage) => stage.id === target || stage.workflowGraphTarget.stageId === target,
+  );
+  if (exactId !== undefined) {
+    return {
+      ok: true,
+      runId: exactId.workflowGraphTarget.runId,
+      stageId: exactId.workflowGraphTarget.stageId,
+    };
+  }
+  const exactNames = graph.stages.filter((stage) => stage.name === target);
+  if (exactNames.length === 1) {
+    const stage = exactNames[0]!;
+    return {
+      ok: true,
+      runId: stage.workflowGraphTarget.runId,
+      stageId: stage.workflowGraphTarget.stageId,
+    };
+  }
+  if (exactNames.length > 1) {
+    return { ok: false, message: `Ambiguous stage identifier "${target}" matches: ${exactNames.map(expandedStageLabel).join(", ")}` };
+  }
+  const matches = graph.stages.filter((stage) => stageMatchesExpandedIdentifier(stage, target));
+  if (matches.length === 0) return { ok: false, message: `Stage not found in run ${runId.slice(0, 8)}: ${target}` };
+  if (matches.length > 1) {
+    return { ok: false, message: `Ambiguous stage identifier "${target}" matches: ${matches.map(expandedStageLabel).join(", ")}` };
+  }
+  const stage = matches[0]!;
+  return {
+    ok: true,
+    runId: stage.workflowGraphTarget.runId,
+    stageId: stage.workflowGraphTarget.stageId,
+  };
+}
+
+export function resolveToolStageTarget(runId: string, stageTarget?: string): ToolStageTarget {
+  return resolveStageTarget(runId, stageTarget);
+}
+
+export function ambiguousRunMessage(target: string, matches: readonly string[]): string {
+  return `Ambiguous run prefix "${target}" matches: ${matches
+    .map((id) => id.slice(0, 12))
+    .join(", ")}`;
+}
+
+export function overlaySurfaceFromContext(ctx?: {
+  ui?: PiUISurface;
+}): OverlayPiSurface | undefined {
+  return typeof ctx?.ui?.custom === "function" ? { ui: ctx.ui } : undefined;
+}

package/dist/builtin/workflows/src/extension/workflow-tool-content.ts

@@ -0,0 +1,175 @@
+import { deriveInputFields } from "../shared/schema-introspection.js";
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { WorkflowToolArgs } from "./public-types.js";
+
+function stringifyWorkflowToolResult(result: WorkflowToolResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+function compactWorkflowToolMessage(
+  result: Extract<WorkflowToolResult, {
+    action: "send" | "pause" | "reload" | "interrupt" | "kill" | "resume";
+  }>,
+): string {
+  if (result.action === "reload") {
+    return `${result.action}: ${result.status} — ${result.message}`;
+  }
+  const target = [
+    result.runId,
+    result.action === "send" ? result.stageId : undefined,
+  ].filter((part): part is string => part !== undefined && part.length > 0)
+    .join("/");
+  return `${result.action}:${target ? ` ${target}` : ""} ${result.status} — ${result.message}`;
+}
+
+function renderTranscriptToolContent(
+  result: Extract<WorkflowToolResult, { action: "transcript" }>,
+): string {
+  const lines = [
+    "action: transcript",
+    `runId: ${result.runId}`,
+    `stageId: ${result.stageId}`,
+    `source: ${result.source}`,
+    `truncated: ${result.truncated}`,
+  ];
+  if (result.sessionId) lines.push(`sessionId: ${result.sessionId}`);
+  if (result.sessionFile) lines.push(`sessionFile: ${result.sessionFile}`);
+  if (result.sessionFile) lines.push(`sessionFileJson: ${JSON.stringify(result.sessionFile)}`);
+  if (result.transcriptPath) lines.push(`transcriptPath: ${result.transcriptPath}`);
+  if (result.transcriptPath) lines.push(`transcriptPathJson: ${JSON.stringify(result.transcriptPath)}`);
+  if (result.entryCount !== undefined) lines.push(`availableEntries: ${result.entryCount}`);
+  if (result.entryLimit !== undefined) lines.push(`entryLimit: ${result.entryLimit}`);
+  if (result.lazyReadPrompt) lines.push(`lazyReadPrompt: ${result.lazyReadPrompt}`);
+  if (result.fallbackNote) lines.push(`fallbackNote: ${result.fallbackNote}`);
+  if (result.entries.length === 0) {
+    lines.push(result.inlineMode === "path_only" || result.lazyReadPrompt ? "entries: not inlined" : "entries: none");
+    return lines.join("\n");
+  }
+  lines.push("entries:");
+  result.entries.forEach((entry, index) => {
+    const metadata = [
+      `[${index + 1}]`,
+      `role=${entry.role}`,
+      entry.toolName ? `tool=${entry.toolName}` : undefined,
+      entry.timestamp !== undefined ? `timestamp=${entry.timestamp}` : undefined,
+    ].filter((part): part is string => part !== undefined);
+    lines.push(metadata.join(" "));
+    if (entry.text !== undefined) lines.push(entry.text);
+    if (entry.output !== undefined) {
+      lines.push("tool output:");
+      lines.push(entry.output);
+    }
+    if (entry.text === undefined && entry.output === undefined) lines.push("(no body)");
+  });
+  return lines.join("\n");
+}
+
+function renderStagesToolContent(
+  result: Extract<WorkflowToolResult, { action: "stages" }>,
+): string {
+  const lines = ["action: stages", `runId: ${result.runId}`, `filter: ${result.filter}`];
+  if (result.error) lines.push(`error: ${result.error}`);
+  if (result.stages.length === 0) {
+    lines.push("stages: none");
+    return lines.join("\n");
+  }
+  lines.push("stages:");
+  result.stages.forEach((stage, index) => {
+    lines.push(`[${index + 1}] ${stage.name} (${stage.id}) ${stage.status}`);
+    if (stage.sessionId) lines.push(`sessionId: ${stage.sessionId}`);
+    if (stage.sessionFile) lines.push(`sessionFile: ${stage.sessionFile}`);
+    if (stage.sessionFile) lines.push(`sessionFileJson: ${JSON.stringify(stage.sessionFile)}`);
+    if (stage.transcriptPath) lines.push(`transcriptPath: ${stage.transcriptPath}`);
+    if (stage.transcriptPath) lines.push(`transcriptPathJson: ${JSON.stringify(stage.transcriptPath)}`);
+    if (stage.error) lines.push(`error: ${stage.error}`);
+    if (stage.skippedReason) lines.push(`skippedReason: ${stage.skippedReason}`);
+    if (stage.awaitingInputSince !== undefined) lines.push(`awaitingInputSince: ${stage.awaitingInputSince}`);
+    if (stage.pendingPrompt !== undefined) {
+      lines.push("pendingPrompt:");
+      lines.push(JSON.stringify(stage.pendingPrompt, null, 2));
+    }
+    if (stage.inputRequest !== undefined) {
+      lines.push("inputRequest:");
+      lines.push(JSON.stringify(stage.inputRequest, null, 2));
+    }
+    if (stage.promptFootprint !== undefined) {
+      lines.push("promptFootprint:");
+      lines.push(JSON.stringify(stage.promptFootprint, null, 2));
+    }
+  });
+  return lines.join("\n");
+}
+
+function renderStageToolContent(
+  result: Extract<WorkflowToolResult, { action: "stage" }>,
+): string {
+  const lines = ["action: stage", `runId: ${result.runId}`];
+  if (result.error || result.stage === undefined) {
+    lines.push(`error: ${result.error ?? "stage not found"}`);
+    return lines.join("\n");
+  }
+  lines.push("stage:");
+  lines.push(JSON.stringify(result.stage, null, 2));
+  if (result.stage.sessionFile) {
+    lines.push(`transcriptPath: ${result.stage.sessionFile}`);
+    lines.push(`transcriptPathJson: ${JSON.stringify(result.stage.sessionFile)}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderWorkflowToolContent(
+  result: WorkflowToolResult,
+  args: WorkflowToolArgs,
+): string {
+  if (args.format === "json") return stringifyWorkflowToolResult(result);
+  switch (result.action) {
+    case "transcript":
+      return renderTranscriptToolContent(result);
+    case "stages":
+      return renderStagesToolContent(result);
+    case "stage":
+      return renderStageToolContent(result);
+    case "send":
+    case "pause":
+    case "reload":
+    case "interrupt":
+    case "kill":
+    case "resume":
+      return compactWorkflowToolMessage(result);
+    case "list":
+    case "status":
+    case "statusDetail":
+    case "inputs":
+    case "get":
+    case "run":
+      return stringifyWorkflowToolResult(result);
+  }
+}
+
+export function workflowGetResult(
+  runtime: ExtensionRuntime,
+  args: WorkflowToolArgs,
+): WorkflowToolResult {
+  const workflow = args.workflow ?? "";
+  const def = runtime.registry.get(workflow);
+  if (!def) return { action: "get", workflow, error: `Workflow not found: "${workflow}"` };
+  const inputs = deriveInputFields(def.inputs);
+  return {
+    action: "get",
+    workflow: def.normalizedName,
+    details: {
+      mode: "inspection",
+      action: "get",
+      status: "completed",
+      output: {
+        workflow: def.normalizedName,
+        name: def.name,
+        description: def.description,
+        inputs: inputs as unknown as WorkflowSerializableValue[],
+      },
+      progress: { completed: 0, total: 0 },
+    },
+  };
+}

package/dist/builtin/workflows/src/extension/workflow-tool-control.ts

@@ -0,0 +1,205 @@
+import {
+  interruptAllRuns,
+  interruptRun,
+  killAllRuns,
+  killRun,
+  pauseAllRuns,
+  pauseRun,
+  resumeRun,
+} from "../runs/background/status.js";
+import { cancellationRegistry } from "../runs/background/cancellation-registry.js";
+import { store } from "../shared/store.js";
+import type { WorkflowExecutionPolicy, WorkflowPersistencePort } from "../shared/types.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { WorkflowToolArgs } from "./public-types.js";
+import {
+  allStageConflictMessage,
+  ambiguousRunMessage,
+  formatAlreadyEndedRetainedMessage,
+  inFlightRunCount,
+  reloadBlockedMessage,
+  reloadFailureMessage,
+  resolveToolRunTarget,
+  resolveToolStageTarget,
+  stageFailureMessage,
+} from "./workflow-targets.js";
+
+export interface WorkflowControlActionDeps {
+  getPersistence: () => WorkflowPersistencePort | undefined;
+  reloadWorkflowResources: () => Promise<void> | void;
+  runtime: ExtensionRuntime;
+  policy: WorkflowExecutionPolicy;
+}
+
+export function workflowPauseAction(args: WorkflowToolArgs): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No in-flight runs to pause.");
+  const action = "pause";
+  if (target.kind === "all") {
+    if (args.stageId !== undefined && args.stageId.length > 0) {
+      return { action, runId: "--all", status: "noop", message: allStageConflictMessage("pause") };
+    }
+    const results = pauseAllRuns();
+    const paused = results.filter((r) => r.ok).length;
+    return {
+      action,
+      runId: "--all",
+      status: paused > 0 ? "paused" : "noop",
+      message: paused > 0 ? `Paused ${paused} run(s).` : "No in-flight runs to pause.",
+    };
+  }
+  if (target.kind === "ambiguous") return { action, runId: target.target, status: "noop", message: ambiguousRunMessage(target.target, target.matches) };
+  if (target.kind === "not_found") return { action, runId: target.target, status: "noop", message: target.message };
+  const stage = resolveToolStageTarget(target.runId, args.stageId);
+  if (!stage.ok) return { action, runId: target.runId, status: "noop", message: stage.message };
+  const stageRunId = stage.runId ?? target.runId;
+  const result = pauseRun(stageRunId, { stageId: stage.stageId });
+  return result.ok
+    ? { action, runId: result.runId, status: "paused", message: `Paused ${result.paused.length} stage(s) on run ${result.runId.slice(0, 8)}.` }
+    : {
+        action,
+        runId: stageRunId,
+        status: "noop",
+        message: stageFailureMessage(stageRunId, result.reason, "pause"),
+      };
+}
+
+export async function workflowReloadAction(
+  args: WorkflowToolArgs,
+  deps: Pick<WorkflowControlActionDeps, "reloadWorkflowResources">,
+): Promise<WorkflowToolResult> {
+  const activeRuns = inFlightRunCount();
+  if (activeRuns > 0) {
+    return { action: "reload", status: "noop", message: reloadBlockedMessage(activeRuns) };
+  }
+  try {
+    await deps.reloadWorkflowResources();
+  } catch (error) {
+    return { action: "reload", status: "noop", message: reloadFailureMessage(error) };
+  }
+  return {
+    action: "reload",
+    status: "ok",
+    message: args.reason?.trim()
+      ? `Reloaded workflow resources (${args.reason.trim()}).`
+      : "Reloaded workflow resources.",
+  };
+}
+
+export function workflowKillAction(
+  args: WorkflowToolArgs,
+  deps: Pick<WorkflowControlActionDeps, "getPersistence">,
+): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No in-flight runs to kill.");
+  const action = "kill";
+  if (target.kind === "all") {
+    if (args.stageId !== undefined && args.stageId.length > 0) {
+      return { action, runId: "--all", status: "noop", message: allStageConflictMessage("kill") };
+    }
+    const results = killAllRuns({ cancellation: cancellationRegistry, persistence: deps.getPersistence() });
+    const killed = results.filter((r) => r.ok).length;
+    return {
+      action,
+      runId: "--all",
+      status: killed > 0 ? "killed" : "noop",
+      message: killed > 0 ? `Killed and retained ${killed} run(s) for inspection.` : "No in-flight runs to kill.",
+    };
+  }
+  if (target.kind === "ambiguous") return { action, runId: target.target, status: "noop", message: ambiguousRunMessage(target.target, target.matches) };
+  if (target.kind === "not_found") return { action, runId: target.target, status: "noop", message: target.message };
+  const result = killRun(target.runId, { cancellation: cancellationRegistry, persistence: deps.getPersistence() });
+  if (result.ok) {
+    return {
+      action,
+      runId: result.runId,
+      status: "killed",
+      message: `Run ${result.runId} killed and retained for inspection (was ${result.previousStatus}).`,
+    };
+  }
+  return {
+    action,
+    runId: target.runId,
+    status: "noop",
+    message: result.reason === "already_ended"
+      ? formatAlreadyEndedRetainedMessage(target.runId)
+      : `Run not found: ${target.runId}`,
+  };
+}
+
+export function workflowInterruptAction(args: WorkflowToolArgs): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No in-flight runs to interrupt.");
+  const action = "interrupt";
+  if (target.kind === "all") {
+    if (args.stageId !== undefined && args.stageId.length > 0) {
+      return { action, runId: "--all", status: "noop", message: allStageConflictMessage("interrupt") };
+    }
+    const results = interruptAllRuns();
+    const interrupted = results.filter((r) => r.ok).length;
+    return {
+      action,
+      runId: "--all",
+      status: interrupted > 0 ? "paused" : "noop",
+      message: interrupted > 0 ? `Interrupted ${interrupted} run(s).` : "No in-flight runs to interrupt.",
+    };
+  }
+  if (target.kind === "ambiguous") return { action, runId: target.target, status: "noop", message: ambiguousRunMessage(target.target, target.matches) };
+  if (target.kind === "not_found") return { action, runId: target.target, status: "noop", message: target.message };
+  const stage = resolveToolStageTarget(target.runId, args.stageId);
+  if (!stage.ok) return { action, runId: target.runId, status: "noop", message: stage.message };
+  const stageRunId = stage.runId ?? target.runId;
+  const result = interruptRun(stageRunId, { stageId: stage.stageId });
+  if (result.ok) {
+    return {
+      action,
+      runId: result.runId,
+      status: "paused",
+      message: stage.stageId
+        ? `Stage ${stage.stageId} interrupted on run ${result.runId} and can be resumed.`
+        : `Run ${result.runId} interrupted and can be resumed.`,
+    };
+  }
+  return {
+    action,
+    runId: stageRunId,
+    status: "noop",
+    message: stageFailureMessage(stageRunId, result.reason, "interrupt"),
+  };
+}
+
+export function workflowResumeAction(
+  args: WorkflowToolArgs,
+  deps: Pick<WorkflowControlActionDeps, "runtime" | "policy">,
+): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No active run to resume.");
+  if (target.kind === "all") return { action: "resume", runId: "--all", status: "noop", message: "Resume does not support --all." };
+  if (target.kind === "ambiguous") return { action: "resume", runId: target.target, status: "noop", message: ambiguousRunMessage(target.target, target.matches) };
+  if (target.kind === "not_found") return { action: "resume", runId: target.target, status: "noop", message: target.message };
+  const stage = resolveToolStageTarget(target.runId, args.stageId);
+  if (!stage.ok) return { action: "resume", runId: target.runId, status: "noop", message: stage.message };
+  const stageRunId = stage.runId ?? target.runId;
+  const run = store.runs().find((r) => r.id === stageRunId);
+  const isPaused = run?.status === "paused" || (run?.stages.some((s) => s.status === "paused") ?? false);
+  const isResumableContinuation = run !== undefined && !isPaused && (
+    (run.status === "failed" && run.endedAt !== undefined && run.resumable !== false) ||
+    (run.endedAt === undefined && run.resumable === true && run.failureRecoverability === "recoverable")
+  );
+  if (isResumableContinuation) {
+    const continuation = deps.runtime.resumeFailedRun(stageRunId, stage.stageId, { policy: deps.policy });
+    return {
+      action: "resume",
+      runId: continuation.ok ? continuation.runId : stageRunId,
+      status: continuation.ok ? "running" : "noop",
+      message: continuation.message,
+    };
+  }
+  const result = resumeRun(stageRunId, { stageId: stage.stageId, message: args.message });
+  if (result.ok) {
+    const message = result.message ?? (isPaused
+      ? result.resumed.length === 0
+        ? `No paused stages on run ${result.runId.slice(0, 8)}.`
+        : `Resumed ${result.resumed.length} stage(s) on run ${result.runId.slice(0, 8)}${args.message ? ` with message: "${args.message}"` : ""}.`
+      : `Snapshot available: run ${result.runId} (${result.snapshot.name}) — status: ${result.snapshot.status}, stages: ${result.snapshot.stages.length}`);
+    return { action: "resume", runId: result.runId, status: "ok", message };
+  }
+  return { action: "resume", runId: stageRunId, status: "noop", message: `Run not found: ${stageRunId}` };
+}

package/dist/builtin/workflows/src/extension/workflow-tool-helpers.ts

@@ -0,0 +1,66 @@
+import type { WorkflowDetails } from "../shared/types.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { PiExecuteContext, WorkflowToolArgs } from "./public-types.js";
+
+export function hasDirectExecutionMode(args: WorkflowToolArgs): boolean {
+  return (
+    (args.task !== undefined && typeof args.task === "object") ||
+    Array.isArray(args.tasks) ||
+    Array.isArray(args.chain)
+  );
+}
+
+export function directModeCount(args: WorkflowToolArgs): number {
+  return [
+    args.task !== undefined && typeof args.task === "object",
+    Array.isArray(args.tasks),
+    Array.isArray(args.chain),
+  ].filter(Boolean).length;
+}
+
+export function hasNamedExecutionMode(args: WorkflowToolArgs): boolean {
+  return typeof args.workflow === "string" && args.workflow.trim().length > 0;
+}
+
+function directRequestsFork(args: WorkflowToolArgs): boolean {
+  if (args.context === "fork") return true;
+  if (
+    args.task !== undefined &&
+    typeof args.task === "object" &&
+    args.task.context === "fork"
+  ) return true;
+  if (args.tasks?.some((task) => task.context === "fork")) return true;
+  return (
+    args.chain?.some((step) =>
+      "parallel" in step
+        ? step.parallel.some((task) => task.context === "fork")
+        : step.context === "fork",
+    ) ?? false
+  );
+}
+
+export function withForkParentSession(
+  args: WorkflowToolArgs,
+  ctx: PiExecuteContext,
+): WorkflowToolArgs {
+  if (!directRequestsFork(args) || args.forkFromSessionFile !== undefined) return args;
+  const sessionFile = ctx.sessionManager?.getSessionFile?.();
+  return typeof sessionFile === "string" && sessionFile.length > 0
+    ? { ...args, forkFromSessionFile: sessionFile }
+    : args;
+}
+
+export function workflowRunResultFromDetails(
+  details: WorkflowDetails,
+): WorkflowToolResult {
+  return {
+    action: "run",
+    name: `direct-${details.mode}`,
+    runId: details.runId ?? "",
+    status: details.status,
+    result: details.output,
+    details,
+    error: details.error,
+    stages: [],
+  };
+}