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

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

@@ -0,0 +1,164 @@
+import { stageControlRegistry } from "../runs/foreground/stage-control-registry.js";
+import { store } from "../shared/store.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { WorkflowToolArgs } from "./public-types.js";
+import {
+  cloneStage,
+  shapeTranscriptResult,
+  shouldIncludeSnapshotToolOutput,
+  snapshotTranscriptEntries,
+  snapshotTranscriptEntryCount,
+  summarizeStage,
+  transcriptEntryFromMessage,
+  type MessageLike,
+} from "./workflow-stage-results.js";
+import {
+  ambiguousRunMessage,
+  resolveToolRunTarget,
+  resolveToolStageTarget,
+} from "./workflow-targets.js";
+
+export function workflowStagesResult(args: WorkflowToolArgs): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No active run to inspect.");
+  const filter = args.statusFilter ?? "all";
+  if (target.kind === "all") {
+    return {
+      action: "stages",
+      runId: "--all",
+      filter,
+      stages: [],
+      error: "Stage listing requires a single run.",
+    };
+  }
+  if (target.kind === "ambiguous") {
+    return {
+      action: "stages",
+      runId: target.target,
+      filter,
+      stages: [],
+      error: ambiguousRunMessage(target.target, target.matches),
+    };
+  }
+  if (target.kind === "not_found") {
+    return {
+      action: "stages",
+      runId: target.target,
+      filter,
+      stages: [],
+      error: target.message,
+    };
+  }
+  const run = store.runs().find((r) => r.id === target.runId);
+  const stages = (run?.stages ?? [])
+    .filter((stage) => filter === "all" || stage.status === filter)
+    .map(summarizeStage);
+  return { action: "stages", runId: target.runId, filter, stages };
+}
+
+export function workflowStageResult(args: WorkflowToolArgs): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No active run to inspect.");
+  if (target.kind === "all") {
+    return { action: "stage", runId: "--all", error: "Stage inspection requires a single run." };
+  }
+  if (target.kind === "ambiguous") {
+    return { action: "stage", runId: target.target, error: ambiguousRunMessage(target.target, target.matches) };
+  }
+  if (target.kind === "not_found") {
+    return { action: "stage", runId: target.target, error: target.message };
+  }
+  const stage = resolveToolStageTarget(target.runId, args.stageId);
+  if (!stage.ok || stage.stageId === undefined) {
+    return {
+      action: "stage",
+      runId: target.runId,
+      error: stage.ok ? "Stage id, prefix, or name is required." : stage.message,
+    };
+  }
+  const stageRunId = stage.runId ?? target.runId;
+  const run = store.runs().find((r) => r.id === stageRunId);
+  const snapshot = run?.stages.find((s) => s.id === stage.stageId);
+  return snapshot
+    ? { action: "stage", runId: stageRunId, stage: cloneStage(snapshot) }
+    : {
+        action: "stage",
+        runId: stageRunId,
+        error: `Stage not found in run ${stageRunId.slice(0, 8)}: ${stage.stageId}`,
+      };
+}
+
+export function workflowTranscriptResult(args: WorkflowToolArgs): WorkflowToolResult {
+  const target = resolveToolRunTarget(args, "No active run to inspect.");
+  if (target.kind === "all") {
+    return {
+      action: "transcript",
+      runId: "--all",
+      stageId: "",
+      source: "error",
+      entries: [],
+      truncated: false,
+    };
+  }
+  if (target.kind === "ambiguous") {
+    return {
+      action: "transcript",
+      runId: target.target,
+      stageId: "",
+      source: "error",
+      entries: [{ role: "notice", text: ambiguousRunMessage(target.target, target.matches) }],
+      truncated: false,
+    };
+  }
+  if (target.kind === "not_found") {
+    return {
+      action: "transcript",
+      runId: target.target,
+      stageId: "",
+      source: "error",
+      entries: [{ role: "notice", text: target.message }],
+      truncated: false,
+    };
+  }
+  const stage = resolveToolStageTarget(target.runId, args.stageId);
+  if (!stage.ok || stage.stageId === undefined) {
+    return {
+      action: "transcript",
+      runId: target.runId,
+      stageId: "",
+      source: "error",
+      entries: [{ role: "notice", text: stage.ok ? "Stage id, prefix, or name is required." : stage.message }],
+      truncated: false,
+    };
+  }
+  const stageRunId = stage.runId ?? target.runId;
+  const run = store.runs().find((r) => r.id === stageRunId);
+  const snapshot = run?.stages.find((s) => s.id === stage.stageId);
+  const liveHandle = stageControlRegistry.get(stageRunId, stage.stageId);
+  if (liveHandle !== undefined) {
+    const sessionFile = liveHandle.sessionFile ?? snapshot?.sessionFile;
+    const sessionId = liveHandle.sessionId ?? snapshot?.sessionId;
+    return shapeTranscriptResult({
+      runId: stageRunId,
+      stageId: stage.stageId,
+      source: "live",
+      entryCount: liveHandle.messages.length,
+      buildEntries: () => liveHandle.messages.map((m) => transcriptEntryFromMessage(m as MessageLike)),
+      args,
+      sessionId,
+      sessionFile,
+      transcriptPath: sessionFile,
+    });
+  }
+  const snapshotSessionFile = snapshot?.sessionFile;
+  const includeSnapshotOutput = shouldIncludeSnapshotToolOutput(args, snapshotSessionFile);
+  return shapeTranscriptResult({
+    runId: stageRunId,
+    stageId: stage.stageId,
+    source: "snapshot",
+    entryCount: snapshotTranscriptEntryCount(snapshot),
+    buildEntries: () => snapshotTranscriptEntries(snapshot, includeSnapshotOutput),
+    args,
+    sessionId: snapshot?.sessionId,
+    sessionFile: snapshotSessionFile,
+    transcriptPath: snapshotSessionFile,
+  });
+}

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

