@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/command.js

@@ -0,0 +1,136 @@
+/**
+ * `prohost agent code-host …` — the machine owner's switches for hosting Code
+ * threads on this Mac. Only someone with a shell on this machine can run it;
+ * nothing the server sends can change them.
+ *
+ *     prohost agent code-host status
+ *     prohost agent code-host enable [--allow-remote-terminal]
+ *     prohost agent code-host remote on|off
+ *     prohost agent code-host disable
+ *     prohost agent code-host folders add <path> | list [--json] | remove <path>
+ *
+ * A running `agent run` reads the switches at start, and the remote switch
+ * again on every attach: `remote off` refuses the next viewer at once; `enable`
+ * and `disable` take effect when the agent restarts.
+ *
+ * `folders` is the list of folders this Mac has opened for Code threads
+ * (`folders.ts`): a thread started from a phone or the web may only run in one
+ * of them, or in a folder inside one. The desktop app adds each folder picked
+ * in its folder picker; a running agent reads the list at every start.
+ */
+import { addFolder, FoldersBusyError, foldersPath, loadFolders, reportFolders, removeFolder } from './folders.js';
+import { loadSettings, saveSettings, settingsPath } from './settings.js';
+function describe(settings) {
+    return [
+        `Code-thread hosting: ${settings.enabled ? 'on' : 'off'}`,
+        `Remote terminal:     ${settings.allowRemoteTerminal ? 'ALLOWED — the machine owner may attach and type from ProhostAI' : 'off'}`,
+        `Settings file:       ${settingsPath()}`,
+    ].join('\n');
+}
+const REMOTE_WARNING = 'A remote terminal lets you (this machine\'s owner, signed in to ProhostAI) type into this ' +
+    "Mac's agent terminals from the web, phone or desktop app — that is running commands on this " +
+    'machine. Nobody else can attach; turn it off with `prohost agent code-host remote off`.';
+export function codeHostCommand(args, flags, out = (line) => process.stdout.write(`${line}\n`), err = (line) => process.stderr.write(`${line}\n`)) {
+    const [action, value] = args;
+    if (action === 'folders')
+        return foldersCommand(args.slice(1), flags, out, err);
+    const current = loadSettings();
+    if (!action || action === 'status') {
+        out(describe(current));
+        return 0;
+    }
+    if (action === 'enable') {
+        const next = {
+            version: 1,
+            enabled: true,
+            allowRemoteTerminal: flags['allow-remote-terminal'] === true || current.allowRemoteTerminal,
+        };
+        saveSettings(next);
+        out(describe(next));
+        if (next.allowRemoteTerminal)
+            out(`\n${REMOTE_WARNING}`);
+        out('\nRestart `prohost agent run` (or the daemon) to start hosting.');
+        return 0;
+    }
+    if (action === 'disable') {
+        saveSettings({ version: 1, enabled: false, allowRemoteTerminal: false });
+        out(describe(loadSettings()));
+        out('\nRunning terminals keep running in tmux; restart the agent to stop hosting.');
+        return 0;
+    }
+    if (action === 'remote') {
+        if (value !== 'on' && value !== 'off') {
+            err('Usage: prohost agent code-host remote on|off');
+            return 1;
+        }
+        if (value === 'on' && !current.enabled) {
+            err('Turn hosting on first: prohost agent code-host enable');
+            return 1;
+        }
+        const next = { ...current, allowRemoteTerminal: value === 'on' };
+        saveSettings(next);
+        out(describe(next));
+        if (next.allowRemoteTerminal)
+            out(`\n${REMOTE_WARNING}`);
+        return 0;
+    }
+    err(`Unknown code-host action: ${action}. Expected status, enable, disable, remote on|off, or folders.`);
+    return 1;
+}
+const FOLDERS_USAGE = 'Usage: prohost agent code-host folders add <path> | list [--json] | remove <path>';
+/** `prohost agent code-host folders …`. Prints paths only; nothing in the list is secret. */
+export function foldersCommand(args, flags, out, err) {
+    const [action, target, extra] = args;
+    if (action === 'add' || action === 'remove') {
+        if (!target || extra !== undefined) {
+            err(FOLDERS_USAGE);
+            return 1;
+        }
+        if (action === 'add') {
+            const added = addFolder(target);
+            if (!added.ok) {
+                err(added.reason);
+                return 1;
+            }
+            out(added.path);
+            return 0;
+        }
+        let removed;
+        try {
+            removed = removeFolder(target);
+        }
+        catch (error) {
+            if (!(error instanceof FoldersBusyError))
+                throw error;
+            err(error.message);
+            return 1;
+        }
+        if (!removed) {
+            err(`${target} is not in this Mac's opened folders.`);
+            return 1;
+        }
+        out(`Removed ${removed}`);
+        return 0;
+    }
+    if (action === undefined || action === 'list') {
+        if (target !== undefined) {
+            err(FOLDERS_USAGE);
+            return 1;
+        }
+        if (flags.json === true) {
+            const git = new Map(reportFolders().map((folder) => [folder.path, folder.git]));
+            const folders = loadFolders().map(({ path, openedAt }) => ({ path, openedAt, git: git.get(path) ?? false, exists: git.has(path) }));
+            out(JSON.stringify({ folders }));
+            return 0;
+        }
+        const folders = loadFolders();
+        if (folders.length === 0)
+            out('No folders opened for Code threads yet.');
+        for (const folder of folders)
+            out(folder.path);
+        out(`\nList file: ${foldersPath()}`);
+        return 0;
+    }
+    err(FOLDERS_USAGE);
+    return 1;
+}

