grokbot-control 0.0.0-stage → 0.1.0

package/dist/cli/main.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+import { syncCommand } from "./sync.js";
+import { HELP } from "./help.js";
+import { buildPlane, flag, hasFlag, parseGlobals, persistMockState, } from "./config.js";
+import { catchToExit, emitResult, usageExit } from "./io.js";
+import { failResult } from "../dto/result.js";
+import { parseCliLimit } from "../ops/limits.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const { globals, rest } = parseGlobals(argv);
+    const asJson = globals.json || !process.stdout.isTTY;
+    const [noun, verb] = rest;
+    if (!noun || !verb)
+        usageExit("missing <noun> <verb>", "gbc --help");
+    try {
+        if (noun === "sync")
+            return emitResult(await syncCommand(globals, rest), asJson);
+        const plane = buildPlane(globals);
+        const write = {
+            dryRun: globals.dryRun,
+            allowWrite: globals.allowWrites,
+        };
+        let code = 0;
+        if (noun === "auth") {
+            const ops = plane.authOps;
+            if (verb === "whoami" || verb === "status") {
+                code = emitResult(await ops.whoami(), asJson);
+            }
+            else if (verb === "login-begin") {
+                code = emitResult(await ops.begin(), asJson);
+            }
+            else if (verb === "poll") {
+                code = emitResult(await ops.poll(), asJson);
+            }
+            else if (verb === "complete" || verb === "login") {
+                const timeout = flag(rest, "--timeout");
+                if (timeout !== undefined && !/^\d+$/.test(timeout))
+                    usageExit("--timeout must be an integer number of seconds", "--timeout=300");
+                if (verb === "login") {
+                    const begin = await ops.begin();
+                    if (!begin.ok) {
+                        code = emitResult(begin, asJson);
+                        persistMockState();
+                        return code;
+                    }
+                    // Human-facing URL goes to stderr; stdout carries only the final result.
+                    process.stderr.write(JSON.stringify({
+                        event: "open_browser",
+                        authorization_url: begin.data
+                            .authorization_url,
+                    }) + "\n");
+                }
+                const ac = new AbortController();
+                const onSig = () => ac.abort();
+                process.once("SIGINT", onSig);
+                process.once("SIGTERM", onSig);
+                try {
+                    code = emitResult(await ops.complete(timeout === undefined ? undefined : Number(timeout), ac.signal), asJson);
+                }
+                finally {
+                    process.off("SIGINT", onSig);
+                    process.off("SIGTERM", onSig);
+                }
+            }
+            else if (verb === "cancel") {
+                code = emitResult(await ops.cancel(), asJson);
+            }
+            else if (verb === "refresh") {
+                code = emitResult(await ops.refresh({ force: hasFlag(rest, "--force") }), asJson);
+            }
+            else if (verb === "logout") {
+                code = emitResult(await ops.logout(), asJson);
+            }
+            else {
+                usageExit(`unknown command: auth ${verb}`, "gbc auth whoami|login|login-begin|complete|poll|cancel|refresh[--force]|logout");
+            }
+        }
+        else if (noun === "bot" && verb === "list") {
+            code = emitResult(await plane.bot.list({ limit: parseCliLimit(flag(rest, "--limit")) }), asJson);
+        }
+        else if (noun === "bot" && verb === "get") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("bot get requires --agent-id");
+            code = emitResult(await plane.bot.get(id), asJson);
+        }
+        else if (noun === "bot" && verb === "create") {
+            const name = flag(rest, "--name");
+            if (!name)
+                usageExit("bot create requires --name");
+            code = emitResult(await plane.bot.create({
+                name,
+                description: flag(rest, "--description") || "",
+                title: flag(rest, "--title"),
+                agentId: flag(rest, "--agent-id"),
+                language: flag(rest, "--language"),
+                kickstart: hasFlag(rest, "--kickstart"),
+            }, write), asJson);
+        }
+        else if (noun === "bot" && verb === "update") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("bot update requires --agent-id");
+            code = emitResult(await plane.bot.update(id, {
+                name: flag(rest, "--name"),
+                description: flag(rest, "--description"),
+                title: flag(rest, "--title"),
+            }, write), asJson);
+        }
+        else if (noun === "bot" && verb === "delete") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("bot delete requires --agent-id");
+            code = emitResult(await plane.bot.delete(id, {
+                ...write,
+                confirm: flag(rest, "--confirm"),
+            }), asJson);
+        }
+        else if (noun === "bot" && verb === "status") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("bot status requires --agent-id");
+            code = emitResult(await plane.progress.status([id]), asJson);
+        }
+        else if (noun === "bot" && verb === "todos") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("--agent-id required");
+            code = emitResult(await plane.progress.todos(id), asJson);
+        }
+        else if (noun === "bot" && verb === "tasks") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("--agent-id required");
+            code = emitResult(await plane.progress.tasks(id), asJson);
+        }
+        else if (noun === "bot" && verb === "subagents") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("--agent-id required");
+            code = emitResult(await plane.progress.subagents(id), asJson);
+        }
+        else if (noun === "bot" && verb === "interrupt") {
+            const id = flag(rest, "--agent-id");
+            if (!id)
+                usageExit("--agent-id required");
+            code = emitResult(await plane.progress.interrupt(id, {
+                ...write,
+                confirm: flag(rest, "--confirm"),
+                reason: flag(rest, "--reason"),
+                sessionId: flag(rest, "--session-id"),
+            }), asJson);
+        }
+        else if (noun === "message" && verb === "send") {
+            const agentId = flag(rest, "--agent-id");
+            const sessionId = flag(rest, "--session-id");
+            let text = flag(rest, "--text");
+            if (hasFlag(rest, "--text-file")) {
+                const fs = await import("node:fs");
+                const file = flag(rest, "--text-file");
+                if (!file)
+                    usageExit("--text-file requires a path", "gbc message send ... --text-file ./msg.txt");
+                try {
+                    text = fs.readFileSync(file, "utf8");
+                }
+                catch (err) {
+                    usageExit(`cannot read --text-file: ${err.message}`);
+                }
+            }
+            if (hasFlag(rest, "--text-stdin"))
+                text = await readStdin();
+            if (!agentId || text == null) {
+                usageExit("message send requires --agent-id and --text|--text-file|--text-stdin; omitted --session-id uses default");
+            }
+            code = emitResult(await plane.message.send({
+                agentId,
+                sessionId: sessionId ?? "",
+                text,
+                messageId: flag(rest, "--message-id"),
+                dryRun: write.dryRun,
+                allowWrite: write.allowWrite,
+            }), asJson);
+        }
+        else if (noun === "message" && verb === "status") {
+            const agentId = flag(rest, "--agent-id");
+            const sessionId = flag(rest, "--session-id");
+            const messageId = flag(rest, "--message-id");
+            if (!agentId || !messageId)
+                usageExit("message status requires --agent-id --message-id; optional --session-id");
+            code = emitResult(await plane.message.status({
+                agentId,
+                sessionId: sessionId ?? "",
+                messageId,
+            }), asJson);
+        }
+        else if (noun === "message" && verb === "history") {
+            const agentId = flag(rest, "--agent-id");
+            if (!agentId)
+                usageExit("--agent-id required");
+            code = emitResult(await plane.message.history({
+                agentId,
+                limit: parseCliLimit(flag(rest, "--limit")),
+            }), asJson);
+        }
+        else if (noun === "session" && verb === "list") {
+            const agentId = flag(rest, "--agent-id");
+            if (!agentId)
+                usageExit("--agent-id required");
+            code = emitResult(await plane.session.list(agentId), asJson);
+        }
+        else if (noun === "sidebar" && verb === "list") {
+            code = emitResult(await plane.sidebar.list(), asJson);
+        }
+        else if (noun === "sidebar" && verb === "create") {
+            const name = flag(rest, "--name");
+            if (!name)
+                usageExit("sidebar create requires --name");
+            code = emitResult(await plane.sidebar.createSection(name, write), asJson);
+        }
+        else if (noun === "sidebar" && verb === "rename") {
+            const id = flag(rest, "--section-id");
+            const name = flag(rest, "--name");
+            if (!id || !name)
+                usageExit("sidebar rename requires --section-id --name");
+            code = emitResult(await plane.sidebar.renameSection(id, name, write), asJson);
+        }
+        else if (noun === "sidebar" && verb === "delete") {
+            const id = flag(rest, "--section-id");
+            if (!id)
+                usageExit("--section-id required");
+            code = emitResult(await plane.sidebar.deleteSection(id, {
+                ...write,
+                confirm: flag(rest, "--confirm"),
+            }), asJson);
+        }
+        else if (noun === "sidebar" && verb === "move") {
+            const agentId = flag(rest, "--agent-id");
+            const sectionId = flag(rest, "--section-id");
+            if (!agentId || !sectionId)
+                usageExit("sidebar move requires --agent-id --section-id");
+            code = emitResult(await plane.sidebar.moveBot(agentId, sectionId, write), asJson);
+        }
+        else if (noun === "room") {
+            code = emitResult(failResult("unsupported", "Room RPCs are intentionally not mixed into sidebar; not implemented in this cut", {
+                hint: "Use sidebar for App sidebar grouping.",
+            }), asJson);
+        }
+        else {
+            usageExit(`unknown command: ${noun} ${verb}`, "gbc --help");
+        }
+        persistMockState();
+        return code;
+    }
+    catch (e) {
+        persistMockState();
+        return catchToExit(e, asJson);
+    }
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        if (process.stdin.isTTY) {
+            reject(new Error("stdin is a TTY; pass --text or --text-file"));
+            return;
+        }
+        const chunks = [];
+        process.stdin.on("data", (c) => chunks.push(Buffer.from(c)));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", reject);
+    });
+}
+main().then((code) => process.exit(code));