@@ -0,0 +1,54 @@
+import { renderCall } from "./render-call.js";
+import { renderResult } from "./render-result.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import { WorkflowParametersSchema } from "./workflow-schema.js";
+import { dynamicTextRenderComponent } from "./render-component.js";
+import type { ExtensionAPI, PiExecuteContext, WorkflowToolArgs } from "./public-types.js";
+import { DEFAULT_PROMPT_GUIDANCE, WORKFLOW_TOOL_DESCRIPTION } from "./workflow-prompts.js";
+import { workflowPolicyFromContext } from "./workflow-policy.js";
+import { renderWorkflowToolContent } from "./workflow-tool-content.js";
+
+export function registerWorkflowTool(
+  pi: ExtensionAPI,
+  executeWorkflowTool: (
+    args: WorkflowToolArgs,
+    ctx: PiExecuteContext,
+  ) => Promise<WorkflowToolResult>,
+  runWithLifecycleSuppressedForPolicy: <T>(
+    policy: ReturnType<typeof workflowPolicyFromContext>,
+    fn: () => Promise<T>,
+  ) => Promise<T>,
+): void {
+  if (typeof pi.registerTool !== "function") return;
+  pi.registerTool<WorkflowToolArgs, WorkflowToolResult>({
+    name: "workflow",
+    label: "workflow",
+    description: WORKFLOW_TOOL_DESCRIPTION,
+    parameters: WorkflowParametersSchema,
+    promptGuidelines: DEFAULT_PROMPT_GUIDANCE,
+    renderShell: "self",
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const policy = workflowPolicyFromContext(ctx);
+      const details = (params.action ?? "run") === "run"
+        ? await runWithLifecycleSuppressedForPolicy(policy, () => executeWorkflowTool(params, ctx))
+        : await executeWorkflowTool(params, ctx);
+      return {
+        content: [{ type: "text", text: renderWorkflowToolContent(details, params) }],
+        details,
+      };
+    },
+    renderCall: (args, _theme, _context) =>
+      dynamicTextRenderComponent((width) => renderCall(args, { width })),
+    renderResult: (result, opts, _theme, context) => {
+      const capturedNow = Date.now();
+      return dynamicTextRenderComponent((width) =>
+        renderResult(result.details, {
+          ...opts,
+          width,
+          now: capturedNow,
+          runInputs: (context as { args?: WorkflowToolArgs }).args?.inputs,
+        }),
+      );
+    },
+  });
+}

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

