grok-bot-cli 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# grok-bot-cli
+
+CLI for [Grok Bot](https://cursor.com/help/grok-bot/plans) agents and groups: create, delete, membership, send, and read threads.
+
+    gbot bots list
+    gbot send Oncall status
+
+There is no public HTTP API. This talks to the same box gateway the macOS app uses after EnsureSandBox. Use a Cursor session JWT, not a dashboard API key.
+
+## Setup
+
+Package: grok-bot-cli. Node 18+. Bins: gbot and grok-bot.
+
+## Auth
+
+Preferred: a Cursor session JWT in CURSOR_ACCESS_TOKEN.
+
+    gbot bots list
+
+Or set GROK_BOT_GATEWAY_URL plus GROK_BOT_GATEWAY_TOKEN and pass --gateway.
+
+On a Grok Bot computer, SAND_GATEWAY_TOKEN and SAND_HOST_PORT are picked up automatically.
+
+File fallback (local profile.json folders only; no send or thread):
+
+    gbot --files --dir ./tmp-agents bots create --name Oncall
+
+`--dir` is the local agents folder. `--root` is a thread message id.
+
+## Commands
+
+    gbot doctor
+    gbot bots list
+    gbot bots create --name NAME [--description TEXT] [--title TEXT]
+    gbot bots get <id-or-name>
+    gbot bots delete <id-or-name>
+
+    gbot groups list
+    gbot groups create --name NAME --member ID_OR_NAME [--member ...]
+    gbot groups get <id-or-name>
+    gbot groups members <id-or-name>
+    gbot groups add <group> <bot>
+    gbot groups remove <group> <bot>
+    gbot groups set <group> --member ID [--member ...]
+    gbot groups delete <id-or-name>
+
+    gbot send <bot-or-group> <message...>
+    gbot thread <bot-or-group> [--limit N] [--root MESSAGE_ID]
+    gbot chat <bot-or-group>
+
+Global flags: `--json` `--gateway` `--files` `--dir DIR`.
+
+Groups follow the app: at least one member, no nesting, max 6.
+
+## Examples
+
+    gbot bots create --name Oncall --description pages
+    gbot bots create --name Docs
+    gbot groups create --name Launch --member Oncall --member Docs
+    gbot send Oncall status?
+    gbot send Launch standup
+    gbot thread Oncall --limit 20
+    gbot groups delete Launch
+    gbot bots delete Oncall
+
+## Gateway
+
+The macOS app (com.anysphere.sand 0.20.0) calls:
+
+    POST {gateway}/api/listAgents
+    POST {gateway}/api/createAgent
+    POST {gateway}/api/deleteAgent
+    POST {gateway}/api/createGroup
+    POST {gateway}/api/setGroupMembers
+    POST {gateway}/api/sendPrompt
+    POST {gateway}/api/getAgentTranscriptTail
+    POST {gateway}/api/getAgentThread
+
+A group is an agent plus group.json with version 1 and memberIds.
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "grok-bot-cli",
+  "version": "0.1.0",
+  "description": "CLI for Grok Bot agents and groups: create, delete, send, and read threads",
+  "type": "module",
+  "bin": {
+    "gbot": "./src/cli.js",
+    "grok-bot": "./src/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "gbot": "node src/cli.js",
+    "test": "node --test"
+  },
+  "license": "MIT",
+  "keywords": [
+    "grok-bot",
+    "gbot",
+    "cursor",
+    "cli"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+import { MAX_GROUP_MEMBERS, StoreError, defaultCandidateRoots, looksLikeAgentsRoot, resolveAgentsRoot } from "./store.js";
+import { hasGatewayAuth } from "./gateway.js";
+import { openBackend } from "./commands.js";
+
+function print(value) {
+  if (typeof value === "string") process.stdout.write(value + "\n");
+  else process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+
+function fail(err) {
+  let message = err instanceof Error ? err.message : String(err);
+  message = message.replace(/Bearer\s+[A-Za-z0-9._\-]+/g, "Bearer <redacted>");
+  process.stderr.write(message + "\n");
+  process.exit(1);
+}
+
+function usage() {
+  return [
+    "gbot - manage Grok Bot agents and groups",
+    "",
+    "Usage:",
+    "  gbot [--dir DIR] [--json] <command>",
+    "",
+    "Commands:",
+    "  doctor",
+    "  bots list",
+    "  bots create --name NAME [--description TEXT] [--title TEXT]",
+    "  bots get <id-or-name>",
+    "  bots delete <id-or-name>",
+    "  groups list",
+    "  groups create --name NAME --member ID_OR_NAME [--member ...]",
+    "  groups get <id-or-name>",
+    "  groups members <id-or-name>",
+    "  groups add <group> <bot>",
+    "  groups remove <group> <bot>",
+    "  groups set <group> --member ID [--member ...]",
+    "  groups delete <id-or-name>",
+    "  send <bot-or-group> <message...>",
+    "  thread <bot-or-group> [--limit N] [--root MESSAGE_ID]",
+    "  chat <bot-or-group>     alias for thread",
+    "",
+    "Max group members: " + MAX_GROUP_MEMBERS,
+    "Flags: --gateway  --files  --dir DIR  --json",
+    "Env: CURSOR_ACCESS_TOKEN or GROK_BOT_GATEWAY_URL + GROK_BOT_GATEWAY_TOKEN",
+    "File fallback: GROK_BOT_AGENTS_DIR",
+  ].join("\n");
+}
+
+function takeFlag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  const value = args[i + 1];
+  if (value == null || value.startsWith("-")) throw new StoreError(name + " needs a value");
+  args.splice(i, 2);
+  return value;
+}
+
+function takeRepeating(args, name) {
+  const out = [];
+  for (;;) {
+    const value = takeFlag(args, name);
+    if (value == null) break;
+    out.push(value);
+  }
+  return out;
+}
+
+function hasFlag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return false;
+  args.splice(i, 1);
+  return true;
+}
+
+function summarize(rec) {
+  return {
+    id: rec.id,
+    name: rec.name,
+    title: rec.title || undefined,
+    description: rec.description || undefined,
+    kind: rec.isGroup ? "group" : "bot",
+    members: rec.isGroup ? rec.memberIds : undefined,
+  };
+}
+
+function done(json, rec, text) {
+  print(json ? summarize(rec) : text);
+}
+
+function formatRecord(rec, all) {
+  const kind = rec.isGroup ? "group" : "bot";
+  const members = rec.isGroup
+    ? rec.memberIds.map((id) => {
+        const m = all.find((r) => r.id === id);
+        return m ? m.name + " (" + id + ")" : id;
+      }).join(", ")
+    : "";
+  const title = rec.title ? " - " + rec.title : "";
+  const desc = rec.description ? "\n    " + rec.description : "";
+  const extra = rec.isGroup ? "\n    members (" + rec.memberIds.length + "): " + (members || "(none)") : "";
+  return kind + "  " + rec.name + title + "\n    " + rec.id + desc + extra;
+}
+
+function entryText(e) {
+  if (!e || typeof e !== "object") return "";
+  const direct = e.text || e.prompt || e.message || e.preview;
+  if (typeof direct === "string" && direct) return direct;
+  const content = e.content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => {
+      if (typeof part === "string") return part;
+      if (part && typeof part === "object") return part.text || part.content || "";
+      return "";
+    }).filter(Boolean).join("\n");
+  }
+  if (content && typeof content === "object") return content.text || JSON.stringify(content);
+  return "";
+}
+
+function formatTranscript(out) {
+  const rec = out.target;
+  const payload = out.transcript || out.thread || {};
+  const entries = payload.entries || payload.messages || payload.items || (Array.isArray(payload) ? payload : []);
+  const header = (rec.isGroup ? "group" : "bot") + "  " + rec.name + "\n    " + rec.id;
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return header + "\n    (no messages)";
+  }
+  const lines = [header, ""];
+  for (const e of entries) {
+    const role = e.role || e.kind || e.sender || e.type || "msg";
+    const text = entryText(e);
+    const id = e.id || e.messageId || "";
+    lines.push("[" + role + (id ? " " + id : "") + "] " + String(text).slice(0, 400));
+  }
+  return lines.join("\n");
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+    print(usage());
+    return;
+  }
+
+  const json = hasFlag(args, "--json");
+  const gateway = hasFlag(args, "--gateway");
+  const filesMode = hasFlag(args, "--files");
+  const rootFlag = takeFlag(args, "--dir");
+  const cmd = args[0];
+  const sub = args[1];
+  const rest = args.slice(2);
+  if (!cmd) {
+    print(usage());
+    return;
+  }
+
+  if (cmd === "doctor") {
+    const candidates = defaultCandidateRoots();
+    const found = candidates.filter(looksLikeAgentsRoot);
+    let resolved = null;
+    try {
+      resolved = resolveAgentsRoot(rootFlag);
+    } catch (err) {
+      if (!(err instanceof StoreError)) throw err;
+    }
+    const note = "Live roster is on the box. Prefer CURSOR_ACCESS_TOKEN then EnsureSandBox then POST gateway /api/*.";
+    const payload = { resolved, found, candidates, gatewayAuthPresent: hasGatewayAuth(), note };
+    if (json) print(payload);
+    else {
+      print("resolved: " + (resolved ?? "(none)"));
+      print("gateway auth: " + (hasGatewayAuth() ? "yes (env)" : "no"));
+      print("found:");
+      print(found.length ? found.map((p) => "  " + p).join("\n") : "  (none)");
+      print("candidates:");
+      for (const c of candidates) print("  " + c);
+      print(note);
+    }
+    return;
+  }
+
+  const backend = await openBackend({ root: rootFlag, gateway, files: filesMode });
+
+  if (cmd === "bots" && sub === "list") {
+    const rows = (await backend.list()).filter((r) => !r.isGroup);
+    if (json) print(rows.map(summarize));
+    else if (rows.length === 0) print("No bots.");
+    else print(rows.map((r) => formatRecord(r, rows)).join("\n\n"));
+    return;
+  }
+
+  if (cmd === "bots" && sub === "create") {
+    const name = takeFlag(rest, "--name");
+    const description = takeFlag(rest, "--description") ?? "";
+    const title = takeFlag(rest, "--title") ?? "";
+    const rec = await backend.createAgent({ name, description, title });
+    done(json, rec, "Created bot " + rec.name + " (" + rec.id + ")");
+    return;
+  }
+
+  if (cmd === "bots" && (sub === "get" || sub === "delete")) {
+    const ref = rest[0];
+    if (!ref) throw new StoreError("gbot bots " + sub + " <id-or-name>");
+    if (sub === "get") {
+      const rec = await backend.resolve(ref);
+      if (json) print(summarize(rec));
+      else print(formatRecord(rec, await backend.list()));
+      return;
+    }
+    const rec = await backend.deleteAgent(ref);
+    done(json, rec, "Deleted " + (rec.isGroup ? "group" : "bot") + " " + rec.name + " (" + rec.id + ")");
+    return;
+  }
+
+  if (cmd === "groups" && sub === "list") {
+    const all = await backend.list();
+    const rows = all.filter((r) => r.isGroup);
+    if (json) print(rows.map(summarize));
+    else if (rows.length === 0) print("No groups.");
+    else print(rows.map((r) => formatRecord(r, all)).join("\n\n"));
+    return;
+  }
+
+  if (cmd === "groups" && sub === "delete") {
+    const ref = rest[0];
+    if (!ref) throw new StoreError("gbot groups delete <id-or-name>");
+    const rec = await backend.resolve(ref);
+    if (!rec.isGroup) throw new StoreError('"' + rec.name + '" is a bot, not a group. Use bots delete.');
+    const deleted = await backend.deleteAgent(ref);
+    done(json, deleted, "Deleted group " + deleted.name + " (" + deleted.id + ")");
+    return;
+  }
+
+  if (cmd === "groups" && sub === "create") {
+    const name = takeFlag(rest, "--name");
+    const description = takeFlag(rest, "--description") ?? "";
+    const members = takeRepeating(rest, "--member");
+    const rec = await backend.createGroup({ name, description, memberIds: members });
+    done(json, rec, "Created group " + rec.name + " (" + rec.id + ") with " + rec.memberIds.length + " members");
+    return;
+  }
+
+  if (cmd === "groups" && (sub === "get" || sub === "members")) {
+    const ref = rest[0];
+    if (!ref) throw new StoreError("gbot groups " + sub + " <id-or-name>");
+    const rec = await backend.resolve(ref);
+    if (!rec.isGroup) throw new StoreError('"' + rec.name + '" is a bot, not a group.');
+    if (json) print(summarize(rec));
+    else print(formatRecord(rec, await backend.list()));
+    return;
+  }
+
+  if (cmd === "groups" && (sub === "add" || sub === "remove")) {
+    const group = rest[0];
+    const bot = rest[1];
+    if (!group || !bot) throw new StoreError("gbot groups " + sub + " <group> <bot>");
+    const rec = sub === "add"
+      ? await backend.addGroupMember(group, bot)
+      : await backend.removeGroupMember(group, bot);
+    const verb = sub === "add" ? "Added to " : "Removed from ";
+    done(json, rec, verb + rec.name + ". Members: " + rec.memberIds.length);
+    return;
+  }
+
+  if (cmd === "groups" && sub === "set") {
+    const group = rest.shift();
+    const members = takeRepeating(rest, "--member");
+    if (!group) throw new StoreError("gbot groups set <group> --member ID [--member ...]");
+    const rec = await backend.setGroupMembers(group, members);
+    done(json, rec, "Updated " + rec.name + ". Members: " + rec.memberIds.length);
+    return;
+  }
+
+  if (cmd === "send") {
+    const ref = sub;
+    const message = rest.join(" ").trim();
+    if (!ref || !message) throw new StoreError("gbot send <bot-or-group> <message...>");
+    const out = await backend.send(ref, message);
+    if (json) print({ id: out.target.id, name: out.target.name, kind: out.target.isGroup ? "group" : "bot", result: out.result });
+    else print("Sent to " + (out.target.isGroup ? "group" : "bot") + " " + out.target.name + " (" + out.target.id + ")");
+    return;
+  }
+
+  if (cmd === "thread" || cmd === "chat") {
+    const ref = sub;
+    if (!ref) throw new StoreError("gbot thread <bot-or-group> [--limit N] [--root MESSAGE_ID]");
+    const limitRaw = takeFlag(rest, "--limit");
+    const rootId = takeFlag(rest, "--root");
+    const limit = limitRaw ? Number(limitRaw) : 40;
+    const out = rootId ? await backend.thread(ref, rootId) : await backend.transcript(ref, limit);
+    if (json) print(out);
+    else print(formatTranscript(out));
+    return;
+  }
+
+  throw new StoreError(usage());
+}
+
+main(process.argv).catch(fail);