package/dist/cli/sync.d.ts

@@ -0,0 +1,4 @@
+import { type CliGlobal } from "./config.js";
+import type { ResultEnvelope } from "../dto/result.js";
+/** Sync opts are deliberately strict; an unknown selector must not broaden a pull. */
+export declare function syncCommand(globals: CliGlobal, rest: string[]): Promise<ResultEnvelope>;

package/dist/cli/sync.js

@@ -0,0 +1,105 @@
+import { SyncOps } from "../sync/core.js";
+import { buildPlane, flag, hasFlag } from "./config.js";
+import { GbcError } from "../errors.js";
+/** Sync opts are deliberately strict; an unknown selector must not broaden a pull. */
+export async function syncCommand(globals, rest) {
+    const verb = rest[1];
+    if (!["pull", "status", "render", "attachments"].includes(verb))
+        throw new GbcError("usage", "sync pull|status|render|attachments required");
+    const values = new Set([
+        "--dir",
+        "--agent-id",
+        "--session-id",
+        ...(verb === "pull"
+            ? [
+                "--account-id",
+                "--team-id",
+                "--max-pages",
+                "--page-size",
+                "--hydrate",
+                "--max-hydrate-requests",
+                "--hydrate-max-bytes",
+                "--hydrate-max-body-bytes",
+                "--max-bytes",
+                "--timeout-ms",
+            ]
+            : []),
+        ...(verb === "attachments"
+            ? [
+                "--path",
+                "--max-bytes",
+                "--max-file-bytes",
+                "--timeout-ms",
+                "--account-id",
+                "--team-id",
+            ]
+            : []),
+    ]);
+    const switches = new Set(["pull", "attachments"].includes(verb) ? ["--ack-unverified-scope"] : []);
+    const seen = new Set();
+    for (let j = 2; j < rest.length; j++) {
+        const k = rest[j].split("=")[0];
+        if (seen.has(k) || (!values.has(k) && !switches.has(k)))
+            throw new GbcError("usage", "unknown/duplicate sync flag (v1 requires one --agent-id; --all not supported)");
+        seen.add(k);
+        if (values.has(k)) {
+            flag(rest, k);
+            if (!rest[j].includes("="))
+                j++;
+        }
+        else if (rest[j].includes("="))
+            throw new GbcError("usage", "acknowledgement is a switch, not a value flag");
+    }
+    const dir = flag(rest, "--dir"), agentId = flag(rest, "--agent-id"), sessionId = flag(rest, "--session-id");
+    if (!dir)
+        throw new GbcError("usage", "sync requires --dir <absolute private root>");
+    const local = new SyncOps({}, globals.mock ? "mock://gbc" : globals.baseUrl, globals.mock);
+    if (verb === "status")
+        return local.status({ dir, agentId, sessionId });
+    if (verb === "render")
+        return local.render({ dir, agentId, sessionId, dryRun: globals.dryRun });
+    function number(name) {
+        const v = flag(rest, name);
+        if (v === undefined)
+            return;
+        if (!/^\d+$/.test(v) || !Number.isSafeInteger(Number(v)))
+            throw new GbcError("usage", `${name} requires an integer`);
+        return Number(v);
+    }
+    if (verb === "attachments") {
+        const input = {
+            dir,
+            agentId,
+            sessionId,
+            path: flag(rest, "--path"),
+            accountId: flag(rest, "--account-id") ?? "",
+            teamId: flag(rest, "--team-id") ?? "",
+            acknowledgeUnverifiedScope: hasFlag(rest, "--ack-unverified-scope"),
+            dryRun: globals.dryRun,
+            maxBytes: number("--max-bytes"),
+            maxFileBytes: number("--max-file-bytes"),
+            timeoutMs: number("--timeout-ms"),
+        };
+        return (globals.dryRun ? local : buildPlane(globals).sync).attachments(input);
+    }
+    if (!agentId)
+        throw new GbcError("usage", "sync pull requires --agent-id");
+    const input = {
+        dir,
+        agentId,
+        sessionId,
+        accountId: flag(rest, "--account-id") ?? "",
+        teamId: flag(rest, "--team-id") ?? "",
+        acknowledgeUnverifiedScope: hasFlag(rest, "--ack-unverified-scope"),
+        dryRun: globals.dryRun,
+        pageSize: number("--page-size"),
+        hydrate: flag(rest, "--hydrate"),
+        maxHydrateRequests: number("--max-hydrate-requests"),
+        hydrateMaxBytes: number("--hydrate-max-bytes"),
+        hydrateMaxBodyBytes: number("--hydrate-max-body-bytes"),
+        maxPages: number("--max-pages"),
+        maxBytes: number("--max-bytes"),
+        timeoutMs: number("--timeout-ms"),
+    };
+    return (globals.dryRun ? local : buildPlane(globals).sync).pull(input);
+}