@@ -0,0 +1,164 @@
+import { stageControlRegistry } from "../runs/foreground/stage-control-registry.js";
+import { store } from "../shared/store.js";
+import { stageUiBroker } from "../shared/stage-ui-broker.js";
+import {
+  coerceStageInputAnswer,
+  hasStageInputAnswerContent,
+  type StageInputAnswer,
+} from "../shared/stage-prompt.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { WorkflowToolArgs } from "./public-types.js";
+import {
+  ambiguousRunMessage,
+  resolveToolRunTarget,
+  resolveToolStageTarget,
+} from "./workflow-targets.js";
+
+function hasPayloadProperty(args: WorkflowToolArgs): boolean {
+  return args.text !== undefined || args.response !== undefined || args.message !== undefined;
+}
+
+function promptPayloadFromArgs(args: WorkflowToolArgs): unknown {
+  if (args.response !== undefined) return args.response;
+  if (args.text !== undefined) return args.text;
+  return args.message;
+}
+
+function textPayloadFromArgs(args: WorkflowToolArgs): string | undefined {
+  if (args.text !== undefined) return args.text;
+  if (typeof args.response === "string") return args.response;
+  if (args.message !== undefined) return args.message;
+  return undefined;
+}
+
+function brokerAnswerFromArgs(args: WorkflowToolArgs): StageInputAnswer {
+  if (args.response !== undefined) {
+    const coerced = coerceStageInputAnswer(args.response);
+    if (hasStageInputAnswerContent(coerced)) return coerced;
+  }
+  const text = textPayloadFromArgs(args);
+  return text !== undefined ? { text } : {};
+}
+
+type WorkflowSendToolResult = Extract<WorkflowToolResult, { action: "send" }>;
+
+function workflowSendResult(
+  runId: string,
+  stageId: string,
+  delivery: WorkflowSendToolResult["delivery"],
+  status: WorkflowSendToolResult["status"],
+  message: string,
+): WorkflowSendToolResult {
+  return { action: "send", runId, stageId, delivery, status, message };
+}
+
+export async function workflowSendAction(args: WorkflowToolArgs): Promise<WorkflowSendToolResult> {
+  const target = resolveToolRunTarget(args, "No active run to message.");
+  const requestedDelivery = args.delivery ?? "auto";
+  if (target.kind === "all") {
+    return workflowSendResult("--all", "", requestedDelivery, "noop", "Send requires a single run.");
+  }
+  if (target.kind === "ambiguous") {
+    return workflowSendResult(target.target, "", requestedDelivery, "noop", ambiguousRunMessage(target.target, target.matches));
+  }
+  if (target.kind === "not_found") {
+    return workflowSendResult(target.target, "", requestedDelivery, "noop", target.message);
+  }
+  const stage = resolveToolStageTarget(target.runId, args.stageId);
+  if (!stage.ok || stage.stageId === undefined) {
+    return workflowSendResult(
+      target.runId,
+      "",
+      requestedDelivery,
+      "noop",
+      stage.ok ? "Stage id, prefix, or name is required." : stage.message,
+    );
+  }
+  const stageRunId = stage.runId ?? target.runId;
+  const run = store.runs().find((r) => r.id === stageRunId);
+  const snapshot = run?.stages.find((s) => s.id === stage.stageId);
+  const brokerPrompt = stageUiBroker.peekStagePrompt(stageRunId, stage.stageId);
+  const targetsBrokerPrompt =
+    brokerPrompt !== undefined &&
+    (args.promptId === undefined || args.promptId === brokerPrompt.id) &&
+    (requestedDelivery === "answer" || args.promptId !== undefined || requestedDelivery === "auto");
+  if (targetsBrokerPrompt && brokerPrompt !== undefined) {
+    if (!hasPayloadProperty(args)) {
+      return workflowSendResult(stageRunId, stage.stageId, "answer", "noop", "Send requires text, response, or message.");
+    }
+    const ok = stageUiBroker.answerStagePrompt(stageRunId, stage.stageId, brokerAnswerFromArgs(args), {
+      answerSource: "workflow_tool",
+    });
+    return workflowSendResult(
+      stageRunId,
+      stage.stageId,
+      "answer",
+      ok ? "ok" : "noop",
+      ok ? `Answered input request ${brokerPrompt.id}.` : `No matching pending input request ${brokerPrompt.id}.`,
+    );
+  }
+  const customPrompt = snapshot?.status === "awaiting_input" && snapshot.promptFootprint?.kind === "custom"
+    ? snapshot.promptFootprint
+    : undefined;
+  const targetsCustomPrompt =
+    customPrompt !== undefined &&
+    (args.promptId === undefined || args.promptId === customPrompt.id) &&
+    (requestedDelivery === "answer" || args.promptId !== undefined || requestedDelivery === "auto");
+  if (targetsCustomPrompt && customPrompt !== undefined) {
+    return workflowSendResult(
+      stageRunId,
+      stage.stageId,
+      "answer",
+      "noop",
+      `Custom UI prompt ${customPrompt.id} requires the interactive workflow graph; arbitrary ctx.ui.custom<T> results cannot be answered through workflow send.`,
+    );
+  }
+  const targetsPrompt =
+    requestedDelivery === "answer" ||
+    args.promptId !== undefined ||
+    (requestedDelivery === "auto" && snapshot?.pendingPrompt !== undefined);
+  if (targetsPrompt) {
+    const promptId = args.promptId ?? snapshot?.pendingPrompt?.id;
+    if (promptId === undefined) {
+      return workflowSendResult(stageRunId, stage.stageId, "answer", "noop", "No pending prompt to answer.");
+    }
+    if (!hasPayloadProperty(args)) {
+      return workflowSendResult(stageRunId, stage.stageId, "answer", "noop", "Send requires text, response, or message.");
+    }
+    if (stageUiBroker.wasStagePromptResolved(stageRunId, stage.stageId, promptId)) {
+      return workflowSendResult(stageRunId, stage.stageId, "answer", "ok", `Input request ${promptId} was already answered.`);
+    }
+    const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, promptPayloadFromArgs(args), {
+      answerSource: "workflow_tool",
+    });
+    return workflowSendResult(
+      stageRunId,
+      stage.stageId,
+      "answer",
+      ok ? "ok" : "noop",
+      ok ? `Answered prompt ${promptId}.` : `No matching pending prompt ${promptId}.`,
+    );
+  }
+  const text = textPayloadFromArgs(args);
+  if (text === undefined) {
+    return workflowSendResult(stageRunId, stage.stageId, requestedDelivery, "noop", "Send requires text, response, or message.");
+  }
+  const handle = stageControlRegistry.get(stageRunId, stage.stageId);
+  if (handle === undefined) {
+    return workflowSendResult(stageRunId, stage.stageId, requestedDelivery, "noop", "No live handle for stage.");
+  }
+  if (requestedDelivery === "resume" || (requestedDelivery === "auto" && handle.status === "paused")) {
+    await handle.resume(text);
+    return workflowSendResult(stageRunId, stage.stageId, "resume", "ok", "Resumed stage with message.");
+  }
+  if (requestedDelivery === "steer" || (requestedDelivery === "auto" && handle.isStreaming)) {
+    await handle.steer(text);
+    return workflowSendResult(stageRunId, stage.stageId, "steer", "ok", "Steered live stage.");
+  }
+  if (requestedDelivery === "prompt") {
+    await handle.prompt(text);
+    return workflowSendResult(stageRunId, stage.stageId, "prompt", "ok", "Prompt sent to stage.");
+  }
+  await handle.followUp(text);
+  return workflowSendResult(stageRunId, stage.stageId, "followUp", "ok", "Follow-up queued for stage.");
+}

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

