@bubblebrain-ai/bubble 0.0.34 → 0.0.36

package/dist/approval/controller.js

@@ -87,6 +87,17 @@ export class PermissionAwareApprovalController {
                 return { tool: "Lsp", path: req.path, cwd: this.options.cwd };
             case "agent_profile":
                 return { tool: "AgentProfile" };
+            case "external_tool": {
+                const command = externalCommand(req.rawInput);
+                if (req.kind === "execute" && command !== undefined) {
+                    return { tool: "Bash", command };
+                }
+                const path = req.locations?.[0]?.path;
+                if ((req.kind === "edit" || req.kind === "delete" || req.kind === "move") && path) {
+                    return { tool: "Edit", path, cwd: this.options.cwd };
+                }
+                return { tool: req.title.trim() || req.kind.trim() || "ExternalTool" };
+            }
         }
     }
     checkRequestRules(req) {
@@ -176,6 +187,8 @@ function approvalTarget(req) {
             return "Lsp";
         case "agent_profile":
             return "AgentProfile";
+        case "external_tool":
+            return req.title.trim() || req.kind.trim() || "ExternalTool";
     }
 }
 function summarizeApprovalRequest(req) {
@@ -192,5 +205,20 @@ function summarizeApprovalRequest(req) {
             return { type: req.type, path: req.path, operation: req.operation };
         case "agent_profile":
             return { type: req.type, name: req.name, path: req.path, contentHash: req.contentHash };
+        case "external_tool":
+            return {
+                type: req.type,
+                toolCallId: req.toolCallId,
+                title: req.title,
+                kind: req.kind,
+                locations: req.locations,
+                rawInput: req.rawInput,
+            };
     }
 }
+function externalCommand(rawInput) {
+    if (typeof rawInput !== "object" || rawInput === null || Array.isArray(rawInput))
+        return undefined;
+    const command = rawInput.command;
+    return typeof command === "string" ? command : undefined;
+}

package/dist/approval/tool-helper.js

@@ -32,5 +32,7 @@ function approvalRequestLabel(req) {
             return `LSP ${req.operation} on ${req.path}`;
         case "agent_profile":
             return `Project agent profile "${req.name}"`;
+        case "external_tool":
+            return `External tool "${req.title}"`;
     }
 }

package/dist/approval/types.d.ts

@@ -61,7 +61,27 @@ export interface AgentProfileApprovalRequest {
     /** First lines of the profile prompt so the user can judge it. */
     promptPreview: string;
 }
