omnirush 0.3.3 → 0.4.1

package/assets/extensions/omnirush/mcp-lib.ts

@@ -0,0 +1,199 @@
+// Pure helpers for the Omnirush MCP bridge: config parsing/validation,
+// tool naming, and JSON-schema -> typebox mapping for pi tool parameters.
+//
+// No SDK import and no I/O here (except loadMcpConfigFile) so node:test
+// covers everything directly. The typebox import resolves through pi's
+// jiti alias at runtime and through a test alias under node:test.
+
+import fs from "node:fs";
+import { Type } from "typebox";
+
+export const MCP_CONFIG_FILE = "mcp.json";
+export const MCP_TOOL_PREFIX = "mcp__";
+
+/** Claude-style server entry: stdio (command/args/env) or HTTP (url). */
+export interface McpServerConfig {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+}
+
+export interface ParsedMcpConfig {
+  /** Valid server configs keyed by server name, in file order. */
+  servers: Record<string, McpServerConfig>;
+  /** Human-readable problems, one per skipped/invalid entry. */
+  errors: string[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateEntry(raw: unknown, name: string): { config?: McpServerConfig; error?: string } {
+  if (!isPlainObject(raw)) return { error: `${name}: entry must be an object` };
+  const command = typeof raw.command === "string" ? raw.command.trim() : "";
+  const url = typeof raw.url === "string" ? raw.url.trim() : "";
+  if (command && url) {
+    return { error: `${name}: has both command and url — pick one transport` };
+  }
+  if (command) {
+    const args = raw.args === undefined ? [] : raw.args;
+    if (!Array.isArray(args) || args.some((a) => typeof a !== "string")) {
+      return { error: `${name}: args must be an array of strings` };
+    }
+    let env: Record<string, string> | undefined;
+    if (raw.env !== undefined) {
+      if (!isPlainObject(raw.env)) return { error: `${name}: env must be an object of strings` };
+      env = {};
+      for (const [key, value] of Object.entries(raw.env)) {
+        if (typeof value !== "string") return { error: `${name}: env.${key} must be a string` };
+        env[key] = value;
+      }
+    }
+    return { config: { command, ...(args.length > 0 ? { args: args as string[] } : {}), ...(env ? { env } : {}) } };
+  }
+  if (url) {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return { error: `${name}: url is not a valid URL` };
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      return { error: `${name}: url must be http(s)` };
+    }
+    return { config: { url } };
+  }
+  return { error: `${name}: needs a command (stdio) or url (HTTP)` };
+}
+
+/** Parse a claude-style {"mcpServers": {...}} payload. Invalid entries are skipped (never fatal). */
+export function parseMcpConfig(raw: unknown): ParsedMcpConfig {
+  const errors: string[] = [];
+  if (!isPlainObject(raw)) {
+    return { servers: {}, errors: raw === undefined || raw === null ? [] : ["config root must be an object"] };
+  }
+  const serversRaw = raw.mcpServers ?? raw.servers;
+  if (serversRaw === undefined) return { servers: {}, errors };
+  if (!isPlainObject(serversRaw)) return { servers: {}, errors: ["mcpServers must be an object"] };
+  const servers: Record<string, McpServerConfig> = {};
+  for (const [name, entry] of Object.entries(serversRaw)) {
+    const { config, error } = validateEntry(entry, name);
+    if (error || !config) {
+      errors.push(error ?? `${name}: invalid entry`);
+      continue;
+    }
+    servers[name] = config;
+  }
+  return { servers, errors };
+}
+
+/**
+ * Read + parse ~/.omnirush/mcp.json (or MCP_CONFIG_FILE in dir). A missing
+ * file is an empty config, not an error; a malformed file yields one error
+ * line and no servers — a broken config must never break the session.
+ */
+export function loadMcpConfigFile(filePath: string): ParsedMcpConfig {
+  let text: string;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return { servers: {}, errors: [] };
+    return { servers: {}, errors: [`cannot read config: ${error?.message ?? error}`] };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error: any) {
+    return { servers: {}, errors: [`config is not valid JSON (${error?.message ?? error})`] };
+  }
+  return parseMcpConfig(raw);
+}
+
+/** Sanitize one name segment for a pi tool name: [A-Za-z0-9_-]+, <= 64 chars. */
+export function sanitizeToolPart(name: string): string {
+  const cleaned = String(name)
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return cleaned || "unknown";
+}
+
+/** The pi tool name for an MCP tool: mcp__<server>__<tool>, capped at 64
+ * chars (the OpenAI function-name limit the gateway enforces upstream). */
+export function mcpToolName(server: string, tool: string): string {
+  const name = `${MCP_TOOL_PREFIX}${sanitizeToolPart(server)}__${sanitizeToolPart(tool)}`;
+  return name.length > 64 ? name.slice(0, 64) : name;
+}
+
+/**
+ * Dedupe registered tool names (two servers can expose the same tool name
+ * after sanitization): the first keeps its name, later ones get -2, -3...
+ */
+export function dedupeToolNames(names: string[]): string[] {
+  const seen = new Map<string, number>();
+  return names.map((name) => {
+    const count = seen.get(name) ?? 0;
+    seen.set(name, count + 1);
+    return count === 0 ? name : `${name}-${count + 1}`;
+  });
+}
+
+// --- JSON schema -> typebox ------------------------------------------------
+
+function schemaObject(schema: any): Record<string, any> {
+  const out: Record<string, any> = {};
+  if (typeof schema?.description === "string" && schema.description) {
+    out.description = schema.description;
+  }
+  if (schema?.default !== undefined) out.default = schema.default;
+  return out;
+}
+
+/** Map one JSON-schema node to a typebox schema (Type.Any fallback). */
+export function jsonSchemaToTypeBox(schema: unknown): any {
+  const s = schema as any;
+  if (!isPlainObject(s)) return Type.Any();
+  const opts = schemaObject(s);
+  switch (s.type) {
+    case "string":
+      return Array.isArray(s.enum) && s.enum.every((e: unknown) => typeof e === "string") && s.enum.length > 0
+        ? Type.Union(s.enum.map((e: string) => Type.Literal(e)), opts)
+        : Type.String(opts);
+    case "number":
+    case "integer":
+      return Type.Number(opts);
+    case "boolean":
+      return Type.Boolean(opts);
+    case "array":
+      return Type.Array(jsonSchemaToTypeBox(s.items), opts);
+    case "object": {
+      const properties: Record<string, any> = {};
+      const required = new Set<string>(
+        Array.isArray(s.required) ? s.required.filter((r: unknown) => typeof r === "string") : [],
+      );
+      for (const [key, prop] of Object.entries(s.properties ?? {})) {
+        const mapped = jsonSchemaToTypeBox(prop);
+        properties[key] = required.has(key) ? mapped : Type.Optional(mapped);
+      }
+      return Type.Object(properties, opts);
+    }
+    case "null":
+      return Type.Null(opts);
+    default:
+      // Untyped or union nodes: accept anything rather than reject valid
+      // MCP calls at validation.
+      return Type.Any(opts);
+  }
+}
+
+/**
+ * pi tool parameters for an MCP tool: always an object (MCP tool calls
+ * take a JSON object `arguments`); a missing input schema yields {}.
+ */
+export function parametersForTool(inputSchema: unknown): any {
+  const mapped = jsonSchemaToTypeBox(inputSchema);
+  if (mapped?.type === "object") return mapped;
+  return Type.Object({}, { description: "this tool takes no structured arguments" });
+}