package/dist/codehost/decision.d.ts

@@ -0,0 +1,156 @@
+/**
+ * A decision made in ProhostAI, answered by the agent's own `PermissionRequest`
+ * hook rather than by keys pressed into its pane.
+ *
+ * Claude Code draws its permission menu while that hook is still running, and
+ * applies whichever comes first: the hook's printed decision or an answer in
+ * the terminal (checked against 2.1.314). So the hook waits, bounded, for a
+ * decision for its own prompt, and a decision can never land on another one.
+ *
+ * Two files per prompt, in the private state dir, named by its `approvalId`:
+ *
+ * - `<terminal>.waiter-<id>.json`: the hook waiting on it (`pid`, `deadline`,
+ *   tool fingerprint). Fingerprints are diagnostic only: they do not establish
+ *   invocation identity or application.
+ * - `<terminal>.decision-<id>.json`: **the settlement**, created exactly once
+ *   (a temp file `link`ed into place, which never overwrites) by whoever
+ *   settles the prompt first:
+ *   - `host`: the decision from ProhostAI, which the waiting hook prints;
+ *   - `timeout`: the hook's wait ran out; the menu is answered in the terminal;
+ *   - `local`: turn/user progress retired the prompt;
+ *   - `cancelled`: the hook received a stop signal; not proof the menu closed.
+ *
+ * A host acknowledgement records handoff to a hook, not proof the parent
+ * applied it. PermissionRequest lacks invocation identity. A verified PreToolUse
+ * hook records the candidate IDs first; only their own transcript completions,
+ * a new user prompt or a completed turn release replies. Legacy per-tool
+ * receipts are not trusted.
+ */
+import type { CodeThreadEvent } from './events.js';
+export type HostDecision = 'allow' | 'allow_session' | 'deny';
+export type Settlement = {
+    by: 'host';
+    decision: HostDecision;
+    at: number;
+} | {
+    by: 'timeout' | 'local' | 'cancelled';
+    at: number;
+};
+export interface Waiter {
+    approvalId: string;
+    /** The waiting hook's process. */
+    pid: number;
+    /** Epoch ms past which it no longer waits. */
+    deadline: number;
+    /** {@link toolFingerprint} of the call its prompt is for. */
+    fingerprint: string;
+    /** The transcript and the causal PreToolUse IDs captured before this permission request. */
+    transcript?: string;
+    toolUseIds?: readonly string[];
+    /** Durable original ingest: a daemon can retry after cancellation or a lost response. */
+    permissionRequest?: CodeThreadEvent;
+    /** `beatenDeny` reported this prompt's deny as overridden in the terminal: said once. */
+    overrideReported?: boolean;
+}
+/** What the host did with a decision from ProhostAI. */
+export type DecideOutcome = 
+/** Settled with it: the waiting hook prints it. */
+'delivered'
+/** Already settled with a decision from ProhostAI (a redelivery). */
+ | 'already'
+/** Nothing waits for it: the prompt is (or was) answered in the terminal. */
+ | 'local';
+export declare function waiterPath(terminalId: string, approvalId: string, env?: NodeJS.ProcessEnv): string;
+export declare function settlementPath(terminalId: string, approvalId: string, env?: NodeJS.ProcessEnv): string;
+/** A tool call as `PermissionRequest` saw it. Not an invocation's identity: identical calls share it. */
+export declare function toolFingerprint(toolName: unknown, toolInput: unknown): string;
+/** Lines of a transcript parsed, ever: for tests that a second read parses only what was appended. */
+export declare const transcriptParseCounter: {
+    lines: number;
+};
+/** For tests: forget every transcript read so far. */
+export declare function forgetTranscriptsForTests(): void;
+/** Exact IDs, not content, counts or timestamp proximity, establish transcript completion. */
+export declare function transcriptReleases(transcript: string, ids: readonly string[], now?: number): boolean;
+/** For tests: the transcripts the cache holds now. */
+export declare function cachedTranscriptsForTests(): string[];
+export declare function readSettlement(terminalId: string, approvalId: string, env?: NodeJS.ProcessEnv): Settlement | undefined;
+/**
+ * Settle the prompt with `settlement` unless it is settled already. Created
+ * whole and never overwritten: its contents go to a unique temp file, linked
+ * into place (EEXIST: someone settled it first). Returns the settlement that
+ * stands afterwards, ours or theirs; `undefined` only when the state can't be
+ * written or read, which every caller treats as "not by ProhostAI".
+ */
+export declare function settle(terminalId: string, approvalId: string, settlement: Settlement, env?: NodeJS.ProcessEnv): {
+    settlement: Settlement | undefined;
+    ours: boolean;
+};
+export declare function readWaiter(terminalId: string, approvalId: string, env?: NodeJS.ProcessEnv): Waiter | undefined;
+/**
+ * The hook registers itself as waiting for `waiter.approvalId`, before the
+ * server can hear of the prompt (so a decision that comes back at once finds
+ * it). Prior prompts, including completed ones, retain their fingerprints until
+ * turn progress: a delayed completion must never be mistaken for a new identical call.
+ */
+export declare function registerWaiter(terminalId: string, waiter: Waiter, env?: NodeJS.ProcessEnv, now?: () => number): void;
+/**
+ * Whether a `PermissionRequest` hook in this terminal reported a prompt within `withinMs`: one
+ * waits now, or one was settled that recently. A `permission_prompt` notification then is the
+ * same prompt, already reported.
+ */
+export declare function recentPrompt(terminalId: string, env: NodeJS.ProcessEnv, now: number, withinMs: number, alive?: (pid: number) => boolean): boolean;
+/**
+ * Whether this terminal's agent may have a permission menu up, so a key typed now (a relayed
+ * reply's Enter) could answer it. Every prompt without a confirming lifecycle receipt counts:
+ * - `open`: the menu is the terminal's: the hook's wait ran out (`timeout`), or the hook is gone or
+ *   past its deadline unsettled (Claude Code killed it; its menu stays). Only the person there
+ *   ends it, and turn progress (`markTurnAnswered`) or the transcript says so.
+ * - `deciding`: the hook still runs, waiting for a decision (one may be on its way) or about to
+ *   print one it was handed (`host`; it exits within a poll).
+ * - `unconfirmed`: a host-settled hook exited without a later hook confirming progress. Neither
+ *   its exit nor writing its stdout proves Claude Code consumed/applied the decision.
+ * - `clear`: turn/user progress removed the waiter, or Claude Code's own transcript shows the prompt
+ *   over (`transcriptReleases`). A legacy `local` or `confirmed` receipt with a remaining waiter
+ *   does not establish application.
+ *
+ * Keys a viewer sent (Escape, Ctrl+C) never count: tmux may consume them, and the menu stays.
+ */
+export type MenuState = 'open' | 'unconfirmed' | 'deciding' | 'clear';
+export declare function menuState(terminalId: string, env?: NodeJS.ProcessEnv, now?: number, alive?: (pid: number) => boolean): MenuState;
+/** Completed IDs are reported only once every local permission barrier has cleared. */
+export declare function completedApprovals(terminalId: string, env?: NodeJS.ProcessEnv): string[];
+/** Retain the waiter until the server acknowledges the approval-scoped recovery event. */
+export declare function acknowledgeCompletedApproval(terminalId: string, approvalId: string, env: NodeJS.ProcessEnv): void;
+/** Whether `approvalId` is a prompt a hook waits on (or waited on) here, so the hook answers it. */
+export declare function hookDecides(terminalId: string, approvalId: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The host, for a decision from ProhostAI: settle the prompt with it, only
+ * while its hook still waits (alive, before its deadline, unsettled). Writes
+ * nothing otherwise, and presses no key on any path.
+ */
+export declare function decide(terminalId: string, approvalId: string, decision: HostDecision, env?: NodeJS.ProcessEnv, now?: () => number, alive?: (pid: number) => boolean): DecideOutcome;
+/**
+ * The hook, after registering: wait until its prompt is settled or `deadline`
+ * passes, then settle it `timeout` itself (unless a decision beat it to it).
+ * Returns ProhostAI's decision, or how it was otherwise settled.
+ */
+export declare function awaitSettlement(terminalId: string, approvalId: string, deadline: number, env?: NodeJS.ProcessEnv, now?: () => number, sleep?: (ms: number) => Promise<void>, pollMs?: number): Promise<Settlement | undefined>;
+/** How often a waiting hook looks in the transcript for its call's end. */
+export declare const TRANSCRIPT_RECHECK_MS = 1000;
+/**
+ * A `PostToolUse` for invocation `toolUseId`: that tool ran. If ProhostAI had settled its prompt with a
+ * deny, the terminal's "Yes" came first (Claude Code ignores a decision once the prompt is answered),
+ * and the record must not say "denied" for a command that ran.
+ *
+ * Exact IDs only, as for releases: exactly one held prompt names `toolUseId` among the invocations
+ * that could own it, and it names no other, so no other call (an identical one, or a subagent's) could
+ * be the prompt's own; the call that ran is the prompt's own call (its tool and input, `fingerprint`):
+ * a lone candidate may be a `Task`/`Agent` whose subagent prompted, and that Task finishing says
+ * nothing about the denied command; it was settled with a deny from ProhostAI, not reported yet.
+ * Anything less returns `undefined`: no correction, never a false one. Marks the prompt reported and
+ * returns its approval id. Retires nothing: only turn progress does (`markTurnAnswered`).
+ */
+export declare function beatenDeny(terminalId: string, toolUseId: unknown, toolName: unknown, toolInput: unknown, env?: NodeJS.ProcessEnv): string | undefined;
+/** A new user prompt or completed turn retires its permission waiters. */
+export declare function markTurnAnswered(terminalId: string, env?: NodeJS.ProcessEnv, now?: () => number): void;