@bubblebrain-ai/bubble 0.0.63 → 0.0.64

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;

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

@@ -0,0 +1,15 @@
+export class GrokRuntimeError extends Error {
+    code;
+    diagnostic;
+    constructor(code, message, diagnostic) {
+        super(message);
+        this.name = "GrokRuntimeError";
+        this.code = code;
+        this.diagnostic = diagnostic;
+    }
+}
+export function safeErrorMessage(error) {
+    if (error instanceof GrokRuntimeError)
+        return error.message;
+    return "Grok runtime is unavailable.";
+}

package/dist/external-runtime/grok-input-policy.d.ts

@@ -0,0 +1,58 @@
+/** Commands that remain local while a Grok subscription session is bound. */
+export declare const GROK_LOCAL_COMMAND_HELP: readonly [{
+    readonly name: "help";
+    readonly usage: "/help";
+    readonly description: "Show commands";
+}, {
+    readonly name: "model";
+    readonly usage: "/model";
+    readonly description: "Choose the Grok subscription model and reasoning effort";
+}, {
+    readonly name: "provider";
+    readonly usage: "/provider";
+    readonly description: "Start a fresh native session and manage providers";
+}, {
+    readonly name: "login";
+    readonly usage: "/login [openai|grok]";
+    readonly description: "Start a fresh session with that login";
+}, {
+    readonly name: "logout";
+    readonly usage: "/logout grok";
+    readonly description: "Remove this device's local Grok login";
+}, {
+    readonly name: "session";
+    readonly usage: "/session";
+    readonly description: "Browse sessions";
+}, {
+    readonly name: "theme";
+    readonly usage: "/theme";
+    readonly description: "Pick the color theme";
+}, {
+    readonly name: "feedback";
+    readonly usage: "/feedback";
+    readonly description: "Send product feedback";
+}, {
+    readonly name: "quit";
+    readonly usage: "/quit";
+    readonly description: "Exit Bubble";
+}, {
+    readonly name: "exit";
+    readonly usage: "/exit";
+    readonly description: "Exit Bubble";
+}];
+export declare const GROK_LOCAL_SLASH_COMMANDS: ReadonlySet<string>;
+export type GrokInputDecision = {
+    kind: "prompt";
+} | {
+    kind: "local_command";
+    command: string;
+} | {
+    kind: "blocked";
+    message: string;
+};
+export declare function grokSlashCommandName(input: string): string | undefined;
+export declare function isGrokLocalSlashCommand(command: string): boolean;
+export declare function classifyGrokInput(input: {
+    text: string;
+    imageCount: number;
+}): GrokInputDecision;