grokbox 0.0.1

package/src/output.ts

@@ -0,0 +1,58 @@
+import type { CliError, ErrorBody } from "./errors.ts";
+
+export type Writable = {
+  write(chunk: string): void;
+};
+
+export type SuccessEnvelope = {
+  ok: true;
+  data: unknown;
+  meta?: { gateway: { pid: number; startedAt: number } };
+};
+
+export function writeJsonLine(out: Writable, value: unknown): void {
+  out.write(`${JSON.stringify(value)}\n`);
+}
+
+export function writeSuccess(
+  out: Writable,
+  data: unknown,
+  gateway?: { pid: number; startedAt: number },
+): void {
+  const envelope: SuccessEnvelope = { ok: true, data };
+  if (gateway) envelope.meta = { gateway };
+  writeJsonLine(out, envelope);
+}
+
+export function writeFailure(out: Writable, error: CliError | ErrorBody): void {
+  const body = "toErrorBody" in error ? error.toErrorBody() : error;
+  writeJsonLine(out, { ok: false, error: body });
+}
+
+export function formatTable(rows: Array<Record<string, string>>): string {
+  if (rows.length === 0) return "";
+  const first = rows[0];
+  if (!first) return "";
+  const cols = Object.keys(first);
+  const widths = cols.map((col) =>
+    Math.max(col.length, ...rows.map((row) => (row[col] ?? "").length)),
+  );
+  const pad = (value: string, i: number): string => value.padEnd(widths[i] ?? value.length);
+  const header = cols.map(pad).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows.map((row) => cols.map((col, i) => pad(row[col] ?? "", i)).join("  ")).join("\n");
+  return `${header}\n${sep}\n${body}\n`;
+}
+
+export function flattenRows(record: Record<string, unknown>, prefix = ""): Array<Record<string, string>> {
+  const rows: Array<Record<string, string>> = [];
+  for (const [key, value] of Object.entries(record)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      rows.push(...flattenRows(value as Record<string, unknown>, path));
+    } else {
+      rows.push({ field: path, value: value === null || value === undefined ? "" : String(value) });
+    }
+  }
+  return rows;
+}

package/src/program.ts