-export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest;
+/**
+ * Permission gate for a tool exposed by an external ACP runtime.
+ *
+ * Keep this structural rather than importing ACP SDK types so the approval
+ * layer remains provider-agnostic. External runtimes are responsible for
+ * copying the relevant, user-visible fields from the protocol request.
+ */
+export interface ExternalToolApprovalRequest {
+    type: "external_tool";
+    toolCallId: string;
+    /** Human-readable tool name supplied by the external runtime. */
+    title: string;
+    /** ACP tool category (for example execute, edit, read, or other). */
+    kind: string;
+    rawInput?: unknown;
+    locations?: Array<{
+        path: string;
+        line?: number | null;
+    }>;
+}
+export type ApprovalRequest = EditApprovalRequest | WriteApprovalRequest | PatchApprovalRequest | BashApprovalRequest | LspApprovalRequest | AgentProfileApprovalRequest | ExternalToolApprovalRequest;
 export type ApprovalDecision = {
     action: "approve";
     feedback?: string;

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 /**
  * CLI argument parsing.
  */
-import type { PermissionMode, ThinkingLevel } from "./types.js";
+import { type PermissionMode, type ThinkingLevel } from "./types.js";
 export type CliCommand = "default" | "serve" | "update";
 export interface CliArgs {
     command: CliCommand;

package/dist/cli.js

@@ -1,6 +1,7 @@
 /**
  * CLI argument parsing.
  */
+import { THINKING_LEVELS } from "./types.js";
 import { isThinkingLevel } from "./variant/thinking-level.js";
 export function parseArgs(argv) {
     const args = {
@@ -102,7 +103,7 @@ Options (default):
   -r, --resume             Resume a previous session (latest by default)
   --session <name>         Session name to create or resume
   --reasoning              Enable reasoning mode at medium effort
-  --reasoning-effort <l>   Set reasoning effort: off|minimal|low|medium|high|xhigh|max
+  --reasoning-effort <l>   Set reasoning effort: ${THINKING_LEVELS.join("|")}
   --plan                   Start in plan mode (read-only investigation; propose before executing)
   --dangerously-skip-permissions
                            Enable bypass mode (auto-approve EVERY tool; disables all safety prompts)

package/dist/config.d.ts

@@ -4,6 +4,7 @@
  * Uses a single JSON file in Bubble home, normally ~/.bubble/config.json.
  */
 import { type AgentCategoriesConfig } from "./agent/categories.js";
+import { type AgentRoutingConfig } from "./agent/routing-catalog.js";
 import type { ProviderProfile } from "./provider-registry.js";
 import type { ThinkingLevel } from "./types.js";
 export type ThemeMode = "auto" | "light" | "dark";
@@ -31,13 +32,13 @@ export interface UserConfigData {
     providers?: ProviderProfile[];
     defaultProvider?: string;
     agentCategories?: AgentCategoriesConfig;
+    /** Subagent model-routing knobs: autoTier (default true), allowCrossProvider (default true). */
+    agentRouting?: Partial<AgentRoutingConfig>;
     subagents?: SubagentsUserConfig;
 }
 export interface SubagentsUserConfig {
     /** Global cap on concurrently running children. Default 8. */
     maxActiveSubagents?: number;
-    /** Absolute per-child soft token cap. Default 200000. */
-    childTokenCap?: number;
 }
 export declare class UserConfig {
     private data;
@@ -64,9 +65,10 @@ export declare class UserConfig {
     setThemeMode(mode: ThemeMode): void;
     setThemeOverrides(overrides: Record<string, string>): void;
     getAgentCategories(): AgentCategoriesConfig;
+    getAgentRouting(): AgentRoutingConfig;
     getSubagents(): SubagentsUserConfig;
 }
-export declare function shouldProbeTerminalTheme(config: ThemeConfig): boolean;
+export declare function shouldProbeTerminalTheme(_config: ThemeConfig): boolean;
 export declare function effectiveThemeModeForTerminal(config: ThemeConfig, detectedTheme: Exclude<ThemeMode, "auto">): ThemeMode;
 /** Mask an API key for safe display. */
 export declare function maskKey(key: string): string;

package/dist/config.js

@@ -7,6 +7,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getBubbleHome } from "./bubble-home.js";
 import { sanitizeAgentCategories } from "./agent/categories.js";
+import { sanitizeAgentRouting } from "./agent/routing-catalog.js";
 const HIDDEN_PROVIDER_IDS = new Set(["openrouter", "openai-codex"]);
 function getConfigPath() {
     return join(getBubbleHome(), "config.json");
@@ -45,9 +46,6 @@ function sanitizeSubagentsConfig(value) {
     if (typeof raw.maxActiveSubagents === "number" && Number.isFinite(raw.maxActiveSubagents)) {
         out.maxActiveSubagents = Math.max(1, Math.floor(raw.maxActiveSubagents));
     }
-    if (typeof raw.childTokenCap === "number" && Number.isFinite(raw.childTokenCap)) {
-        out.childTokenCap = Math.max(1_000, Math.floor(raw.childTokenCap));
-    }
     return Object.keys(out).length > 0 ? out : undefined;
 }
 function sanitizeTheme(value) {
@@ -207,12 +205,19 @@ export class UserConfig {
     getAgentCategories() {
         return sanitizeAgentCategories(this.data.agentCategories);
     }
+    getAgentRouting() {
+        return sanitizeAgentRouting(this.data.agentRouting);
+    }
     getSubagents() {
         return sanitizeSubagentsConfig(this.data.subagents) ?? {};
     }
 }
-export function shouldProbeTerminalTheme(config) {
-    return config.mode === "auto" || isLegacyBareDarkTheme(config);
+export function shouldProbeTerminalTheme(_config) {
+    // Always probe: even a forced theme needs the real terminal background to
+    // decide between inheriting it (theme matches the terminal) and painting
+    // its own canvas (forced theme mismatching the terminal, where the
+    // palette's foregrounds would otherwise be unreadable).
+    return true;
 }
 export function effectiveThemeModeForTerminal(config, detectedTheme) {
     if (isLegacyBareDarkTheme(config) && detectedTheme === "light")

package/dist/context/compact-llm.d.ts

@@ -7,11 +7,11 @@
  * fails.
  */
 import type { CompactOptions, CompactResult } from "./compact.js";
-import type { Message, Provider, ProviderMessage } from "../types.js";
+import type { Message, Provider, ProviderMessage, ThinkingLevel } from "../types.js";
 export interface LLMCompactOptions extends CompactOptions {
     provider: Provider;
     model: string;
-    thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    thinkingLevel?: ThinkingLevel;
 }
 export declare const COMPACT_SYSTEM_PROMPT = "You are a conversation summarizer. Your job is to produce a structured\nsummary of an earlier portion of a software-engineering assistant's\nconversation so that the assistant can continue working without the full\nhistory. Preserve fidelity over brevity where the user's intent, file\npaths, or decisions are concerned. Output ONLY the summary, no preamble.";
 export declare const COMPACT_INSTRUCTIONS = "Summarize the conversation above using exactly these 9 sections, each\npreceded by the literal heading on its own line. If a section has no\ncontent, write \"None\".\n\n1. Primary Request and Intent\n   - What the user ultimately wants, in their own framing.\n\n2. Key Technical Concepts\n   - Libraries, frameworks, architectural patterns referenced.\n\n3. Files and Code Sections\n   - Files read, written, or discussed. Include full paths and a one-line note.\n\n4. Errors and Fixes\n   - Bugs encountered and how they were resolved.\n\n5. Problem Solving\n   - Non-trivial debugging or design decisions.\n\n6. All User Messages\n   - Every user message, verbatim, in order. Do not summarize here.\n\n7. Pending Tasks\n   - Work that was planned but not yet completed.\n\n8. Current Work\n   - What was being actively worked on when the summary was taken.\n\n9. Optional Next Step\n   - The single most natural next action, if obvious.";

package/dist/external-runtime/grok-acp.d.ts

@@ -0,0 +1,56 @@
+import * as acp from "@agentclientprotocol/sdk";
+import type { GrokProfile } from "./grok-profile.js";
+import type { GrokSpawn } from "./grok-process.js";
+import { GrokRuntimeError } from "./grok-errors.js";
+export interface GrokAcpHandlers {
+    onSessionUpdate(notification: acp.SessionNotification): void | Promise<void>;
+    onPermissionRequest(params: acp.RequestPermissionRequest): Promise<string | undefined>;
+    onPermissionViolation(sessionId?: string): void | Promise<void>;
+    onCrash(error: GrokRuntimeError): void;
+}
+export interface GrokAcpClient {
+    initialize(): Promise<void>;
+    newSession(): Promise<GrokAcpSessionState>;
+    loadSession(sessionId: string): Promise<GrokAcpSessionState>;
+    setModel(sessionId: string, modelId: string): Promise<GrokAcpModelState | undefined>;
+    prompt(sessionId: string, prompt: string, generation: number, signal?: AbortSignal): Promise<acp.PromptResponse>;
+    cancel(sessionId: string): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface GrokAcpModelInfo {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface GrokAcpModelState {
+    currentModelId: string;
+    availableModels: GrokAcpModelInfo[];
+}
+export interface GrokAcpSessionState {
+    id: string;
+    models?: GrokAcpModelState;
+}
+export type GrokAcpFactory = (options: {
+    binary: string;
+    profile: GrokProfile;
+    workspace: string;
+    modelId?: string;
+    reasoningEffort?: string;
+    permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
+    env: NodeJS.ProcessEnv;
+    spawn: GrokSpawn;
+    handlers: GrokAcpHandlers;
+}) => GrokAcpClient;
+export declare const GROK_ACP_ARGS: (workspace: string, modelId?: string, reasoningEffort?: string, permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions") => readonly string[];
+/**
+ * Reassemble stderr before redaction so secrets split across arbitrary child
+ * process chunks cannot bypass token patterns. If the private in-memory raw
+ * buffer exceeds its cap, discard it wholesale and expose only a fixed notice.
+ */
+export declare class GrokDiagnosticBuffer {
+    private raw;
+    private overflowed;
+    append(chunk: Buffer | string): void;
+    sanitized(maxLength?: number): string;
+}
+export declare const createDefaultGrokAcpClient: GrokAcpFactory;

package/dist/external-runtime/grok-acp.js

@@ -0,0 +1,386 @@
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+import { sanitizeGrokDiagnostic } from "./grok-process.js";
+import { GrokRuntimeError } from "./grok-errors.js";
+import { createBoundedGrokNdjsonStream } from "./grok-ndjson.js";
+export const GROK_ACP_ARGS = (workspace, modelId, reasoningEffort, permissionMode = "default") => [
+    "--no-auto-update",
+    "--cwd",
+    workspace,
+    "--no-memory",
+    "--no-subagents",
+    "--no-plan",
+    "--disable-web-search",
+    "--tools",
+    "Read,Edit,Grep,Bash",
+    "--permission-mode",
+    permissionMode,
+    "--sandbox",
+    "strict",
+    ...(modelId ? ["--model", modelId] : []),
+    ...(modelId && reasoningEffort && reasoningEffort !== "off" ? ["--reasoning-effort", reasoningEffort] : []),
+    "agent",
+    "--no-leader",
+    "stdio",
+];
+function processCrash(code, signal, diagnostic) {
+    const reason = code === null ? `signal ${signal ?? "unknown"}` : `exit code ${code}`;
+    return new GrokRuntimeError("process_crashed", `Grok runtime stopped unexpectedly (${reason}).`, diagnostic || undefined);
+}
+const MAX_GROK_STDERR_RAW_BYTES = 64 * 1024;
+/**
+ * Reassemble stderr before redaction so secrets split across arbitrary child
+ * process chunks cannot bypass token patterns. If the private in-memory raw
+ * buffer exceeds its cap, discard it wholesale and expose only a fixed notice.
+ */
+export class GrokDiagnosticBuffer {
+    raw = "";
+    overflowed = false;
+    append(chunk) {
+        if (this.overflowed)
+            return;
+        const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk;
+        if (Buffer.byteLength(this.raw, "utf8") + Buffer.byteLength(text, "utf8") > MAX_GROK_STDERR_RAW_BYTES) {
+            this.raw = "";
+            this.overflowed = true;
+            return;
+        }
+        this.raw += text;
+    }
+    sanitized(maxLength = 2048) {
+        if (this.overflowed)
+            return "Grok ACP stderr exceeded the safe diagnostic limit.";
+        return sanitizeGrokDiagnostic(this.raw, maxLength);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseModelState(value) {
+    if (!isRecord(value) || typeof value.currentModelId !== "string" || !Array.isArray(value.availableModels))
+        return undefined;
+    const availableModels = [];
+    for (const item of value.availableModels) {
+        if (!isRecord(item))
+            return undefined;
+        const id = typeof item.modelId === "string" ? item.modelId : typeof item.id === "string" ? item.id : undefined;
+        if (!id)
+            return undefined;
+        availableModels.push({
+            id,
+            name: typeof item.name === "string" ? item.name : id,
+            ...(typeof item.description === "string" ? { description: item.description } : {}),
+        });
+    }
+    if (availableModels.length === 0 || !availableModels.some((model) => model.id === value.currentModelId))
+        return undefined;
+    return { currentModelId: value.currentModelId, availableModels };
+}
+function parseSessionResponse(value, fallbackId) {
+    if (!isRecord(value))
+        throw new GrokRuntimeError("protocol_error", "Grok ACP returned an invalid session response.");
+    const id = typeof value.sessionId === "string" ? value.sessionId : fallbackId;
+    if (!id)
+        throw new GrokRuntimeError("protocol_error", "Grok ACP session response omitted its session ID.");
+    const models = value.models === undefined ? undefined : parseModelState(value.models);
+    if (value.models !== undefined && !models) {
+        throw new GrokRuntimeError("protocol_error", "Grok ACP returned an invalid model catalog.");
+    }
+    return { id, ...(models ? { models } : {}) };
+}
+function parseInterceptedSessionUpdate(message) {
+    if (!("method" in message) || message.method !== acp.methods.client.session.update)
+        return undefined;
+    if ("id" in message) {
+        throw new GrokRuntimeError("protocol_error", "Grok ACP sent session/update as a request.");
+    }
+    if (!isRecord(message.params)
+        || typeof message.params.sessionId !== "string"
+        || !isRecord(message.params.update)
+        || typeof message.params.update.sessionUpdate !== "string") {
+        throw new GrokRuntimeError("protocol_error", "Grok ACP sent an invalid session update.");
+    }
+    if (message.params._meta !== undefined && message.params._meta !== null && !isRecord(message.params._meta)) {
+        throw new GrokRuntimeError("protocol_error", "Grok ACP sent invalid session metadata.");
+    }
+    return message.params;
+}
+async function settlesWithin(promise, timeoutMs) {
+    return await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs);
+        timer.unref?.();
+        void promise.then(() => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
+class DefaultGrokAcpClient {
+    options;
+    child;
+    connection;
+    stderr = new GrokDiagnosticBuffer();
+    disposed = false;
+    initialized = false;
+    crashReported = false;
+    crashError;
+    exited;
+    notificationTail = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        const child = options.spawn(options.binary, GROK_ACP_ARGS(options.workspace, options.modelId, options.reasoningEffort, options.permissionMode), {
+            cwd: options.workspace,
+            env: options.env,
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        this.exited = new Promise((resolve) => {
+            child.once("exit", () => resolve());
+            child.once("error", () => resolve());
+        });
+        if (!child.stdin || !child.stdout) {
+            child.kill();
+            throw new GrokRuntimeError("protocol_error", "Grok ACP did not provide stdio pipes.");
+        }
+        child.stderr?.on("data", (chunk) => {
+            this.stderr.append(chunk);
+        });
+        child.once("error", () => this.reportCrash(processCrash(null, null, this.stderr.sanitized())));
+        child.once("exit", (code, signal) => {
+            if (!this.disposed)
+                this.reportCrash(processCrash(code, signal, this.stderr.sanitized()));
+        });
+        const rejectHostCapability = async (sessionId) => {
+            await this.enqueuePermissionViolation(sessionId);
+            throw acp.RequestError.requestCancelled(undefined, "This host capability is not exposed by Bubble's Grok runtime.");
+        };
+        const app = acp
+            .client({ name: "bubble-grok-runtime" })
+            .onRequest(acp.methods.client.session.requestPermission, async ({ params }) => {
+            const optionId = await options.handlers.onPermissionRequest(params);
+            if (!optionId || !params.options.some((option) => option.optionId === optionId)) {
+                return { outcome: { outcome: "cancelled" } };
+            }
+            return { outcome: { outcome: "selected", optionId } };
+        })
+            .onRequest(acp.methods.client.fs.readTextFile, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.fs.writeTextFile, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.terminal.create, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.terminal.output, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.terminal.release, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.terminal.waitForExit, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.terminal.kill, async ({ params }) => await rejectHostCapability(params.sessionId))
+            .onRequest(acp.methods.client.elicitation.create, async ({ params }) => await rejectHostCapability("sessionId" in params && typeof params.sessionId === "string" ? params.sessionId : undefined))
+            .onNotification(acp.methods.client.elicitation.complete, () => this.enqueuePermissionViolation(undefined));
+        const input = Writable.toWeb(child.stdin);
+        const output = Readable.toWeb(child.stdout);
+        const stream = createBoundedGrokNdjsonStream(input, output, {
+            interceptIncoming: (message) => {
+                const notification = parseInterceptedSessionUpdate(message);
+                if (!notification)
+                    return false;
+                void this.enqueueSessionUpdate(notification);
+                return true;
+            },
+            onProtocolError: (error) => {
+                this.reportCrash(error);
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGTERM");
+            },
+        });
+        this.connection = app.connect(stream);
+    }
+    reportCrash(error) {
+        if (this.crashReported || this.disposed)
+            return;
+        this.crashReported = true;
+        this.crashError = error;
+        this.options.handlers.onCrash(error);
+    }
+    enqueueSessionUpdate(notification) {
+        const work = this.notificationTail.then(async () => {
+            try {
+                await this.options.handlers.onSessionUpdate(notification);
+            }
+            catch (cause) {
+                const error = cause instanceof GrokRuntimeError
+                    ? cause
+                    : new GrokRuntimeError("protocol_error", "Grok ACP notification handling failed.");
+                this.reportCrash(error);
+                if (this.child.exitCode === null && this.child.signalCode === null)
+                    this.child.kill("SIGTERM");
+            }
+        });
+        this.notificationTail = work;
+        return work;
+    }
+    enqueuePermissionViolation(sessionId) {
+        const work = this.notificationTail.then(async () => {
+            try {
+                await this.options.handlers.onPermissionViolation(sessionId);
+            }
+            catch (cause) {
+                const error = cause instanceof GrokRuntimeError
+                    ? cause
+                    : new GrokRuntimeError("protocol_error", "Grok ACP policy handling failed.");
+                this.reportCrash(error);
+                if (this.child.exitCode === null && this.child.signalCode === null)
+                    this.child.kill("SIGTERM");
+            }
+        });
+        this.notificationTail = work;
+        return work;
+    }
+    async drainNotifications() {
+        // Incoming requests/notifications are dispatched independently from the
+        // response promise. Let already-parsed work join the ordered tail before
+        // deciding that initialize/new/load completed safely.
+        await new Promise((resolve) => setImmediate(resolve));
+        await this.notificationTail;
+        if (this.crashError)
+            throw this.crashError;
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        let response;
+        try {
+            response = await this.connection.agent.request(acp.methods.agent.initialize, {
+                protocolVersion: acp.PROTOCOL_VERSION,
+                clientCapabilities: { session: { configOptions: { boolean: {} } } },
+                clientInfo: { name: "bubble", title: "Bubble", version: "1" },
+            });
+            await this.drainNotifications();
+        }
+        catch {
+            if (this.crashError)
+                throw this.crashError;
+            throw new GrokRuntimeError("protocol_error", "Grok ACP initialization failed.", this.stderr.sanitized() || undefined);
+        }
+        if (response.protocolVersion !== acp.PROTOCOL_VERSION) {
+            throw new GrokRuntimeError("protocol_error", "Grok ACP returned an unsupported protocol version.");
+        }
+        if (response.agentCapabilities?.loadSession !== true) {
+            throw new GrokRuntimeError("protocol_error", "Grok ACP must support session loading for isolated turn rotation.");
+        }
+        const authMethods = response.authMethods ?? [];
+        const cached = authMethods.find((method) => method.id === "cached_token");
+        if (!cached) {
+            throw new GrokRuntimeError("not_authenticated", "Sign in to Grok before starting a subscription session.");
+        }
+        try {
+            await this.connection.agent.request(acp.methods.agent.authenticate, { methodId: "cached_token" });
+            await this.drainNotifications();
+        }
+        catch {
+            if (this.crashError)
+                throw this.crashError;
+            throw new GrokRuntimeError("not_authenticated", "The cached Grok login is unavailable or expired.");
+        }
+        this.initialized = true;
+    }
+    async newSession() {
+        await this.initialize();
+        try {
+            const response = await this.connection.agent.request("session/new", {
+                cwd: this.options.workspace,
+                additionalDirectories: [],
+                mcpServers: [],
+            });
+            await this.drainNotifications();
+            return parseSessionResponse(response);
+        }
+        catch (error) {
+            if (this.crashError)
+                throw this.crashError;
+            throw error;
+        }
+    }
+    async loadSession(sessionId) {
+        await this.initialize();
+        try {
+            const response = await this.connection.agent.request("session/load", {
+                sessionId,
+                cwd: this.options.workspace,
+                additionalDirectories: [],
+                mcpServers: [],
+            });
+            await this.drainNotifications();
+            return parseSessionResponse(response, sessionId);
+        }
+        catch (error) {
+            if (this.crashError)
+                throw this.crashError;
+            throw error;
+        }
+    }
+    async setModel(sessionId, modelId) {
+        await this.initialize();
+        try {
+            const response = await this.connection.agent.request("session/set_model", { sessionId, modelId });
+            await this.drainNotifications();
+            if (!isRecord(response))
+                throw new GrokRuntimeError("protocol_error", "Grok ACP returned an invalid model switch response.");
+            if (response.models === undefined)
+                return undefined;
+            const models = parseModelState(response.models);
+            if (!models)
+                throw new GrokRuntimeError("protocol_error", "Grok ACP returned an invalid model catalog.");
+            return models;
+        }
+        catch (error) {
+            if (this.crashError)
+                throw this.crashError;
+            throw error;
+        }
+    }
+    async prompt(sessionId, prompt, generation, signal) {
+        await this.initialize();
+        try {
+            const response = await this.connection.agent.request(acp.methods.agent.session.prompt, {
+                sessionId,
+                prompt: [{ type: "text", text: prompt }],
+                _meta: { bubbleGeneration: generation },
+            }, { cancellationSignal: signal });
+            // The SDK dispatches notification handlers independently from response
+            // settlement. Yield once so all notifications parsed before the prompt
+            // response can join our ordered tail, then drain it before rotating the
+            // sidecar at the turn boundary.
+            await new Promise((resolve) => setImmediate(resolve));
+            await this.notificationTail;
+            return response;
+        }
+        catch (error) {
+            // Stream closure can reject the request one microtask before ChildProcess
+            // emits exit. Give the exit handler a chance to preserve the safe crash
+            // diagnostic instead of collapsing it into a generic protocol error.
+            await new Promise((resolve) => setTimeout(resolve, 25));
+            if (this.crashError)
+                throw this.crashError;
+            throw error;
+        }
+    }
+    async cancel(sessionId) {
+        if (this.disposed)
+            return;
+        await this.connection.agent.notify(acp.methods.agent.session.cancel, { sessionId });
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.connection.close();
+        this.child.stdin?.end();
+        let stopped = await settlesWithin(this.exited, 250);
+        if (!stopped && this.child.exitCode === null && this.child.signalCode === null) {
+            this.child.kill("SIGTERM");
+            stopped = await settlesWithin(this.exited, 1_000);
+        }
+        if (!stopped && this.child.exitCode === null && this.child.signalCode === null) {
+            this.child.kill("SIGKILL");
+            await settlesWithin(this.exited, 1_000);
+        }
+    }
+}
+export const createDefaultGrokAcpClient = (options) => new DefaultGrokAcpClient(options);

package/dist/external-runtime/grok-binary.d.ts

@@ -0,0 +1,25 @@
+import type { ExternalRuntimeBinaryInfo } from "./types.js";
+export declare const GROK_PINNED_VERSION = "0.2.93";
+export declare const GROK_PINNED_SHA256 = "2a97ba675bd992aa9b981e2e83776460d94f469b510c0b8efe28b50d236d767c";
+export interface GrokBinaryDependencies {
+    platform?: NodeJS.Platform;
+    arch?: string;
+    uid?: number;
+    binaryPath?: string;
+    pathEnv?: string;
+    userHome?: string;
+    expectedVersion?: string;
+    expectedSha256?: string;
+    hashFile?: (path: string) => Promise<string>;
+    readVersion?: (path: string) => Promise<string>;
+}
+export declare function resolveGrokBinary(deps?: GrokBinaryDependencies): Promise<string>;
+export declare function sha256File(path: string): Promise<string>;
+/**
+ * The executable's directory chain is part of the trust boundary. Even a
+ * read-only, user-owned file can be swapped between verification and spawn if
+ * another local user can rename a writable ancestor directory entry.
+ */
+export declare function verifyGrokBinaryAncestors(path: string, uid?: number | undefined): Promise<void>;
+export declare function parseGrokVersion(output: string): string | undefined;
+export declare function verifyGrokBinary(deps?: GrokBinaryDependencies): Promise<ExternalRuntimeBinaryInfo>;