package/dist/connect/client.d.ts

@@ -0,0 +1,32 @@
+import { ConnectError } from "@connectrpc/connect";
+import type { Interceptor, Transport } from "@connectrpc/connect";
+import type { AuthProvider } from "../auth/types.js";
+import { GbcError } from "../errors.js";
+/**
+ * Generated Connect client. Typed loosely because vendored JS ServiceType
+ * lacks full TS generics; runtime methods match GrokBotService.
+ */
+export type GrokBotClient = any;
+export type ConnectConfig = {
+    baseUrl: string;
+    auth?: AuthProvider;
+    transport?: Transport;
+    /** Optional transport decoded-response cap (sync uses 16MiB). */
+    readMaxBytes?: number;
+};
+/**
+ * Project read-only unary RPCs eligible for at most one 401 refresh+retry.
+ * Writes are never retried. Membership is by Connect method name (PascalCase),
+ * never by HTTP verb alone.
+ */
+export declare const READ_ONLY_UNARY_METHODS: Set<string>;
+/** Carry GbcError through Connect as `cause` so ops can restore structured codes. */
+export declare function gbcAsConnect(gbc: GbcError): ConnectError;
+export declare function unwrapGbcCause(err: unknown): GbcError | undefined;
+export declare function createAuthInterceptor(auth: AuthProvider): Interceptor;
+export declare function createGrokBotClient(cfg: ConnectConfig): GrokBotClient;
+export type MapErrorOpts = {
+    /** True when the RPC is a mutation (create/update/delete/send/sidebar write/interrupt). */
+    write?: boolean;
+};
+export declare function mapConnectError(err: unknown, requestId: string, opts?: MapErrorOpts): GbcError;

