@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/src/shared/authoring-contract-ui.ts

@@ -156,6 +156,8 @@ export interface WorkflowToolOptions {
 	readonly maxAttempts?: number;
 	readonly intervalMs?: number;
 	readonly backoffRate?: number;
+	/** Maximum duration in milliseconds for each callback attempt. */
+	readonly timeoutMs?: number;
 }
 
 export type WorkflowToolReturnOptions = WorkflowToolOptions & { readonly failureMode: "return" };
@@ -235,6 +237,7 @@ export interface WorkflowDefinition<
 	readonly normalizedName: string;
 	readonly description: string;
 	readonly autoAttach?: true;
+	readonly heartbeatIntervalMinutes: number;
 	readonly inputs: WorkflowInputSchemaMap;
 	readonly outputs?: WorkflowOutputSchemaMap;
 	readonly inputBindings?: WorkflowInputBindings;
@@ -368,6 +371,8 @@ export interface ToolNodeSnapshot extends WorkflowSerializableObject {
 	/** Stable durable node identity. */
 	readonly id: string;
 	readonly name: string;
+	/** Exact invocation arguments retained for read-only graph inspection. */
+	readonly args?: Readonly<Record<string, WorkflowSerializableValue>>;
 	readonly argsHash: string;
 	readonly ordinal: number;
 	readonly parentIds: readonly string[];
@@ -377,6 +382,11 @@ export interface ToolNodeSnapshot extends WorkflowSerializableObject {
 	readonly executionOrder?: number;
 	readonly startedAt?: number;
 	readonly endedAt?: number;
+	readonly durationMs?: number;
+	/** Full serializable callback result, when one was retained. */
+	readonly result?: WorkflowSerializableValue;
+	/** Callback source captured from `fn.toString()` at registration. */
+	readonly source?: string;
 	readonly resultSummary?: string;
 	readonly error?: string;
 	readonly attachable: false;

package/dist/builtin/workflows/src/shared/graph-store-snapshot.ts

@@ -10,6 +10,7 @@ import type {
 	WorkflowChildReplaySnapshot,
 	WorkflowNotice,
 } from "./store-types.js";
+import { boundedToolPayload, boundedToolPayloadRecord, boundedToolText } from "./tool-payload-bounds.js";
 import type { WorkflowOutputValues, WorkflowSerializableValue } from "./types.js";
 
 export const COMPACT_RESULT_FIELD_LIMIT = 1024;
@@ -115,7 +116,9 @@ function compactStage(stage: StageSnapshot): StageSnapshot {
 		attemptedModels: _attemptedModels,
 		modelAttempts: _modelAttempts,
 		// Agent-stage results can be unbounded and graph cards do not render
-		// them. Durable tool cards use ToolNodeSnapshot.resultSummary instead.
+		// them. Tool cards render a constant body, so `resultSummary` is kept
+		// for status surfaces while the bounded full payload below backs the
+		// read-only detail view.
 		result: _result,
 		...metadata
 	} = stage;
@@ -133,7 +136,16 @@ function compactStage(stage: StageSnapshot): StageSnapshot {
 }
 
 function compactToolNode(node: ToolNodeSnapshot): ToolNodeSnapshot {
-	return { ...node, parentIds: [...node.parentIds] };
+	return {
+		...node,
+		parentIds: [...node.parentIds],
+		// Author payloads may be cyclic, may throw on property access, and may be
+		// arbitrarily large. `boundedToolPayload` contains all three so building a
+		// snapshot cannot throw and one version cannot retain a whole payload.
+		...(node.args !== undefined ? { args: boundedToolPayloadRecord(node.args) } : {}),
+		...(node.result !== undefined ? { result: boundedToolPayload(node.result) } : {}),
+		...(node.source !== undefined ? { source: boundedToolText(node.source) } : {}),
+	};
 }
 
 function compactRun(run: RunSnapshot): RunSnapshot {

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

@@ -35,6 +35,18 @@ export interface SessionEntry {
 	readonly payload?: Record<string, WorkflowSerializableValue>;
 	readonly customType?: string;
 	readonly data?: Record<string, WorkflowSerializableValue>;
+	/**
+	 * The payload a custom-message entry was published with. Distinct from
+	 * `data`: this is what an extension passed as `details`, so a heartbeat entry
+	 * carries its `WorkflowHeartbeatEventDetails` here. Read only to recover a
+	 * heartbeat's identity structurally rather than by parsing its rendered text.
+	 *
+	 * `unknown` deliberately: the host declares this generic and any extension
+	 * may write any shape into it, so every reader narrows. Typing it as a known
+	 * record here would be a claim about other extensions' data that nothing
+	 * enforces.
+	 */
+	readonly details?: unknown;
 }
 
 export interface NormalizedSessionEntry {

package/dist/builtin/workflows/src/shared/prompt-answer.ts

@@ -0,0 +1,130 @@
+/**
+ * Kind-aware answers for primitive workflow HIL prompts.
+ *
+ * Workflow-tool payloads cross a model/provider boundary before they reach the
+ * prompt waiter. Normalize them while the pending prompt descriptor is still
+ * available, rather than letting each UI sink guess what a raw value means.
+ */
+
+import type { PendingPrompt, PromptKind } from "./store-types.js";
+
+export type PrimitivePromptKind = Exclude<PromptKind, "custom">;
+
+export type PrimitivePrompt = Pick<PendingPrompt, "kind" | "choices" | "initial"> & {
+	readonly kind: PrimitivePromptKind;
+};
+
+type PrimitivePendingPrompt = PendingPrompt & { readonly kind: PrimitivePromptKind };
+
+export function isPrimitivePrompt(prompt: PendingPrompt): prompt is PrimitivePendingPrompt {
+	return prompt.kind !== "custom";
+}
+
+export type PrimitivePromptAnswer = string | boolean;
+
+export interface PromptAnswerAccepted {
+	readonly ok: true;
+	readonly value: PrimitivePromptAnswer;
+}
+
+export interface PromptAnswerRejected {
+	readonly ok: false;
+}
+
+export type PrimitivePromptAnswerResult = PromptAnswerAccepted | PromptAnswerRejected;
+
+const CONFIRM_TRUE = new Set(["true", "yes", "y", "approve", "confirm"]);
+const CONFIRM_FALSE = new Set(["false", "no", "n", "reject", "deny"]);
+
+function normalizeText(value: string): string {
+	return value.trim().toLowerCase();
+}
+
+function accepted(value: PrimitivePromptAnswer): PromptAnswerAccepted {
+	return { ok: true, value };
+}
+
+function rejected(): PromptAnswerRejected {
+	return { ok: false };
+}
+
+function selectIndex(value: unknown, choiceCount: number): number | undefined {
+	if (typeof value === "number") {
+		return Number.isInteger(value) && value >= 1 && value <= choiceCount ? value - 1 : undefined;
+	}
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (!/^[1-9]\d*$/u.test(trimmed)) return undefined;
+	const index = Number(trimmed);
+	return Number.isSafeInteger(index) && index <= choiceCount ? index - 1 : undefined;
+}
+
+function coerceConfirm(value: unknown): PrimitivePromptAnswerResult {
+	if (typeof value === "boolean") return accepted(value);
+	if (typeof value !== "string") return rejected();
+	const normalized = normalizeText(value);
+	if (CONFIRM_TRUE.has(normalized)) return accepted(true);
+	if (CONFIRM_FALSE.has(normalized)) return accepted(false);
+	return rejected();
+}
+
+function coerceSelect(choices: readonly string[], value: unknown): PrimitivePromptAnswerResult {
+	if (typeof value === "string") {
+		const normalized = normalizeText(value);
+		const choice = choices.find((candidate) => normalizeText(candidate) === normalized);
+		if (choice !== undefined) return accepted(choice);
+	}
+	const index = selectIndex(value, choices.length);
+	return index === undefined ? rejected() : accepted(choices[index]!);
+}
+
+/**
+ * Normalize a raw answer for a primitive prompt, or reject it.
+ *
+ * The `default` branch is unreachable through the guarded call sites, which all
+ * exclude `custom` prompts. It exists so a malformed descriptor is rejected
+ * rather than falling through to `undefined`, which would make
+ * `requirePrimitivePromptAnswer` throw a bare `TypeError` on `result.ok`.
+ */
+export function coercePrimitivePromptAnswer(prompt: PrimitivePrompt, value: unknown): PrimitivePromptAnswerResult {
+	switch (prompt.kind) {
+		case "input":
+		case "editor":
+			return typeof value === "string" ? accepted(value) : rejected();
+		case "confirm":
+			return coerceConfirm(value);
+		case "select":
+			return coerceSelect(prompt.choices ?? [], value);
+		default:
+			return rejected();
+	}
+}
+
+/** Require a prompt answer to identify a value; defaults are reserved for abort/cancel paths. */
+export function requirePrimitivePromptAnswer(prompt: PrimitivePrompt, value: unknown): PrimitivePromptAnswer {
+	const result = coercePrimitivePromptAnswer(prompt, value);
+	if (result.ok) return result.value;
+	throw new Error(
+		`atomic-workflows: Invalid ${prompt.kind} prompt answer. ${primitivePromptAnswerExpectation(prompt)}`,
+	);
+}
+
+/** Explain the only accepted workflow-tool answer shapes for a prompt. */
+export function primitivePromptAnswerExpectation(prompt: PrimitivePrompt): string {
+	switch (prompt.kind) {
+		case "input":
+		case "editor":
+			return "Expected a text string in response, text, or message.";
+		case "confirm":
+			return "Expected a boolean or a case-insensitive trimmed string: true/false, yes/y, no/n, approve/reject, or confirm/deny.";
+		case "select":
+			return `Expected an exact choice label (case-insensitive, trimmed) or a 1-based numeric index. Available choices: ${prompt.choices?.join(", ") || "(none)"}.`;
+		default:
+			return "Expected an answer matching the pending prompt kind.";
+	}
+}
+
+/** Format a truthful workflow-send noop for an unusable primitive answer. */
+export function primitivePromptAnswerRejection(promptId: string, prompt: PrimitivePrompt): string {
+	return `Invalid answer for ${prompt.kind} prompt ${promptId}. ${primitivePromptAnswerExpectation(prompt)}`;
+}

package/dist/builtin/workflows/src/shared/session-scoped-singleton.ts

@@ -0,0 +1,98 @@
+import { sessionScopedExtensionState } from "@bastani/atomic";
+
+/**
+ * Shared across duplicate copies of this module after a host scope is adopted.
+ * Windows' resolver can evaluate the same singleton file twice: one copy
+ * registers, the other adopts. A module-local `instance` then splits them.
+ *
+ * Construction records this copy's local in the process bag if the key is new,
+ * but `current()` / `facade` stay module-local until `adopt`. That keeps
+ * no-scope evaluations isolated. The first `adopt` claims the recorded local
+ * (the first constructor's populated object) into the host scope.
+ */
+const SHARED_STATES_KEY = Symbol.for("atomic-workflows/session-scoped-singleton-pre-adoption@1");
+
+interface SharedSingletonState<T extends object> {
+	local: T;
+	instance: T | undefined;
+	localClaimed: boolean;
+}
+
+interface ProcessSingletonStates {
+	readonly version: 1;
+	readonly byKey: Map<string, SharedSingletonState<object>>;
+}
+
+function processBag(): Record<symbol, ProcessSingletonStates | undefined> {
+	return globalThis as typeof globalThis & Record<symbol, ProcessSingletonStates | undefined>;
+}
+
+function recordLocal<T extends object>(key: string, local: T): SharedSingletonState<T> {
+	const bag = processBag();
+	let states = bag[SHARED_STATES_KEY];
+	if (states === undefined || states.version !== 1) {
+		states = { version: 1, byKey: new Map() };
+		bag[SHARED_STATES_KEY] = states;
+	}
+	const existing = states.byKey.get(key) as SharedSingletonState<T> | undefined;
+	if (existing !== undefined) return existing;
+	const created: SharedSingletonState<T> = { local, instance: undefined, localClaimed: false };
+	states.byKey.set(key, created as SharedSingletonState<object>);
+	return created;
+}
+
+/** Drop every shared slot so unit tests stay isolated. */
+export function resetSessionScopedSingletonPreAdoptionForTests(): void {
+	delete processBag()[SHARED_STATES_KEY];
+}
+
+/**
+ * Stable facade over a run-scoped singleton that can re-bind to host
+ * session-scoped state after `/reload` re-evaluates the module graph.
+ *
+ * Local state seeds at most one unseen scope; later unseen scopes start fresh.
+ * After the first adopt, every module copy for the same key reads one instance.
+ */
+export interface SessionScopedSingleton<T extends object> {
+	readonly facade: T;
+	readonly adopt: (scope: object) => T;
+	readonly current: () => T;
+}
+
+export function createSessionScopedSingleton<T extends object>(
+	key: string,
+	createLocal: () => T,
+): SessionScopedSingleton<T> {
+	const local = createLocal();
+	const shared = recordLocal(key, local);
+	let instance = local;
+
+	const live = (): T => shared.instance ?? instance;
+
+	const current = (): T => live();
+
+	const adopt = (scope: object): T => {
+		shared.instance = sessionScopedExtensionState(scope, key, () => {
+			if (shared.localClaimed) return createLocal();
+			shared.localClaimed = true;
+			return shared.local;
+		});
+		instance = shared.instance;
+		return shared.instance;
+	};
+
+	const facade = new Proxy(local, {
+		get(_target, prop) {
+			const value = Reflect.get(live(), prop, live());
+			if (typeof value === "function") {
+				return value.bind(live());
+			}
+			return value;
+		},
+		has(_target, prop) {
+			return Reflect.has(live(), prop);
+		},
+	});
+
+	return { facade, adopt, current };
+}

package/dist/builtin/workflows/src/shared/stage-ui-broker.ts

@@ -7,6 +7,7 @@ import type {
 	PiKeybindings,
 	PiTheme,
 } from "../extension/wiring.js";
+import { createSessionScopedSingleton } from "./session-scoped-singleton.js";
 import type { StageInputAnswer, StagePromptAdapter } from "./stage-prompt.js";
 import type { StagePromptAnswerSource, Store } from "./store.js";
 import { store as defaultStore } from "./store.js";
@@ -329,4 +330,11 @@ export async function mountStageCustomUi(
 	return { request, component };
 }
 
-export const stageUiBroker = new StageUiBroker();
+const SESSION_KEY = "workflows:stage-ui:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, () => new StageUiBroker());
+
+export const stageUiBroker = singleton.facade;
+
+export function adoptStageUiBroker(scope: object): StageUiBroker {
+	return singleton.adopt(scope);
+}

package/dist/builtin/workflows/src/shared/store-factory.ts

@@ -1,3 +1,4 @@
+import { createSessionScopedSingleton } from "./session-scoped-singleton.js";
 import { createStoreContext } from "./store-internal.js";
 import { createPromptStoreMethods } from "./store-prompt-methods.js";
 import type { Store } from "./store-public-types.js";
@@ -15,4 +16,11 @@ export function createStore(): Store {
 	};
 }
 
-export const store: Store = createStore();
+const SESSION_KEY = "workflows:store:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createStore);
+
+export const store: Store = singleton.facade;
+
+export function adoptStore(scope: object): Store {
+	return singleton.adopt(scope);
+}

package/dist/builtin/workflows/src/shared/store-public-types.ts

@@ -106,7 +106,8 @@ export interface Store {
 	recordToolNodeEnd(
 		runId: string,
 		nodeId: string,
-		update: Pick<ToolNodeSnapshot, "status"> & Partial<Pick<ToolNodeSnapshot, "endedAt" | "resultSummary" | "error">>,
+		update: Pick<ToolNodeSnapshot, "status"> &
+			Partial<Pick<ToolNodeSnapshot, "endedAt" | "durationMs" | "result" | "resultSummary" | "error">>,
 	): boolean;
 	/** Link a workflow boundary stage to its live child run before that child completes. */
 	recordStageWorkflowChildRun(runId: string, stageId: string, ref: WorkflowChildRunRef): boolean;

package/dist/builtin/workflows/src/shared/store-tool-node-methods.ts

@@ -1,6 +1,7 @@
 import { type StoreContext, TERMINAL_STATUSES } from "./store-internal.js";
 import type { Store } from "./store-public-types.js";
 import type { RunSnapshot, ToolNodeSnapshot } from "./store-types.js";
+import { boundedToolPayload } from "./tool-payload-bounds.js";
 
 type ToolNodeStoreMethods = Pick<Store, "recordToolNodeStart" | "recordToolNodeRunning" | "recordToolNodeEnd">;
 
@@ -44,6 +45,12 @@ export function createToolNodeStoreMethods(context: StoreContext): ToolNodeStore
 				return false;
 			node.status = update.status;
 			if (update.endedAt !== undefined) node.endedAt = update.endedAt;
+			if (update.durationMs !== undefined) node.durationMs = update.durationMs;
+			// The live store is read raw by session/status surfaces that clone and
+			// re-serialize it, so the author's result is detached and bounded here
+			// rather than aliased. The durable checkpoint keeps the exact output,
+			// which is what a cached replay returns.
+			if (update.result !== undefined) node.result = boundedToolPayload(update.result);
 			if (update.resultSummary !== undefined) node.resultSummary = update.resultSummary;
 			if (update.error !== undefined) node.error = update.error;
 			context.bumpAndNotify();

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

@@ -3,7 +3,12 @@
  * cross-ref: spec §5.5
  */
 
-import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import type {
+	WorkflowExitStatus,
+	WorkflowInputValues,
+	WorkflowOutputValues,
+	WorkflowSerializableValue,
+} from "./types.js";
 
 export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "killed";
 export type StageStatus =
@@ -23,6 +28,8 @@ export interface ToolNodeSnapshot {
 	readonly kind: "tool";
 	readonly id: string;
 	readonly name: string;
+	/** Exact invocation arguments retained for read-only graph inspection. */
+	readonly args?: Readonly<Record<string, WorkflowSerializableValue>>;
 	readonly argsHash: string;
 	readonly ordinal: number;
 	readonly parentIds: readonly string[];
@@ -35,8 +42,18 @@ export interface ToolNodeSnapshot {
 	executionOrder?: number;
 	startedAt?: number;
 	endedAt?: number;
+	durationMs?: number;
+	/** Full serializable callback result, when one was retained. */
+	result?: WorkflowSerializableValue;
+	/**
+	 * Callback source captured from `fn.toString()` when the call was
+	 * registered. Inspection-only: capture never re-runs the callback, never
+	 * reads a file, and never reaches past the value already in hand.
+	 */
+	source?: string;
 	resultSummary?: string;
 	error?: string;
+	/** Tool nodes remain read-only graph inspection targets, never chat targets. */
 	readonly attachable: false;
 }