@bastani/atomic 0.9.8 → 0.9.9-alpha.2

package/dist/builtin/workflows/src/durable/completed-catalog.ts

@@ -0,0 +1,245 @@
+import { readFileSync, statSync } from "node:fs";
+import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
+import type { WorkflowInputValues } from "../shared/types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import type {
+  DurableCheckpoint,
+  DurableStageCheckpoint,
+  ResumableWorkflowEntry,
+} from "./types.js";
+import { resolveDurableEntry } from "./resume-runtime.js";
+
+export type CompletedWorkflowResolution =
+  | { readonly kind: "found"; readonly entry: ResumableWorkflowEntry; readonly snapshot: RunSnapshot }
+  | { readonly kind: "ambiguous"; readonly matches: readonly ResumableWorkflowEntry[] }
+  | { readonly kind: "not_found" }
+  | { readonly kind: "stale"; readonly entry: ResumableWorkflowEntry };
+
+interface SessionTranscriptEntry {
+  readonly type?: string;
+  readonly id?: string;
+  readonly timestamp?: string;
+  readonly message?: {
+    readonly role?: string;
+    readonly content?: string | object;
+  };
+}
+
+interface StageDraft {
+  readonly replayKey: string;
+  readonly name: string;
+  readonly firstCompletedAt: number;
+  readonly output?: DurableStageCheckpoint["output"];
+  readonly result?: string;
+  readonly sessionId?: string;
+  readonly sessionFile?: string;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly durationMs?: number;
+  readonly model?: string;
+  readonly fastMode?: boolean;
+  readonly attemptedModels?: readonly string[];
+  readonly modelAttempts?: DurableStageCheckpoint["modelAttempts"];
+}
+
+/** Authoritative completed rows. This path is deliberately separate from resumability. */
+export function listCompletedFromBackend(
+  backend: DurableWorkflowBackend,
+): readonly ResumableWorkflowEntry[] {
+  return backend.listCompletedWorkflows();
+}
+
+/** Completed rows whose authoritative checkpoints and referenced transcripts still exist. */
+export function listOpenableCompletedWorkflows(
+  backend: DurableWorkflowBackend,
+): readonly ResumableWorkflowEntry[] {
+  return listCompletedFromBackend(backend)
+    .filter((entry) => completedWorkflowSnapshot(backend, entry) !== undefined)
+    .sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+export function resolveCompletedWorkflow(
+  workflowIdOrPrefix: string,
+  backend: DurableWorkflowBackend,
+  openableCatalog: readonly ResumableWorkflowEntry[] = listOpenableCompletedWorkflows(backend),
+): CompletedWorkflowResolution {
+  const resolved = resolveDurableEntry(workflowIdOrPrefix, openableCatalog);
+  if (resolved !== undefined) {
+    if ("kind" in resolved) return { kind: "ambiguous", matches: resolved.matches };
+    const snapshot = completedWorkflowSnapshot(backend, resolved);
+    return snapshot === undefined
+      ? { kind: "stale", entry: resolved }
+      : { kind: "found", entry: resolved, snapshot };
+  }
+
+  const authoritative = resolveDurableEntry(workflowIdOrPrefix, listCompletedFromBackend(backend));
+  if (authoritative === undefined) return { kind: "not_found" };
+  if ("kind" in authoritative) return { kind: "ambiguous", matches: authoritative.matches };
+  return { kind: "stale", entry: authoritative };
+}
+
+export function completedWorkflowSnapshot(
+  backend: DurableWorkflowBackend,
+  entry: ResumableWorkflowEntry,
+): RunSnapshot | undefined {
+  const handle = backend.getWorkflow(entry.workflowId);
+  if (handle === undefined || handle.status !== "completed") return undefined;
+  const checkpoints = backend.listCheckpoints(entry.workflowId);
+  if (checkpoints.length === 0) return undefined;
+  const stages = stageSnapshotsFromCheckpoints(checkpoints, handle.updatedAt).map(validatedStageTranscript);
+  if (!stages.some((stage) => stage.sessionFile !== undefined)) return undefined;
+
+  return {
+    id: handle.workflowId,
+    name: handle.name,
+    inputs: { ...handle.inputs } as WorkflowInputValues,
+    status: "completed",
+    stages,
+    startedAt: handle.createdAt,
+    endedAt: handle.updatedAt,
+    durationMs: Math.max(0, handle.updatedAt - handle.createdAt),
+    resumable: false,
+  };
+}
+
+function validatedStageTranscript(stage: StageSnapshot): StageSnapshot {
+  if (stage.sessionFile === undefined || isReopenableSessionTranscript(stage.sessionFile)) return stage;
+  const { sessionFile, ...withoutSessionFile } = stage;
+  void sessionFile;
+  return withoutSessionFile;
+}
+
+function isReopenableSessionTranscript(path: string): boolean {
+  try {
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size === 0) return false;
+    const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length < 2) return false;
+    const entries: SessionTranscriptEntry[] = [];
+    for (const line of lines) {
+      const parsed = JSON.parse(line) as object;
+      if (typeof parsed !== "object" || parsed === null) return false;
+      entries.push(parsed as SessionTranscriptEntry);
+    }
+    const header = entries[0];
+    return header?.type === "session" && typeof header.id === "string" && entries.some(isUsableContextMessage);
+  } catch {
+    return false;
+  }
+}
+
+function isUsableContextMessage(entry: SessionTranscriptEntry): boolean {
+  return entry.type === "message"
+    && typeof entry.id === "string"
+    && typeof entry.timestamp === "string"
+    && typeof entry.message?.role === "string"
+    && hasUsableMessageContent(entry.message.content);
+}
+
+function hasUsableMessageContent(content: string | object | undefined): boolean {
+  if (typeof content === "string") return content.trim().length > 0;
+  return Array.isArray(content) && content.some(hasUsableContentBlock);
+}
+
+function hasUsableContentBlock(block: object): boolean {
+  if (typeof block !== "object" || block === null) return false;
+  const contentBlock = block as {
+    readonly text?: string;
+    readonly thinking?: string;
+    readonly data?: string;
+    readonly name?: string;
+  };
+  return [contentBlock.text, contentBlock.thinking, contentBlock.data, contentBlock.name]
+    .some((value) => typeof value === "string" && value.trim().length > 0);
+}
+
+function stageSnapshotsFromCheckpoints(
+  checkpoints: readonly DurableCheckpoint[],
+  fallbackCompletedAt: number,
+): StageSnapshot[] {
+  const drafts = new Map<string, StageDraft>();
+  for (const checkpoint of checkpoints) {
+    if (checkpoint.kind !== "stage") continue;
+    const existing = drafts.get(checkpoint.replayKey);
+    drafts.set(checkpoint.replayKey, mergeStageDraft(existing, checkpoint));
+  }
+  const ordered = [...drafts.values()].sort((a, b) => a.firstCompletedAt - b.firstCompletedAt);
+  if (ordered.length === 0) return [syntheticCheckpointStage(checkpoints.length, fallbackCompletedAt)];
+  return ordered.map(stageSnapshotFromDraft);
+}
+
+function mergeStageDraft(
+  existing: StageDraft | undefined,
+  checkpoint: DurableStageCheckpoint,
+): StageDraft {
+  return {
+    replayKey: checkpoint.replayKey,
+    name: existing?.name ?? checkpoint.name,
+    firstCompletedAt: Math.min(existing?.firstCompletedAt ?? checkpoint.completedAt, checkpoint.completedAt),
+    ...valueOrExisting("output", checkpoint, existing),
+    ...valueOrExisting("result", checkpoint, existing),
+    ...valueOrExisting("sessionId", checkpoint, existing),
+    ...valueOrExisting("sessionFile", checkpoint, existing),
+    ...valueOrExisting("startedAt", checkpoint, existing),
+    ...valueOrExisting("endedAt", checkpoint, existing),
+    ...valueOrExisting("durationMs", checkpoint, existing),
+    ...valueOrExisting("model", checkpoint, existing),
+    ...valueOrExisting("fastMode", checkpoint, existing),
+    ...valueOrExisting("attemptedModels", checkpoint, existing),
+    ...valueOrExisting("modelAttempts", checkpoint, existing),
+  };
+}
+
+function valueOrExisting<
+  K extends keyof Omit<StageDraft, "replayKey" | "name" | "firstCompletedAt">
+>(key: K, checkpoint: DurableStageCheckpoint, existing: StageDraft | undefined): Pick<StageDraft, K> | object {
+  const checkpointValue = checkpoint[key];
+  if (checkpointValue !== undefined) return { [key]: checkpointValue } as Pick<StageDraft, K>;
+  const existingValue = existing?.[key];
+  return existingValue === undefined ? {} : { [key]: existingValue } as Pick<StageDraft, K>;
+}
+
+function stageSnapshotFromDraft(draft: StageDraft, index: number): StageSnapshot {
+  const startedAt = draft.startedAt ?? draft.firstCompletedAt;
+  const endedAt = draft.endedAt ?? draft.firstCompletedAt;
+  return {
+    id: `completed-stage-${index + 1}`,
+    name: draft.name,
+    status: "completed",
+    parentIds: [],
+    startedAt,
+    endedAt,
+    durationMs: draft.durationMs ?? Math.max(0, endedAt - startedAt),
+    ...(stageResult(draft) !== undefined ? { result: stageResult(draft) } : {}),
+    replayKey: draft.replayKey,
+    toolEvents: [],
+    attachable: false,
+    ...(draft.sessionId !== undefined ? { sessionId: draft.sessionId } : {}),
+    ...(draft.sessionFile !== undefined ? { sessionFile: draft.sessionFile } : {}),
+    ...(draft.model !== undefined ? { model: draft.model } : {}),
+    ...(draft.fastMode !== undefined ? { fastMode: draft.fastMode } : {}),
+    ...(draft.attemptedModels !== undefined ? { attemptedModels: draft.attemptedModels } : {}),
+    ...(draft.modelAttempts !== undefined ? { modelAttempts: draft.modelAttempts } : {}),
+  };
+}
+
+function stageResult(draft: StageDraft): string | undefined {
+  if (draft.result !== undefined) return draft.result;
+  if (draft.output === undefined) return undefined;
+  return typeof draft.output === "string" ? draft.output : JSON.stringify(draft.output);
+}
+
+function syntheticCheckpointStage(checkpointCount: number, completedAt: number): StageSnapshot {
+  return {
+    id: "completed-checkpoints",
+    name: "durable checkpoints",
+    status: "completed",
+    parentIds: [],
+    startedAt: completedAt,
+    endedAt: completedAt,
+    durationMs: 0,
+    result: `${checkpointCount} durable checkpoint${checkpointCount === 1 ? "" : "s"}`,
+    toolEvents: [],
+    attachable: false,
+  };
+}