package/src/commands.js

@@ -0,0 +1,50 @@
+import * as files from "./store.js";
+import * as gw from "./gateway.js";
+
+export function chooseBackend(opts) {
+  const forceFiles = Boolean(opts.root) || opts.files;
+  const forceGw = Boolean(opts.gateway);
+  if (forceGw && forceFiles) {
+    throw new files.StoreError("Use --dir/--files or --gateway, not both.");
+  }
+  if (forceGw || (!forceFiles && gw.hasGatewayAuth())) return "gateway";
+  return "files";
+}
+
+export async function openBackend(opts) {
+  const kind = chooseBackend(opts);
+  if (kind === "gateway") {
+    const session = await gw.connectGateway();
+    return {
+      kind,
+      session,
+      list: () => gw.listAgents(session),
+      resolve: (ref) => gw.resolveRef(session, ref),
+      createAgent: (input) => gw.createAgent(session, input),
+      deleteAgent: (ref) => gw.deleteAgent(session, ref),
+      createGroup: (input) => gw.createGroup(session, input),
+      setGroupMembers: (group, members) => gw.setGroupMembers(session, group, members),
+      addGroupMember: (group, bot) => gw.addGroupMember(session, group, bot),
+      removeGroupMember: (group, bot) => gw.removeGroupMember(session, group, bot),
+      send: (ref, prompt, extra) => gw.sendPrompt(session, ref, prompt, extra),
+      transcript: (ref, limit) => gw.getTranscriptTail(session, ref, limit),
+      thread: (ref, rootId) => gw.getThread(session, ref, rootId),
+    };
+  }
+  const root = files.resolveAgentsRoot(opts.root);
+  return {
+    kind,
+    root,
+    list: async () => files.listRecords(root),
+    resolve: async (ref) => files.resolveRef(root, ref),
+    createAgent: async (input) => files.createAgent(root, input),
+    deleteAgent: async (ref) => files.deleteAgent(root, ref),
+    createGroup: async (input) => files.createGroup(root, input),
+    setGroupMembers: async (group, members) => files.setGroupMembers(root, group, members),
+    addGroupMember: async (group, bot) => files.addGroupMember(root, group, bot),
+    removeGroupMember: async (group, bot) => files.removeGroupMember(root, group, bot),
+    send: async () => { throw new files.StoreError("send requires the live gateway"); },
+    transcript: async () => { throw new files.StoreError("thread requires the live gateway"); },
+    thread: async () => { throw new files.StoreError("thread requires the live gateway"); },
+  };
+}

