grok-bot-cli 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScriptedAlchemy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,84 +1,42 @@
 # grok-bot-cli
 
-CLI for [Grok Bot](https://cursor.com/help/grok-bot/plans) agents and groups: create, delete, membership, send, and read threads.
+[![npm version](https://img.shields.io/npm/v/grok-bot-cli.svg)](https://www.npmjs.com/package/grok-bot-cli)
 
-    gbot bots list
-    gbot send Oncall status
+Manage [Grok Bot](https://cursor.com/help/grok-bot/plans) agents, groups, and messages from your terminal.
 
-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.
+![Live create, group, send, and delete smoke test](https://raw.githubusercontent.com/ScriptedAlchemy/grok-bot-cli/main/demo/grok-bot-cli-demo.gif)
 
-## Setup
+[Watch the MP4](https://github.com/ScriptedAlchemy/grok-bot-cli/blob/main/demo/grok-bot-cli-demo.mp4)
 
-Package: grok-bot-cli. Node 18+. Bins: gbot and grok-bot.
+## Install
 
-## Auth
+```sh
+npm install --global grok-bot-cli
+```
 
-Preferred: a Cursor session JWT in CURSOR_ACCESS_TOKEN.
+Requires Node.js 18+ and the Grok Bot macOS app. Open Grok Bot and sign in once; `gbot` automatically uses the app's encrypted session and routing credentials. No token copying is required.
 
-    gbot bots list
+## Use
 
-Or set GROK_BOT_GATEWAY_URL plus GROK_BOT_GATEWAY_TOKEN and pass --gateway.
+```sh
+gbot bots list
+gbot bots create --name Researcher
+gbot bots update Researcher --description "Research the launch" --notify on
+gbot bots create --name Writer
+gbot groups create --name Launch --member Researcher --member Writer --description "Ship together"
+gbot groups update Launch --title "Launch room" --hidden off
+gbot send Researcher "Summarize the launch status."
+gbot send Launch "Share your updates."
+gbot thread Researcher
+gbot groups delete Launch
+gbot bots delete Researcher
+gbot bots delete Writer
+```
 
-On a Grok Bot computer, SAND_GATEWAY_TOKEN and SAND_HOST_PORT are picked up automatically.
+`update` fields: `--name` `--description`/`--instructions` `--title` `--avatar-shape` `--avatar-color` `--notify` `--hidden`. `--description` is the UI Instructions field.
 
-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.
+Run `gbot --help` for every command.
 
 ## License
 
 MIT
-

package/package.json

@@ -1,28 +1,48 @@
 {
   "name": "grok-bot-cli",
-  "version": "0.1.0",
-  "description": "CLI for Grok Bot agents and groups: create, delete, send, and read threads",
+  "version": "0.2.1",
+  "description": "CLI for Grok Bot agents and groups: create, update, message, inspect threads, and automate cleanup",
   "type": "module",
   "bin": {
-    "gbot": "./src/cli.js",
-    "grok-bot": "./src/cli.js"
+    "gbot": "src/cli.js",
+    "grok-bot": "src/cli.js"
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
+    "changeset": "changeset",
     "gbot": "node src/cli.js",
+    "release": "changeset publish",
     "test": "node --test"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ScriptedAlchemy/grok-bot-cli.git"
+  },
+  "homepage": "https://github.com/ScriptedAlchemy/grok-bot-cli#readme",
+  "bugs": {
+    "url": "https://github.com/ScriptedAlchemy/grok-bot-cli/issues"
+  },
+  "author": "Zack Jackson (https://github.com/ScriptedAlchemy)",
   "license": "MIT",
   "keywords": [
+    "grok",
     "grok-bot",
+    "grokbot",
     "gbot",
     "cursor",
+    "ai-agents",
+    "automation",
+    "terminal",
     "cli"
   ],
   "files": [
     "src",
-    "README.md"
-  ]
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "2.31.1"
+  }
 }

package/src/app-session.js

@@ -0,0 +1,74 @@
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SAFE_STORAGE_PREFIX = Buffer.from("v10");
+
+export function decryptSafeStorageString(encryptedBase64, password) {
+  const encrypted = Buffer.from(encryptedBase64, "base64");
+  if (!encrypted.subarray(0, 3).equals(SAFE_STORAGE_PREFIX)) {
+    throw new Error("Unsupported Grok Bot Safe Storage format.");
+  }
+
+  const key = crypto.pbkdf2Sync(password, "saltysalt", 1003, 16, "sha1");
+  const decipher = crypto.createDecipheriv(
+    "aes-128-cbc",
+    key,
+    Buffer.alloc(16, 32),
+  );
+  return Buffer.concat([
+    decipher.update(encrypted.subarray(3)),
+    decipher.final(),
+  ]).toString("utf8");
+}
+
+export function grokBotGatewayDescriptorPath(home = homedir()) {
+  return join(
+    home,
+    "Library/Application Support/Grok Bot/gateway-descriptor.json",
+  );
+}
+
+export function hasGrokBotGatewaySession({
+  platform = process.platform,
+  home = homedir(),
+} = {}) {
+  return platform === "darwin" && existsSync(grokBotGatewayDescriptorPath(home));
+}
+
+function readKeychainPassword() {
+  return execFileSync(
+    "/usr/bin/security",
+    ["find-generic-password", "-w", "-s", "Grok Bot Safe Storage"],
+    { encoding: "utf8" },
+  ).trimEnd();
+}
+
+export function loadGrokBotGatewaySession({
+  platform = process.platform,
+  home = homedir(),
+  getKeychainPassword = readKeychainPassword,
+} = {}) {
+  if (platform !== "darwin") return null;
+
+  const path = grokBotGatewayDescriptorPath(home);
+  if (!existsSync(path)) return null;
+
+  const wrapped = JSON.parse(readFileSync(path, "utf8"));
+  const clear = decryptSafeStorageString(
+    wrapped.encrypted,
+    getKeychainPassword(),
+  );
+  const descriptor = JSON.parse(clear);
+  if (!descriptor.baseUrl || !descriptor.token) {
+    throw new Error("Grok Bot gateway descriptor is incomplete.");
+  }
+
+  return {
+    gatewayUrl: String(descriptor.baseUrl).replace(/\/$/, ""),
+    gatewayToken: String(descriptor.token),
+    headers: descriptor.headers ?? {},
+  };
+}

package/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { MAX_GROUP_MEMBERS, StoreError, defaultCandidateRoots, looksLikeAgentsRoot, resolveAgentsRoot } from "./store.js";
+import { AVATAR_COLORS, AVATAR_SHAPES, MAX_GROUP_MEMBERS, StoreError, defaultCandidateRoots, looksLikeAgentsRoot, resolveAgentsRoot } from "./store.js";
 import { hasGatewayAuth } from "./gateway.js";
 import { openBackend } from "./commands.js";
 
@@ -25,11 +25,18 @@ function usage() {
     "Commands:",
     "  doctor",
     "  bots list",
-    "  bots create --name NAME [--description TEXT] [--title TEXT]",
+    "  bots create --name NAME [--description TEXT] [--instructions TEXT] [--title TEXT]",
+    "           [--avatar-shape SHAPE] [--avatar-color COLOR]",
+    "  bots update <id-or-name> [--name NAME] [--description TEXT] [--instructions TEXT]",
+    "           [--title TEXT] [--avatar-shape SHAPE] [--avatar-color COLOR]",
+    "           [--notify on|off] [--hidden on|off]",
     "  bots get <id-or-name>",
     "  bots delete <id-or-name>",
     "  groups list",
     "  groups create --name NAME --member ID_OR_NAME [--member ...]",
+    "           [--description TEXT] [--instructions TEXT] [--title TEXT]",
+    "           [--avatar-shape SHAPE] [--avatar-color COLOR]",
+    "  groups update <id-or-name>  (same flags as bots update; members stay on set/add/remove)",
     "  groups get <id-or-name>",
     "  groups members <id-or-name>",
     "  groups add <group> <bot>",
@@ -41,8 +48,11 @@ function usage() {
     "  chat <bot-or-group>     alias for thread",
     "",
     "Max group members: " + MAX_GROUP_MEMBERS,
+    "--description / --instructions is the UI Instructions field (same key).",
+    "Avatar shapes: " + AVATAR_SHAPES.join(" "),
+    "Avatar colors: " + AVATAR_COLORS.join(" "),
     "Flags: --gateway  --files  --dir DIR  --json",
-    "Env: CURSOR_ACCESS_TOKEN or GROK_BOT_GATEWAY_URL + GROK_BOT_GATEWAY_TOKEN",
+    "Auth: GROK_BOT_GATEWAY_URL + GROK_BOT_GATEWAY_TOKEN, or the Grok Bot app session, or CURSOR_ACCESS_TOKEN",
     "File fallback: GROK_BOT_AGENTS_DIR",
   ].join("\n");
 }
@@ -56,6 +66,27 @@ function takeFlag(args, name) {
   return value;
 }
 
+function takeLastFlag(args, ...names) {
+  let value;
+  let seen = false;
+  for (;;) {
+    let hit = false;
+    for (const name of names) {
+      const i = args.indexOf(name);
+      if (i === -1) continue;
+      const next = args[i + 1];
+      if (next == null || next.startsWith("-")) throw new StoreError(name + " needs a value");
+      args.splice(i, 2);
+      value = next;
+      seen = true;
+      hit = true;
+      break;
+    }
+    if (!hit) break;
+  }
+  return seen ? value : undefined;
+}
+
 function takeRepeating(args, name) {
   const out = [];
   for (;;) {
@@ -73,12 +104,55 @@ function hasFlag(args, name) {
   return true;
 }
 
+function parseOnOff(value, flag) {
+  const v = String(value).trim().toLowerCase();
+  if (v === "on" || v === "true" || v === "1" || v === "yes") return true;
+  if (v === "off" || v === "false" || v === "0" || v === "no") return false;
+  throw new StoreError(flag + " must be on|off (or true|false|1|0|yes|no)");
+}
+
+function takeCreateFields(args) {
+  return {
+    name: takeFlag(args, "--name"),
+    description: takeLastFlag(args, "--description", "--instructions") ?? "",
+    title: takeFlag(args, "--title") ?? "",
+    avatarShape: takeFlag(args, "--avatar-shape") ?? "",
+    avatarColor: takeFlag(args, "--avatar-color") ?? "",
+  };
+}
+
+function takeUpdatePatch(args) {
+  const name = takeFlag(args, "--name");
+  const description = takeLastFlag(args, "--description", "--instructions");
+  const title = takeFlag(args, "--title");
+  const avatarShape = takeFlag(args, "--avatar-shape");
+  const avatarColor = takeFlag(args, "--avatar-color");
+  const notifyRaw = takeFlag(args, "--notify");
+  const hiddenRaw = takeFlag(args, "--hidden");
+  const patch = {};
+  if (name !== undefined) patch.name = name;
+  if (description !== undefined) patch.description = description;
+  if (title !== undefined) patch.title = title;
+  if (avatarShape !== undefined) patch.avatarShape = avatarShape;
+  if (avatarColor !== undefined) patch.avatarColor = avatarColor;
+  if (notifyRaw !== undefined) patch.notifyOnAgentUpdates = parseOnOff(notifyRaw, "--notify");
+  if (hiddenRaw !== undefined) patch.hiddenFromSidebar = parseOnOff(hiddenRaw, "--hidden");
+  if (Object.keys(patch).length === 0) {
+    throw new StoreError("update needs at least one of --name --description --instructions --title --avatar-shape --avatar-color --notify --hidden");
+  }
+  return patch;
+}
+
 function summarize(rec) {
   return {
     id: rec.id,
     name: rec.name,
     title: rec.title || undefined,
     description: rec.description || undefined,
+    avatarShape: rec.avatarShape || undefined,
+    avatarColor: rec.avatarColor || undefined,
+    ...(rec.notifyOnAgentUpdates !== undefined ? { notifyOnAgentUpdates: rec.notifyOnAgentUpdates } : {}),
+    ...(rec.hiddenFromSidebar !== undefined ? { hiddenFromSidebar: rec.hiddenFromSidebar } : {}),
     kind: rec.isGroup ? "group" : "bot",
     members: rec.isGroup ? rec.memberIds : undefined,
   };
@@ -98,8 +172,15 @@ function formatRecord(rec, all) {
     : "";
   const title = rec.title ? " - " + rec.title : "";
   const desc = rec.description ? "\n    " + rec.description : "";
+  const avatar = rec.avatarShape || rec.avatarColor
+    ? "\n    avatar: " + [rec.avatarShape, rec.avatarColor].filter(Boolean).join(" ")
+    : "";
+  const settings = [];
+  if (rec.notifyOnAgentUpdates !== undefined) settings.push("notify " + (rec.notifyOnAgentUpdates ? "on" : "off"));
+  if (rec.hiddenFromSidebar !== undefined) settings.push("hidden " + (rec.hiddenFromSidebar ? "on" : "off"));
+  const settingsLine = settings.length ? "\n    " + settings.join(", ") : "";
   const extra = rec.isGroup ? "\n    members (" + rec.memberIds.length + "): " + (members || "(none)") : "";
-  return kind + "  " + rec.name + title + "\n    " + rec.id + desc + extra;
+  return kind + "  " + rec.name + title + "\n    " + rec.id + desc + avatar + settingsLine + extra;
 }
 
 function entryText(e) {
@@ -191,14 +272,20 @@ async function main(argv) {
   }
 
   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 });
+    const fields = takeCreateFields(rest);
+    const rec = await backend.createAgent(fields);
     done(json, rec, "Created bot " + rec.name + " (" + rec.id + ")");
     return;
   }
 
+  if (cmd === "bots" && sub === "update") {
+    const ref = rest.shift();
+    if (!ref || ref.startsWith("-")) throw new StoreError("gbot bots update <id-or-name> [--name NAME] ...");
+    const rec = await backend.updateAgent(ref, takeUpdatePatch(rest));
+    done(json, rec, "Updated " + (rec.isGroup ? "group" : "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>");
@@ -233,14 +320,23 @@ async function main(argv) {
   }
 
   if (cmd === "groups" && sub === "create") {
-    const name = takeFlag(rest, "--name");
-    const description = takeFlag(rest, "--description") ?? "";
+    const fields = takeCreateFields(rest);
     const members = takeRepeating(rest, "--member");
-    const rec = await backend.createGroup({ name, description, memberIds: members });
+    const rec = await backend.createGroup({ ...fields, memberIds: members });
     done(json, rec, "Created group " + rec.name + " (" + rec.id + ") with " + rec.memberIds.length + " members");
     return;
   }
 
+  if (cmd === "groups" && sub === "update") {
+    const ref = rest.shift();
+    if (!ref || ref.startsWith("-")) throw new StoreError("gbot groups update <id-or-name> [--name NAME] ...");
+    const current = await backend.resolve(ref);
+    if (!current.isGroup) throw new StoreError('"' + current.name + '" is a bot, not a group. Use bots update.');
+    const rec = await backend.updateAgent(ref, takeUpdatePatch(rest));
+    done(json, rec, "Updated group " + rec.name + " (" + rec.id + ")");
+    return;
+  }
+
   if (cmd === "groups" && (sub === "get" || sub === "members")) {
     const ref = rest[0];
     if (!ref) throw new StoreError("gbot groups " + sub + " <id-or-name>");

package/src/commands.js

@@ -21,6 +21,7 @@ export async function openBackend(opts) {
       list: () => gw.listAgents(session),
       resolve: (ref) => gw.resolveRef(session, ref),
       createAgent: (input) => gw.createAgent(session, input),
+      updateAgent: (ref, patch) => gw.updateAgent(session, ref, patch),
       deleteAgent: (ref) => gw.deleteAgent(session, ref),
       createGroup: (input) => gw.createGroup(session, input),
       setGroupMembers: (group, members) => gw.setGroupMembers(session, group, members),
@@ -38,6 +39,7 @@ export async function openBackend(opts) {
     list: async () => files.listRecords(root),
     resolve: async (ref) => files.resolveRef(root, ref),
     createAgent: async (input) => files.createAgent(root, input),
+    updateAgent: async (ref, patch) => files.updateAgent(root, ref, patch),
     deleteAgent: async (ref) => files.deleteAgent(root, ref),
     createGroup: async (input) => files.createGroup(root, input),
     setGroupMembers: async (group, members) => files.setGroupMembers(root, group, members),

package/src/gateway.js

@@ -1,4 +1,7 @@
 import { randomUUID } from "node:crypto";
+import { ensureSandboxHeaders, headersFromEnsureSandbox, headersFromEnv, mergeGatewayHeaders, normalizeHeaderMap, requestHeaders } from "./headers.js";
+import { hasGrokBotGatewaySession, loadGrokBotGatewaySession } from "./app-session.js";
+import { AVATAR_COLORS, AVATAR_SHAPES } from "./store.js";
 
 export class GatewayError extends Error {
   constructor(message, { status, method } = {}) {
@@ -42,12 +45,22 @@ function gatewayOverride() {
     ? "http://127.0.0.1:" + (process.env.SAND_HOST_PORT || "1340")
     : "";
   const url = explicitUrl || localUrl;
-  if (url && token) return { gatewayUrl: url.replace(/\/$/, ""), gatewayToken: token };
+  if (url && token) return { gatewayUrl: url.replace(/\/$/, ""), gatewayToken: token, gatewayHeaders: headersFromEnv() };
   return null;
 }
 
+function sessionFromApp() {
+  const loaded = loadGrokBotGatewaySession();
+  if (!loaded) return null;
+  return {
+    gatewayUrl: loaded.gatewayUrl,
+    gatewayToken: loaded.gatewayToken,
+    gatewayHeaders: mergeGatewayHeaders(normalizeHeaderMap(loaded.headers), headersFromEnv()),
+  };
+}
+
 export function hasGatewayAuth() {
-  return Boolean(gatewayOverride() || accessTokenFromEnv());
+  return Boolean(gatewayOverride() || accessTokenFromEnv() || hasGrokBotGatewaySession());
 }
 
 async function readJson(res) {
@@ -72,14 +85,7 @@ 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",
-    },
+    headers: ensureSandboxHeaders(accessToken),
     body: "{}",
   });
   const body = await readJson(res);
@@ -92,12 +98,14 @@ export async function ensureSandbox(accessToken) {
   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) };
+  return { gatewayUrl: String(gatewayUrl).replace(/\/$/, ""), gatewayToken: String(gatewayToken), gatewayHeaders: mergeGatewayHeaders(headersFromEnsureSandbox(body), headersFromEnv()) };
 }
 
 export async function connectGateway() {
   const override = gatewayOverride();
   if (override) return override;
+  const fromApp = sessionFromApp();
+  if (fromApp) return fromApp;
   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.");
@@ -109,10 +117,7 @@ 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,
-    },
+    headers: requestHeaders(session),
     body: JSON.stringify(body),
   });
   const data = await readJson(res);
@@ -127,16 +132,31 @@ function asRecord(agent) {
   if (!agent) return null;
   const id = agent.id || agent.agentId;
   const memberIds = agent.memberIds || agent.memberAgentIds || [];
+  const notify = agent.notifyOnUpdatesEnabled ?? agent.notifyOnAgentUpdates;
+  const hidden = agent.isHiddenFromSidebar ?? agent.hiddenFromSidebar;
   return {
     id,
     name: agent.name || "",
     title: agent.title || "",
     description: agent.description || "",
+    avatarShape: agent.avatarShape || "",
+    avatarColor: agent.avatarColor || "",
+    ...(notify !== undefined ? { notifyOnAgentUpdates: Boolean(notify) } : {}),
+    ...(hidden !== undefined ? { hiddenFromSidebar: Boolean(hidden) } : {}),
     isGroup: agent.isGroup === true || (agent.isGroup == null && Array.isArray(memberIds) && memberIds.length > 0),
     memberIds: Array.isArray(memberIds) ? memberIds : [],
   };
 }
 
+function assertAvatar(kind, value, allowed) {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return "";
+  if (!allowed.includes(trimmed)) {
+    throw new GatewayError("Unknown avatar " + kind + " \"" + value + "\". Use: " + allowed.join(" "));
+  }
+  return trimmed;
+}
+
 function unwrapList(data) {
   if (Array.isArray(data)) return data;
   if (Array.isArray(data.agents)) return data.agents;
@@ -172,13 +192,36 @@ export async function createAgent(session, input) {
     name: input.name,
     description: input.description || "",
     title: input.title || "",
-    avatarShape: input.avatarShape || "",
-    avatarColor: input.avatarColor || "",
+    avatarShape: assertAvatar("shape", input.avatarShape, AVATAR_SHAPES),
+    avatarColor: assertAvatar("color", input.avatarColor, AVATAR_COLORS),
     origin: "user",
   });
   return unwrapOne(data);
 }
 
+export async function updateAgent(session, ref, patch = {}) {
+  const rec = await resolveRef(session, ref);
+  if (patch.name !== undefined && !String(patch.name).trim()) {
+    throw new GatewayError("Name cannot be blank.");
+  }
+  const profile = {
+    name: patch.name !== undefined ? String(patch.name).trim() : rec.name,
+    description: patch.description !== undefined ? String(patch.description) : rec.description,
+  };
+  if (patch.title !== undefined) profile.title = String(patch.title);
+  if (patch.avatarShape !== undefined) profile.avatarShape = assertAvatar("shape", patch.avatarShape, AVATAR_SHAPES);
+  if (patch.avatarColor !== undefined) profile.avatarColor = assertAvatar("color", patch.avatarColor, AVATAR_COLORS);
+  await gatewayCall(session, "updateAgent", { id: rec.id, profile });
+  if (patch.notifyOnAgentUpdates !== undefined) {
+    await gatewayCall(session, "setAgentNotifyOnUpdates", { id: rec.id, isEnabled: Boolean(patch.notifyOnAgentUpdates) });
+  }
+  if (patch.hiddenFromSidebar !== undefined) {
+    await gatewayCall(session, "setAgentHiddenFromSidebar", { id: rec.id, isHidden: Boolean(patch.hiddenFromSidebar) });
+  }
+  const fresh = (await listAgents(session)).find((r) => r.id === rec.id);
+  return fresh || rec;
+}
+
 export async function deleteAgent(session, ref) {
   const rec = await resolveRef(session, ref);
   await gatewayCall(session, "deleteAgent", { id: rec.id });
@@ -193,7 +236,13 @@ export async function createGroup(session, input) {
     description: input.description || "",
     memberAgentIds,
   });
-  return unwrapOne(data);
+  const rec = unwrapOne(data);
+  const extras = {};
+  if (input.title) extras.title = input.title;
+  if (input.avatarShape) extras.avatarShape = input.avatarShape;
+  if (input.avatarColor) extras.avatarColor = input.avatarColor;
+  if (Object.keys(extras).length && rec?.id) return updateAgent(session, rec.id, extras);
+  return rec;
 }
 
 export async function setGroupMembers(session, groupRef, memberRefs) {

package/src/headers.js

@@ -0,0 +1,53 @@
+export function normalizeHeaderMap(obj) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return {};
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value == null || value === "") continue;
+    out[String(key).toLowerCase()] = String(value);
+  }
+  return out;
+}
+
+export function parseGatewayHeaders(raw) {
+  if (raw == null || String(raw).trim() === "") return {};
+  const parsed = JSON.parse(String(raw));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("GROK_BOT_GATEWAY_HEADERS must be a JSON object");
+  }
+  return normalizeHeaderMap(parsed);
+}
+
+export function headersFromEnsureSandbox(body) {
+  if (!body || typeof body !== "object") return {};
+  const mapped = normalizeHeaderMap(body.gatewayHeaders || body.gateway_headers);
+  if (Object.keys(mapped).length) return mapped;
+  const token = body.anyrunNetworkToken || body.anyrun_network_token || body.networkToken;
+  return token ? { "x-anyrun-network-token": String(token) } : {};
+}
+
+export function headersFromEnv() {
+  return parseGatewayHeaders(process.env.GROK_BOT_GATEWAY_HEADERS);
+}
+
+export function mergeGatewayHeaders(sessionHeaders, envHeaders) {
+  return { ...(sessionHeaders || {}), ...(envHeaders || {}) };
+}
+
+export function requestHeaders(session) {
+  return {
+    "content-type": "application/json",
+    authorization: "Bearer " + session.gatewayToken,
+    ...(session.gatewayHeaders || {}),
+  };
+}
+
+export function ensureSandboxHeaders(accessToken) {
+  return {
+    "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",
+  };
+}

package/src/store.js

@@ -17,6 +17,41 @@ export const PROFILE_FILE = "profile.json";
 export const GROUP_FILE = "group.json";
 export const SETTINGS_FILE = "settings.json";
 
+export const AVATAR_SHAPES = [
+  "blob",
+  "pebble",
+  "bean",
+  "egg",
+  "squircle",
+  "tablet",
+  "capsule",
+  "cylinder",
+  "hex",
+  "gem",
+  "crystal",
+  "wedge",
+  "shield",
+  "dome",
+  "arch",
+  "cloud",
+  "teardrop",
+  "leaf",
+];
+
+export const AVATAR_COLORS = [
+  "black",
+  "brown",
+  "red",
+  "orange",
+  "yellow",
+  "green",
+  "cyan",
+  "blue",
+  "violet",
+  "magenta",
+  "gray",
+];
+
 const UUID_RE =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -104,6 +139,25 @@ function readGroup(dir) {
   };
 }
 
+function readRawSettings(dir) {
+  const path = join(dir, SETTINGS_FILE);
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readJson(path);
+    return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  } catch {
+    return {};
+  }
+}
+
+function readSettings(dir) {
+  const raw = readRawSettings(dir);
+  return {
+    notifyOnAgentUpdates: typeof raw.notifyOnAgentUpdates === "boolean" ? raw.notifyOnAgentUpdates : true,
+    hiddenFromSidebar: typeof raw.hiddenFromSidebar === "boolean" ? raw.hiddenFromSidebar : false,
+  };
+}
+
 export function listRecords(root) {
   if (!existsSync(root)) return [];
   const out = [];
@@ -117,6 +171,7 @@ export function listRecords(root) {
       id: entry.name,
       path: dir,
       ...profile,
+      ...readSettings(dir),
       isGroup: group != null,
       memberIds: group?.memberIds ?? [],
     });
