@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/external-runtime/grok-input-policy.js

@@ -0,0 +1,52 @@
+/** Commands that remain local while a Grok subscription session is bound. */
+export const GROK_LOCAL_COMMAND_HELP = [
+    { name: "help", usage: "/help", description: "Show commands" },
+    { name: "model", usage: "/model", description: "Choose the Grok subscription model and reasoning effort" },
+    { name: "provider", usage: "/provider", description: "Start a fresh native session and manage providers" },
+    { name: "login", usage: "/login [openai|grok]", description: "Start a fresh session with that login" },
+    { name: "logout", usage: "/logout grok", description: "Remove this device's local Grok login" },
+    { name: "session", usage: "/session", description: "Browse sessions" },
+    { name: "theme", usage: "/theme", description: "Pick the color theme" },
+    { name: "feedback", usage: "/feedback", description: "Send product feedback" },
+    { name: "quit", usage: "/quit", description: "Exit Bubble" },
+    { name: "exit", usage: "/exit", description: "Exit Bubble" },
+];
+export const GROK_LOCAL_SLASH_COMMANDS = new Set(GROK_LOCAL_COMMAND_HELP.map((command) => command.name));
+export function grokSlashCommandName(input) {
+    const match = /^\s*\/([^\s/]+)/.exec(input);
+    return match?.[1]?.toLowerCase();
+}
+export function isGrokLocalSlashCommand(command) {
+    return GROK_LOCAL_SLASH_COMMANDS.has(command.toLowerCase());
+}
+export function classifyGrokInput(input) {
+    if (input.imageCount > 0) {
+        return {
+            kind: "blocked",
+            message: "This Grok runtime does not advertise image or attachment input support.",
+        };
+    }
+    const command = grokSlashCommandName(input.text);
+    if (command) {
+        if (!isGrokLocalSlashCommand(command)) {
+            return {
+                kind: "blocked",
+                message: `/${command} is not available in this Grok workspace session.`,
+            };
+        }
+        if (command === "logout") {
+            const argument = input.text.trim().split(/\s+/)[1]?.toLowerCase();
+            if (argument !== "grok") {
+                return {
+                    kind: "blocked",
+                    message: "Use /logout grok while Grok subscription chat is active.",
+                };
+            }
+        }
+        return { kind: "local_command", command };
+    }
+    if (input.text.trimStart().startsWith("/")) {
+        return { kind: "blocked", message: "Unknown slash command." };
+    }
+    return { kind: "prompt" };
+}

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

@@ -0,0 +1,14 @@
+import type { AnyMessage, Stream } from "@agentclientprotocol/sdk";
+import { GrokRuntimeError } from "./grok-errors.js";
+export declare const GROK_ACP_MAX_LINE_BYTES: number;
+export interface BoundedNdjsonOptions {
+    maxLineBytes?: number;
+    onProtocolError?: (error: GrokRuntimeError) => void;
+    /** Return true to consume a validated envelope before SDK async dispatch. */
+    interceptIncoming?: (message: AnyMessage) => boolean;
+}
+/**
+ * A credential-safe NDJSON transport. Unlike the SDK convenience transport,
+ * this implementation bounds each line and never prints rejected input.
+ */
+export declare function createBoundedGrokNdjsonStream(output: WritableStream<Uint8Array>, input: ReadableStream<Uint8Array>, options?: BoundedNdjsonOptions): Stream;

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

