@bastani/atomic 0.8.21 → 0.8.22

package/dist/builtin/workflows/src/shared/persistence-restore.ts

@@ -7,7 +7,10 @@
  */
 
 import type { Store } from "./store.js";
-import type { RunSnapshot, StageSnapshot, StageStatus } from "./store-types.js";
+import type { RunSnapshot, StageSnapshot, StageStatus, WorkflowChildReplaySnapshot } from "./store-types.js";
+import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import { workflowSerializableObjectSchema } from "./serializable.js";
+import { Value } from "typebox/value";
 import { isWorkflowFailureKind } from "./workflow-failures.js";
 
 // ---------------------------------------------------------------------------
@@ -40,7 +43,7 @@ export interface SessionManager {
 export interface InFlightRun {
   readonly runId: string;
   readonly name: string;
-  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly inputs: Readonly<WorkflowInputValues>;
   readonly startTs: number;
   /** Stage IDs that were started (in order) but may or may not have ended. */
   readonly stageIds: readonly string[];
@@ -57,7 +60,7 @@ export interface InFlightRun {
  * Pure function — does not mutate anything.
  */
 export function scanInFlightRuns(entries: readonly SessionEntry[]): InFlightRun[] {
-  const started = new Map<string, { name: string; inputs: Record<string, unknown>; startTs: number; stageIds: string[] }>();
+  const started = new Map<string, { name: string; inputs: WorkflowInputValues; startTs: number; stageIds: string[] }>();
   const ended = new Set<string>();
 
   for (const entry of entries) {
@@ -73,9 +76,7 @@ export function scanInFlightRuns(entries: readonly SessionEntry[]): InFlightRun[
       ) {
         started.set(runId, {
           name,
-          inputs: (inputs !== null && typeof inputs === "object" && !Array.isArray(inputs))
-            ? (inputs as Record<string, unknown>)
-            : {},
+          inputs: serializableObjectOrEmpty(inputs),
           startTs: ts,
           stageIds: [],
         });
@@ -180,6 +181,9 @@ export function restoreOnSessionStart(
         status: "running",
         stages,
         startedAt: run.startTs,
+        ...(runMeta.parentRunId !== undefined ? { parentRunId: runMeta.parentRunId } : {}),
+        ...(runMeta.parentStageId !== undefined ? { parentStageId: runMeta.parentStageId } : {}),
+        ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
         ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
         ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
       };
@@ -198,6 +202,9 @@ export function restoreOnSessionStart(
         error: "Run did not complete — process was interrupted.",
         failureKind: "unknown",
         resumable: false,
+        ...(runMeta.parentRunId !== undefined ? { parentRunId: runMeta.parentRunId } : {}),
+        ...(runMeta.parentStageId !== undefined ? { parentStageId: runMeta.parentStageId } : {}),
+        ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
         ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
         ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
       };
@@ -262,7 +269,7 @@ function _buildStageSnapshots(
         if (typeof failureKind === "string" && isWorkflowFailureKind(failureKind)) snap.failureKind = failureKind;
         if (typeof failureMessage === "string") snap.failureMessage = failureMessage;
         if (typeof skippedReason === "string") snap.skippedReason = skippedReason;
-        Object.assign(snap, replayMetadata(entry.payload));
+        Object.assign(snap, replayMetadata(entry.payload), workflowChildMetadata(entry.payload));
       }
     }
   }
@@ -289,6 +296,66 @@ function replayMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "
   };
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function serializableObject(value: unknown): WorkflowOutputValues | undefined {
+  return Value.Check(workflowSerializableObjectSchema, value)
+    ? (value as WorkflowOutputValues)
+    : undefined;
+}
+
+function serializableObjectOrEmpty(value: unknown): WorkflowOutputValues {
+  return serializableObject(value) ?? {};
+}
+
+function isWorkflowChildReplayStatus(status: unknown): status is WorkflowChildReplaySnapshot["status"] {
+  return status === "completed";
+}
+
+function workflowChildMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "workflowChild"> {
+  const workflowChild = payload["workflowChild"];
+  if (!isRecord(workflowChild)) return {};
+  const alias = workflowChild["alias"];
+  const workflow = workflowChild["workflow"];
+  const childRunId = workflowChild["runId"];
+  const status = workflowChild["status"];
+  const outputs = workflowChild["outputs"];
+  if (
+    typeof alias !== "string" ||
+    typeof workflow !== "string" ||
+    typeof childRunId !== "string" ||
+    !isWorkflowChildReplayStatus(status) ||
+    !isRecord(outputs)
+  ) {
+    return {};
+  }
+
+  // `structuredClone` detaches the restored snapshot from the parsed JSONL
+  // payload with a guaranteed deep copy, independent of the TypeBox
+  // serializable check. Declared `outputs` are the child contract, so a
+  // non-serializable value bails the whole child snapshot.
+  let clonedOutputs: WorkflowOutputValues;
+  try {
+    const serializableOutputs = serializableObject(outputs);
+    if (serializableOutputs === undefined) return {};
+    clonedOutputs = structuredClone(serializableOutputs);
+  } catch {
+    return {};
+  }
+
+  return {
+    workflowChild: {
+      alias,
+      workflow,
+      runId: childRunId,
+      status,
+      outputs: clonedOutputs,
+    },
+  };
+}
+
 function restoreStageStatus(status: unknown): StageStatus {
   switch (status) {
     case "completed":
@@ -301,7 +368,7 @@ function restoreStageStatus(status: unknown): StageStatus {
 }
 
 function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): void {
-  const started = new Map<string, { readonly name: string; readonly inputs: Readonly<Record<string, unknown>>; readonly startTs: number }>();
+  const started = new Map<string, { readonly name: string; readonly inputs: Readonly<WorkflowInputValues>; readonly startTs: number }>();
   const ended = new Map<string, Record<string, unknown>>();
 
   for (const entry of entries) {
@@ -313,9 +380,7 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
       if (typeof runId === "string" && typeof name === "string" && typeof ts === "number") {
         started.set(runId, {
           name,
-          inputs: (inputs !== null && typeof inputs === "object" && !Array.isArray(inputs))
-            ? (inputs as Record<string, unknown>)
-            : {},
+          inputs: serializableObjectOrEmpty(inputs),
           startTs: ts,
         });
       }
@@ -342,6 +407,9 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
       status: "running",
       stages,
       startedAt: start.startTs,
+      ...(runMeta.parentRunId !== undefined ? { parentRunId: runMeta.parentRunId } : {}),
+      ...(runMeta.parentStageId !== undefined ? { parentStageId: runMeta.parentStageId } : {}),
+      ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
       ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
       ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
     });
@@ -380,12 +448,24 @@ function restoreTerminalRunStatus(status: unknown): "completed" | "failed" | "ki
 function findRunStartMetadata(
   entries: readonly SessionEntry[],
   runId: string,
-): { readonly resumedFromRunId?: string; readonly resumeFromStageId?: string } {
+): {
+  readonly parentRunId?: string;
+  readonly parentStageId?: string;
+  readonly rootRunId?: string;
+  readonly resumedFromRunId?: string;
+  readonly resumeFromStageId?: string;
+} {
   for (const entry of entries) {
     if (entry.type !== "workflow.run.start" || entry.payload["runId"] !== runId) continue;
+    const parentRunId = entry.payload["parentRunId"];
+    const parentStageId = entry.payload["parentStageId"];
+    const rootRunId = entry.payload["rootRunId"];
     const resumedFromRunId = entry.payload["resumedFromRunId"];
     const resumeFromStageId = entry.payload["resumeFromStageId"];
     return {
+      ...(typeof parentRunId === "string" ? { parentRunId } : {}),
+      ...(typeof parentStageId === "string" ? { parentStageId } : {}),
+      ...(typeof rootRunId === "string" ? { rootRunId } : {}),
       ...(typeof resumedFromRunId === "string" ? { resumedFromRunId } : {}),
       ...(typeof resumeFromStageId === "string" ? { resumeFromStageId } : {}),
     };

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -6,6 +6,8 @@
  * through gracefully when the runtime doesn't support the method.
  */
 
+import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+
 // ---------------------------------------------------------------------------
 // Structural API type (subset of ExtensionAPI needed here)
 // ---------------------------------------------------------------------------
@@ -30,7 +32,10 @@ export interface PersistenceAPI {
 export interface RunStartPayload {
   readonly runId: string;
   readonly name: string;
-  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly inputs: Readonly<WorkflowInputValues>;
+  readonly parentRunId?: string;
+  readonly parentStageId?: string;
+  readonly rootRunId?: string;
   readonly resumedFromRunId?: string;
   readonly resumeFromStageId?: string;
   readonly ts: number;
@@ -55,6 +60,14 @@ export interface StageProgressPayload {
   readonly payload: unknown;
 }
 
+export interface WorkflowChildReplayPayload {
+  readonly alias: string;
+  readonly workflow: string;
+  readonly runId: string;
+  readonly status: "completed";
+  readonly outputs: WorkflowOutputValues;
+}
+
 export interface StageEndPayload {
   readonly runId: string;
   readonly stageId: string;
@@ -68,12 +81,13 @@ export interface StageEndPayload {
   readonly replayKey?: string;
   readonly replayedFromStageId?: string;
   readonly replayed?: boolean;
+  readonly workflowChild?: WorkflowChildReplayPayload;
 }
 
 export interface RunEndPayload {
   readonly runId: string;
   readonly status: string;
-  readonly result?: unknown;
+  readonly result?: WorkflowOutputValues;
   readonly error?: string;
   readonly failureKind?: string;
   readonly failureMessage?: string;
@@ -96,6 +110,9 @@ export function appendRunStart(api: PersistenceAPI, payload: RunStartPayload): v
     runId: payload.runId,
     name: payload.name,
     inputs: payload.inputs,
+    ...(payload.parentRunId !== undefined ? { parentRunId: payload.parentRunId } : {}),
+    ...(payload.parentStageId !== undefined ? { parentStageId: payload.parentStageId } : {}),
+    ...(payload.rootRunId !== undefined ? { rootRunId: payload.rootRunId } : {}),
     ...(payload.resumedFromRunId !== undefined ? { resumedFromRunId: payload.resumedFromRunId } : {}),
     ...(payload.resumeFromStageId !== undefined ? { resumeFromStageId: payload.resumeFromStageId } : {}),
     ts: payload.ts,
@@ -153,6 +170,7 @@ export function appendStageEnd(
     ...(payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {}),
     ...(payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {}),
     ...(payload.replayed !== undefined ? { replayed: payload.replayed } : {}),
+    ...(payload.workflowChild !== undefined ? { workflowChild: payload.workflowChild } : {}),
   });
   if (opts?.emitMessage === true && payload.summary && typeof api.appendCustomMessageEntry === "function") {
     api.appendCustomMessageEntry(
@@ -168,7 +186,7 @@ export function appendRunEnd(api: PersistenceAPI, payload: RunEndPayload): void
   api.appendEntry("workflow.run.end", {
     runId: payload.runId,
     status: payload.status,
-    ...(payload.result !== undefined ? { result: payload.result as Record<string, unknown> } : {}),
+    ...(payload.result !== undefined ? { result: payload.result } : {}),
     ...(payload.error !== undefined ? { error: payload.error } : {}),
     ...(payload.failureKind !== undefined ? { failureKind: payload.failureKind } : {}),
     ...(payload.failureMessage !== undefined ? { failureMessage: payload.failureMessage } : {}),

package/dist/builtin/workflows/src/shared/render-inputs-schema.ts

@@ -19,7 +19,7 @@
  *     and for non-TTY consumers (LLM tool results, logfiles, --help in
  *     redirected output).
  *
- * The layout in pretty mode mirrors flora131/atomic's `renderInputsText` so a
+ * The layout in pretty mode mirrors bastani-inc/atomic's `renderInputsText` so a
  * dev moving between the atomic CLI and the pi extension feels at home:
  *
  *     INPUTS FOR ralph
@@ -42,7 +42,6 @@
 import type { GraphTheme } from "../tui/graph-theme.js";
 import { paint } from "../tui/color-utils.js";
 import { renderRoundedBox, chatWidth } from "../tui/chat-surface.js";
-import { truncateToWidth } from "../tui/text-helpers.js";
 import type { WorkflowInputEntry } from "../extension/render-result.js";
 
 export interface RenderInputsSchemaOptions {

package/dist/builtin/workflows/src/shared/run-visibility.ts

@@ -0,0 +1,9 @@
+import type { RunSnapshot } from "./store-types.js";
+
+export function isTopLevelWorkflowRun(run: Pick<RunSnapshot, "parentRunId">): boolean {
+  return run.parentRunId === undefined;
+}
+
+export function topLevelWorkflowRuns(runs: readonly RunSnapshot[]): RunSnapshot[] {
+  return runs.filter(isTopLevelWorkflowRun);
+}

package/dist/builtin/workflows/src/shared/schema-introspection.ts

@@ -0,0 +1,121 @@
+/**
+ * schema-introspection — single adapter between TypeBox input/output schemas
+ * and the legacy normalized field descriptor (`WorkflowInputEntry`) consumed by
+ * the inputs picker UI, validation, dispatch, and render paths.
+ *
+ * Authors declare inputs/outputs with TypeBox schemas (`Type.String`,
+ * `Type.Number`, `Type.Union([...literals])`, …). The many UI/render/dispatch
+ * surfaces still want a flat `{ type, choices?, default?, required?,
+ * description? }` view; rather than rewrite all of them, they derive that view
+ * from a TypeBox schema through this module.
+ */
+
+import {
+  IsAny,
+  IsArray,
+  IsBoolean,
+  IsInteger,
+  IsLiteralString,
+  IsNumber,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUnion,
+  type TSchema,
+} from "typebox";
+import type { WorkflowInputEntry } from "../extension/render-result.js";
+
+/** Field-kind label expected by the legacy descriptor consumers. */
+export type SchemaFieldKind =
+  | "text"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "select"
+  | "object"
+  | "array"
+  | "unknown";
+
+interface SchemaMeta {
+  readonly default?: unknown;
+  readonly description?: string;
+  readonly anyOf?: readonly TSchema[];
+  readonly const?: unknown;
+}
+
+function meta(schema: TSchema): SchemaMeta {
+  return schema as unknown as SchemaMeta;
+}
+
+/** True when every member of a union is a string literal. */
+function isStringLiteralUnion(schema: TSchema): boolean {
+  if (!IsUnion(schema)) return false;
+  const members = meta(schema).anyOf ?? [];
+  return members.length > 0 && members.every((m) => IsLiteralString(m));
+}
+
+/** Map a TypeBox schema to the legacy field-kind label. */
+export function schemaFieldKind(schema: TSchema): SchemaFieldKind {
+  if (isStringLiteralUnion(schema)) return "select";
+  if (IsLiteralString(schema)) return "text";
+  if (IsString(schema)) return "text";
+  if (IsInteger(schema)) return "integer";
+  if (IsNumber(schema)) return "number";
+  if (IsBoolean(schema)) return "boolean";
+  if (IsObject(schema)) return "object";
+  if (IsArray(schema)) return "array";
+  if (IsAny(schema)) return "unknown";
+  return "unknown";
+}
+
+/** Declared default value (`schema.default`), or undefined when none. */
+export function schemaDefault(schema: TSchema): unknown {
+  return meta(schema).default;
+}
+
+/** Declared description, or undefined. */
+export function schemaDescription(schema: TSchema): string | undefined {
+  return meta(schema).description;
+}
+
+/** Allowed string values for a string-literal union, else undefined. */
+export function schemaChoices(schema: TSchema): readonly string[] | undefined {
+  if (!isStringLiteralUnion(schema)) return undefined;
+  const members = meta(schema).anyOf ?? [];
+  return members.map((m) => String(meta(m).const));
+}
+
+/**
+ * A field is "required" in the picker/validation sense — i.e. the caller MUST
+ * supply it — when it is neither wrapped in `Type.Optional(...)` nor carries a
+ * `default`. A defaulted input is a required KEY at the type level (it is always
+ * present after defaults are applied) but the user need not provide it, so it is
+ * reported as not-required here, matching the legacy descriptor semantics where
+ * `{ default }` implied `required: false`.
+ */
+export function schemaIsRequired(schema: TSchema): boolean {
+  return !IsOptional(schema) && schemaDefault(schema) === undefined;
+}
+
+/** Derive the legacy normalized input descriptor for a single named field. */
+export function deriveInputField(name: string, schema: TSchema): WorkflowInputEntry {
+  const choices = schemaChoices(schema);
+  const def = schemaDefault(schema);
+  const description = schemaDescription(schema);
+  const entry: WorkflowInputEntry = {
+    name,
+    type: schemaFieldKind(schema),
+    required: schemaIsRequired(schema),
+  };
+  if (description !== undefined) entry.description = description;
+  if (def !== undefined) entry.default = def;
+  if (choices !== undefined) entry.choices = choices;
+  return entry;
+}
+
+/** Derive descriptors for an entire declared input map (preserving order). */
+export function deriveInputFields(
+  schema: Readonly<Record<string, TSchema>>,
+): WorkflowInputEntry[] {
+  return Object.entries(schema).map(([name, s]) => deriveInputField(name, s));
+}

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

@@ -0,0 +1,132 @@
+import { Refine, Type, type TSchema } from "typebox";
+
+/**
+ * A JSON-serializable object must be a *plain* object (or array, handled
+ * separately) — class instances such as `Date`, `Map`, or `RegExp` structurally
+ * look like empty records to the schema checker but are not JSON round-trippable,
+ * so they are rejected here.
+ */
+function isPlainObjectValue(value: unknown): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+import { Value } from "typebox/value";
+import type {
+  WorkflowOutputValues,
+  WorkflowSerializableValue,
+} from "./types.js";
+
+export const WORKFLOW_SERIALIZABLE_DESCRIPTION =
+  "JSON-serializable (string, finite number, boolean, null, array, or object)";
+
+/**
+ * Recursive TypeBox schema describing a JSON-serializable value: string, finite
+ * number, boolean, null, array of serializable values, or an object whose
+ * values are serializable. `Type.Number` already rejects NaN/Infinity in
+ * TypeBox's value checker, matching the previous `z.number().finite()`.
+ */
+export const workflowSerializableValueSchema: TSchema = Type.Cyclic(
+  {
+    Serializable: Type.Union([
+      Type.String(),
+      Type.Number(),
+      Type.Boolean(),
+      Type.Null(),
+      Type.Array(Type.Ref("Serializable")),
+      Refine(
+        Type.Record(Type.String(), Type.Ref("Serializable")),
+        isPlainObjectValue,
+        "must be a plain JSON object",
+      ),
+    ]),
+  },
+  "Serializable",
+);
+
+export const workflowSerializableObjectSchema: TSchema = Type.Record(
+  Type.String(),
+  workflowSerializableValueSchema,
+);
+
+export function workflowSerializableTypeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number" && Number.isNaN(value)) return "NaN";
+  if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+  return typeof value;
+}
+
+/** Convert a TypeBox `instancePath` ("/a/0/b") to the legacy "a[0].b" form. */
+function formatInstancePath(instancePath: string): string {
+  if (!instancePath) return "";
+  const segments = instancePath.split("/").filter((s) => s.length > 0);
+  return segments
+    .map((segment) =>
+      /^\d+$/.test(segment)
+        ? `[${segment}]`
+        : /^[A-Za-z_$][\w$]*$/.test(segment)
+          ? `.${segment}`
+          : `[${JSON.stringify(segment)}]`,
+    )
+    .join("")
+    .replace(/^\./, "");
+}
+
+/** Resolve the value located at a TypeBox instance path within `root`. */
+function valueAtInstancePath(root: unknown, instancePath: string): unknown {
+  if (!instancePath) return root;
+  let current: unknown = root;
+  for (const segment of instancePath.split("/").filter((s) => s.length > 0)) {
+    if (current === null || typeof current !== "object") return current;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function firstError(schema: TSchema, value: unknown): { instancePath: string } | undefined {
+  for (const error of Value.Errors(schema, value)) {
+    return { instancePath: error.instancePath };
+  }
+  return undefined;
+}
+
+export function workflowSerializableValidationError(
+  value: unknown,
+  label: string,
+): string | undefined {
+  if (Value.Check(workflowSerializableValueSchema, value)) return undefined;
+  const issue = firstError(workflowSerializableValueSchema, value);
+  const issuePath = issue === undefined ? "" : formatInstancePath(issue.instancePath);
+  const location = issuePath.length > 0 ? ` at ${issuePath}` : "";
+  const offending = issue === undefined ? value : valueAtInstancePath(value, issue.instancePath);
+  return `${label}${location} must be ${WORKFLOW_SERIALIZABLE_DESCRIPTION}, got ${workflowSerializableTypeName(offending)}`;
+}
+
+export function workflowSerializableObjectValidationError(
+  value: unknown,
+  label: string,
+): string | undefined {
+  if (Value.Check(workflowSerializableObjectSchema, value)) return undefined;
+  const issue = firstError(workflowSerializableObjectSchema, value);
+  const issuePath = issue === undefined ? "" : formatInstancePath(issue.instancePath);
+  const location = issuePath.length > 0 ? ` at ${issuePath}` : "";
+  const offending = issue === undefined ? value : valueAtInstancePath(value, issue.instancePath);
+  return `${label}${location} must be a ${WORKFLOW_SERIALIZABLE_DESCRIPTION} object, got ${workflowSerializableTypeName(offending)}`;
+}
+
+export function assertWorkflowSerializableValue(
+  value: unknown,
+  label: string,
+): asserts value is WorkflowSerializableValue {
+  const error = workflowSerializableValidationError(value, label);
+  if (error !== undefined) throw new Error(`atomic-workflows: ${error}`);
+}
+
+export function assertWorkflowSerializableObject(
+  value: unknown,
+  label: string,
+): asserts value is WorkflowOutputValues {
+  const error = workflowSerializableObjectValidationError(value, label);
+  if (error !== undefined) throw new Error(`atomic-workflows: ${error}`);
+}