@bastani/atomic 0.9.3-alpha.3 → 0.9.3-alpha.4

package/dist/builtin/cursor/src/model-mapper.ts

@@ -1,6 +1,7 @@
 import type { ThinkingLevel, ThinkingLevelMap } from "@earendil-works/pi-ai";
 import { CURSOR_API, CURSOR_API_BASE_URL } from "./config.js";
 import rawFallbackModels from "./cursor-models-raw.json" with { type: "json" };
+import { positiveIntOrUndefined, resolveCursorModelReferenceLimits, type CursorModelReferenceCandidate } from "./model-reference.js";
 
 export type CursorCatalogSource = "live" | "estimated";
 export type CursorEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max" | "default";
@@ -60,12 +61,13 @@ interface CursorVariantGroup {
 const CURSOR_FALLBACK_RAW_MODELS = rawFallbackModels satisfies readonly CursorUsableModel[];
 const PARSEABLE_EFFORTS: readonly Exclude<CursorEffort, "default">[] = ["none", "low", "medium", "high", "xhigh", "max"];
 const EFFORT_ORDER: readonly CursorEffort[] = ["none", "low", "default", "medium", "high", "xhigh", "max"];
+const THINKING_LEVELS: readonly ThinkingLevel[] = ["minimal", "low", "medium", "high", "xhigh"];
 const THINKING_LEVEL_EFFORT_PREFERENCES: Record<ThinkingLevel, readonly CursorEffort[]> = {
 	minimal: ["none", "low", "default"],
 	low: ["low", "none", "default"],
 	medium: ["medium", "default", "low"],
 	high: ["high", "medium", "default"],
-	xhigh: ["max", "xhigh", "high"],
+	xhigh: ["max", "xhigh"],
 };
 
 const ESTIMATED_CONTEXT_WINDOW = 200_000;
@@ -85,38 +87,99 @@ export function createEstimatedCursorCatalog(now = Date.now()): CursorModelCatal
 }
 
 export function mapCursorCatalogToProviderModels(catalog: CursorModelCatalog): CursorProviderModelDefinition[] {
-	return groupCursorModels(catalog.models).map((group) => {
+	const groups = groupCursorModels(catalog.models);
+	const familyReferenceVariants = cursorReferenceVariantsByBaseId(groups);
+	return groups.map((group) => {
 		const effortVariants = collectEffortVariants(group.variants, group.primaryId);
 		const supportsEffort = group.variants.some((variant) => Boolean(variant.effort)) || effortVariants.size >= 2;
 		const supportsReasoning = supportsReasoningModelId(group.primaryId);
 		const name = catalog.source === "estimated" ? `${group.displayName} (estimated)` : group.displayName;
+		// Cursor's private API omits token limits, so when neither a live nor a
+		// static explicit limit is present, derive the window/output from the
+		// bundled pi-ai model catalog before falling back to a conservative
+		// estimate. This never changes which models are registered. One-million
+		// labels are tracked across fast/thinking sibling groups for the same
+		// family so Cursor's mode suffixes do not hide the advertised long window.
+		const referenceLimits = resolveCursorModelReferenceLimits(cursorModelReferenceCandidates(group, familyReferenceVariants.get(group.baseId) ?? []));
 		return {
 			id: group.primaryId,
 			name,
 			api: CURSOR_API,
 			baseUrl: CURSOR_API_BASE_URL,
 			reasoning: supportsReasoning,
-			thinkingLevelMap: supportsEffort ? buildThinkingLevelMap(effortVariants, group.primaryId) : undefined,
+			thinkingLevelMap: supportsEffort ? buildCursorThinkingLevelMap(group, effortVariants) : undefined,
 			input: cursorModelInput(group.primaryId),
 			cost: subscriptionCost(),
-			contextWindow: chooseLargestNumber(group.variants.map((variant) => variant.contextWindow)) ?? ESTIMATED_CONTEXT_WINDOW,
-			maxTokens: chooseLargestNumber(group.variants.map((variant) => variant.maxTokens)) ?? ESTIMATED_MAX_TOKENS,
+			contextWindow: positiveIntLimit(chooseLargestNumber(group.variants.map((variant) => variant.contextWindow)) ?? referenceLimits.contextWindow, ESTIMATED_CONTEXT_WINDOW),
+			maxTokens: positiveIntLimit(chooseLargestNumber(group.variants.map((variant) => variant.maxTokens)) ?? referenceLimits.maxTokens, ESTIMATED_MAX_TOKENS),
 		};
 	});
 }
 
+function cursorModelReferenceCandidates(group: CursorVariantGroup, familyVariants: readonly CursorVariant[]): CursorModelReferenceCandidate[] {
+	return [
+		{ id: group.primaryId, displayName: group.displayName },
+		...group.variants.map((variant) => ({ id: variant.id, displayName: variant.displayName })),
+		...familyVariants.map((variant) => ({ id: variant.id, displayName: variant.displayName })),
+	];
+}
+
+function cursorReferenceVariantsByBaseId(groups: readonly CursorVariantGroup[]): ReadonlyMap<string, readonly CursorVariant[]> {
+	const variantsByBaseId = new Map<string, CursorVariant[]>();
+	for (const group of groups) {
+		const variants = variantsByBaseId.get(group.baseId) ?? [];
+		variants.push(...group.variants);
+		variantsByBaseId.set(group.baseId, variants);
+	}
+	return variantsByBaseId;
+}
+
+function positiveIntLimit(value: number | undefined, fallback: number): number {
+	// Provider registration rejects non-positive/non-integer windows and would
+	// drop the whole catalog; guarantee a valid positive integer here so limit
+	// values can never affect which Cursor models are listed.
+	return positiveIntOrUndefined(value) ?? fallback;
+}
+
 export function resolveCursorModelVariant(
 	baseModelId: string,
 	thinkingLevelMap: ThinkingLevelMap | undefined,
 	thinkingLevel: ThinkingLevel | undefined,
 ): string {
-	if (!thinkingLevel || !thinkingLevelMap) return baseModelId;
-	const mapped = thinkingLevelMap[thinkingLevel];
-	if (!mapped || mapped === "default") return baseModelId;
+	if (!thinkingLevelMap) return baseModelId;
+	// With no explicit thinking level, fall back to the `off` default variant.
+	// Effort-only Cursor models have no real base id (Cursor lists only
+	// `gpt-5.5-medium`, never a bare `gpt-5.5`), so sending the synthesized base
+	// id makes Cursor reject the run with `not_found`; the `off` entry carries a
+	// concrete variant id to send instead.
+	const mapped = thinkingLevel ? thinkingLevelMap[thinkingLevel] : thinkingLevelMap.off;
+	if (mapped === null) {
+		const fallbackLevel = nearestSupportedThinkingLevel(thinkingLevelMap, thinkingLevel);
+		return fallbackLevel ? resolveCursorModelVariant(baseModelId, thinkingLevelMap, fallbackLevel) : baseModelId;
+	}
+	if (mapped === undefined || mapped === "default") return baseModelId;
 	if (isCursorEffort(mapped)) return replaceEffortBeforeCursorSuffix(baseModelId, mapped);
 	return mapped;
 }
 
+function nearestSupportedThinkingLevel(
+	thinkingLevelMap: ThinkingLevelMap,
+	thinkingLevel: ThinkingLevel | undefined,
+): ThinkingLevel | undefined {
+	if (!thinkingLevel) return undefined;
+	const requestedIndex = THINKING_LEVELS.indexOf(thinkingLevel);
+	if (requestedIndex === -1) return undefined;
+	for (let index = requestedIndex - 1; index >= 0; index--) {
+		const level = THINKING_LEVELS[index];
+		if (level && thinkingLevelMap[level] !== null && thinkingLevelMap[level] !== undefined) return level;
+	}
+	for (let index = requestedIndex + 1; index < THINKING_LEVELS.length; index++) {
+		const level = THINKING_LEVELS[index];
+		if (level && thinkingLevelMap[level] !== null && thinkingLevelMap[level] !== undefined) return level;
+	}
+	return undefined;
+}
+
 export function insertEffortBeforeCursorSuffix(modelId: string, effort: CursorEffort): string {
 	if (effort === "default") return modelId;
 	let base = modelId;
@@ -205,16 +268,36 @@ function collectEffortVariants(variants: readonly CursorVariant[], primaryId: st
 	return byEffort;
 }
 
+function buildCursorThinkingLevelMap(group: CursorVariantGroup, effortVariants: ReadonlyMap<CursorEffort, string>): ThinkingLevelMap {
+	const map = buildThinkingLevelMap(effortVariants, group.primaryId);
+	// When the group has no real base id (every Cursor variant carries an effort
+	// suffix), the synthesized primary id is not a sendable Cursor model. Record
+	// an `off` default so a no-thinking request maps to a concrete variant instead
+	// of the base id, which Cursor would reject with `not_found`. Prefer the
+	// minimal/least-effort variant because `off` means minimum reasoning.
+	const hasRealBaseId = group.variants.some((variant) => variant.id === group.primaryId);
+	if (!hasRealBaseId) {
+		const defaultVariant = map.minimal ?? map.low ?? map.medium ?? map.high ?? map.xhigh ?? null;
+		if (defaultVariant) map.off = defaultVariant;
+	}
+	return map;
+}
+
 function buildThinkingLevelMap(effortVariants: ReadonlyMap<CursorEffort, string>, primaryId: string): ThinkingLevelMap {
 	return {
 		minimal: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.minimal, primaryId),
 		low: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.low, primaryId),
 		medium: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.medium, primaryId),
 		high: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.high, primaryId),
-		xhigh: chooseEffortVariant(effortVariants, THINKING_LEVEL_EFFORT_PREFERENCES.xhigh, primaryId),
+		// `xhigh` should only be offered when Cursor advertises a true xhigh/max variant.
+		xhigh: chooseCursorXhighVariant(effortVariants),
 	};
 }
 
