@bastani/atomic 0.9.27 → 0.9.28-alpha.2

package/docs/sdk/web-server.md

@@ -0,0 +1,325 @@
+---
+title: "Embedding Atomic in a web server"
+sidebarTitle: "Web server"
+description: "Run Atomic sessions and workflows behind a Next.js App Router route and stream their output to a browser."
+---
+
+# Embedding Atomic in a web server
+
+This guide puts an Atomic agent behind an HTTP endpoint, using a Next.js App Router project as the example. The same pattern works in any long-running Node.js server: keep one session per conversation, start a prompt per request, and stream the session's events back as newline-delimited JSON (NDJSON).
+
+Read the [SDK](/sdk) page first for `createAgentSession()` and session events.
+
+The examples use `createTranscript()`, `createAgentSessionAdapter()`, and `RunOpts.onStageSessionEvent`, which require an Atomic release newer than 0.9.28-alpha.1. Check the [changelog](/changelog) for your installed version.
+
+## Install
+
+```bash
+npm install @bastani/atomic
+```
+
+Atomic needs Node.js 22.19 or newer and does not require dependency install scripts.
+
+Bun blocks the install scripts of some dependencies, such as `@embedded-postgres/<platform>`, `protobufjs`, and `@google/genai`, and reports them after `bun add @bastani/atomic`. You don't need to add them to `trustedDependencies` in `package.json`: Atomic prepares the embedded Postgres runtime itself the first time it starts it, and it doesn't depend on the other scripts.
+
+## Keep Atomic out of the server bundle
+
+Atomic finds its bundled resources and native modules relative to its installed package, so it must load from `node_modules` rather than from Next.js's server bundle. List it in `serverExternalPackages` (Next.js 15 and later):
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  serverExternalPackages: ["@bastani/atomic", "@bastani/atomic-natives", "@bastani/pi-ai", "typebox"],
+};
+
+export default nextConfig;
+```
+
+Atomic's own dependencies load from `node_modules` once `@bastani/atomic` is external. The other entries cover packages your app may import directly, such as `typebox` for workflow schemas, so your code and Atomic share one copy. Add any other Atomic dependency you import yourself.
+
+Every route that imports Atomic must use the Node.js runtime:
+
+```ts
+export const runtime = "nodejs";
+```
+
+Import Atomic only from server code. Client components may use `import type` from `@bastani/atomic`, which adds nothing to the browser bundle.
+
+## Keep one session per conversation
+
+An `AgentSession` holds the conversation's history, so create one per conversation and reuse it across requests. Keep sessions on `globalThis`: in `next dev`, module-level variables reset on every hot reload, but `globalThis` survives, so open conversations don't vanish and old sessions aren't leaked. Restart the dev server after changing session options; existing sessions keep the options they were created with.
+
+```ts
+// lib/atomic.ts
+import "server-only";
+import { type AgentSession, createAgentSession, ModelRuntime, SessionManager } from "@bastani/atomic";
+
+export const WORKSPACE = process.env.AGENT_WORKSPACE ?? "/srv/agent-workspace";
+
+export interface Conversation {
+  session: AgentSession;
+  busy: boolean;
+}
+
+interface AtomicState {
+  modelRuntime: Promise<ModelRuntime>;
+  conversations: Map<string, Promise<Conversation>>;
+}
+
+const shared = globalThis as typeof globalThis & { atomicState?: AtomicState };
+const state = (shared.atomicState ??= {
+  modelRuntime: ModelRuntime.create(),
+  conversations: new Map(),
+});
+
+export function getConversation(id: string): Promise<Conversation> {
+  let conversation = state.conversations.get(id);
+  if (!conversation) {
+    conversation = state.modelRuntime.then(async (modelRuntime) => {
+      const { session } = await createAgentSession({
+        cwd: WORKSPACE,
+        sessionManager: SessionManager.inMemory(WORKSPACE),
+        modelRuntime,
+        tools: ["read", "find", "search"],
+        builtins: { workflows: false, subagents: false, mcp: false, "web-access": false, intercom: false },
+      });
+      return { session, busy: false };
+    });
+    conversation.catch(() => state.conversations.delete(id));
+    state.conversations.set(id, conversation);
+  }
+  return conversation;
+}
+
+export async function closeConversation(id: string): Promise<void> {
+  const conversation = state.conversations.get(id);
+  state.conversations.delete(id);
+  if (conversation) await (await conversation).session.dispose();
+}
+```
+
+`SessionManager.inMemory()` keeps history in process memory. To keep conversations across restarts, pass a file-backed `SessionManager` instead; see [Sessions](/sessions). Call `closeConversation()` when a conversation ends or has been idle for a while, because each open session holds resources until it is disposed.
+
+Sessions on `globalThis` live in one server process. Run this on a long-lived Node.js server, and route each conversation to the same instance if you run several. Short-lived serverless functions lose the session between requests.
+
+## Stream a prompt
+
+The route below starts one prompt and streams the assistant's output as NDJSON. `createTranscript()` turns session events into ordered, JSON-serializable parts (text, thinking, and tool calls joined to their results), so each line carries the complete output so far and the client simply replaces what it shows.
+
+```ts
+// app/api/chat/route.ts
+import { createTranscript, type TranscriptPart } from "@bastani/atomic";
+import { getConversation } from "@/lib/atomic";
+import { authenticate } from "@/lib/auth";
+
+export const runtime = "nodejs";
+
+export type ChatLine =
+  | { type: "parts"; parts: TranscriptPart[] }
+  | { type: "done" }
+  | { type: "error"; message: string };
+
+export async function POST(request: Request): Promise<Response> {
+  const user = await authenticate(request);
+  if (!user) return new Response("Unauthorized", { status: 401 });
+
+  const { conversationId, message } = (await request.json()) as { conversationId: string; message: string };
+  const conversation = await getConversation(`${user.id}:${conversationId}`);
+  const { session } = conversation;
+  if (conversation.busy || session.isStreaming) {
+    return new Response("This conversation is already answering a prompt.", { status: 409 });
+  }
+  if (request.signal.aborted) return new Response(null, { status: 499 });
+  conversation.busy = true;
+
+  const encoder = new TextEncoder();
+  const transcript = createTranscript();
+  let open = true;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const send = (line: ChatLine) => {
+        if (open) controller.enqueue(encoder.encode(`${JSON.stringify(line)}\n`));
+      };
+      const stop = () => void session.abort();
+      request.signal.addEventListener("abort", stop, { once: true });
+
+      const unsubscribe = session.subscribe((event) => {
+        transcript.apply(event);
+        if (
+          event.type === "message_update" ||
+          event.type === "message_end" ||
+          event.type === "tool_execution_update" ||
+          event.type === "tool_execution_end"
+        ) {
+          send({ type: "parts", parts: transcript.parts() });
+        }
+      });
+
+      session
+        .prompt(message)
+        .then(() => send({ type: "done" }))
+        .catch((error: Error) => send({ type: "error", message: error.message }))
+        .finally(() => {
+          unsubscribe();
+          request.signal.removeEventListener("abort", stop);
+          conversation.busy = false;
+          if (open) {
+            open = false;
+            controller.close();
+          }
+        });
+    },
+    cancel() {
+      open = false;
+      void session.abort();
+    },
+  });
+
+  return new Response(stream, {
+    headers: { "Content-Type": "application/x-ndjson; charset=utf-8", "Cache-Control": "no-cache" },
+  });
+}
+```
+
+A few details matter here:
+
+- **One prompt at a time.** `session.prompt()` rejects while the session is already streaming. The route answers `409` instead. `busy` is set synchronously, so two requests that arrive together can't both start a prompt. To queue a message instead of rejecting it, call `session.prompt(message, { streamingBehavior: "followUp" })`.
+- **Stop on disconnect.** When the browser disconnects or aborts its `fetch`, `request.signal` aborts and the stream is cancelled. Both call `session.abort()`, which stops the current turn and its tools but keeps the session usable.
+- **Payload size.** Each line repeats the whole output so far. For long answers, send lines on a timer instead of on every event, or send only the parts that changed.
+
+`createTranscript()` reports a tool result's text by default. To send a tool's structured `details` instead, pass `createTranscript({ toolResult: (toolName) => (toolName === "todo" ? "details" : "content") })`.
+
+## Read the stream in the browser
+
+```tsx
+// app/chat/send-message.ts
+import type { TranscriptPart } from "@bastani/atomic";
+import type { ChatLine } from "@/app/api/chat/route";
+
+export async function sendMessage(
+  conversationId: string,
+  message: string,
+  onParts: (parts: TranscriptPart[]) => void,
+  signal?: AbortSignal,
+): Promise<void> {
+  const response = await fetch("/api/chat", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ conversationId, message }),
+    signal,
+  });
+  if (!response.ok || !response.body) throw new Error(await response.text());
+
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  let buffered = "";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) return;
+    buffered += value;
+    const lines = buffered.split("\n");
+    buffered = lines.pop() ?? "";
+    for (const text of lines) {
+      if (!text) continue;
+      const line = JSON.parse(text) as ChatLine;
+      if (line.type === "parts") onParts(line.parts);
+      if (line.type === "error") throw new Error(line.message);
+    }
+  }
+}
+```
+
+Render each part by `type`: `text` and `thinking` are strings, and a `toolCall` part has `name`, `arguments`, and, once the tool reports progress or finishes, a `result` with `content`, `isError`, and `isPartial`. Pass an `AbortController`'s signal to stop the agent from the page.
+
+## Run a workflow from a route
+
+`run()` from `@bastani/atomic/workflows` runs a workflow definition in the server process. Each stage runs as an in-process Atomic session, so `run()` needs no adapters. Use `createAgentSessionAdapter()` when every stage should share session options, such as the same tool restrictions as your chat sessions:
+
+```ts
+// app/api/review/route.ts
+import { createTranscript, type Transcript } from "@bastani/atomic";
+import { createAgentSessionAdapter, run } from "@bastani/atomic/workflows";
+import { WORKSPACE } from "@/lib/atomic";
+import { authenticate } from "@/lib/auth";
+import { reviewWorkflow } from "@/workflows/review";
+
+export const runtime = "nodejs";
+
+export async function POST(request: Request): Promise<Response> {
+  if (!(await authenticate(request))) return new Response("Unauthorized", { status: 401 });
+  const { topic } = (await request.json()) as { topic: string };
+  if (request.signal.aborted) return new Response(null, { status: 499 });
+
+  const encoder = new TextEncoder();
+  const abort = new AbortController();
+  request.signal.addEventListener("abort", () => abort.abort(), { once: true });
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const send = (line: object) => {
+        if (!abort.signal.aborted) controller.enqueue(encoder.encode(`${JSON.stringify(line)}\n`));
+      };
+      const stages = new Map<string, Transcript>();
+
+      try {
+        const result = await run(reviewWorkflow, { topic }, {
+          cwd: WORKSPACE,
+          signal: abort.signal,
+          durability: { mode: "memory" },
+          adapters: {
+            agentSession: createAgentSessionAdapter({ cwd: WORKSPACE, tools: ["read", "find", "search"] }),
+          },
+          onStageSessionEvent: (runId, stageId, event) => {
+            let transcript = stages.get(stageId);
+            if (!transcript) stages.set(stageId, (transcript = createTranscript()));
+            transcript.apply(event);
+            if (event.type === "message_update" || event.type === "tool_execution_end") {
+              send({ type: "stage", runId, stageId, parts: transcript.parts() });
+            }
+          },
+        });
+        send({ type: "done", status: result.status, result: result.result, error: result.error });
+      } catch (error) {
+        send({ type: "error", message: error instanceof Error ? error.message : String(error) });
+      } finally {
+        if (!abort.signal.aborted) controller.close();
+      }
+    },
+    cancel() {
+      abort.abort();
+    },
+  });
+
+  return new Response(stream, { headers: { "Content-Type": "application/x-ndjson; charset=utf-8" } });
+}
+```
+
+`onStageSessionEvent` receives every stage's session events tagged with its run and stage ids, including stages that switch to a fallback model and stages of nested workflows. Aborting `signal`, here when the client disconnects, cancels the run.
+
+### Choose workflow durability
+
+By default, `run()` makes workflow state durable by starting a managed local Postgres, so a run can resume after the process exits. Request-scoped servers rarely want that:
+
+- **`durability: { mode: "memory" }`** keeps state in memory for this call only. No Postgres starts, and the run can't resume after the process exits. Use it when the request owns the run.
+- **`durability: { mode: "durable", systemDatabaseUrl }`** stores state in a Postgres database you run, such as a hosted one, and Atomic doesn't start its own. Use it in deployments that need runs to survive restarts. `DBOS_SYSTEM_DATABASE_URL`, when set, overrides the URL.
+
+One process uses one workflow database. See [Choosing the durable backend](/workflows/api-reference#choosing-the-durable-backend) for the full rules, and [Workflows](/workflows) for writing workflow definitions.
+
+## Secure the endpoint
+
+A route that drives an agent session lets whoever calls it run tools on your server with the server process's permissions. Atomic has [no built-in sandbox](/security#no-built-in-sandbox).
+
+- **Require authentication** on every route that creates sessions, sends prompts, or starts workflows, and scope conversation ids to the authenticated user, as `getConversation()` does above.
+- **Allow only the tools you need.** `tools` is an allowlist; the examples allow only the read-only `read`, `find`, and `search`. Leave out `bash`, `edit`, and `write` unless the agent must change files or run commands. `excludedTools` removes tools, and `noTools: "all"` exposes none. `ask_user_question` needs a person to answer, so leave it out of headless sessions. See [Tools](/sdk/reference#tools).
+- **Disable builtins you don't use.** `builtins` turns off the shipped workflows, subagents, MCP, web access, and Intercom packages, along with their tools.
+- **Choose the working directory deliberately.** `cwd` sets the starting directory for tool paths and controls which project settings, context files, and extensions Atomic discovers. It does not restrict file access: tools can use absolute paths and paths outside `cwd`. Point it at a directory you control, never at an upload or a user-supplied path.
+- **Isolate the process** in a container, VM, or restricted OS account when callers must not access other server files, even with read-only tools, or when the agent can write files or run commands. See [Containerization](/containerization).
+- **Keep credentials on the server.** Provider keys come from the server's `ModelRuntime`. Never send them to the browser or accept them from requests.
+
+## Next steps
+
+- [SDK](/sdk) for sessions, prompting, and events.
+- [SDK API reference](/sdk/reference) for every `createAgentSession()` option.
+- [Workflow API reference](/workflows/api-reference) for `run()` and `RunOpts`.

package/docs/sdk.md

@@ -26,6 +26,8 @@ For a custom host that runs background work, see [Owner-bound task supervisor](/
 
 Not sure the SDK is the right integration mode? Compare it with RPC and JSON mode on [Programmatic use](/programmatic).
 
+To serve an agent over HTTP, see [Embedding Atomic in a web server](/sdk/web-server), which walks through a Next.js App Router route that streams session output to a browser.
+
 ## Quick Start
 
 ```typescript