package/dist/builtin/workflows/src/durable/completed-inspection.ts

@@ -0,0 +1,213 @@
+import type { Store } from "../shared/store.js";
+import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
+import { createStageContext, type StageAdapters } from "../runs/foreground/stage-runner.js";
+import {
+  stageControlRegistry as defaultStageControlRegistry,
+  type AgentSessionEventListener,
+  type StageControlHandle,
+  type StageControlRegistry,
+} from "../runs/foreground/stage-control-registry.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import {
+  listOpenableCompletedWorkflows,
+  resolveCompletedWorkflow,
+} from "./completed-catalog.js";
+import type { ResumableWorkflowEntry } from "./types.js";
+
+export type OpenCompletedDurableResult =
+  | { readonly ok: true; readonly runId: string; readonly workflowId: string; readonly name: string; readonly message: string }
+  | { readonly ok: false; readonly reason: "not_found" | "ambiguous" | "stale" | "active"; readonly message: string };
+
+export interface OpenCompletedDurableDeps {
+  readonly durableBackend: DurableWorkflowBackend;
+  readonly store: Store;
+  readonly adapters?: StageAdapters;
+  readonly stageControlRegistry?: StageControlRegistry;
+  readonly cwd?: string;
+  readonly defaultSessionDir?: string;
+}
+
+interface CompletedChatRegistration {
+  readonly handle: StageControlHandle;
+  readonly unregister: () => void;
+}
+
+const completedChatRegistrations = new WeakMap<
+  StageControlRegistry,
+  Map<string, CompletedChatRegistration>
+>();
+
+/**
+ * Open a completed durable workflow as an immutable run snapshot. The only
+ * mutable surface is a lazily reopened stage chat, which appends follow-up
+ * conversation to its retained Atomic session without dispatching the workflow.
+ */
+export function openCompletedDurableWorkflow(
+  workflowIdOrPrefix: string,
+  deps: OpenCompletedDurableDeps,
+  catalog: readonly ResumableWorkflowEntry[] = listOpenableCompletedWorkflows(deps.durableBackend),
+): OpenCompletedDurableResult {
+  const resolved = resolveCompletedWorkflow(workflowIdOrPrefix, deps.durableBackend, catalog);
+  if (resolved.kind === "not_found") {
+    return failure("not_found", `No completed durable workflow found for id/prefix: ${workflowIdOrPrefix}`);
+  }
+  if (resolved.kind === "ambiguous") {
+    const matches = resolved.matches.map((entry) => `${entry.name} (${entry.workflowId.slice(0, 8)})`).join(", ");
+    return failure("ambiguous", `Ambiguous completed workflow prefix "${workflowIdOrPrefix}" matches: ${matches}`);
+  }
+  if (resolved.kind === "stale") {
+    return failure(
+      "stale",
+      `Completed workflow ${resolved.entry.workflowId.slice(0, 8)} is stale or missing durable checkpoint/session data and cannot be opened.`,
+    );
+  }
+
+  const existing = deps.store.runs().find((run) => run.id === resolved.snapshot.id);
+  if (existing !== undefined && existing.status !== "completed") {
+    return failure(
+      "active",
+      `Workflow ${resolved.snapshot.id.slice(0, 8)} is already active in this session; attach with /workflow connect ${resolved.snapshot.id.slice(0, 8)} instead.`,
+    );
+  }
+  const snapshot = resolved.snapshot;
+  if (existing !== undefined) deps.store.removeRun(existing.id);
+  deps.store.recordRunStart(snapshot);
+  registerCompletedChatHandles(snapshot, deps);
+  return {
+    ok: true,
+    runId: snapshot.id,
+    workflowId: snapshot.id,
+    name: snapshot.name,
+    message: `Opened completed durable workflow "${snapshot.name}" (${snapshot.id.slice(0, 8)}) for read-only inspection and follow-up chat.`,
+  };
+}
+
+function failure(
+  reason: "not_found" | "ambiguous" | "stale" | "active",
+  message: string,
+): OpenCompletedDurableResult {
+  return { ok: false, reason, message };
+}
+
+function registerCompletedChatHandles(
+  snapshot: RunSnapshot,
+  deps: OpenCompletedDurableDeps,
+): void {
+  if (deps.adapters?.agentSession === undefined) return;
+  const registry = deps.stageControlRegistry ?? defaultStageControlRegistry;
+  const registrations = completedChatRegistrations.get(registry) ?? new Map();
+  completedChatRegistrations.set(registry, registrations);
+  const desiredKeys = new Set(
+    snapshot.stages
+      .filter((stage) => stage.sessionFile !== undefined)
+      .map((stage) => completedChatKey(snapshot.id, stage.id)),
+  );
+  for (const [key, registration] of registrations) {
+    if (!key.startsWith(`${snapshot.id}:`) || desiredKeys.has(key)) continue;
+    removeCompletedChatRegistration(registrations, key, registration);
+  }
+  for (const stage of snapshot.stages) {
+    if (stage.sessionFile === undefined) continue;
+    const key = completedChatKey(snapshot.id, stage.id);
+    const registration = registrations.get(key);
+    const existing = registry.get(snapshot.id, stage.id);
+    if (existing?.sessionFile === stage.sessionFile && !existing.isDisposed) continue;
+    if (registration !== undefined) {
+      removeCompletedChatRegistration(registrations, key, registration);
+    } else if (existing !== undefined) {
+      disposeCompletedChatHandle(existing);
+    }
+    const handle = createCompletedChatHandle(snapshot, stage, stage.sessionFile, deps.adapters, deps.cwd, deps.defaultSessionDir);
+    const unregister = registry.register(handle);
+    registrations.set(key, { handle, unregister });
+    registry.detachControl(snapshot.id, stage.id, handle);
+  }
+}
+
+function completedChatKey(runId: string, stageId: string): string {
+  return `${runId}:${stageId}`;
+}
+
+function removeCompletedChatRegistration(
+  registrations: Map<string, CompletedChatRegistration>,
+  key: string,
+  registration: CompletedChatRegistration,
+): void {
+  registration.unregister();
+  registrations.delete(key);
+  disposeCompletedChatHandle(registration.handle);
+}
+
+function disposeCompletedChatHandle(handle: StageControlHandle): void {
+  void Promise.resolve(handle.dispose?.()).catch((error: Error) => {
+    console.warn("atomic-workflows: completed chat handle dispose failed", error);
+  });
+}
+
+function createCompletedChatHandle(
+  run: RunSnapshot,
+  stage: StageSnapshot,
+  sessionFile: string,
+  adapters: StageAdapters,
+  cwd: string | undefined,
+  defaultSessionDir: string | undefined,
+): StageControlHandle {
+  const context = createStageContext({
+    runId: run.id,
+    stageId: stage.id,
+    stageName: stage.name,
+    adapters,
+    stageOptions: {
+      resumeFromSessionFile: sessionFile,
+      ...(cwd !== undefined ? { cwd } : {}),
+    },
+    ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
+  });
+  let disposed = false;
+  const ensureAttached = async (): Promise<void> => {
+    if (disposed) throw new Error(`Completed stage chat "${stage.name}" is closed.`);
+    if (context.__sessionMeta().sessionFile === undefined) {
+      await context.__ensureSessionFromFile(sessionFile);
+    }
+  };
+  return {
+    runId: run.id,
+    stageId: stage.id,
+    stageName: stage.name,
+    status: "completed",
+    get sessionId() { return context.__sessionMeta().sessionId ?? stage.sessionId; },
+    get sessionFile() { return context.__sessionMeta().sessionFile ?? sessionFile; },
+    get isStreaming() { return context.isStreaming; },
+    get isDisposed() { return disposed; },
+    get messages() { return context.messages; },
+    get agentSession() { return context.__agentSession(); },
+    async ensureAttached() { await ensureAttached(); },
+    async prompt(text: string) {
+      await ensureAttached();
+      await context.prompt(text);
+    },
+    async steer(text: string) {
+      await ensureAttached();
+      await context.steer(text);
+    },
+    async followUp(text: string) {
+      await ensureAttached();
+      await context.followUp(text);
+    },
+    async pause() {
+      throw new Error("Completed workflow snapshots cannot be paused or resumed.");
+    },
+    async resume(message?: string) {
+      if (message !== undefined && message.trim().length > 0) {
+        await ensureAttached();
+        await context.prompt(message);
+      }
+    },
+    subscribe(listener: AgentSessionEventListener) { return context.subscribe(listener); },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      await context.__dispose();
+    },
+  };
+}