package/dist/connect/client.js

@@ -0,0 +1,257 @@
+import { createClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-node";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { GrokBotService } from "#proto-gen/GrokBotService";
+import { GbcError } from "../errors.js";
+/**
+ * Project read-only unary RPCs eligible for at most one 401 refresh+retry.
+ * Writes are never retried. Membership is by Connect method name (PascalCase),
+ * never by HTTP verb alone.
+ */
+export const READ_ONLY_UNARY_METHODS = new Set([
+    "ListGrokBotAgents",
+    "ListGrokBotAgentStatuses",
+    "GetGrokBotUserRuntimeSettings",
+    "ListGrokBotAgentSessions",
+    "GetGrokBotSendStatus",
+    "ListGrokBotAgentTodos",
+    "ListGrokBotAgentTasks",
+    "ListGrokBotSubagents",
+    "ListGrokBotTranscriptEntries",
+    "ResolveGrokBotAttachmentReads",
+    "PresignSandBoxStoreReads",
+]);
+function isUnauthenticated(err) {
+    if (err instanceof ConnectError)
+        return err.code === Code.Unauthenticated;
+    const anyErr = err;
+    const c = String(anyErr.code ?? "");
+    return c === "unauthenticated" || c === "16" || c === String(Code.Unauthenticated);
+}
+function methodName(req) {
+    return req.method?.name ?? "";
+}
+function isReadOnlyUnary(req) {
+    if (req.stream)
+        return false;
+    return READ_ONLY_UNARY_METHODS.has(methodName(req));
+}
+function connectCodeFor(gbc) {
+    switch (gbc.code) {
+        case "unauthenticated":
+        case "auth":
+        case "auth_revoked":
+        case "auth_refresh_unconfigured":
+        case "auth_refresh_client_mismatch":
+        case "auth_refresh_subject_mismatch":
+            return Code.Unauthenticated;
+        case "denied":
+        case "permission_denied":
+            return Code.PermissionDenied;
+        case "auth_refresh_network":
+        case "auth_refresh_timeout":
+        case "auth_refresh_rate_limited":
+        case "auth_refresh_cooldown":
+        case "auth_refresh_lock_timeout":
+            return Code.Unavailable;
+        default:
+            return gbc.retryable ? Code.Unavailable : Code.FailedPrecondition;
+    }
+}
+/** Carry GbcError through Connect as `cause` so ops can restore structured codes. */
+export function gbcAsConnect(gbc) {
+    return new ConnectError(gbc.message, connectCodeFor(gbc), undefined, undefined, gbc);
+}
+export function unwrapGbcCause(err) {
+    if (err instanceof GbcError)
+        return err;
+    if (err instanceof ConnectError && err.cause instanceof GbcError)
+        return err.cause;
+    const anyErr = err;
+    if (anyErr?.cause instanceof GbcError)
+        return anyErr.cause;
+    return undefined;
+}
+export function createAuthInterceptor(auth) {
+    return (next) => async (req) => {
+        let token;
+        try {
+            token = await auth.getAccessToken();
+        }
+        catch (e) {
+            // Fail locally (request NOT sent). Wrap as ConnectError with GbcError cause so
+            // mapConnectError can restore structured codes (Connect may not pass plain Error).
+            const gbc = e instanceof GbcError
+                ? new GbcError(e.code, e.message, {
+                    retryable: e.retryable,
+                    outcome: e.outcome,
+                    hint: e.hint,
+                    exitCode: e.exitCode,
+                    details: {
+                        ...((typeof e.details === "object" && e.details) || {}),
+                        rpc_dispatched: false,
+                    },
+                })
+                : new GbcError("unauthenticated", "credential load/refresh failed (request not sent)", {
+                    exitCode: 4,
+                    details: { rpc_dispatched: false },
+                });
+            throw gbcAsConnect(gbc);
+        }
+        if (!token) {
+            throw gbcAsConnect(new GbcError("unauthenticated", "not logged in: run `gbc auth login` (request not sent)", {
+                exitCode: 4,
+                details: { rpc_dispatched: false },
+            }));
+        }
+        req.header.set("authorization", `Bearer ${token}`);
+        try {
+            return await next(req);
+        }
+        catch (err) {
+            if (!isUnauthenticated(err))
+                throw err;
+            // Closest to App Qz / Grok Build recovery: only force-rotate when the rejected
+            // bearer is still the current disk token; otherwise adopt the newer pair.
+            // Never replay writes. Optional: one refresh+retry for whitelisted read-only unary.
+            let refreshed = false;
+            try {
+                await auth.refresh({ force: true, rejectedAccessToken: token });
+                refreshed = true;
+            }
+            catch {
+                /* keep original 401; creds may be cleared on shouldLogout */
+            }
+            const allowRetry = refreshed && isReadOnlyUnary(req);
+            if (!allowRetry)
+                throw err;
+            let token2;
+            try {
+                token2 = await auth.getAccessToken();
+            }
+            catch {
+                throw err;
+            }
+            if (!token2 || token2 === token)
+                throw err;
+            req.header.set("authorization", `Bearer ${token2}`);
+            return next(req);
+        }
+    };
+}
+export function createGrokBotClient(cfg) {
+    const interceptors = [];
+    if (cfg.auth)
+        interceptors.push(createAuthInterceptor(cfg.auth));
+    const transport = cfg.transport ??
+        createConnectTransport({
+            baseUrl: cfg.baseUrl.replace(/\/$/, ""),
+            httpVersion: "1.1",
+            readMaxBytes: cfg.readMaxBytes,
+            interceptors,
+        });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return createClient(GrokBotService, transport);
+}
+/**
+ * Codes that do not prove the server did NOT apply a mutation. For writes these
+ * become outcome=unknown / retryable=false / exit 10 (reconcile, never blind-retry).
+ */
+const WRITE_AMBIGUOUS = new Set(["unavailable", "rpc_error", "internal", "unknown_rpc", "resource_exhausted"]);
+export function mapConnectError(err, requestId, opts) {
+    const caused = unwrapGbcCause(err);
+    if (caused) {
+        const details = {
+            ...((typeof caused.details === "object" && caused.details) || {}),
+            request_id: requestId,
+        };
+        return new GbcError(caused.code, caused.message, {
+            retryable: caused.retryable,
+            outcome: caused.outcome,
+            hint: caused.hint,
+            exitCode: caused.exitCode,
+            details,
+        });
+    }
+    const base = mapConnectErrorBase(err, requestId);
+    if (opts?.write && WRITE_AMBIGUOUS.has(base.code)) {
+        return new GbcError("unknown", `write outcome unknown (${base.code}): ${base.message}`, {
+            outcome: "unknown",
+            retryable: false,
+            exitCode: 10,
+            hint: "Server may or may not have applied this write. Reconcile with list/get_send_status/history before any retry; do not blindly resend.",
+            details: { request_id: requestId, rpc_code: base.code },
+        });
+    }
+    return base;
+}
+function mapConnectErrorBase(err, requestId) {
+    const anyErr = err;
+    const msg = anyErr.rawMessage || anyErr.message || String(err);
+    const codeStr = String(anyErr.code ?? "");
+    if (anyErr.name === "AbortError" ||
+        /fetch failed|ECONNRESET|socket hang up|network/i.test(msg)) {
+        return new GbcError("unknown", `transport ended without a known outcome: ${msg}`, {
+            outcome: "unknown",
+            retryable: false,
+            exitCode: 10,
+            hint: "Do not blindly resend create/send/delete. Reconcile with list/get_send_status/history.",
+            details: { request_id: requestId },
+        });
+    }
+    switch (codeStr) {
+        case "unauthenticated":
+        case "16":
+            return new GbcError("unauthenticated", msg, { exitCode: 4, details: { request_id: requestId, rpc_dispatched: true } });
+        case "not_found":
+        case "5":
+            return new GbcError("not_found", msg, { exitCode: 5 });
+        case "already_exists":
+        case "aborted":
+        case "6":
+        case "10":
+            return new GbcError("conflict", msg, { exitCode: 6 });
+        case "permission_denied":
+        case "7":
+            return new GbcError("permission_denied", msg, { exitCode: 7 });
+        case "failed_precondition":
+        case "9":
+            return new GbcError("failed_precondition", msg, {
+                exitCode: 7,
+                hint: "May indicate sidebar_sections_base conflict — re-read and retry patch.",
+            });
+        case "unavailable":
+        case "14":
+            return new GbcError("unavailable", msg, { retryable: true, exitCode: 8 });
+        case "deadline_exceeded":
+        case "4":
+            return new GbcError("deadline_exceeded", msg, {
+                outcome: "unknown",
+                retryable: false,
+                exitCode: 10,
+                hint: "Deadline without response: treat write as unknown; reconcile; do not auto-replay.",
+            });
+        case "canceled":
+        case "1":
+            return new GbcError("canceled", msg, {
+                outcome: "unknown",
+                retryable: false,
+                exitCode: 10,
+                hint: "Request canceled ≠ InterruptGrokBotAgentRun.",
+            });
+        case "internal":
+        case "13":
+            return new GbcError("internal", msg, { exitCode: 9 });
+        case "unknown":
+        case "2":
+            return new GbcError("unknown_rpc", msg, { exitCode: 9 });
+        case "resource_exhausted":
+        case "8":
+            return new GbcError("resource_exhausted", msg, { retryable: true, exitCode: 8 });
+        case "invalid_argument":
+        case "3":
+            return new GbcError("invalid_argument", msg, { exitCode: 2 });
+        default:
+            return new GbcError("rpc_error", msg, { exitCode: 9, details: { code: codeStr } });
+    }
+}