@@ -241,6 +243,7 @@ interface SessionWorkflows {
   pause(target: { all: true }): Promise<WorkflowRunControlOutcome>;
   quit(target: string | { all: true }): Promise<WorkflowRunControlOutcome>;
   resume(runId: string, options?: { stageId?: string; message?: string }): Promise<WorkflowRunControlOutcome>;
+  observe(observer: WorkflowActivityObserver): WorkflowActivitySubscription;
 }
 ```
 
@@ -313,7 +316,38 @@ async function onResumeClicked() {
 }
 ```
 
-`pause` holds the live run and keeps it resumable in this process; `quit` retires the executor at a durability boundary so a later process can resume it. After `quit`, or when resuming a run from a previous process, `resume` follows the durable resume path: keep the workflow definition and durable storage available. See [pausing, quitting, and resuming](/workflows/operations#pausing-quitting-and-resuming) for what each action guarantees. To watch runs change instead of polling `listRuns()`, use the observation contract in [Workflow activity and lifecycle hooks](/extensions/events#workflow-activity-and-lifecycle-hooks).
+`pause` holds the live run and keeps it resumable in this process; `quit` retires the executor at a durability boundary so a later process can resume it. After `quit`, or when resuming a run from a previous process, `resume` follows the durable resume path: keep the workflow definition and durable storage available. See [pausing, quitting, and resuming](/workflows/operations#pausing-quitting-and-resuming) for what each action guarantees.
+
+#### Observing workflow runs
+
+To follow runs instead of polling `listRuns()`, call `session.workflows.observe(observer)`. It covers runs that the agent launches with the `workflow` tool, and needs no extension. The first frame is a `snapshot`. After it come `changed` and `removed` frames, delivered in order. Each callback finishes before the next one starts. Call `dispose()` on the returned subscription to stop. The frames and cursors follow the [workflow activity contract](/extensions/events#workflow-activity-and-lifecycle-hooks).
+
+Each root summary carries a `graph` with the nodes of that root's workflow, including the nodes of nested child workflows. Nodes are `stage` nodes and `ctx.tool` nodes. Each one has an `id`, `kind`, `name`, `status`, `parentIds`, `runId`, `nodeId` (its run-local id), `depth`, and `executionOrder` when it is known. Tool nodes add their `ordinal`. A stage that is waiting on a prompt adds `pendingPrompt` with the prompt's `id`, `kind`, `message`, `choices`, and `createdAt`. A prompt that a run raises outside any stage appears in `graph.runPrompts` with the same fields and the `runId` that owns it. A node status change produces a `changed` frame. Frames are plain JSON-serializable objects.
+
+```typescript
+import type { WorkflowRootActivity } from "@bastani/atomic";
+
+const roots = new Map<string, WorkflowRootActivity>();
+const subscription = session.workflows.observe((frame) => {
+  if (frame.kind === "snapshot") {
+    roots.clear();
+    // `recovering` or `unavailable` means activity is unknown, not idle.
+    if (frame.availability === "ready") for (const root of frame.roots) roots.set(root.rootRunId, root);
+  } else if (frame.kind === "changed") {
+    roots.set(frame.root.rootRunId, frame.root);
+    for (const node of frame.root.graph?.nodes ?? []) {
+      renderNode(node.id, node.name, node.status, node.parentIds);
+    }
+  } else {
+    roots.delete(frame.rootRunId);
+  }
+});
+
+// Later:
+subscription.dispose();
+```
+
+Observation can start before the workflows package has finished loading; the first snapshot then reports `availability: "unavailable"`, and a `ready` snapshot follows. The subscription survives `session.reload()`. After a reload, the observer receives a new snapshot with a new cursor `epoch`, so replace everything you knew. When the session is disposed, each observer receives a final `snapshot` with `availability: "unavailable"` before `dispose()` resolves; after that, `observe()` throws `WorkflowRunControlUnavailableError`. This stream reports root activity and graph state. It does not carry the events inside each stage.
 
 ### Workflow and subagent children
 
@@ -403,6 +437,8 @@ A `ShutdownFailed` error contains component failures in `errors`; cleanup still
 
 Captured extension APIs also refuse new execution, mutations and registrations as soon as close or reload begins. Already-admitted `pi.exec()` calls remain part of the awaited drain; provide `signal` or `timeout` when invoking subprocesses that might not finish on their own. `abort()` alone does not retire the API. A rejected transactional reload restores the surviving generation's action admission.
 
+Custom messages queued with `persistWhenStreaming: true` survive a successful reload and receive their model turn through the replacement extensions. An explicitly paused queue remains paused; call `resumeQueuedMessages()` before sending the next prompt. A rejected transactional reload retains the notices for the next prompt on the surviving generation.
+
 #### Finishing admitted work
 
 Disposal and reload wait for admitted callbacks, resource refreshes, and subprocesses. Ensure callbacks can settle independently of disposal, including work started by cleanup handlers. Give `pi.exec()` calls a timeout or cancellation signal, and await them in the handler so you can inspect failures. Never make cleanup wait for disposal itself.
@@ -415,6 +451,24 @@ Strict transactional reload failure leaves the original generation usable. Ordin
 
 Prefer acquiring extension resources in `session_start`. If a factory acquires them earlier, register `session_shutdown` immediately, even if `extensionsOverride` may later omit that factory. Capture cleanup handles when acquiring resources rather than rereading loader getters during cleanup.
 
+Transactional reload dispatches candidate `session_start` before commit. Use `publishExtensionContextEffect(ctx, effect)` to publish shared lifecycle state only after commit and retiring-generation cleanup; rollback discards the effect. Outside a transactional candidate, it runs immediately. Awaiting the helper queues the effect, not its eventual execution, so startup must not depend on the effect's result.
+
+For synchronous identity handoff, use `publishExtensionContextEffect(ctx, effect, "commit")`. This phase runs after the transaction commits and before predecessor authority is revoked or any retirement work is awaited. It must not return a promise or start asynchronous work; asynchronous callbacks are rejected and reported. The default `"start"` phase still runs after retirement, when reporter and task-host startup is safe.
+
+Register generation-owned observer disposal with `registerExtensionContextRetirementEffect(ctx, dispose)` during `session_start`. Disposal is synchronous, runs before authority revocation and before rollback invalidation, and is independent of `session_shutdown` handler order. The returned function unregisters the effect. Keep awaited resource cleanup in `session_shutdown`; observer disposal must not quit or checkpoint preserved workflows.
+
+```typescript
+import { publishExtensionContextEffect, type ExtensionFactory } from "@bastani/atomic";
+
+const extension: ExtensionFactory = (pi) => {
+  pi.on("session_start", (_event, ctx) =>
+    publishExtensionContextEffect(ctx, () => {
+      pi.events.emit("example:session-ready", { sessionId: ctx.sessionManager.getSessionId() });
+    }),
+  );
+};
+```
+
 Do not cache dialog functions across reload attempts. Retiring functions refuse new questions; after a rejected transaction, use the surviving session's current `ctx.ui`.
 
 Shared loaders, event buses, settings, and `SessionManager` instances do not share live task ownership. Closing one session leaves another session's commands and borrowed discovery resources alone.
@@ -678,6 +732,34 @@ To rebuild an assistant message from deltas, accumulate them in your own message
 
 If you subscribe part-way through a turn, seed your object from `session.agent.state.streamingMessage`, if present, to include the deltas you missed.
 
+### Collecting assistant output
+
+`createTranscript()` does that bookkeeping for you. It turns session events into the assistant's output as ordered, JSON-serializable parts:
+
+```typescript
+import { createTranscript } from "@bastani/atomic";
+
+const transcript = createTranscript();
+session.subscribe((event) => transcript.apply(event));
+
+await session.prompt("List the files here");
+console.log(JSON.stringify(transcript.parts()));
+```
+
+`parts()` returns a fresh copy of the parts of every assistant message seen so far, including one still streaming:
+
+- `{ type: "text", text }`
+- `{ type: "thinking", thinking }`. Redacted thinking is left out.
+- `{ type: "toolCall", id, name, arguments, result? }`. `result` appears once the tool reports progress or finishes. It holds `isError` and `isPartial`, which stays `true` until the tool finishes. If the message is aborted or fails, tool calls without a final result get an error result carrying the error message.
+
+Events from tools called inside other tools (those with `parentToolCallId`) are ignored. By default, `result.content` holds the result's text content. To get a tool's structured `details` instead, pass `toolResult`:
+
+```typescript
+const transcript = createTranscript({
+  toolResult: (toolName) => (toolName === "todo" ? "details" : "content"),
+});
+```
+
 ## Options Reference
 
 Moved to [SDK API reference](/sdk/reference#options-reference).

package/docs/security.md

@@ -21,7 +21,7 @@ Trusting a project allows Atomic to load trust-gated project inputs, including:
 - missing project packages configured through project settings
 - project-local extensions and project package-managed extensions
 
-Declining trust skips protected resources, including project-local discovery of `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md`. Global context and explicitly supplied CLI resources remain available.
+Declining trust skips protected resources, including project-local discovery of `AGENTS.override.md`, `AGENTS.md`, and `CLAUDE.md`. Global context and explicitly supplied CLI resources remain available. Interactive sessions in an untrusted project show a warning that project resources are ignored; use `/trust` to save a decision, then restart Atomic.
 
 Before resolving trust, Atomic loads only user/global extensions and explicit CLI `-e` package-level extensions. Those trusted extensions can handle the `project_trust` event; the first to return a yes/no decision owns it.
 

package/docs/workflows/api-reference.md

@@ -1163,18 +1163,29 @@ interface StageSnapshot extends WorkflowSerializableObject {
   readonly id: string;
   readonly name: string;
   readonly status: StageStatus;
+  readonly parentIds: readonly string[];
+  readonly executionOrder?: number;
+  readonly model?: string;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly durationMs?: number;
   readonly result?: WorkflowSerializableValue;
   readonly error?: string;
+  readonly routerSelection?: ModelRouterOutput;
 }
 ```
 
 Programmatic `run(...)` returns this type. `exited` identifies `ctx.exit(...)` termination, and `stages` contains the final stage snapshots.
 
+Each stage snapshot carries its graph position: `parentIds` lists the stages it depends on, and `executionOrder` is its admission order among the run's stages and tool nodes. `model` is the effective model after fallback resolution; `routerSelection` is the automatic routing choice. Timestamps are epoch milliseconds and are absent until the stage starts or ends. The runtime may replace `parentIds` before a stage starts, so read it from the latest snapshot rather than caching it.
+
 ## Programmatic usage
 
 `@bastani/atomic/workflows` is Atomic's published workflow SDK. Import `workflow` from that specifier, import `Type` from `typebox`, and export the definition returned by `workflow({...})`. Workflow helpers may also import the host TypeBox runtime subpaths `typebox/compile` and `typebox/value`; the legacy `@sinclair/typebox` root and matching subpaths remain supported. Keep runtime helpers such as widget factories and shared utilities in a subdirectory outside the top-level discovery scan, such as `.atomic/workflows/lib/`; see [Workflow Locations](/workflows/operations#workflow-locations).
 
-Package authors list both `@bastani/atomic` and `typebox` in `peerDependencies`. The `@bastani/atomic` package publishes compiled JavaScript and declarations for `@bastani/atomic/workflows`, `@bastani/atomic/workflows/builtin`, and each `@bastani/atomic/workflows/builtin/*` module. TypeScript resolves those exports directly under `moduleResolution: NodeNext`. When Atomic executes a workflow file or an imported helper, its runtime loader resolves the workflow SDK and supported TypeBox aliases to the same in-memory host modules. It intentionally does not expose extension-only host modules such as the agent core, UI, provider transport, or lockfile implementation.
+Package authors list both `@bastani/atomic` and `typebox` in `peerDependencies`. The `@bastani/atomic` package publishes compiled JavaScript and declarations for `@bastani/atomic/workflows`, `@bastani/atomic/workflows/builtin`, and each `@bastani/atomic/workflows/builtin/*` module. TypeScript resolves those exports directly under `moduleResolution: NodeNext`. When Atomic executes a workflow file or an imported helper, its runtime loader resolves the workflow SDK and supported TypeBox aliases to the same in-memory host modules.
+
+The loader also shares the host's modules for the exact specifiers `@bastani/atomic`, `@bastani/pi-ai`, and `@bastani/pi-ai/providers/all`. These exceptions expose Atomic's public root API and the AI compatibility API and provider transports. The host's versions take precedence over project-local copies, including in standalone-binary installs without project packages. Workflow files and relative imports still refresh on reload. Other deep subpaths resolve from disk. The workflow loader does not share the extension loader's remaining host aliases, including the separate agent-core and UI packages, other AI subpaths, and `proper-lockfile`. Older or alternative hosts without [`getWorkflowHostModules()`](/extensions/api-reference#pi-getworkflowhostmodules) retain filesystem resolution for the three specifiers.
 
 ```ts
 import { workflow } from "@bastani/atomic/workflows";
@@ -1273,6 +1284,52 @@ function run<
 
 Executes a compiled definition programmatically with validated inputs. Empty-input workflows accept an empty readonly record.
 
+#### Stage sessions and adapters
+
+When `opts.adapters` supplies neither `agentSession` nor `prompt`, `run()` uses `createAgentSessionAdapter({ cwd: opts.cwd })`. Each stage then runs its own in-process Atomic `createAgentSession` session with an in-memory `SessionManager`, unless the stage sets `sessionDir` or resumes or forks a session. Stage sessions resolve models, credentials, settings, and resources the same way `createAgentSession` does. A `prompt` adapter on its own answers stage prompts itself, so `run()` adds no default session adapter beside it.
+
+```typescript
+function createAgentSessionAdapter(
+  baseOptions?: Omit<CreateAgentSessionOptions, "sessionManager">,
+): AgentSessionAdapter;
+
+interface AgentSessionAdapter {
+  create(
+    options: StageSessionCreateOptions,
+    meta?: StageExecutionMeta,
+  ): Promise<StageSessionRuntime | StageSessionCreateResult>;
+}
+```
+
+Call `createAgentSessionAdapter(baseOptions)` yourself to apply the same `createAgentSession` options, such as `agentDir`, `modelRuntime`, or `settingsManager`, to every stage. Options set on an individual stage override `baseOptions`. `baseOptions` cannot set `sessionManager`, because every stage needs its own. A `cwd` in `baseOptions` applies to every stage that doesn't set its own, and session files saved through `sessionDir` record that directory.
+
+A custom adapter's `create(options, meta)` receives the stage's session options, including any session manager Atomic opened for `sessionDir`, resume, or fork. It must resolve to `{ session }` or to the session itself, where `session` implements `StageSessionRuntime`. To change options per stage while keeping the stage policy that `createAgentSessionAdapter` applies, such as hiding the `workflow` tool from stage sessions, delegate to it:
+
+```ts
+import { createAgentSessionAdapter, run } from "@bastani/atomic/workflows";
+
+// Default: in-process stage sessions with in-memory session managers.
+await run(helloWorld, { name: "Atomic" }, { cwd: process.cwd() });
+
+// Shared options for every stage.
+await run(helloWorld, { name: "Atomic" }, {
+  adapters: { agentSession: createAgentSessionAdapter({ agentDir: "/srv/atomic-agent" }) },
+});
+
+// Per-stage options on top of the default adapter.
+const stageSessions = createAgentSessionAdapter();
+await run(helloWorld, { name: "Atomic" }, {
+  adapters: {
+    agentSession: {
+      create: (options, meta) =>
+        stageSessions.create(meta?.stageName === "review" ? { ...options, cwd: "/srv/review" } : options, meta),
+    },
+  },
+});
+```
+
+Without an attached workflow UI, a stage that calls `ask_user_question` waits for an answer until the run is aborted through `opts.signal`. For unattended runs, pass `executionMode: "non_interactive"`; stages then run without `ask_user_question`.
+
 ### `RunOpts`
 
 ```typescript
@@ -1307,6 +1364,7 @@ interface RunOpts {
   readonly onRunStart?: (snapshot: RunSnapshot) => void;
   readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
   readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
+  readonly onStageSessionEvent?: (runId: string, stageId: string, event: AgentSessionEvent) => void;
   readonly onRunEnd?: (
     runId: string,
     status: RunStatus,
@@ -1319,6 +1377,8 @@ interface RunOpts {
 
 Supplies runtime adapters, execution policy, persistence, MCP, cancellation, graph/store integration, continuation metadata, and lifecycle callbacks to `run(...)`. Every field is optional.
 
+`onStageSessionEvent` streams every agent-session event from each stage (for example `message_update`, `tool_execution_start`, and `tool_execution_end`), tagged with the stage's `runId` and `stageId`. `AgentSessionEvent` is exported by `@bastani/atomic`. The stream continues when a fallback model replaces a stage's session. Stages in nested `ctx.workflow(...)` runs report the child run's `runId`. Exceptions thrown by the listener, and rejections from an async listener, are ignored and do not affect the stage.
+
 The public authoring declaration intentionally excludes runtime-only executor fields such as `defaultSessionDir`, `gitWorktreeSetupCache`, `durableBackend`, `durableScope`, and `onStageSession`.
 
 #### Choosing the durable backend
@@ -1341,11 +1401,10 @@ One process uses one workflow database: DBOS runs a single executor per process,
 ```ts
 import { run, WorkflowDurabilityRequiredError } from "@bastani/atomic/workflows";
 
-await run(helloWorld, { name: "Atomic" }, { adapters, durability: { mode: "memory" } });
+await run(helloWorld, { name: "Atomic" }, { durability: { mode: "memory" } });
 
 try {
   await run(helloWorld, { name: "Atomic" }, {
-    adapters,
     durability: { mode: "durable", systemDatabaseUrl: process.env.WORKFLOW_DATABASE_URL },
   });
 } catch (error) {
@@ -1451,12 +1510,23 @@ interface Store {
   removeRun(runId: string): boolean;
   recordNotice(notice: WorkflowNotice): void;
   ackNotice(id: string): boolean;
+  snapshot(): StoreSnapshot;
+  graphSnapshot(): StoreSnapshot;
+  subscribe(listener: (snapshot: StoreSnapshot) => void): () => void;
+}
+
+interface StoreSnapshot {
+  readonly runs: readonly RunSnapshot[];
+  readonly notices: readonly WorkflowNotice[];
+  readonly version: number;
 }
 ```
 
 `createStore()` returns an isolated workflow state store. `store` is the default singleton exported by the SDK authoring surface.
 
-This is the stable core exposed by the standalone authoring declaration. Atomic's runtime store also has graph, prompt, session, pause/resume, snapshot, and subscription methods used by embedded integrations; those richer runtime controls are not part of the lean workflow-package `Store` contract shown here.
+`snapshot()` returns a JSON copy of every run and notice; `version` increases on every store change. `graphSnapshot()` returns a cached, size-bounded copy for graph rendering that stays the same object until the store changes. `subscribe(listener)` calls `listener` with a fresh `snapshot()` after each change and returns an unsubscribe function.
+
+Atomic's runtime store also has prompt, session, and pause/resume methods used by embedded integrations; those controls are not part of the published `Store` contract shown here.
 
 ### `createCancellationRegistry()` / `cancellationRegistry`
 

package/docs/workflows/authoring.md

@@ -716,12 +716,16 @@ A `verified` result is cached durably, so a resumed run does not click again. A
 
 Workflow stages run chat language models. For a schema-backed decision, use the stage's `schema` and `structured_output` tool. It resolves an exact chat or registered classifier ID through the stage model registry and falls back on a classifier runtime failure. The direct `@bastani/pi-ai` examples below are for cases that need the classifier's probabilities or image generation from workflow TypeScript inside `ctx.tool(name, args, fn, { timeoutMs })`. Those calls are durable, replayable nodes. `model: "auto"` selects only chat language models for stage execution; `routerModel` may select a classifier for routing, but a classifier never executes a chat stage.
 
-Discovery loads a workflow file with the project that owns it as the module root. The host provides `@bastani/atomic/workflows` and `typebox`; other imports, including `@bastani/atomic` for `AuthStorage`, resolve from that project's `node_modules` in npm and standalone-binary installs alike. Install both libraries next to the workflow at the version `atomic --version` prints, because older releases have no `classify()` or `generateImages()`:
+Atomic provides `@bastani/atomic/workflows`, `typebox`, and the exact imports `@bastani/atomic`, `@bastani/pi-ai`, and `@bastani/pi-ai/providers/all` to workflow files. The latter three use the running CLI's module instances and version, including `AuthStorage`. These examples need no project-local package installation, in npm or standalone-binary installs. A project copy does not override these host-provided imports.
+
+For editor type checking, install the packages as dev dependencies at the version `atomic --version` prints. Atomic still runs these imports from the CLI, not from the project copy:
 
 ```sh
 npm install --save-dev @bastani/atomic@"$(atomic --version)" @bastani/pi-ai@"$(atomic --version)"
 ```
 
+Other imports, including unlisted deep package subpaths, still resolve from the owning project's `node_modules`. Install those dependencies next to the workflow. `/workflow reload` reloads workflow files and their relative imports, but does not replace the shared host modules; restart Atomic to use a different host version.
+
 Pass `AuthStorage.create()` to `builtinModels()` so classifier and image requests use credentials saved by Atomic's `/login` flows in `auth.json`; this is the recommended default for workflows running inside Atomic. Ambient provider environment variables such as `TYPESAFE_API_KEY` and `OPENROUTER_API_KEY` continue to work. Never read, print, or pass credential values in workflow state, prompts, or artifacts. Both operations resolve instead of throwing: check `stopReason === "stop"` before using a result, and forward the tool's `signal` so a quit or targeted abort cancels the request.
 
 #### Classify a request before choosing a stage
@@ -777,7 +781,7 @@ export default workflow({
 });
 ```
 
-The cached `{ choice, confidence }` is what a resumed run replays; the classifier is not asked again. For a consequential action, add policy checks or `ctx.ui.confirm(...)` before the side effect. Without the extra install, a schema-backed stage or task (`ctx.task(name, { schema, prompt })`, as the `classify-and-act` builtin does) can also make a validated decision. Its `structured_output` call can name a registered classifier or omit `model` and use the current chat model. A classifier probability is available only from a direct `classify()` call like the example above; a chat result does not supply one.
+The cached `{ choice, confidence }` is what a resumed run replays; the classifier is not asked again. For a consequential action, add policy checks or `ctx.ui.confirm(...)` before the side effect. A schema-backed stage or task (`ctx.task(name, { schema, prompt })`, as the `classify-and-act` builtin does) can also make a validated decision. Its `structured_output` call can name a registered classifier or omit `model` and use the current chat model. A classifier probability is available only from a direct `classify()` call like the example above; a chat result does not supply one.
 
 #### Generate an image artifact in a durable tool step