@prohost/cli 0.12.4 → 0.13.2

package/CHANGELOG.md

@@ -4,6 +4,60 @@ Versions follow [semver](https://semver.org/). Publishing is automated: merging
 a version bump to `main` triggers `.github/workflows/npm-publish-cli.yml`, which
 builds via `prepack`, runs the suite, publishes, and tags `cli-v<version>`.
 
+## 0.13.2
+
+- **A run stopped by the Claude usage limit tells ProhostAI when the limit
+  lifts.** The completion now carries `failure_kind: "usage_limit"` and, when
+  Claude Code's stream said, `retry_after` (the reset time). When the limit
+  lifts within a few hours, ProhostAI runs the same request again shortly after,
+  unless someone asks again first; either way it alerts the person who asked
+  instead of leaving a note nobody is notified of. The thread keeps its session, as before, so the retry continues it. A
+  server that predates the fields ignores them.
+
+## 0.13.1
+
+- **A connected team's thread is never answered after the run's grant ended.**
+  A venue session that has already expired (or has less than 30 seconds left)
+  is refused when it opens, and the grant is checked again right before
+  Claude Code starts. A run that waited in the queue past its grant is never
+  started; it is closed as failed with its own token while the token still
+  works, so the thread's thinking indicator clears. A `--dry-run` only logs
+  that it would.
+- **The grant is timed on both of this machine's clocks**, from the server's
+  own remaining lifetime (`expires_in_seconds`) counted from when the session
+  was asked for, and whichever runs out first ends it. A wound-back system
+  clock can't lengthen it, and neither can a sleep the monotonic clock doesn't
+  count (Linux): a venue run is re-checked at least every 15 seconds.
+- **A venue run whose grant is ending is stopped and closed with its own
+  token** while the 30-second margin still leaves it good — queued or already
+  working — instead of being dropped locally and left to the server's
+  stale-run sweep. Nothing it was saying is posted.
+
+## 0.13.0
+
+- **An agent can answer in a connected team's thread without its own key.**
+  When ProhostAI hands this agent a run in a thread that belongs to a
+  connected team's workspace, the event carries none of that thread. The CLI
+  opens the run's venue session over its own connection to ProhostAI (there is
+  no HTTP route to it), which returns the thread and a token minted for that
+  one run. It uses the token, not this machine's key, for every request the
+  run makes, and keeps it in memory only. The run's progress line and failure
+  report are fixed text, so nothing from that thread lands in this
+  workspace's run history or in this machine's log. ProhostAI hands such a
+  run only to the one connection that holds this pairing: if a second process
+  connects with the same key, the run is declined rather than sent to either.
+- The run is answered by a Claude Code session started from your `--exec`
+  binary and model only. It has no tools, no MCP servers, no hooks, plugins,
+  settings or `CLAUDE.md` (`--safe-mode --setting-sources '' --settings '{}'`),
+  and writes no transcript (`--no-session-persistence`). Its environment
+  contains only the shell basics and Claude Code's own login, and it runs in an
+  empty directory of its own. The other team's messages never reach a session
+  that could act on this workspace.
+- The CLI tells ProhostAI it can do this (`capabilities: ["venue_run_token"]`
+  on its status frame) only when it drives a Claude Code that has all of those
+  flags, on macOS or Linux. ProhostAI sends such runs to no other agent. Codex
+  and plain `--exec` commands are unchanged and never receive one.
+
 ## 0.12.4
 
 - Refuse redirects on credentialed API writes and pairing requests, so a validated endpoint cannot replay keys or pairing codes to another destination. Direct HTTPS and local-loopback requests keep working.

package/README.md

@@ -1,6 +1,6 @@
 # `@prohost/cli`
 