@@ -0,0 +1,213 @@
+import { Command, CommanderError } from "commander";
+import { runAgentsList, runAgentsSearch, runAgentsShow } from "./commands/agents.ts";
+import { runDoctor } from "./commands/doctor.ts";
+import { runEvents } from "./commands/events.ts";
+import { runHistoryTail, runHistoryThread } from "./commands/history.ts";
+import { runIsRunning } from "./commands/is.ts";
+import { runMemoryList } from "./commands/memory.ts";
+import { runSend } from "./commands/send.ts";
+import type { CliDeps } from "./deps.ts";
+import { CliError, usage } from "./errors.ts";
+import { writeFailure } from "./output.ts";
+import { DEFAULT_TIMEOUT_MS, START_HERE, TOP_LEVEL_COMMANDS } from "./registry.ts";
+import { runSkillsGet, runSkillsList } from "./skills.ts";
+
+function addIoOptions(command: Command): Command {
+  return command
+    .option("--json", "Write JSON")
+    .option("--table", "Human-readable table for declared commands")
+    .option("--timeout-ms <n>", "Finite HTTP timeout in milliseconds", String(DEFAULT_TIMEOUT_MS));
+}
+
+function publicCommanderMessage(error: CommanderError): string {
+  const text = error.message.replace(/^error: /i, "").trim();
+  if (/bearer|authorization|token/i.test(text)) return "Invalid usage.";
+  return text.length > 0 ? text : "Invalid usage.";
+}
+
+function unexpectedMessage(error: unknown): string {
+  if (error instanceof Error) {
+    if (/bearer|authorization|token/i.test(error.message)) return "Unexpected CLI failure.";
+    return error.message;
+  }
+  return "Unexpected CLI failure.";
+}
+
+export function createProgram(deps: CliDeps): Command {
+  const program = new Command();
+  program
+    .name("grok-bot")
+    .description("Agent-first CLI for the box-local Grok Bot Gateway.")
+    .version(deps.cliVersion, "--version")
+    .enablePositionalOptions()
+    .helpCommand(false)
+    .showSuggestionAfterError(false)
+    .showHelpAfterError(false)
+    .exitOverride()
+    .addHelpText("before", `${START_HERE}\n`);
+
+  addIoOptions(program);
+
+  program.configureOutput({
+    writeOut: (chunk) => {
+      deps.stdout.write(chunk);
+    },
+    writeErr: () => {
+      // Usage failures are emitted as JSON by runCli.
+    },
+  });
+
+  program.action(() => {
+    throw usage("Missing command. Try grok-bot --help or grok-bot skills get core --full.");
+  });
+
+  const skills = program.command("skills").description("Bundled skills (version-matched)");
+  addIoOptions(skills.command("list").description("List bundled skills")).action(async (opts) => {
+    await runSkillsList(deps, opts);
+  });
+  addIoOptions(
+    skills
+      .command("get")
+      .argument("<name>", "Skill name")
+      .option("--full", "Include generated command reference")
+      .description("Print a bundled skill"),
+  ).action(async (name: string, opts) => {
+    await runSkillsGet(deps, name, opts);
+  });
+
+  addIoOptions(program.command("doctor").description("Check discovery and host health")).action(
+    async (opts) => {
+      await runDoctor(deps, opts);
+    },
+  );
+
+  const agents = program.command("agents").description("Roster and transcript search");
+  addIoOptions(
+    agents
+      .command("list")
+      .option("--kind <kind>", "all, agent, or group", "all")
+      .option("--include-hidden", "Include sidebar-hidden rows")
+      .description("List compact roster rows"),
+  ).action(async (opts) => {
+    await runAgentsList(deps, opts);
+  });
+  addIoOptions(
+    agents
+      .command("search")
+      .argument("<query>", "Transcript search query")
+      .option("--limit <n>", "Max matches (1..100)")
+      .description("Search transcript messages"),
+  ).action(async (query: string, opts) => {
+    await runAgentsSearch(deps, query, opts);
+  });
+  addIoOptions(
+    agents
+      .command("show")
+      .argument("<id>", "Agent or group id")
+      .option("--history <n>", "Tail sample size (0..100)")
+      .description("Show one roster row"),
+  ).action(async (id: string, opts) => {
+    await runAgentsShow(deps, id, opts);
+  });
+
+  addIoOptions(
+    program
+      .command("send")
+      .option("--agent <id>", "Ordinary agent id")
+      .option("--group <id>", "Product group id")
+      .option("--text <text>", "Prompt text")
+      .option("--nonce <uuid>", "Stable client nonce (UUID v4)")
+      .description("Send a Human message via sendPrompt"),
+  ).action(async (opts) => {
+    await runSend(deps, opts);
+  });
+
+  const history = program.command("history").description("Read display transcript");
+  addIoOptions(
+    history
+      .command("tail")
+      .argument("<id>", "Agent or group id")
+      .option("--limit <n>", "Entry limit (1..200)")
+      .option("--before-seq <n>", "Page backward from this seq")
+      .description("Read display transcript tail"),
+  ).action(async (id: string, opts) => {
+    await runHistoryTail(deps, id, opts);
+  });
+  addIoOptions(
+    history
+      .command("thread")
+      .argument("<id>", "Agent or group id")
+      .requiredOption("--root <entry-id>", "Thread root entry id")
+      .description("Read one display thread"),
+  ).action(async (id: string, opts) => {
+    await runHistoryThread(deps, id, opts);
+  });
+
+  const memory = program.command("memory").description("Read agent Memory metadata");
+  addIoOptions(
+    memory
+      .command("list")
+      .requiredOption("--agent <id>", "Agent id")
+      .option("--limit <n>", "Local slice (1..1000)")
+      .option("--content", "Include Memory content")
+      .description("List agent-scope Memory metadata"),
+  ).action(async (opts) => {
+    await runMemoryList(deps, opts);
+  });
+
+  addIoOptions(
+    program
+      .command("events")
+      .option("--channels <csv>", "Allowed channel subset")
+      .option("--once", "Exit after the first allowed event")
+      .option("--include-memory-content", "Keep memory event content")
+      .description("Subscribe to Gateway events (NDJSON)"),
+  ).action(async (opts) => {
+    await runEvents(deps, opts);
+  });
+
+  const isCmd = program.command("is").description("Read roster running projection");
+  addIoOptions(
+    isCmd
+      .command("running")
+      .argument("<id>", "Agent or group id")
+      .description("Read roster running projection"),
+  ).action(async (id: string, opts) => {
+    await runIsRunning(deps, id, opts);
+  });
+
+  const names = program.commands.map((command) => command.name());
+  for (const expected of TOP_LEVEL_COMMANDS) {
+    if (!names.includes(expected)) {
+      throw new Error(`command registry missing ${expected}`);
+    }
+  }
+
+  return program;
+}
+
+export async function runCli(argv: string[], deps: CliDeps): Promise<number> {
+  const program = createProgram(deps);
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (
+        error.exitCode === 0 ||
+        error.code === "commander.helpDisplayed" ||
+        error.code === "commander.version"
+      ) {
+        return 0;
+      }
+      writeFailure(deps.stderr, usage(publicCommanderMessage(error)));
+      return 2;
+    }
+    if (error instanceof CliError) {
+      writeFailure(deps.stderr, error);
+      return error.exitCode;
+    }
+    writeFailure(deps.stderr, new CliError("gateway_internal", unexpectedMessage(error)));
+    return 15;
+  }
+}

