@bubblebrain-ai/bubble 0.0.63 → 0.0.64

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

@@ -0,0 +1,184 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { GrokRuntimeError } from "./grok-errors.js";
+export const defaultGrokSpawn = (command, args, options) => nodeSpawn(command, [...args], { ...options, shell: false });
+function appendBounded(chunks, chunk, used, limit) {
+    if (used >= limit)
+        return used;
+    const remaining = limit - used;
+    chunks.push(chunk.subarray(0, remaining));
+    return used + Math.min(chunk.byteLength, remaining);
+}
+export function sanitizeGrokDiagnostic(input, maxLength = 2048) {
+    let value = input
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "")
+        .replace(/https:\/\/auth\.x\.ai\/oauth2\/authorize[^\s"'<>`]*/gi, "https://auth.x.ai/oauth2/authorize?[redacted]")
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 [redacted]")
+        .replace(/\bxai-[A-Za-z0-9_-]+/gi, "xai-[redacted]")
+        .replace(/([?&](?:access_token|refresh_token|token|api_key|key|secret|password)=)[^\s&#]+/gi, "$1[redacted]")
+        .replace(/(["']?(?:access_token|refresh_token|id_token|token|api_key|secret|password)["']?\s*[:=]\s*["']?)[^"',\s}]+/gi, "$1[redacted]")
+        .replace(/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD|AUTH)[A-Z0-9_]*)\s*=\s*[^\s]+/gi, "$1=[redacted]")
+        .replace(/\beyJ[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]{8,})?/g, "[redacted-jwt]")
+        .replace(/(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi, "$1[redacted]@");
+    if (value.length > maxLength)
+        value = `${value.slice(0, maxLength)}…`;
+    return value.trim();
+}
+const GROK_OAUTH_AUTHORIZE_PREFIX = "https://auth.x.ai/oauth2/authorize";
+/**
+ * Extract only the pinned xAI authorization endpoint. OAuth query values are
+ * intentionally treated as opaque and are never copied into diagnostics.
+ */
+export function extractGrokOAuthAuthorizeUrl(input) {
+    let offset = 0;
+    while (offset < input.length) {
+        const start = input.indexOf(GROK_OAUTH_AUTHORIZE_PREFIX, offset);
+        if (start < 0)
+            return undefined;
+        let end = start + GROK_OAUTH_AUTHORIZE_PREFIX.length;
+        while (end < input.length) {
+            const char = input[end];
+            const code = char.charCodeAt(0);
+            if (code <= 0x20 || code === 0x7f || char === '"' || char === "'" || char === "<" || char === ">" || char === "`") {
+                break;
+            }
+            end += 1;
+        }
+        let candidate = input.slice(start, end);
+        while (/[),.;\]}]$/.test(candidate))
+            candidate = candidate.slice(0, -1);
+        try {
+            const parsed = new URL(candidate);
+            if (parsed.protocol === "https:"
+                && parsed.hostname === "auth.x.ai"
+                && parsed.port === ""
+                && parsed.username === ""
+                && parsed.password === ""
+                && parsed.pathname === "/oauth2/authorize"
+                && parsed.hash === "") {
+                return parsed.toString();
+            }
+        }
+        catch {
+            // Keep scanning: a malformed lookalike must not suppress a later valid URL.
+        }
+        offset = start + GROK_OAUTH_AUTHORIZE_PREFIX.length;
+    }
+    return undefined;
+}
+export async function runGrokCommand(spawn, binary, args, options) {
+    return await new Promise((resolve, reject) => {
+        if (options.signal?.aborted) {
+            reject(new GrokRuntimeError("cancelled", "Grok command cancelled."));
+            return;
+        }
+        const child = spawn(binary, args, {
+            cwd: options.cwd,
+            env: options.env,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        const maxStdout = options.maxStdoutBytes ?? 512 * 1024;
+        const maxStderr = options.maxStderrBytes ?? 8 * 1024;
+        let stdoutBytes = 0;
+        let stdoutStoredBytes = 0;
+        let stderrBytes = 0;
+        let stdoutOverflow = false;
+        let oauthStdoutScanBuffer = "";
+        let oauthStderrScanBuffer = "";
+        let oauthUrlSeen = false;
+        let oauthHandlerFailed = false;
+        let childError;
+        let aborted = false;
+        let killTimer;
+        const terminate = () => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill("SIGTERM");
+            if (killTimer)
+                return;
+            killTimer = setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGKILL");
+            }, 1_000);
+            killTimer.unref?.();
+        };
+        const onAbort = () => {
+            aborted = true;
+            terminate();
+        };
+        const scanOAuthChunk = (source, text) => {
+            if (oauthUrlSeen || !options.onOAuthAuthorizeUrl)
+                return;
+            if (source === "stdout") {
+                oauthStdoutScanBuffer = `${oauthStdoutScanBuffer}${text}`.slice(-64 * 1024);
+            }
+            else {
+                oauthStderrScanBuffer = `${oauthStderrScanBuffer}${text}`.slice(-64 * 1024);
+            }
+            const url = extractGrokOAuthAuthorizeUrl(source === "stdout" ? oauthStdoutScanBuffer : oauthStderrScanBuffer);
+            if (!url)
+                return;
+            oauthUrlSeen = true;
+            try {
+                options.onOAuthAuthorizeUrl(url);
+            }
+            catch {
+                oauthHandlerFailed = true;
+                terminate();
+            }
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout?.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (!stdoutOverflow && stdoutBytes + bytes.byteLength > maxStdout) {
+                stdoutOverflow = true;
+                terminate();
+            }
+            stdoutBytes += bytes.byteLength;
+            if (!options.discardStdout) {
+                stdoutStoredBytes = appendBounded(stdout, bytes, stdoutStoredBytes, maxStdout);
+            }
+            scanOAuthChunk("stdout", bytes.toString("utf8"));
+        });
+        child.stderr?.on("data", (chunk) => {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            stderrBytes = appendBounded(stderr, bytes, stderrBytes, maxStderr);
+            scanOAuthChunk("stderr", bytes.toString("utf8"));
+        });
+        child.once("error", (error) => {
+            childError = error;
+        });
+        child.once("close", (code, signal) => {
+            options.signal?.removeEventListener("abort", onAbort);
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (aborted || options.signal?.aborted) {
+                reject(new GrokRuntimeError("cancelled", "Grok command cancelled."));
+                return;
+            }
+            if (stdoutOverflow) {
+                reject(new GrokRuntimeError("protocol_error", "Grok command output exceeded the safe capture limit."));
+                return;
+            }
+            if (oauthHandlerFailed) {
+                reject(new GrokRuntimeError("protocol_error", "Grok OAuth URL handling failed."));
+                return;
+            }
+            if (childError) {
+                reject(childError);
+                return;
+            }
+            if (code === null) {
+                reject(new GrokRuntimeError("process_crashed", `Grok runtime terminated by ${signal ?? "an unknown signal"}.`));
+                return;
+            }
+            resolve({
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: sanitizeGrokDiagnostic(Buffer.concat(stderr).toString("utf8")),
+                code,
+            });
+        });
+    });
+}

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

