grokbox 0.0.1

package/README.md

@@ -0,0 +1,34 @@
+# grokbox
+
+Unofficial local CLI for inspecting and messaging a running Grok Bot host.
+It is not affiliated with or endorsed by Anysphere, Cursor, or xAI.
+
+## Requirements
+
+- Bun 1.3 or newer
+- A reachable Grok Bot host on the same machine or network
+
+## Install
+
+```bash
+bun add --global grokbox
+grok-bot --help
+```
+
+For a one-off run:
+
+```bash
+bunx grokbox --help
+```
+
+## Common commands
+
+```bash
+grok-bot doctor
+grok-bot agents list
+grok-bot send <agent> "status only"
+grok-bot history tail <agent>
+grok-bot skills list
+```
+
+Run `grok-bot --help` or `grok-bot <command> --help` for the complete command reference.

package/bin/grok-bot

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.ts";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "grokbox",
+  "version": "0.0.1",
+  "description": "Unofficial local CLI for inspecting and messaging a running Grok Bot host",
+  "type": "module",
+  "bin": {
+    "grok-bot": "bin/grok-bot"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "src"
+  ],
+  "keywords": [
+    "grok-bot",
+    "cli",
+    "agents",
+    "automation"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "grok-bot": "bun src/index.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  }
+}

package/skills/core.md

@@ -0,0 +1,81 @@
+# grok-bot core
+
+Version-matched usage guide for the box-local Grok Bot CLI. Load this file from the installed
+binary (`grok-bot skills get core --full`) instead of copying command docs into an Agent skill
+stub.
+
+## What this CLI is
+
+`grok-bot` is an agent-first adapter, not a 151-method Gateway wrapper.
+
+```text
+Agent / Skill
+    -> grok-bot
+        -> /home/box/sand-data/gateway.json
+        -> loopback HTTP + Bearer (in-process only)
+        -> Grok Bot host Gateway
+```
+
+It does two jobs: read a narrow state surface, and append one Human message to a 1:1 agent or a
+product group. It does not impersonate peer delivery.
+
+## Start here
+
+```bash
+grok-bot doctor
+grok-bot agents list --kind all --table
+grok-bot send --agent <id> --text "hello"
+grok-bot history tail <id> --limit 50
+```
+
+Get `<id>` from `agents list`. Do not pass a token, URL, host, or port flag. The CLI reads
+discovery itself.
+
+## 80% paths
+
+1. **Discover** — `doctor` proves loopback mapping and `GET /health`. Health does **not** prove
+   the discovery Bearer can call authenticated commands; `checks.authenticatedCommand` stays
+   `not-probed`.
+2. **Pick a target** — `agents list` (roster) or `agents show <id>`. `agents search` searches
+   transcript text, not bot names.
+3. **Speak as Human** — `send --agent` or `send --group`. Both map to one `sendPrompt`. Success
+   means accepted, not completed. There is no `--wait`.
+4. **Watch** — `events` (NDJSON) for incremental roster/transcript; `history tail` to reconcile
+   display entries; `is running <id>` for that row's roster projection. `isRunning=false` does
+   not prove a send finished.
+5. **Memory metadata** — `memory list --agent <id>` strips `content` unless you pass `--content`.
+
+Sensitive or multiline prompts should go on stdin:
+
+```bash
+printf '%s' "$prompt" | grok-bot send --agent <id>
+```
+
+If you retry the same send, reuse `--nonce <uuid>` and the same target/prompt. Do not mint a new
+nonce after `send_delivery_unknown`.
+
+## Safety
+
+- No `--token`, `--gateway-url`, `--host`, `--port`. No `SAND_GATEWAY_TOKEN` env fallback.
+- HTTP has no `Origin` header. Token never belongs on argv, URL, stdout, stderr, or logs.
+- `send` is Human `sendPrompt` only. There is no peer, broadcast, raw, delete, Memory write,
+  approval, secret, or prepare-upgrade command.
+- Default stdout redacts roster `path` / `avatarDataUrl` / `lastMessagePreview` and Memory
+  `content`.
+- `history` and `agents search` return private product text. Do not copy them into ordinary logs.
+- `--table` is only valid on commands that declare it (`skills list`, `doctor`, `agents list`,
+  `is running`). `--content` / `--include-memory-content` cannot combine with `--table`.
+
+## Output
+
+Finite commands write one JSON object plus a trailing newline (except `skills get`, which is
+Markdown unless `--json`). `events` writes NDJSON. On failure, stdout is empty and stderr is one
+JSON error object. `is running` returning false is still exit 0.
+
+## External skill stub
+
+Harness-installed skills should not copy this file. They should only say:
+
+```text
+Run `grok-bot skills get core --full` before first use in this session.
+```