@@ -0,0 +1,193 @@
+import { GrokRuntimeError } from "./grok-errors.js";
+export const GROK_ACP_MAX_LINE_BYTES = 1024 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonRpcId(value) {
+    return value === null || typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+}
+function isJsonRpcMessage(value) {
+    if (!isRecord(value) || value.jsonrpc !== "2.0")
+        return false;
+    if (typeof value.method === "string" && value.method.length > 0) {
+        return !("id" in value) || isJsonRpcId(value.id);
+    }
+    if (!("id" in value) || !isJsonRpcId(value.id))
+        return false;
+    const hasResult = Object.prototype.hasOwnProperty.call(value, "result");
+    const hasError = Object.prototype.hasOwnProperty.call(value, "error");
+    if (hasResult === hasError)
+        return false;
+    if (hasError) {
+        return isRecord(value.error)
+            && typeof value.error.code === "number"
+            && typeof value.error.message === "string";
+    }
+    return true;
+}
+function malformedMessage() {
+    return new GrokRuntimeError("protocol_error", "Grok ACP sent a malformed JSON-RPC message.");
+}
+function oversizedMessage() {
+    return new GrokRuntimeError("protocol_error", "Grok ACP message exceeded the safe line limit.");
+}
+/**
+ * A credential-safe NDJSON transport. Unlike the SDK convenience transport,
+ * this implementation bounds each line and never prints rejected input.
+ */
+export function createBoundedGrokNdjsonStream(output, input, options = {}) {
+    const maxLineBytes = options.maxLineBytes ?? GROK_ACP_MAX_LINE_BYTES;
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let inputReader;
+    let cancelled = false;
+    let reported = false;
+    const pendingRequestIds = new Set();
+    const requestKey = (id) => `${typeof id}:${String(id)}`;
+    const report = (error) => {
+        if (reported)
+            return;
+        reported = true;
+        options.onProtocolError?.(error);
+    };
+    const readable = new ReadableStream({
+        async start(controller) {
+            const parts = [];
+            let lineBytes = 0;
+            const append = (segment) => {
+                if (lineBytes + segment.byteLength > maxLineBytes)
+                    throw oversizedMessage();
+                if (segment.byteLength > 0)
+                    parts.push(new Uint8Array(segment));
+                lineBytes += segment.byteLength;
+            };
+            const consumeLine = () => {
+                if (lineBytes === 0)
+                    return;
+                const bytes = new Uint8Array(lineBytes);
+                let offset = 0;
+                for (const part of parts) {
+                    bytes.set(part, offset);
+                    offset += part.byteLength;
+                }
+                parts.length = 0;
+                lineBytes = 0;
+                let text;
+                try {
+                    text = decoder.decode(bytes).trim();
+                }
+                catch {
+                    throw malformedMessage();
+                }
+                if (!text)
+                    return;
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    throw malformedMessage();
+                }
+                if (!isJsonRpcMessage(parsed))
+                    throw malformedMessage();
+                if (!("method" in parsed)) {
+                    // The pinned CLI emits a small number of internal responses (for
+                    // example `skills-reload`) that were never requested by Bubble. The
+                    // SDK logs unknown response IDs verbatim, so consume them here unless
+                    // the ID belongs to an outgoing Bubble request.
+                    if (!pendingRequestIds.delete(requestKey(parsed.id)))
+                        return;
+                }
+                if (options.interceptIncoming?.(parsed))
+                    return;
+                controller.enqueue(parsed);
+            };
+            const reader = input.getReader();
+            inputReader = reader;
+            try {
+                while (!cancelled) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    if (!value)
+                        continue;
+                    let start = 0;
+                    for (let index = 0; index < value.byteLength; index += 1) {
+                        if (value[index] !== 0x0a)
+                            continue;
+                        append(value.subarray(start, index));
+                        consumeLine();
+                        start = index + 1;
+                    }
+                    if (start < value.byteLength)
+                        append(value.subarray(start));
+                }
+                if (!cancelled && lineBytes > 0)
+                    consumeLine();
+                if (!cancelled)
+                    controller.close();
+            }
+            catch (error) {
+                if (!cancelled) {
+                    const safe = error instanceof GrokRuntimeError ? error : malformedMessage();
+                    report(safe);
+                    await reader.cancel(safe).catch(() => undefined);
+                    // The typed failure is delivered through onProtocolError. Close the
+                    // SDK-facing stream cleanly so its router never logs the rejected raw
+                    // JSON-RPC line as part of an exception path.
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        // The connection may have been concurrently closed by the
+                        // protocol-error callback. Either state is safely terminal.
+                    }
+                }
+            }
+            finally {
+                if (inputReader === reader)
+                    inputReader = undefined;
+                reader.releaseLock();
+            }
+        },
+        async cancel(reason) {
+            cancelled = true;
+            await inputReader?.cancel(reason);
+        },
+    });
+    const writable = new WritableStream({
+        async write(message) {
+            let bytes;
+            try {
+                bytes = encoder.encode(`${JSON.stringify(message)}\n`);
+            }
+            catch {
+                const error = malformedMessage();
+                report(error);
+                throw error;
+            }
+            if (bytes.byteLength > maxLineBytes) {
+                const error = oversizedMessage();
+                report(error);
+                throw error;
+            }
+            if ("method" in message && "id" in message) {
+                pendingRequestIds.add(requestKey(message.id));
+            }
+            const writer = output.getWriter();
+            try {
+                await writer.write(bytes);
+            }
+            finally {
+                writer.releaseLock();
+            }
+        },
+        async abort(reason) {
+            await output.abort(reason);
+        },
+        async close() {
+            await output.close();
+        },
+    });
+    return { readable, writable };
+}

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

