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

package/dist/builtin/workflows/src/runs/foreground/stage-runner-output.ts

@@ -0,0 +1,146 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import type { PromptOptions } from "@bastani/atomic";
+import type {
+  StageOutputOptions,
+  StagePromptOptions,
+  WorkflowMaxOutput,
+} from "../../shared/types.js";
+
+const DEFAULT_MAX_OUTPUT_BYTES = 200 * 1024;
+const DEFAULT_MAX_OUTPUT_LINES = 5000;
+
+function normalizeMaxOutput(maxOutput: WorkflowMaxOutput | undefined): Required<WorkflowMaxOutput> {
+  return {
+    bytes: maxOutput?.bytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+    lines: maxOutput?.lines ?? DEFAULT_MAX_OUTPUT_LINES,
+  };
+}
+
+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 };
+}
+
+function truncateOutput(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]`;
+}
+
+function countLines(text: string): number {
+  if (!text) return 0;
+  const newlineMatches = text.match(/\r\n|\r|\n/g);
+  return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+function savedOutputReference(outputPath: string, fullOutput: string): string {
+  const absolutePath = resolve(outputPath);
+  const bytes = Buffer.byteLength(fullOutput, "utf8");
+  const lines = countLines(fullOutput);
+  return `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`;
+}
+
+function resolveOutputPath(
+  output: string | false | undefined,
+  runtimeCwd: string,
+  requestedCwd: string | undefined,
+): string | undefined {
+  if (typeof output !== "string" || output.length === 0) return undefined;
+  if (isAbsolute(output)) return output;
+  const baseCwd = requestedCwd === undefined
+    ? runtimeCwd
+    : isAbsolute(requestedCwd)
+      ? requestedCwd
+      : resolve(runtimeCwd, requestedCwd);
+  return resolve(baseCwd, output);
+}
+
+export function splitPromptOptions(options: StagePromptOptions | undefined): {
+  sdkOptions: PromptOptions | undefined;
+  outputOptions: StageOutputOptions;
+} {
+  if (!options) return { sdkOptions: undefined, outputOptions: {} };
+  const sdkOptions: PromptOptions = {};
+  if (options.expandPromptTemplates !== undefined) sdkOptions.expandPromptTemplates = options.expandPromptTemplates;
+  if (options.images !== undefined) sdkOptions.images = options.images;
+  if (options.streamingBehavior !== undefined) sdkOptions.streamingBehavior = options.streamingBehavior;
+  if (options.source !== undefined) sdkOptions.source = options.source;
+  if (options.preflightResult !== undefined) sdkOptions.preflightResult = options.preflightResult;
+
+  const outputOptions: StageOutputOptions = {
+    ...(options.output !== undefined ? { output: options.output } : {}),
+    ...(options.outputMode !== undefined ? { outputMode: options.outputMode } : {}),
+    ...(options.context !== undefined ? { context: options.context } : {}),
+    ...(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 {
+    sdkOptions: Object.keys(sdkOptions).length === 0 ? undefined : sdkOptions,
+    outputOptions,
+  };
+}
+
+export function validatePromptOutputOptions(outputOptions: StageOutputOptions): void {
+  if (outputOptions.outputMode === "file-only" && (typeof outputOptions.output !== "string" || outputOptions.output.length === 0)) {
+    throw new Error(
+      "atomic-workflows: prompt sets outputMode: \"file-only\" but does not configure an output file. Set output to a path or use outputMode: \"inline\".",
+    );
+  }
+}
+
+export async function finalizePromptOutput(
+  fullOutput: string,
+  outputOptions: StageOutputOptions,
+  runtimeCwd: string,
+): Promise<string> {
+  const outputPath = resolveOutputPath(outputOptions.output, runtimeCwd, outputOptions.cwd);
+  validatePromptOutputOptions(outputOptions);
+  const displayOutput = truncateOutput(fullOutput, outputOptions.maxOutput);
+  if (outputPath === undefined) return displayOutput;
+
+  try {
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, fullOutput, "utf8");
+  } catch (err) {
+    return `${displayOutput}\n\nOutput file error: ${outputPath}\n${err instanceof Error ? err.message : String(err)}`;
+  }
+
+  const reference = savedOutputReference(outputPath, fullOutput);
+  return outputOptions.outputMode === "file-only"
+    ? reference
+    : `${displayOutput}\n\n${reference}`;
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-session.ts

@@ -0,0 +1,55 @@
+import type { AgentSession } from "@bastani/atomic";
+import type {
+  StageSessionCreateResult,
+  StageSessionRuntime,
+} from "./stage-runner-types.js";
+
+type StageSessionExtensionRunner = {
+  hasHandlers(eventType: string): boolean;
+  emit(event: { readonly type: "session_shutdown"; readonly reason: "quit" }): Promise<unknown>;
+};
+
+function stageSessionExtensionRunner(
+  current: StageSessionRuntime,
+): StageSessionExtensionRunner | undefined {
+  const runner = (current as StageSessionRuntime & { extensionRunner?: StageSessionExtensionRunner })
+    .extensionRunner;
+  if (runner && typeof runner.hasHandlers === "function" && typeof runner.emit === "function") {
+    return runner;
+  }
+  return undefined;
+}
+
+export async function disposeStageSession(current: StageSessionRuntime | undefined): Promise<void> {
+  if (!current) return;
+  const runner = stageSessionExtensionRunner(current);
+  if (runner?.hasHandlers("session_shutdown")) {
+    try {
+      await runner.emit({ type: "session_shutdown", reason: "quit" });
+    } catch (error) {
+      console.error("atomic-workflows: stage session_shutdown handler failed", error);
+    }
+  }
+  await current.dispose();
+}
+
+export function asAgentSession(activeSession: StageSessionRuntime | undefined): AgentSession | undefined {
+  if (!activeSession) return undefined;
+  const candidate = activeSession as StageSessionRuntime & Partial<Pick<AgentSession, "state" | "sessionManager" | "modelRegistry" | "getContextUsage">>;
+  if (
+    candidate.state !== undefined &&
+    candidate.sessionManager !== undefined &&
+    candidate.modelRegistry !== undefined &&
+    typeof candidate.getContextUsage === "function"
+  ) {
+    return candidate as AgentSession;
+  }
+  return undefined;
+}
+
+export function normalizeSessionCreateResult(
+  created: StageSessionRuntime | StageSessionCreateResult,
+): StageSessionCreateResult {
+  if ("session" in created) return created;
+  return { session: created };
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-structured-output.ts

@@ -0,0 +1,82 @@
+import {
+  createStructuredOutputTool,
+  type StructuredOutputCapture,
+} from "@bastani/atomic";
+import type { StageOptions } from "../../shared/types.js";
+import type { Static, TSchema } from "typebox";
+
+export const STRUCTURED_OUTPUT_MAX_CORRECTIVE_PROMPTS = 3;
+export const STRUCTURED_OUTPUT_MISSING_ERROR = "atomic-workflows: stage configured with schema must finish by calling structured_output.";
+
+const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
+
+type ToolResultContentBlock = {
+  readonly type?: unknown;
+  readonly text?: unknown;
+};
+
+function toolResultText(content: unknown): string | undefined {
+  if (!Array.isArray(content)) return undefined;
+  const text = content
+    .map((block: ToolResultContentBlock) => block.type === "text" && typeof block.text === "string" ? block.text : "")
+    .join("\n")
+    .trim();
+  return text.length > 0 ? text : undefined;
+}
+
+export function structuredOutputToolErrorFromEvent(event: unknown): string | undefined {
+  if (event === null || typeof event !== "object") return undefined;
+  const record = event as Record<string, unknown>;
+  if (record["type"] !== "tool_execution_end") return undefined;
+  if (record["toolName"] !== STRUCTURED_OUTPUT_TOOL_NAME) return undefined;
+  const result = record["result"];
+  const resultRecord = result !== null && typeof result === "object" ? result as Record<string, unknown> : undefined;
+  const isError = record["isError"] === true || resultRecord?.["isError"] === true;
+  if (!isError) return undefined;
+  return toolResultText(resultRecord?.["content"]) ?? "structured_output tool call failed schema validation.";
+}
+
+export function formatStructuredOutputCorrectionPrompt(error: string, attempt: number): string {
+  return [
+    "The previous response failed this stage's structured-output contract.",
+    "",
+    `Corrective attempt ${attempt}/${STRUCTURED_OUTPUT_MAX_CORRECTIVE_PROMPTS}.`,
+    "",
+    "Error:",
+    error,
+    "",
+    "You must finish by calling the `structured_output` tool exactly once with arguments matching the registered schema.",
+    "Do not answer with plain JSON text, Markdown, or prose. If you attempted `structured_output` and validation failed, correct the tool arguments and call `structured_output` again.",
+  ].join("\n");
+}
+
+export function stringifyStructuredOutputValue(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch (error) {
+    throw new Error(`atomic-workflows: structured_output returned a non-serializable value: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function stageOptionsWithStructuredOutput(
+  options: StageOptions | undefined,
+  capture: StructuredOutputCapture<unknown> | undefined,
+): StageOptions | undefined {
+  if (!options?.schema || !capture) return options;
+  const tools = options.tools === undefined
+    ? options.noTools === "all" ? [STRUCTURED_OUTPUT_TOOL_NAME] : undefined
+    : Array.from(new Set([...options.tools, STRUCTURED_OUTPUT_TOOL_NAME]));
+  const excludedTools = options.excludedTools?.filter((toolName) => toolName !== STRUCTURED_OUTPUT_TOOL_NAME);
+  return {
+    ...options,
+    ...(tools !== undefined ? { tools } : {}),
+    ...(excludedTools !== undefined ? { excludedTools } : {}),
+    customTools: [
+      ...(options.customTools ?? []),
+      createStructuredOutputTool({
+        schema: options.schema as TSchema,
+        capture: capture as StructuredOutputCapture<Static<TSchema>>,
+      }),
+    ],
+  };
+}

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