package/assets/extensions/omnirush/mcp.ts

@@ -0,0 +1,379 @@
+// Omnirush MCP bridge — bring MCP servers' tools into pi sessions.
+//
+// pi has no MCP support, but extensions can register custom tools
+// (pi.registerTool). This extension:
+//   - reads ~/.omnirush/mcp.json (claude-style
+//     {"mcpServers": {"<name>": {command, args, env} | {url}}}),
+//   - on session start, connects every configured server — lazily spawned
+//     here but bounded: each connect has a timeout and per-server error
+//     isolation, so a dead server can never break the session or the
+//     other servers,
+//   - lists each server's tools and registers EACH as a pi tool named
+//     mcp__<server>__<tool> with a JSON-schema-mapped input schema,
+//   - forwards tool calls to the right server and surfaces MCP errors
+//     (transport failures and isError results) as pi tool errors,
+//   - serves /mcp: configured servers, connection state, tool counts,
+//     and reconnect (optionally for one server).
+//
+// The MCP SDK is imported from the committed sibling bundle
+// (mcp-client.bundle.js): pi copies this directory into
+// ~/.pi/agent/extensions/omnirush/ and jiti there resolves only sibling
+// files, never npm packages.
+
+import path from "node:path";
+import { Client, McpError, StdioClientTransport, StreamableHTTPClientTransport } from "./mcp-client.bundle.js";
+import { omniDir } from "./auth";
+import {
+  dedupeToolNames,
+  loadMcpConfigFile,
+  mcpToolName,
+  MCP_CONFIG_FILE,
+  parametersForTool,
+  type McpServerConfig,
+} from "./mcp-lib";
+import { truncateTail } from "@earendil-works/pi-coding-agent";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Bounded lifecycles: a hung server must never wedge the session start
+// (connect) or a turn (tool call). Timeouts land as ordinary errors in
+// the per-server state and as tool errors, respectively. Env overrides
+// exist for tests (MCP_*_TIMEOUT_MS); production defaults are generous.
+function timeoutFromEnv(name: string, fallback: number): number {
+  const value = Number(process.env[name]);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+const CONNECT_TIMEOUT_MS = timeoutFromEnv("MCP_CONNECT_TIMEOUT_MS", 15_000);
+const LIST_TIMEOUT_MS = timeoutFromEnv("MCP_LIST_TIMEOUT_MS", 15_000);
+const CALL_TIMEOUT_MS = timeoutFromEnv("MCP_CALL_TIMEOUT_MS", 120_000);
+// Tool output cap (pi's built-in guidance: ~50KB / 2000 lines).
+const OUTPUT_MAX_BYTES = 50 * 1024;
+// Shutdown budget so quitting is never blocked by a wedged server.
+const SHUTDOWN_BUDGET_MS = 3_000;
+// Stderr lines kept per stdio server for failure diagnostics.
+const STDERR_TAIL_LINES = 5;
+
+type ServerStatus = "connecting" | "connected" | "failed";
+
+/** OMNIRUSH_DEBUG=1 diagnostics (same convention as the sota guard). */
+function debug(line: string): void {
+  if (process.env.OMNIRUSH_DEBUG !== "1") return;
+  try {
+    process.stderr.write(`omnirush mcp: ${line}\n`);
+  } catch {
+    /* stderr may be closed late in shutdown */
+  }
+}
+
+interface McpToolInfo {
+  name: string;
+  description?: string;
+  inputSchema?: unknown;
+}
+
+interface ServerState {
+  name: string;
+  config: McpServerConfig;
+  status: ServerStatus;
+  error?: string;
+  tools: McpToolInfo[];
+  client?: Client;
+  stderrTail: string[];
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms / 1000}s`)), ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/** MCP content blocks -> pi tool-result content (text/image, rest summarized). */
+function mcpContentToPiContent(content: unknown): Array<Record<string, any>> {
+  const blocks = Array.isArray(content) ? content : [];
+  const out: Array<Record<string, any>> = [];
+  for (const block of blocks as Array<any>) {
+    if (block?.type === "text" && typeof block.text === "string") {
+      out.push({ type: "text", text: block.text });
+    } else if (block?.type === "image" && typeof block.data === "string") {
+      out.push({ type: "image", data: block.data, mimeType: String(block.mimeType ?? "image/png") });
+    } else if (block?.type === "audio") {
+      out.push({
+        type: "text",
+        text: `[audio content omitted: ${block.mimeType ?? "unknown"}, ${String(block.data ?? "").length} base64 chars]`,
+      });
+    } else if (block?.type === "resource" && block.resource) {
+      const resource = block.resource;
+      if (typeof resource.text === "string") {
+        out.push({ type: "text", text: resource.text });
+      } else {
+        out.push({
+          type: "text",
+          text: `[binary resource omitted: ${resource.uri ?? resource.name ?? "unknown"}, ${String(resource.blob ?? "").length} base64 chars]`,
+        });
+      }
+    } else if (block && typeof block === "object") {
+      out.push({ type: "text", text: JSON.stringify(block) });
+    }
+  }
+  return out;
+}
+
+function contentText(content: Array<Record<string, any>>): string {
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text)
+    .join("\n");
+}
+
+/** Connect one server (bounded). Throws on failure — caller isolates. */
+async function connectServer(state: ServerState): Promise<void> {
+  const client = new Client({
+    name: "omnirush",
+    version: (process.env.OMNIRUSH_VERSION || "").trim() || "0.0.0",
+  });
+  let transport: any;
+  if (state.config.url) {
+    transport = new StreamableHTTPClientTransport(new URL(state.config.url));
+  } else {
+    transport = new StdioClientTransport({
+      command: state.config.command!,
+      args: state.config.args ?? [],
+      ...(state.config.env ? { env: state.config.env } : {}),
+      stderr: "pipe",
+    });
+  }
+  state.client = client;
+  client.onerror = (error) => {
+    if (state.status === "connected") {
+      state.status = "failed";
+      state.error = error?.message ?? String(error);
+    }
+  };
+  if (transport.stderr) {
+    transport.stderr.on("data", (chunk: Buffer | string) => {
+      const line = String(chunk).trim();
+      if (!line) return;
+      state.stderrTail.push(line);
+      if (state.stderrTail.length > STDERR_TAIL_LINES) state.stderrTail.shift();
+    });
+  }
+  try {
+    await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `${state.name}: connect`);
+    const listed = await client.listTools({}, { timeout: LIST_TIMEOUT_MS });
+    state.tools = (listed.tools ?? []).map((tool: any) => ({
+      name: String(tool.name),
+      ...(typeof tool.description === "string" ? { description: tool.description } : {}),
+      ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+    }));
+    state.status = "connected";
+    state.error = undefined;
+    debug(`${state.name}: connected, ${state.tools.length} tools`);
+  } catch (error) {
+    state.status = "failed";
+    state.error = error?.message ?? String(error);
+    debug(`${state.name}: connect failed — ${state.error}`);
+    // Best-effort teardown so a half-open transport does not linger.
+    try {
+      await client.close();
+    } catch {
+      /* already dead */
+    }
+    state.client = undefined;
+    throw error;
+  }
+}
+
+function describeServer(state: ServerState): string {
+  if (state.config.url) return `${state.name} (${state.config.url})`;
+  const args = (state.config.args ?? []).join(" ");
+  return `${state.name} (${[state.config.command, args].filter(Boolean).join(" ")})`;
+}
+
+export default function (pi: any) {
+  const servers = new Map<string, ServerState>();
+  // Ordered pi tool names per server (mcp__<server>__<tool>).
+  const registeredByServer = new Map<string, string[]>();
+
+  const loadConfig = (): { found: boolean; errors: string[] } => {
+    const parsed = loadMcpConfigFile(path.join(omniDir(), MCP_CONFIG_FILE));
+    servers.clear();
+    for (const [name, config] of Object.entries(parsed.servers)) {
+      servers.set(name, { name, config, status: "connecting", tools: [], stderrTail: [] });
+    }
+    return { found: Object.keys(parsed.servers).length > 0, errors: parsed.errors };
+  };
+
+  const registerServerTools = (state: ServerState): void => {
+    const names = dedupeToolNames(state.tools.map((tool) => mcpToolName(state.name, tool.name)));
+    const registered: string[] = [];
+    state.tools.forEach((tool, index) => {
+      const toolName = names[index];
+      registered.push(toolName);
+      pi.registerTool({
+        name: toolName,
+        label: `${state.name}: ${tool.name}`,
+        description:
+          tool.description ||
+          `MCP tool ${tool.name} from server "${state.name}"`,
+        parameters: parametersForTool(tool.inputSchema),
+        async execute(toolCallId: string, params: any, signal: any, onUpdate: any, ctx: any) {
+          void toolCallId;
+          void onUpdate;
+          const current = servers.get(state.name);
+          const client = current?.client;
+          if (current?.status !== "connected" || !client) {
+            throw new Error(
+              `MCP server "${state.name}" is not connected (${current?.error ?? "not connected"}). Use /mcp reconnect ${state.name}.`,
+            );
+          }
+          if (signal?.aborted) {
+            return { content: [{ type: "text", text: "Cancelled" }], details: {} };
+          }
+          let result: any;
+          try {
+            result = await client.callTool(
+              { name: tool.name, arguments: (params ?? {}) as Record<string, unknown> },
+              undefined,
+              { timeout: CALL_TIMEOUT_MS, signal },
+            );
+          } catch (error: any) {
+            const detail = error instanceof McpError ? error.message : error?.message ?? String(error);
+            throw new Error(`MCP call failed on "${state.name}": ${detail}`);
+          }
+          const content = mcpContentToPiContent(result?.content);
+          // Tools MUST truncate their output (pi's 50KB / 2000-line
+          // guidance); MCP servers don't all honor that, so cap here.
+          for (const block of content) {
+            if (block.type === "text" && typeof block.text === "string") {
+              block.text = truncateTail(block.text, { maxBytes: OUTPUT_MAX_BYTES, maxLines: 2000 }).content;
+            }
+          }
+          const text = contentText(content) || "(empty tool result)";
+          if (result?.isError) {
+            // MCP-level failure: surface as a pi tool error.
+            throw new Error(text);
+          }
+          void ctx;
+          return {
+            content: content.length > 0 ? content : [{ type: "text", text: "(empty tool result)" }],
+            details: { mcpServer: state.name, mcpTool: tool.name },
+          };
+        },
+      });
+    });
+    registeredByServer.set(state.name, registered);
+  };
+
+  const connectAll = async (only?: string): Promise<void> => {
+    const targets = [...servers.values()].filter((state) => !only || state.name === only);
+    await Promise.allSettled(
+      targets.map(async (state) => {
+        state.status = "connecting";
+        state.error = undefined;
+        try {
+          await connectServer(state);
+          registerServerTools(state);
+        } catch {
+          /* connectServer recorded the failure; isolation keeps going */
+        }
+      }),
+    );
+  };
+
+  const closeAll = async (): Promise<void> => {
+    const clients = [...servers.values()].map((state) => state.client).filter(Boolean) as Client[];
+    if (clients.length === 0) return;
+    await Promise.race([
+      Promise.allSettled(clients.map((client) => client.close())),
+      new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, SHUTDOWN_BUDGET_MS);
+        timer.unref?.();
+      }),
+    ]);
+  };
+
+  const formatStatusLines = (): string[] => {
+    const lines: string[] = [];
+    if (servers.size === 0) {
+      lines.push(
+        `no MCP servers configured — add ${path.join(omniDir(), MCP_CONFIG_FILE)}` +
+          " (see docs/mcp.md)",
+      );
+      return lines;
+    }
+    for (const state of servers.values()) {
+      const stateLabel =
+        state.status === "connected"
+          ? `connected, ${state.tools.length} tool${state.tools.length === 1 ? "" : "s"}`
+          : state.status === "connecting"
+            ? "connecting…"
+            : `failed: ${state.error ?? "unknown error"}`;
+      lines.push(`  ${describeServer(state)} — ${stateLabel}`);
+      if (state.status === "failed" && state.stderrTail.length > 0) {
+        lines.push(`    stderr: ${state.stderrTail[state.stderrTail.length - 1]}`);
+      }
+      if (state.status === "connected") {
+        for (const tool of state.tools) {
+          lines.push(`    - ${mcpToolName(state.name, tool.name)}${tool.description ? `: ${tool.description}` : ""}`);
+        }
+      }
+    }
+    return lines;
+  };
+
+  pi.registerCommand("mcp", {
+    description: "Show MCP server state (args: reconnect [server])",
+    getArgumentCompletions: (prefix: string) => {
+      const options = ["reconnect", ...[...servers.keys()].map((name) => `reconnect ${name}`)];
+      const filtered = options.filter((option) => option.startsWith(prefix));
+      return filtered.length > 0
+        ? filtered.map((value) => ({ value, label: value }))
+        : null;
+    },
+    handler: async (args: string, ctx: any) => {
+      const rest = (args ?? "").trim();
+      const reconnectMatch = /^reconnect\b\s*(\S+)?$/.exec(rest);
+      if (reconnectMatch) {
+        const target = reconnectMatch[1];
+        if (target && !servers.has(target)) {
+          ctx?.ui?.notify?.(`mcp: no server named "${target}"`, "error");
+          return;
+        }
+        await closeAll();
+        await connectAll(target);
+      } else if (rest) {
+        ctx?.ui?.notify?.("mcp: usage /mcp [reconnect [server]]", "error");
+        return;
+      }
+      const lines = [`Omnirush MCP (${servers.size} server${servers.size === 1 ? "" : "s"}):`, ...formatStatusLines()];
+      ctx?.ui?.notify?.(lines.join("\n"));
+    },
+  });
+
+  pi.on("session_start", async (_event: any, ctx: any) => {
+    await closeAll();
+    const { errors } = loadConfig();
+    for (const error of errors) {
+      ctx?.ui?.notify?.(`mcp config: ${error}`, "warning");
+    }
+    if (servers.size > 0) {
+      // Isolated + bounded per server; failures surface via /mcp only.
+      await connectAll();
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    await closeAll();
+  });
+}

package/assets/extensions/omnirush/status-lib.ts

@@ -0,0 +1,85 @@
+// Pure formatters for the /status one-screen session summary. No I/O and
+// no imports beyond node builtins, so node:test covers them directly (the
+// command handler in commands.ts gathers the live inputs).
+
+export interface CollectorStatusInput {
+  /** pi session id (empty when unknown). */
+  sessionId: string;
+  /** Ledger record for the session, when the collector has one. */
+  record?: {
+    segment: number;
+    nextSequence: number;
+    sentBytes?: number;
+    lastSeenAt: string;
+  } | null;
+}
+
+/** The collector line: current session, parts uploaded, last upload time. */
+export function formatCollectorLine({ sessionId, record }: CollectorStatusInput): string {
+  if (!sessionId) return "collector: no session yet";
+  const short = sessionId.slice(0, 8);
+  if (!record) {
+    return `collector: session ${short} — no uploads yet`;
+  }
+  const parts = `session ${short} — ${record.nextSequence} part${record.nextSequence === 1 ? "" : "s"} uploaded`;
+  const bytes = typeof record.sentBytes === "number" && record.sentBytes > 0
+    ? ` · ${(record.sentBytes / 1024).toFixed(0)} kB sent`
+    : "";
+  const seen = record.lastSeenAt ? ` · last upload ${record.lastSeenAt}` : "";
+  return `collector: ${parts}${bytes}${seen} (segment ${record.segment})`;
+}
+
+/** Truncate an identity string for one-line display. */
+function clip(value: string, max = 64): string {
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+export interface StatusInput {
+  signedIn: boolean;
+  /** email / device name from /device/me. */
+  identity?: string | null;
+  /** "provider/model" of the active model, when one is selected. */
+  model?: string | null;
+  /** Active thinking level (pi session state). */
+  thinkingLevel?: string | null;
+  /** Reasoning effort the gateway last reported (x-omnirush-effort). */
+  effort?: string | null;
+  /** Human grant summary, e.g. "997.2M of 1.0B tokens remaining". */
+  grant?: string | null;
+  grantDate?: string | null;
+  collector: CollectorStatusInput;
+  /** Manager origin the CLI talks to. */
+  origin: string;
+  /** omnirush CLI version ("unknown" when not provided by the launcher). */
+  version: string;
+}
+
+/**
+ * The one-screen /status block, one fact per line, best-effort per line:
+ * a missing fact degrades its own line, never the whole screen.
+ */
+export function formatStatusLines(input: StatusInput): string[] {
+  const lines: string[] = [];
+  lines.push(
+    input.signedIn
+      ? `signed in: ${clip(input.identity || "device recognized")}`
+      : "signed in: no — run `omnirush login`",
+  );
+
+  const modelParts: string[] = [];
+  if (input.model) modelParts.push(input.model);
+  if (input.thinkingLevel) modelParts.push(`effort ${input.effort || input.thinkingLevel}`);
+  else if (input.effort) modelParts.push(`effort ${input.effort}`);
+  lines.push(modelParts.length > 0 ? `model: ${modelParts.join(" · ")}` : "model: none selected");
+
+  if (input.grant) {
+    lines.push(`grant: ${input.grant}${input.grantDate ? ` — ${input.grantDate}` : ""}`);
+  } else {
+    lines.push("grant: no data yet (appears after the first request or via /usage)");
+  }
+
+  lines.push(formatCollectorLine(input.collector));
+  lines.push(`manager: ${input.origin}`);
+  lines.push(`version: ${input.version}`);
+  return lines;
+}