@bubblebrain-ai/bubble 0.0.35 → 0.0.36

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,6 +32,8 @@ 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 {
@@ -62,6 +65,7 @@ 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;

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");
@@ -204,6 +205,9 @@ export class UserConfig {
     getAgentCategories() {
         return sanitizeAgentCategories(this.data.agentCategories);
     }
+    getAgentRouting() {
+        return sanitizeAgentRouting(this.data.agentRouting);
+    }
     getSubagents() {
         return sanitizeSubagentsConfig(this.data.subagents) ?? {};
     }

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>;

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

@@ -0,0 +1,108 @@
+import { constants as fsConstants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { GrokRuntimeError } from "./grok-errors.js";
+export const GROK_PINNED_VERSION = "0.2.93";
+export const GROK_PINNED_SHA256 = "2a97ba675bd992aa9b981e2e83776460d94f469b510c0b8efe28b50d236d767c";
+async function isExecutable(path) {
+    try {
+        await access(path, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolveGrokBinary(deps = {}) {
+    const candidates = [];
+    if (deps.binaryPath)
+        candidates.push(deps.binaryPath);
+    if (!deps.binaryPath) {
+        const home = deps.userHome ?? homedir();
+        candidates.push(join(home, ".local", "bin", "grok"), join(home, ".grok", "bin", "grok"));
+        for (const entry of (deps.pathEnv ?? process.env.PATH ?? "").split(delimiter)) {
+            if (entry && isAbsolute(entry))
+                candidates.push(join(entry, "grok"));
+        }
+    }
+    for (const candidate of [...new Set(candidates)]) {
+        if (!isAbsolute(candidate) || !(await isExecutable(candidate)))
+            continue;
+        try {
+            return await realpath(candidate);
+        }
+        catch {
+            // Continue to the next independently verified candidate.
+        }
+    }
+    throw new GrokRuntimeError("binary_not_found", "Install the pinned Grok Build CLI (0.2.93) to use Grok subscription login.");
+}
+export async function sha256File(path) {
+    return await new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const input = createReadStream(path);
+        input.on("error", reject);
+        input.on("data", (chunk) => hash.update(chunk));
+        input.on("end", () => resolve(hash.digest("hex")));
+    });
+}
+/**
+ * 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 async function verifyGrokBinaryAncestors(path, uid = process.getuid?.()) {
+    if (uid === undefined) {
+        throw new GrokRuntimeError("binary_untrusted", "The Grok CLI path owner could not be verified.");
+    }
+    let current = dirname(path);
+    while (true) {
+        const metadata = await stat(current);
+        if (!metadata.isDirectory() || (metadata.uid !== uid && metadata.uid !== 0) || (metadata.mode & 0o022) !== 0) {
+            throw new GrokRuntimeError("binary_untrusted", "The Grok CLI must be located under directories writable only by the current user or root.");
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return;
+        current = parent;
+    }
+}
+export function parseGrokVersion(output) {
+    return /^grok\s+(\d+\.\d+\.\d+)(?:\s|$)/m.exec(output.trim())?.[1];
+}
+export async function verifyGrokBinary(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const arch = deps.arch ?? process.arch;
+    if (platform !== "darwin" || arch !== "arm64") {
+        throw new GrokRuntimeError("unsupported_platform", "Grok Subscription is available on macOS Apple Silicon only.");
+    }
+    const path = await resolveGrokBinary(deps);
+    const metadata = await stat(path);
+    const uid = deps.uid ?? process.getuid?.();
+    if (!metadata.isFile() || uid === undefined || metadata.uid !== uid) {
+        throw new GrokRuntimeError("binary_untrusted", "The Grok CLI must be a regular file owned by the current user.");
+    }
+    if ((metadata.mode & 0o111) === 0 || (metadata.mode & 0o022) !== 0) {
+        throw new GrokRuntimeError("binary_untrusted", "The Grok CLI must be executable and not writable by group or other users.");
+    }
+    await verifyGrokBinaryAncestors(path, uid);
+    // Never execute an untrusted candidate merely to ask it for its version.
+    const sha256 = await (deps.hashFile ?? sha256File)(path);
+    const expectedSha256 = deps.expectedSha256 ?? GROK_PINNED_SHA256;
+    if (sha256.toLowerCase() !== expectedSha256.toLowerCase()) {
+        throw new GrokRuntimeError("binary_hash_mismatch", "The Grok CLI checksum does not match Bubble's pinned build.");
+    }
+    const expectedVersion = deps.expectedVersion ?? GROK_PINNED_VERSION;
+    const output = await deps.readVersion?.(path);
+    if (output === undefined) {
+        throw new GrokRuntimeError("protocol_error", "A version reader is required to verify the Grok CLI.");
+    }
+    const version = parseGrokVersion(output);
+    if (version !== expectedVersion) {
+        throw new GrokRuntimeError("binary_version_mismatch", `Grok CLI ${expectedVersion} is required.`);
+    }
+    return { path, version, sha256: sha256.toLowerCase() };
+}

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

@@ -0,0 +1,7 @@
+export type GrokRuntimeErrorCode = "unsupported_platform" | "binary_not_found" | "binary_untrusted" | "binary_version_mismatch" | "binary_hash_mismatch" | "profile_unsafe" | "profile_locked" | "preflight_failed" | "not_authenticated" | "protocol_error" | "policy_violation" | "process_crashed" | "cancelled" | "disposed";
+export declare class GrokRuntimeError extends Error {
+    readonly code: GrokRuntimeErrorCode;
+    readonly diagnostic?: string;
+    constructor(code: GrokRuntimeErrorCode, message: string, diagnostic?: string);
+}
+export declare function safeErrorMessage(error: unknown): string;