grokbot-control 0.0.0-stage → 0.1.3

package/dist/mcp/tools.js

@@ -0,0 +1,408 @@
+import path from "node:path";
+import { GbcError } from "../errors.js";
+import { z } from "zod";
+import { LIMIT_MAX } from "../ops/limits.js";
+const limitSchema = z.number().int().positive().max(LIMIT_MAX).optional();
+const agentId = z.string().min(1);
+const writeFlags = {
+    dry_run: z.boolean().optional(),
+    allow_writes: z.boolean().optional(),
+};
+export function buildTools(opts) {
+    const all = [
+        {
+            name: "list_bots",
+            description: "List Grok Bot agents (ListGrokBotAgents)",
+            readOnly: true,
+            inputSchema: z.object({ limit: limitSchema }),
+            handler: (p, a) => p.bot.list({ limit: a.limit }),
+        },
+        {
+            name: "get_bot",
+            description: "Get one bot by filtering ListGrokBotAgents (no Get RPC)",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId }),
+            handler: (p, a) => p.bot.get(String(a.agent_id)),
+        },
+        {
+            name: "create_bot",
+            description: "Create temporal harness bot (CreateGrokBotTemporalAgent)",
+            inputSchema: z.object({
+                name: z.string().min(1),
+                description: z.string().optional(),
+                title: z.string().optional(),
+                agent_id: z.string().optional(),
+                language: z.string().optional(),
+                kickstart: z.boolean().optional(),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.bot.create({
+                name: String(a.name),
+                description: a.description,
+                title: a.title,
+                agentId: a.agent_id,
+                language: a.language,
+                kickstart: Boolean(a.kickstart),
+            }, { dryRun: Boolean(a.dry_run), allowWrite: Boolean(a.allow_writes) }),
+        },
+        {
+            name: "update_bot",
+            description: "Partial update bot (UpdateGrokBotAgent)",
+            inputSchema: z.object({
+                agent_id: agentId,
+                name: z.string().optional(),
+                description: z.string().optional(),
+                title: z.string().optional(),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.bot.update(String(a.agent_id), {
+                name: a.name,
+                description: a.description,
+                title: a.title,
+            }, { dryRun: Boolean(a.dry_run), allowWrite: Boolean(a.allow_writes) }),
+        },
+        {
+            name: "delete_bot",
+            description: "Delete bot; requires confirm=agent_id. Sidebar cleanup unverified.",
+            inputSchema: z.object({
+                agent_id: agentId,
+                confirm: z.string().min(1),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.bot.delete(String(a.agent_id), {
+                confirm: String(a.confirm),
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "send_message",
+            description: "Send user message directly (SendGrokBotUserMessage). No task_id required. Delivery ≠ success.",
+            inputSchema: z.object({
+                agent_id: agentId,
+                session_id: z.string().optional(),
+                text: z.string().min(1),
+                message_id: z.string().optional(),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.message.send({
+                agentId: String(a.agent_id),
+                sessionId: a.session_id ?? "",
+                text: String(a.text),
+                messageId: a.message_id,
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "get_send_status",
+            description: "Get message send status (delivery path)",
+            readOnly: true,
+            inputSchema: z.object({
+                agent_id: agentId,
+                session_id: z.string().optional(),
+                message_id: z.string().min(1),
+            }),
+            handler: (p, a) => p.message.status({
+                agentId: String(a.agent_id),
+                sessionId: a.session_id ?? "",
+                messageId: String(a.message_id),
+            }),
+        },
+        {
+            name: "list_transcript",
+            description: "List transcript entries; ciphertext not decrypted",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId, limit: limitSchema }),
+            handler: (p, a) => p.message.history({
+                agentId: String(a.agent_id),
+                limit: a.limit,
+            }),
+        },
+        {
+            name: "list_sessions",
+            description: "List agent sessions",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId }),
+            handler: (p, a) => p.session.list(String(a.agent_id)),
+        },
+        {
+            name: "get_bot_status",
+            description: "Native live progress status",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId }),
+            handler: (p, a) => p.progress.status([String(a.agent_id)]),
+        },
+        {
+            name: "list_agent_todos",
+            description: "Native agent todos (not bridge tasks)",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId }),
+            handler: (p, a) => p.progress.todos(String(a.agent_id)),
+        },
+        {
+            name: "list_agent_tasks",
+            description: "Native agent tasks",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId }),
+            handler: (p, a) => p.progress.tasks(String(a.agent_id)),
+        },
+        {
+            name: "list_agent_subagents",
+            description: "ListGrokBotSubagents",
+            readOnly: true,
+            inputSchema: z.object({ agent_id: agentId }),
+            handler: (p, a) => p.progress.subagents(String(a.agent_id)),
+        },
+        {
+            name: "interrupt_run",
+            description: "InterruptGrokBotAgentRun. MCP request cancel does NOT call this.",
+            inputSchema: z.object({
+                agent_id: agentId,
+                confirm: z.string().min(1),
+                reason: z.string().optional(),
+                session_id: z.string().optional(),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.progress.interrupt(String(a.agent_id), {
+                confirm: String(a.confirm),
+                reason: a.reason,
+                sessionId: a.session_id,
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "get_sidebar_sections",
+            description: "Read SidebarSections from runtime settings",
+            readOnly: true,
+            inputSchema: z.object({}),
+            handler: (p) => p.sidebar.list(),
+        },
+        {
+            name: "create_sidebar_section",
+            description: "Create sidebar section (does not delete bots)",
+            inputSchema: z.object({ name: z.string().min(1), ...writeFlags }),
+            handler: (p, a) => p.sidebar.createSection(String(a.name), {
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "rename_sidebar_section",
+            inputSchema: z.object({
+                section_id: z.string().min(1),
+                name: z.string().min(1),
+                ...writeFlags,
+            }),
+            description: "Rename sidebar section",
+            handler: (p, a) => p.sidebar.renameSection(String(a.section_id), String(a.name), {
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "delete_sidebar_section",
+            description: "Delete sidebar section only — does not delete bots",
+            inputSchema: z.object({
+                section_id: z.string().min(1),
+                confirm: z.string().min(1),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.sidebar.deleteSection(String(a.section_id), {
+                confirm: String(a.confirm),
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "move_bot_to_sidebar_section",
+            description: "Move bot into a sidebar section",
+            inputSchema: z.object({
+                agent_id: agentId,
+                section_id: z.string().min(1),
+                ...writeFlags,
+            }),
+            handler: (p, a) => p.sidebar.moveBot(String(a.agent_id), String(a.section_id), {
+                dryRun: Boolean(a.dry_run),
+                allowWrite: Boolean(a.allow_writes),
+            }),
+        },
+        {
+            name: "auth_whoami",
+            description: "Local credential status (no network; never returns tokens)",
+            readOnly: true,
+            inputSchema: z.object({}),
+            handler: (p) => p.authOps.whoami(),
+        },
+        {
+            name: "auth_login_begin",
+            description: "Start independent Cursor browser login. Returns authorization_url for the user to open; verifier stays in a 0600 pending file.",
+            readOnly: true,
+            authTool: true,
+            inputSchema: z.object({}),
+            handler: (p) => p.authOps.begin(),
+        },
+        {
+            name: "auth_login_complete",
+            description: "Poll the pending login until signed in or timeout (default 60s, max 120s). Returns auth_pending (retryable) if not yet signed in.",
+            readOnly: true,
+            authTool: true,
+            inputSchema: z.object({
+                timeout_seconds: z.number().int().min(1).max(120).optional(),
+            }),
+            handler: (p, a) => p.authOps.complete(a.timeout_seconds ?? 60),
+        },
+        {
+            name: "auth_login_cancel",
+            description: "Discard the pending login (local only)",
+            readOnly: true,
+            authTool: true,
+            inputSchema: z.object({}),
+            handler: (p) => p.authOps.cancel(),
+        },
+        {
+            name: "auth_logout",
+            description: "Remove this tool's own local credential (does not revoke server session or touch the App)",
+            readOnly: true,
+            authTool: true,
+            inputSchema: z.object({}),
+            handler: (p) => p.authOps.logout(),
+        },
+        {
+            name: "auth_refresh",
+            description: "Refresh local Cursor OAuth credentials (non-secret metadata only). Without force, may report already_fresh with no network call. Auto refresh still happens before RPCs when near expiry. Not exposed under GBT_MCP_READONLY=1.",
+            authTool: true,
+            inputSchema: z.object({
+                force: z.boolean().optional(),
+            }),
+            handler: (p, a) => p.authOps.refresh({ force: Boolean(a.force) }),
+        },
+    ];
+    if (opts?.sync) {
+        const c = { ...opts.sync }; // startup-only copy: callers cannot choose paths or account scope
+        if (!path.isAbsolute(c.root))
+            throw new GbcError("invalid_argument", "MCP sync root must be absolute");
+        const selectors = {
+            agent_id: agentId.optional(),
+            session_id: agentId.optional(),
+        };
+        all.push({
+            name: "sync_status",
+            description: "Read bounded local archive status; no login/RPC",
+            readOnly: true,
+            inputSchema: z.object(selectors).strict(),
+            handler: (p, a) => p.sync.status({
+                dir: c.root,
+                agentId: a.agent_id,
+                sessionId: a.session_id,
+            }),
+        });
+        if (c.allowLocalWrites && !opts.readOnly) {
+            all.push({
+                name: "sync_pull",
+                description: "Write a bounded local snapshot to the configured private root. Only remote read RPCs; known JSON entry kinds decoded, unknown bodies opaque, completeness unknown.",
+                inputSchema: z
+                    .object({
+                    agent_id: agentId,
+                    session_id: agentId.optional(),
+                    dry_run: z.boolean().optional(),
+                    page_size: z.number().int().min(1).max(500).optional(),
+                    hydrate: z.enum(["off", "missing"]).optional(),
+                    max_hydrate_requests: z.number().int().min(1).max(256).optional(),
+                    hydrate_max_bytes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(64 * 1024 * 1024)
+                        .optional(),
+                    hydrate_max_body_bytes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(4 * 1024 * 1024)
+                        .optional(),
+                    max_pages: z.number().int().min(1).max(1000).optional(),
+                    max_bytes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(256 * 1024 * 1024)
+                        .optional(),
+                    timeout_ms: z.number().int().min(1).max(300000).optional(),
+                })
+                    .strict(),
+                handler: (p, a) => p.sync.pull({
+                    dir: c.root,
+                    agentId: String(a.agent_id),
+                    sessionId: a.session_id,
+                    accountId: c.accountId ?? "",
+                    teamId: c.teamId ?? "",
+                    acknowledgeUnverifiedScope: c.acknowledgeUnverifiedScope === true,
+                    dryRun: a.dry_run,
+                    pageSize: a.page_size,
+                    hydrate: a.hydrate,
+                    maxHydrateRequests: a.max_hydrate_requests,
+                    hydrateMaxBytes: a.hydrate_max_bytes,
+                    hydrateMaxBodyBytes: a.hydrate_max_body_bytes,
+                    maxPages: a.max_pages,
+                    maxBytes: a.max_bytes,
+                    timeoutMs: a.timeout_ms,
+                }),
+            });
+            all.push({
+                name: "sync_render",
+                description: "Rebuild readable Markdown for verified JSON message/tool-summary shapes locally; unknown bodies opaque, no decryption or RPC",
+                inputSchema: z
+                    .object({ ...selectors, dry_run: z.boolean().optional() })
+                    .strict(),
+                handler: (p, a) => p.sync.render({
+                    dir: c.root,
+                    agentId: a.agent_id,
+                    sessionId: a.session_id,
+                    dryRun: a.dry_run,
+                }),
+            });
+            all.push({
+                name: "sync_attachments",
+                description: "On-demand download of synced user-attachment file_path via ResolveGrokBotAttachmentReads + HTTPS GET into the configured private root. Not live verified; signed URLs never stored; not blob_hash hydration.",
+                inputSchema: z
+                    .object({
+                    ...selectors,
+                    path: z.string().min(1).max(4096).optional(),
+                    dry_run: z.boolean().optional(),
+                    max_bytes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(256 * 1024 * 1024)
+                        .optional(),
+                    max_file_bytes: z
+                        .number()
+                        .int()
+                        .min(1)
+                        .max(128 * 1024 * 1024)
+                        .optional(),
+                    timeout_ms: z.number().int().min(1).max(300000).optional(),
+                })
+                    .strict(),
+                handler: (p, a) => p.sync.attachments({
+                    dir: c.root,
+                    agentId: a.agent_id,
+                    sessionId: a.session_id,
+                    path: a.path,
+                    accountId: c.accountId ?? "",
+                    teamId: c.teamId ?? "",
+                    acknowledgeUnverifiedScope: c.acknowledgeUnverifiedScope === true,
+                    dryRun: a.dry_run,
+                    maxBytes: a.max_bytes,
+                    maxFileBytes: a.max_file_bytes,
+                    timeoutMs: a.timeout_ms,
+                }),
+            });
+        }
+    }
+    if (opts?.readOnly)
+        return all.filter((t) => t.readOnly && !t.authTool);
+    return all;
+}

package/dist/mcp/zod-json.d.ts

@@ -0,0 +1,2 @@
+/** Placeholder — MCP SDK uses Zod shapes directly; keep file for future schema export. */
+export declare function zodToJsonSchema(_z: unknown): unknown;

package/dist/mcp/zod-json.js

@@ -0,0 +1,4 @@
+/** Placeholder — MCP SDK uses Zod shapes directly; keep file for future schema export. */
+export function zodToJsonSchema(_z) {
+    return {};
+}

package/dist/ops/auth.d.ts

@@ -0,0 +1,48 @@
+import type { AuthProvider } from "../auth/types.js";
+import { type ResultEnvelope } from "../dto/result.js";
+export declare const AUTH_TIMEOUT_MAX_S = 900;
+/** Shared CLI/MCP auth operations. Results never contain verifier/access/refresh tokens. */
+export declare class AuthOps {
+    private auth;
+    private flags;
+    constructor(auth: AuthProvider | undefined, flags?: {
+        simulated?: boolean;
+    });
+    private guard;
+    private run;
+    whoami(): Promise<ResultEnvelope<never>> | Promise<{
+        simulated: boolean | undefined;
+        schema_version: typeof import("../dto/result.js").SCHEMA_VERSION;
+        ok: boolean;
+        outcome: import("../dto/result.js").Outcome;
+        code: string;
+        retryable: boolean;
+        request_id: string;
+        data?: import("../auth/types.js").WhoamiLocal | undefined;
+        error?: {
+            message: string;
+            hint?: string;
+            details?: unknown;
+        };
+    }>;
+    begin(): Promise<ResultEnvelope<import("../auth/types.js").AuthBeginResult>>;
+    /** Single poll; pending -> ok:false code auth_pending retryable (safe: read-only poll). */
+    poll(): Promise<ResultEnvelope<import("../auth/types.js").AuthCompleteResult>>;
+    complete(timeoutSeconds?: number, signal?: AbortSignal): Promise<ResultEnvelope<import("../auth/types.js").AuthCompleteResult>>;
+    cancel(): Promise<ResultEnvelope<{
+        had_pending: boolean;
+    }>>;
+    /**
+     * Refresh credentials. Without force: may return refreshed:false / reason already_fresh
+     * when the token is still outside the 5-minute early window (no network call).
+     * With force: always attempts a network refresh (for verification / 401 recovery).
+     */
+    refresh(opts?: {
+        force?: boolean;
+    }): Promise<ResultEnvelope<import("../auth/types.js").RefreshResult>>;
+    logout(): Promise<ResultEnvelope<{
+        note: string;
+        removed_credential: boolean;
+        removed_pending: boolean;
+    }>>;
+}

package/dist/ops/auth.js

@@ -0,0 +1,89 @@
+import { failResult, newRequestId, okResult } from "../dto/result.js";
+import { GbcError } from "../errors.js";
+export const AUTH_TIMEOUT_MAX_S = 900;
+/** Shared CLI/MCP auth operations. Results never contain verifier/access/refresh tokens. */
+export class AuthOps {
+    auth;
+    flags;
+    constructor(auth, flags = {}) {
+        this.auth = auth;
+        this.flags = flags;
+    }
+    guard() {
+        if (!this.auth)
+            throw new GbcError("auth", "no auth provider", { exitCode: 4 });
+        if (this.flags.simulated) {
+            throw new GbcError("unsupported", "auth login/refresh is not available in --mock mode", { exitCode: 9 });
+        }
+        return this.auth;
+    }
+    async run(fn) {
+        const request_id = newRequestId();
+        try {
+            return okResult(await fn(this.guard()), { request_id });
+        }
+        catch (e) {
+            const err = e instanceof GbcError ? e : new GbcError("auth", "auth operation failed", { exitCode: 4 });
+            return failResult(err.code, err.message, {
+                request_id,
+                outcome: err.outcome,
+                retryable: err.retryable,
+                hint: err.hint,
+                details: err.details,
+            });
+        }
+    }
+    whoami() {
+        const request_id = newRequestId();
+        if (!this.auth)
+            return Promise.resolve(failResult("auth", "no auth provider", { request_id }));
+        return this.auth.whoamiLocal().then((w) => ({ ...okResult(w, { request_id }), simulated: this.flags.simulated }));
+    }
+    begin() {
+        return this.run((a) => a.beginLogin());
+    }
+    /** Single poll; pending -> ok:false code auth_pending retryable (safe: read-only poll). */
+    async poll() {
+        const r = await this.run((a) => a.pollLogin());
+        return pendingToFail(r);
+    }
+    async complete(timeoutSeconds, signal) {
+        const t = timeoutSeconds ?? 300;
+        if (!Number.isInteger(t) || t < 1 || t > AUTH_TIMEOUT_MAX_S) {
+            return failResult("invalid_argument", `timeout must be an integer in 1..${AUTH_TIMEOUT_MAX_S} seconds`, {
+                hint: "--timeout=300",
+            });
+        }
+        const r = await this.run((a) => a.completeLogin({ timeoutMs: t * 1000, signal }));
+        return pendingToFail(r);
+    }
+    cancel() {
+        return this.run((a) => a.cancelLogin());
+    }
+    /**
+     * Refresh credentials. Without force: may return refreshed:false / reason already_fresh
+     * when the token is still outside the 5-minute early window (no network call).
+     * With force: always attempts a network refresh (for verification / 401 recovery).
+     */
+    refresh(opts) {
+        return this.run(async (a) => a.refresh({ force: Boolean(opts?.force) }));
+    }
+    logout() {
+        return this.run(async (a) => ({
+            ...(await a.logout()),
+            note: "Local only: removed this tool's own credential/pending files; server-side session not revoked.",
+        }));
+    }
+}
+function pendingToFail(r) {
+    const d = r.data;
+    if (r.ok && d?.status === "pending") {
+        return failResult("auth_pending", d.note ?? "login still pending", {
+            request_id: r.request_id,
+            retryable: true,
+            hint: "Finish sign-in in the browser, then run `gbc auth complete` again.",
+            details: { expires_at_ms: d.expires_at_ms },
+        });
+    }
+    return r;
+}

package/dist/ops/bot.d.ts

@@ -0,0 +1,52 @@
+import type { GrokBotClient } from "../connect/client.js";
+import { type ResultEnvelope } from "../dto/result.js";
+import type { BotSummary } from "../dto/types.js";
+export type WriteOpts = {
+    dryRun?: boolean;
+    /** Required for delete: must equal agent_id. */
+    confirm?: string;
+    allowWrite?: boolean;
+};
+export declare class BotOps {
+    private client;
+    private flags;
+    constructor(client: GrokBotClient, flags?: {
+        simulated?: boolean;
+    });
+    private wrapSim;
+    /** Update/Delete RPC `id` is the numeric server id (App: serverId); accept agent_id UUID by resolving via list. */
+    private serverId;
+    list(opts?: {
+        limit?: number;
+    }): Promise<ResultEnvelope<{
+        bots: BotSummary[];
+        truncated: boolean;
+    }>>;
+    /** No GetBot RPC — filter ListGrokBotAgents client-side (full server page, not the user-facing cap). */
+    get(agentId: string): Promise<ResultEnvelope<{
+        bot: BotSummary;
+    }>>;
+    create(input: {
+        name: string;
+        description?: string;
+        title?: string;
+        agentId?: string;
+        language?: string;
+        kickstart?: boolean;
+    }, write?: WriteOpts): Promise<ResultEnvelope<{
+        bot: BotSummary;
+        agent_id: string;
+    }>>;
+    update(agentId: string, patch: {
+        name?: string;
+        description?: string;
+        title?: string;
+    }, write?: WriteOpts): Promise<ResultEnvelope<{
+        bot: BotSummary;
+    }>>;
+    delete(agentId: string, write?: WriteOpts): Promise<ResultEnvelope<{
+        deleted: boolean;
+        note: string;
+    }>>;
+    private fromErr;
+}