@@ -0,0 +1,15 @@
+export type GrokNetworkRouteSource = "direct" | "clash-verge" | "clashx";
+export interface GrokNetworkRoute {
+    source: GrokNetworkRouteSource;
+    proxy?: string;
+}
+export type GrokNetworkProbe = (proxy?: string) => Promise<boolean>;
+export interface GrokNetworkResolverDependencies {
+    platform?: NodeJS.Platform;
+    userHome?: string;
+    uid?: number;
+    probe?: GrokNetworkProbe;
+}
+export declare function probeXaiOidc(proxy?: string, timeoutMs?: number): Promise<boolean>;
+export declare function parseClashHttpProxyPort(contents: string): number | undefined;
+export declare function resolveGrokNetworkRoute(deps?: GrokNetworkResolverDependencies): Promise<GrokNetworkRoute>;

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

@@ -0,0 +1,81 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { GrokRuntimeError } from "./grok-errors.js";
+const XAI_OIDC_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
+const MAX_PROXY_CONFIG_BYTES = 64 * 1024;
+export async function probeXaiOidc(proxy, timeoutMs = 5_000) {
+    const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1_000)).toString();
+    const args = [
+        "--fail",
+        "--silent",
+        "--show-error",
+        "--output", "/dev/null",
+        "--connect-timeout", timeoutSeconds,
+        "--max-time", timeoutSeconds,
+        "--proto", "=https",
+    ];
+    if (proxy)
+        args.push("--proxy", proxy);
+    else
+        args.push("--noproxy", "*");
+    args.push(XAI_OIDC_DISCOVERY_URL);
+    return await new Promise((resolve) => {
+        execFile("/usr/bin/curl", args, { timeout: timeoutMs + 1_000, maxBuffer: 4 * 1024 }, (error) => resolve(error === null));
+    });
+}
+export function parseClashHttpProxyPort(contents) {
+    for (const key of ["mixed-port", "port"]) {
+        const match = new RegExp(`^${key}:\\s*([0-9]{1,5})\\s*$`, "m").exec(contents);
+        const port = match ? Number(match[1]) : 0;
+        if (port >= 1 && port <= 65_535)
+            return port;
+    }
+    return undefined;
+}
+async function readOwnedProxyPort(path, uid) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.uid !== uid
+            || (metadata.mode & 0o022) !== 0 || metadata.size > MAX_PROXY_CONFIG_BYTES)
+            return undefined;
+        return parseClashHttpProxyPort(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function discoverConfiguredLoopbackProxies(deps) {
+    if ((deps.platform ?? process.platform) !== "darwin")
+        return [];
+    const uid = deps.uid ?? process.getuid?.();
+    if (uid === undefined)
+        return [];
+    const home = deps.userHome ?? homedir();
+    const configs = [
+        { source: "clash-verge", path: join(home, "Library", "Application Support", "io.github.clash-verge-rev.clash-verge-rev", "config.yaml") },
+        { source: "clashx", path: join(home, "Library", "Application Support", "com.west2online.ClashX", "config.yaml") },
+    ];
+    const candidates = [];
+    for (const config of configs) {
+        const port = await readOwnedProxyPort(config.path, uid);
+        if (port)
+            candidates.push({ source: config.source, proxy: `http://127.0.0.1:${port}` });
+    }
+    return candidates;
+}
+export async function resolveGrokNetworkRoute(deps = {}) {
+    const probe = deps.probe ?? probeXaiOidc;
+    if (await probe())
+        return { source: "direct" };
+    const seen = new Set();
+    for (const candidate of await discoverConfiguredLoopbackProxies(deps)) {
+        if (seen.has(candidate.proxy))
+            continue;
+        seen.add(candidate.proxy);
+        if (await probe(candidate.proxy))
+            return candidate;
+    }
+    throw new GrokRuntimeError("not_authenticated", "Bubble could not reach xAI through this Mac's current network configuration.");
+}

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

@@ -0,0 +1,28 @@
+import type { GrokProfile } from "./grok-profile.js";
+import type { GrokSpawn } from "./grok-process.js";
+/**
+ * How a workspace-scoped preflight may relax the empty-surface rule. The
+ * pinned Grok CLI always *lists* project-level extensions in `inspect`, even
+ * when their loading is disabled, so a workspace containing its own
+ * `.grok/skills` or `.agents/skills` directories can never produce an empty
+ * report. Loading is prevented instead: every discovered project skill must be
+ * written into the profile's `[skills] disabled` list before the sidecar
+ * starts, and MCP entries are acceptable only when they come from the
+ * cursor/claude compatibility scanners that the profile verifiably disables
+ * (agent-stdio sessions additionally use only the MCP servers passed by
+ * Bubble, which passes none).
+ */
+export interface GrokWorkspaceExtensionPolicy {
+    allowedProjectSkills: ReadonlySet<string>;
+    allowCompatMcpServers: boolean;
+}
+/**
+ * Collect the names of every skill Grok discovered for this workspace so they
+ * can be written into the profile's `[skills] disabled` list. Fails closed on
+ * any skill that is not a plain project-level discovery inside the workspace
+ * scope, or whose name cannot be disabled safely.
+ */
+export declare function collectGrokProjectSkills(payload: unknown, workspace: string): Promise<string[]>;
+export declare function validateGrokInspect(payload: unknown, profile: GrokProfile, workspace?: string, policy?: GrokWorkspaceExtensionPolicy): Promise<void>;
+export declare function runGrokInspectJson(spawn: GrokSpawn, binary: string, profile: GrokProfile, env: NodeJS.ProcessEnv, workspace?: string, signal?: AbortSignal): Promise<unknown>;
+export declare function runGrokPreflight(spawn: GrokSpawn, binary: string, profile: GrokProfile, env: NodeJS.ProcessEnv, workspace?: string, signal?: AbortSignal, policy?: GrokWorkspaceExtensionPolicy): Promise<void>;

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

@@ -0,0 +1,194 @@
+import { realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+import { isSafeGrokSkillName } from "./grok-profile.js";
+import { runGrokCommand } from "./grok-process.js";
+import { GrokRuntimeError } from "./grok-errors.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireEmptyArray(root, key) {
+    const value = root[key];
+    if (!Array.isArray(value) || value.length !== 0) {
+        throw new GrokRuntimeError("preflight_failed", `Grok isolation check failed: ${key} must be empty.`);
+    }
+}
+function sourcePath(value) {
+    if (typeof value === "string") {
+        // Grok 0.2.93 renders permission origins as
+        // "/absolute/file.toml (config)" in inspect JSON.
+        return value.replace(/\s+\((?:config|requirements)\)$/, "");
+    }
+    if (!isRecord(value))
+        return undefined;
+    for (const key of ["path", "file", "sourcePath"]) {
+        if (typeof value[key] === "string")
+            return value[key];
+    }
+    const source = value.source;
+    if (typeof source === "string" && source.startsWith("/"))
+        return source;
+    if (isRecord(source))
+        return sourcePath(source);
+    return undefined;
+}
+async function canonicalOrResolved(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** Render a workspace-controlled path safely inside an error message. */
+function describeForeignPath(path) {
+    if (!path)
+        return "an unidentified configuration source";
+    const printable = path.replace(/[\p{Cc}\p{Cf}]/gu, "?");
+    return printable.length > 160 ? `${printable.slice(0, 157)}...` : printable;
+}
+/**
+ * The directory subtree Grok legitimately scans for project extensions: the
+ * validated project root when the workspace sits inside one, otherwise the
+ * workspace itself.
+ */
+async function workspaceExtensionScope(payload, workspace) {
+    const expectedCwd = await canonicalOrResolved(workspace);
+    if (typeof payload.projectRoot === "string") {
+        const projectRoot = await canonicalOrResolved(payload.projectRoot);
+        if (expectedCwd === projectRoot || expectedCwd.startsWith(`${projectRoot}${sep}`))
+            return projectRoot;
+    }
+    return expectedCwd;
+}
+/**
+ * Collect the names of every skill Grok discovered for this workspace so they
+ * can be written into the profile's `[skills] disabled` list. Fails closed on
+ * any skill that is not a plain project-level discovery inside the workspace
+ * scope, or whose name cannot be disabled safely.
+ */
+export async function collectGrokProjectSkills(payload, workspace) {
+    if (!isRecord(payload) || !Array.isArray(payload.skills)) {
+        throw new GrokRuntimeError("preflight_failed", "Grok isolation check returned invalid skill data.");
+    }
+    const scope = await workspaceExtensionScope(payload, workspace);
+    const names = new Set();
+    for (const entry of payload.skills) {
+        if (!isRecord(entry) || typeof entry.name !== "string" || !isSafeGrokSkillName(entry.name)) {
+            throw new GrokRuntimeError("preflight_failed", "Grok discovered a skill Bubble cannot disable safely.");
+        }
+        const source = entry.source;
+        if (!isRecord(source) || source.type !== "project" || typeof source.path !== "string") {
+            throw new GrokRuntimeError("preflight_failed", `Grok discovered the skill "${entry.name}" outside the workspace project scope.`);
+        }
+        const path = await canonicalOrResolved(source.path);
+        if (path !== scope && !path.startsWith(`${scope}${sep}`)) {
+            throw new GrokRuntimeError("preflight_failed", `Grok discovered the skill "${entry.name}" outside the workspace project scope.`);
+        }
+        names.add(entry.name);
+    }
+    return [...names].sort();
+}
+export async function validateGrokInspect(payload, profile, workspace = profile.workspace, policy) {
+    if (!isRecord(payload))
+        throw new GrokRuntimeError("preflight_failed", "Grok isolation check returned invalid data.");
+    const expectedCwd = await canonicalOrResolved(workspace);
+    if (typeof payload.cwd !== "string" || (await canonicalOrResolved(payload.cwd)) !== expectedCwd) {
+        throw new GrokRuntimeError("preflight_failed", "Grok isolation check used an unexpected workspace.");
+    }
+    if (payload.projectRoot !== null) {
+        if (typeof payload.projectRoot !== "string") {
+            throw new GrokRuntimeError("preflight_failed", "Grok isolation check returned an invalid project root.");
+        }
+        const projectRoot = await canonicalOrResolved(payload.projectRoot);
+        if (expectedCwd !== projectRoot && !expectedCwd.startsWith(`${projectRoot}${sep}`)) {
+            throw new GrokRuntimeError("preflight_failed", "Grok isolation check discovered an unrelated project root.");
+        }
+    }
+    for (const key of ["projectInstructions", "hooks", "plugins", "marketplaces", "lspServers"]) {
+        requireEmptyArray(payload, key);
+    }
+    if (policy) {
+        for (const name of await collectGrokProjectSkills(payload, workspace)) {
+            if (!policy.allowedProjectSkills.has(name)) {
+                throw new GrokRuntimeError("preflight_failed", `Grok discovered the workspace skill "${name}" that Bubble has not disabled.`);
+            }
+        }
+    }
+    else {
+        requireEmptyArray(payload, "skills");
+    }
+    if (policy?.allowCompatMcpServers) {
+        const mcpServers = payload.mcpServers;
+        if (!Array.isArray(mcpServers)) {
+            throw new GrokRuntimeError("preflight_failed", "Grok isolation check returned invalid MCP data.");
+        }
+        for (const entry of mcpServers) {
+            // Compat-scanner discoveries stay listed even though the disabled
+            // compatibility cells (verified below) and Bubble's empty session MCP
+            // list keep them from loading. Anything else fails closed.
+            if (!isRecord(entry) || (entry.vendor !== "cursor" && entry.vendor !== "claude")) {
+                throw new GrokRuntimeError("preflight_failed", "Grok discovered an MCP server it could load.");
+            }
+        }
+    }
+    else {
+        requireEmptyArray(payload, "mcpServers");
+    }
+    const externalCompat = payload.externalCompat;
+    if (!isRecord(externalCompat) || !Array.isArray(externalCompat.cells) || externalCompat.cells.length === 0) {
+        throw new GrokRuntimeError("preflight_failed", "Grok compatibility scanners could not be verified as disabled.");
+    }
+    for (const cell of externalCompat.cells) {
+        if (!isRecord(cell) || cell.enabled !== false) {
+            throw new GrokRuntimeError("preflight_failed", "Grok compatibility scanners are not fully disabled.");
+        }
+    }
+    const allowedSources = new Set([
+        await canonicalOrResolved(profile.configPath),
+        await canonicalOrResolved(profile.requirementsPath),
+    ]);
+    const permissions = payload.permissions;
+    if (!isRecord(permissions) || !Array.isArray(permissions.sources)) {
+        throw new GrokRuntimeError("preflight_failed", "Grok permission sources could not be verified.");
+    }
+    for (const source of permissions.sources) {
+        const path = sourcePath(source);
+        if (!path || !allowedSources.has(await canonicalOrResolved(path))) {
+            throw new GrokRuntimeError("preflight_failed", "Grok discovered a permission source outside Bubble's isolated profile.");
+        }
+    }
+    if (Array.isArray(permissions.skipped) && permissions.skipped.length > 0) {
+        throw new GrokRuntimeError("preflight_failed", "Grok discovered an unverified permission source.");
+    }
+    if (permissions.managedSettingsActive === true) {
+        throw new GrokRuntimeError("preflight_failed", "Grok discovered active managed settings outside Bubble's isolated profile.");
+    }
+    const configSources = payload.configSources;
+    if (isRecord(configSources) && Array.isArray(configSources.layers)) {
+        for (const layer of configSources.layers) {
+            const path = sourcePath(layer);
+            if (!path || !allowedSources.has(await canonicalOrResolved(path))) {
+                // A project-scope config layer overrides the isolated profile's
+                // settings (verified on the pinned CLI: it can re-enable disabled
+                // skills past requirements.toml), so it can never be allowed.
+                throw new GrokRuntimeError("preflight_failed", `Grok would load ${describeForeignPath(path)} as project configuration. Start Bubble in a workspace without its own Grok config file.`);
+            }
+        }
+    }
+}
+export async function runGrokInspectJson(spawn, binary, profile, env, workspace = profile.workspace, signal) {
+    const result = await runGrokCommand(spawn, binary, ["--no-auto-update", "--cwd", workspace, "inspect", "--json"], { cwd: workspace, env, signal });
+    if (result.code !== 0) {
+        throw new GrokRuntimeError("preflight_failed", "Grok isolation check failed to run.", result.stderr);
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new GrokRuntimeError("preflight_failed", "Grok isolation check returned invalid JSON.");
+    }
+}
+export async function runGrokPreflight(spawn, binary, profile, env, workspace = profile.workspace, signal, policy) {
+    const payload = await runGrokInspectJson(spawn, binary, profile, env, workspace, signal);
+    await validateGrokInspect(payload, profile, workspace, policy);
+}

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

@@ -0,0 +1,26 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+export type GrokSpawn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export interface GrokCommandResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface RunGrokCommandOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    maxStdoutBytes?: number;
+    maxStderrBytes?: number;
+    /** Login-only hook. Called once, and only with Bubble's strictly allowlisted xAI OAuth URL. */
+    onOAuthAuthorizeUrl?: (url: string) => void;
+    /** Keep login stdout inside the process boundary; callers only receive the trusted URL hook above. */
+    discardStdout?: boolean;
+}
+export declare const defaultGrokSpawn: GrokSpawn;
+export declare function sanitizeGrokDiagnostic(input: string, maxLength?: number): string;
+/**
+ * Extract only the pinned xAI authorization endpoint. OAuth query values are
+ * intentionally treated as opaque and are never copied into diagnostics.
+ */
+export declare function extractGrokOAuthAuthorizeUrl(input: string): string | undefined;
+export declare function runGrokCommand(spawn: GrokSpawn, binary: string, args: readonly string[], options: RunGrokCommandOptions): Promise<GrokCommandResult>;