-The [ProhostAI](https://www.prohost.ai) command-line tool. Three things it does:
+The [ProhostAI](https://prohost.ai) command-line tool. Three things it does:
 
 - **`prohost agent`** — run your own local agent as a ProhostAI teammate. Someone
   @-mentions it in the app, it runs on your machine, and its answer is posted
@@ -233,9 +233,12 @@ and gets a reply that has forgotten asking. The CLI reads the `session_id` out
 of Claude Code's JSON output, records it per conversation in
 `~/.prohost/sessions.json`, and `--resume`s it next time. Sessions don't live
 forever; when one is gone the run is retried once from scratch rather than
-failing. A run stopped by your Claude usage limit is not retried: it fails
+failing. A run stopped by your Claude usage limit is not retried here: it fails
 with Claude Code's own message, which says when the limit resets, and the
-conversation keeps its session for the next run.
+conversation keeps its session for the next run. The failure also tells
+ProhostAI when the limit lifts: if that is within a few hours, ProhostAI asks
+the agent again shortly after (unless someone asks again first), and either way
+it alerts whoever asked.
 
 **It lets the agent actually do things.** Runs are invoked with
 `--dangerously-skip-permissions`, so tool calls execute without stopping to ask.
@@ -663,6 +666,27 @@ Other agents: the CLI shapes no command but Claude Code's and Codex's, so give
 yours its own equivalent flag — whatever your runner calls it — and apply the
 same judgement.
 
+**Threads in a connected team's workspace are the exception.** When a
+connected team addresses your agent in one of *their* threads, the prompt is
+another workspace's text, so the run is answered without any of the above. The
+event carries none of the thread: the CLI opens the run's venue session over
+its own connection to ProhostAI (no HTTP route, so a process that only holds
+your key cannot ask the same way), which returns the thread and a token of its
+own that can only read and post in that one thread and report on that one run.
+ProhostAI sends such a run only while this connection is the only one holding
+the pairing, and opens its session only on the connection it went to: another
+process connecting with your key makes the run decline, never receive it. The CLI uses it instead of your key and
+keeps it in memory only. Claude Code is started from your `--exec` binary and
+model only, with `--tools ''`, `--safe-mode`, `--setting-sources ''
+--settings '{}'`, an empty `--strict-mcp-config` and
+`--no-session-persistence`: no tools, no MCP servers, no hooks, plugins,
+settings or `CLAUDE.md`, no transcript on disk. Its environment holds only the
+shell basics and Claude Code's own login, and it runs in an empty directory of
+its own. The agent answers from the thread it is sent; the CLI posts the reply.
+Only a Claude Code that has those flags, on macOS or Linux, tells ProhostAI it
+can do this, and ProhostAI sends these runs to no other agent — Codex and plain
+commands never get one.
+
 ### `agent run` flags
 
 | Flag | Default | What it does |

package/dist/agent/api.d.ts

@@ -129,6 +129,20 @@ export type HeartbeatOutcome =
  * work send none either.
  */
 export declare function heartbeatRun(options: ApiOptions, path: string, progress?: string): Promise<HeartbeatOutcome>;
+/**
+ * A run's terminal state as the completion reports it. A failure the brain's
+ * usage limit caused says so, with when the limit lifts if the brain said.
+ */
+export type CompletionOutcome = {
+    ok: true;
+    silent?: boolean;
+} | {
+    ok: false;
+    error: string;
+    usageLimit?: {
+        retryAfter?: string;
+    };
+};
 /**
  * Report a run's terminal state. Called for every run — including one whose
  * command crashed — so the server never waits on a run this harness abandoned.
@@ -140,13 +154,7 @@ export declare function heartbeatRun(options: ApiOptions, path: string, progress
  * ``model`` is the model id the run used, when the harness knows it. Omitted
  * otherwise, so a plain ``--exec`` command's completion body is unchanged.
  */
-export declare function completeRun(options: ApiOptions, path: string, outcome: {
-    ok: true;
-    silent?: boolean;
-} | {
-    ok: false;
-    error: string;
-}, model?: string): Promise<ApiResult>;
+export declare function completeRun(options: ApiOptions, path: string, outcome: CompletionOutcome, model?: string): Promise<ApiResult>;
 /**
  * Report a batch of tool events for a run in flight.
  *

package/dist/agent/api.js

@@ -10,7 +10,7 @@
  * `completion.path`), which is why these take a path rather than building one.
  */
 import { USER_AGENT } from '../version.js';
-import { MAX_ERROR_CHARS, MAX_MODEL_CHARS, MAX_PROGRESS_CHARS, MAX_TOOL_EVENTS_PER_BATCH, RUN_OUTCOME_SILENT, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.js';
+import { MAX_ERROR_CHARS, MAX_MODEL_CHARS, MAX_PROGRESS_CHARS, MAX_TOOL_EVENTS_PER_BATCH, RUN_FAILURE_USAGE_LIMIT, RUN_OUTCOME_SILENT, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.js';
 /** Deadline for the cheap calls — a heartbeat answers in milliseconds. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 /**
@@ -184,6 +184,11 @@ export async function completeRun(options, path, outcome, model) {
     const body = outcome.ok
         ? { status: RUN_STATUS_SUCCEEDED, ...(outcome.silent ? { outcome: RUN_OUTCOME_SILENT } : {}) }
         : { status: RUN_STATUS_FAILED, error: outcome.error.slice(0, MAX_ERROR_CHARS) };
+    if (!outcome.ok && outcome.usageLimit) {
+        body.failure_kind = RUN_FAILURE_USAGE_LIMIT;
+        if (outcome.usageLimit.retryAfter)
+            body.retry_after = outcome.usageLimit.retryAfter;
+    }
     if (model)
         body.model = model.slice(0, MAX_MODEL_CHARS);
     const result = await postJson(options, path, body, undefined, false, SEND_TIMEOUT_MS);

package/dist/agent/claude.d.ts

@@ -199,6 +199,13 @@ export interface ClaudeStream {
      * help until the limit resets, so a caller must not retry it.
      */
     usageLimit(): string | undefined;
+    /**
+     * When the usage limit that stopped the turn lifts, in epoch seconds: the
+     * `resetsAt` of the rejecting `rate_limit_event`. `undefined` when no such
+     * event arrived, even if {@link usageLimit} recognised the limit from Claude
+     * Code's message alone — that message's "resets 11pm" is for people.
+     */
+    usageLimitResetsAt(): number | undefined;
     /**
      * The turn's outcome. ``stdout`` is the complete captured output, used only
      * when the stream held no `result` event — a crashed binary, a login prompt,

package/dist/agent/claude.js

@@ -655,6 +655,10 @@ export function readClaudeStream() {
                 ? 'usage limit reached'
                 : `usage limit reached · resets ${new Date(resetsAt * 1000).toISOString()}`;
         },
+        usageLimitResetsAt: () => {
+            flushTail();
+            return limitRejected?.resetsAt;
+        },
         finish(stdout) {
             // A binary that exits without flushing a final `\n` must not lose its
             // result.

package/dist/agent/contract.d.ts

@@ -50,6 +50,13 @@ export declare const RUN_OUTCOME_SILENT = "silent";
 export declare const NO_REPLY_TOKEN = "[NO_REPLY]";
 /** Whether the agent's output is the no-reply token and nothing else. */
 export declare function isNoReply(output: string): boolean;
+/**
+ * Completion `failure_kind` for a run the brain's subscription usage limit
+ * stopped. Sent with `status: failed`, plus `retry_after` when the brain said
+ * when the limit lifts, so the server can retry the work then instead of
+ * leaving the question unanswered. A server that predates the field ignores it.
+ */
+export declare const RUN_FAILURE_USAGE_LIMIT = "usage_limit";
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export declare const MAX_ERROR_CHARS = 1000;
 /** Server-side cap on the `model` field of a completion (`MAX_MODEL_CHARS`). */
@@ -339,6 +346,36 @@ export interface AgentRunRequest {
     memories?: RunMemory[];
     /** Selected records omitted whole by the server's inline context budget. */
     memories_omitted?: number;
+    /**
+     * Set when the conversation belongs to a CONNECTED team's workspace rather
+     * than this agent's own (see `venue.ts`). Absent on every other run.
+     */
+    venue?: RunVenue;
+    /**
+     * The run's own credential, set by the harness once it opened the venue
+     * session — never read from the event. The one thing that may read and post
+     * in that thread and heartbeat, stream and complete the run. Kept in memory
+     * only, and never handed to the agent.
+     */
+    venue_run_token?: string;
+    /**
+     * When the venue run's grant ends, on this process's monotonic clock
+     * (`performance.now()`): the server's remaining lifetime counted from the
+     * moment the session was asked for, so a wrong wall clock cannot extend it.
+     */
+    venue_deadline_ms?: number;
+    /**
+     * The same deadline on the wall clock (`Date.now()`): the server's lifetime
+     * counted from the wall-clock moment the session was asked for. It keeps
+     * counting through a suspend, which the monotonic clock may not.
+     */
+    venue_wall_deadline_ms?: number;
+}
+/** The connected team's thread a venue run answers in. */
+export interface RunVenue {
+    account_id?: string;
+    conversation_id?: string;
+    team_connection_id?: string;
 }
 /** Reply destinations the server can bind a run to, including future surfaces. */
 export type ReplySurface = 'conversation' | 'task' | 'cleaning' | 'none' | (string & {});

package/dist/agent/contract.js

@@ -52,6 +52,13 @@ export const NO_REPLY_TOKEN = '[NO_REPLY]';
 export function isNoReply(output) {
     return output.trim().toUpperCase() === NO_REPLY_TOKEN;
 }
+/**
+ * Completion `failure_kind` for a run the brain's subscription usage limit
+ * stopped. Sent with `status: failed`, plus `retry_after` when the brain said
+ * when the limit lifts, so the server can retry the work then instead of
+ * leaving the question unanswered. A server that predates the field ignores it.
+ */
+export const RUN_FAILURE_USAGE_LIMIT = 'usage_limit';
 /** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
 export const MAX_ERROR_CHARS = 1000;
 /** Server-side cap on the `model` field of a completion (`MAX_MODEL_CHARS`). */
@@ -386,5 +393,16 @@ export function parseRunRequest(data) {
         recent_messages: contextList(data.recent_messages ?? context.recent_messages, parseMessage),
         memories: contextList(data.memories ?? context.memories, parseMemory),
         memories_omitted: omittedMemoryCount(data.memories_omitted ?? context.memories_omitted),
+        // Any object counts as a venue, so a run the server marked as one is never
+        // mistaken for a run at home — even if a field inside it is malformed.
+        ...(data.venue && typeof data.venue === 'object' && !Array.isArray(data.venue)
+            ? {
+                venue: {
+                    account_id: str(obj(data.venue).account_id),
+                    conversation_id: str(obj(data.venue).conversation_id),
+                    team_connection_id: str(obj(data.venue).team_connection_id),
+                },
+            }
+            : {}),
     };
 }

package/dist/agent/exec.d.ts

@@ -43,6 +43,12 @@ export interface ExecOptions {
     cwd?: string;
     /** Extra environment for the child, merged over ``process.env``. */
     env?: NodeJS.ProcessEnv;
+    /**
+     * ``false``: the child gets {@link env} and nothing else — not
+     * ``process.env``. A venue session's environment is built by dropping what
+     * it must not see, and merging the harness's own back over it would undo that.
+     */
+    inheritEnv?: boolean;
     /**
      * Ends the run early — a person pressed stop, or the server closed the run.
      *

package/dist/agent/exec.js

@@ -103,7 +103,11 @@ export async function execAgent(options) {
         const spawnOptions = {
             shell: true,
             cwd: options.cwd,
-            env: options.env ? { ...process.env, ...options.env } : process.env,
+            env: options.inheritEnv === false
+                ? { ...options.env }
+                : options.env
+                    ? { ...process.env, ...options.env }
+                    : process.env,
             stdio: ['pipe', 'pipe', 'pipe'],
             // Own process group. `--exec 'foo | bar'` runs under a shell, and
             // signalling the shell alone leaves its children holding our stdio

package/dist/agent/heartbeat.d.ts

@@ -44,6 +44,19 @@ export type Scheduler = (run: () => void, ms: number) => ScheduledTick;
 export interface HeartbeatTarget {
     /** Where the heartbeat POSTs — see `heartbeatPathFor`. */
     path: string;
+    /**
+     * The credential this run's beats go out with, when it is not the loop's
+     * own: a venue run is heartbeated with its run token (see `venue.ts`).
+     */
+    api?: ApiOptions;
+    /**
+     * A venue run (see `venue.ts`): its token's authority ends with the run's
+     * grant, so a refusal that means "this token is no longer good" — 401, 403,
+     * 404 — ends the run here as if the server had closed it, rather than
+     * leaving the agent working on a connected team's thread it may no longer
+     * answer.
+     */
+    venue?: boolean;
     /**
      * Latest one-line description of what the agent is doing, read fresh at each
      * beat. Absent for a queued run, and for brains whose output we don't stream.

package/dist/agent/heartbeat.js

@@ -122,7 +122,7 @@ export class HeartbeatLoop {
      */
     async beat(target) {
         try {
-            const outcome = await heartbeatRun(this.options.api, target.path, target.progress?.());
+            const outcome = await heartbeatRun(target.api ?? this.options.api, target.path, target.progress?.());
             // The run may have finished while its own heartbeat was in flight; acting
             // on a stale answer would cancel a run that is already reporting itself.
             if (!this.targets.has(target.runId))
@@ -135,6 +135,14 @@ export class HeartbeatLoop {
                 await target.onCancelRequested();
                 return;
             }
+            if (target.venue &&
+                (outcome.kind === 'unknown' ||
+                    (outcome.kind === 'error' && (outcome.status === 401 || outcome.status === 403)))) {
+                this.untrack(target.runId);
+                this.options.log(`    ⏹ run ${target.runId.slice(0, 12)} lost its connected-team grant — stopping it`);
+                await target.onResolved();
+                return;
+            }
             if (outcome.kind === 'unknown') {
                 // Said once per run, then silence: on a server that predates
                 // heartbeats this is the answer for every run forever, and a line a