@bubblebrain-ai/bubble 0.0.34 → 0.0.36

package/dist/oauth/grok.js

@@ -0,0 +1,218 @@
+/**
+ * xAI Grok subscription OAuth login (PKCE + local callback).
+ *
+ * Mirrors the public OAuth client used by the official Grok CLI so a Grok
+ * subscription can drive Bubble's native agent loop the same way ChatGPT
+ * OAuth does: browser sign-in once, then bearer + refresh tokens stored in
+ * ~/.bubble/auth.json.
+ */
+import { createServer } from "node:http";
+import { exec } from "node:child_process";
+import { randomBytes, createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { chatGptFetch } from "../network/chatgpt-transport.js";
+// Public OAuth client registered for the official Grok CLI ("Grok Build").
+const CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const AUTH_URL = "https://auth.x.ai/oauth2/authorize";
+const TOKEN_URL = "https://auth.x.ai/oauth2/token";
+const SCOPE = "openid profile email offline_access grok-cli:access api:access conversations:read conversations:write";
+function generatePKCE() {
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+    return { codeVerifier, codeChallenge };
+}
+function generateOpaqueId() {
+    return globalThis.crypto?.randomUUID?.() ?? randomBytes(16).toString("hex");
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    exec(`${cmd} ${JSON.stringify(url)}`, () => {
+        // ignore errors; we show manual fallback in UI
+    });
+}
+/**
+ * xAI's OAuth client allows dynamic loopback ports, so listen on an ephemeral
+ * port and report the redirect URI back to the login flow once bound.
+ */
+async function startCallbackServer(timeoutMs, onListening, onStatus) {
+    return new Promise((resolve, reject) => {
+        let resolved = false;
+        const server = createServer((req, res) => {
+            try {
+                const port = server.address().port;
+                const url = new URL(req.url || "/", `http://127.0.0.1:${port}`);
+                if (url.pathname === "/callback") {
+                    const code = url.searchParams.get("code");
+                    const state = url.searchParams.get("state");
+                    const error = url.searchParams.get("error");
+                    const errorDesc = url.searchParams.get("error_description");
+                    if (error) {
+                        res.writeHead(400, { "Content-Type": "text/html" });
+                        res.end(`<html><body><h1>Authorization failed</h1><p>${errorDesc || error}</p></body></html>`);
+                        if (!resolved) {
+                            resolved = true;
+                            server.close(() => reject(new Error(`OAuth error: ${errorDesc || error}`)));
+                        }
+                        return;
+                    }
+                    if (code) {
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end("<html><body><h1>Authorization successful</h1><p>You can close this window and return to the terminal.</p></body></html>");
+                        if (!resolved) {
+                            resolved = true;
+                            server.close(() => resolve({ code, state: state || "" }));
+                        }
+                        return;
+                    }
+                }
+                res.writeHead(404);
+                res.end("Not found");
+            }
+            catch {
+                res.writeHead(500);
+                res.end("Error");
+            }
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            onStatus?.(`Local server listening on http://127.0.0.1:${port}`);
+            onListening(`http://127.0.0.1:${port}/callback`);
+        });
+        setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                server.close(() => reject(new Error(`OAuth login timed out after ${timeoutMs / 1000}s`)));
+            }
+        }, timeoutMs);
+    });
+}
+function parseTokenResponse(data, fallbackRefreshToken) {
+    if (!data.access_token || typeof data.access_token !== "string") {
+        throw new Error("xAI returned no access token.");
+    }
+    const refreshToken = data.refresh_token || fallbackRefreshToken;
+    if (!refreshToken) {
+        throw new Error("xAI returned no refresh token.");
+    }
+    const expiresIn = typeof data.expires_in === "number" && data.expires_in > 0 ? data.expires_in : 3600;
+    return {
+        accessToken: data.access_token,
+        refreshToken,
+        expiresAt: Date.now() + expiresIn * 1000,
+    };
+}
+export async function loginGrok(callbacks, options = {}) {
+    const fetchImpl = options.fetch ?? chatGptFetch;
+    callbacks?.onStatus("Starting xAI Grok OAuth login...");
+    const pkce = generatePKCE();
+    const state = generateOpaqueId();
+    const nonce = generateOpaqueId();
+    let redirectUri = "";
+    const serverPromise = startCallbackServer(5 * 60 * 1000, (uri) => {
+        redirectUri = uri;
+    }, callbacks?.onStatus);
+    // The listen callback fires before any request can arrive; give the event
+    // loop one tick so redirectUri is populated before building the URL.
+    await new Promise((resolve) => setImmediate(resolve));
+    if (!redirectUri) {
+        throw new Error("The local OAuth callback server did not start.");
+    }
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: CLIENT_ID,
+        redirect_uri: redirectUri,
+        scope: SCOPE,
+        code_challenge: pkce.codeChallenge,
+        code_challenge_method: "S256",
+        state,
+        nonce,
+        referrer: "grok-build",
+    });
+    const authUrl = `${AUTH_URL}?${params.toString()}`;
+    callbacks?.onStatus("Opening browser for authorization...");
+    openBrowser(authUrl);
+    callbacks?.onStatus(`If your browser didn't open, copy this URL manually:\n${authUrl}`);
+    callbacks?.onStatus("Waiting for authorization (timeout: 5min)...");
+    const { code, state: returnedState } = await serverPromise;
+    if (returnedState !== state) {
+        throw new Error("OAuth state mismatch. Possible CSRF attack.");
+    }
+    callbacks?.onStatus("Exchanging authorization code for tokens...");
+    const response = await fetchImpl(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: CLIENT_ID,
+            code_verifier: pkce.codeVerifier,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "Unknown error");
+        throw new Error(`Token exchange failed: ${response.status} ${response.statusText} - ${text}`);
+    }
+    const tokens = parseTokenResponse((await response.json()));
+    callbacks?.onStatus("Login successful!");
+    return tokens;
+}
+export async function refreshGrok(refreshToken, options = {}) {
+    const fetchImpl = options.fetch ?? chatGptFetch;
+    const response = await fetchImpl(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: CLIENT_ID,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "Unknown error");
+        throw new Error(`Token refresh failed: ${response.status} ${response.statusText} - ${text}`);
+    }
+    return parseTokenResponse((await response.json()), refreshToken);
+}
+/**
+ * One-time credential import from the official Grok CLI's auth store (either
+ * Bubble's isolated runtime profile or the user's real ~/.grok). Users who
+ * already completed `grok login` skip the browser round-trip entirely.
+ */
+export function importGrokCliCredentials(bubbleHome = join(homedir(), ".bubble")) {
+    const candidates = [
+        join(bubbleHome, "runtimes", "grok", "grok-home", "auth.json"),
+        join(homedir(), ".grok", "auth.json"),
+    ];
+    for (const path of candidates) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object")
+            continue;
+        for (const [key, value] of Object.entries(parsed)) {
+            if (!key.startsWith("https://auth.x.ai::"))
+                continue;
+            if (!value || typeof value !== "object")
+                continue;
+            const entry = value;
+            if (typeof entry.key !== "string" || !entry.key || typeof entry.refresh_token !== "string" || !entry.refresh_token) {
+                continue;
+            }
+            const expiresAt = typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) : NaN;
+            return {
+                accessToken: entry.key,
+                refreshToken: entry.refresh_token,
+                // An unparseable expiry just means the first request refreshes.
+                expiresAt: Number.isFinite(expiresAt) ? expiresAt : 0,
+            };
+        }
+    }
+    return undefined;
+}