@@ -0,0 +1,102 @@
+import { inspectRun } from "../runs/background/status.js";
+import type { WorkflowExecutionPolicy, WorkflowPersistencePort } from "../shared/types.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { PiExecuteContext, WorkflowToolArgs } from "./public-types.js";
+import { workflowPolicyFromContext } from "./workflow-policy.js";
+import { workflowGetResult } from "./workflow-tool-content.js";
+import {
+  directModeCount,
+  hasDirectExecutionMode,
+  hasNamedExecutionMode,
+  withForkParentSession,
+  workflowRunResultFromDetails,
+} from "./workflow-tool-helpers.js";
+import {
+  workflowInterruptAction,
+  workflowKillAction,
+  workflowPauseAction,
+  workflowReloadAction,
+  workflowResumeAction,
+} from "./workflow-tool-control.js";
+import {
+  workflowStageResult,
+  workflowStagesResult,
+  workflowTranscriptResult,
+} from "./workflow-tool-inspection.js";
+import { workflowSendAction } from "./workflow-tool-send.js";
+import { isWorkflowStageToolContext, topLevelExpandedSnapshots } from "./workflow-targets.js";
+
+export function makeExecuteWorkflowTool(
+  runtime: ExtensionRuntime | ((ctx: PiExecuteContext) => ExtensionRuntime),
+  getPersistence: () => WorkflowPersistencePort | undefined,
+  reloadWorkflowResources: () => Promise<void> | void,
+) {
+  return async function executeWorkflowTool(
+    args: WorkflowToolArgs,
+    ctx: PiExecuteContext,
+  ): Promise<WorkflowToolResult> {
+    const action = args.action ?? "run";
+    const runId = args.runId ?? "";
+    if (isWorkflowStageToolContext(ctx)) {
+      return {
+        action: "run",
+        runId,
+        status: "failed",
+        error: "workflows cannot invoke workflows from workflow stages",
+        stages: [],
+      };
+    }
+    const activeRuntime = typeof runtime === "function" ? runtime(ctx) : runtime;
+    const policy: WorkflowExecutionPolicy = workflowPolicyFromContext(ctx);
+
+    switch (action) {
+      case "get":
+        return workflowGetResult(activeRuntime, args);
+      case "list":
+      case "inputs":
+      case "run":
+        if (action === "run" && hasDirectExecutionMode(args)) {
+          const normalModeCount = directModeCount(args) + (hasNamedExecutionMode(args) ? 1 : 0);
+          if (normalModeCount !== 1) {
+            throw new Error("Workflow extension: specify exactly one normal execution mode: workflow, task, tasks, or chain");
+          }
+          const details = await activeRuntime.runDirect(withForkParentSession(args, ctx), { policy });
+          return workflowRunResultFromDetails(details);
+        }
+        return activeRuntime.dispatch(args, { policy });
+      case "status": {
+        const target = args.runId;
+        if (target !== undefined) {
+          const result = inspectRun(target);
+          return result.ok
+            ? { action: "statusDetail", runId: result.runId, detail: result.detail }
+            : { action: "statusDetail", runId: target, error: `run not found: ${target}` };
+        }
+        return { action: "status", snapshots: topLevelExpandedSnapshots() };
+      }
+      case "stages":
+        return workflowStagesResult(args);
+      case "stage":
+        return workflowStageResult(args);
+      case "transcript":
+        return workflowTranscriptResult(args);
+      case "send":
+        return workflowSendAction(args);
+      case "pause":
+        return workflowPauseAction(args);
+      case "reload":
+        return workflowReloadAction(args, { reloadWorkflowResources });
+      case "kill":
+        return workflowKillAction(args, { getPersistence });
+      case "interrupt":
+        return workflowInterruptAction(args);
+      case "resume":
+        return workflowResumeAction(args, { runtime: activeRuntime, policy });
+      default: {
+        const _exhaustive: never = action;
+        throw new Error(`Workflow extension: unknown action "${_exhaustive}"`);
+      }
+    }
+  };
+}