package/src/redaction.ts

@@ -0,0 +1,130 @@
+import { asBoolean, asNumber, asString, emptyToNull, isRecord, utf8Bytes } from "./util.ts";
+
+export type AgentKind = "agent" | "group";
+
+export function agentKind(row: Record<string, unknown>): AgentKind {
+  return row.isGroup === true ? "group" : "agent";
+}
+
+export type CompactRoster = {
+  id: string;
+  name: string;
+  title: string | null;
+  kind: AgentKind;
+  isHidden: boolean;
+  isRunning: boolean;
+  isRunningTurn: boolean;
+  awaitingUserResponse: boolean;
+  hasUnread: boolean;
+  updatedAt: number;
+};
+
+export function compactRosterRow(row: Record<string, unknown>): CompactRoster {
+  return {
+    id: asString(row.id),
+    name: asString(row.name),
+    title: emptyToNull(row.title),
+    kind: agentKind(row),
+    isHidden: asBoolean(row.isHiddenFromSidebar),
+    isRunning: asBoolean(row.isRunning),
+    isRunningTurn: asBoolean(row.isRunningTurn),
+    awaitingUserResponse: asBoolean(row.awaitingUserResponse),
+    hasUnread: asBoolean(row.hasUnread),
+    updatedAt: asNumber(row.updatedAt),
+  };
+}
+
+export function detailRosterRow(row: Record<string, unknown>): CompactRoster & {
+  description: string;
+  memberIds: string[];
+} {
+  return {
+    ...compactRosterRow(row),
+    description: asString(row.description),
+    memberIds: Array.isArray(row.memberIds)
+      ? row.memberIds.filter((id): id is string => typeof id === "string")
+      : [],
+  };
+}
+
+export function runningProjection(row: Record<string, unknown>, observedAtMs: number) {
+  return {
+    id: asString(row.id),
+    kind: agentKind(row),
+    isRunning: asBoolean(row.isRunning),
+    isRunningTurn: asBoolean(row.isRunningTurn),
+    awaitingUserResponse: asBoolean(row.awaitingUserResponse),
+    isComposingMessage: asBoolean(row.isComposingMessage),
+    isRetrying: asBoolean(row.isRetrying),
+    observedAtMs,
+  };
+}
+
+export function projectSearchHit(row: unknown): {
+  agentId: string;
+  entryId: string;
+  role: string;
+  timestampMs: number;
+  snippet: string;
+} {
+  const rec = isRecord(row) ? row : {};
+  return {
+    agentId: asString(rec.agentId),
+    entryId: asString(rec.entryId),
+    role: asString(rec.role),
+    timestampMs: asNumber(rec.timestampMs),
+    snippet: asString(rec.snippet),
+  };
+}
+
+export function projectMemory(
+  row: unknown,
+  includeContent: boolean,
+): Record<string, unknown> {
+  const rec = isRecord(row) ? row : {};
+  const content = asString(rec.content);
+  const projected: Record<string, unknown> = {
+    id: asString(rec.id),
+    kind: asString(rec.kind, "log"),
+    createdAt: asNumber(rec.createdAt),
+    contentBytes:
+      typeof rec.contentBytes === "number" && Number.isFinite(rec.contentBytes)
+        ? rec.contentBytes
+        : utf8Bytes(content),
+  };
+  if (includeContent) projected.content = content;
+  return projected;
+}
+
+function stripRosterSecrets(row: unknown): unknown {
+  if (!isRecord(row)) return row;
+  const next = { ...row };
+  delete next.path;
+  delete next.avatarDataUrl;
+  delete next.lastMessagePreview;
+  return next;
+}
+
+export function redactEventPayload(
+  channel: string,
+  payload: unknown,
+  includeMemoryContent: boolean,
+): unknown {
+  if (!isRecord(payload)) return payload;
+  if (channel === "agents") {
+    const agents = Array.isArray(payload.agents) ? payload.agents.map(stripRosterSecrets) : payload.agents;
+    return { ...payload, agents };
+  }
+  if (channel === "agent-upserted") {
+    return { ...payload, agent: stripRosterSecrets(payload.agent) };
+  }
+  if (channel === "memory") {
+    const memories = Array.isArray(payload.memories) ? payload.memories : [];
+    if (includeMemoryContent) return payload;
+    return {
+      agentId: payload.agentId,
+      count: memories.length,
+    };
+  }
+  return payload;
+}