package/dist/oauth/index.d.ts

@@ -1,3 +1,4 @@
 export { AuthStorage } from "./storage.js";
 export { loginOpenAICodex, refreshOpenAICodex, type OpenAICodexLoginCallbacks } from "./openai-codex.js";
+export { loginGrok, refreshGrok, importGrokCliCredentials, type GrokLoginCallbacks } from "./grok.js";
 export type { OAuthTokens, OAuthCredentials } from "./types.js";

package/dist/oauth/index.js

@@ -1,2 +1,3 @@
 export { AuthStorage } from "./storage.js";
 export { loginOpenAICodex, refreshOpenAICodex } from "./openai-codex.js";
+export { loginGrok, refreshGrok, importGrokCliCredentials } from "./grok.js";

package/dist/oauth/storage.d.ts

@@ -4,7 +4,16 @@
 import type { OAuthCredentials } from "./types.js";
 export declare class AuthStorage {
     private data;
+    private mutationListeners;
     constructor();
+    /**
+     * Observe credential writes/removals. Callers across the codebase mutate
+     * this storage directly (login/logout flows), so consumers that must react
+     * to credential-identity changes (ProviderRegistry's routing revision)
+     * subscribe here instead of wrapping every call site.
+     */
+    onMutation(listener: (providerId: string) => void): () => void;
+    private notifyMutation;
     private load;
     private save;
     getPath(): string;

package/dist/oauth/storage.js

@@ -7,9 +7,32 @@ import { homedir } from "node:os";
 const AUTH_PATH = join(homedir(), ".bubble", "auth.json");
 export class AuthStorage {
     data = {};
+    mutationListeners = [];
     constructor() {
         this.load();
     }
+    /**
+     * Observe credential writes/removals. Callers across the codebase mutate
+     * this storage directly (login/logout flows), so consumers that must react
+     * to credential-identity changes (ProviderRegistry's routing revision)
+     * subscribe here instead of wrapping every call site.
+     */
+    onMutation(listener) {
+        this.mutationListeners.push(listener);
+        return () => {
+            this.mutationListeners = this.mutationListeners.filter((item) => item !== listener);
+        };
+    }
+    notifyMutation(providerId) {
+        for (const listener of this.mutationListeners) {
+            try {
+                listener(providerId);
+            }
+            catch {
+                // Listeners must never break credential writes.
+            }
+        }
+    }
     load() {
         if (!existsSync(AUTH_PATH))
             return;
@@ -37,10 +60,12 @@ export class AuthStorage {
     set(providerId, creds) {
         this.data[providerId] = creds;
         this.save();
+        this.notifyMutation(providerId);
     }
     remove(providerId) {
         delete this.data[providerId];
         this.save();
+        this.notifyMutation(providerId);
     }
     has(providerId) {
         return !!this.data[providerId];

package/dist/orchestrator/default-hooks.js

@@ -4,8 +4,8 @@ import { EvidenceTracker } from "../agent/evidence-tracker.js";
 import { ExecutionGovernor } from "../agent/execution-governor.js";
 import { DiscoveryBarrier } from "../agent/discovery-barrier.js";
 import { arbitrateToolCall } from "../agent/tool-arbiter.js";
-import { buildEditRetryEscalationReminder, buildSmallTaskHint, buildTaskSummaryReminder, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
-import { reminderForTaskType } from "../prompt/task-reminders.js";
+import { buildEditRetryEscalationReminder, buildSmallTaskHint, buildWorkflowPhaseReminder, } from "../prompt/reminders.js";
+import { orchestrationRequestReminder, reminderForTaskType, userNamedModelReminder } from "../prompt/task-reminders.js";
 import { formatCoverageSummary, resolveWorkflowPhase } from "./workflow.js";
 import { buildSubagentLifecycleReminder } from "../agent/subagent-lifecycle-reminder.js";
 export function createDefaultHooks() {
@@ -28,6 +28,19 @@ export function createDefaultHooks() {
                 if (taskReminder) {
                     ctx.queueReminder(taskReminder);
                 }
+                // User named the mechanism ("agent team" / workflow / 编排): remind at
+                // the decision turn, where it outweighs the parallel-spawns prior.
+                const orchestrationReminder = orchestrationRequestReminder(ctx.input, ctx.agent.hasToolAvailable("run_workflow"));
+                if (orchestrationReminder) {
+                    ctx.queueReminder(orchestrationReminder);
+                }
+                // User named a configured model ("gpt 5.6 sol"): resolve it against
+                // the routable catalog and hand over the exact id at the decision
+                // point — never let the parent retype ids from priors (v3.6).
+                const namedModelReminder = userNamedModelReminder(ctx.input, ctx.agent.listRoutableModels?.(), ctx.agent.hasToolAvailable("spawn_agent"));
+                if (namedModelReminder) {
+                    ctx.queueReminder(namedModelReminder);
+                }
                 // Small-task hint: counterweight to the default protocol's exploration
                 // bias, only fires once per run on focused one-shot requests like
                 // "写个 HTML 介绍元旦". Don't issue for the same input twice.
@@ -141,9 +154,6 @@ export function createDefaultHooks() {
                 // edit was correct. CC's approach is the opposite: verify when there
                 // is something real to verify, say so explicitly when there isn't, and
                 // trust the model to judge. We follow that.
-                if (ctx.toolCall.name === "task") {
-                    ctx.queueReminder(buildTaskSummaryReminder());
-                }
                 if (ctx.state.governor) {
                     for (const reminder of ctx.state.governor.consumePendingReminders()) {
                         ctx.queueReminder(reminder);
@@ -157,6 +167,13 @@ export function createDefaultHooks() {
                         ctx.queueReminder(reminder);
                     }
                 }
+                // Routing detector note (model-routing design §6): rides the same
+                // channel as the lifecycle reminder, once per session. Consuming also
+                // closes the per-fan-out counting window.
+                const routingReminder = ctx.agent.consumePendingRoutingReminder?.();
+                if (routingReminder) {
+                    ctx.queueReminder(routingReminder);
+                }
                 if (ctx.state.taskType === "security_investigation" && ctx.state.evidenceTracker?.isCoreCoverageComplete()) {
                     ctx.requestTextOnlyTurn("Core security investigation evidence has been collected. Summarize the findings instead of continuing with more tool calls.");
                     return;
@@ -190,8 +207,7 @@ function isSubagentLifecycleTool(name) {
     return name === "spawn_agent"
         || name === "wait_agent"
         || name === "send_input"
-        || name === "close_agent"
-        || name === "task";
+        || name === "close_agent";
 }
 function hashEditCall(toolCall) {
     // Cheap fingerprint that identifies "same edit/write call". JSON of the

package/dist/prompt/compose.d.ts

@@ -9,5 +9,8 @@ export interface ComposeSystemPromptOptions extends EnvironmentPromptOptions {
     skills?: SkillSummary[];
     memoryPrompt?: string;
     agentProfilePrompt?: string;
+    /** Rendered subagent model-routing menu (design §4). Placed right after the
+     *  delegation policy and gated the same way: spawn_agent present. */
+    modelRoutingPrompt?: string;
 }
 export declare function composeSystemPrompt(options?: ComposeSystemPromptOptions): string;

package/dist/prompt/compose.js

@@ -27,11 +27,14 @@ export function composeSystemPrompt(options = {}) {
         guidelines: buildGuidelines(options.tools ?? defaultToolNames, options.guidelines ?? []),
     });
     const delegationPrompt = buildDelegationPolicyPrompt(options.tools ?? defaultToolNames);
+    // Same gate as the delegation policy: children (no spawn_agent) never see the menu.
+    const modelRoutingPrompt = delegationPrompt ? options.modelRoutingPrompt : undefined;
     return [
         providerPrompt,
         environmentPrompt,
         runtimePrompt,
         delegationPrompt,
+        modelRoutingPrompt,
         options.agentProfilePrompt,
         options.memoryPrompt,
     ].filter(Boolean).join("\n\n");

package/dist/prompt/delegation.d.ts

@@ -5,7 +5,7 @@
  * and read-only-scoped, negative clauses get equal weight — the user's hard
  * constraint is "proactive, but never delegate-everything". Gated on the
  * delegation tools being present, so child agents (whose tool sets never
- * include spawn_agent/agent_team) never see it.
+ * include spawn_agent/run_workflow) never see it.
  */
 /**
  * Returns the delegation policy section when the agent actually has the

package/dist/prompt/delegation.js

@@ -5,12 +5,19 @@
  * and read-only-scoped, negative clauses get equal weight — the user's hard
  * constraint is "proactive, but never delegate-everything". Gated on the
  * delegation tools being present, so child agents (whose tool sets never
- * include spawn_agent/agent_team) never see it.
+ * include spawn_agent/run_workflow) never see it.
  */
 const DELEGATION_POLICY = `## Delegation policy (subagents)
 
-You can delegate work to background subagents (spawn_agent) and batch
-fan-outs (agent_team). Delegate deliberately, not by default.
+You can delegate work two ways: a single background subagent (spawn_agent),
+or an orchestration script coordinating many subagents (run_workflow).
+Delegate deliberately, not by default.
+
+Explicit requests win, before any other rule: when the user names a
+coordinated multi-agent run in any phrasing — a workflow, an orchestration,
+an agent team, "fan out agents" — that means run_workflow, NOT a row of
+spawn_agent calls. When they ask for a subagent, spawn one. Only when the
+user has not named a mechanism do you choose by shape (below).
 
 Delegate when:
 - An investigation will clearly require more than four search or read
@@ -18,9 +25,20 @@ Delegate when:
   needs the conclusion — delegate to a subagent so the intermediate noise
   stays out of the main context. Launch multiple subagents concurrently for
   independent questions.
-- The task naturally splits into the same read-only investigation or
-  analysis (review, audit, summarize) over several independent items (files,
-  modules, endpoints) — use agent_team.
+- The task fans out over many independent items (review, audit, summarize
+  across files, modules, endpoints) or needs staged orchestration — consider
+  run_workflow. Choose by shape, not by rule: a handful of subagents whose
+  results you want to read and react to individually favor spawn_agent; a
+  uniform sweep over many items, results that should be aggregated or
+  filtered before they reach this conversation, or control flow between
+  stages (pipelines, loops, retry rounds) favor a run_workflow script — each
+  member's full handoff stays out of your context and the script returns one
+  digested result. Inside parallel()/pipeline(), a failed agent() resolves to
+  null — report which items came back null instead of silently dropping them.
+  A bare "await agent(...)" outside those combinators PROPAGATES its error
+  and fails the whole run: keep must-not-die steps (a final synthesis, the
+  last aggregation) inside parallel([...]) or a try/catch so one member's
+  failure cannot discard every other member's finished work.
 - A side-investigation is independent of your current main-line work and can
   run in the background while you continue.
 
@@ -51,8 +69,23 @@ Do NOT delegate when:
 When in doubt about a one-off task, do it yourself. When a task is clearly
 the same read-only operation over three or more independent items — where
 each item alone would take more than a couple of tool calls — prefer
-agent_team over doing them sequentially yourself. For just two small items,
-do them yourself with parallel tool calls.`;
+run_workflow over doing them sequentially yourself. For just two small items,
+do them yourself with parallel tool calls.
+
+Routing (model per child): match each child's model to its task, not to
+habit. Mechanical fan-out work — scanning, grepping, summarizing single
+files, format checks, data extraction — belongs on category "quick" or
+"explore", or an explicit fast-tier model from the routing menu; spawning
+many children that all inherit a strong parent model is waste. Judgment
+work — reviewing, adjudicating between findings, synthesizing a final
+answer, subtle debugging — keeps the parent's model: do NOT downgrade it
+to save cost. When unsure, inherit. Follow the routing menu's rules on
+which model ids are valid and whether cross-provider routing is available.
+Cross-provider (provider:model) is for a reason, not a habit: use it when
+the user names a provider or a task clearly plays to another provider's
+strength; tier labels do not compare across providers, so a cross-provider
+pick is a judgment call you should be able to justify. Same-provider is
+the default frame.`;
 /**
  * Returns the delegation policy section when the agent actually has the
  * delegation tools; child agents and stripped-down tool sets get nothing.

package/dist/prompt/environment.js

@@ -6,13 +6,11 @@ export const defaultToolSnippets = {
     write: "Write a new file or overwrite an existing one",
     glob: "Find files by glob pattern without using bash",
     grep: "Search file contents using regex",
-    lsp: "Use the language server for code navigation, symbols, call hierarchy, and type-aware lookup",
     web_search: "Search the public web for current information",
     web_fetch: "Fetch and extract the contents of a specific webpage",
     spawn_agent: "Start a child subagent thread and return its agent id plus nickname",
     wait_agent: "Wait for one or more spawned subagents to finish",
     send_input: "Send follow-up input to an existing subagent thread",
-    close_agent: "Close or cancel a spawned subagent thread",
     question: "Ask the user structured questions when clarification or preference choices would materially improve the work",
     skill_search: "Search available skills by name, description, tags, and source",
     skill: "Load a named skill with specialized instructions and bundled resources",
@@ -25,13 +23,11 @@ export const defaultToolNames = [
     "edit",
     "write",
     "grep",
-    "lsp",
     "web_search",
     "web_fetch",
     "spawn_agent",
     "wait_agent",
     "send_input",
-    "close_agent",
     "question",
     "skill_search",
     "skill",

package/dist/prompt/reminders.d.ts

@@ -29,7 +29,6 @@ export declare function buildWorkflowPhaseReminder(input: {
     covered: string[];
     pending: string[];
 }): string;
-export declare function buildTaskSummaryReminder(): string;
 /**
  * Fired when a file mutation failure suggests the model may be relying on stale
  * local memory instead of the current file bytes. Models — especially

package/dist/prompt/reminders.js

@@ -20,7 +20,7 @@ const PLAN_MODE_ENTER = `
 Plan mode is now ACTIVE.
 
 Rules while in plan mode:
-- Only read-only tools are allowed, including read, glob, grep, lsp, web_search, web_fetch, spawn_agent, wait_agent, send_input, close_agent, skill_search, skill, todo_write, tool_search, question, and exit_plan_mode.
+- Only read-only tools are allowed, including read, glob, grep, web_search, web_fetch, spawn_agent, wait_agent, send_input, skill_search, skill, todo_write, tool_search, question, and exit_plan_mode.
 - Writes, edits, and shell commands WILL be rejected by the harness; do not try them.
 - Do not edit files or claim implementation is complete while plan mode is active.
 - Investigate the codebase, then use the question tool to clarify important ambiguities, tradeoffs, requirements, or preference choices that would materially change the plan.
@@ -161,16 +161,6 @@ Remaining evidence to check:
 ${pending}
 `);
 }
-export function buildTaskSummaryReminder() {
-    return wrapInSystemReminder(`
-Summarize the task tool output above and continue with your task.
-
-Treat the task output as a bounded subtask result:
-- extract the findings that matter
-- integrate them into your main reasoning
-- do not re-run the same exploratory search unless the subtask uncovered a concrete contradiction
-`);
-}
 // Removed: buildVerificationReminder / buildVerificationFailureReminder.
 // The verification reminder ladder pressured the model to run a "verification"
 // after every file change. For models with hex-tokenization blind spots (e.g.

package/dist/prompt/routing.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Subagent model-routing menu for the parent agent's system prompt
+ * (docs/model-routing-design.md §4).
+ *
+ * Wording rules: the prompt must never promise more enforcement than the
+ * runtime delivers at any later moment. Absolute "choose only from this
+ * list" wording is used only for a models.json allowlist (the one catalog
+ * that cannot silently expire); every other membership source gets the
+ * conservative lag disclaimer, matching §7.1's warn-and-allow validation.
+ * Gated on spawn_agent alongside the delegation policy — children never
+ * see it.
+ */
+import type { AgentRoutingConfig, RoutingSnapshot } from "../agent/routing-catalog.js";
+export declare function buildModelRoutingPrompt(snapshot: RoutingSnapshot, agentRouting: AgentRoutingConfig): string;

package/dist/prompt/routing.js

@@ -0,0 +1,71 @@
+/**
+ * Subagent model-routing menu for the parent agent's system prompt
+ * (docs/model-routing-design.md §4).
+ *
+ * Wording rules: the prompt must never promise more enforcement than the
+ * runtime delivers at any later moment. Absolute "choose only from this
+ * list" wording is used only for a models.json allowlist (the one catalog
+ * that cannot silently expire); every other membership source gets the
+ * conservative lag disclaimer, matching §7.1's warn-and-allow validation.
+ * Gated on spawn_agent alongside the delegation policy — children never
+ * see it.
+ */
+const MENU_MODEL_LIMIT = 12;
+export function buildModelRoutingPrompt(snapshot, agentRouting) {
+    const lines = ["## Subagent model routing"];
+    const parentTier = snapshot.parent.tier ? ` (${snapshot.parent.tier} tier)` : "";
+    lines.push(`Parent model: ${snapshot.parent.providerId} ${snapshot.parent.model}${parentTier}.`);
+    const categories = snapshot.resolvedCategories
+        .map((category) => {
+        const effort = category.thinkingLevel ? ` + ${category.thinkingLevel}` : "";
+        return `${category.name} → ${category.model}${effort}`;
+    })
+        .join(" · ");
+    if (categories) {
+        lines.push("Categories (category → what a spawn actually gets):");
+        lines.push(`  ${categories}`);
+    }
+    // Tiered models first, then untiered; cap with an explicit remainder note
+    // so truncation never reads as "nothing else exists".
+    const ordered = [...snapshot.models].sort((a, b) => {
+        const aTiered = a.tier ? 0 : 1;
+        const bTiered = b.tier ? 0 : 1;
+        return aTiered - bTiered;
+    });
+    const shown = ordered.slice(0, MENU_MODEL_LIMIT);
+    const remainder = ordered.length - shown.length;
+    const modelList = shown
+        .map((model) => (model.tier ? `${model.id} (${model.tier})` : model.id))
+        .join(" · ");
+    if (modelList) {
+        lines.push("Models on this provider, usable via per-call `model`:");
+        lines.push(`  ${modelList}`);
+        if (remainder > 0) {
+            lines.push(snapshot.authoritative
+                ? `  … and ${remainder} more in the configured allowlist (not shown); ids outside the allowlist are rejected.`
+                : `  … and ${remainder} more; any explicit id from this provider is valid.`);
+        }
+    }
+    if (snapshot.authoritative) {
+        lines.push(remainder > 0
+            ? "Choose only from the configured allowlist (shown plus the unlisted remainder); do not invent model ids."
+            : "Choose only from this list; do not invent model ids.");
+    }
+    else {
+        lines.push("(list may lag the provider; explicit ids not listed are allowed)");
+    }
+    if (agentRouting.allowCrossProvider) {
+        const runnable = snapshot.runnableProviderIds
+            .filter((id) => id !== snapshot.parent.providerId);
+        if (runnable.length > 0) {
+            lines.push(`Cross-provider routing (provider:model) is available for providers with credentials: ${runnable.join(", ")}.`);
+        }
+        else {
+            lines.push("Cross-provider routing (provider:model): no other provider has credentials in this session.");
+        }
+    }
+    else {
+        lines.push("Cross-provider routing (provider:model) is disabled in this session.");
+    }
+    return lines.join("\n");
+}

package/dist/prompt/runtime.js

@@ -8,7 +8,7 @@ const defaultGuidelines = [
     "Choose the smallest coherent change. Edit only the files required for the requested change; do not refactor or improve adjacent code unprompted.",
     "Runtime meta instructions are private control state. Use them only to adjust behavior; do not quote, mention, or paraphrase them in user-facing text.",
     "For modifications to existing code, read the file first. For brand-new files whose target path is known and does not exist, write directly without exploratory reading. Use edit for targeted changes and write for intentional full-file replacement of an existing file. Never delete and recreate a file just to overwrite it.",
-    "Prefer structured tools (glob, grep, lsp, read) over bash for search and inspection. Do not repeat a near-identical search or re-read the same file unless new evidence changes the question.",
+    "Prefer structured tools (glob, grep, read) over bash for search and inspection. Do not repeat a near-identical search or re-read the same file unless new evidence changes the question.",
     "If a tool fails, diagnose the error before switching tactics. Do not retry the identical call with identical arguments. After two equivalent failures, switch approach — re-read the file, use a different tool, rewrite the whole file with write, or ask the user.",
     "Before reporting a task complete, verify it works when verification is meaningful and cheap — run the existing test, execute the script, check the output. If no test exists, the change is purely declarative (static HTML/markdown/config), or running the code is not practical, state that explicitly rather than inventing a verification step. Do not write throwaway validation scripts to prove correctness; if there is no real check to run, report the change and stop.",
 ];

package/dist/prompt/task-reminders.d.ts

@@ -1,6 +1,26 @@
 import type { TaskType } from "../agent/task-classifier.js";
+import { type RoutableModelEntry } from "../agent/routing-catalog.js";
 export interface TaskReminderOptions {
     /** Whether this agent has the delegation tools (parent agents only). */
     canDelegate?: boolean;
 }
 export declare function reminderForTaskType(taskType: TaskType, options?: TaskReminderOptions): string | undefined;
+/**
+ * Deterministic detector for an explicit user request for a coordinated
+ * multi-agent run. Three rounds of prompt wording lost to the model's
+ * "agent team = parallel spawns" prior in live tests (opus-4.8, 2026-07-06);
+ * per the task-reminder principle above, a reminder injected at the decision
+ * turn is the lever that actually works — the harness remembers so the model
+ * does not have to.
+ */
+/**
+ * User-named model resolution (model-routing design v3.6): when the user's
+ * message names a model that exists in the routable catalog, hand the main
+ * agent the EXACT provider:model id at the decision point. The catalog is a
+ * closed set, so matching is deterministic — the model must never retype an
+ * id from priors when the harness can resolve it ("gpt 5.6 sol" ->
+ * openai:gpt-5.6-sol; a Grok-4.5 parent invented "openai:gpt-5.6" without
+ * this, 2026-07-12 live case). Silent on no match: zero standing noise.
+ */
+export declare function userNamedModelReminder(input: string | import("../types.js").ContentPart[], routableModels: RoutableModelEntry[] | undefined, canSpawn: boolean): string | undefined;
+export declare function orchestrationRequestReminder(input: string | import("../types.js").ContentPart[], canRunWorkflow: boolean): string | undefined;