package/src/commands/agents.ts

@@ -0,0 +1,110 @@
+import type { CliDeps } from "../deps.ts";
+import { usage } from "../errors.ts";
+import { GatewayClient, gatewayMeta } from "../gateway.ts";
+import { formatTable, writeSuccess } from "../output.ts";
+import { ioFromOpts } from "../opts.ts";
+import { compactRosterRow, detailRosterRow, projectSearchHit } from "../redaction.ts";
+import { isRecord, parseInteger } from "../util.ts";
+import { findRosterRow } from "./roster.ts";
+
+export async function runAgentsList(
+  deps: CliDeps,
+  raw: {
+    json?: boolean;
+    table?: boolean;
+    timeoutMs?: string;
+    kind?: string;
+    includeHidden?: boolean;
+  },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  const kind = raw.kind ?? "all";
+  if (kind !== "all" && kind !== "agent" && kind !== "group") {
+    throw usage("--kind must be all, agent, or group.");
+  }
+  const client = new GatewayClient(deps);
+  const { agents, discovery } = await client.listAgents(io.timeoutMs);
+  const includeHidden = Boolean(raw.includeHidden);
+  const projected = agents
+    .filter(isRecord)
+    .map(compactRosterRow)
+    .filter((row) => (includeHidden ? true : !row.isHidden))
+    .filter((row) => (kind === "all" ? true : row.kind === kind));
+  const data = { count: projected.length, agents: projected };
+  if (io.table) {
+    deps.stdout.write(
+      formatTable(
+        projected.map((row) => ({
+          id: row.id,
+          name: row.name,
+          kind: row.kind,
+          running: String(row.isRunning),
+          unread: String(row.hasUnread),
+        })),
+      ),
+    );
+    return;
+  }
+  writeSuccess(deps.stdout, data, gatewayMeta(discovery));
+}
+
+export async function runAgentsSearch(
+  deps: CliDeps,
+  query: string,
+  raw: { json?: boolean; table?: boolean; timeoutMs?: string; limit?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  if (io.table) throw usage("This command does not support --table.");
+  if (query.trim().length === 0) throw usage("Search query must not be blank.");
+  const limit = parseInteger(raw.limit, { name: "--limit", min: 1, max: 100, defaultValue: 20 });
+  const client = new GatewayClient(deps);
+  const { matches, discovery } = await client.searchAgents(query, limit, io.timeoutMs);
+  writeSuccess(
+    deps.stdout,
+    { matches: matches.map(projectSearchHit) },
+    gatewayMeta(discovery),
+  );
+}
+
+export async function runAgentsShow(
+  deps: CliDeps,
+  id: string,
+  raw: { json?: boolean; table?: boolean; timeoutMs?: string; history?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  if (io.table) throw usage("This command does not support --table.");
+  const history = parseInteger(raw.history, {
+    name: "--history",
+    min: 0,
+    max: 100,
+    defaultValue: 20,
+  });
+  const client = new GatewayClient(deps);
+  const { agents, discovery } = await client.listAgents(io.timeoutMs);
+  const row = findRosterRow(agents, id);
+  let historyView = {
+    sampledEntries: 0,
+    hasEarlier: false,
+    nextBeforeSeq: null as number | null,
+  };
+  let meta = gatewayMeta(discovery);
+  if (history > 0) {
+    const tail = await client.getAgentTranscriptTail({ id, limit: history }, io.timeoutMs);
+    meta = gatewayMeta(tail.discovery);
+    const payload = isRecord(tail.result) ? tail.result : {};
+    const entries = Array.isArray(payload.entries) ? payload.entries : [];
+    historyView = {
+      sampledEntries: entries.length,
+      hasEarlier: payload.nextBeforeSeq !== undefined && payload.nextBeforeSeq !== null,
+      nextBeforeSeq: typeof payload.nextBeforeSeq === "number" ? payload.nextBeforeSeq : null,
+    };
+  }
+  writeSuccess(
+    deps.stdout,
+    {
+      agent: detailRosterRow(row),
+      history: historyView,
+    },
+    meta,
+  );
+}

package/src/commands/doctor.ts

@@ -0,0 +1,50 @@
+import type { CliDeps } from "../deps.ts";
+import { GatewayClient, gatewayMeta } from "../gateway.ts";
+import { flattenRows, formatTable, writeSuccess } from "../output.ts";
+import { ioFromOpts } from "../opts.ts";
+import { asBoolean, asNumber } from "../util.ts";
+
+export async function runDoctor(
+  deps: CliDeps,
+  raw: { json?: boolean; table?: boolean; timeoutMs?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  const client = new GatewayClient(deps);
+  const discovery = await client.load();
+  const { health } = await client.health(io.timeoutMs);
+  const healthPid = asNumber(health.pid, Number.NaN);
+  const healthStarted = asNumber(health.startedAt, Number.NaN);
+  const healthView: Record<string, unknown> = {
+    ok: asBoolean(health.ok),
+    pid: health.pid ?? null,
+    isBusy: asBoolean(health.isBusy),
+    activeAgentId: health.activeAgentId ?? null,
+    startedAt: health.startedAt ?? null,
+    lastBusyAtMs: health.lastBusyAtMs ?? null,
+  };
+  if ("busyOnlyAwaitingApproval" in health) {
+    healthView.busyOnlyAwaitingApproval = health.busyOnlyAwaitingApproval;
+  }
+  const data = {
+    discovery: {
+      scheme: discovery.scheme,
+      bindHost: discovery.bindHost,
+      dialHost: discovery.dialHost,
+      port: discovery.port,
+      pid: discovery.pid,
+      startedAt: discovery.startedAt,
+      tokenPresent: discovery.tokenPresent,
+    },
+    health: healthView,
+    checks: {
+      loopbackTarget: discovery.dialHost === "127.0.0.1" || discovery.dialHost === "::1" || discovery.dialHost === "[::1]",
+      generationMatches: healthPid === discovery.pid && healthStarted === discovery.startedAt,
+      authenticatedCommand: "not-probed",
+    },
+  };
+  if (io.table) {
+    deps.stdout.write(formatTable(flattenRows(data as unknown as Record<string, unknown>)));
+    return;
+  }
+  writeSuccess(deps.stdout, data, gatewayMeta(discovery));
+}

package/src/commands/events.ts

@@ -0,0 +1,123 @@
+import type { CliDeps } from "../deps.ts";
+import { CliError, usage } from "../errors.ts";
+import { GatewayClient, parseSse } from "../gateway.ts";
+import { writeJsonLine } from "../output.ts";
+import { ioFromOpts } from "../opts.ts";
+import { redactEventPayload } from "../redaction.ts";
+import { ALLOWED_EVENT_CHANNELS, DEFAULT_EVENT_CHANNELS } from "../registry.ts";
+import { asString, isRecord } from "../util.ts";
+
+const ALLOWED = new Set<string>(ALLOWED_EVENT_CHANNELS);
+
+function parseChannels(csv: string | undefined): string[] {
+  if (csv === undefined || csv.trim().length === 0) return [...DEFAULT_EVENT_CHANNELS];
+  const channels = csv
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+  if (channels.length === 0) throw usage("--channels must list at least one channel.");
+  for (const channel of channels) {
+    if (!ALLOWED.has(channel)) {
+      throw usage(`Channel '${channel}' is not in the v1 allowlist.`);
+    }
+  }
+  return channels;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function runEvents(
+  deps: CliDeps,
+  raw: {
+    json?: boolean;
+    table?: boolean;
+    timeoutMs?: string;
+    channels?: string;
+    once?: boolean;
+    includeMemoryContent?: boolean;
+  },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  if (io.table) throw usage("events does not support --table.");
+  const channels = parseChannels(raw.channels);
+  const includeMemoryContent = Boolean(raw.includeMemoryContent);
+  if (includeMemoryContent && !channels.includes("memory")) {
+    throw usage("--include-memory-content requires the memory channel.");
+  }
+  const once = Boolean(raw.once);
+  const client = new GatewayClient(deps);
+  const stop = deps.signal;
+  let emitted = false;
+  let first = true;
+
+  while (!stop?.aborted) {
+    let response: Response;
+    let discoveryPid: number;
+    let discoveryStarted: number;
+    try {
+      const opened = await client.openEventStream(channels, io.timeoutMs);
+      response = opened.response;
+      discoveryPid = opened.discovery.pid;
+      discoveryStarted = opened.discovery.startedAt;
+    } catch (error) {
+      if (stop?.aborted) return;
+      if (first) throw error;
+      deps.stderr.write("grok-bot: event stream reconnect failed; retrying\n");
+      await sleep(1000);
+      continue;
+    }
+    first = false;
+    if (!response.body) {
+      throw new CliError("gateway_unreachable", "Gateway event stream had no body.");
+    }
+
+    let lastChunk = deps.now();
+    const watchdog = setInterval(() => {
+      if (deps.now() - lastChunk > deps.idleWatchdogMs) {
+        void response.body?.cancel();
+      }
+    }, 1000);
+
+    try {
+      for await (const frame of parseSse(response.body, {
+        onChunk: () => {
+          lastChunk = deps.now();
+        },
+        signal: stop,
+      })) {
+        if (stop?.aborted) return;
+        const rec = isRecord(frame) ? frame : {};
+        const channel = asString(rec.channel);
+        if (!channels.includes(channel)) continue;
+        const payload = redactEventPayload(channel, rec.payload, includeMemoryContent);
+        writeJsonLine(deps.stdout, {
+          ok: true,
+          event: { channel, payload },
+          meta: {
+            observedAtMs: deps.now(),
+            gateway: { pid: discoveryPid, startedAt: discoveryStarted },
+          },
+        });
+        emitted = true;
+        if (once) return;
+      }
+    } finally {
+      clearInterval(watchdog);
+    }
+
+    if (stop?.aborted) return;
+    if (once) break;
+    deps.stderr.write("grok-bot: event stream disconnected; rereading discovery\n");
+    try {
+      await client.listAgents(io.timeoutMs);
+    } catch {
+      // reconciliation is best-effort; do not claim the gap was empty
+    }
+  }
+
+  if (once && !emitted) {
+    throw new CliError("gateway_unreachable", "Event stream ended before the first allowed event.");
+  }
+}

package/src/commands/history.ts

@@ -0,0 +1,65 @@
+import type { CliDeps } from "../deps.ts";
+import { usage } from "../errors.ts";
+import { GatewayClient, gatewayMeta } from "../gateway.ts";
+import { writeSuccess } from "../output.ts";
+import { ioFromOpts } from "../opts.ts";
+import { isRecord, parseInteger } from "../util.ts";
+
+export async function runHistoryTail(
+  deps: CliDeps,
+  id: string,
+  raw: {
+    json?: boolean;
+    table?: boolean;
+    timeoutMs?: string;
+    limit?: string;
+    beforeSeq?: string;
+  },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  if (io.table) throw usage("This command does not support --table.");
+  if (id.length === 0) throw usage("id is required.");
+  const limit = parseInteger(raw.limit, { name: "--limit", min: 1, max: 200, defaultValue: 50 });
+  const beforeSeq =
+    raw.beforeSeq === undefined
+      ? undefined
+      : parseInteger(raw.beforeSeq, { name: "--before-seq", min: 0, max: Number.MAX_SAFE_INTEGER });
+  const client = new GatewayClient(deps);
+  const { result, discovery } = await client.getAgentTranscriptTail(
+    beforeSeq === undefined ? { id, limit } : { id, limit, beforeSeq },
+    io.timeoutMs,
+  );
+  const payload = isRecord(result) ? result : {};
+  const data: Record<string, unknown> = {
+    id,
+    entries: Array.isArray(payload.entries) ? payload.entries : [],
+  };
+  if (payload.nextBeforeSeq !== undefined && payload.nextBeforeSeq !== null) {
+    data.nextBeforeSeq = payload.nextBeforeSeq;
+  }
+  writeSuccess(deps.stdout, data, gatewayMeta(discovery));
+}
+
+export async function runHistoryThread(
+  deps: CliDeps,
+  id: string,
+  raw: { json?: boolean; table?: boolean; timeoutMs?: string; root?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  if (io.table) throw usage("This command does not support --table.");
+  if (id.length === 0) throw usage("id is required.");
+  const rootId = raw.root;
+  if (!rootId) throw usage("--root is required.");
+  const client = new GatewayClient(deps);
+  const { result, discovery } = await client.getAgentThread({ id, rootId }, io.timeoutMs);
+  const payload = isRecord(result) ? result : {};
+  writeSuccess(
+    deps.stdout,
+    {
+      id,
+      rootId,
+      entries: Array.isArray(payload.entries) ? payload.entries : [],
+    },
+    gatewayMeta(discovery),
+  );
+}

package/src/commands/is.ts

@@ -0,0 +1,23 @@
+import type { CliDeps } from "../deps.ts";
+import { GatewayClient, gatewayMeta } from "../gateway.ts";
+import { flattenRows, formatTable, writeSuccess } from "../output.ts";
+import { ioFromOpts } from "../opts.ts";
+import { runningProjection } from "../redaction.ts";
+import { findRosterRow } from "./roster.ts";
+
+export async function runIsRunning(
+  deps: CliDeps,
+  id: string,
+  raw: { json?: boolean; table?: boolean; timeoutMs?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  const client = new GatewayClient(deps);
+  const { agents, discovery } = await client.listAgents(io.timeoutMs);
+  const row = findRosterRow(agents, id);
+  const data = runningProjection(row, deps.now());
+  if (io.table) {
+    deps.stdout.write(formatTable(flattenRows(data as unknown as Record<string, unknown>)));
+    return;
+  }
+  writeSuccess(deps.stdout, data, gatewayMeta(discovery));
+}

package/src/commands/memory.ts

@@ -0,0 +1,47 @@
+import type { CliDeps } from "../deps.ts";
+import { usage } from "../errors.ts";
+import { GatewayClient, gatewayMeta } from "../gateway.ts";
+import { writeSuccess } from "../output.ts";
+import { ioFromOpts } from "../opts.ts";
+import { projectMemory } from "../redaction.ts";
+import { MEMORY_UPSTREAM_CAP } from "../registry.ts";
+import { parseInteger } from "../util.ts";
+
+export async function runMemoryList(
+  deps: CliDeps,
+  raw: {
+    json?: boolean;
+    table?: boolean;
+    timeoutMs?: string;
+    agent?: string;
+    limit?: string;
+    content?: boolean;
+  },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  const includeContent = Boolean(raw.content);
+  if (io.table) throw usage("memory list does not support --table.");
+  const agentId = raw.agent;
+  if (!agentId) throw usage("--agent is required.");
+  const limit = parseInteger(raw.limit, {
+    name: "--limit",
+    min: 1,
+    max: MEMORY_UPSTREAM_CAP,
+    defaultValue: 100,
+  });
+  const client = new GatewayClient(deps);
+  const { result, discovery } = await client.getAgentMemories(agentId, io.timeoutMs);
+  const source = Array.isArray(result) ? result : [];
+  const sliced = source.slice(0, limit);
+  writeSuccess(
+    deps.stdout,
+    {
+      agentId,
+      returned: sliced.length,
+      sourceCount: source.length,
+      sourceMayBeTruncated: source.length === MEMORY_UPSTREAM_CAP,
+      memories: sliced.map((row) => projectMemory(row, includeContent)),
+    },
+    gatewayMeta(discovery),
+  );
+}

package/src/commands/roster.ts

@@ -0,0 +1,11 @@
+import { CliError, usage } from "../errors.ts";
+import { isRecord } from "../util.ts";
+
+export function findRosterRow(agents: unknown[], id: string): Record<string, unknown> {
+  if (id.length === 0) throw usage("Agent id is required.");
+  const row = agents.find((item): item is Record<string, unknown> => isRecord(item) && item.id === id);
+  if (!row) {
+    throw new CliError("target_not_found", "No roster row matched that id.");
+  }
+  return row;
+}

package/src/commands/send.ts

@@ -0,0 +1,72 @@
+import type { CliDeps } from "../deps.ts";
+import { CliError, usage } from "../errors.ts";
+import { GatewayClient, gatewayMeta } from "../gateway.ts";
+import { writeSuccess } from "../output.ts";
+import { ioFromOpts, readPrompt } from "../opts.ts";
+import { agentKind } from "../redaction.ts";
+import { assertUuidV4, isRecord } from "../util.ts";
+import { findRosterRow } from "./roster.ts";
+
+export async function runSend(
+  deps: CliDeps,
+  raw: {
+    json?: boolean;
+    table?: boolean;
+    timeoutMs?: string;
+    agent?: string;
+    group?: string;
+    text?: string;
+    nonce?: string;
+  },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  if (io.table) throw usage("This command does not support --table.");
+  const agentId = raw.agent;
+  const groupId = raw.group;
+  if ((agentId === undefined) === (groupId === undefined)) {
+    throw usage("Provide exactly one of --agent or --group.");
+  }
+  const wantedKind = agentId !== undefined ? "agent" : "group";
+  const targetId = (agentId ?? groupId) as string;
+  const prompt = await readPrompt(raw.text, deps);
+  const clientNonce = raw.nonce === undefined ? deps.randomUUID() : assertUuidV4(raw.nonce, "--nonce");
+  const client = new GatewayClient(deps);
+  const { agents } = await client.listAgents(io.timeoutMs);
+  const row = findRosterRow(agents, targetId);
+  const actualKind = agentKind(row);
+  if (actualKind !== wantedKind) {
+    throw new CliError(
+      "target_kind_mismatch",
+      wantedKind === "agent"
+        ? "--agent matched a group id."
+        : "--group matched a non-group agent id.",
+    );
+  }
+  try {
+    const { result, discovery } = await client.sendPrompt(
+      { agentId: String(row.id), prompt, clientNonce },
+      io.timeoutMs,
+    );
+    const accepted = !isRecord(result) || result.accepted !== false;
+    if (!accepted) {
+      throw new CliError("gateway_internal", "Gateway did not accept the send.");
+    }
+    writeSuccess(
+      deps.stdout,
+      {
+        status: "accepted",
+        accepted: true,
+        target: { id: String(row.id), kind: actualKind },
+        clientNonce,
+      },
+      gatewayMeta(discovery),
+    );
+  } catch (error) {
+    if (error instanceof CliError && error.code === "send_delivery_unknown") {
+      throw new CliError("send_delivery_unknown", error.message, {
+        context: { clientNonce, target: { id: String(row.id), kind: actualKind } },
+      });
+    }
+    throw error;
+  }
+}