grokbot-control 0.0.0-stage → 0.1.3

package/dist/dto/result.d.ts

@@ -0,0 +1,33 @@
+/** Stable CLI/MCP envelope. schema_version only increases; fields only add. */
+export declare const SCHEMA_VERSION: "1.0.0";
+export type Outcome = "known_success" | "known_failure" | "unknown";
+export type ResultEnvelope<T = unknown> = {
+    schema_version: typeof SCHEMA_VERSION;
+    ok: boolean;
+    outcome: Outcome;
+    code: string;
+    retryable: boolean;
+    request_id: string;
+    data?: T;
+    error?: {
+        message: string;
+        hint?: string;
+        details?: unknown;
+    };
+    /** When true, response came from explicit mock/sim transport — never claim live. */
+    simulated?: boolean;
+};
+export declare function newRequestId(): string;
+export declare function okResult<T>(data: T, opts?: {
+    request_id?: string;
+    simulated?: boolean;
+    code?: string;
+}): ResultEnvelope<T>;
+export declare function failResult(code: string, message: string, opts?: {
+    outcome?: Outcome;
+    retryable?: boolean;
+    hint?: string;
+    request_id?: string;
+    details?: unknown;
+    simulated?: boolean;
+}): ResultEnvelope<never>;

package/dist/dto/result.js

@@ -0,0 +1,29 @@
+/** Stable CLI/MCP envelope. schema_version only increases; fields only add. */
+export const SCHEMA_VERSION = "1.0.0";
+export function newRequestId() {
+    return crypto.randomUUID();
+}
+export function okResult(data, opts) {
+    return {
+        schema_version: SCHEMA_VERSION,
+        ok: true,
+        outcome: "known_success",
+        code: opts?.code ?? "ok",
+        retryable: false,
+        request_id: opts?.request_id ?? newRequestId(),
+        data,
+        simulated: opts?.simulated,
+    };
+}
+export function failResult(code, message, opts) {
+    return {
+        schema_version: SCHEMA_VERSION,
+        ok: false,
+        outcome: opts?.outcome ?? "known_failure",
+        code,
+        retryable: opts?.retryable ?? false,
+        request_id: opts?.request_id ?? newRequestId(),
+        error: { message, hint: opts?.hint, details: opts?.details },
+        simulated: opts?.simulated,
+    };
+}

package/dist/dto/types.d.ts

@@ -0,0 +1,63 @@
+/** Public stable DTOs (not raw protobuf dumps). */
+export type BotSummary = {
+    agent_id: string;
+    id: string;
+    name: string;
+    description: string;
+    title: string;
+    harness: string;
+    role: string;
+    kind: string;
+    viewer_session_id: string;
+    created_at_ms?: string;
+    updated_at_ms?: string;
+};
+export type SidebarSection = {
+    id: string;
+    name: string;
+    agent_ids: string[];
+};
+export type SessionSummary = {
+    agent_id: string;
+    session_id: string;
+    kind: string;
+    created_at_ms?: string;
+    updated_at_ms?: string;
+};
+export type ProgressStatus = {
+    agent_id: string;
+    is_running: boolean;
+    session_id?: string;
+    live?: {
+        is_composing_message?: boolean;
+        is_retrying?: boolean;
+        awaiting?: unknown;
+        working_task_ids?: string[];
+    };
+};
+export type SendDelivery = {
+    message_id: string;
+    agent_id: string;
+    session_id: string;
+    dispatched?: boolean;
+    delivery?: string;
+    /** Delivery/acceptance only — NOT task/business success. */
+    note: string;
+};
+export type SendStatusView = {
+    agent_id: string;
+    message_id: string;
+    session_id: string;
+    status?: string;
+    rejection_code?: string;
+    accepted_at_ms?: string;
+    note: string;
+};
+export type TranscriptEntryView = {
+    /** Opaque / partial — ciphertext or omitted bodies are not decrypted. */
+    entry_id?: string;
+    kind?: string;
+    omitted?: boolean;
+    preview?: string;
+    untrusted?: boolean;
+};

package/dist/dto/types.js

