grokbox 0.0.1

package/src/deps.ts

@@ -0,0 +1,49 @@
+import { join } from "node:path";
+import cliPackage from "../package.json" with { type: "json" };
+import { DEFAULT_DISCOVERY_PATH } from "./registry.ts";
+import type { Writable } from "./output.ts";
+
+export type FetchFn = typeof fetch;
+
+export type CliDeps = {
+  discoveryPath: string;
+  fetch: FetchFn;
+  now: () => number;
+  randomUUID: () => string;
+  readFile: (path: string) => Promise<string>;
+  stdout: Writable;
+  stderr: Writable;
+  stdinIsTTY: boolean;
+  readStdin: () => Promise<string>;
+  skillsDir: string;
+  cliVersion: string;
+  idleWatchdogMs: number;
+  signal?: AbortSignal;
+};
+
+export const CLI_VERSION: string = cliPackage.version;
+
+export function createProductionDeps(): CliDeps {
+  return {
+    discoveryPath: DEFAULT_DISCOVERY_PATH,
+    fetch: globalThis.fetch.bind(globalThis),
+    now: () => Date.now(),
+    randomUUID: () => crypto.randomUUID(),
+    readFile: async (path) => await Bun.file(path).text(),
+    stdout: {
+      write(chunk) {
+        process.stdout.write(chunk);
+      },
+    },
+    stderr: {
+      write(chunk) {
+        process.stderr.write(chunk);
+      },
+    },
+    stdinIsTTY: Boolean(process.stdin.isTTY),
+    readStdin: async () => await Bun.stdin.text(),
+    skillsDir: join(import.meta.dir, "..", "skills"),
+    cliVersion: CLI_VERSION,
+    idleWatchdogMs: 45_000,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,132 @@
+export const EXIT_CODES = {
+  ok: 0,
+  invalid_usage: 2,
+  discovery_unavailable: 3,
+  gateway_unreachable: 4,
+  gateway_bad_request: 10,
+  gateway_unauthorized: 11,
+  gateway_forbidden: 12,
+  gateway_not_found: 13,
+  gateway_conflict: 14,
+  gateway_internal: 15,
+  send_delivery_unknown: 16,
+  target_not_found: 17,
+  target_kind_mismatch: 18,
+} as const;
+
+export type ErrorCode = Exclude<keyof typeof EXIT_CODES, "ok">;
+
+export type ErrorBody = {
+  code: ErrorCode;
+  message: string;
+  httpStatus?: number;
+  failureCode?: string;
+  retryable: boolean;
+  context?: {
+    clientNonce: string;
+    target: { id: string; kind: "agent" | "group" };
+  };
+};
+
+const RETRYABLE: Record<ErrorCode, boolean> = {
+  invalid_usage: false,
+  discovery_unavailable: false,
+  gateway_unreachable: true,
+  gateway_bad_request: false,
+  gateway_unauthorized: false,
+  gateway_forbidden: false,
+  gateway_not_found: false,
+  gateway_conflict: false,
+  gateway_internal: true,
+  send_delivery_unknown: false,
+  target_not_found: false,
+  target_kind_mismatch: false,
+};
+
+export class CliError extends Error {
+  readonly code: ErrorCode;
+  readonly httpStatus?: number;
+  readonly failureCode?: string;
+  readonly retryable: boolean;
+  readonly context?: ErrorBody["context"];
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    extras: {
+      httpStatus?: number;
+      failureCode?: string;
+      retryable?: boolean;
+      context?: ErrorBody["context"];
+    } = {},
+  ) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.httpStatus = extras.httpStatus;
+    this.failureCode = extras.failureCode;
+    this.retryable = extras.retryable ?? RETRYABLE[code];
+    this.context = extras.context;
+  }
+
+  get exitCode(): number {
+    return EXIT_CODES[this.code];
+  }
+
+  toErrorBody(): ErrorBody {
+    const body: ErrorBody = {
+      code: this.code,
+      message: this.message,
+      retryable: this.retryable,
+    };
+    if (this.httpStatus !== undefined) body.httpStatus = this.httpStatus;
+    if (this.failureCode !== undefined) body.failureCode = this.failureCode;
+    if (this.context !== undefined) body.context = this.context;
+    return body;
+  }
+}
+
+export function usage(message: string): CliError {
+  return new CliError("invalid_usage", message);
+}
+
+export function httpStatusToError(
+  status: number,
+  failureCode: string | undefined,
+  fallbackMessage: string,
+): CliError {
+  if (status === 400) {
+    return new CliError("gateway_bad_request", "Gateway rejected the request body.", {
+      httpStatus: 400,
+      failureCode,
+    });
+  }
+  if (status === 401) {
+    return new CliError("gateway_unauthorized", "Gateway rejected the credentials.", {
+      httpStatus: 401,
+      failureCode,
+    });
+  }
+  if (status === 403) {
+    return new CliError("gateway_forbidden", "Gateway forbade the request.", {
+      httpStatus: 403,
+      failureCode,
+    });
+  }
+  if (status === 404) {
+    return new CliError("gateway_not_found", "Gateway method or path was not found.", {
+      httpStatus: 404,
+      failureCode,
+    });
+  }
+  if (status === 409) {
+    return new CliError("gateway_conflict", "Gateway rejected the request.", {
+      httpStatus: 409,
+      failureCode,
+    });
+  }
+  return new CliError("gateway_internal", fallbackMessage, {
+    httpStatus: status,
+    failureCode,
+  });
+}

