@prohost/cli 0.12.4 → 0.13.1

package/dist/agent/runtime_status.d.ts

@@ -206,6 +206,12 @@ export interface RuntimeStatusReporterOptions {
     accountKeys?: () => string[] | undefined;
     /** A run is executing — it will bring fresh numbers, so don't probe beside it. */
     isBusy?: () => boolean;
+    /**
+     * What this harness can do that the server needs to know before sending it
+     * work — today only `venue_run_token` (see `venue.ts`). Read for every
+     * frame, so a downgraded harness stops declaring what it no longer does.
+     */
+    capabilities?: () => string[];
     now?: () => number;
     /** Timer seam for tests. Returns a cancel function. */
     schedule?: (fn: () => void, ms: number) => () => void;

package/dist/agent/runtime_status.js

@@ -472,6 +472,10 @@ function asOf(window, nowMs) {
         return window;
     return { ...window, used_percent: 0, resets_at: null };
 }
+/** Left out when there is nothing to declare, so an older server sees the frame it knows. */
+function capabilitiesField(capabilities) {
+    return capabilities && capabilities.length > 0 ? { capabilities } : {};
+}
 function defaultSchedule(fn, ms) {
     const timer = setTimeout(fn, ms);
     timer.unref?.();
@@ -595,6 +599,7 @@ export class RuntimeStatusReporter {
             plan_label: this.state.plan_label ?? null,
             quota_windows: windows,
             observed_at: new Date(nowMs).toISOString(),
+            ...capabilitiesField(this.options.capabilities?.()),
             // Optional additions: an older server ignores keys it doesn't know.
             ...(this.accounts?.current ? { account: this.accounts.current } : {}),
             // Never a list the registry has moved on from — the server would delete

package/dist/agent/venue.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Runs that answer in a connected team's thread — a *venue*.
+ *
+ * Connected Teams let two ProhostAI workspaces talk in each other's team chat,
+ * so this agent can be addressed in a thread that belongs to the OTHER
+ * workspace. That thread's text is someone else's prompt, and the harness's own
+ * credential can write anywhere in this agent's home workspace. So a venue run
+ * is answered by a session that holds none of it:
+ *
+ * * **Its own credential.** The event carries no thread text at all. The
+ *   harness opens the run's *venue session* over its own `/ws/webhooks` socket
+ *   (there is no HTTP route to it) and gets back a token minted for this one
+ *   run together with the thread. The token reads and posts in that one thread and heartbeats,
+ *   streams and completes that one run — nothing else — and the server refuses
+ *   the harness's key for all of it. Every request the run makes carries the
+ *   token. It lives in memory only: never logged, never written to disk.
+ * * **No tools, no configuration.** Claude Code is started from the operator's
+ *   binary and model only, with `--tools ''` (no built-in tools, so nothing can
+ *   read the credentials file or the environment), `--safe-mode` and
+ *   `--setting-sources '' --settings '{}'` (no hooks, plugins, skills,
+ *   `CLAUDE.md`, permissions or settings from `~/.claude` or any project), an
+ *   empty strict MCP config (never the ProhostAI server or the operator's extra
+ *   servers), and `--no-session-persistence` (the connected team's text is not
+ *   written to a transcript). The agent answers from the thread; the harness
+ *   posts the reply.
+ * * **No home environment.** The child gets an allowlisted environment —
+ *   what a shell and the Claude login need, nothing of ProhostAI's — and an
+ *   empty directory of its own, removed afterwards.
+ *
+ * Only Claude Code can be held to that, and only a release that has every one
+ * of those flags, so only such a harness declares
+ * {@link VENUE_RUN_TOKEN_CAPABILITY} — and the server sends venue runs only to
+ * a runtime that declared it. A venue run that reaches any other harness anyway
+ * is refused without being run.
+ */
+import type { ApiOptions } from './api.js';
+import type { AgentRunRequest } from './contract.js';
+/**
+ * What a harness declares in its `runtime_status` frame when it runs venue
+ * sessions as described above. Mirrors `VENUE_RUN_TOKEN_CAPABILITY` in the
+ * server's `shared/agents/runtime_status.py`.
+ */
+export declare const VENUE_RUN_TOKEN_CAPABILITY = "venue_run_token";
+/** The token prefix the server mints. Anything else is not a run token. */
+export declare const VENUE_RUN_TOKEN_PREFIX = "pvr_";
+/** Whether a run answers in a connected team's thread. */
+export declare function isVenueRun(run: AgentRunRequest): boolean;
+/**
+ * The API options a run's requests go out with: its own token for a venue run
+ * whose session is open, the harness's credential for every other.
+ */
+export declare function apiForRun(api: ApiOptions, run: AgentRunRequest): ApiOptions;
+/**
+ * Whether this Claude Code binary has every flag a venue session depends on.
+ *
+ * Asked of `--help` rather than inferred from a version number: the flags are
+ * what matters, and a build without one of them would reject the command
+ * outright — or, worse, a future one might accept and ignore it. Windows is
+ * left out because its shell quoting cannot be relied on to hand `--tools` an
+ * empty value.
+ */
+export declare function claudeSupportsVenueSessions(helpText: string, platform?: NodeJS.Platform): boolean;
+/**
+ * The Claude Code command a venue run is answered with.
+ *
+ * Built from the operator's binary and model only — never the rest of their
+ * `--exec` string, whose flags (`--add-dir`, `--mcp-config`, `--allowedTools`,
+ * `--dangerously-skip-permissions`) are exactly what a venue session must not
+ * get.
+ */
+export declare function claudeVenueCommand(exec: string, model?: string, platform?: NodeJS.Platform): string;
+/**
+ * The environment a venue session's child gets, built up rather than pared
+ * down: the shell basics above, the locale, and Claude Code's own login and
+ * configuration (`CLAUDE_*`, `ANTHROPIC_*` — the brain cannot start without
+ * them). Everything else is dropped — ProhostAI's variables first among them,
+ * but also every other credential the operator's environment happens to hold.
+ *
+ * `HOME` stays real: Claude Code finds its login through it, and a session
+ * with no tools cannot read anything there.
+ */
+export declare function venueEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** A fresh empty directory for one venue session, and its removal. */
+export declare function venueWorkdir(): {
+    dir: string;
+    remove: () => void;
+};
+/**
+ * The `/ws/webhooks` contract for venue sessions. Mirrors `VENUE_SESSION_*` in
+ * the server's `shared/agents/venue.py`: the feature `auth_ok` lists, the frame
+ * this harness sends to open one, and the frame it gets back.
+ */
+export declare const VENUE_SESSION_FEATURE = "venue_session";
+export declare const VENUE_SESSION_OPEN_FRAME = "venue_session_open";
+export declare const VENUE_SESSION_FRAME = "venue_session";
+/** An opened venue session: the run as the agent will see it, token attached. */
+export type VenueSessionResult = {
+    ok: true;
+    run: AgentRunRequest;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The run as its venue session answered it, with the thread and the token.
+ *
+ * The session is opened over this harness's own socket and nowhere else — the
+ * server keeps no HTTP route to it, so a process that merely holds this
+ * machine's key (an ordinary agent session) cannot ask for one the way the
+ * harness does. The token is attached to the returned run and goes nowhere
+ * else: no error here repeats the answer.
+ */
+export declare function venueRunFromSession(run: AgentRunRequest, data: Record<string, unknown>, answer: Record<string, unknown>, clock?: VenueClock): VenueSessionResult;
+/**
+ * When a venue session was asked for, and the time now, on both clocks. Each
+ * defaults to the real clock; tests pin them.
+ */
+export interface VenueClock {
+    openedAtMono?: number;
+    openedAtWall?: number;
+    nowMono?: number;
+    wallNow?: number;
+}
+/**
+ * How long before its deadline a venue grant already counts as over: room to
+ * close the run with its token while the token still works.
+ */
+export declare const VENUE_EXPIRY_MARGIN_MS = 30000;
+/**
+ * How often a running venue run's grant is re-checked: the longest a run can
+ * outlive its grant after the machine wakes from a sleep.
+ */
+export declare const VENUE_GRANT_CHECK_MS = 15000;
+/** The completion error of a venue run whose grant ran out before it started. */
+export declare const VENUE_GRANT_EXPIRED_ERROR = "connected-team grant expired before the run started";
+/** The completion error of a venue run stopped because its grant was ending. */
+export declare const VENUE_GRANT_ENDED_ERROR = "connected-team grant expired while the run was working";
+/**
+ * How much of a venue run's grant is left, in milliseconds — negative once it
+ * is over, and `-Infinity` for a run that carries no grant.
+ *
+ * The lifetime is counted on both clocks and the shorter one wins: the
+ * monotonic clock cannot be wound back, and the wall clock keeps counting
+ * while the machine sleeps (Linux's monotonic clock does not), so neither a
+ * changed clock nor a suspend outlasts the token. Both count elapsed time from
+ * the same moment, so a skewed wall clock still cancels out.
+ */
+export declare function venueGrantRemainingMs(run: AgentRunRequest, nowMono?: number, wallNow?: number): number;
+/**
+ * Whether a venue run's grant is still good — checked when its session opens
+ * and again right before the agent is started, so a run that waited in the
+ * queue past its grant never starts.
+ */
+export declare function venueGrantLive(run: AgentRunRequest, nowMono?: number, wallNow?: number): boolean;
+/**
+ * What a venue run reports about itself while it works and when it fails.
+ *
+ * The run's progress line and failure detail land on its row in this agent's
+ * home workspace. A venue run's would be the agent's words about the
+ * connected team's thread — or the thread itself, quoted — so it reports a
+ * fixed line instead.
+ */
+export declare const VENUE_PROGRESS = "answering in a connected team's thread";

package/dist/agent/venue.js

@@ -0,0 +1,272 @@
+/**
+ * Runs that answer in a connected team's thread — a *venue*.
+ *
+ * Connected Teams let two ProhostAI workspaces talk in each other's team chat,
+ * so this agent can be addressed in a thread that belongs to the OTHER
+ * workspace. That thread's text is someone else's prompt, and the harness's own
+ * credential can write anywhere in this agent's home workspace. So a venue run
+ * is answered by a session that holds none of it:
+ *
+ * * **Its own credential.** The event carries no thread text at all. The
+ *   harness opens the run's *venue session* over its own `/ws/webhooks` socket
+ *   (there is no HTTP route to it) and gets back a token minted for this one
+ *   run together with the thread. The token reads and posts in that one thread and heartbeats,
+ *   streams and completes that one run — nothing else — and the server refuses
+ *   the harness's key for all of it. Every request the run makes carries the
+ *   token. It lives in memory only: never logged, never written to disk.
+ * * **No tools, no configuration.** Claude Code is started from the operator's
+ *   binary and model only, with `--tools ''` (no built-in tools, so nothing can
+ *   read the credentials file or the environment), `--safe-mode` and
+ *   `--setting-sources '' --settings '{}'` (no hooks, plugins, skills,
+ *   `CLAUDE.md`, permissions or settings from `~/.claude` or any project), an
+ *   empty strict MCP config (never the ProhostAI server or the operator's extra
+ *   servers), and `--no-session-persistence` (the connected team's text is not
+ *   written to a transcript). The agent answers from the thread; the harness
+ *   posts the reply.
+ * * **No home environment.** The child gets an allowlisted environment —
+ *   what a shell and the Claude login need, nothing of ProhostAI's — and an
+ *   empty directory of its own, removed afterwards.
+ *
+ * Only Claude Code can be held to that, and only a release that has every one
+ * of those flags, so only such a harness declares
+ * {@link VENUE_RUN_TOKEN_CAPABILITY} — and the server sends venue runs only to
+ * a runtime that declared it. A venue run that reaches any other harness anyway
+ * is refused without being run.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseRunRequest } from './contract.js';
+import { shellQuote } from './shell.js';
+/**
+ * What a harness declares in its `runtime_status` frame when it runs venue
+ * sessions as described above. Mirrors `VENUE_RUN_TOKEN_CAPABILITY` in the
+ * server's `shared/agents/runtime_status.py`.
+ */
+export const VENUE_RUN_TOKEN_CAPABILITY = 'venue_run_token';
+/** The token prefix the server mints. Anything else is not a run token. */
+export const VENUE_RUN_TOKEN_PREFIX = 'pvr_';
+/** Every flag {@link claudeVenueCommand} uses. A build missing one cannot run a venue session. */
+const VENUE_FLAGS = [
+    '--tools',
+    '--safe-mode',
+    '--setting-sources',
+    '--settings',
+    '--strict-mcp-config',
+    '--mcp-config',
+    '--no-session-persistence',
+];
+/** Whether a run answers in a connected team's thread. */
+export function isVenueRun(run) {
+    return run.venue !== undefined;
+}
+/**
+ * The API options a run's requests go out with: its own token for a venue run
+ * whose session is open, the harness's credential for every other.
+ */
+export function apiForRun(api, run) {
+    return isVenueRun(run) && run.venue_run_token ? { ...api, apiKey: run.venue_run_token } : api;
+}
+/**
+ * Whether this Claude Code binary has every flag a venue session depends on.
+ *
+ * Asked of `--help` rather than inferred from a version number: the flags are
+ * what matters, and a build without one of them would reject the command
+ * outright — or, worse, a future one might accept and ignore it. Windows is
+ * left out because its shell quoting cannot be relied on to hand `--tools` an
+ * empty value.
+ */
+export function claudeSupportsVenueSessions(helpText, platform = process.platform) {
+    if (platform === 'win32')
+        return false;
+    return VENUE_FLAGS.every((flag) => new RegExp(`(^|\\s)${flag.replace(/-/g, '\\-')}(\\s|,|$)`, 'm').test(helpText));
+}
+/** An empty MCP config, inline: there is no file another run could rewrite under us. */
+const EMPTY_MCP_CONFIG = '{"mcpServers":{}}';
+/**
+ * The Claude Code command a venue run is answered with.
+ *
+ * Built from the operator's binary and model only — never the rest of their
+ * `--exec` string, whose flags (`--add-dir`, `--mcp-config`, `--allowedTools`,
+ * `--dangerously-skip-permissions`) are exactly what a venue session must not
+ * get.
+ */
+export function claudeVenueCommand(exec, model, platform = process.platform) {
+    const quote = (value) => shellQuote(value, platform);
+    const binary = exec.trim().split(/\s+/)[0] ?? 'claude';
+    const parts = [binary, '-p'];
+    if (model)
+        parts.push('--model', quote(model));
+    parts.push('--output-format', 'stream-json', '--verbose', '--no-session-persistence', '--safe-mode', '--setting-sources', quote(''), '--settings', quote('{}'), '--tools', quote(''), 
+    // Last: `--mcp-config` is variadic and would swallow anything after it
+    // that is not itself a flag.
+    '--strict-mcp-config', '--mcp-config', quote(EMPTY_MCP_CONFIG));
+    return parts.join(' ');
+}
+/** Variables a venue session keeps by name: what a shell and the TLS stack need. */
+const VENUE_ENV_NAMES = new Set([
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'LANG',
+    'TERM',
+    'TMPDIR',
+    'TZ',
+    'NODE_EXTRA_CA_CERTS',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'HTTPS_PROXY',
+    'HTTP_PROXY',
+    'NO_PROXY',
+    'https_proxy',
+    'http_proxy',
+    'no_proxy',
+]);
+/**
+ * The environment a venue session's child gets, built up rather than pared
+ * down: the shell basics above, the locale, and Claude Code's own login and
+ * configuration (`CLAUDE_*`, `ANTHROPIC_*` — the brain cannot start without
+ * them). Everything else is dropped — ProhostAI's variables first among them,
+ * but also every other credential the operator's environment happens to hold.
+ *
+ * `HOME` stays real: Claude Code finds its login through it, and a session
+ * with no tools cannot read anything there.
+ */
+export function venueEnv(base) {
+    const env = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || /PROHOST/i.test(key))
+            continue;
+        if (VENUE_ENV_NAMES.has(key) || key.startsWith('LC_') || /^(CLAUDE|ANTHROPIC)_/.test(key))
+            env[key] = value;
+    }
+    return env;
+}
+/** A fresh empty directory for one venue session, and its removal. */
+export function venueWorkdir() {
+    const dir = mkdtempSync(path.join(os.tmpdir(), 'prohost-venue-'));
+    return {
+        dir,
+        remove: () => {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best effort: an empty temp directory left behind costs nothing.
+            }
+        },
+    };
+}
+/**
+ * The `/ws/webhooks` contract for venue sessions. Mirrors `VENUE_SESSION_*` in
+ * the server's `shared/agents/venue.py`: the feature `auth_ok` lists, the frame
+ * this harness sends to open one, and the frame it gets back.
+ */
+export const VENUE_SESSION_FEATURE = 'venue_session';
+export const VENUE_SESSION_OPEN_FRAME = 'venue_session_open';
+export const VENUE_SESSION_FRAME = 'venue_session';
+/**
+ * The run as its venue session answered it, with the thread and the token.
+ *
+ * The session is opened over this harness's own socket and nowhere else — the
+ * server keeps no HTTP route to it, so a process that merely holds this
+ * machine's key (an ordinary agent session) cannot ask for one the way the
+ * harness does. The token is attached to the returned run and goes nowhere
+ * else: no error here repeats the answer.
+ */
+export function venueRunFromSession(run, data, answer, clock = {}) {
+    if (answer.ok !== true)
+        return { ok: false, error: 'the server refused the venue session' };
+    const token = typeof answer.token === 'string' ? answer.token : '';
+    if (!token.startsWith(VENUE_RUN_TOKEN_PREFIX))
+        return { ok: false, error: 'the venue session carried no run token' };
+    const trigger = answer.trigger && typeof answer.trigger === 'object' ? answer.trigger : {};
+    const opened = parseRunRequest({
+        ...data,
+        trigger: { ...data.trigger, ...trigger },
+        recent_messages: Array.isArray(answer.recent_messages) ? answer.recent_messages : [],
+    });
+    if (opened === null || opened.run_id !== run.run_id) {
+        return { ok: false, error: 'the venue session did not match the run' };
+    }
+    const lifetime = sessionLifetimeMs(answer, clock.wallNow);
+    if (lifetime === undefined)
+        return { ok: false, error: 'the venue session carried no expiry' };
+    const withGrant = {
+        ...opened,
+        venue_run_token: token,
+        venue_deadline_ms: (clock.openedAtMono ?? performance.now()) + lifetime,
+        venue_wall_deadline_ms: (clock.openedAtWall ?? Date.now()) + lifetime,
+    };
+    if (!venueGrantLive(withGrant, clock.nowMono, clock.wallNow)) {
+        return { ok: false, error: 'the venue session had already expired' };
+    }
+    return { ok: true, run: withGrant };
+}
+/**
+ * How long the grant lasts from when the session was asked for, or
+ * `undefined` for an answer that states none.
+ *
+ * The server's remaining lifetime (`expires_in_seconds`) is counted from when
+ * the session was asked for — never later than the server started counting —
+ * so neither a skewed wall clock nor the round trip can lengthen the grant.
+ * `expires_at` is the fallback for a server that sends only that, and the one
+ * place the wall clock's reading is trusted.
+ */
+function sessionLifetimeMs(answer, wallNow = Date.now()) {
+    const remaining = answer.expires_in_seconds;
+    if (typeof remaining === 'number' && Number.isFinite(remaining))
+        return Math.max(0, remaining) * 1000;
+    const expiresAt = typeof answer.expires_at === 'string' ? Date.parse(answer.expires_at) : Number.NaN;
+    if (!Number.isFinite(expiresAt))
+        return undefined;
+    return expiresAt - wallNow;
+}
+/**
+ * How long before its deadline a venue grant already counts as over: room to
+ * close the run with its token while the token still works.
+ */
+export const VENUE_EXPIRY_MARGIN_MS = 30_000;
+/**
+ * How often a running venue run's grant is re-checked: the longest a run can
+ * outlive its grant after the machine wakes from a sleep.
+ */
+export const VENUE_GRANT_CHECK_MS = 15_000;
+/** The completion error of a venue run whose grant ran out before it started. */
+export const VENUE_GRANT_EXPIRED_ERROR = 'connected-team grant expired before the run started';
+/** The completion error of a venue run stopped because its grant was ending. */
+export const VENUE_GRANT_ENDED_ERROR = 'connected-team grant expired while the run was working';
+/**
+ * How much of a venue run's grant is left, in milliseconds — negative once it
+ * is over, and `-Infinity` for a run that carries no grant.
+ *
+ * The lifetime is counted on both clocks and the shorter one wins: the
+ * monotonic clock cannot be wound back, and the wall clock keeps counting
+ * while the machine sleeps (Linux's monotonic clock does not), so neither a
+ * changed clock nor a suspend outlasts the token. Both count elapsed time from
+ * the same moment, so a skewed wall clock still cancels out.
+ */
+export function venueGrantRemainingMs(run, nowMono = performance.now(), wallNow = Date.now()) {
+    if (run.venue_deadline_ms === undefined || run.venue_wall_deadline_ms === undefined)
+        return -Infinity;
+    return Math.min(run.venue_deadline_ms - nowMono, run.venue_wall_deadline_ms - wallNow);
+}
+/**
+ * Whether a venue run's grant is still good — checked when its session opens
+ * and again right before the agent is started, so a run that waited in the
+ * queue past its grant never starts.
+ */
+export function venueGrantLive(run, nowMono = performance.now(), wallNow = Date.now()) {
+    return venueGrantRemainingMs(run, nowMono, wallNow) > VENUE_EXPIRY_MARGIN_MS;
+}
+/**
+ * What a venue run reports about itself while it works and when it fails.
+ *
+ * The run's progress line and failure detail land on its row in this agent's
+ * home workspace. A venue run's would be the agent's words about the
+ * connected team's thread — or the thread itself, quoted — so it reports a
+ * fixed line instead.
+ */
+export const VENUE_PROGRESS = "answering in a connected team's thread";

package/dist/version.d.ts

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export declare const CLI_VERSION = "0.12.4";
+export declare const CLI_VERSION = "0.13.1";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.12.4";
+export declare const USER_AGENT = "prohost-cli/0.13.1";

package/dist/version.js

@@ -7,6 +7,6 @@
  * `package.json`, so a release bump that forgets this file fails the suite
  * instead of shipping a `User-Agent` that lies about which build is calling.
  */
-export const CLI_VERSION = '0.12.4';
+export const CLI_VERSION = '0.13.1';
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
 export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prohost/cli",
-  "version": "0.12.4",
+  "version": "0.13.1",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",