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

package/dist/builtin/workflows/src/runs/foreground/executor-task-prompts.ts

@@ -0,0 +1,293 @@
+import { isAbsolute, resolve } from "node:path";
+import type {
+  StageOptions,
+  StagePromptOptions,
+  WorkflowTaskContextInput,
+  WorkflowTaskOptions,
+  WorkflowTaskStep,
+  WorkflowChainOptions,
+  WorkflowParallelOptions,
+  WorkflowDirectOptions,
+  WorkflowDirectTaskItem,
+  WorkflowMaxOutput,
+} from "../../shared/types.js";
+
+export function normalizeTaskContexts(
+  previous: WorkflowTaskOptions["previous"],
+): Array<{ readonly name?: string; readonly text: string }> {
+  if (previous === undefined) return [];
+  const items = Array.isArray(previous) ? previous : [previous];
+  return items
+    .map((item: WorkflowTaskContextInput) => {
+      if (typeof item === "string") return { text: item };
+      return item.name ? { name: item.name, text: item.text } : { text: item.text };
+    })
+    .filter((item) => item.text.trim().length > 0);
+}
+
+export function renderTaskContext(contexts: readonly { readonly name?: string; readonly text: string }[]): string {
+  if (contexts.length === 0) return "";
+  if (contexts.length === 1 && contexts[0]?.name === undefined) return contexts[0]!.text;
+  return contexts
+    .map((context, index) => {
+      const label = context.name ?? `context-${index + 1}`;
+      return `--- ${label} ---\n${context.text}`;
+    })
+    .join("\n\n");
+}
+
+export function applyTaskContext(prompt: string, previous: WorkflowTaskOptions["previous"]): string {
+  const contexts = normalizeTaskContexts(previous);
+  if (contexts.length === 0) return prompt;
+
+  const lastPrevious = contexts[contexts.length - 1]?.text ?? "";
+  const rendered = renderTaskContext(contexts);
+  let next = prompt.replace(/\{previous\}/g, lastPrevious);
+
+  if (next !== prompt) return next;
+  next += `\n\n---\nContext:\n${rendered}`;
+  return next;
+}
+
+export function taskPrompt(options: WorkflowTaskOptions): string {
+  const prompt = options.prompt ?? options.task;
+  if (prompt === undefined) {
+    throw new Error("atomic-workflows: ctx.task requires options.prompt or options.task");
+  }
+  return prompt;
+}
+
+export function taskPrevious(options: WorkflowTaskOptions): WorkflowTaskOptions["previous"] {
+  return options.previous;
+}
+
+export type WorkflowTaskExecutionOptions = WorkflowTaskOptions & { chainDir?: string };
+
+export function resolveWorkflowPath(filePath: string, baseDir: string | undefined): string {
+  if (isAbsolute(filePath)) return filePath;
+  return resolve(baseDir ?? process.cwd(), filePath);
+}
+
+export function taskBaseDir(options: Pick<WorkflowTaskExecutionOptions, "chainDir" | "cwd">): string | undefined {
+  if (typeof options.chainDir === "string" && options.chainDir.length > 0) {
+    return resolveWorkflowPath(options.chainDir, process.cwd());
+  }
+  if (typeof options.cwd === "string" && options.cwd.length > 0) {
+    return resolveWorkflowPath(options.cwd, process.cwd());
+  }
+  return undefined;
+}
+
+export function taskReadInstruction(options: WorkflowTaskExecutionOptions): string {
+  if (options.reads === false || options.reads === undefined || options.reads.length === 0) return "";
+  const baseDir = taskBaseDir(options);
+  const files = options.reads.map((file) => resolveWorkflowPath(file, baseDir));
+  return `[Read from: ${files.join(", ")}]\n\n`;
+}
+
+export function taskPromptOptions(options: WorkflowTaskExecutionOptions): StagePromptOptions | undefined {
+  const baseDir = taskBaseDir(options);
+  const promptOptions: StagePromptOptions = {
+    ...(options.output !== undefined ? { output: options.output } : {}),
+    ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {}),
+    ...(baseDir !== undefined ? { cwd: baseDir } : options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    ...(options.maxOutput !== undefined ? { maxOutput: options.maxOutput } : {}),
+    ...(options.artifacts !== undefined ? { artifacts: options.artifacts } : {}),
+    ...(options.sessionDir !== undefined ? { sessionDir: options.sessionDir } : {}),
+  };
+  return Object.keys(promptOptions).length === 0 ? undefined : promptOptions;
+}
+
+export function taskStageOptions(options: WorkflowTaskExecutionOptions): StageOptions {
+  const {
+    prompt: _prompt,
+    task: _task,
+    previous: _previous,
+    chainDir: _chainDir,
+    output: _output,
+    outputMode: _outputMode,
+    reads: _reads,
+    worktree: _worktree,
+    gitWorktreeDir: _gitWorktreeDir,
+    baseBranch: _baseBranch,
+    maxOutput: _maxOutput,
+    artifacts: _artifacts,
+    ...stageOptions
+  } = options;
+  return stageOptions;
+}
+
+export function taskOptionsFromStep(step: WorkflowTaskStep, prompt: string, previous?: WorkflowTaskOptions["previous"]): WorkflowTaskOptions {
+  const {
+    name: _name,
+    prompt: _prompt,
+    task: _task,
+    previous: _previous,
+    ...stepOptions
+  } = step;
+  return previous === undefined
+    ? { ...stepOptions, prompt }
+    : { ...stepOptions, prompt, previous };
+}
+
+export function replaceTaskPlaceholder(prompt: string, task: string): string {
+  return prompt.replace(/\{task\}/g, task);
+}
+
+export function chainStepPrompt(step: WorkflowTaskStep, index: number): string {
+  return step.prompt ?? step.task ?? (index === 0 ? "{task}" : "{previous}");
+}
+
+export function parallelFallbackTask(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): string {
+  if (options?.task !== undefined) return options.task;
+  for (const step of steps) {
+    const task = step.prompt ?? step.task;
+    if (task !== undefined) return task;
+  }
+  return "";
+}
+
+export function directTaskPrompt(item: WorkflowDirectTaskItem): string | undefined {
+  return item.prompt ?? item.task;
+}
+
+export function normalizeMaxOutput(maxOutput: WorkflowMaxOutput | undefined): Required<WorkflowMaxOutput> {
+  return {
+    bytes: maxOutput?.bytes ?? 200 * 1024,
+    lines: maxOutput?.lines ?? 5000,
+  };
+}
+
+function truncateByLines(text: string, maxLines: number): { text: string; truncated: boolean } {
+  if (!Number.isFinite(maxLines) || maxLines <= 0) return { text: "", truncated: text.length > 0 };
+  const lines = text.split(/\r?\n/);
+  if (lines.length <= maxLines) return { text, truncated: false };
+  return {
+    text: lines.slice(0, maxLines).join("\n"),
+    truncated: true,
+  };
+}
+
+function truncateByBytes(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0) return { text: "", truncated: text.length > 0 };
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return { text, truncated: false };
+
+  let low = 0;
+  let high = text.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (Buffer.byteLength(text.slice(0, mid), "utf8") <= maxBytes) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return { text: text.slice(0, low), truncated: true };
+}
+
+export function structuredTaskOutputText(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch (error) {
+    throw new Error(`atomic-workflows: structured task output is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function truncateTaskOutput(text: string, maxOutput: WorkflowMaxOutput | undefined): string {
+  const limits = normalizeMaxOutput(maxOutput);
+  const byLines = truncateByLines(text, limits.lines);
+  const byBytes = truncateByBytes(byLines.text, limits.bytes);
+  if (!byLines.truncated && !byBytes.truncated) return text;
+  return `${byBytes.text}\n\n[workflow output truncated; limits: ${limits.bytes} bytes, ${limits.lines} lines]`;
+}
+
+export function withoutUndefinedProperties<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, field]) => field !== undefined),
+  ) as Partial<T>;
+}
+
+export function sharedTaskDefaultsFromOptions(
+  options: WorkflowChainOptions | WorkflowParallelOptions,
+): Partial<WorkflowTaskExecutionOptions> {
+  const {
+    task: _task,
+    concurrency: _concurrency,
+    failFast: _failFast,
+    ...taskDefaults
+  } = options as WorkflowParallelOptions;
+  return withoutUndefinedProperties(taskDefaults);
+}
+
+export function taskWithSharedDefaults(
+  taskOptions: WorkflowTaskOptions,
+  options: WorkflowChainOptions | WorkflowParallelOptions,
+): WorkflowTaskExecutionOptions {
+  return {
+    ...sharedTaskDefaultsFromOptions(options),
+    ...withoutUndefinedProperties(taskOptions),
+  } as WorkflowTaskExecutionOptions;
+}
+
+export function directTaskWithDefaults(
+  item: WorkflowDirectTaskItem,
+  options: WorkflowDirectOptions,
+): WorkflowDirectTaskItem {
+  const {
+    task: _task,
+    chainName: _chainName,
+    concurrency: _concurrency,
+    failFast: _failFast,
+    chainDir: _chainDir,
+    reads,
+    output,
+    outputMode,
+    worktree,
+    gitWorktreeDir,
+    baseBranch,
+    maxOutput,
+    artifacts,
+    ...stageDefaults
+  } = options;
+
+  const taskWithStageDefaults = {
+    ...withoutUndefinedProperties(stageDefaults),
+    ...withoutUndefinedProperties(item),
+    name: item.name,
+  } as WorkflowDirectTaskItem;
+
+  return {
+    ...taskWithStageDefaults,
+    ...(item.reads === undefined && reads !== undefined ? { reads } : {}),
+    ...(item.output === undefined && output !== undefined ? { output } : {}),
+    ...(item.outputMode === undefined && outputMode !== undefined ? { outputMode } : {}),
+    ...(item.worktree === undefined && worktree !== undefined ? { worktree } : {}),
+    ...(item.gitWorktreeDir === undefined && gitWorktreeDir !== undefined ? { gitWorktreeDir } : {}),
+    ...(item.baseBranch === undefined && baseBranch !== undefined ? { baseBranch } : {}),
+    ...(item.maxOutput === undefined && maxOutput !== undefined ? { maxOutput } : {}),
+    ...(item.artifacts === undefined && artifacts !== undefined ? { artifacts } : {}),
+  };
+}
+
+export function directTaskToStep(
+  item: WorkflowDirectTaskItem,
+  fallbackPrompt?: string,
+  previous?: WorkflowTaskOptions["previous"],
+): WorkflowTaskStep {
+  const {
+    count: _count,
+    output: _output,
+    outputMode: _outputMode,
+    worktree: _worktree,
+    prompt,
+    task,
+    previous: itemPrevious,
+    ...stageOptions
+  } = item;
+  return {
+    ...stageOptions,
+    prompt: prompt ?? task ?? fallbackPrompt,
+    previous: previous ?? itemPrevious,
+  };
+}

package/dist/builtin/workflows/src/runs/foreground/executor-types.ts

@@ -0,0 +1,109 @@
+import type * as AuthoringContract from "../../shared/authoring-contract.js";
+import type {
+  WorkflowExecutionMode,
+  WorkflowInputValues,
+  WorkflowOutputValues,
+  WorkflowRuntimeConfig,
+  WorkflowUIAdapter,
+  WorkflowPersistencePort,
+  WorkflowMcpPort,
+  WorkflowModelCatalogPort,
+} from "../../shared/types.js";
+import type { RunStatus, RunSnapshot, StageSnapshot, WorkflowOverlayAdapter } from "../../shared/store-types.js";
+import type { Store } from "../../shared/store.js";
+import type { WorkflowRegistry } from "../../workflows/registry.js";
+import type { CancellationRegistry } from "../background/cancellation-registry.js";
+import type { StageAdapters } from "./stage-runner.js";
+import type { StageControlRegistry } from "./stage-control-registry.js";
+
+export interface ResolvedInputs extends WorkflowInputValues {}
+
+export interface RunContinuationOpts {
+  readonly source: RunSnapshot;
+  readonly resumeFromStageId: string;
+}
+
+export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "store" | "cancellation" | "overlay" | "registry" | "stageControlRegistry" | "continuation" | "onRunStart" | "onStageStart" | "onStageEnd" | "onRunEnd" | "ui"> {
+  adapters?: StageAdapters;
+  /** Invocation working directory exposed to workflow definitions as ctx.cwd. */
+  cwd?: string;
+  /** HIL adapter injected by the pi runtime or test harness. */
+  ui?: WorkflowUIAdapter;
+  /** Runtime execution mode. Controls child session policy metadata. */
+  executionMode?: WorkflowExecutionMode;
+  /** Host-resolved non-default session directory inherited by stages without explicit sessionDir. */
+  defaultSessionDir?: string;
+  /** Internal detached-run mode: surface ctx.ui.* as node-local workflow prompt stages. */
+  usePromptNodesForUi?: boolean;
+  /** Readiness-gate confirmation seam (#1099). */
+  confirmStageReadiness?: (request: {
+    readonly runId: string;
+    readonly stageId: string;
+    readonly stageName: string;
+    readonly signal: AbortSignal;
+  }) => Promise<boolean>;
+  /** Store override (for testing; defaults to singleton store) */
+  store?: Store;
+  /** Persistence port for writing session entries (run.start, stage.start, etc.). */
+  persistence?: WorkflowPersistencePort;
+  /** MCP scope-gating port; forwards per-stage allow/deny to the MCP adapter. */
+  mcp?: WorkflowMcpPort;
+  /** Cancellation registry; the executor registers an ActiveRunController per run. */
+  cancellation?: CancellationRegistry;
+  /** Overlay adapter for displaying run progress in the UI layer. */
+  overlay?: WorkflowOverlayAdapter;
+  /** AbortSignal that requests cancellation from the caller side. */
+  signal?: AbortSignal;
+  /** Yield to the next event-loop turn before invoking user workflow code. */
+  deferWorkflowStart?: boolean;
+  /** Resolved runtime configuration. */
+  config?: WorkflowRuntimeConfig;
+  /** Optional model catalog used for fallback validation/resolution. */
+  models?: WorkflowModelCatalogPort;
+  /** Registry metadata forwarded to workflow runs launched from discovery/tooling. */
+  registry?: WorkflowRegistry;
+  /** Current nesting depth of this workflow run. */
+  depth?: number;
+  /** Live stage-control registry. */
+  stageControlRegistry?: StageControlRegistry;
+  /** Pre-allocated runId. */
+  runId?: string;
+  /** Replay completed stages from a failed source run, then resume at this stage. */
+  continuation?: RunContinuationOpts;
+  /** Internal parent linkage for nested ctx.workflow(...) runs. */
+  parentRun?: {
+    readonly runId: string;
+    readonly stageId: string;
+    readonly rootRunId: string;
+  };
+  onRunStart?: (snapshot: RunSnapshot) => void;
+  onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
+  onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
+  onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
+}
+
+export interface RunResult {
+  readonly runId: string;
+  readonly status: RunStatus;
+  readonly result?: WorkflowOutputValues;
+  readonly error?: string;
+  /** True when the run reached its terminal status through ctx.exit(). */
+  readonly exited?: boolean;
+  readonly exitReason?: string;
+  readonly stages: StageSnapshot[];
+}
+
+export interface ParallelFailFastStage {
+  readonly skip: () => void;
+}
+
+export interface ParallelFailFastScope {
+  failed: boolean;
+  firstFailure?: unknown;
+  readonly activeStages: Map<string, ParallelFailFastStage>;
+  readonly parentIds?: readonly string[];
+}
+
+export interface WorkflowExitCleanup {
+  skipForWorkflowExit(reason?: string): void | Promise<void>;
+}