package/src/registry.ts

@@ -0,0 +1,202 @@
+export const CLI_NAME = "grok-bot";
+export const DEFAULT_DISCOVERY_PATH = "/home/box/sand-data/gateway.json";
+export const DEFAULT_TIMEOUT_MS = 10_000;
+export const PROMPT_MAX_BYTES = 64 * 1024;
+export const MEMORY_UPSTREAM_CAP = 1000;
+export const DEFAULT_EVENT_CHANNELS = ["agents", "agent-upserted", "transcript"] as const;
+export const ALLOWED_EVENT_CHANNELS = [
+  "agents",
+  "agent-upserted",
+  "transcript",
+  "memory",
+  "subagents",
+  "async-tasks",
+] as const;
+
+export const TOP_LEVEL_COMMANDS = [
+  "skills",
+  "doctor",
+  "agents",
+  "send",
+  "history",
+  "memory",
+  "events",
+  "is",
+] as const;
+
+export type TopLevelCommand = (typeof TOP_LEVEL_COMMANDS)[number];
+
+export type LeafCommand = {
+  path: readonly string[];
+  usage: string;
+  summary: string;
+  table: boolean;
+  stdin: boolean;
+  gateway: boolean;
+};
+
+export const LEAF_COMMANDS: readonly LeafCommand[] = [
+  {
+    path: ["skills", "list"],
+    usage: "grok-bot skills list [--table]",
+    summary: "List bundled skills (version-matched).",
+    table: true,
+    stdin: false,
+    gateway: false,
+  },
+  {
+    path: ["skills", "get"],
+    usage: "grok-bot skills get core [--full] [--json]",
+    summary: "Print the bundled core skill.",
+    table: false,
+    stdin: false,
+    gateway: false,
+  },
+  {
+    path: ["doctor"],
+    usage: "grok-bot doctor [--json|--table]",
+    summary: "Check discovery, loopback mapping, and GET /health.",
+    table: true,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["agents", "list"],
+    usage: "grok-bot agents list [--kind all|agent|group] [--include-hidden] [--table]",
+    summary: "List compact roster rows via listAgents.",
+    table: true,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["agents", "search"],
+    usage: "grok-bot agents search <query> [--limit <1..100>]",
+    summary: "Search transcript messages via searchAgents.",
+    table: false,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["agents", "show"],
+    usage: "grok-bot agents show <id> [--history <0..100>]",
+    summary: "Show one roster row plus tail sample size.",
+    table: false,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["send"],
+    usage: "grok-bot send (--agent <id> | --group <id>) [--text <text> | stdin] [--nonce <uuid>]",
+    summary: "Send a Human message via sendPrompt.",
+    table: false,
+    stdin: true,
+    gateway: true,
+  },
+  {
+    path: ["history", "tail"],
+    usage: "grok-bot history tail <id> [--limit <1..200>] [--before-seq <n>]",
+    summary: "Read display transcript tail via getAgentTranscriptTail.",
+    table: false,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["history", "thread"],
+    usage: "grok-bot history thread <id> --root <entry-id>",
+    summary: "Read one display thread via getAgentThread.",
+    table: false,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["memory", "list"],
+    usage: "grok-bot memory list --agent <id> [--limit <1..1000>] [--content]",
+    summary: "List agent-scope Memory metadata via getAgentMemories.",
+    table: false,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["events"],
+    usage: "grok-bot events [--channels <csv>] [--once] [--include-memory-content]",
+    summary: "Subscribe to a narrow GET /events channel subset (NDJSON).",
+    table: false,
+    stdin: false,
+    gateway: true,
+  },
+  {
+    path: ["is", "running"],
+    usage: "grok-bot is running <id> [--json|--table]",
+    summary: "Read roster isRunning projection via listAgents.",
+    table: true,
+    stdin: false,
+    gateway: true,
+  },
+];
+
+export const START_HERE = `Start here (for Agents):
+  grok-bot skills get core --full`;
+
+export const EXAMPLES = [
+  "grok-bot skills get core --full",
+  "grok-bot doctor",
+  "grok-bot agents list --kind all --table",
+  'grok-bot agents search "deployment status" --limit 10',
+  'grok-bot send --agent <tom-agent-id> --text "hello"',
+  "printf '%s' 'summarize the current blockers' | grok-bot send --group <group-id>",
+  "grok-bot history tail <agent-id> --limit 50",
+  "grok-bot history tail <agent-id> --limit 50 --before-seq <next-before-seq>",
+  "grok-bot history thread <agent-id> --root <entry-id>",
+  "grok-bot memory list --agent <agent-id> --limit 100",
+  "grok-bot events",
+  "grok-bot is running <agent-id>",
+];
+
+export function renderCommandReference(cliVersion: string): string {
+  const lines: string[] = [
+    `# grok-bot command reference`,
+    ``,
+    `CLI version: ${cliVersion}`,
+    ``,
+    `Top-level names: ${TOP_LEVEL_COMMANDS.join(", ")}.`,
+    `There is no raw / api fallback. Unknown names are local usage errors.`,
+    ``,
+    `## Leaf commands`,
+    ``,
+  ];
+  for (const leaf of LEAF_COMMANDS) {
+    lines.push(`### \`${leaf.path.join(" ")}\``);
+    lines.push("");
+    lines.push("```text");
+    lines.push(leaf.usage);
+    lines.push("```");
+    lines.push("");
+    lines.push(leaf.summary);
+    lines.push("");
+    lines.push(`- table: ${leaf.table ? "yes" : "no"}`);
+    lines.push(`- stdin: ${leaf.stdin ? "yes" : "no"}`);
+    lines.push(`- gateway: ${leaf.gateway ? "yes" : "no"}`);
+    lines.push("");
+  }
+  lines.push("## Copy-paste");
+  lines.push("");
+  lines.push("```bash");
+  for (const example of EXAMPLES) lines.push(example);
+  lines.push("```");
+  lines.push("");
+  lines.push("Do not pass `--token`, `--gateway-url`, `--host`, or `--port`.");
+  lines.push("Reuse `--nonce` when retrying the same send.");
+  lines.push("");
+  return lines.join("\n");
+}
+
+export const GATEWAY_METHODS = [
+  "listAgents",
+  "searchAgents",
+  "getAgentTranscriptTail",
+  "getAgentThread",
+  "getAgentMemories",
+  "sendPrompt",
+] as const;
+
+export type GatewayMethod = (typeof GATEWAY_METHODS)[number];