package/src/gateway.js

@@ -0,0 +1,248 @@
+import { randomUUID } from "node:crypto";
+
+export class GatewayError extends Error {
+  constructor(message, { status, method } = {}) {
+    super(message);
+    this.name = "GatewayError";
+    this.status = status;
+    this.method = method;
+  }
+}
+
+function backendBase() {
+  return (
+    process.env.SAND_BACKEND_URL ||
+    process.env.CURSOR_API_BASE_URL ||
+    "https://api2.cursor.sh"
+  ).replace(/\/$/, "");
+}
+
+function accessTokenFromEnv() {
+  return (
+    process.env.CURSOR_ACCESS_TOKEN ||
+    process.env.GROK_BOT_ACCESS_TOKEN ||
+    process.env.SAND_ACCESS_TOKEN ||
+    ""
+  ).trim();
+}
+
+function gatewayTokenFromEnv() {
+  return (
+    process.env.GROK_BOT_GATEWAY_TOKEN ||
+    process.env.SAND_HOST_GATEWAY_TOKEN ||
+    process.env.SAND_GATEWAY_TOKEN ||
+    ""
+  ).trim();
+}
+
+function gatewayOverride() {
+  const token = gatewayTokenFromEnv();
+  const explicitUrl = (process.env.GROK_BOT_GATEWAY_URL || process.env.SAND_HOST_GATEWAY_URL || "").trim();
+  const localUrl = token
+    ? "http://127.0.0.1:" + (process.env.SAND_HOST_PORT || "1340")
+    : "";
+  const url = explicitUrl || localUrl;
+  if (url && token) return { gatewayUrl: url.replace(/\/$/, ""), gatewayToken: token };
+  return null;
+}
+
+export function hasGatewayAuth() {
+  return Boolean(gatewayOverride() || accessTokenFromEnv());
+}
+
+async function readJson(res) {
+  const text = await res.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function pick(obj, ...keys) {
+  if (!obj || typeof obj !== "object") return undefined;
+  for (const key of keys) {
+    if (obj[key] != null && obj[key] !== "") return obj[key];
+  }
+  return undefined;
+}
+
+export async function ensureSandbox(accessToken) {
+  const url = backendBase() + "/aiserver.v1.GrokBotService/EnsureSandBox";
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "connect-protocol-version": "1",
+      authorization: "Bearer " + accessToken,
+      "x-cursor-client-type": "sand",
+      "x-cursor-client-version": process.env.SAND_CLIENT_VERSION || "0.20.0",
+      "x-sand-box-namespace": process.env.SAND_BOX_NAMESPACE || "prod",
+    },
+    body: "{}",
+  });
+  const body = await readJson(res);
+  if (!res.ok) {
+    const detail = body.message || body.error || body.raw || res.statusText;
+    throw new GatewayError("EnsureSandBox failed: " + res.status + " " + detail, { status: res.status, method: "EnsureSandBox" });
+  }
+  const gatewayUrl = pick(body, "gatewayUrl", "gateway_url");
+  const gatewayToken = pick(body, "gatewayToken", "gateway_token");
+  if (!gatewayUrl || !gatewayToken) {
+    throw new GatewayError("EnsureSandBox returned no gatewayUrl/gatewayToken. Auth may be a dashboard API key (those do not work).");
+  }
+  return { gatewayUrl: String(gatewayUrl).replace(/\/$/, ""), gatewayToken: String(gatewayToken) };
+}
+
+export async function connectGateway() {
+  const override = gatewayOverride();
+  if (override) return override;
+  const token = accessTokenFromEnv();
+  if (!token) {
+    throw new GatewayError("Set CURSOR_ACCESS_TOKEN, or GROK_BOT_GATEWAY_URL + GROK_BOT_GATEWAY_TOKEN. Do not use a Cursor dashboard API key.");
+  }
+  return ensureSandbox(token);
+}
+
+export async function gatewayCall(session, method, body = {}) {
+  const url = session.gatewayUrl + "/api/" + method;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: "Bearer " + session.gatewayToken,
+    },
+    body: JSON.stringify(body),
+  });
+  const data = await readJson(res);
+  if (!res.ok) {
+    const detail = data.message || data.error || data.raw || res.statusText;
+    throw new GatewayError(method + " failed: " + res.status + " " + String(detail).slice(0, 300), { status: res.status, method });
+  }
+  return data;
+}
+
+function asRecord(agent) {
+  if (!agent) return null;
+  const id = agent.id || agent.agentId;
+  const memberIds = agent.memberIds || agent.memberAgentIds || [];
+  return {
+    id,
+    name: agent.name || "",
+    title: agent.title || "",
+    description: agent.description || "",
+    isGroup: agent.isGroup === true || (agent.isGroup == null && Array.isArray(memberIds) && memberIds.length > 0),
+    memberIds: Array.isArray(memberIds) ? memberIds : [],
+  };
+}
+
+function unwrapList(data) {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data.agents)) return data.agents;
+  if (data.agent) return [data.agent];
+  return [];
+}
+
+function unwrapOne(data) {
+  return asRecord(data.agent || data);
+}
+
+export async function listAgents(session) {
+  const data = await gatewayCall(session, "listAgents", {});
+  return unwrapList(data).map(asRecord).filter((r) => r && r.id);
+}
+
+function resolveFromList(records, ref) {
+  const needle = String(ref).trim().toLowerCase();
+  const byId = records.find((r) => r.id.toLowerCase() === needle);
+  if (byId) return byId;
+  const matches = records.filter((r) => r.name.toLowerCase() === needle || r.title.toLowerCase() === needle);
+  if (matches.length === 1) return matches[0];
+  if (matches.length === 0) throw new GatewayError("No bot or group named \"" + ref + "\"");
+  throw new GatewayError("Ambiguous name \"" + ref + "\"");
+}
+
+export async function resolveRef(session, ref) {
+  return resolveFromList(await listAgents(session), ref);
+}
+
+export async function createAgent(session, input) {
+  const data = await gatewayCall(session, "createAgent", {
+    name: input.name,
+    description: input.description || "",
+    title: input.title || "",
+    avatarShape: input.avatarShape || "",
+    avatarColor: input.avatarColor || "",
+    origin: "user",
+  });
+  return unwrapOne(data);
+}
+
+export async function deleteAgent(session, ref) {
+  const rec = await resolveRef(session, ref);
+  await gatewayCall(session, "deleteAgent", { id: rec.id });
+  return rec;
+}
+
+export async function createGroup(session, input) {
+  const records = await listAgents(session);
+  const memberAgentIds = (input.memberIds || []).map((ref) => resolveFromList(records, ref).id);
+  const data = await gatewayCall(session, "createGroup", {
+    name: input.name,
+    description: input.description || "",
+    memberAgentIds,
+  });
+  return unwrapOne(data);
+}
+
+export async function setGroupMembers(session, groupRef, memberRefs) {
+  const records = await listAgents(session);
+  const group = resolveFromList(records, groupRef);
+  const memberAgentIds = memberRefs.map((ref) => resolveFromList(records, ref).id);
+  const data = await gatewayCall(session, "setGroupMembers", {
+    id: group.id,
+    memberAgentIds,
+  });
+  return unwrapOne(data) || { ...group, memberIds: memberAgentIds, isGroup: true };
+}
+
+export async function addGroupMember(session, groupRef, memberRef) {
+  const records = await listAgents(session);
+  const group = resolveFromList(records, groupRef);
+  const member = resolveFromList(records, memberRef);
+  const next = [...new Set([...group.memberIds, member.id])];
+  return setGroupMembers(session, group.id, next);
+}
+
+export async function removeGroupMember(session, groupRef, memberRef) {
+  const records = await listAgents(session);
+  const group = resolveFromList(records, groupRef);
+  const member = resolveFromList(records, memberRef);
+  const next = group.memberIds.filter((id) => id !== member.id);
+  return setGroupMembers(session, group.id, next);
+}
+
+export async function sendPrompt(session, ref, prompt, extra = {}) {
+  const rec = await resolveRef(session, ref);
+  const body = {
+    agentId: rec.id,
+    prompt,
+    clientNonce: extra.clientNonce || randomUUID(),
+  };
+  if (extra.replyToId) body.replyToId = extra.replyToId;
+  const data = await gatewayCall(session, "sendPrompt", body);
+  return { target: rec, result: data };
+}
+
+export async function getTranscriptTail(session, ref, limit = 50) {
+  const rec = await resolveRef(session, ref);
+  const data = await gatewayCall(session, "getAgentTranscriptTail", { id: rec.id, limit });
+  return { target: rec, transcript: data };
+}
+
+export async function getThread(session, ref, rootId) {
+  const rec = await resolveRef(session, ref);
+  const data = await gatewayCall(session, "getAgentThread", { id: rec.id, rootId });
+  return { target: rec, thread: data };
+}

