@bastani/atomic 0.8.21 → 0.8.22-0

package/dist/builtin/workflows/src/shared/types.ts

@@ -11,12 +11,15 @@ import type {
   ModelCycleResult,
   PromptOptions,
 } from "@bastani/atomic";
+import type { TSchema } from "typebox";
+
+export type { TSchema };
 
 export type { AgentSessionEvent, CompactionResult, ModelCycleResult, PromptOptions };
 
 export type WorkflowModelValue = NonNullable<CreateAgentSessionOptions["model"]> | string;
 
-export interface WorkflowModelUsage {
+export interface WorkflowModelUsage extends WorkflowSerializableObject {
   readonly input?: number;
   readonly output?: number;
   readonly cacheRead?: number;
@@ -25,7 +28,7 @@ export interface WorkflowModelUsage {
   readonly turns?: number;
 }
 
-export interface WorkflowModelAttempt {
+export interface WorkflowModelAttempt extends WorkflowSerializableObject {
   readonly model: string;
   readonly success: boolean;
   readonly error?: string;
@@ -54,45 +57,93 @@ export interface WorkflowModelCatalogPort {
 }
 
 // ---------------------------------------------------------------------------
-// Workflow input schema
+// Workflow serializable values
 // ---------------------------------------------------------------------------
 
-/** Discriminated union of supported input kinds. */
-export type WorkflowInputType = "text" | "string" | "number" | "boolean" | "select";
+export type WorkflowSerializablePrimitive = string | number | boolean | null;
 
-interface BaseInputSchema {
-  description?: string;
-  required?: boolean;
+export interface WorkflowSerializableObject {
+  /**
+   * Optional properties use `undefined` at the type level for ergonomic
+   * intellisense, but workflow runtime validation rejects actual `undefined`
+   * values in returned/input objects. Omit optional keys instead.
+   */
+  readonly [key: string]: WorkflowSerializableValue | undefined;
 }
 
-export interface TextInputSchema extends BaseInputSchema {
-  type: "text" | "string";
-  default?: string;
-}
+export type WorkflowSerializableValue =
+  | WorkflowSerializablePrimitive
+  | readonly WorkflowSerializableValue[]
+  | WorkflowSerializableObject;
 
-export interface NumberInputSchema extends BaseInputSchema {
-  type: "number";
-  default?: number;
-}
+export type WorkflowInputValues = WorkflowSerializableObject;
+export type WorkflowOutputValues = WorkflowSerializableObject;
+export type WorkflowRunOutput = WorkflowOutputValues;
+
+// ---------------------------------------------------------------------------
+// Workflow input / output schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Inputs and outputs are declared with TypeBox schemas. Authors use
+ * `.input(key, Type.String({ ... }))` / `.output(key, Type.Object({ ... }))`;
+ * the builder threads the precise `Static<>` types and the runtime validates
+ * via TypeBox `Value`.
+ */
+export type WorkflowInputSchemaMap = Readonly<Record<string, TSchema>>;
+export type WorkflowOutputSchemaMap = Readonly<Record<string, TSchema>>;
 
-export interface BooleanInputSchema extends BaseInputSchema {
-  type: "boolean";
-  default?: boolean;
+/** A single declared input schema is just a TypeBox schema. */
+export type WorkflowInputSchema = TSchema;
+/** A single declared output schema is just a TypeBox schema. */
+export type WorkflowOutputSchema = TSchema;
+
+// ---------------------------------------------------------------------------
+// Workflow execution policy
+// ---------------------------------------------------------------------------
+
+export type WorkflowExecutionMode = "interactive" | "non_interactive";
+
+export interface WorkflowExecutionPolicy {
+  readonly mode: WorkflowExecutionMode;
+  readonly allowHumanInput: boolean;
+  readonly awaitTerminalRun: boolean;
+  readonly allowInputPicker: boolean;
 }
 
-export interface SelectInputSchema extends BaseInputSchema {
-  type: "select";
-  /** Non-empty array of valid string choices. */
-  choices: readonly string[];
-  default?: string;
+export const INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy = Object.freeze({
+  mode: "interactive",
+  allowHumanInput: true,
+  awaitTerminalRun: false,
+  allowInputPicker: true,
+});
+
+export const NON_INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy = Object.freeze({
+  mode: "non_interactive",
+  allowHumanInput: false,
+  awaitTerminalRun: true,
+  allowInputPicker: false,
+});
+
+// ---------------------------------------------------------------------------
+// Workflow child composition and outputs
+// ---------------------------------------------------------------------------
+
+export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {
+  /** Inputs forwarded to the child workflow, typed against its input contract. */
+  readonly inputs?: TInputs;
+  /** Parent boundary stage display name. Defaults to workflow:<workflow-name>. */
+  readonly stageName?: string;
 }
 
-/** Union of all concrete input schema shapes. */
-export type WorkflowInputSchema =
-  | TextInputSchema
-  | NumberInputSchema
-  | BooleanInputSchema
-  | SelectInputSchema;
+export interface WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues>
+  extends WorkflowSerializableObject {
+  readonly workflow: string;
+  readonly runId: string;
+  readonly status: "completed";
+  /** Child outputs, typed from the child workflow's declared `.output(...)` contract. */
+  readonly outputs: TOutputs;
+}
 
 // ---------------------------------------------------------------------------
 // HIL (human-in-the-loop) primitives available inside run functions
@@ -186,6 +237,8 @@ export interface StageExecutionMeta {
   stageOptions?: StageOptions;
   /** AbortSignal propagated from the executor's own AbortController. */
   signal?: AbortSignal;
+  /** Runtime execution mode for policy-aware child sessions. */
+  executionMode?: WorkflowExecutionMode;
 }
 
 export interface CompleteStageOpts extends WorkflowModelFallbackFields {
@@ -227,7 +280,7 @@ export interface WorkflowPersistencePort {
  * `{previous}` handoffs as a typed SDK primitive instead of requiring authors
  * to manually concatenate prior output into every prompt.
  */
-export interface WorkflowTaskContext {
+export interface WorkflowTaskContext extends WorkflowSerializableObject {
   /** Optional display label used when rendering the context block. */
   readonly name?: string;
   /** Textual context made available to the next task. */
@@ -243,6 +296,7 @@ export interface WorkflowTaskResult extends WorkflowTaskContext {
   readonly sessionFile?: string;
   readonly artifacts?: WorkflowArtifact[];
   readonly model?: string;
+  readonly fastMode?: boolean;
   readonly attemptedModels?: readonly string[];
   readonly modelAttempts?: readonly WorkflowModelAttempt[];
   readonly warnings?: readonly string[];
@@ -331,7 +385,7 @@ export interface StageOutputOptions {
 
 export type StagePromptOptions = PromptOptions & StageOutputOptions;
 
-export interface WorkflowArtifact {
+export interface WorkflowArtifact extends WorkflowSerializableObject {
   readonly kind: "output" | "session" | "diff" | "patch";
   readonly path: string;
   readonly taskName?: string;
@@ -390,7 +444,7 @@ export interface WorkflowDetails {
   readonly status: WorkflowDetailsStatus;
   readonly context?: "fresh" | "fork";
   readonly results?: WorkflowTaskResult[];
-  readonly output?: Record<string, unknown>;
+  readonly output?: WorkflowOutputValues;
   readonly progress?: WorkflowProgressSummary;
   readonly artifacts?: WorkflowArtifact[];
   readonly controlEvents?: WorkflowControlEvent[];
@@ -518,7 +572,7 @@ export interface StageContext {
 // Workflow run context (top-level ctx passed to the run function)
 // ---------------------------------------------------------------------------
 
-export interface WorkflowRunContext<TInputs extends Record<string, unknown> = Record<string, unknown>> {
+export interface WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues> {
   /** Typed inputs provided by the caller, validated against the input schema. */
   readonly inputs: TInputs;
   /** Invocation working directory for workflow-owned artifacts. Defaults to the host process cwd when omitted. */
@@ -541,6 +595,11 @@ export interface WorkflowRunContext<TInputs extends Record<string, unknown> = Re
   chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
   /** Run tasks in parallel. Missing step tasks use the first available task as a fallback. */
   parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
+  /** Execute a reusable child workflow by compiled workflow definition. */
+  workflow<TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues>(
+    definition: WorkflowDefinition<TChildInputs, TChildOutputs>,
+    options?: WorkflowRunChildOptions<TChildInputs>,
+  ): Promise<WorkflowChildResult<TChildOutputs>>;
   /** HIL primitives for user interaction during a run. */
   readonly ui: WorkflowUIContext;
 }
@@ -581,9 +640,10 @@ export interface WorkflowRuntimeConfig {
 // Workflow run function
 // ---------------------------------------------------------------------------
 
-export type WorkflowRunFn<TInputs extends Record<string, unknown> = Record<string, unknown>> = (
-  ctx: WorkflowRunContext<TInputs>,
-) => Promise<Record<string, unknown>>;
+export type WorkflowRunFn<
+  TInputs extends WorkflowInputValues = WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+> = (ctx: WorkflowRunContext<TInputs>) => Promise<TOutputs>;
 
 // ---------------------------------------------------------------------------
 // Compiled workflow definition
@@ -598,15 +658,20 @@ export interface WorkflowInputBindings {
   readonly worktree?: WorkflowWorktreeInputBinding;
 }
 
-export interface WorkflowDefinition<TInputs extends Record<string, unknown> = Record<string, unknown>> {
+export interface WorkflowDefinition<
+  TInputs extends WorkflowInputValues = WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+> {
   /** Sentinel consumed by the registry loader to validate the export. */
   readonly __piWorkflow: true;
   readonly name: string;
   /** Normalised name (lowercase, hyphens) used as the registry key. */
   readonly normalizedName: string;
   readonly description: string;
-  readonly inputs: Readonly<Record<string, WorkflowInputSchema>>;
+  readonly inputs: WorkflowInputSchemaMap;
+  /** Optional output contract used by parent workflows when selecting child outputs. */
+  readonly outputs?: WorkflowOutputSchemaMap;
   /** Optional input-to-runtime defaults declared by the workflow builder. */
   readonly inputBindings?: WorkflowInputBindings;
-  readonly run: WorkflowRunFn<TInputs>;
+  readonly run: WorkflowRunFn<TInputs, TOutputs>;
 }

package/dist/builtin/workflows/src/tui/chat-surface-message.ts

@@ -28,6 +28,7 @@
 import type { ExtensionAPI } from "../extension/index.js";
 import type { RunDetail } from "../runs/background/status.js";
 import type { RunSnapshot, RunStatus } from "../shared/store-types.js";
+import type { WorkflowInputValues } from "../shared/types.js";
 import type { GraphTheme } from "./graph-theme.js";
 import type { WorkflowListEntry } from "./workflow-list.js";
 import { renderDispatchConfirm } from "./dispatch-confirm.js";
@@ -54,7 +55,7 @@ export interface DispatchPayload {
   kind: "dispatch";
   workflowName: string;
   runId: string;
-  inputs: Readonly<Record<string, unknown>>;
+  inputs: Readonly<WorkflowInputValues>;
 }
 
 /**
@@ -147,16 +148,100 @@ export function registerChatSurfaceRenderer(
  * is invoked by pi on every chat re-render with the real chat content
  * width — there's no need for the caller to thread `process.stdout.columns`.
  */
+export interface RenderChatSurfacePlainTextOptions {
+  readonly width?: number;
+  readonly now?: number;
+  readonly theme?: GraphTheme;
+}
+
+/**
+ * Render the full printable fallback stored in pi's custom-message `content`.
+ * The interactive TUI still uses `details` + the registered renderer; this
+ * string is for print mode, transcripts, and any host that cannot mount the
+ * custom component.
+ */
+export function renderChatSurfacePlainText(
+  payload: ChatSurfacePayload,
+  options: RenderChatSurfacePlainTextOptions = {},
+): string {
+  const themed = options.theme === undefined ? {} : { theme: options.theme };
+  const width = options.width;
+  const now = options.now ?? Date.now();
+
+  switch (payload.kind) {
+    case "dispatch": {
+      const rendered = renderDispatchConfirm({
+        workflowName: payload.workflowName,
+        runId: payload.runId,
+        inputs: payload.inputs,
+        width,
+        ...themed,
+      });
+      return [
+        rendered,
+        `run id: ${payload.runId}`,
+        `inputs: ${formatPlainRecord(payload.inputs)}`,
+      ].join("\n");
+    }
+    case "status": {
+      const rendered = renderStatusList(payload.runs, { width, now, ...themed });
+      if (payload.runs.length === 0) return rendered;
+      return [
+        rendered,
+        "",
+        ...payload.runs.map(
+          (run) => `run id: ${run.id} · workflow: ${run.name} · status: ${run.status}`,
+        ),
+      ].join("\n");
+    }
+    case "list": {
+      const rendered = renderWorkflowList(payload.entries, { width, ...themed });
+      if (payload.entries.length === 0) return rendered;
+      return [
+        rendered,
+        "",
+        ...payload.entries.map(formatWorkflowEntryPlain),
+      ].join("\n");
+    }
+    case "detail": {
+      const rendered = renderRunDetail(payload.detail, { width, now, ...themed });
+      const lines = [
+        rendered,
+        `run id: ${payload.detail.runId}`,
+        `inputs: ${formatPlainRecord(payload.detail.inputs)}`,
+      ];
+      if (payload.detail.result !== undefined) {
+        lines.push(`result: ${formatPlainValue(payload.detail.result)}`);
+      }
+      if (payload.detail.error !== undefined) {
+        lines.push(`error: ${payload.detail.error}`);
+      }
+      return lines.join("\n");
+    }
+    case "killed":
+      if (options.theme !== undefined) {
+        return renderWorkflowKilledNotice({
+          width: width ?? 80,
+          theme: options.theme,
+          run: payload.run,
+          previousStatus: payload.previousStatus,
+        }).join("\n");
+      }
+      return renderKilledPlainText(payload);
+  }
+}
+
 export function emitChatSurface(
   pi: ExtensionAPI,
   payload: ChatSurfacePayload,
+  options: { readonly content?: string } = {},
 ): void {
   const send = pi.sendMessage;
   if (typeof send !== "function") return;
-  // `content` is unused by our renderer but pi's message store may surface
-  // it in non-display contexts (e.g. transcript export); pick a short
-  // descriptor per kind so it remains greppable.
-  const content = describePayload(payload);
+  // The renderer consumes `details`, but print/json/transcript surfaces read
+  // the stored `content`. Default to a complete printable rendering so
+  // headless `/workflow list|status|status <id>` is useful without a TUI.
+  const content = options.content ?? renderChatSurfacePlainText(payload);
   (send as unknown as (msg: {
     customType: string;
     content: string;
@@ -174,14 +259,45 @@ export function emitChatSurface(
 // Internals
 // ---------------------------------------------------------------------------
 
-function describePayload(payload: ChatSurfacePayload): string {
-  switch (payload.kind) {
-    case "dispatch": return `dispatched ${payload.workflowName} · ${payload.runId.slice(0, 8)}`;
-    case "status":   return `status · ${payload.runs.length} run${payload.runs.length === 1 ? "" : "s"}`;
-    case "list":     return `workflows · ${payload.entries.length} registered`;
-    case "detail":   return `run detail · ${payload.detail.runId.slice(0, 8)}`;
-    case "killed":   return `workflow killed · ${payload.run.id.slice(0, 8)}`;
-  }
+function formatWorkflowEntryPlain(entry: WorkflowListEntry): string {
+  const required = entry.inputs
+    .filter((input) => input.required === true)
+    .map((input) => input.name);
+  const optional = entry.inputs
+    .filter((input) => input.required !== true)
+    .map((input) => input.name);
+  const inputs = [
+    required.length > 0 ? `required inputs: ${required.join(", ")}` : undefined,
+    optional.length > 0 ? `optional inputs: ${optional.join(", ")}` : undefined,
+  ].filter((part): part is string => part !== undefined);
+  const inputSummary = inputs.length > 0 ? inputs.join(" · ") : "inputs: (none)";
+  return `workflow: ${entry.name} · description: ${entry.description} · ${inputSummary}`;
+}
+
+function renderKilledPlainText(payload: KilledPayload): string {
+  const run = payload.run;
+  const stageCount = run.stages.length;
+  const runningStages = run.stages.filter((stage) => stage.status === "running").length;
+  return [
+    "Workflow killed",
+    `workflow: ${run.name}`,
+    `run id: ${run.id}`,
+    `status: ${payload.previousStatus} → killed`,
+    `active stages: ${runningStages}/${stageCount}`,
+    `inspect: /workflow status ${run.id}`,
+  ].join("\n");
+}
+
+function formatPlainRecord(record: Readonly<WorkflowInputValues>): string {
+  const entries = Object.entries(record);
+  if (entries.length === 0) return "(none)";
+  return entries.map(([key, value]) => `${key}=${formatPlainValue(value)}`).join(", ");
+}
+
+function formatPlainValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  const json = JSON.stringify(value);
+  return json === undefined ? String(value) : json;
 }
 
 function makeComponent(

package/dist/builtin/workflows/src/tui/chat-surface.ts

@@ -118,7 +118,10 @@ export function renderRoundedBoxLines(opts: RenderRoundedBoxOpts & { width: numb
     ? ` ${truncateToWidth(opts.title, titleBudget, ELLIPSIS)} `
     : "";
   const topFill = Math.max(0, inner - visibleWidth(titleText));
-  const top = `${border}╭${titleText}${"─".repeat(topFill)}╮${reset}`;
+  // `titleText` may contain its own ANSI runs (for status-coloured badges).
+  // Re-prime the border colour after it so RESETs inside the title do not
+  // leave the trailing rule/corner on the terminal default colour.
+  const top = `${border}╭${titleText}${border}${"─".repeat(topFill)}╮${reset}`;
 
   const body = opts.bodyLines.length > 0 ? opts.bodyLines : [""];
   const rows = body.map((line) => {
@@ -504,6 +507,7 @@ function stageGlyph(status: StageStatus): string {
     case "completed": return "✓";
     case "running":   return "●";
     case "failed":    return "✗";
+    case "awaiting_input": return "？";
     case "skipped":   return "⊘";
     case "pending":
     default:          return "○";
@@ -515,6 +519,7 @@ function stageColor(status: StageStatus, theme: GraphTheme): string {
     case "completed": return hexToAnsi(theme.success);
     case "running":   return hexToAnsi(theme.warning);
     case "failed":    return hexToAnsi(theme.error);
+    case "awaiting_input": return hexToAnsi(theme.info);
     case "skipped":   return hexToAnsi(theme.dim);
     case "pending":
     default:          return hexToAnsi(theme.dim);

package/dist/builtin/workflows/src/tui/dispatch-confirm.ts

@@ -33,6 +33,7 @@
  */
 
 import type { GraphTheme } from "./graph-theme.js";
+import type { WorkflowInputValues } from "../shared/types.js";
 import {
   renderHintRows,
   renderRoundedBox,
@@ -59,7 +60,7 @@ export interface RenderDispatchConfirmOpts {
   /** Real run UUID; the renderer surfaces the first 8 chars in the tag. */
   runId: string;
   /** Inputs merged from CLI tokens + picker output. */
-  inputs: Readonly<Record<string, unknown>>;
+  inputs: Readonly<WorkflowInputValues>;
   /** Provide for themed chrome; omit for plain ASCII. */
   theme?: GraphTheme;
   /** Render width (cells). Defaults to `process.stdout.columns`. */
@@ -195,7 +196,7 @@ interface InputsSegment {
  *    label.
  */
 function renderInputsSegment(
-  inputs: Readonly<Record<string, unknown>>,
+  inputs: Readonly<WorkflowInputValues>,
   budget: number,
   theme?: GraphTheme,
 ): InputsSegment | null {

package/dist/builtin/workflows/src/tui/graph-canvas.ts

@@ -9,7 +9,7 @@
  * keeps the buffer cheap for wide-but-mostly-empty graph canvases.
  *
  * cross-ref:
- *   - github.com/flora131/atomic packages/atomic-sdk/src/components/connectors.ts
+ *   - github.com/bastani-inc/atomic packages/atomic-sdk/src/components/connectors.ts
  *   - src/tui/graph-view.ts  _renderGraph
  */