package/src/skills.ts

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+import type { CliDeps } from "./deps.ts";
+import { usage } from "./errors.ts";
+import { formatTable, writeSuccess } from "./output.ts";
+import { ioFromOpts, rejectTable } from "./opts.ts";
+import { renderCommandReference } from "./registry.ts";
+
+export const CORE_SKILL_NAME = "core";
+export const CORE_SKILL_SUMMARY = "Core grok-bot usage guide.";
+
+export async function loadCoreMarkdown(deps: CliDeps, full: boolean): Promise<string> {
+  const overview = await deps.readFile(join(deps.skillsDir, "core.md"));
+  if (!full) return overview.trimEnd() + "\n";
+  return `${overview.trimEnd()}\n\n${renderCommandReference(deps.cliVersion)}`;
+}
+
+export async function runSkillsList(
+  deps: CliDeps,
+  raw: { json?: boolean; table?: boolean; timeoutMs?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  const data = {
+    cliVersion: deps.cliVersion,
+    skills: [{ name: CORE_SKILL_NAME, summary: CORE_SKILL_SUMMARY, fullAvailable: true }],
+  };
+  if (io.table) {
+    deps.stdout.write(
+      formatTable(
+        data.skills.map((skill) => ({
+          name: skill.name,
+          summary: skill.summary,
+          full: skill.fullAvailable ? "yes" : "no",
+        })),
+      ),
+    );
+    return;
+  }
+  writeSuccess(deps.stdout, data);
+}
+
+export async function runSkillsGet(
+  deps: CliDeps,
+  name: string,
+  raw: { full?: boolean; json?: boolean; table?: boolean; timeoutMs?: string },
+): Promise<void> {
+  const io = ioFromOpts(raw);
+  rejectTable(io.table, false);
+  if (name !== CORE_SKILL_NAME) throw usage(`Unknown skill '${name}'. v1 only bundles core.`);
+  const content = await loadCoreMarkdown(deps, Boolean(raw.full));
+  if (io.json) {
+    writeSuccess(deps.stdout, { name: CORE_SKILL_NAME, cliVersion: deps.cliVersion, content });
+    return;
+  }
+  deps.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+}