package/src/store.js

@@ -0,0 +1,262 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const GROUP_JSON_VERSION = 1;
+export const MAX_GROUP_MEMBERS = 6;
+export const PROFILE_FILE = "profile.json";
+export const GROUP_FILE = "group.json";
+export const SETTINGS_FILE = "settings.json";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export class StoreError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StoreError";
+  }
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function isUuid(value) {
+  return UUID_RE.test(value);
+}
+
+export function defaultCandidateRoots() {
+  const home = homedir();
+  const env = [
+    process.env.GROK_BOT_AGENTS_DIR,
+    process.env.SAND_AGENTS_DIR,
+    process.env.SAND_DATA_ROOT && join(process.env.SAND_DATA_ROOT, "agents"),
+    process.env.SAND_DATA_ROOT && join(process.env.SAND_DATA_ROOT, "agent-data", "agents"),
+  ].filter(Boolean);
+
+  return [
+    ...env,
+    "/home/box/agent-data/agents",
+    "/home/box/sand-data/agents",
+    join(home, ".grokbot", "agent-data", "agents"),
+    join(home, ".grokbot", "sand-data", "agents"),
+    join(home, "Library", "Application Support", "Grok Bot", "agent-data", "agents"),
+    join(home, "Library", "Application Support", "Grok Bot", "sand-data", "agents"),
+  ];
+}
+
+export function looksLikeAgentsRoot(dir) {
+  if (!dir || !existsSync(dir) || !statSync(dir).isDirectory()) return false;
+  const entries = readdirSync(dir, { withFileTypes: true });
+  return entries.some(
+    (e) => e.isDirectory() && isUuid(e.name) && existsSync(join(dir, e.name, PROFILE_FILE)),
+  );
+}
+
+export function resolveAgentsRoot(explicit) {
+  if (explicit) {
+    mkdirSync(explicit, { recursive: true });
+    return explicit;
+  }
+  for (const candidate of defaultCandidateRoots()) {
+    if (looksLikeAgentsRoot(candidate)) return candidate;
+  }
+  throw new StoreError(
+    "Could not find a Grok Bot agents directory. Pass --dir or set GROK_BOT_AGENTS_DIR.\nThe macOS app keeps the live roster on its cloud computer (agent-data/agents), not in ~/Library/Application Support/Grok Bot.",
+  );
+}
+
+function readProfile(dir) {
+  const path = join(dir, PROFILE_FILE);
+  if (!existsSync(path)) return null;
+  const raw = readJson(path);
+  return {
+    name: String(raw.name ?? ""),
+    description: String(raw.description ?? ""),
+    title: String(raw.title ?? ""),
+    avatarShape: String(raw.avatarShape ?? ""),
+    avatarColor: String(raw.avatarColor ?? ""),
+  };
+}
+
+function readGroup(dir) {
+  const path = join(dir, GROUP_FILE);
+  if (!existsSync(path)) return null;
+  const raw = readJson(path);
+  const memberIds = Array.isArray(raw.memberIds) ? raw.memberIds.map(String) : [];
+  return {
+    version: Number(raw.version ?? GROUP_JSON_VERSION),
+    memberIds,
+  };
+}
+
+export function listRecords(root) {
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !isUuid(entry.name)) continue;
+    const dir = join(root, entry.name);
+    const profile = readProfile(dir);
+    if (!profile) continue;
+    const group = readGroup(dir);
+    out.push({
+      id: entry.name,
+      path: dir,
+      ...profile,
+      isGroup: group != null,
+      memberIds: group?.memberIds ?? [],
+    });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+}
+
+export function resolveRef(root, ref) {
+  const records = listRecords(root);
+  if (isUuid(ref)) {
+    const exact = records.find((r) => r.id.toLowerCase() === ref.toLowerCase());
+    if (!exact) throw new StoreError(`No bot or group with id ${ref}`);
+    return exact;
+  }
+  const needle = ref.trim().toLowerCase();
+  const matches = records.filter(
+    (r) => r.name.toLowerCase() === needle || r.title.toLowerCase() === needle,
+  );
+  if (matches.length === 1) return matches[0];
+  if (matches.length === 0) throw new StoreError(`No bot or group named "${ref}"`);
+  throw new StoreError(
+    `Ambiguous name "${ref}": ${matches.map((m) => `${m.name} (${m.id})`).join(", ")}`,
+  );
+}
+
+function writeProfile(dir, profile) {
+  writeJson(join(dir, PROFILE_FILE), {
+    name: profile.name.trim(),
+    description: (profile.description ?? "").trim(),
+    title: (profile.title ?? "").trim(),
+    avatarShape: (profile.avatarShape ?? "").trim(),
+    avatarColor: (profile.avatarColor ?? "").trim(),
+  });
+}
+
+function writeSettings(dir) {
+  writeJson(join(dir, SETTINGS_FILE), { notifyOnAgentUpdates: true });
+}
+
+function writeGroup(dir, memberIds) {
+  writeJson(join(dir, GROUP_FILE), {
+    version: GROUP_JSON_VERSION,
+    memberIds,
+  });
+}
+
+function normalizeMemberIds(root, memberRefs, { groupId } = {}) {
+  const records = listRecords(root);
+  const byId = new Map(records.map((r) => [r.id, r]));
+  const groups = new Set(records.filter((r) => r.isGroup).map((r) => r.id));
+  const resolved = [];
+  const seen = new Set();
+  for (const ref of memberRefs) {
+    const rec = resolveRef(root, ref);
+    if (groups.has(rec.id)) {
+      throw new StoreError(`Cannot add group "${rec.name}" as a member. Nested groups are not allowed.`);
+    }
+    if (groupId && rec.id === groupId) continue;
+    if (!byId.has(rec.id)) continue;
+    if (seen.has(rec.id)) continue;
+    seen.add(rec.id);
+    resolved.push(rec.id);
+  }
+  if (resolved.length > MAX_GROUP_MEMBERS) {
+    throw new StoreError(`A group can have at most ${MAX_GROUP_MEMBERS} members.`);
+  }
+  return resolved;
+}
+
+export function createAgent(root, input) {
+  const name = (input.name ?? "").trim();
+  if (!name) throw new StoreError("Name is required.");
+  const id = randomUUID();
+  const dir = join(root, id);
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(join(dir, "memory"), { recursive: true });
+  mkdirSync(join(dir, "automations"), { recursive: true });
+  writeProfile(dir, {
+    name,
+    description: input.description ?? "",
+    title: input.title ?? "",
+    avatarShape: input.avatarShape ?? "",
+    avatarColor: input.avatarColor ?? "",
+  });
+  writeSettings(dir);
+  return resolveRef(root, id);
+}
+
+export function deleteAgent(root, ref) {
+  const rec = resolveRef(root, ref);
+  rmSync(rec.path, { recursive: true, force: true });
+  for (const other of listRecords(root).filter((r) => r.isGroup)) {
+    if (!other.memberIds.includes(rec.id)) continue;
+    writeGroup(
+      other.path,
+      other.memberIds.filter((id) => id !== rec.id),
+    );
+  }
+  return rec;
+}
+
+export function createGroup(root, input) {
+  const memberIds = normalizeMemberIds(root, input.memberIds ?? []);
+  if (memberIds.length === 0) {
+    throw new StoreError("A group needs at least one existing member agent.");
+  }
+  const existing = listRecords(root).find(
+    (r) =>
+      r.isGroup &&
+      r.memberIds.length === memberIds.length &&
+      r.memberIds.every((id) => memberIds.includes(id)),
+  );
+  if (existing) return existing;
+  const group = createAgent(root, {
+    name: input.name,
+    description: input.description ?? "",
+    title: input.title ?? "",
+  });
+  writeGroup(join(root, group.id), memberIds);
+  return resolveRef(root, group.id);
+}
+
+export function setGroupMembers(root, groupRef, memberRefs) {
+  const group = resolveRef(root, groupRef);
+  if (!group.isGroup) throw new StoreError(`"${group.name}" is a bot, not a group.`);
+  const memberIds = normalizeMemberIds(root, memberRefs, { groupId: group.id });
+  if (memberIds.length === 0) {
+    throw new StoreError("A group needs at least one existing member agent.");
+  }
+  writeGroup(group.path, memberIds);
+  return resolveRef(root, group.id);
+}
+
+export function addGroupMember(root, groupRef, memberRef) {
+  const group = resolveRef(root, groupRef);
+  return setGroupMembers(root, group.id, [...group.memberIds, memberRef]);
+}
+
+export function removeGroupMember(root, groupRef, memberRef) {
+  const group = resolveRef(root, groupRef);
+  const member = resolveRef(root, memberRef);
+  return setGroupMembers(root, group.id, group.memberIds.filter((id) => id !== member.id));
+}