@@ -0,0 +1,141 @@
+import type {
+  AgentSession,
+  CreateAgentSessionOptions,
+  PromptOptions,
+} from "@bastani/atomic";
+import type {
+  CompleteStageOpts,
+  StageContext,
+  StageExecutionMeta,
+  StageOptions,
+  WorkflowExecutionMode,
+  WorkflowModelAttempt,
+  WorkflowModelCatalogPort,
+} from "../../shared/types.js";
+
+export type StageSessionEvent = Parameters<AgentSession["subscribe"]>[0] extends (event: infer T) => void ? T : never;
+
+export type WorkflowFastModeSettings = {
+  readonly chat: boolean;
+  readonly workflow: boolean;
+};
+
+export type WorkflowFastModeSettingsManager = {
+  getCodexFastModeSettings(): WorkflowFastModeSettings;
+};
+
+export interface StageSessionRuntime {
+  prompt(text: string, options?: PromptOptions): Promise<string | void>;
+  steer(text: string): Promise<void>;
+  followUp(text: string): Promise<void>;
+  subscribe(listener: (event: StageSessionEvent) => void): () => void;
+  readonly sessionFile: string | undefined;
+  readonly sessionId: string;
+  setModel(model: Parameters<AgentSession["setModel"]>[0]): Promise<void>;
+  setThinkingLevel(level: Parameters<AgentSession["setThinkingLevel"]>[0]): void;
+  cycleModel(): ReturnType<AgentSession["cycleModel"]>;
+  cycleThinkingLevel(): ReturnType<AgentSession["cycleThinkingLevel"]>;
+  readonly agent: AgentSession["agent"];
+  readonly model: AgentSession["model"];
+  readonly thinkingLevel: AgentSession["thinkingLevel"];
+  readonly messages: AgentSession["messages"];
+  readonly isStreaming: AgentSession["isStreaming"];
+  /** Number of SDK-level queued steering/follow-up messages, when supported. */
+  readonly pendingMessageCount?: number;
+  /** Settings manager supplied by the Atomic SDK when the adapter did not pre-create one. */
+  readonly settingsManager?: WorkflowFastModeSettingsManager;
+  navigateTree: AgentSession["navigateTree"];
+  compact: AgentSession["compact"];
+  abortCompaction(): void;
+  abort(): Promise<void>;
+  dispose(): void | Promise<void>;
+  getLastAssistantText?: () => string | undefined;
+}
+
+export type StageSessionCreateOptions = CreateAgentSessionOptions & Pick<StageOptions, "mcp" | "fallbackModels" | "fallbackThinkingLevels">;
+
+export interface StageSessionCreateResult {
+  readonly session: StageSessionRuntime;
+  readonly settingsManager?: WorkflowFastModeSettingsManager;
+}
+
+export interface AgentSessionAdapter {
+  create(options: StageSessionCreateOptions, meta?: StageExecutionMeta): Promise<StageSessionRuntime | StageSessionCreateResult>;
+}
+
+export interface StageModelFallbackMeta {
+  readonly model?: string;
+  readonly fastMode?: boolean;
+  readonly attemptedModels?: readonly string[];
+  readonly modelAttempts?: readonly WorkflowModelAttempt[];
+  readonly warnings?: readonly string[];
+}
+
+export interface PromptAdapter {
+  prompt(text: string, meta?: StageExecutionMeta): Promise<string>;
+}
+
+export interface CompleteAdapter {
+  complete(text: string, opts?: CompleteStageOpts, meta?: StageExecutionMeta): Promise<string>;
+}
+
+export interface StageAdapters {
+  agentSession?: AgentSessionAdapter;
+  prompt?: PromptAdapter;
+  complete?: CompleteAdapter;
+}
+
+export interface StageRunnerOpts {
+  stageId: string;
+  stageName: string;
+  adapters: StageAdapters;
+  /** Options passed to ctx.stage(name, options?). Forwarded to createAgentSession except mcp. */
+  stageOptions?: StageOptions;
+  /** Run ID of the containing workflow execution — forwarded to session adapter metadata. */
+  runId: string;
+  /** AbortSignal from the executor's own AbortController — forwarded to session adapter metadata. */
+  signal?: AbortSignal;
+  /** Optional model catalog used for fallback validation/resolution. */
+  models?: WorkflowModelCatalogPort;
+  /** Runtime execution mode forwarded to stage session adapters. */
+  executionMode?: WorkflowExecutionMode;
+  /** Host-resolved non-default session directory inherited by stages without explicit sessionDir. */
+  defaultSessionDir?: string;
+  /** Internal: notifies the executor when an in-flight fallback changes model/fast metadata. */
+  onModelFallbackMetaChange?: (meta: StageModelFallbackMeta) => void;
+}
+
+export interface InternalStageContext extends StageContext {
+  /** Internal cleanup hook; intentionally omitted from the public StageContext type. */
+  __dispose(): Promise<void>;
+  /** Internal result snapshot hook for the workflow store/TUI. */
+  __getLastAssistantText(): string | undefined;
+  getLastAssistantText(): string | undefined;
+  /**
+   * Internal: eagerly create the underlying SDK AgentSession without sending a
+   * prompt. Used by the live stage-control registry when a user attaches to a
+   * stage and types their first message before the workflow body's natural
+   * first `prompt()` lands.
+   */
+  __ensureSession(): Promise<void>;
+  /** Internal: reopen an archived stage transcript before post-terminal follow-up. */
+  __ensureSessionFromFile(sessionFile: string): Promise<void>;
+  /** Internal: snapshot of currently-known SDK session metadata. */
+  __sessionMeta(): { sessionId: string | undefined; sessionFile: string | undefined };
+  /** Internal: live coding-agent session when the adapter returned one. */
+  __agentSession(): AgentSession | undefined;
+  /** Internal: SDK queued steering/follow-up message count, when available. */
+  __pendingMessageCount(): number;
+  /** Internal: selected/effective model and fallback attempt metadata. */
+  __modelFallbackMeta(): StageModelFallbackMeta;
+  /** Internal: register a controlled-pause request. */
+  __requestPause(): Promise<void>;
+  /** Internal: complete a pending controlled pause. */
+  __resume(message?: string): Promise<void>;
+  /** Internal: true while a controlled pause is in flight. */
+  __isPaused(): boolean;
+  /** Internal: true once a schema-backed prompt captured its final structured output. */
+  __structuredOutputFinalized(): boolean;
+}
+
+export type AgentSessionConsumer = "prompt" | "complete";