@@ -0,0 +1,32 @@
+export interface GrokProfile {
+    root: string;
+    home: string;
+    grokHome: string;
+    tmp: string;
+    workspace: string;
+    configPath: string;
+    requirementsPath: string;
+    lockPath: string;
+}
+export interface GrokProfileLock {
+    release(): Promise<void>;
+}
+export declare function isSafeGrokSkillName(name: string): boolean;
+export declare function buildGrokConfigToml(extraDisabledSkills?: readonly string[]): string;
+export declare function buildGrokRequirementsToml(extraDisabledSkills?: readonly string[]): string;
+export declare const GROK_CONFIG_TOML: string;
+export declare const GROK_REQUIREMENTS_TOML: string;
+export declare function getGrokProfile(bubbleHome?: string): GrokProfile;
+/**
+ * Establish only the private directory needed to create runtime.lock. Existing
+ * profile content is validated but never chmodded or rewritten here, because
+ * another Bubble process may already own the lock and be using that profile.
+ */
+export declare function prepareGrokProfileLockRoot(profile?: GrokProfile, uid?: number | undefined): Promise<GrokProfile>;
+export declare function prepareGrokProfile(profile?: GrokProfile, uid?: number | undefined, extraDisabledSkills?: readonly string[]): Promise<GrokProfile>;
+export declare function buildGrokChildEnv(profile: GrokProfile, parentEnv?: NodeJS.ProcessEnv, proxy?: string): NodeJS.ProcessEnv;
+export declare function acquireGrokProfileLock(profile: GrokProfile): Promise<GrokProfileLock>;
+export declare function grokProfileHasAuth(profile: GrokProfile): Promise<boolean>;
+export declare function clearGrokRuntimeData(profile: GrokProfile, includeAuth: boolean): Promise<void>;
+/** Remove extension surfaces that the pinned CLI may materialize at startup. */
+export declare function clearGrokGeneratedExtensions(profile: GrokProfile): Promise<void>;

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

