Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

10.5 KB
Raw Blame
import { spawn as ptySpawn } from 'node-pty';
import { mkdirSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { stripAnsi } from './ansiStrip.js';
import { sleep } from './fileUtils.js';
import { buildCliChildEnv } from './cliChildEnv.js';
import { SUBMIT_KEY } from './tuiHandshake.js';
import { killProcessTree } from './bufferedSpawn.js';

/**
 * Drive an interactive coding-agent TUI (Antigravity `agy`, Grok Build `grok`)
 * in a throwaway PTY, type a slash command, and return the ANSI-stripped screen
 * text so a caller can parse it.
 *
 * Why this exists: some CLIs expose subscription-quota usage ONLY through an
 * interactive slash command (`/usage` for agy, `/usage show` for grok) — their
 * non-interactive `--print` mode treats `/usage` as an LLM prompt (wrong data,
 * and it burns tokens). So the only way to read that panel is to spawn the real
 * TUI over a PTY, send the command, and scrape the rendered screen. This is the
 * headless-TUI-scrape analogue of `claudeCodeUsage.js` (which gets to use the
 * cheaper `echo /usage | claude -p` because Claude Code DOES honor `/usage` in
 * print mode).
 *
 * The scrape runs in a dedicated **sandbox cwd** (a fixed dir under the OS temp
 * dir) — never the user's project — so it can't read or mutate real work. The
 * dir is stable (not per-call) on purpose: agy/grok remember "trusted folder"
 * per path, so a stable sandbox is trusted once (via the primer Enter below)
 * and every later scrape skips straight to the prompt.
 *
 * This drives a slash command that renders synchronously — it does NOT run an
 * LLM turn — so it is 0-token and consumes no quota, matching the
 * "user-triggered usage read" carve-out in the AI Provider Usage Policy.
 *
 * Read-only capture: we read the PTY output buffer from a variable and kill the
 * child; the TUI never writes a response file (that pattern is `tuiPromptRunner`
 * for LLM tasks — not applicable to a slash command).
 */

// Fixed, reused sandbox cwd so the "trust this folder?" gate is answered once.
export const USAGE_SANDBOX_DIR = join(tmpdir(), 'portos-provider-usage-sandbox');

// Wide PTY so quota panels/meters don't wrap and split a value across lines.
const PTY_COLS = 200;
const PTY_ROWS = 50;

// Timing defaults (ms). The TUI needs a moment to sign in and paint its banner
// before it accepts input; after the command we wait for the rendered panel to
// stop changing (output-idle) rather than a fixed sleep, bounded by a hard cap.
const DEFAULT_READY_CAP_MS = 15000;  // cap on waiting for the banner/gate to paint + go idle
const DEFAULT_PRIMER_CAP_MS = 3000;  // cap on waiting for the trust/menu dismissal to repaint
const DEFAULT_IDLE_MS = 2500;        // "screen finished rendering" = no output for this long
const DEFAULT_RENDER_CAP_MS = 12000; // hard cap on waiting for the panel after the command
const DEFAULT_HARD_TIMEOUT_MS = 45000; // absolute backstop for the whole scrape

// Bounded tail for the PTY capture: slice back to CAP once it exceeds HEADROOM
// (slicing on a headroom margin, not every chunk, keeps the common case free of
// repeated reallocations). 512KB holds many repaints of a quota panel.
const RAW_BUFFER_CAP = 512 * 1024;
const RAW_BUFFER_HEADROOM = RAW_BUFFER_CAP * 2;

/**
 * Spawn a TUI, send `slashCommand`, and resolve with the ANSI-stripped screen.
 *
 * @param {object} opts
 * @param {string} opts.command — TUI binary (`agy`, `grok`).
 * @param {string[]} [opts.args] — extra argv (default none).
 * @param {string} opts.slashCommand — e.g. `/usage` or `/usage show`.
 * @param {object} [opts.env] — extra env vars merged over `process.env` (the
 *   matched provider's `envVars`, so a provider that authenticates via env
 *   scrapes with the same config a normal run uses).
 * @param {RegExp} [opts.readyMarker] — when set, the render phase does not
 *   treat output-idle as "done" until this pattern appears in the captured
 *   screen. Guards against a TUI that renders a loading row (which would arm
 *   the plain idle heuristic) before its real panel arrives — completion then
 *   requires the panel itself, not merely "some output then quiet."
 * @param {string} [opts.sandboxDir] — cwd override (default USAGE_SANDBOX_DIR).
 * @param {number} [opts.readyMs] @param {number} [opts.primerCapMs]
 * @param {number} [opts.idleMs] @param {number} [opts.renderCapMs]
 * @param {number} [opts.timeoutMs]
 * @returns {Promise<string>} ANSI-stripped captured output.
 */
export async function scrapeTuiUsage({
  command,
  args = [],
  slashCommand,
  env: extraEnv = {},
  readyMarker = null,
  sandboxDir = USAGE_SANDBOX_DIR,
  readyCapMs = DEFAULT_READY_CAP_MS,
  primerCapMs = DEFAULT_PRIMER_CAP_MS,
  idleMs = DEFAULT_IDLE_MS,
  renderCapMs = DEFAULT_RENDER_CAP_MS,
  timeoutMs = DEFAULT_HARD_TIMEOUT_MS,
  // True when `command` is a credential-bootstrap WRAPPER rather than the
  // harness itself. node-pty's `kill()` signals its direct child's pid alone,
  // so a wrapper that forks would leave the harness rendering into a PTY nobody
  // reads any more — and this scrape's every exit runs through killPty (#7496).
  // forkpty already makes the PTY child a session leader whose descendants share
  // its group, so the group signal is exact.
  processGroup = false,
} = {}) {
  if (!command || typeof command !== 'string') throw new Error('scrapeTuiUsage: command is required');
  if (!slashCommand || typeof slashCommand !== 'string') throw new Error('scrapeTuiUsage: slashCommand is required');

  mkdirSync(sandboxDir, { recursive: true });

  // TERM/COLORTERM go in `extra` so the PTY is always a truecolor xterm
  // regardless of the provider's own env (mirrors tuiPromptRunner.js). The PWD
  // pin keeps the scrape in the throwaway sandbox instead of opening the PortOS
  // checkout as a project. No provider record here — this drives a slash command,
  // not a model, so there is nothing for the OpenCode layer to declare.
  const env = buildCliChildEnv({
    before: extraEnv,
    cwd: sandboxDir,
    extra: { TERM: 'xterm-256color', COLORTERM: 'truecolor' },
  });

  let pty;
  try {
    pty = ptySpawn(command, args, {
      name: 'xterm-256color', cols: PTY_COLS, rows: PTY_ROWS, cwd: sandboxDir, env,
    });
  } catch (err) {
    throw new Error(`Failed to spawn TUI '${command}': ${err.message}`);
  }

  // Keep only a bounded tail of the capture: the quota panel renders near the
  // end and the parsers take the latest value per key, so the tail is what
  // matters. Without this, a runaway/noisy TUI that repaints continuously could
  // grow `raw` to hundreds of MB before the render cap / hard timeout and trip
  // PM2's memory restart just from loading Usage (mirrors tuiPromptRunner's cap).
  let raw = '';
  let lastDataAt = Date.now();
  let exited = false;
  pty.onData((d) => {
    raw += d;
    if (raw.length > RAW_BUFFER_HEADROOM) raw = raw.slice(-RAW_BUFFER_CAP);
    lastDataAt = Date.now();
  });
  pty.onExit(() => { exited = true; });

  // 'SIGHUP' is node-pty's own POSIX default for `kill()`; naming it keeps the
  // signal identical while letting killProcessTree take the group path.
  const killPty = () => { try { if (!exited) killProcessTree(pty, 'SIGHUP', { processGroup }); } catch { /* already gone */ } };

  // Absolute backstop so a wedged TUI can't hang the request forever.
  let hardTimer = null;
  const hardStop = new Promise((resolve) => { hardTimer = setTimeout(resolve, timeoutMs); });
  let timedOut = false;
  hardStop.then(() => { timedOut = true; });

  // Wait until the screen stops changing — no PTY output for `idleMs` — bounded
  // by `capMs`. Each await also races the hard timeout, so a TUI that never goes
  // idle still returns when hardStop resolves. Callers reset `lastDataAt` right
  // after a keystroke so this measures idle relative to that input, not to stale
  // banner output from an earlier phase.
  //
  // `requireOutput` guards the render phase: after submitting the command, a
  // slow sign-in / quota lookup can stay silent for >idleMs, and without this
  // the initial silence would read as "done" and kill the TUI before its panel
  // ever renders. When set, idle can only mean completion once at least one
  // chunk has arrived since the wait began (else we wait out `capMs`, then the
  // hard-timeout backstop). The primer phase leaves it off so an already-trusted
  // sandbox (which emits nothing) returns promptly.
  // `ready` (optional) is a final predicate on the captured screen that must
  // also hold before idle counts as done — used to require the actual quota
  // panel, not just any post-submit output. Only evaluated when idle is already
  // reached, so its stripAnsi cost is paid at most once per idle poll.
  const waitForIdle = async (capMs, { requireOutput = false, ready = null } = {}) => {
    const start = Date.now();
    const deadline = start + capMs;
    while (!exited && !timedOut && Date.now() < deadline) {
      const sawOutput = lastDataAt > start;
      const idle = Date.now() - lastDataAt >= idleMs;
      if ((!requireOutput || sawOutput) && idle && (!ready || ready())) return;
      await Promise.race([sleep(250), hardStop]);
    }
  };

  try {
    // Wait for the TUI's initial paint (banner, sign-in spinner, and the
    // trust/menu gate) to finish and go input-idle before touching the keyboard.
    // A fixed sleep would fire the primer Enter before a slow startup's gate had
    // rendered — the keystroke would be dropped or land mid-animation. Gating on
    // output-idle instead means we press Enter exactly when the gate is up and
    // waiting for input, however long sign-in took.
    await waitForIdle(readyCapMs, { requireOutput: true });

    // Dismiss the first-run gate: agy shows "Do you trust this folder?" (default
    // "Yes, I trust"), grok shows a start menu (default highlighted item). One
    // Enter clears either. On an already-trusted sandbox there is no gate and
    // this is a harmless empty-prompt submit. Wait for the dismissal to repaint.
    if (!exited) { pty.write(SUBMIT_KEY); lastDataAt = Date.now(); }
    await waitForIdle(primerCapMs);

    // Bracketed-paste the command so multi-word input (`/usage show`) lands
    // atomically, then submit and wait for the panel to render.
    if (!exited) {
      pty.write(`\x1b[200~${slashCommand}\x1b[201~`);
      await Promise.race([sleep(400), hardStop]);
      pty.write(SUBMIT_KEY);
      lastDataAt = Date.now();
    }
    await waitForIdle(renderCapMs, {
      requireOutput: true,
      ready: readyMarker ? () => readyMarker.test(stripAnsi(raw)) : null,
    });
  } finally {
    if (hardTimer) clearTimeout(hardTimer);
    killPty();
  }

  return stripAnsi(raw);
}