+function chooseCursorXhighVariant(effortVariants: ReadonlyMap<CursorEffort, string>): string | null {
+	return effortVariants.get("max") ?? effortVariants.get("xhigh") ?? null;
+}
+
 function chooseEffortVariant(effortVariants: ReadonlyMap<CursorEffort, string>, preferences: readonly CursorEffort[], _primaryId: string): string | null {
 	for (const effort of preferences) {
 		const variantId = effortVariants.get(effort);
@@ -232,8 +315,10 @@ function isCursorEffort(value: string): value is CursorEffort {
 }
 
 function chooseLargestNumber(values: readonly (number | undefined)[]): number | undefined {
-	const finiteValues = values.filter((value): value is number => typeof value === "number" && Number.isFinite(value));
-	return finiteValues.length > 0 ? Math.max(...finiteValues) : undefined;
+	// Cursor's private API omits token limits; treat any non-positive value as
+	// bogus so a stray 0/negative never becomes an invalid context window.
+	const positiveValues = values.filter((value): value is number => typeof value === "number" && Number.isFinite(value) && value > 0);
+	return positiveValues.length > 0 ? Math.max(...positiveValues) : undefined;
 }
 
 function choosePrimaryId(variants: readonly CursorVariant[], baseId: string): string {

package/dist/builtin/cursor/src/model-reference.ts

@@ -0,0 +1,282 @@
+import { getModels, getProviders } from "@earendil-works/pi-ai";
+
+export interface CursorModelReferenceCandidate {
+	readonly id: string;
+	readonly displayName?: string;
+}
+
+export interface CursorModelReferenceLimits {
+	readonly contextWindow?: number;
+	readonly maxTokens?: number;
+}
+
+export interface CursorModelReferenceCatalogEntry {
+	readonly provider: string;
+	readonly id: string;
+	readonly name: string;
+	readonly contextWindow: number;
+	readonly maxTokens: number;
+}
+
+interface ReferenceModelLimits {
+	readonly provider: string;
+	readonly id: string;
+	readonly name: string;
+	readonly contextWindow: number;
+	readonly maxTokens: number;
+	readonly priority: number;
+}
+
+const ONE_MILLION_MODEL_NAME_CONTEXT_WINDOW = 1_000_000;
+const UNRANKED_PROVIDER_PRIORITY = 10_000;
+const CURSOR_EFFORT_SUFFIXES = ["none", "low", "medium", "high", "xhigh", "max", "default"] as const;
+const CLAUDE_FAMILY_NAMES = new Set(["fable", "haiku", "opus", "sonnet"]);
+
+const REFERENCE_PROVIDER_PRIORITY = new Map<string, number>([
+	["opencode", 0],
+	["opencode-go", 1],
+	["anthropic", 10],
+	["google", 20],
+	["google-vertex", 21],
+	["openai", 30],
+	["openai-codex", 31],
+	["azure-openai-responses", 32],
+	["xai", 40],
+	["moonshotai", 50],
+	["moonshotai-cn", 51],
+	["kimi-coding", 52],
+	["zai", 60],
+	["zai-coding-cn", 61],
+	["openrouter", 100],
+	["vercel-ai-gateway", 101],
+	["cloudflare-ai-gateway", 102],
+	["cloudflare-workers-ai", 103],
+	["github-copilot", 200],
+]);
+
+const EMPTY_REFERENCE_MODEL_INDEX: ReadonlyMap<string, readonly ReferenceModelLimits[]> = new Map();
+let referenceModelIndex: ReadonlyMap<string, readonly ReferenceModelLimits[]> | undefined;
+let referenceModelCatalogOverride: readonly CursorModelReferenceCatalogEntry[] | undefined;
+
+export function setCursorModelReferenceCatalogForTesting(models: readonly CursorModelReferenceCatalogEntry[] | undefined): void {
+	referenceModelCatalogOverride = models;
+	resetCursorModelReferenceIndex();
+}
+
+export function resetCursorModelReferenceIndex(): void {
+	referenceModelIndex = undefined;
+}
+
+export function resolveCursorModelReferenceLimits(candidates: readonly CursorModelReferenceCandidate[]): CursorModelReferenceLimits {
+	// Limit resolution must never affect which Cursor models register. Any failure
+	// (e.g. an unexpected pi-ai catalog shape at runtime) degrades to "no reference
+	// limits" so the caller keeps the model with its estimate.
+	try {
+		const explicitOneMillion = candidates.some((candidate) => hasOneMillionMarker(candidate.id) || hasOneMillionMarker(candidate.displayName ?? ""));
+		const match = findReferenceModel(cursorCandidateAliases(candidates), explicitOneMillion);
+		if (!match) {
+			return explicitOneMillion ? { contextWindow: ONE_MILLION_MODEL_NAME_CONTEXT_WINDOW } : {};
+		}
+		const contextWindow = positiveIntOrUndefined(match.contextWindow);
+		return {
+			contextWindow: explicitOneMillion && contextWindow !== undefined
+				? Math.max(contextWindow, ONE_MILLION_MODEL_NAME_CONTEXT_WINDOW)
+				: contextWindow,
+			maxTokens: positiveIntOrUndefined(match.maxTokens),
+		};
+	} catch {
+		return {};
+	}
+}
+
+export function positiveIntOrUndefined(value: number | undefined): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+function findReferenceModel(aliases: readonly string[], preferOneMillion: boolean): ReferenceModelLimits | undefined {
+	const index = getReferenceModelIndex();
+	for (const alias of aliases) {
+		const matches = index.get(alias);
+		if (!matches?.[0]) continue;
+		if (preferOneMillion) {
+			const oneMillionMatch = matches.find((candidate) => candidate.contextWindow >= ONE_MILLION_MODEL_NAME_CONTEXT_WINDOW);
+			if (oneMillionMatch) return oneMillionMatch;
+		}
+		return matches[0];
+	}
+	return undefined;
+}
+
+function getReferenceModelIndex(): ReadonlyMap<string, readonly ReferenceModelLimits[]> {
+	if (referenceModelIndex) return referenceModelIndex;
+	try {
+		const mutableIndex = new Map<string, ReferenceModelLimits[]>();
+		for (const model of getReferenceModels()) {
+			for (const alias of referenceModelAliases(model)) {
+				const existing = mutableIndex.get(alias) ?? [];
+				existing.push(model);
+				mutableIndex.set(alias, existing);
+			}
+		}
+		for (const matches of mutableIndex.values()) {
+			matches.sort(compareReferenceModels);
+		}
+		referenceModelIndex = mutableIndex;
+	} catch {
+		referenceModelIndex = EMPTY_REFERENCE_MODEL_INDEX;
+	}
+	return referenceModelIndex;
+}
+
+function getReferenceModels(): ReferenceModelLimits[] {
+	return referenceModelCatalogOverride
+		? referenceModelCatalogOverride.map((model) => toReferenceModelLimits(model, referenceProviderPriority(model.provider)))
+		: getPiAiReferenceModels();
+}
+
+function getPiAiReferenceModels(): ReferenceModelLimits[] {
+	const models: ReferenceModelLimits[] = [];
+	for (const provider of getProviders()) {
+		const priority = referenceProviderPriority(provider);
+		for (const model of getModels(provider)) {
+			if (!isPositiveFiniteNumber(model.contextWindow) || !isPositiveFiniteNumber(model.maxTokens)) continue;
+			models.push(toReferenceModelLimits(model, priority));
+		}
+	}
+	return models;
+}
+
+function referenceProviderPriority(provider: string): number {
+	return REFERENCE_PROVIDER_PRIORITY.get(provider) ?? UNRANKED_PROVIDER_PRIORITY;
+}
+
+function toReferenceModelLimits(model: CursorModelReferenceCatalogEntry, priority: number): ReferenceModelLimits {
+	return {
+		provider: model.provider,
+		id: model.id,
+		name: model.name,
+		contextWindow: model.contextWindow,
+		maxTokens: model.maxTokens,
+		priority,
+	};
+}
+
+function compareReferenceModels(left: ReferenceModelLimits, right: ReferenceModelLimits): number {
+	return left.priority - right.priority
+		|| left.provider.localeCompare(right.provider)
+		|| left.id.localeCompare(right.id)
+		|| left.name.localeCompare(right.name);
+}
+
+function referenceModelAliases(model: ReferenceModelLimits): string[] {
+	const aliases = new Set<string>();
+	addNormalizedAlias(aliases, model.id);
+	addNormalizedAlias(aliases, lastPathSegment(model.id));
+	addNormalizedAlias(aliases, model.name);
+	addNormalizedAlias(aliases, displayNameTail(model.name));
+	return [...aliases];
+}
+
+function cursorCandidateAliases(candidates: readonly CursorModelReferenceCandidate[]): string[] {
+	// Match strictly on Cursor model IDs, which already carry the family and
+	// version (e.g. `gpt-5.5-high`, `claude-4.6-sonnet-medium`). Cursor display
+	// names are short and generic ("Auto", "Sonnet 4") and would produce false
+	// matches against unrelated pi-ai models, so they are not used as match keys.
+	const aliases = new Set<string>();
+	for (const candidate of candidates) {
+		for (const alias of cursorIdAliases(candidate.id)) {
+			addNormalizedAlias(aliases, alias);
+		}
+	}
+	return [...aliases];
+}
+
+function cursorIdAliases(id: string): string[] {
+	const aliases = new Set<string>([id]);
+	for (const baseAlias of cursorBaseIdAliases(id)) {
+		aliases.add(baseAlias);
+		for (const claudeAlias of cursorClaudeIdAliases(baseAlias)) {
+			aliases.add(claudeAlias);
+		}
+	}
+	return [...aliases];
+}
+
+function cursorBaseIdAliases(id: string): string[] {
+	const aliases = new Set<string>([id]);
+	const withoutModes = stripTrailingCursorModes(id);
+	aliases.add(withoutModes);
+	const withoutEffort = stripTrailingEffort(withoutModes);
+	aliases.add(withoutEffort);
+	for (const alias of [...aliases]) {
+		if (alias.endsWith("-1m")) aliases.add(alias.slice(0, -"-1m".length));
+	}
+	return [...aliases];
+}
+
+function stripTrailingCursorModes(id: string): string {
+	let result = id;
+	let changed = true;
+	while (changed) {
+		changed = false;
+		if (result.endsWith("-fast")) {
+			result = result.slice(0, -"-fast".length);
+			changed = true;
+		}
+		if (result.endsWith("-thinking")) {
+			result = result.slice(0, -"-thinking".length);
+			changed = true;
+		}
+	}
+	return result;
+}
+
+function stripTrailingEffort(id: string): string {
+	for (const effort of CURSOR_EFFORT_SUFFIXES) {
+		const suffix = `-${effort}`;
+		if (id.endsWith(suffix)) return id.slice(0, -suffix.length);
+	}
+	return id;
+}
+
+function cursorClaudeIdAliases(id: string): string[] {
+	const match = /^claude-(\d+(?:[.-]\d+)*)-([a-z]+)(?:$|-)/iu.exec(id);
+	if (!match) return [];
+	const [, version, family] = match;
+	if (!version || !family || !CLAUDE_FAMILY_NAMES.has(family.toLowerCase())) return [];
+	return [`claude-${family.toLowerCase()}-${version.replace(/[.-]/gu, "-")}`];
+}
+
+function addNormalizedAlias(aliases: Set<string>, value: string): void {
+	const normalized = normalizeReferenceKey(value);
+	if (normalized) aliases.add(normalized);
+}
+
+function normalizeReferenceKey(value: string): string | undefined {
+	const normalized = value
+		.normalize("NFKD")
+		.replace(/[\u0300-\u036f]/gu, "")
+		.toLowerCase()
+		.replace(/&/gu, " and ")
+		.replace(/[^a-z0-9]+/gu, " ")
+		.trim();
+	return normalized.length > 0 ? normalized : undefined;
+}
+
+function lastPathSegment(id: string): string {
+	const parts = id.split("/");
+	return parts[parts.length - 1] ?? id;
+}
+
+function displayNameTail(name: string): string {
+	const parts = name.split(":");
+	return parts[parts.length - 1]?.trim() ?? name;
+}
+
+function hasOneMillionMarker(value: string): boolean {
+	return /(?:^|[^a-z0-9])1\s*m(?:$|[^a-z0-9])/iu.test(value);
+}
+
+function isPositiveFiniteNumber(value: number): boolean {
+	return Number.isFinite(value) && value > 0;
+}

package/dist/builtin/cursor/src/proto/README.md

@@ -18,7 +18,7 @@ Protocol behavior intentionally copied from the reference provider:
 - Run requests use generated `AgentRunRequest`, `ConversationStateStructure`, `ConversationAction`, `UserMessage`, and `ModelDetails` messages.
 - `UserMessage.message_id`, `UserMessage.correlation_id`, and reconstructed historical turn request ids are UUIDs generated the same way as the reference provider.
 - Conversation ids are deterministic UUIDs derived from the hashed conversation key (`conv:<session-or-first-user-text>`), matching the reference provider rather than sending raw Atomic session ids to Cursor.
-- Static fallback models are the reference `cursor-models-raw.json`; live model discovery is opportunistic and only replaces the registered catalog when Cursor returns usable models.
+- Static fallback models are the reference `cursor-models-raw.json`; live model discovery is opportunistic and only replaces the registered catalog when Cursor returns usable models. Cursor's model-discovery protobuf carries no context-window or output-token fields, so the provider preserves any positive limits and otherwise resolves them from Atomic's bundled `@earendil-works/pi-ai` model catalog by Cursor model ID (with a conservative estimate for unmatched Cursor-only models and a 1,000,000-token floor for explicit `1M` Cursor labels); this only sets limits and does not change catalog membership.
 - Tool definitions are returned in response to `ExecServerMessage.request_context_args = 10`; `McpArgs` messages become Atomic tool calls and active tool results are sent back as generated `ExecClientMessage.mcp_result` frames.
 - Checkpoint and blob-store state is persisted per Cursor conversation id and discarded on Cursor end-stream errors such as `not_found`.
 - `InteractionUpdate.turn_ended` is non-terminal; the stream closes on the Connect stream ending.
@@ -27,7 +27,7 @@ Manual smoke-test procedure after Cursor releases:
 
 1. Sign in to the current Cursor CLI/app and capture a successful `api2.cursor.sh` model discovery or agent `Run` request.
 2. Update `CURSOR_CLIENT_VERSION` in `src/config.ts` from the captured `x-cursor-client-version` header if it changed.
-3. In Atomic, run `/login`, select **Cursor**, complete browser auth, then confirm `/model` lists `cursor/<model-id>` entries from live discovery.
+3. In Atomic, run `/login`, select **Cursor (Experimental)**, complete browser auth, then confirm `/model` lists `cursor/<model-id>` entries from live discovery.
 4. Select a Cursor model and run one chat turn plus one tool-using turn; verify the process exits cleanly for a one-shot/noninteractive run.
 5. Re-run the Cursor unit tests and update these notes for any changed protobuf paths.
 

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.3-alpha.4] - 2026-06-28
+
+### Changed
+
+- Published a synchronized Atomic 0.9.3-alpha.4 prerelease for the intercom extension; no intercom extension changes were made after 0.9.3-alpha.3.
+
 ## [0.9.3-alpha.3] - 2026-06-27
 
 ### Changed

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.3-alpha.3",
+  "version": "0.9.3-alpha.4",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3-alpha.4] - 2026-06-28
+
+### Changed
+
+- Published a synchronized Atomic 0.9.3-alpha.4 prerelease for the MCP extension; no MCP extension changes were made after 0.9.3-alpha.3.
+
 ## [0.9.3-alpha.3] - 2026-06-27
 
 ### Changed

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.3-alpha.3",
+  "version": "0.9.3-alpha.4",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.3-alpha.4] - 2026-06-28
+
+### Changed
+
+- Published a synchronized Atomic 0.9.3-alpha.4 prerelease for the subagents extension; no subagents extension changes were made after 0.9.3-alpha.3.
+
 ## [0.9.3-alpha.3] - 2026-06-27
 
 ### Changed

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.3-alpha.3",
+  "version": "0.9.3-alpha.4",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/web-access/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.3-alpha.4] - 2026-06-28
+
+### Changed
+
+- Published a synchronized Atomic 0.9.3-alpha.4 prerelease for the web-access extension; no web-access extension changes were made after 0.9.3-alpha.3.
+
 ## [0.9.3-alpha.3] - 2026-06-27
 
 ### Changed

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.3-alpha.3",
+  "version": "0.9.3-alpha.4",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [

package/dist/builtin/workflows/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.9.3-alpha.4] - 2026-06-28
+
+### Changed
+
+- Strengthened the model-facing workflow prompt guidance to treat workflows as the default path for non-trivial tasks and requests with inherent structure plus verifiable objectives, explicitly including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, and validation-heavy docs/code prompts alongside loop-shaped phrasing such as `do X until Y`, `repeat until`, `iterate until`, and review/fix/test-until-passing prompts.
+
 ## [0.9.3-alpha.3] - 2026-06-27
 
 ### Changed