@@ -0,0 +1,419 @@
+import { constants as fsConstants, realpathSync, statSync } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, realpath, rm, stat } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+import { GrokRuntimeError } from "./grok-errors.js";
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+// Skills the pinned Grok CLI bundles and can materialize on its own. They are
+// disabled by name because the runtime re-creates their files at startup.
+const GROK_BUNDLED_SKILLS = [
+    "code-review",
+    "xlsx",
+    "create-skill",
+    "pptx",
+    "check-work",
+    "docx",
+    "imagine",
+    "help",
+];
+// `[skills] disabled` entries are written into TOML basic strings. Only accept
+// names that cannot alter the document structure or smuggle escapes.
+const SAFE_GROK_SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function isSafeGrokSkillName(name) {
+    return SAFE_GROK_SKILL_NAME.test(name);
+}
+function grokDisabledSkillsLine(extraDisabledSkills) {
+    for (const name of extraDisabledSkills) {
+        if (!isSafeGrokSkillName(name)) {
+            throw new GrokRuntimeError("profile_unsafe", "A discovered Grok skill name cannot be disabled safely.");
+        }
+    }
+    const disabled = [...new Set([...GROK_BUNDLED_SKILLS, ...extraDisabledSkills])].sort();
+    return `disabled = [${disabled.map((name) => JSON.stringify(name)).join(", ")}]`;
+}
+// Keep credentials and runtime configuration isolated while allowing the
+// official Grok runtime to work inside the user's selected workspace. Tool
+// execution is still gated by ACP permission requests handled by Bubble.
+export function buildGrokConfigToml(extraDisabledSkills = []) {
+    return `[cli]
+auto_update = false
+
+[session]
+load_envrc = false
+
+[sandbox]
+profile = "strict"
+auto_allow_bash = false
+
+[features]
+web_fetch = false
+write_file = true
+tool_search = false
+lsp_tools = false
+
+[subagents]
+enabled = false
+
+[memory]
+enabled = false
+
+[skills]
+${grokDisabledSkillsLine(extraDisabledSkills)}
+
+[compat.cursor]
+skills = false
+rules = false
+agents = false
+mcps = false
+hooks = false
+
+[compat.claude]
+skills = false
+rules = false
+agents = false
+mcps = false
+hooks = false
+
+# Grok's Claude permission compatibility is independent from the extension
+# compatibility switches above. Mark the one-time import as complete so the
+# runtime never reads workspace .claude/settings*.json permission rules.
+[claude_compat]
+imported = true
+`;
+}
+export function buildGrokRequirementsToml(extraDisabledSkills = []) {
+    return `[cli]
+auto_update = false
+
+[session]
+load_envrc = false
+
+[sandbox]
+profile = "strict"
+auto_allow_bash = false
+
+[features]
+web_fetch = false
+write_file = true
+tool_search = false
+lsp_tools = false
+
+[subagents]
+enabled = false
+
+[memory]
+enabled = false
+
+[skills]
+${grokDisabledSkillsLine(extraDisabledSkills)}
+
+[compat.cursor]
+skills = false
+rules = false
+agents = false
+mcps = false
+hooks = false
+
+[compat.claude]
+skills = false
+rules = false
+agents = false
+mcps = false
+hooks = false
+
+[claude_compat]
+imported = true
+`;
+}
+export const GROK_CONFIG_TOML = buildGrokConfigToml();
+export const GROK_REQUIREMENTS_TOML = buildGrokRequirementsToml();
+export function getGrokProfile(bubbleHome = getBubbleHome()) {
+    const root = resolve(bubbleHome, "runtimes", "grok");
+    const grokHome = join(root, "grok-home");
+    return {
+        root,
+        home: join(root, "home"),
+        grokHome,
+        tmp: join(root, "tmp"),
+        workspace: join(root, "workspace"),
+        configPath: join(grokHome, "config.toml"),
+        requirementsPath: join(grokHome, "requirements.toml"),
+        lockPath: join(root, "runtime.lock"),
+    };
+}
+async function ensurePrivateDirectory(path, uid, repairMode = true) {
+    let created = false;
+    try {
+        const before = await lstat(path);
+        if (!before.isDirectory() || before.isSymbolicLink() || before.uid !== uid) {
+            throw new GrokRuntimeError("profile_unsafe", "The isolated Grok profile contains an unsafe path.");
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        await mkdir(path, { recursive: true, mode: DIRECTORY_MODE });
+        created = true;
+    }
+    if (created || repairMode)
+        await chmod(path, DIRECTORY_MODE);
+    const after = await stat(path);
+    if (!after.isDirectory() || after.uid !== uid || (after.mode & 0o077) !== 0) {
+        throw new GrokRuntimeError("profile_unsafe", "The isolated Grok profile must be private to the current user.");
+    }
+}
+/**
+ * Establish only the private directory needed to create runtime.lock. Existing
+ * profile content is validated but never chmodded or rewritten here, because
+ * another Bubble process may already own the lock and be using that profile.
+ */
+export async function prepareGrokProfileLockRoot(profile = getGrokProfile(), uid = process.getuid?.()) {
+    if (uid === undefined) {
+        throw new GrokRuntimeError("unsupported_platform", "The Grok runtime requires a POSIX user account.");
+    }
+    await ensurePrivateDirectory(dirname(profile.root), uid, false);
+    await ensurePrivateDirectory(profile.root, uid, false);
+    return profile;
+}
+async function writePrivateFile(path, contents, uid) {
+    try {
+        const existing = await lstat(path);
+        if (!existing.isFile() || existing.isSymbolicLink() || existing.uid !== uid) {
+            throw new GrokRuntimeError("profile_unsafe", "The isolated Grok profile contains an unsafe configuration file.");
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const handle = await open(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | fsConstants.O_NOFOLLOW, FILE_MODE);
+    try {
+        await handle.writeFile(contents, { encoding: "utf8" });
+    }
+    finally {
+        await handle.close();
+    }
+    await chmod(path, FILE_MODE);
+    const metadata = await stat(path);
+    if (!metadata.isFile() || metadata.uid !== uid || (metadata.mode & 0o077) !== 0) {
+        throw new GrokRuntimeError("profile_unsafe", "The isolated Grok configuration must be private to the current user.");
+    }
+}
+export async function prepareGrokProfile(profile = getGrokProfile(), uid = process.getuid?.(), extraDisabledSkills = []) {
+    if (uid === undefined) {
+        throw new GrokRuntimeError("unsupported_platform", "The Grok runtime requires a POSIX user account.");
+    }
+    await ensurePrivateDirectory(dirname(profile.root), uid);
+    await ensurePrivateDirectory(profile.root, uid);
+    for (const path of [profile.home, profile.grokHome, profile.tmp, profile.workspace]) {
+        await ensurePrivateDirectory(path, uid);
+    }
+    const canonicalRoot = await realpath(profile.root);
+    for (const path of [profile.home, profile.grokHome, profile.tmp, profile.workspace]) {
+        const canonical = await realpath(path);
+        if (canonical !== canonicalRoot && !canonical.startsWith(`${canonicalRoot}${sep}`)) {
+            throw new GrokRuntimeError("profile_unsafe", "The isolated Grok profile escaped its private root.");
+        }
+    }
+    await writePrivateFile(profile.configPath, buildGrokConfigToml(extraDisabledSkills), uid);
+    await writePrivateFile(profile.requirementsPath, buildGrokRequirementsToml(extraDisabledSkills), uid);
+    return profile;
+}
+export function buildGrokChildEnv(profile, parentEnv = process.env, proxy) {
+    const env = {
+        HOME: profile.home,
+        GROK_HOME: profile.grokHome,
+        TMPDIR: profile.tmp,
+        PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+        GROK_DISABLE_AUTOUPDATER: "1",
+        GROK_SANDBOX: "strict",
+        GROK_SANDBOX_AUTO_ALLOW_BASH: "0",
+        GROK_MEMORY: "0",
+        GROK_SUBAGENTS: "0",
+        GROK_WEB_FETCH: "0",
+        GROK_WRITE_FILE: "1",
+        GROK_TOOL_SEARCH: "0",
+        GROK_LSP_TOOLS: "0",
+        GROK_CURSOR_SKILLS_ENABLED: "0",
+        GROK_CURSOR_RULES_ENABLED: "0",
+        GROK_CURSOR_AGENTS_ENABLED: "0",
+        GROK_CURSOR_MCPS_ENABLED: "0",
+        GROK_CURSOR_HOOKS_ENABLED: "0",
+        GROK_CLAUDE_SKILLS_ENABLED: "0",
+        GROK_CLAUDE_RULES_ENABLED: "0",
+        GROK_CLAUDE_AGENTS_ENABLED: "0",
+        GROK_CLAUDE_MCPS_ENABLED: "0",
+        GROK_CLAUDE_HOOKS_ENABLED: "0",
+        // Pinned Grok 0.2.93 has a separate Claude permission compatibility gate.
+        // Keep its exact process override as defense in depth for every child.
+        _GROK_CLAUDE_MARKER_OVERRIDE: "1",
+        GROK_CRASH_HANDLER: "0",
+    };
+    const uid = process.getuid?.();
+    const safePath = parentEnv.PATH?.split(":").filter((entry) => {
+        if (!entry.startsWith("/") || /[\r\n\0]/.test(entry))
+            return false;
+        try {
+            const canonical = realpathSync(entry);
+            const metadata = statSync(canonical);
+            return metadata.isDirectory()
+                && (uid === undefined || metadata.uid === 0 || metadata.uid === uid)
+                && (metadata.mode & 0o022) === 0;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (safePath?.length)
+        env.PATH = [...new Set(safePath)].join(":");
+    for (const name of ["LANG", "LC_ALL", "TERM", "COLORTERM", "NO_COLOR"]) {
+        const value = parentEnv[name];
+        if (value && !/[\r\n\0]/.test(value))
+            env[name] = value;
+    }
+    if (proxy) {
+        env.HTTPS_PROXY = proxy;
+        env.ALL_PROXY = proxy;
+    }
+    return env;
+}
+export async function acquireGrokProfileLock(profile) {
+    const uid = process.getuid?.();
+    const openNewLock = async () => await open(profile.lockPath, "wx", FILE_MODE);
+    let handle;
+    try {
+        handle = await openNewLock();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const metadata = await lstat(profile.lockPath);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || uid === undefined || metadata.uid !== uid || (metadata.mode & 0o077) !== 0) {
+            throw new GrokRuntimeError("profile_unsafe", "The isolated Grok runtime lock is unsafe.");
+        }
+        const rawPid = (await readFile(profile.lockPath, "utf8")).trim();
+        if (!/^[1-9][0-9]*$/.test(rawPid)) {
+            throw new GrokRuntimeError("profile_unsafe", "The isolated Grok runtime lock is invalid.");
+        }
+        const pid = Number(rawPid);
+        if (!Number.isSafeInteger(pid) || pid > 2_147_483_647) {
+            throw new GrokRuntimeError("profile_unsafe", "The isolated Grok runtime lock is invalid.");
+        }
+        let stale = false;
+        try {
+            process.kill(pid, 0);
+        }
+        catch (probeError) {
+            if (probeError.code === "ESRCH")
+                stale = true;
+            else
+                throw new GrokRuntimeError("profile_locked", "The isolated Grok runtime is already in use.");
+        }
+        if (!stale) {
+            throw new GrokRuntimeError("profile_locked", "The isolated Grok runtime is already in use.");
+        }
+        await rm(profile.lockPath);
+        try {
+            handle = await openNewLock();
+        }
+        catch (retryError) {
+            if (retryError.code === "EEXIST") {
+                throw new GrokRuntimeError("profile_locked", "The isolated Grok runtime is already in use.");
+            }
+            throw retryError;
+        }
+    }
+    await handle.writeFile(`${process.pid}\n`, { encoding: "utf8" });
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await handle.close();
+            await rm(profile.lockPath, { force: true });
+        },
+    };
+}
+export async function grokProfileHasAuth(profile) {
+    for (const path of [join(profile.grokHome, "auth.json"), join(profile.grokHome, "auth")]) {
+        try {
+            const metadata = await lstat(path);
+            if (metadata.isFile() || metadata.isDirectory())
+                return true;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return false;
+}
+export async function clearGrokRuntimeData(profile, includeAuth) {
+    const names = [
+        "sessions",
+        "logs",
+        "log",
+        "crash",
+        "leader.sock",
+        "leader.pid",
+        "socket",
+        "sockets",
+        "active_sessions.json",
+        "active_sessions.lock",
+        "sandbox-events.jsonl",
+        "auth.json.lock",
+    ];
+    if (includeAuth)
+        names.push("auth.json", "auth");
+    for (const name of names) {
+        await rm(join(profile.grokHome, name), { recursive: true, force: true });
+    }
+    // OAuth helpers may place browser hand-off logs or sockets under TMPDIR.
+    // The directory is dedicated to this isolated runtime, so clear and
+    // recreate it at every authentication boundary.
+    await rm(profile.tmp, { recursive: true, force: true });
+    await mkdir(profile.tmp, { mode: DIRECTORY_MODE });
+    await chmod(profile.tmp, DIRECTORY_MODE);
+    // The process workspace is intentionally disposable and never points at the user's project.
+    await rm(profile.workspace, { recursive: true, force: true });
+    await mkdir(profile.workspace, { mode: DIRECTORY_MODE });
+    await chmod(profile.workspace, DIRECTORY_MODE);
+}
+/** Remove extension surfaces that the pinned CLI may materialize at startup. */
+export async function clearGrokGeneratedExtensions(profile) {
+    for (const name of [
+        "skills",
+        "plugins",
+        "marketplaces",
+        "hooks",
+        "agents",
+        "mcp",
+        "lsp",
+        "docs",
+        // The pinned CLI can materialize transcript-bearing archives and logs
+        // even with memory disabled. They are never inputs to a later turn.
+        "upload_queue",
+        "logs",
+        "log",
+        "crash",
+        "sandbox-events.jsonl",
+        "README.md",
+        ".config-init.lock",
+        "managed_config.lock",
+        "auth.json.lock",
+        "active_sessions.json",
+        "active_sessions.lock",
+        "leader.sock",
+        "leader.pid",
+        "socket",
+        "sockets",
+    ]) {
+        await rm(join(profile.grokHome, name), { recursive: true, force: true });
+    }
+    // Bundled skills/docs are written under isolated HOME rather than GROK_HOME.
+    // Remove them after every short-lived process so the next preflight/sidecar
+    // starts from the same empty extension surface it verified.
+    await rm(join(profile.home, ".grok"), { recursive: true, force: true });
+}

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

@@ -0,0 +1,31 @@
+/** Canonical product/picker identity for the subscription-backed runtime. */
+export declare const GROK_SUBSCRIPTION_PROVIDER_ID: "grok-subscription";
+/** Short command alias accepted by `/provider`, `/login`, and `/logout`. */
+export declare const GROK_SUBSCRIPTION_COMMAND_ALIAS: "grok";
+export declare const GROK_SUBSCRIPTION_PROVIDER_NAME: "Grok Subscription";
+export declare const GROK_SUBSCRIPTION_PROVIDER_LABEL: "Grok Subscription [OAuth]";
+export declare const GROK_SUBSCRIPTION_PROVIDER: Readonly<{
+    id: "grok-subscription";
+    commandAlias: "grok";
+    name: "Grok Subscription";
+    label: "Grok Subscription [OAuth]";
+}>;
+export interface ExternalProviderPickerEntry {
+    id: string;
+    name: string;
+    enabled: boolean;
+}
+export interface GrokSubscriptionPickerOptions {
+    label?: string;
+    enabled?: boolean;
+}
+/** Normalize only Grok's public command alias; unrelated provider IDs pass through. */
+export declare function normalizeGrokSubscriptionProviderId(providerId: string): string;
+export declare function isGrokSubscriptionProviderId(providerId: string | undefined): boolean;
+/**
+ * Append one canonical Grok row after native provider rows. Existing canonical
+ * or command-alias rows are replaced, so independently composed picker lists
+ * cannot show Grok twice. This helper is intentionally independent from
+ * ProviderRegistry: Grok Subscription remains an external runtime.
+ */
+export declare function withGrokSubscriptionProvider(entries: readonly ExternalProviderPickerEntry[], options?: GrokSubscriptionPickerOptions): ExternalProviderPickerEntry[];