package/src/gateway.ts

@@ -0,0 +1,421 @@
+import type { CliDeps } from "./deps.ts";
+import { CliError, httpStatusToError } from "./errors.ts";
+import type { GatewayMethod } from "./registry.ts";
+import { isRecord } from "./util.ts";
+
+const WILDCARD_HOSTS = new Set(["0.0.0.0", "::", "[::]", "*"]);
+
+export type Discovery = {
+  scheme: string;
+  bindHost: string;
+  dialHost: string;
+  port: number;
+  pid: number;
+  startedAt: number;
+  token: string;
+  tokenPresent: boolean;
+  baseUrl: string;
+};
+
+export type GatewayMeta = { pid: number; startedAt: number };
+
+type RequestKind = "read" | "write" | "health";
+
+function isWildcardHost(host: string): boolean {
+  return WILDCARD_HOSTS.has(host.trim().toLowerCase());
+}
+
+function isLoopbackHost(host: string): boolean {
+  const h = host.trim().toLowerCase();
+  if (h === "localhost" || h === "127.0.0.1" || h === "::1" || h === "[::1]") return true;
+  if (/^127(?:\.\d{1,3}){3}$/.test(h)) return true;
+  return false;
+}
+
+function formatHostForUrl(host: string): string {
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`;
+  return host;
+}
+
+export function resolveDialHost(bindHost: string): string {
+  const host = bindHost.trim();
+  if (host.length === 0) {
+    throw new CliError("discovery_unavailable", "Discovery host is missing.");
+  }
+  if (isWildcardHost(host)) return "127.0.0.1";
+  if (isLoopbackHost(host)) {
+    if (host.toLowerCase() === "localhost") return "127.0.0.1";
+    return host;
+  }
+  throw new CliError(
+    "discovery_unavailable",
+    "Discovery host is not loopback; grok-bot refuses to dial off-box.",
+  );
+}
+
+export async function readDiscovery(deps: CliDeps): Promise<Discovery> {
+  let raw: string;
+  try {
+    raw = await deps.readFile(deps.discoveryPath);
+  } catch {
+    throw new CliError("discovery_unavailable", "Gateway discovery file is missing or unreadable.");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CliError("discovery_unavailable", "Gateway discovery file is not valid JSON.");
+  }
+  if (!isRecord(parsed)) {
+    throw new CliError("discovery_unavailable", "Gateway discovery file has the wrong shape.");
+  }
+  const scheme = parsed.scheme;
+  const host = parsed.host;
+  const port = parsed.port;
+  const pid = parsed.pid;
+  const startedAt = parsed.startedAt;
+  const token = parsed.token;
+  if (scheme !== "http" && scheme !== "https") {
+    throw new CliError("discovery_unavailable", "Discovery scheme must be http or https.");
+  }
+  if (typeof host !== "string") {
+    throw new CliError("discovery_unavailable", "Discovery host is missing.");
+  }
+  if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new CliError("discovery_unavailable", "Discovery port is invalid.");
+  }
+  if (typeof pid !== "number" || !Number.isFinite(pid)) {
+    throw new CliError("discovery_unavailable", "Discovery pid is invalid.");
+  }
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt)) {
+    throw new CliError("discovery_unavailable", "Discovery startedAt is invalid.");
+  }
+  if (typeof token !== "string") {
+    throw new CliError("discovery_unavailable", "Discovery token is invalid.");
+  }
+  const dialHost = resolveDialHost(host);
+  return {
+    scheme,
+    bindHost: host,
+    dialHost,
+    port,
+    pid,
+    startedAt,
+    token,
+    tokenPresent: token.length > 0,
+    baseUrl: `${scheme}://${formatHostForUrl(dialHost)}:${port}`,
+  };
+}
+
+export function gatewayMeta(discovery: Discovery): GatewayMeta {
+  return { pid: discovery.pid, startedAt: discovery.startedAt };
+}
+
+function parseFailureCode(body: unknown): string | undefined {
+  if (!isRecord(body) || typeof body.failureCode !== "string") return undefined;
+  return body.failureCode;
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+}
+
+type HttpResult = {
+  status: number;
+  body: unknown;
+  text: string;
+  response: Response;
+};
+
+export class GatewayClient {
+  lastDiscovery: Discovery | null = null;
+
+  constructor(private readonly deps: CliDeps) {}
+
+  async load(): Promise<Discovery> {
+    const discovery = await readDiscovery(this.deps);
+    this.lastDiscovery = discovery;
+    return discovery;
+  }
+
+  requireToken(discovery: Discovery): void {
+    if (!discovery.tokenPresent) {
+      throw new CliError("discovery_unavailable", "Discovery token is missing.");
+    }
+  }
+
+  async health(timeoutMs: number): Promise<{ discovery: Discovery; health: Record<string, unknown> }> {
+    const result = await this.request({
+      kind: "health",
+      path: "/health",
+      method: "GET",
+      auth: false,
+      timeoutMs,
+    });
+    if (!isRecord(result.body)) {
+      throw new CliError("gateway_internal", "Gateway /health did not return an object.", {
+        httpStatus: result.status,
+      });
+    }
+    return { discovery: this.lastDiscovery!, health: result.body };
+  }
+
+  async rpc(
+    method: GatewayMethod,
+    body: Record<string, unknown>,
+    options: { timeoutMs: number; write?: boolean; slim?: boolean },
+  ): Promise<{ result: unknown; discovery: Discovery }> {
+    const result = await this.request({
+      kind: options.write ? "write" : "read",
+      path: `/api/${method}`,
+      method: "POST",
+      auth: true,
+      timeoutMs: options.timeoutMs,
+      jsonBody: body,
+      slim: options.slim === true,
+      write: options.write === true,
+    });
+    return { result: result.body, discovery: this.lastDiscovery! };
+  }
+
+  async listAgents(timeoutMs: number): Promise<{ agents: unknown[]; discovery: Discovery }> {
+    const { result, discovery } = await this.rpc("listAgents", {}, { timeoutMs, slim: true });
+    if (!Array.isArray(result)) {
+      throw new CliError("gateway_internal", "Gateway listAgents did not return an array.");
+    }
+    return { agents: result, discovery };
+  }
+
+  async searchAgents(
+    query: string,
+    limit: number,
+    timeoutMs: number,
+  ): Promise<{ matches: unknown[]; discovery: Discovery }> {
+    const { result, discovery } = await this.rpc("searchAgents", { query, limit }, { timeoutMs });
+    if (!Array.isArray(result)) {
+      throw new CliError("gateway_internal", "Gateway searchAgents did not return an array.");
+    }
+    return { matches: result, discovery };
+  }
+
+  async getAgentTranscriptTail(
+    body: { id: string; limit: number; beforeSeq?: number },
+    timeoutMs: number,
+  ): Promise<{ result: unknown; discovery: Discovery }> {
+    const payload: Record<string, unknown> = { id: body.id, limit: body.limit };
+    if (body.beforeSeq !== undefined) payload.beforeSeq = body.beforeSeq;
+    return await this.rpc("getAgentTranscriptTail", payload, { timeoutMs });
+  }
+
+  async getAgentThread(
+    body: { id: string; rootId: string },
+    timeoutMs: number,
+  ): Promise<{ result: unknown; discovery: Discovery }> {
+    return await this.rpc("getAgentThread", { id: body.id, rootId: body.rootId }, { timeoutMs });
+  }
+
+  async getAgentMemories(id: string, timeoutMs: number): Promise<{ result: unknown; discovery: Discovery }> {
+    return await this.rpc("getAgentMemories", { id }, { timeoutMs });
+  }
+
+  async sendPrompt(
+    body: { agentId: string; prompt: string; clientNonce: string },
+    timeoutMs: number,
+  ): Promise<{ result: unknown; discovery: Discovery }> {
+    return await this.rpc(
+      "sendPrompt",
+      { agentId: body.agentId, prompt: body.prompt, clientNonce: body.clientNonce },
+      { timeoutMs, write: true },
+    );
+  }
+
+  async openEventStream(
+    channels: string[],
+    timeoutMs: number,
+  ): Promise<{ response: Response; discovery: Discovery }> {
+    const qs = channels.map((c) => encodeURIComponent(c)).join(",");
+    const result = await this.request({
+      kind: "read",
+      path: `/events?channels=${qs}`,
+      method: "GET",
+      auth: true,
+      timeoutMs,
+      slim: true,
+      accept: "text/event-stream",
+      stream: true,
+    });
+    return { response: result.response, discovery: this.lastDiscovery! };
+  }
+
+  private async request(input: {
+    kind: RequestKind;
+    path: string;
+    method: "GET" | "POST";
+    auth: boolean;
+    timeoutMs: number;
+    jsonBody?: Record<string, unknown>;
+    slim?: boolean;
+    write?: boolean;
+    accept?: string;
+    stream?: boolean;
+  }): Promise<HttpResult> {
+    const serialized = input.jsonBody === undefined ? undefined : JSON.stringify(input.jsonBody);
+    const write = input.write === true;
+    const attempt = async (): Promise<HttpResult> => {
+      const discovery = await this.load();
+      if (input.auth) this.requireToken(discovery);
+      return await this.sendOnce(discovery, input, serialized, write);
+    };
+
+    try {
+      return await this.interpret(await attempt());
+    } catch (error) {
+      if (error instanceof CliError && error.code === "gateway_unauthorized") {
+        return await this.interpret(await attempt());
+      }
+      if (error instanceof CliError && error.code === "gateway_unreachable") {
+        return await this.interpret(await attempt());
+      }
+      throw error;
+    }
+  }
+
+  private async sendOnce(
+    discovery: Discovery,
+    input: {
+      path: string;
+      method: "GET" | "POST";
+      auth: boolean;
+      timeoutMs: number;
+      slim?: boolean;
+      accept?: string;
+      stream?: boolean;
+    },
+    serialized: string | undefined,
+    write: boolean,
+  ): Promise<HttpResult> {
+    const headers = new Headers();
+    if (input.auth) headers.set("Authorization", `Bearer ${discovery.token}`);
+    if (serialized !== undefined) headers.set("Content-Type", "application/json");
+    headers.set("Accept", input.accept ?? "application/json");
+    if (input.slim) headers.set("x-sand-slim-avatars", "1");
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), input.timeoutMs);
+    let response: Response;
+    try {
+      response = await this.deps.fetch(`${discovery.baseUrl}${input.path}`, {
+        method: input.method,
+        headers,
+        body: serialized,
+        signal: ac.signal,
+        redirect: "manual",
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      if (isAbortError(error)) {
+        if (write) {
+          throw new CliError(
+            "send_delivery_unknown",
+            "Send may have reached Gateway before the response was lost.",
+          );
+        }
+        throw new CliError("gateway_unreachable", "Gateway request timed out.");
+      }
+      throw new CliError("gateway_unreachable", "Gateway is unreachable.", {
+        retryable: true,
+      });
+    }
+    if (input.stream) {
+      clearTimeout(timer);
+      if (!response.ok) {
+        const text = await response.text();
+        let parsed: unknown;
+        try {
+          parsed = text.length === 0 ? null : JSON.parse(text);
+        } catch {
+          parsed = null;
+        }
+        throw httpStatusToError(response.status, parseFailureCode(parsed), "Gateway request failed.");
+      }
+      return { status: response.status, body: null, text: "", response };
+    }
+    let text = "";
+    try {
+      text = await response.text();
+    } catch {
+      clearTimeout(timer);
+      if (write) {
+        throw new CliError(
+          "send_delivery_unknown",
+          "Send may have reached Gateway before the response was lost.",
+        );
+      }
+      throw new CliError("gateway_unreachable", "Gateway is unreachable.");
+    } finally {
+      clearTimeout(timer);
+    }
+    let body: unknown = null;
+    if (text.length > 0) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = null;
+      }
+    }
+    return { status: response.status, body, text, response };
+  }
+
+  private interpret(result: HttpResult): HttpResult {
+    if (result.status >= 200 && result.status < 300) return result;
+    throw httpStatusToError(result.status, parseFailureCode(result.body), "Gateway request failed.");
+  }
+}
+
+export async function* parseSse(
+  stream: ReadableStream<Uint8Array>,
+  options: { onChunk?: () => void; signal?: AbortSignal } = {},
+): AsyncGenerator<unknown> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  const abort = () => {
+    void reader.cancel();
+  };
+  options.signal?.addEventListener("abort", abort, { once: true });
+  try {
+    while (true) {
+      if (options.signal?.aborted) return;
+      const { done, value } = await reader.read();
+      if (done) {
+        buf += decoder.decode();
+        if (buf.length > 0 && !buf.endsWith("\n\n")) buf += "\n\n";
+      } else {
+        options.onChunk?.();
+        buf += decoder.decode(value, { stream: true });
+      }
+      buf = buf.replace(/\r\n/g, "\n");
+      let idx = buf.indexOf("\n\n");
+      while (idx >= 0) {
+        const block = buf.slice(0, idx);
+        buf = buf.slice(idx + 2);
+        const data = block
+          .split("\n")
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).replace(/^ /, ""))
+          .join("\n");
+        if (data.length > 0) {
+          try {
+            yield JSON.parse(data) as unknown;
+          } catch {
+            // skip malformed event frames
+          }
+        }
+        idx = buf.indexOf("\n\n");
+      }
+      if (done) break;
+    }
+  } finally {
+    options.signal?.removeEventListener("abort", abort);
+    reader.releaseLock();
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { createProductionDeps } from "./deps.ts";
+import { runCli } from "./program.ts";
+
+const code = await runCli(process.argv.slice(2), createProductionDeps());
+process.exit(code);

package/src/opts.ts

@@ -0,0 +1,52 @@
+import type { CliDeps } from "./deps.ts";
+import { usage } from "./errors.ts";
+import { DEFAULT_TIMEOUT_MS, PROMPT_MAX_BYTES } from "./registry.ts";
+import { parseInteger, stripOneTrailingNewline, utf8Bytes } from "./util.ts";
+
+export type IoOpts = {
+  json: boolean;
+  table: boolean;
+  timeoutMs: number;
+};
+
+export function ioFromOpts(opts: {
+  json?: boolean;
+  table?: boolean;
+  timeoutMs?: string | number;
+}): IoOpts {
+  const json = Boolean(opts.json);
+  const table = Boolean(opts.table);
+  if (json && table) throw usage("--json and --table cannot be used together.");
+  return {
+    json,
+    table,
+    timeoutMs: parseInteger(opts.timeoutMs, {
+      name: "--timeout-ms",
+      min: 1,
+      max: 300_000,
+      defaultValue: DEFAULT_TIMEOUT_MS,
+    }),
+  };
+}
+
+export function rejectTable(table: boolean, allowed: boolean): void {
+  if (table && !allowed) throw usage("This command does not support --table.");
+}
+
+export async function readPrompt(text: string | undefined, deps: CliDeps): Promise<string> {
+  if (text !== undefined && !deps.stdinIsTTY) {
+    throw usage("Provide --text or stdin, not both.");
+  }
+  let prompt: string;
+  if (text !== undefined) {
+    prompt = text;
+  } else if (deps.stdinIsTTY) {
+    throw usage("Provide --text or pipe stdin. Interactive prompts are not supported.");
+  } else {
+    prompt = await deps.readStdin();
+  }
+  prompt = stripOneTrailingNewline(prompt);
+  if (prompt.length === 0) throw usage("Prompt is empty.");
+  if (utf8Bytes(prompt) > PROMPT_MAX_BYTES) throw usage("Prompt exceeds the 64 KiB CLI limit.");
+  return prompt;
+}