@@ -0,0 +1,2 @@
+/** Public stable DTOs (not raw protobuf dumps). */
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,31 @@
+import type { Outcome } from "./dto/result.js";
+/** Mapped application error with exit-code semantics. */
+export declare class GbcError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly outcome: Outcome;
+    readonly hint?: string;
+    readonly details?: unknown;
+    readonly exitCode: number;
+    constructor(code: string, message: string, opts?: {
+        retryable?: boolean;
+        outcome?: Outcome;
+        hint?: string;
+        details?: unknown;
+        exitCode?: number;
+    });
+}
+export declare function mapExitCode(code: string, outcome?: Outcome, retryable?: boolean): number;
+/** CLI exit codes (documented in --help; meanings must not change). */
+export declare const EXIT: {
+    readonly SUCCESS: 0;
+    readonly ERROR: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 4;
+    readonly NOT_FOUND: 5;
+    readonly CONFLICT: 6;
+    readonly DENIED: 7;
+    readonly RETRYABLE: 8;
+    readonly FAILURE: 9;
+    readonly UNKNOWN: 10;
+};

package/dist/errors.js

@@ -0,0 +1,64 @@
+/** Mapped application error with exit-code semantics. */
+export class GbcError extends Error {
+    code;
+    retryable;
+    outcome;
+    hint;
+    details;
+    exitCode;
+    constructor(code, message, opts) {
+        super(message);
+        this.name = "GbcError";
+        this.code = code;
+        this.retryable = opts?.retryable ?? false;
+        this.outcome = opts?.outcome ?? "known_failure";
+        this.hint = opts?.hint;
+        this.details = opts?.details;
+        this.exitCode = opts?.exitCode ?? mapExitCode(code, opts?.outcome, opts?.retryable);
+    }
+}
+export function mapExitCode(code, outcome, retryable) {
+    if (outcome === "unknown")
+        return 10;
+    if (retryable)
+        return 8;
+    switch (code) {
+        case "usage":
+        case "invalid_argument":
+            return 2;
+        case "unauthenticated":
+        case "auth":
+            return 4;
+        case "not_found":
+            return 5;
+        case "conflict":
+        case "sidebar_conflict":
+            return 6;
+        case "denied":
+        case "permission_denied":
+        case "failed_precondition":
+            return 7;
+        case "unavailable":
+        case "deadline_exceeded":
+            return 8;
+        case "unsupported":
+            return 9;
+        case "ok":
+            return 0;
+        default:
+            return 9;
+    }
+}
+/** CLI exit codes (documented in --help; meanings must not change). */
+export const EXIT = {
+    SUCCESS: 0,
+    ERROR: 1,
+    USAGE: 2,
+    AUTH: 4,
+    NOT_FOUND: 5,
+    CONFLICT: 6,
+    DENIED: 7,
+    RETRYABLE: 8,
+    FAILURE: 9,
+    UNKNOWN: 10,
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { ControlPlane } from "./ops/plane.js";
+export { createGrokBotClient, mapConnectError } from "./connect/client.js";
+export { createAuthProvider, staticTokenProvider } from "./auth/provider.js";
+export { FileCredentialStore, redactCredential } from "./auth/store.js";
+export { createMockTransport, createEmptyMockState } from "./testing/mock-transport.js";
+export { SCHEMA_VERSION, okResult, failResult } from "./dto/result.js";
+export type { ResultEnvelope, Outcome } from "./dto/result.js";
+export { GbcError, EXIT } from "./errors.js";
+export { buildTools } from "./mcp/tools.js";
+export { SyncOps } from "./sync/core.js";
+export type { PullInput, LocalInput, AttachmentsInput, Scope } from "./sync/core.js";
+export { ATTACHMENT_DOWNLOADER } from "./sync/attachments.js";
+export { decodeBody, DECODER } from "./sync/decode.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+export { ControlPlane } from "./ops/plane.js";
+export { createGrokBotClient, mapConnectError } from "./connect/client.js";
+export { createAuthProvider, staticTokenProvider } from "./auth/provider.js";
+export { FileCredentialStore, redactCredential } from "./auth/store.js";
+export { createMockTransport, createEmptyMockState } from "./testing/mock-transport.js";
+export { SCHEMA_VERSION, okResult, failResult } from "./dto/result.js";
+export { GbcError, EXIT } from "./errors.js";
+export { buildTools } from "./mcp/tools.js";
+export { SyncOps } from "./sync/core.js";
+export { ATTACHMENT_DOWNLOADER } from "./sync/attachments.js";
+export { decodeBody, DECODER } from "./sync/decode.js";

package/dist/mcp/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp/main.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * MCP stdio server. stdout is reserved for MCP JSON-RPC frames only.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildPlane } from "../cli/config.js";
+import { buildTools } from "./tools.js";
+async function main() {
+    const readOnly = process.env.GBT_MCP_READONLY === "1";
+    const mock = process.env.GBT_MOCK === "1" || process.argv.includes("--mock");
+    const plane = buildPlane({
+        json: true,
+        allowWrites: process.env.GBT_ALLOW_WRITES === "1",
+        dryRun: false,
+        baseUrl: process.env.GBT_BASE_URL || "https://api2.cursor.sh",
+        authKind: process.env.GBT_AUTH_KIND || "cursor",
+        mock,
+        trustBackend: process.env.GBT_TRUST_BACKEND === "1",
+    });
+    const server = new McpServer({
+        name: "grokbot-control",
+        version: "0.1.0",
+    });
+    const tools = buildTools({ readOnly, sync: process.env.GBT_SYNC_ROOT ? {
+            root: process.env.GBT_SYNC_ROOT,
+            allowLocalWrites: process.env.GBT_SYNC_ALLOW_LOCAL_WRITES === "1",
+            accountId: process.env.GBT_SYNC_ACCOUNT_ID,
+            teamId: process.env.GBT_SYNC_TEAM_ID,
+            acknowledgeUnverifiedScope: process.env.GBT_SYNC_ACK_UNVERIFIED_SCOPE === "1",
+        } : undefined });
+    for (const t of tools) {
+        server.registerTool(t.name, {
+            title: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema.shape,
+            annotations: t.authTool
+                ? { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+                : t.readOnly
+                    ? { readOnlyHint: true, openWorldHint: true }
+                    : { readOnlyHint: false, destructiveHint: t.name.includes("delete"), openWorldHint: true },
+        }, async (args) => {
+            const parsed = t.inputSchema.safeParse(args);
+            if (!parsed.success) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ code: "usage", error: parsed.error.format() }),
+                        },
+                    ],
+                    structuredContent: {
+                        schema_version: "1.0.0",
+                        ok: false,
+                        outcome: "known_failure",
+                        code: "usage",
+                        retryable: false,
+                        request_id: crypto.randomUUID(),
+                        error: { message: "invalid tool arguments", details: parsed.error.format() },
+                    },
+                };
+            }
+            // Tool cancellation ≠ InterruptGrokBotAgentRun
+            const result = await t.handler(plane, parsed.data);
+            return {
+                isError: !result.ok,
+                content: [{ type: "text", text: JSON.stringify(result) }],
+                structuredContent: result,
+            };
+        });
+    }
+    console.log = (...args) => {
+        console.error("[gbc-mcp stdout-blocked]", ...args);
+    };
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/dist/mcp/tools.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { ControlPlane } from "../ops/plane.js";
+import type { ResultEnvelope } from "../dto/result.js";
+export type ToolDef = {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<any>;
+    /** Does not mutate Grok Bot server state (safe in read-only toolsets). */
+    readOnly?: boolean;
+    /** Local auth-state tool (changes only this tool's own credential files). */
+    authTool?: boolean;
+    handler: (plane: ControlPlane, args: Record<string, unknown>) => Promise<ResultEnvelope>;
+};
+export type SyncToolConfig = {
+    root: string;
+    allowLocalWrites?: boolean;
+    accountId?: string;
+    teamId?: string;
+    acknowledgeUnverifiedScope?: boolean;
+};
+export declare function buildTools(opts?: {
+    readOnly?: boolean;
+    sync?: SyncToolConfig;
+}): ToolDef[];