@prohost/cli 0.13.3 → 0.15.0

package/dist/codehost/history.js

@@ -0,0 +1,98 @@
+/**
+ * A viewer's local scroll-back (CONTRACTS-R2 R1): the pane's history as text, so the viewer
+ * scrolls it on its own screen instead of driving tmux copy mode over the network (one wheel
+ * step per round trip, and copy mode is the PANE's: one viewer's scroll froze everyone's view).
+ *
+ * - client → server: `{"type":"history","id":<string>,"lines":<int, capped 10000>}`;
+ * - server → that client only: `{"type":"history","id","text","cols","rows"}`, the history and
+ *   visible screen as `tmux capture-pane -p -e -J -S -<lines>` prints them (SGR colours kept,
+ *   wrapped lines joined), or `{"type":"history","id","error":"<code>"}`.
+ *
+ * Answered only to a viewer that said `hello` (an older page never sees one), and bounded: a
+ * frame never exceeds {@link HISTORY_MAX_FRAME_BYTES}; the oldest lines go first.
+ */
+import { windowTarget } from './tmux.js';
+/** Most lines a viewer may ask for. */
+export const HISTORY_MAX_LINES = 10_000;
+/** Lines asked for when a request names none (or an unusable number). */
+export const HISTORY_DEFAULT_LINES = 2_000;
+/**
+ * Largest answer, as sent (JSON): the relay carries it over Redis and the cloud pipe's upstream
+ * socket takes at most 1 MiB, so this stays well under both.
+ */
+export const HISTORY_MAX_FRAME_BYTES = 768 * 1024;
+/** A request id: what the viewer matches its answer by. */
+export const HISTORY_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** `lines` as asked, within 1..{@link HISTORY_MAX_LINES}. */
+export function clampHistoryLines(raw) {
+    const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.trunc(raw) : Number.NaN;
+    if (!Number.isFinite(n) || n < 1)
+        return HISTORY_DEFAULT_LINES;
+    return Math.min(n, HISTORY_MAX_LINES);
+}
+/** A `history` request frame's fields, or `null` when it can't be answered (no usable id). */
+export function parseHistoryRequest(frame) {
+    if (frame.type !== 'history' || typeof frame.id !== 'string' || !HISTORY_ID_PATTERN.test(frame.id))
+        return null;
+    return { type: 'history', id: frame.id, lines: clampHistoryLines(frame.lines) };
+}
+/**
+ * `-p` print, `-e` keep the SGR escapes (colours, bold), `-J` join wrapped lines (the viewer
+ * wraps them at its own width), `-S -<lines>` from that far back in the history to the screen's end.
+ */
+export function captureHistoryArgs(name, lines) {
+    return ['capture-pane', '-p', '-e', '-J', '-S', `-${clampHistoryLines(lines)}`, '-t', windowTarget(name)];
+}
+/** The pane's size, and whether a program (vim, less) holds its alternate screen: `<cols> <rows> <0|1>`. */
+export function paneGeometryArgs(name) {
+    return ['display-message', '-p', '-t', windowTarget(name), '#{pane_width} #{pane_height} #{alternate_on}'];
+}
+export function parsePaneGeometry(stdout) {
+    const match = /^(\d+) (\d+) ([01])$/.exec(stdout.trim());
+    if (!match)
+        return null;
+    const cols = Number(match[1]);
+    const rows = Number(match[2]);
+    if (cols < 1 || rows < 1)
+        return null;
+    return { cols, rows, alternate: match[3] === '1' };
+}
+const frameBytes = (frame) => Buffer.byteLength(JSON.stringify(frame), 'utf8');
+/**
+ * The answer to request `id`, at most `maxBytes` as JSON: whole lines are dropped from the top
+ * (the oldest) until it fits. tmux ends its capture with a newline, which is not a line.
+ */
+export function historyFrame(id, result, maxBytes = HISTORY_MAX_FRAME_BYTES) {
+    if (!result.ok)
+        return { type: 'history', id, error: result.error };
+    let lines = result.text.replace(/\r/g, '').replace(/\n$/, '').split('\n');
+    const build = () => ({ type: 'history', id, text: lines.join('\n'), cols: result.cols, rows: result.rows });
+    let frame = build();
+    let size = frameBytes(frame);
+    while (size > maxBytes && lines.length > 1) {
+        // Proportionally, with a margin, so a big history takes a few passes rather than thousands.
+        const keep = Math.max(1, Math.min(lines.length - 1, Math.floor((lines.length * maxBytes) / size) - 1));
+        lines = lines.slice(lines.length - keep);
+        frame = build();
+        size = frameBytes(frame);
+    }
+    if (size > maxBytes)
+        return { type: 'history', id, error: 'capture_failed' };
+    return frame;
+}
+/**
+ * Read `lines` of window `name`'s history. A pane in the alternate screen (a full-screen program)
+ * has no scroll-back to show: the viewer falls back to sending it the wheel.
+ */
+export async function readHistory(tmux, name, lines) {
+    const geometryRead = await tmux(paneGeometryArgs(name));
+    const geometry = geometryRead.ok ? parsePaneGeometry(geometryRead.stdout ?? '') : null;
+    if (!geometry)
+        return { ok: false, error: 'capture_failed' };
+    if (geometry.alternate)
+        return { ok: false, error: 'alternate_screen' };
+    const capture = await tmux(captureHistoryArgs(name, lines));
+    if (!capture.ok)
+        return { ok: false, error: 'capture_failed' };
+    return { ok: true, text: capture.stdout ?? '', cols: geometry.cols, rows: geometry.rows };
+}

