@bastani/atomic 0.9.28-alpha.5 → 0.9.29-alpha.1

package/docs/subagents/reference.md

@@ -38,7 +38,7 @@ subagent({
 })
 ```
 
-`work` is one of `computer_use`, `coding`, `code_review`, `codebase_lookup`, `research`, `business_workflow`, `math_science` or `writing`; `difficulty` is `trivial`, `easy`, `moderate`, `hard` or `very_hard`; `mistakeCost` is `negligible`, `low`, `moderate`, `high` or `severe`; `needsImages`, `longContext` (must hold a very large codebase or document set) and `latencySensitive` (a fast answer matters more than extra reasoning) are true or false. When listing candidates, prefer the user's subscription models over pay-per-token API models unless the user asked for API models or has none. To keep providers out of routing entirely, use the [`modelRouting`](/settings#modelrouting) setting. You do not need to attach eval records yourself.
+`work` is one of `computer_use`, `coding`, `code_review`, `codebase_lookup`, `research`, `business_workflow`, `math_science` or `writing`; `difficulty` is `trivial`, `easy`, `moderate`, `hard` or `very_hard`; `mistakeCost` is `negligible`, `low`, `moderate`, `high` or `severe`; `needsImages`, `longContext` (must hold a very large codebase or document set) and `latencySensitive` (a fast answer matters more than extra reasoning) are true or false. When listing candidates, prefer the user's subscription models over pay-per-token API models unless the user asked for API models or has none. To keep providers or models out of routing entirely, use the [`modelRouting`](/settings#modelrouting) setting. You do not need to attach eval records yourself.
 
 The agent's system prompt is not routing metadata. For a self-contained agent with no task, it remains the task fallback. The router weighs task-relevant evidence, cost, and latency rather than always choosing a benchmark winner or maximum effort. Benchmark measurement effort does not prescribe execution effort.
 
@@ -53,7 +53,7 @@ Saved classifier credentials do not change this order. Neither routing nor child
 
 Routing has no built-in wall-clock deadline. Slow decisions can finish; cancel the request to stop waiting. Independent provider and credential-preparation limits still apply. Chat routing gets an initial attempt plus three corrective retries for malformed or schema-invalid answers. A classifier routing failure switches to the current chat model instead of repeating the classifier request. A valid answer stops repairs.
 
-The result records a primary `{ model, effort }` and up to two ordered `fallbacks`, each with its own model and effort. Atomic ranks three distinct eligible provider/model IDs, or all available IDs when fewer than three qualify. It selects each rank from the remaining models, excluding all efforts of earlier choices. A supported `"off"` is distinct from `null`, which means no configurable reasoning. The catalog reflects configured authentication, not proof of valid credentials, quota, or entitlement.
+The result records a primary `{ model, effort }`, up to two ordered `fallbacks`, each with its own model and effort, and `candidates`, every model the router could choose from after the routing settings, constraints, and the task's image and long-context needs. Atomic ranks three distinct eligible provider/model IDs, or all available IDs when fewer than three qualify. It selects each rank from the remaining models, excluding all efforts of earlier choices. A supported `"off"` is distinct from `null`, which means no configurable reasoning. The catalog reflects configured authentication, not proof of valid credentials, quota, or entitlement.
 
 The child does not start if no candidates are eligible, availability changes, or cancellation occurs. A classifier provider failure, missing credentials, unsupported classify operation, size rejection, or malformed answer switches to the current chat model. Transient provider failures are retried up to three times first. The chat model gets its own output-repair allowance. If routing inference fails completely, or Atomic cannot pick a model itself (the task needs images and no eligible model reads them, `allowedModels` lists more models than one routing request holds (roughly 100), or `evals.md` is missing), the child runs on the current chat model instead of failing, but only when that model is available and satisfies every routing constraint (such as `allowedModels` and effort, cost, context and input limits). Otherwise the launch fails. Invalid inputs, conflicting constraints, cancellation and stale-catalog failures never trigger fallback. No partial decision can launch a child. These switches are silent unless `ATOMIC_MODEL_ROUTING_DEBUG=1` is set.
 
@@ -65,11 +65,11 @@ Choose a router provider permitted to receive the task and agent name/descriptio
 
 ### Hard model constraints
 
-For automatic routing, optional `modelConstraints` on a call, parallel task, or agent definition restricts eligible choices and execution fallbacks. All applicable restrictions must hold; a call cannot widen an agent's restrictions. Omit this object to use the full available catalog.
+For automatic routing, optional `modelConstraints` on a call, parallel task, or agent definition restricts eligible choices and execution fallbacks. All applicable restrictions must hold; a call cannot widen an agent's restrictions. Omit this object to use the full available catalog that your [`modelRouting`](/settings#modelrouting) settings allow.
 
 | Field | Meaning |
 | --- | --- |
-| `allowedModels` | Exact provider/model IDs permitted to receive the task |
+| `allowedModels` | Exact provider/model IDs permitted to receive the task. The [`modelRouting`](/settings#modelrouting) `allowedModels` and `excludedModels` settings still apply on top of this list |
 | `allowedProviders`, `excludedProviders` | Provider IDs whose models may or may never be used. On a call, setting either replaces the [`modelRouting`](/settings#modelrouting) provider settings for that call, so set them only when the user asks; in an agent definition they only narrow those settings |
 | `maxInputCost`, `maxOutputCost` | Maximum catalog price in USD per million input or output tokens, not a total spending cap |
 | `minContextWindow` | Minimum advertised context window in tokens |

package/docs/workflows/api-reference.md

@@ -546,7 +546,7 @@ Selects the primary stage model. String values can carry the reasoning suffix de
 
 Use `model: "auto"` for prompt-based selection of an execution model and supported effort before session admission. Omission and concrete models keep prior behavior. Shared chain/parallel defaults accept `auto`; each stage receives one decision. The router sees the final supplied prompt, including interpolated inputs and supplied task context, rather than only a stage name.
 
-`modelConstraints?: ModelConstraints` applies hard restrictions to auto selection and execution/compaction fallbacks. Fields are `allowedModels?: string[]`, `allowedProviders?: string[]`, `excludedProviders?: string[]`, `allowedEfforts?: (string | null)[]`, `maxInputCost?: number`, `maxOutputCost?: number`, `minContextWindow?: number`, and `requiredInputs?: ("text" | "image")[]`. Model IDs are exact provider/model IDs. Costs are catalog USD per million tokens including pricing tiers, not task budgets. Efforts are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `null` for nonreasoning models. Empty allowlists admit nothing. Inherited and stage restrictions all hold; a task override cannot widen shared restrictions. An authored `thinkingLevel` restricts auto selection to that supported effort.
+`modelConstraints?: ModelConstraints` applies hard restrictions to auto selection and execution/compaction fallbacks. Fields are `allowedModels?: string[]`, `allowedProviders?: string[]`, `excludedProviders?: string[]`, `allowedEfforts?: (string | null)[]`, `maxInputCost?: number`, `maxOutputCost?: number`, `minContextWindow?: number`, and `requiredInputs?: ("text" | "image")[]`. Model IDs are exact provider/model IDs. Costs are catalog USD per million tokens including pricing tiers, not task budgets. Efforts are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `null` for nonreasoning models. Empty allowlists admit nothing. Inherited and stage restrictions all hold; a task override cannot widen shared restrictions. An authored `thinkingLevel` restricts auto selection to that supported effort. The user's [`modelRouting.allowedModels` and `excludedModels`](/settings#modelrouting) settings also apply to every auto stage, including builtin stages that omit a model; `modelConstraints` cannot widen them, and a stage whose filters leave no eligible model fails before launch.
 
 An auto stage has no session until it receives prompt text. Model-dependent operations such as `compact()` or `cycleModel()` before that point report an error; call `prompt()` first or deliberately select a concrete model with `setModel()`. Session operations after admission keep their normal behavior.
 
@@ -569,7 +569,7 @@ Rejected credentials, unavailable models, and incompatible requests advance imme
 
 A stage that sets `model` or `fallbackModels` uses only the chain it declares. The `fallbackModels` list in `settings.json` and the chain of the session that launched the workflow never apply to it, so a provider failure cannot move the stage to a model or reasoning level outside the chain you declared. A stage that sets neither runs on the session's current model and keeps that session's fallback behavior.
 
-Explicit stage models can use numbered account providers such as `openai-1/gpt-5-mini:low` with credentials saved under `openai-1` in `auth.json`. They use the source provider's catalog and endpoint, but the account's own credentials; no alias entry in `models.json` or provider-registration extension is needed. The source provider and requested model must exist. `modelRouting.allowedProviders`, `modelRouting.excludedProviders`, and `routerModel` apply to `model: "auto"`, not to these pinned primary or fallback models.
+Explicit stage models can use numbered account providers such as `openai-1/gpt-5-mini:low` with credentials saved under `openai-1` in `auth.json`. They use the source provider's catalog and endpoint, but the account's own credentials; no alias entry in `models.json` or provider-registration extension is needed. The source provider and requested model must exist. `modelRouting` (`allowedProviders`, `excludedProviders`, `allowedModels`, `excludedModels`) and `routerModel` apply to `model: "auto"`, not to these pinned primary or fallback models.
 
 A same-candidate retry resumes the existing turn when the transcript ends in a message the agent can continue from. Otherwise, it re-sends the stage prompt. In either case, Atomic removes the failed provider error from the live transcript and delivers the prompt exactly once.
 
@@ -1023,7 +1023,7 @@ interface WorkflowTaskResult extends WorkflowTaskContext {
   readonly artifacts?: readonly WorkflowArtifact[];
   readonly model?: string;
   readonly thinkingLevel?: string;
-  readonly routerSelection?: { readonly model: string; readonly effort: string | null };
+  readonly routerSelection?: ModelRouterOutput;
   readonly attemptedModels?: readonly string[];
   readonly modelAttempts?: readonly WorkflowModelAttempt[];
   readonly warnings?: readonly string[];
@@ -1177,7 +1177,7 @@ interface StageSnapshot extends WorkflowSerializableObject {
 
 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.
+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: `model` and `effort`, ranked `fallbacks`, and `candidates`, the full IDs of every model the router could choose from after [`modelRouting`](/settings#modelrouting) and `modelConstraints` filtering. Selections recorded before `candidates` existed omit it. 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
 

package/docs/workflows/authoring.md

@@ -826,6 +826,10 @@ export default workflow({
 
 Hand the path to a later chat stage in its prompt. Review generated assets before publishing them or citing them as evidence: a generated image is not proof of a real-world state.
 
+To call OpenAI's Images API with your own OpenAI API key instead of OpenRouter, use an `openai-images` model, for example `models.getModelOfType("image", "openai-images", "gpt-image-2.5-flare")`. The provider also lists `gpt-image-2.5-sunburst`, `gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, and `gpt-image-1-mini`. It has no login of its own: it uses the key saved for `openai-api`, then a key saved for `openai`, then `OPENAI_API_KEY`. A ChatGPT sign-in cannot call the Images API, so with only that sign-in the call returns `stopReason: "error"` with `Provider is not configured: openai-images`. Text blocks become the prompt; add image blocks to `input` to edit them or use them as references. Pass `size`, `quality`, `n`, or `background` with the other options when you need them, for example `{ signal, size: "1024x1024", quality: "low" }`; each generated image is a separate image block in `result.output`.
+
+`builtinModels()` covers Atomic's built-in image providers. For another image backend, register its implementation for a new `api` ID with `registerImagesApiProvider({ api, generateImages })` from `@bastani/pi-ai/compat`, then call `generateImages(model, context, { apiKey, signal })` from the same entry point with a model whose `api` matches. That call dispatches on `model.api` and does not look up credentials, so take `apiKey` from your own configuration, such as an environment variable, and never put it in workflow state or outputs. `@bastani/pi-ai/compat` is not one of the host-provided imports, so install `@bastani/pi-ai` next to the workflow. To make an image backend available to codemode and extensions through the session's model registry instead, register a provider with `images`; see [Custom providers](/custom-provider#quick-reference).
+
 ### Workflow Composition
 
 Use workflow composition when a workflow calls a reusable user-defined workflow from the project or package, or a bundled builtin workflow, and consumes its outputs as a tracked boundary stage. Import the child definition with a normal TypeScript import, then pass it directly to `ctx.workflow(workflowDefinition, options)`. `ctx.workflow(...)` does not accept registry names, path objects, or string aliases.

package/docs/workflows/operations.md

@@ -4,7 +4,7 @@ Run and operate workflows from interactive chat or the workflow tool: identify r
 
 ## Automatic stage models
 
-For stages authored with `model: "auto"`, Atomic ranks up to three distinct eligible models before starting execution. It tries them in order, retaining each selected effort, before remaining configured fallbacks and the current chat model. Duplicate model IDs are skipped. The primary model/effort and ordered `fallbacks` are retained as `routerSelection`, independently of the actual `model`, `thinkingLevel`, and attempts. Remaining unsuffixed fallbacks inherit the primary effort; explicit suffixes retain their own effort. Every automatic fallback must satisfy the stage's hard constraints.
+For stages authored with `model: "auto"`, Atomic ranks up to three distinct eligible models before starting execution. It tries them in order, retaining each selected effort, before remaining configured fallbacks and the current chat model. Duplicate model IDs are skipped. The primary model/effort and ordered `fallbacks` are retained as `routerSelection`, independently of the actual `model`, `thinkingLevel`, and attempts, together with `candidates`, every model the router could choose from after filtering. Remaining unsuffixed fallbacks inherit the primary effort; explicit suffixes retain their own effort. Every automatic fallback must satisfy the stage's hard constraints and the [`modelRouting`](/settings#modelrouting) settings.
 
 Model selection uses the actual stage prompt, stage name, hard constraints, eligible model catalog, and compact dated evaluation records, not full human guides. Stage system and appended system prompts are not sent to the model router. Put requirements that should influence model selection in the stage prompt; the execution session still receives its configured system prompts.
 

package/npm-shrinkwrap.json

@@ -1,16 +1,16 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.28-alpha.5",
+	"version": "0.9.29-alpha.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.28-alpha.5",
+			"version": "0.9.29-alpha.1",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.28-alpha.5",
-				"@bastani/pi-ai": "0.9.28-alpha.5",
+				"@bastani/atomic-natives": "0.9.29-alpha.1",
+				"@bastani/pi-ai": "0.9.29-alpha.1",
 				"@dbos-inc/dbos-sdk": "4.25.14",
 				"@earendil-works/pi-agent-core": "1.1.0",
 				"@earendil-works/pi-client": "1.1.0",
@@ -432,18 +432,18 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-darwin-x64": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-linux-arm64-musl": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-linux-x64-musl": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.28-alpha.5",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.28-alpha.5"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-darwin-x64": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-linux-arm64-musl": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-linux-x64-musl": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.29-alpha.1",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.29-alpha.1"
 			},
 			"engines": {
 				"bun": ">=1.4.2",
@@ -451,8 +451,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -463,8 +463,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -475,8 +475,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -490,8 +490,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-musl": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -505,8 +505,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -520,8 +520,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-musl": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -535,8 +535,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -547,8 +547,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -559,8 +559,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/pi-ai": {
-			"version": "0.9.28-alpha.5",
-			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.28-alpha.5.tgz",
+			"version": "0.9.29-alpha.1",
+			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.29-alpha.1.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.129.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.28-alpha.5",
+  "version": "0.9.29-alpha.1",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -80,8 +80,8 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.28-alpha.5",
-    "@bastani/pi-ai": "0.9.28-alpha.5",
+    "@bastani/atomic-natives": "0.9.29-alpha.1",
+    "@bastani/pi-ai": "0.9.29-alpha.1",
     "@dbos-inc/dbos-sdk": "4.25.14",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-client": "1.1.0",