package/dist/builtin/workflows/README.md

@@ -5,6 +5,8 @@
   An open-source Atomic workflow extension: install it, author workflows in TypeScript, run them from chat.
 </p>
 
+Use workflows by default for non-trivial tasks, structured requests, and objectives with verifiable done criteria, including implementation, build, debugging, bug-fix, migration, new-feature, scoped multi-file, and validation-heavy docs/code work. Prompt language such as `do X until Y`, `repeat until`, `iterate until`, `review/fix until passing`, or `run checks and fix until green` is a strong signal to map the work to a workflow with an explicit stop condition rather than a direct chat turn.
+
 <p align="center">
   <a href="#authoring-api">Authoring API</a>
   &nbsp;·&nbsp;

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.9.3-alpha.3",
+  "version": "0.9.3-alpha.4",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -8,7 +8,10 @@ export const WORKFLOW_TOOL_DESCRIPTION =
   "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
 
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-  `**Workflows**: Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when that is useful.
+  `**Workflows**: Treat workflows as the default execution path for any non-trivial task and for any request that has inherent structure plus an objective you can make verifiable. Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, multi-stage, or reviewer-gated processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when no named workflow fits.
+  - Workflow fit check: before implementing directly, ask whether the task is an implementation, build, debug/diagnosis, bug-fix, migration, new-feature, scoped multi-file edit, or docs/code change with validation; or whether it has multiple steps, dependencies, handoffs, uncertainty, validation/review needs, a long-running surface, or measurable done criteria. If yes, launch or design a workflow instead of doing parallel implementation yourself.
+  - Treat loop/structural wording as a strong workflow signal, especially requests like "do X until Y", "repeat until", "iterate until", "review/fix until passing", "run checks and fix until green", "keep going until done", or any prompt that names a stop condition, approval gate, or evidence requirement.
+  - Only skip workflows for tiny, deterministic, low-risk answers or direct edits that are faster and safer to complete inline without stage tracking, typically a clearly single-file/no-test/no-review change.
   - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
   - When designing or editing workflows, read docs/workflows.md and reference its Workflow Starter Patterns: Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done. Choose or combine these patterns before inventing a custom stage graph, and reflect the selected pattern in the spec and Mermaid diagram when using the create-spec skill.
   - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.
@@ -19,7 +22,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
   - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
     - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
-  - Prefer using the \`goal\` workflow for small fixes/quick fixes and the \`ralph\` workflow for tasks that are non-trivial (over 2K LoC estimated diff).
-    - Adjust the \`max_loops\` based on task complexity (estimated LoC and number of unique files that are touched).
+  - Prefer the \`goal\` workflow for small-to-medium non-trivial one-off fixes, debugging, docs/code changes, scoped multi-file edits, or test/fix loops when you can name the work surface, outcome, and validation; prefer the \`ralph\` workflow for larger/riskier work, migrations, new features, broad refactors, multi-package changes, or tasks estimated over ~2K LoC.
+    - Adjust \`goal.max_turns\` for Goal runs and \`ralph.max_loops\` for Ralph runs based on task complexity (estimated LoC, risk, validation effort, and number of unique files/areas touched).
     - Define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,
 ];