package/dist/codehost/hooks.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Claude Code hooks and Codex `notify` for Mac-hosted Code threads.
+ *
+ * **Nothing global is installed.** The operator's `~/.claude/settings.json`
+ * and `~/.codex/config.toml` are never edited. Each thread's agent is launched
+ * with the hooks on its own command line — `claude --settings <file>`, `codex -c
+ * notify=[...]` — so they exist only in the sessions this host starts, and the
+ * one command they run is a shim that exits at once unless
+ * `$PROHOST_TERMINAL_ID` is set. A `claude` the operator starts in their own
+ * terminal sees none of it.
+ *
+ * The shim (`$PROHOST_HOME/code-host/bin/prohost-hook`) is rewritten on every
+ * daemon start to name the CLI that is installed now, so a session started
+ * under an older CLI (npx caches move) keeps working after an upgrade.
+ *
+ * What each hook reports (contract "Hook / host ingest"):
+ *
+ * | Hook | Event |
+ * | --- | --- |
+ * | `UserPromptSubmit` | `prompt {text}` |
+ * | `Stop` | `stop {finalText, question}` then `stats {...}` |
+ * | `PermissionRequest --wait <s>` | `permission_request {approvalId, command, options, capabilities: ['hook_decision'], waitMs, deadlineMs, sentAtMs}`, then waits for the decision and prints it (`decision.ts`); `prompt_local` if its wait runs out |
+ * | `PermissionRequest` (a window launched before `--wait`) | `permission_request`, then at once `prompt_local {reason: 'launched_before_update'}`: its Claude Code would kill a waiting hook at 10 s |
+ * | `Notification` (`permission_prompt`) | for a Claude Code without `PermissionRequest`: `permission_request`, then `prompt_local {reason: 'no_hook'}` |
+ * | `SessionStart` | nothing posted; like every hook, it marks the window past the trust dialog (`ready.ts`) |
+ * | Codex `agent-turn-complete` | `prompt` (when it carries one) then `stop` |
+ *
+ * `question` is always true for an interactive turn: when an interactive agent
+ * stops, its turn is over and nothing more happens until a person types — that
+ * is a hand-off by construction, not a reading of what it said.
+ *
+ * Ordinary hooks print nothing (a `UserPromptSubmit` hook's stdout becomes part of the
+ * prompt), except a waiting `PermissionRequest` hook's decision from ProhostAI,
+ * which never blocks the menu (Claude Code draws it while the hook runs, and
+ * applies whichever answers first). The verified modern profile also records
+ * PreToolUse IDs; recording failures block the tool rather than returning success. Claude Code and
+ * Codex credentials are never read; the only Claude file read is the session's
+ * own transcript, for the turn's final text and token counts, and for whether a
+ * held prompt's call is over (`decision.ts`).
+ */
+import type { CodeThreadEvent } from './events.js';
+import type { HostDecision } from './decision.js';
+export declare const TERMINAL_ID_ENV = "PROHOST_TERMINAL_ID";
+export declare const CODE_THREAD_ID_ENV = "PROHOST_CODE_THREAD_ID";
+/** Claude Code hook events this host registers. */
+export declare const CLAUDE_HOOK_EVENTS: readonly ["SessionStart", "UserPromptSubmit", "Stop", "PermissionRequest", "Notification"];
+export type ClaudeHookEvent = (typeof CLAUDE_HOOK_EVENTS)[number];
+export declare const APPROVAL_OPTIONS: readonly ["allow", "allow_session", "deny"];
+/**
+ * Declared on a `permission_request` whose decision the hook itself returns
+ * (`decision.ts`): the server may relay a decision the moment it has the
+ * prompt, since it can only ever answer that prompt.
+ */
+export declare const HOOK_DECISION_CAPABILITY = "hook_decision";
+/** Waits between `permission_request` attempts whose outcome is unknown, within the hook's wait. */
+export declare const POST_RETRY_DELAYS_MS: number[];
+/** Waits between `approval_overridden_locally` attempts, all within {@link OVERRIDE_BUDGET_MS}. */
+export declare const OVERRIDE_RETRY_DELAYS_MS: number[];
+/** Every correction attempt ends this soon after the PostToolUse hook started, under its 10 s timeout. */
+export declare const OVERRIDE_BUDGET_MS = 8000;
+/**
+ * How long the `PermissionRequest` hook waits for a decision from ProhostAI.
+ * The menu is up in the terminal all along (Claude Code draws it while the hook
+ * runs), so the person at the Mac is never kept waiting by it: this bounds only
+ * how long a decision from ProhostAI may still answer the prompt.
+ */
+export declare const HOOK_DECISION_WAIT_S = 120;
+/** The hook's own timeout, past which Claude Code kills it: above its wait. */
+export declare const PERMISSION_HOOK_TIMEOUT_S = 150;
+export declare const MAX_PREVIEW_CHARS = 280;
+export declare function hookBinDir(env?: NodeJS.ProcessEnv): string;
+export declare function hookShimPath(env?: NodeJS.ProcessEnv): string;
+export declare function claudeSettingsPath(env?: NodeJS.ProcessEnv): string;
+/** The shim script: env-guarded, then the current CLI's `hook` command. */
+export declare function hookShimScript(nodePath: string, cliEntrypoint: string): string;
+/**
+ * The `--settings` document Claude Code is launched with: hooks only, and, for a window started
+ * without permission prompts (`skipsPermissions`), the owner's acceptance of Claude Code's one-time
+ * bypass-mode warning: `skipDangerousModePermissionPrompt` ("whether the user has accepted the
+ * bypass permissions mode dialog", Claude Code's settings schema; read from `--settings` too). Only
+ * that window's document carries it: every other window launches without bypass mode, as before.
+ */
+export declare function claudeHookSettings(shimPath: string, invocationProtocol?: boolean, skipsPermissions?: boolean): Record<string, unknown>;
+/** Codex `-c notify=[...]` value (TOML array), naming the shim. */
+export declare function codexNotifyOverride(shimPath: string): string;
+/** Write the shim and Claude settings. Called on every daemon start. */
+export declare function installHookFiles(nodePath: string, cliEntrypoint: string, env?: NodeJS.ProcessEnv): {
+    shim: string;
+    claudeSettings: string;
+    claudeInvocationSettings: string;
+    claudeSkipSettings: string;
+    claudeInvocationSkipSettings: string;
+};
+/** Last non-empty line, clipped — the inbox row's preview. */
+export declare function previewOf(text: string): string | undefined;
+export interface TranscriptTurn {
+    finalText?: string;
+    tokensTotal?: number;
+    tokensCachedPct?: number;
+}
+/**
+ * The last assistant turn of a Claude Code transcript (JSONL): its text and
+ * token usage. Unknown shapes yield nothing rather than zeros.
+ */
+export declare function parseTranscriptTail(content: string): TranscriptTurn;
+/** `git diff --shortstat` numbers for a worktree, against where its branch left the default branch. */
+export declare function parseShortstat(text: string): {
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+};
+export type GitRunner = (args: string[], cwd: string) => Promise<string | undefined>;
+/**
+ * What the thread changed in its worktree, against where its branch left the
+ * default branch: commits, uncommitted edits, and new files not yet added
+ * (`git diff` alone never counts an untracked file, so a thread that made one
+ * would read "No changes yet").
+ */
+export declare function diffStats(cwd: string, git?: GitRunner, countLines?: (file: string) => number): Promise<{
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+} | undefined>;
+/** Stable approval id for one permission prompt, so a retried hook doesn't make two. */
+export declare function approvalIdFor(parts: (string | undefined)[]): string;
+/** A one-line description of what a tool wants to do. */
+export declare function permissionCommand(toolName: string | undefined, toolInput: unknown): string;
+export interface HookContext {
+    env: NodeJS.ProcessEnv;
+    now: () => number;
+    git: GitRunner;
+    readTranscript: (file: string) => string | undefined;
+}
+/** Events for one Claude Code hook invocation. Pure apart from the context's readers. */
+export declare function claudeHookEvents(hook: string, input: Record<string, unknown>, ctx: HookContext): Promise<CodeThreadEvent[]>;
+/** Events for one Codex `notify` call; `payload` is the JSON Codex passes as the last argument. */
+export declare function codexNotifyEvents(payload: string, now: number): CodeThreadEvent[];
+/**
+ * One hook can report several events at the moment it fired (`stop` then
+ * `stats`). Ingest drops an event older than the newest it applied for the
+ * thread, so each later event gets a later `at` — a millisecond apart.
+ */
+export declare function strictlyIncreasing(events: CodeThreadEvent[]): CodeThreadEvent[];
+export interface RunHookOptions {
+    env?: NodeJS.ProcessEnv;
+    stdin?: NodeJS.ReadableStream;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    git?: GitRunner;
+    sleep?: (ms: number) => Promise<void>;
+    /** A waiting `PermissionRequest` hook's decision output (default: stdout). */
+    stdout?: (text: string) => void;
+    /** Registers what runs when Claude Code stops a waiting hook (default: the signal handlers). */
+    onStop?: (handler: () => void) => void;
+    claudeVersion?: () => Promise<string | undefined>;
+}
+/** `--wait <seconds>` on the hook's command line, capped below its timeout; 0 without one. */
+export declare function waitArg(args: string[]): number;
+/**
+ * "Allow for this session", as Claude Code offers it for this prompt: its first
+ * suggestion that adds an allow rule, kept to the session. Only that kind: a
+ * suggestion to add a directory or switch mode grants more than the one call
+ * the person decided on. None: the option isn't offered.
+ */
+export declare function sessionRule(suggestions: unknown): Record<string, unknown> | undefined;
+/** The hook's stdout for a decision: what Claude Code applies to the prompt. */
+export declare function decisionOutput(decision: HostDecision, rule: Record<string, unknown> | undefined): string;
+export interface PermissionWait {
+    /** How long to wait for a decision from ProhostAI. */
+    waitMs: number;
+    /**
+     * Why the prompt is the terminal's when the hook doesn't wait (`waitMs` 0), as `prompt_local`
+     * says it: remote control is off, or the window was launched before hooks waited.
+     */
+    localReason: PromptLocalReason;
+    stdout: (text: string) => void;
+    /** Called with a handler for SIGTERM/SIGINT/SIGHUP: Claude Code stopping the hook (Escape, "No"). */
+    onStop: (handler: () => void) => void;
+}
+/** Why a prompt is answered in the terminal, as `prompt_local {reason}` tells the server. */
+export type PromptLocalReason = 'timeout' | 'remote_off' | 'launched_before_update' | 'no_hook';
+/**
+ * `prohost hook claude <Event>` / `prohost hook codex <payload>`. Critical invocation
+ * recording failures are nonzero; ordinary reporting failures stay nonblocking.
+ */
+export declare function runHook(args: string[], options?: RunHookOptions): Promise<number>;