@bastani/atomic 0.9.12 → 0.9.13-alpha.2

package/examples/extensions/modal-editor.ts

@@ -28,21 +28,19 @@ const NORMAL_KEYS: Record<string, string | null> = {
 class ModalEditor extends CustomEditor {
 	private mode: "normal" | "insert" = "insert";
 
-	handleInput(data: string): void {
-		// Escape toggles to normal mode, or passes through for app handling
+	handleInput(data: string): boolean {
+		// Escape toggles to normal, or passes through for app handling
 		if (matchesKey(data, "escape")) {
 			if (this.mode === "insert") {
 				this.mode = "normal";
-			} else {
-				super.handleInput(data); // abort agent, etc.
+				return true;
 			}
-			return;
+			return super.handleInput(data); // abort agent, etc.
 		}
 
 		// Insert mode: pass everything through
 		if (this.mode === "insert") {
-			super.handleInput(data);
-			return;
+			return super.handleInput(data);
 		}
 
 		// Normal mode: check mapped keys
@@ -56,12 +54,12 @@ class ModalEditor extends CustomEditor {
 			} else if (seq) {
 				super.handleInput(seq);
 			}
-			return;
+			return true;
 		}
 
 		// Pass control sequences (ctrl+c, etc.) to super, ignore printable chars
-		if (data.length === 1 && data.charCodeAt(0) >= 32) return;
-		super.handleInput(data);
+		if (data.length === 1 && data.charCodeAt(0) >= 32) return false;
+		return super.handleInput(data);
 	}
 
 	render(width: number): string[] {

package/examples/extensions/rainbow-editor.ts

@@ -64,13 +64,14 @@ class RainbowEditor extends CustomEditor {
 		}
 	}
 
-	handleInput(data: string): void {
-		super.handleInput(data);
+	handleInput(data: string): boolean {
+		const handled = super.handleInput(data);
 		if (this.hasUltrathink()) {
 			this.startAnimation();
 		} else {
 			this.stopAnimation();
 		}
+		return handled;
 	}
 
 	render(width: number): string[] {

package/examples/extensions/subagent/README.md

@@ -1,6 +1,6 @@
 # Subagent Example
 
-Delegate tasks to specialized subagents with isolated context windows.
+Delegate tasks to specialized agents with isolated context windows.
 
 ## Features
 
@@ -18,15 +18,11 @@ subagent/
 ├── README.md            # This file
 ├── index.ts             # The extension (entry point)
 ├── agents.ts            # Agent discovery logic
-├── agents/              # Sample agent definitions
-│   ├── scout.md         # Fast recon, returns compressed context
-│   ├── planner.md       # Creates implementation plans
-│   ├── reviewer.md      # Code review
-│   └── worker.md        # General-purpose (full capabilities)
-└── prompts/             # Workflow presets (prompt templates)
-    ├── implement.md     # scout -> planner -> worker
-    ├── scout-and-plan.md    # scout -> planner (no implementation)
-    └── implement-and-review.md  # worker -> reviewer -> worker
+└── agents/              # Sample agent definitions
+    ├── scout.md         # Fast recon, returns compressed context
+    ├── planner.md       # Creates implementation plans
+    ├── reviewer.md      # Code review
+    └── worker.md        # General-purpose (full capabilities)
 ```
 
 ## Installation
@@ -34,22 +30,14 @@ subagent/
 From the repository root, symlink the files:
 
 ```bash
-# Symlink the extension (must be in a subdirectory with index.ts)
 mkdir -p ~/.atomic/agent/extensions/subagent
 ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/index.ts" ~/.atomic/agent/extensions/subagent/index.ts
 ln -sf "$(pwd)/packages/coding-agent/examples/extensions/subagent/agents.ts" ~/.atomic/agent/extensions/subagent/agents.ts
 
-# Symlink agents
 mkdir -p ~/.atomic/agent/agents
 for f in packages/coding-agent/examples/extensions/subagent/agents/*.md; do
   ln -sf "$(pwd)/$f" ~/.atomic/agent/agents/$(basename "$f")
 done
-
-# Symlink workflow prompts
-mkdir -p ~/.atomic/agent/prompts
-for f in packages/coding-agent/examples/extensions/subagent/prompts/*.md; do
-  ln -sf "$(pwd)/$f" ~/.atomic/agent/prompts/$(basename "$f")
-done
 ```
 
 ## Security Model
@@ -67,25 +55,15 @@ When running interactively, the tool prompts for confirmation before running pro
 ## Usage
 
 ### Single agent
+
 ```
 Use scout to find all authentication code
 ```
 
 ### Parallel execution
-```
-Run 2 scouts in parallel: one to find models, one to find providers
-```
-
-### Chained workflow
-```
-Use a chain: first have scout find the read tool, then have planner suggest improvements
-```
 
-### Workflow prompts
 ```
-/implement add Redis caching to the session store
-/scout-and-plan refactor auth to support OAuth
-/implement-and-review add input validation to API endpoints
+Run 2 scouts in parallel: one to find models, one to find providers
 ```
 
 ## Tool Modes
@@ -94,27 +72,30 @@ Use a chain: first have scout find the read tool, then have planner suggest impr
 |------|-----------|-------------|
 | Single | `{ agent, task }` | One agent, one task |
 | Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 50, 4 concurrent) |
-| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
 
 ## Output Display
 
 **Collapsed view** (default):
+
 - Status icon (✓/✗/⏳) and agent name
 - Last 5-10 items (tool calls and text)
 - Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
 
 **Expanded view** (Ctrl+O):
+
 - Full task text
 - All tool calls with formatted arguments
 - Final output rendered as Markdown
-- Per-task usage (for chain/parallel)
+- Per-task usage
 
 **Parallel mode streaming**:
+
 - Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
 - Updates as each task makes progress
 - Shows "2/3 done, 1 running" status
 
 **Tool call formatting** (mimics built-in tools):
+
 - `$ command` for bash
 - `read ~/path:1-10` for read
 - `search /pattern/ in ~/path` for search
@@ -136,6 +117,7 @@ System prompt for the agent goes here.
 ```
 
 **Locations:**
+
 - `~/.atomic/agent/agents/*.md` - User-level (always loaded)
 - `.atomic/agents/*.md` - Project-level (legacy `.pi/agents/*.md` also works) (only with `agentScope: "project"` or `"both"`)
 
@@ -150,20 +132,9 @@ Project agents override user agents with the same name when `agentScope: "both"`
 | `reviewer` | Code review | Sonnet | read, search, find, ls, bash |
 | `worker` | General-purpose | Sonnet | (all default) |
 
-## Workflow Prompts
-
-| Prompt | Flow |
-|--------|------|
-| `/implement <query>` | scout → planner → worker |
-| `/scout-and-plan <query>` | scout → planner |
-| `/implement-and-review <query>` | worker → reviewer → worker |
-
-## Error Handling
+## Workflow prompts
 
-- **Exit code != 0**: Tool returns error with stderr/output
-- **stopReason "error"**: LLM error propagated with error message
-- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
-- **Chain mode**: Stops at first failing step, reports which step failed
+This example focuses on direct single-agent and independent parallel delegation. Use the main Atomic workflow tools when a task needs ordered stages, review loops, or durable handoffs.
 
 ## Limitations
 

package/examples/extensions/subagent/index.ts

@@ -4,12 +4,11 @@
  * Spawns a separate `atomic` process for each subagent invocation,
  * giving it an isolated context window.
  *
- * Supports three modes:
+ * Supports two modes:
  *   - Single: { agent: "name", task: "..." }
  *   - Parallel: { tasks: [{ agent: "name", task: "..." }, ...] }
- *   - Chain: { chain: [{ agent: "name", task: "... {previous} ..." }, ...] }
  *
- * Uses JSON mode to capture structured output from subagents.
+ * Supports direct single-agent and parallel delegation.
  */
 
 import * as path from "node:path";
@@ -32,7 +31,7 @@ export default function (pi: ExtensionAPI) {
 		label: "Subagent",
 		description: [
 			"Delegate tasks to specialized subagents with isolated context.",
-			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
+			"Modes: single (agent + task) or parallel (tasks array).",
 			`Default agent scope is "user" (from ${path.join(getAgentDir(), "agents")}).`,
 			`To enable project-local agents in ${CONFIG_DIR_NAME}/agents (legacy .pi/agents also works), set agentScope: "both" (or "project").`,
 		].join(" "),
@@ -44,13 +43,12 @@ export default function (pi: ExtensionAPI) {
 			const agents = discovery.agents;
 			const confirmProjectAgents = params.confirmProjectAgents ?? true;
 
-			const hasChain = (params.chain?.length ?? 0) > 0;
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
 			const hasSingle = Boolean(params.agent && params.task);
-			const modeCount = Number(hasChain) + Number(hasTasks) + Number(hasSingle);
+			const modeCount = Number(hasTasks) + Number(hasSingle);
 
 			const makeDetails =
-				(mode: "single" | "parallel" | "chain") =>
+				(mode: "single" | "parallel") =>
 				(results: SingleResult[]): SubagentDetails => ({
 					mode,
 					agentScope,
@@ -73,7 +71,6 @@ export default function (pi: ExtensionAPI) {
 
 			if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
 				const requestedAgentNames = new Set<string>();
-				if (params.chain) for (const step of params.chain) requestedAgentNames.add(step.agent);
 				if (params.tasks) for (const t of params.tasks) requestedAgentNames.add(t.agent);
 				if (params.agent) requestedAgentNames.add(params.agent);
 
@@ -96,76 +93,11 @@ export default function (pi: ExtensionAPI) {
 									text: "Canceled: project-local agents not approved.",
 								},
 							],
-							details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+							details: makeDetails(hasTasks ? "parallel" : "single")([]),
 						};
 				}
 			}
 
-			if (params.chain && params.chain.length > 0) {
-				const results: SingleResult[] = [];
-				let previousOutput = "";
-
-				for (let i = 0; i < params.chain.length; i++) {
-					const step = params.chain[i];
-					const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
-
-					// Create update callback that includes all previous results
-					const chainUpdate: OnUpdateCallback | undefined = onUpdate
-						? (partial) => {
-								// Combine completed results with current streaming result
-								const currentResult = partial.details?.results[0];
-								if (currentResult) {
-									const allResults = [...results, currentResult];
-									onUpdate({
-										content: partial.content,
-										details: makeDetails("chain")(allResults),
-									});
-								}
-							}
-						: undefined;
-
-					const result = await runSingleAgent(
-						ctx.cwd,
-						agents,
-						step.agent,
-						taskWithContext,
-						step.cwd,
-						i + 1,
-						signal,
-						chainUpdate,
-						makeDetails("chain"),
-					);
-					results.push(result);
-
-					const isError =
-						result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-					if (isError) {
-						const errorMsg =
-							result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
-						return {
-							content: [
-								{
-									type: "text",
-									text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}`,
-								},
-							],
-							details: makeDetails("chain")(results),
-							isError: true,
-						};
-					}
-					previousOutput = getFinalOutput(result.messages);
-				}
-				return {
-					content: [
-						{
-							type: "text",
-							text: getFinalOutput(results[results.length - 1].messages) || "(no output)",
-						},
-					],
-					details: makeDetails("chain")(results),
-				};
-			}
-
 			if (params.tasks && params.tasks.length > 0) {
 				if (params.tasks.length > MAX_PARALLEL_TASKS)
 					return {
@@ -225,7 +157,6 @@ export default function (pi: ExtensionAPI) {
 						t.agent,
 						t.task,
 						t.cwd,
-						undefined,
 						signal,
 						// Per-task update callback
 						(partial) => {
@@ -265,7 +196,6 @@ export default function (pi: ExtensionAPI) {
 					params.agent,
 					params.task,
 					params.cwd,
-					undefined,
 					signal,
 					onUpdate,
 					makeDetails("single"),
@@ -310,26 +240,6 @@ export default function (pi: ExtensionAPI) {
 
 		renderCall(args, theme, _context) {
 			const scope: AgentScope = args.agentScope ?? "user";
-			if (args.chain && args.chain.length > 0) {
-				let text =
-					theme.fg("toolTitle", theme.bold("subagent ")) +
-					theme.fg("accent", `chain (${args.chain.length} steps)`) +
-					theme.fg("muted", ` [${scope}]`);
-				for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
-					const step = args.chain[i];
-					// Clean up {previous} placeholder for display
-					const cleanTask = step.task.replace(/\{previous\}/g, "").trim();
-					const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask;
-					text +=
-						"\n  " +
-						theme.fg("muted", `${i + 1}.`) +
-						" " +
-						theme.fg("accent", step.agent) +
-						theme.fg("dim", ` ${preview}`);
-				}
-				if (args.chain.length > 3) text += `\n  ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`;
-				return new Text(text, 0, 0);
-			}
 			if (args.tasks && args.tasks.length > 0) {
 				let text =
 					theme.fg("toolTitle", theme.bold("subagent ")) +

package/examples/extensions/subagent/render.ts

@@ -116,84 +116,6 @@ export function renderSubagentResult(result: ToolResult, { expanded }: RenderSta
 		return total;
 	};
 
-	if (details.mode === "chain") {
-		const successCount = details.results.filter((r) => r.exitCode === 0).length;
-		const icon = successCount === details.results.length ? theme.fg("success", "✓") : theme.fg("error", "✗");
-
-		if (expanded) {
-			const container = new Container();
-			container.addChild(
-				new Text(
-					icon +
-						" " +
-						theme.fg("toolTitle", theme.bold("chain ")) +
-						theme.fg("accent", `${successCount}/${details.results.length} steps`),
-					0,
-					0,
-				),
-			);
-
-			for (const r of details.results) {
-				const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
-				const displayItems = getDisplayItems(r.messages);
-				const finalOutput = getFinalOutput(r.messages);
-
-				container.addChild(new Spacer(1));
-				container.addChild(
-					new Text(`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0),
-				);
-				container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
-
-				// Show tool calls
-				for (const item of displayItems) {
-					if (item.type === "toolCall") {
-						container.addChild(
-							new Text(
-								theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)),
-								0,
-								0,
-							),
-						);
-					}
-				}
-
-				// Show final output as markdown
-				if (finalOutput) {
-					container.addChild(new Spacer(1));
-					container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-				}
-
-				const stepUsage = formatUsageStats(r.usage, r.model);
-				if (stepUsage) container.addChild(new Text(theme.fg("dim", stepUsage), 0, 0));
-			}
-
-			const usageStr = formatUsageStats(aggregateUsage(details.results));
-			if (usageStr) {
-				container.addChild(new Spacer(1));
-				container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
-			}
-			return container;
-		}
-
-		// Collapsed view
-		let text =
-			icon +
-			" " +
-			theme.fg("toolTitle", theme.bold("chain ")) +
-			theme.fg("accent", `${successCount}/${details.results.length} steps`);
-		for (const r of details.results) {
-			const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
-			const displayItems = getDisplayItems(r.messages);
-			text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
-			if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
-			else text += `\n${renderDisplayItems(displayItems, 5)}`;
-		}
-		const usageStr = formatUsageStats(aggregateUsage(details.results));
-		if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
-		text += `\n${theme.fg("muted", "(ctrl+o to expand)")}`;
-		return new Text(text, 0, 0);
-	}
-
 	if (details.mode === "parallel") {
 		const running = details.results.filter((r) => r.exitCode === -1).length;
 		const successCount = details.results.filter((r) => r.exitCode === 0).length;

package/examples/extensions/subagent/runner.ts

@@ -65,7 +65,6 @@ export async function runSingleAgent(
 	agentName: string,
 	task: string,
 	cwd: string | undefined,
-	step: number | undefined,
 	signal: AbortSignal | undefined,
 	onUpdate: OnUpdateCallback | undefined,
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
@@ -90,7 +89,6 @@ export async function runSingleAgent(
 				contextTokens: 0,
 				turns: 0,
 			},
-			step,
 		};
 	}
 
@@ -118,7 +116,6 @@ export async function runSingleAgent(
 			turns: 0,
 		},
 		model: agent.model,
-		step,
 	};
 
 	const emitUpdate = () => {

package/examples/extensions/subagent/schemas.ts

@@ -9,14 +9,6 @@ const TaskItem = Type.Object({
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 });
 
-const ChainItem = Type.Object({
-	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({
-		description: "Task with optional {previous} placeholder for prior output",
-	}),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
-});
-
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
 	default: "user",
@@ -35,11 +27,6 @@ export const SubagentParams = Type.Object({
 			maxItems: MAX_PARALLEL_TASKS,
 		}),
 	),
-	chain: Type.Optional(
-		Type.Array(ChainItem, {
-			description: "Array of {agent, task} for sequential execution",
-		}),
-	),
 	agentScope: Type.Optional(AgentScopeSchema),
 	confirmProjectAgents: Type.Optional(
 		Type.Boolean({

package/examples/extensions/subagent/types.ts

@@ -23,11 +23,10 @@ export interface SingleResult {
 	model?: string;
 	stopReason?: string;
 	errorMessage?: string;
-	step?: number;
 }
 
 export interface SubagentDetails {
-	mode: "single" | "parallel" | "chain";
+	mode: "single" | "parallel";
 	agentScope: AgentScope;
 	projectAgentsDir: string | null;
 	results: SingleResult[];

package/examples/sdk/09-api-keys-and-oauth.ts

@@ -26,9 +26,13 @@ const { session: customAuthSession } = await createAgentSession({
 console.log("Session with custom credential and model configuration");
 customAuthSession.dispose();
 
-// Runtime API key override (not persisted to disk)
+// Runtime API key override (not persisted to disk). Auth and catalog updates
+// are separate so callers can scope and cancel network refreshes.
 const runtimeKeyRuntime = await ModelRuntime.create();
-await runtimeKeyRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
+const providerId = "anthropic";
+const authController = new AbortController();
+await runtimeKeyRuntime.setRuntimeApiKey(providerId, "sk-my-temp-key", { signal: authController.signal });
+await runtimeKeyRuntime.refresh({ providers: [providerId], signal: authController.signal });
 const { session: runtimeKeySession } = await createAgentSession({
 	sessionManager: SessionManager.inMemory(),
 	modelRuntime: runtimeKeyRuntime,

package/examples/sdk/12-full-control.ts

@@ -20,9 +20,15 @@ const modelRuntime = await ModelRuntime.create({
 	modelsPath: null,
 });
 
-// Runtime API key override (not persisted)
+// Runtime API key override (not persisted). Update auth state first, then
+// explicitly refresh the affected provider catalog.
 if (process.env.MY_ANTHROPIC_KEY) {
-	await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_ANTHROPIC_KEY);
+	const providerId = "anthropic";
+	const authController = new AbortController();
+	await modelRuntime.setRuntimeApiKey(providerId, process.env.MY_ANTHROPIC_KEY, {
+		signal: authController.signal,
+	});
+	await modelRuntime.refresh({ providers: [providerId], signal: authController.signal });
 }
 
 const model = getModel("anthropic", "claude-sonnet-4-5");

package/examples/sdk/README.md

@@ -75,7 +75,10 @@ const customRuntime = await ModelRuntime.create({
   authPath: "/my/app/auth.json",
   modelsPath: "/my/app/models.json",
 });
-await customRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY!);
+const providerId = "anthropic";
+const authController = new AbortController();
+await customRuntime.setRuntimeApiKey(providerId, process.env.MY_KEY!, { signal: authController.signal });
+await customRuntime.refresh({ providers: [providerId], signal: authController.signal });
 const resourceLoader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are helpful.",
   extensionFactories: [myExtension],