@bastani/atomic 0.9.16-alpha.7 → 0.9.16-alpha.9

package/docs/intercom.md

@@ -34,7 +34,8 @@ Atomic bundles `@bastani/intercom`, a first-party extension for direct 1:1 messa
 - [How Connection Works](#how-connection-works)
 - [The intercom Tool](#the-intercom-tool)
   - [Actions](#actions)
-  - [Targeting Sessions](#targeting-sessions)
+  - [Targeting Sessions and Pending Workflow Stages](#targeting-sessions-and-pending-workflow-stages)
+  - [Deferred delivery to pending stages](#deferred-delivery-to-pending-stages)
   - [send vs ask vs reply](#send-vs-ask-vs-reply)
   - [Attachments](#attachments)
 - [Coordination Patterns](#coordination-patterns)
@@ -138,7 +139,7 @@ Name sessions with `/name` so they can target each other (for example `/name pla
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `action` | string | `"list"`, `"join"`, `"leave"`, `"send"`, `"ask"`, `"reply"`, `"pending"`, or `"status"` |
-| `to` | string | Exact session name or exact full session ID (for send/ask, or targeted reply) |
+| `to` | string | Exact session name/full session ID, or `<runId>:<stageKey>` for `send` to a not-yet-started workflow stage (for send/ask, or targeted reply) |
 | `message` | string | Message text (for send/ask/reply) |
 | `attachments` | array | Optional `file`, `snippet`, or `context` attachments |
 | `replyTo` | string | Optional message ID for threading or replying to an `ask` |
@@ -151,8 +152,8 @@ Name sessions with `/name` so they can target each other (for example `/name pla
 | `join` | Moves the session into a trimmed named group and creates it if needed. The action waits for broker acknowledgement before changing local inheritance state. `default` is the shared group; `true` and `auto` are reserved for subagent auto-groups. |
 | `leave` | Returns the session to its resolved home group from startup. It takes no `group` parameter. |
 | `list` | Returns the current session plus other active intercom-connected sessions with name, full session ID, working directory, model, and live status (`idle`, `thinking`, or `tool:<name>`, derived from lifecycle events). Every displayed full session ID is a valid target. |
-| `send` | Fire-and-forget delivery. Requires `to` and `message`; returns delivery confirmation or the delivery-failure reason. Cannot message the current session. |
-| `ask` | Sends a message and blocks until the recipient replies (10-minute timeout). A recipient disconnect after delivery fails the wait promptly; the timeout remains the backstop for a connected but unresponsive recipient. From a foreground child to its resolved launching parent, it instead ends the child and returns a fresh-subagent handoff through the parent `subagent` call. |
+| `send` | Fire-and-forget delivery through ordinary Intercom. A live workflow-stage session receives the message immediately and returns `delivered`. A known workflow stage whose session has not initialized is addressed as `<runId>:<stageKey>`; Atomic persists the message and returns the distinct `queued` result with its FIFO position. Unknown stage identities retain the ordinary unknown-target failure. Requires `to` and `message`; cannot message the current session. |
+| `ask` | Sends a message and blocks until a live recipient replies (10-minute timeout). An ask to a known workflow stage whose session has not initialized is refused with `pending_stage_ask_unsupported` and recommends ordinary `send`; holding a waiter until a stage eventually starts would be unbounded. A live recipient disconnect fails promptly. From a foreground child to its launching parent, the existing fresh-subagent handoff path remains unchanged. |
 | `reply` | Replies to the intercom-triggered message of the current turn; otherwise falls back to the single unresolved inbound ask. With multiple pending asks, pass `to` or inspect with `pending` first. |
 | `pending` | Lists unresolved inbound asks with sender, message ID, elapsed time, and a short preview. |
 | `status` | Shows connection status, session ID, current group, and the count of active sessions in that group. A `group` filter remains a read-only peek. |
@@ -167,9 +168,17 @@ The broker updates presence in place and sends a `session_left` event to the old
 
 Sent and received messages are recorded in session history as `intercom_sent` / `intercom_received` entries.
 
-### Targeting Sessions
+### Targeting Sessions and Pending Workflow Stages
 
-Target lookup accepts only an exact full session ID or an exact case-insensitive session name. Targeting is also **group-scoped** — see [Groups](#groups) below.
+Live-session lookup accepts only an exact full session ID or an exact case-insensitive session name. Ordinary `send` also accepts the exact `<runId>:<stageKey>` identity of a known workflow stage whose session has not initialized. The run ID is the full UUID, and the authored stage key is case-sensitive. Unknown runs and stages retain the ordinary unknown-target failure. Targeting is **group-scoped** — see [Groups](#groups) below.
+
+### Deferred delivery to pending stages
+
+Send material updates through Intercom to every affected workflow stage, including stages that have not started. Atomic queues messages for known pending stages and delivers them when their sessions initialize. A deferred send returns `queued`, including its FIFO position, rather than claiming the message was `delivered`; live delivery remains immediate and returns `delivered`.
+
+The workflows extension persists up to **50 queued messages per exact run/stage key** with workflow state. Messages survive resume/replay and broker restart, and logical message IDs prevent redelivery across stage-attempt restarts. When the stage session initializes, it receives the FIFO entries through the ordinary Intercom inbound path before its first model turn, under the heading **Messages received before you started**, with sender identity and `Sent:` timestamps visible separately from the task prompt.
+
+Only a session in the workflow run's Intercom group can queue a message; a cross-group attempt is refused with `Target workflow run is in a different intercom group`. The 51st queued message is refused with `Pending stage message queue is full (limit 50)` rather than evicting an earlier entry. If the destination is skipped, the run is cancelled, or the stage becomes terminal before its session initializes, Atomic marks the message undeliverable and sends the correlated failure notification when acknowledgment was requested. Blocking `ask` is deliberately unsupported before initialization: use ordinary `send`, because a stage may start much later or never start.
 
 ### Groups
 

package/docs/packages.md

@@ -177,7 +177,7 @@ If no app manifest (`atomic`, or legacy `pi`) is present, Atomic auto-discovers
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
 - `prompts/` loads `.md` files
 - `themes/` loads `.json` files
-- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files should `import { workflow } from "@bastani/workflows"`, import `Type` from `typebox`, and export the `workflow({ ... })` result. TypeScript package authors do not need a hand-authored `.d.ts`, a `declare module` shim, or a `tsconfig` `paths` alias for the SDK import — the SDK types ship with `@bastani/atomic`. A package that also imports `@bastani/atomic` picks them up automatically; a pure workflow-only package adds one opt-in line (`compilerOptions.types: ["@bastani/atomic/workflows/ambient"]` or a `/// <reference types="@bastani/atomic/workflows/ambient" />` directive). See the workflow SDK typing guidance under Programmatic Usage in the workflows guide.
+- `workflows/` loads workflow SDK files (`.ts`, `.js`, `.mjs`, `.cjs`); `workflow/` is also accepted as a singular alias. Workflow files import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export the definition returned by `workflow({ ... })`. TypeScript resolves the published `@bastani/atomic/workflows` specifier through the `@bastani/atomic` package. Atomic resolves that workflow specifier to its in-memory SDK when it loads the workflow at runtime. See Programmatic Usage in the workflows guide.
 
 When a package manifest exists, declared resource arrays normally define what loads. Workflows are the exception: if `atomic.workflows` / legacy `pi.workflows` is omitted, Atomic still checks conventional `workflows/` and `workflow/` directories.
 
@@ -187,7 +187,7 @@ Third-party runtime dependencies belong in `dependencies` in `package.json`. Dep
 
 Atomic bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@bastani/pi-ai`, `@earendil-works/pi-agent-core`, `@bastani/atomic`, `@earendil-works/pi-tui`, `typebox`.
 
-Workflow packages should author workflow files with `import { workflow } from "@bastani/workflows"`, `import { Type } from "typebox"`, and export definitions produced by `workflow({ ... })`. Do not use the removed `runWorkflow` object-form API, and do not hand-roll objects with `__piWorkflow: true`; discovery accepts only definitions minted by `workflow({ ... })`. `@bastani/workflows` is not a separate npm package: its types resolve through `@bastani/atomic`, so list `@bastani/atomic` and `typebox` in `peerDependencies`. A pure workflow-only package also adds the one-line ambient opt-in noted above; a package that imports `@bastani/atomic` elsewhere picks the types up automatically.
+Workflow packages import `workflow` from `@bastani/atomic/workflows`, import `Type` from `typebox`, and export definitions returned by `workflow({ ... })`. List `@bastani/atomic` and `typebox` in `peerDependencies` so package consumers receive the workflow SDK and schema library.
 
 Package-authored workflows should follow the same guiding principles as project workflows mentioned in docs/workflows.md.
 

package/docs/providers.md

@@ -49,11 +49,16 @@ Checks refresh expired OAuth credentials by default through the ordinary locked
 
 If the Codex backend reports that an OAuth/auth token was invalidated or revoked, retry the request once in case the rejection is transient. If it persists, run `/logout` and select **OpenAI ChatGPT Plus/Pro**, then run `/login`, authenticate that subscription again, and retry the request. Atomic displays these recovery steps with the provider error; it does not automatically delete the stored credential or repeatedly retry a definitive authentication rejection.
 
-### Codex Fast Mode
+### Fast mode
 
-Run `/fast` in interactive mode to enable OpenAI priority service tier separately for normal chat and workflow-stage sessions. The command is shown when the current model scope includes a supported `openai/*` or `openai-codex/*` model. A resolved provider alias also qualifies when it uses the shared `openai-codex-responses` transport. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use the workflow setting, not the chat setting. Each fallback, retry, compaction-planner, and branch-summary request is evaluated against its effective model, so an eligible fallback gets the tier and an ineligible provider does not. When enabled for the active supported model, the UI appends `fast` after the model name in the chat footer, workflow stage model labels, and stage-launched subagent results. Fast mode intentionally does not apply to `github-copilot/*`, Azure OpenAI, OpenRouter, or generic OpenAI-compatible providers. Use workflow fast mode deliberately because parallel workflow fan-out can multiply priority-tier usage.
+Run `/fast` in interactive mode to configure fast mode separately for normal chat and workflow-stage sessions. Atomic supports two provider paths:
 
-The shared ChatGPT Codex transport sends the fast routing contract only after the final request payload contains `service_tier: priority`: `originator: codex_cli_rs` plus `x-codex-routing-hint: model=<effective-model>;tier=priority` on both HTTP/SSE and WebSocket transports. The same rule covers the stock provider, renamed providers, credential-resolved endpoints, and monitoring proxies that retain `api: "openai-codex-responses"`. WebSocket fallback, reconnect, and HTTP retry attempts reuse that identity; a final model or tier change drops a cached socket before reuse. Requests to the standard OpenAI API send only the tier. When Fast Mode is off, or a request hook changes the final tier away from `priority`, Atomic keeps the normal `originator: pi` identity and sends no routing hint.
+- OpenAI `openai/*` and `openai-codex/*` models use the priority service tier. A resolved provider alias also qualifies when it uses the shared `openai-codex-responses` transport.
+- GitHub Copilot models qualify when the OAuth model catalog for the signed-in account advertises a fast variant. Atomic uses that variant only for the outgoing request, so it does not appear as a separate choice in `/model`. Copilot fast mode requires the account catalog metadata obtained through `/login`; a raw `COPILOT_GITHUB_TOKEN` does not provide that metadata.
+
+Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use the workflow setting, not the chat setting. Atomic checks each fallback, retry, compaction-planner, and branch-summary request against its effective model. An eligible fallback uses fast mode, while an unsupported model keeps its normal request behavior. The UI appends `fast` after the model name in the chat footer, workflow stage model labels, and stage-launched subagent results. Fast mode does not apply to Azure OpenAI, OpenRouter, or generic OpenAI-compatible providers. Enable it deliberately for workflows because parallel fan-out can multiply provider usage.
+
+For the shared ChatGPT Codex transport, Atomic sends the fast routing contract only after the final request payload contains `service_tier: priority`: `originator: codex_cli_rs` plus `x-codex-routing-hint: model=<effective-model>;tier=priority` on both HTTP/SSE and WebSocket transports. The same rule covers the stock provider, renamed providers, credential-resolved endpoints, and monitoring proxies that retain `api: "openai-codex-responses"`. WebSocket fallback, reconnect, and HTTP retry attempts reuse that identity; a final model or tier change drops a cached socket before reuse. Requests to the standard OpenAI API send only the tier. When fast mode is off, or a request hook changes the final tier away from `priority`, Atomic keeps the normal `originator: pi` identity and sends no routing hint.
 
 ### Claude Pro/Max
 

package/docs/quickstart.md

@@ -163,7 +163,7 @@ On a fresh install with no prior Atomic startup state, Atomic shows a one-time f
 
 Once Atomic starts, default to a workflow for non-trivial work and for requests with inherent structure plus a verifiable objective. Implementation, build, debugging, bug fixes, migrations, features, scoped multi-file edits, validation/review work, and loop-shaped requests are workflow candidates; reserve direct chat for tiny deterministic low-risk answers or edits where tracking clearly adds more overhead than value.
 
-Workflow-first is not builtin-only or monolithic. Atomic can discover and run named builtin, project, user, and package workflows; author a rich custom TypeScript `workflow({...})` inline; and compositionally import reusable workflow definitions—including builtins from `@bastani/workflows/builtin`—into parent workflows with `ctx.workflow(...)`. Nested children can nest again within `maxDepth`, so custom graphs can combine proven research, implementation, design, verification, and approval workflows instead of copying them. They can also classify and branch, dynamically fan out and synthesize artifacts, run adversarial repair cycles, tournament-rank candidates, and loop until checks pass with explicit bounds.
+Workflow-first is not builtin-only or monolithic. Atomic can discover and run named builtin, project, user, and package workflows; author a rich custom TypeScript `workflow({...})` inline; and compositionally import reusable workflow definitions—including builtins from `@bastani/atomic/workflows/builtin`—into parent workflows with `ctx.workflow(...)`. Nested children can nest again within `maxDepth`, so custom graphs can combine proven research, implementation, design, verification, and approval workflows instead of copying them. They can also classify and branch, dynamically fan out and synthesize artifacts, run adversarial repair cycles, tournament-rank candidates, and loop until checks pass with explicit bounds.
 
 Atomic turns repeatable engineering loops into executable stages with inspectable evidence instead of relying on a markdown checklist the model may or may not follow.
 
@@ -269,7 +269,7 @@ Atomic will:
 - run `/workflow reload` so the generated workflow is rediscovered and can be launched with `/workflow <name>`,
 - then report the generated workflow folder so you can inspect the code it wrote, using `Custom workflow created. You can inspect its code at: <workflow-folder-path>` (for example, `.atomic/workflows/`); Atomic does this only for newly created custom workflows, never builtin or pre-existing workflows.
 
-The same plain-chat approach works for editing or hardening an existing workflow. For the full authoring reference, see [Workflows](/workflows), including composition with user-defined workflows and all nine builtins from `@bastani/workflows/builtin`.
+The same plain-chat approach works for editing or hardening an existing workflow. For the full authoring reference, see [Workflows](/workflows), including composition with user-defined workflows and all nine builtins from `@bastani/atomic/workflows/builtin`.
 
 ### Default tools and prompts
 

package/docs/rpc.md

@@ -243,12 +243,17 @@ Messages are `AgentMessage` objects (see [Types](#types)).
 
 #### set_model
 
-Switch to a specific model.
+Switch to a specific model. Omit `persist` (or set it false) to change only the current session. Set `"persist": true` to also write `defaultProvider`/`defaultModel` in settings, matching Ctrl+S in the interactive `/model` picker.
 
 ```json
 {"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}
 ```
 
+Persist as the startup default:
+```json
+{"type": "set_model", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514", "persist": true}
+```
+
 Response contains the full [Model](#model) object:
 ```json
 {
@@ -261,7 +266,7 @@ Response contains the full [Model](#model) object:
 
 #### cycle_model
 
-Cycle to the next available model. Returns `null` when fewer than two authenticated models are available in the active scope or catalog. When an unsupported saved default is blocking prompts, a successful cycle that returns a different model clears that condition; a `null` or unchanged result does not.
+Cycle to the next available model. Returns `null` when fewer than two authenticated models are available in the active scope or catalog. When an unsupported saved default is blocking prompts, a successful cycle that returns a different model clears that condition; a `null` or unchanged result does not. Set `"persist": true` to also write the cycled model as the startup default.
 
 ```json
 {"type": "cycle_model"}
@@ -344,21 +349,33 @@ Response:
 
 #### set_thinking_level
 
-Set the reasoning/thinking level for models that support it.
+Set the reasoning/thinking level for models that support it. Omit `persist` (or set it false) to change only the current session. Set `"persist": true` to also save the startup thinking default, matching Ctrl+S in the interactive `/thinking` picker. When a model is active, that writes the per-model override; otherwise it writes `defaultThinkingLevel`.
 
 ```json
 {"type": "set_thinking_level", "level": "high"}
 ```
 
+Persist as the startup default:
+```json
+{"type": "set_thinking_level", "level": "high", "persist": true}
+```
+
 Levels: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`.
 
 `xhigh` and `max` are available only when the active model's capability mapping supports them; unsupported levels are clamped by the session model controls.
 
-Response:
+Response may omit `data` for compatibility with older clients:
 ```json
 {"type": "response", "command": "set_thinking_level", "success": true}
 ```
 
+Current engines include the effective level after capability clamping and, when a model is active, the provider/model the engine persisted against:
+```json
+{"type": "response", "command": "set_thinking_level", "success": true, "data": {"level": "high", "provider": "anthropic", "modelId": "claude-sonnet-4-20250514"}}
+```
+
+Isolated interactive hosts must apply a persisted thinking default using that ACK target, not the host session model at callback time. A later `model_changed` event must not re-key the saved override. A later `thinking_level_changed` event must keep the host session's effective level even if an older ACK settles afterward. `RpcClient.setThinkingLevel(level)` stays one-argument `Promise<void>`; isolated persist reads the ACK through an internal client path.
+
 #### cycle_thinking_level
 
 Cycle through available thinking levels. Returns `null` data if model doesn't support thinking.

package/docs/settings.md

@@ -85,14 +85,16 @@ Fallback attempts are visible as model changes in the session transcript and as
 
 `enabledModels` is separate: it only controls the interactive Ctrl+P model cycle list and is not used as an implicit fallback chain.
 
-### Codex Fast Mode
+### Fast mode
 
-Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode to supported `openai/*` and `openai-codex/*` providers and to provider aliases that use the shared `openai-codex-responses` transport, not `github-copilot/*` or generic OpenAI-compatible providers. Chat and workflow-stage scopes are independent. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use `codexFastMode.workflow`; normal-chat subagents use `codexFastMode.chat`. Fast mode is resolved again for each fallback model, so the marker and priority tier follow the effective provider. When fast mode is active for the current supported model, Atomic shows `fast` after the model name in the chat footer, workflow stage model labels, and subagent results. Enable the workflow scope deliberately for broad fan-outs because each eligible stage can consume priority-tier requests.
+Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode to supported `openai/*` and `openai-codex/*` providers, provider aliases that use the shared `openai-codex-responses` transport, and GitHub Copilot models whose OAuth account catalog advertises a fast variant. OpenAI requests use the priority service tier. GitHub Copilot requests use the account-supported fast variant without adding the OpenAI service-tier field. Fast mode does not apply to Azure OpenAI, OpenRouter, or generic OpenAI-compatible providers.
+
+Chat and workflow-stage scopes are independent. Workflow stages, nested `ctx.workflow(...)` stages, and subagents launched by those stages use `codexFastMode.workflow`; normal-chat subagents use `codexFastMode.chat`. Atomic resolves eligibility again for each fallback model, so the marker and request behavior follow the effective provider and model. When fast mode is active, Atomic shows `fast` after the model name in the chat footer, workflow stage model labels, and subagent results. Enable the workflow scope deliberately for broad fan-outs because each eligible stage can consume fast provider requests. The `codexFastMode` setting name remains for compatibility.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `codexFastMode.chat` | boolean | `false` | Use OpenAI priority service tier for supported normal chat requests |
-| `codexFastMode.workflow` | boolean | `false` | Use OpenAI priority service tier for supported workflow-stage requests |
+| `codexFastMode.chat` | boolean | `false` | Enable fast mode for supported normal chat models |
+| `codexFastMode.workflow` | boolean | `false` | Enable fast mode for supported workflow-stage models |
 
 ```json
 {

package/docs/subagents.md

@@ -128,7 +128,7 @@ Status and interrupt use the live Rust registry and status watch; `list` and `ge
 
 Inside workflow stages, completion delivery observes the stage generation boundary. A completion received before the boundary closes is queued through the stage AgentSession and processed before the stage publishes its terminal snapshot. A completion that arrives after close is routed once to the parent/main chat and cannot reopen or append to the completed stage transcript. Explicit post-mortem stage chat is still available separately.
 
-Live progress and completed results show each step's resolved model, effective reasoning level, and applied Codex fast-mode marker, including after a model fallback; parallel steps keep their metadata separate.
+Live progress and completed results show each step's resolved model, effective reasoning level, and applied fast-mode marker, including after a model fallback; parallel steps keep their metadata separate.
 
 ## Orchestrator model and group policy
 

package/docs/usage.md

@@ -45,7 +45,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/model` | Switch models; Ctrl+S in the picker saves the startup default |
 | `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
 | `/scoped-models` | Enable/disable models for CTRL+P cycling |
-| `/fast` | Toggle Codex fast mode for chat and workflow stages when supported OpenAI or shared ChatGPT Codex transport models are available |
+| `/fast` | Configure fast mode for chat and workflow stages when supported OpenAI or GitHub Copilot models are available |
 | `/workflow` | List/run workflows; manage runs (connect/inspect/pause/interrupt/quit/resume); reload workflow resources |
 | `/settings` | Theme, message delivery, transport, and other preferences |
 | `/resume` | Pick from previous sessions |