@@ -142,13 +197,22 @@ export function resolveRef(root, ref) {
   );
 }
 
+function assertAvatar(kind, value, allowed) {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed) return "";
+  if (!allowed.includes(trimmed)) {
+    throw new StoreError(`Unknown avatar ${kind} "${value}". Use: ${allowed.join(" ")}`);
+  }
+  return trimmed;
+}
+
 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(),
+    avatarShape: assertAvatar("shape", profile.avatarShape, AVATAR_SHAPES),
+    avatarColor: assertAvatar("color", profile.avatarColor, AVATAR_COLORS),
   });
 }
 
@@ -156,6 +220,14 @@ function writeSettings(dir) {
   writeJson(join(dir, SETTINGS_FILE), { notifyOnAgentUpdates: true });
 }
 
+function mergeSettings(dir, patch) {
+  const update = {};
+  if (patch.notifyOnAgentUpdates !== undefined) update.notifyOnAgentUpdates = Boolean(patch.notifyOnAgentUpdates);
+  if (patch.hiddenFromSidebar !== undefined) update.hiddenFromSidebar = Boolean(patch.hiddenFromSidebar);
+  if (Object.keys(update).length === 0) return;
+  writeJson(join(dir, SETTINGS_FILE), { ...readRawSettings(dir), ...update });
+}
+
 function writeGroup(dir, memberIds) {
   writeJson(join(dir, GROUP_FILE), {
     version: GROUP_JSON_VERSION,
@@ -163,9 +235,8 @@ function writeGroup(dir, memberIds) {
   });
 }
 
-function normalizeMemberIds(root, memberRefs, { groupId } = {}) {
+function normalizeMemberIds(root, memberRefs) {
   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();
@@ -174,8 +245,6 @@ function normalizeMemberIds(root, memberRefs, { groupId } = {}) {
     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);
@@ -205,6 +274,31 @@ export function createAgent(root, input) {
   return resolveRef(root, id);
 }
 
+export function updateAgent(root, ref, patch = {}) {
+  const rec = resolveRef(root, ref);
+  if (patch.name !== undefined) {
+    const name = String(patch.name).trim();
+    if (!name) throw new StoreError("Name cannot be blank.");
+  }
+  const hasProfile =
+    patch.name !== undefined ||
+    patch.description !== undefined ||
+    patch.title !== undefined ||
+    patch.avatarShape !== undefined ||
+    patch.avatarColor !== undefined;
+  if (hasProfile) {
+    writeProfile(rec.path, {
+      name: patch.name !== undefined ? String(patch.name) : rec.name,
+      description: patch.description !== undefined ? String(patch.description) : rec.description,
+      title: patch.title !== undefined ? String(patch.title) : rec.title,
+      avatarShape: patch.avatarShape !== undefined ? String(patch.avatarShape) : rec.avatarShape,
+      avatarColor: patch.avatarColor !== undefined ? String(patch.avatarColor) : rec.avatarColor,
+    });
+  }
+  mergeSettings(rec.path, patch);
+  return resolveRef(root, rec.id);
+}
+
 export function deleteAgent(root, ref) {
   const rec = resolveRef(root, ref);
   rmSync(rec.path, { recursive: true, force: true });
@@ -234,6 +328,8 @@ export function createGroup(root, input) {
     name: input.name,
     description: input.description ?? "",
     title: input.title ?? "",
+    avatarShape: input.avatarShape ?? "",
+    avatarColor: input.avatarColor ?? "",
   });
   writeGroup(join(root, group.id), memberIds);
   return resolveRef(root, group.id);
@@ -242,7 +338,7 @@ export function createGroup(root, input) {
 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 });
+  const memberIds = normalizeMemberIds(root, memberRefs);
   if (memberIds.length === 0) {
     throw new StoreError("A group needs at least one existing member agent.");
   }