@prohost/cli 0.6.0 → 0.8.0

package/dist/agent/claude.d.ts

@@ -14,9 +14,11 @@
  * session is unresumable, if the JSON is not what we expect — the run still
  * happens and still completes. These are enhancements that must fail soft.
  */
+import type { ToolEvent } from './contract.js';
 import { MCP_SERVER_NAME } from './mcp.js';
 import type { RuntimeObservation } from './runtime_status.js';
 export { MCP_SERVER_NAME };
+export type { ToolEvent };
 /**
  * What goes to `--allowedTools` so the ProhostAI tools are callable.
  *
@@ -126,6 +128,13 @@ export declare function parseClaudeOutput(stdout: string): ClaudeOutput;
 export declare const MAX_ACTIVITY_CHARS = 120;
 /** Cap on the partial answer salvaged from a run that was killed. */
 export declare const MAX_SALVAGE_CHARS = 500;
+/**
+ * Cap on the one-line previews a tool event carries — a headline argument,
+ * the head of a result. The server clips again and redacts before showing
+ * anything to a person; this bound just keeps a `Read` of a large file from
+ * putting the file on the wire.
+ */
+export declare const MAX_TOOL_EVENT_PREVIEW_CHARS = 200;
 /**
  * A run's stdout, read as it is produced.
  *
@@ -152,6 +161,16 @@ export interface ClaudeStream {
     activity(): string | undefined;
     /** The tail of the last thing the agent wrote, for a run that was killed. */
     salvage(): string | undefined;
+    /**
+     * Tool-call starts and ends seen since the last drain, in stream order.
+     *
+     * Each `tool_use` block becomes a `calling` event and each `tool_result`
+     * block the matching `completed` / `failed`, correlated by Claude Code's
+     * own `tool_use.id`. Taken, not copied: a second call returns only what
+     * arrived in between. Empty for a stream with no tool calls, and for one
+     * that isn't Claude Code's at all.
+     */
+    drainToolEvents(): ToolEvent[];
     /**
      * Model, Claude Code version and capacity windows the stream announced —
      * `system/init.{model, claude_code_version}` and the last
@@ -165,6 +184,22 @@ export interface ClaudeStream {
      */
     finish(stdout: string): ClaudeOutput;
 }
+/**
+ * What a tool was called with, as a small JSON object the server can render.
+ *
+ * For the tools whose input has an obvious headline — the command, the path,
+ * the pattern, the URL — that field alone; the rest of the input (a `Write`'s
+ * whole file content, an `Edit`'s old and new strings) stays on this machine.
+ * Anything else is a shallow projection of the input: the first few keys,
+ * scalar values capped, lists and objects reduced to their shape — which for
+ * an MCP tool is a handful of ids and short strings.
+ *
+ * Always a JSON **object** string, never bare text: the run-detail page
+ * parses the preview as JSON and renders it `key=value` through a key-aware
+ * redactor (so a `token` key is masked outright), and a preview it cannot
+ * parse is shown as nothing at all.
+ */
+export declare function toolArgsPreview(name: string, input: unknown): string | undefined;
 /**
  * Parse `--output-format stream-json` incrementally.
  *

package/dist/agent/claude.js

@@ -269,6 +269,21 @@ export function parseClaudeOutput(stdout) {
 export const MAX_ACTIVITY_CHARS = 120;
 /** Cap on the partial answer salvaged from a run that was killed. */
 export const MAX_SALVAGE_CHARS = 500;
+/**
+ * Cap on the one-line previews a tool event carries — a headline argument,
+ * the head of a result. The server clips again and redacts before showing
+ * anything to a person; this bound just keeps a `Read` of a large file from
+ * putting the file on the wire.
+ */
+export const MAX_TOOL_EVENT_PREVIEW_CHARS = 200;
+/**
+ * Cap on tool events held between drains.
+ *
+ * The reader is drained on every stdout chunk, so this only ever fills if
+ * nobody is draining — a caller that doesn't report events at all. Oldest
+ * dropped, so memory stays bounded for the whole of a long run.
+ */
+const MAX_PENDING_TOOL_EVENTS = 500;
 /**
  * Cap on a single buffered stdout line.
  *
@@ -301,6 +316,116 @@ function assistantContent(event) {
     }
     return { text: latestText, tool: latestTool };
 }
+/** Whitespace-collapsed, trimmed, capped — or nothing, for nothing. */
+function preview(text) {
+    const collapsed = text?.replace(/\s+/g, ' ').trim();
+    if (!collapsed)
+        return undefined;
+    return collapsed.length > MAX_TOOL_EVENT_PREVIEW_CHARS
+        ? collapsed.slice(0, MAX_TOOL_EVENT_PREVIEW_CHARS)
+        : collapsed;
+}
+/**
+ * Cap on one value inside a JSON args preview, and on how many keys travel.
+ * The server's key-aware redactor reads the preview as an object, so the
+ * shape must survive intact: capping values (not the JSON) is what keeps a
+ * large MCP argument from truncating the object mid-key into something the
+ * reader can no longer parse.
+ */
+const MAX_PREVIEW_VALUE_CHARS = 120;
+const MAX_PREVIEW_KEYS = 6;
+/**
+ * What a tool was called with, as a small JSON object the server can render.
+ *
+ * For the tools whose input has an obvious headline — the command, the path,
+ * the pattern, the URL — that field alone; the rest of the input (a `Write`'s
+ * whole file content, an `Edit`'s old and new strings) stays on this machine.
+ * Anything else is a shallow projection of the input: the first few keys,
+ * scalar values capped, lists and objects reduced to their shape — which for
+ * an MCP tool is a handful of ids and short strings.
+ *
+ * Always a JSON **object** string, never bare text: the run-detail page
+ * parses the preview as JSON and renders it `key=value` through a key-aware
+ * redactor (so a `token` key is masked outright), and a preview it cannot
+ * parse is shown as nothing at all.
+ */
+export function toolArgsPreview(name, input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return undefined;
+    const args = input;
+    const headline = HEADLINE_FIELDS[name];
+    if (headline) {
+        for (const key of headline) {
+            const value = args[key];
+            const text = typeof value === 'string' ? preview(value) : undefined;
+            if (text)
+                return JSON.stringify({ [key]: text });
+        }
+        // A headline-only tool with no headline shows nothing rather than its
+        // whole input — that input is the file content this field exists to keep
+        // off the wire.
+        return undefined;
+    }
+    const projected = {};
+    for (const key of Object.keys(args).slice(0, MAX_PREVIEW_KEYS)) {
+        const value = args[key];
+        if (typeof value === 'string') {
+            const collapsed = value.replace(/\s+/g, ' ').trim();
+            projected[key] =
+                collapsed.length > MAX_PREVIEW_VALUE_CHARS ? collapsed.slice(0, MAX_PREVIEW_VALUE_CHARS) : collapsed;
+        }
+        else if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+            projected[key] = value;
+        }
+        else if (Array.isArray(value)) {
+            projected[key] = `[${value.length} items]`;
+        }
+        else if (value && typeof value === 'object') {
+            projected[key] = `{${Object.keys(value).length} keys}`;
+        }
+    }
+    try {
+        return JSON.stringify(projected);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The field that IS the call, per tool, in order of preference. Listed tools
+ * never fall through to the projection above.
+ */
+const HEADLINE_FIELDS = {
+    Bash: ['command'],
+    shell: ['command'],
+    Read: ['file_path'],
+    Edit: ['file_path'],
+    MultiEdit: ['file_path'],
+    Write: ['file_path'],
+    NotebookEdit: ['notebook_path', 'file_path'],
+    Grep: ['pattern'],
+    Glob: ['pattern'],
+    WebFetch: ['url'],
+    WebSearch: ['query'],
+    Task: ['description'],
+    Agent: ['description'],
+};
+/** The text of a `tool_result` block — a string, or its `text` parts joined. */
+function toolResultText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const entry = block;
+        if (entry.type === 'text' && typeof entry.text === 'string')
+            parts.push(entry.text);
+    }
+    return parts.length > 0 ? parts.join(' ') : undefined;
+}
 /**
  * Parse `--output-format stream-json` incrementally.
  *
@@ -316,6 +441,74 @@ export function readClaudeStream() {
     let lastActivity;
     let lastText;
     let result;
+    let toolEvents = [];
+    // `tool_use.id` → tool name, so a result can be reported under the name of
+    // the call it answers. Deleted on the result: bounded by tools in flight.
+    const toolNames = new Map();
+    const enqueue = (event) => {
+        toolEvents.push(event);
+        if (toolEvents.length > MAX_PENDING_TOOL_EVENTS)
+            toolEvents.shift();
+    };
+    /** Every `tool_use` block in an assistant message → a `calling` event. */
+    const collectToolUses = (event) => {
+        const message = event.message;
+        if (!message || typeof message !== 'object')
+            return;
+        const content = message.content;
+        if (!Array.isArray(content))
+            return;
+        for (const block of content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const entry = block;
+            if (entry.type !== 'tool_use')
+                continue;
+            const id = text(entry.id);
+            const name = text(entry.name);
+            if (!id || !name)
+                continue;
+            toolNames.set(id, name);
+            const args = toolArgsPreview(name, entry.input);
+            enqueue({
+                tool_id: id,
+                tool_name: name,
+                status: 'calling',
+                started_at: new Date().toISOString(),
+                ...(args ? { args_preview: args } : {}),
+            });
+        }
+    };
+    /** Every `tool_result` block in a user message → the matching terminal event. */
+    const collectToolResults = (event) => {
+        const message = event.message;
+        if (!message || typeof message !== 'object')
+            return;
+        const content = message.content;
+        if (!Array.isArray(content))
+            return;
+        for (const block of content) {
+            if (!block || typeof block !== 'object')
+                continue;
+            const entry = block;
+            if (entry.type !== 'tool_result')
+                continue;
+            const id = text(entry.tool_use_id);
+            if (!id)
+                continue;
+            const name = toolNames.get(id) ?? 'unknown';
+            toolNames.delete(id);
+            const summary = preview(toolResultText(entry.content));
+            const failed = entry.is_error === true;
+            enqueue({
+                tool_id: id,
+                tool_name: name,
+                status: failed ? 'failed' : 'completed',
+                ended_at: new Date().toISOString(),
+                ...(summary ? (failed ? { error_summary: summary } : { result_summary: summary }) : {}),
+            });
+        }
+    };
     const observed = {};
     const handle = (line) => {
         const event = asObject(line);
@@ -339,8 +532,15 @@ export function readClaudeStream() {
             result = event;
             return;
         }
+        if (event.type === 'user') {
+            // The harness's own prompt arrives as a `user` event too; it carries no
+            // `tool_result` blocks and falls straight through.
+            collectToolResults(event);
+            return;
+        }
         if (event.type !== 'assistant')
             return;
+        collectToolUses(event);
         const { text: written, tool } = assistantContent(event);
         if (written)
             lastText = written;
@@ -371,6 +571,11 @@ export function readClaudeStream() {
         },
         sessionId: () => session,
         activity: () => lastActivity,
+        drainToolEvents: () => {
+            const drained = toolEvents;
+            toolEvents = [];
+            return drained;
+        },
         observed: () => ({ ...observed }),
         salvage: () => {
             const trimmed = lastText?.trim();

package/dist/agent/command.d.ts

@@ -29,6 +29,23 @@ export declare const INVALID_DURATION: unique symbol;
  * had not.
  */
 export declare function parseSeconds(raw: string | boolean | undefined): number | undefined | typeof INVALID_DURATION;
+/**
+ * Environment the daemon must be given explicitly.
+ *
+ * launchd starts a job with almost nothing — notably a minimal `PATH` of
+ * `/usr/bin:/bin:/usr/sbin:/sbin`, which contains no `claude`. Installed from
+ * npm, Homebrew, or the official installer it lives in `~/.local/bin`,
+ * `/opt/homebrew/bin`, or `/usr/local/bin`, so without this the daemon
+ * installs cleanly, reports success, and then crash-loops on
+ * `claude: command not found` in a log nobody is watching.
+ *
+ * The `PATH` captured is the one in effect when the operator ran
+ * `install-daemon` — i.e. the one in which their `--exec` command actually
+ * works. `PROHOST_HOME` is pinned for the same reason it is used for the label:
+ * a daemon must keep serving the home it was installed from, whatever the
+ * environment of a later login happens to say.
+ */
+export declare function daemonEnvironment(): Record<string, string>;
 /** Dispatch an ``agent`` subcommand. Returns the process exit code. */
-export declare function runAgent(subcommand: string | undefined, flags: Flags, printHelp: () => void): Promise<number>;
+export declare function runAgent(subcommand: string | undefined, flags: Flags, printHelp: () => void, args?: string[]): Promise<number>;
 export {};

package/dist/agent/command.js

@@ -10,8 +10,11 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { agentLogPath, buildSystemdUnit, harnessArguments, installLaunchdDaemon, launchdLabel, uninstallLaunchdDaemon, } from './daemon.js';
+import { accountCommand, listCommand, workspaceCommand } from './agent_commands.js';
+import { AccountError, loadAccounts, setAgentAccount } from './accounts.js';
+import { acquireRunLock } from './lock.js';
 import { PairError, runPair } from './pair.js';
-import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome } from './credentials.js';
+import { CredentialsMissingError, ensureWorkspace, loadCredentials, prohostHome, tryLoadCredentials, } from './credentials.js';
 import { DEFAULT_EXEC_TIMEOUT_MS, DEFAULT_IDLE_TIMEOUT_MS, runAgentHarness } from './run.js';
 import { announceUpgradeIfAvailable } from '../upgrade.js';
 function flagString(flags, name) {
@@ -132,10 +135,14 @@ function parseIdleTimeoutSeconds(flags) {
  * a daemon must keep serving the home it was installed from, whatever the
  * environment of a later login happens to say.
  */
-function daemonEnvironment() {
+export function daemonEnvironment() {
     const env = { PROHOST_HOME: prohostHome() };
     if (process.env.PATH)
         env.PATH = process.env.PATH;
+    // A registry moved with $PROHOST_ACCOUNTS_ROOT must be the one the daemon
+    // reads, or it can't find the account it was installed with.
+    if (process.env.PROHOST_ACCOUNTS_ROOT)
+        env.PROHOST_ACCOUNTS_ROOT = process.env.PROHOST_ACCOUNTS_ROOT;
     return env;
 }
 /** Absolute path of this CLI's entrypoint, for a daemon to exec. */
@@ -147,7 +154,7 @@ function cliEntrypoint() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
 }
 /** Dispatch an ``agent`` subcommand. Returns the process exit code. */
-export async function runAgent(subcommand, flags, printHelp) {
+export async function runAgent(subcommand, flags, printHelp, args = []) {
     if (subcommand === 'pair')
         return pairCommand(flags);
     if (subcommand === 'run')
@@ -156,9 +163,16 @@ export async function runAgent(subcommand, flags, printHelp) {
         return installDaemonCommand(flags);
     if (subcommand === 'uninstall-daemon')
         return uninstallDaemonCommand();
+    if (subcommand === 'account')
+        return accountCommand(args, flags);
+    if (subcommand === 'list')
+        return listCommand();
+    if (subcommand === 'workspace')
+        return workspaceCommand(args, flags);
     process.stderr.write(subcommand
         ? `Unknown agent subcommand: ${subcommand}\n\n`
-        : 'Missing agent subcommand — expected `pair`, `run`, `install-daemon`, or `uninstall-daemon`.\n\n');
+        : 'Missing agent subcommand — expected `pair`, `run`, `install-daemon`, `uninstall-daemon`, ' +
+            '`account`, `list`, or `workspace`.\n\n');
     printHelp();
     return 1;
 }
@@ -184,6 +198,8 @@ async function installDaemonCommand(flags) {
     const credentials = loadOrExplain();
     if (!credentials)
         return 1;
+    if (!applyAccountFlag(flags))
+        return 1;
     // Validated here and not only in `agent run`, because the consequence differs:
     // a bad --timeout typed at a terminal prints an error, while one baked into a
     // plist makes every launch exit on that same validation and KeepAlive restart
@@ -261,6 +277,16 @@ async function pairCommand(flags) {
         process.stderr.write('Missing pairing code. Pass --code or set $PROHOST_PAIRING_CODE.\n');
         return 1;
     }
+    // Checked before the code is spent: a typo here must not cost a pairing.
+    const account = flagString(flags, 'account');
+    if (flags.account === true) {
+        process.stderr.write('--account needs a label, e.g. --account work\n');
+        return 1;
+    }
+    // A re-pair keeps the account the home already runs on unless told otherwise.
+    const previousAccount = tryLoadCredentials()?.account;
+    if (account && !accountExists(account))
+        return 1;
     try {
         await runPair({
             code,
@@ -268,6 +294,19 @@ async function pairCommand(flags) {
             wsUrl: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
             webhookUrl: flagString(flags, 'webhook-url'),
         });
+        const chosen = account ?? previousAccount;
+        if (chosen) {
+            try {
+                setAgentAccount(chosen, undefined);
+                process.stdout.write(`  Account      ${chosen}\n`);
+            }
+            catch (err) {
+                // Paired either way; only the carried-over account is gone.
+                if (!(err instanceof AccountError))
+                    throw err;
+                process.stderr.write(`! ${err.message} This agent will use the default login.\n`);
+            }
+        }
         return 0;
     }
     catch (err) {
@@ -293,6 +332,14 @@ async function runCommand(flags) {
     const parsedIdleTimeout = parseIdleTimeoutSeconds(flags);
     if (parsedIdleTimeout === INVALID_DURATION)
         return 1;
+    // One harness per home: two would both execute every run.
+    const lock = acquireRunLock();
+    if (!lock.ok) {
+        process.stderr.write(`✗ Another \`prohost agent run\` (pid ${lock.holder.pid}, started ${lock.holder.started_at || 'at an unknown time'}) ` +
+            `is already serving ${prohostHome()}. Stop it first — or, if it is the daemon, use ` +
+            '`prohost agent uninstall-daemon` — or give this agent its own $PROHOST_HOME.\n');
+        return 1;
+    }
     // First signal stops accepting work and lets the in-flight run finish
     // reporting itself (so the server doesn't wait on a run we abandoned); a
     // second one means the operator wants out now.
@@ -335,5 +382,42 @@ async function runCommand(flags) {
     finally {
         process.off('SIGINT', onSig);
         process.off('SIGTERM', onSig);
+        lock.release();
+    }
+}
+/** Whether an account label exists on this machine (any runtime), explaining if not. */
+function accountExists(label) {
+    if (label === 'default')
+        return true;
+    try {
+        // Validates only; the write happens once pairing has succeeded.
+        if (loadAccounts().some((a) => a.label === label))
+            return true;
+    }
+    catch {
+        /* fall through */
+    }
+    process.stderr.write(`✗ No account named "${label}" on this machine. Add it first: prohost agent account add ${label} --runtime claude|codex\n`);
+    return false;
+}
+/** `--account <label>` on install-daemon: persist it to agent.json. */
+function applyAccountFlag(flags) {
+    if (flags.account === undefined)
+        return true;
+    const label = flagString(flags, 'account');
+    if (!label) {
+        process.stderr.write('--account needs a label, e.g. --account work\n');
+        return false;
+    }
+    try {
+        setAgentAccount(label, undefined);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof AccountError) {
+            process.stderr.write(`✗ ${err.message}\n`);
+            return false;
+        }
+        throw err;
     }
 }

package/dist/agent/contract.d.ts

@@ -14,6 +14,7 @@
  *   - payload shape — `shared/events/payloads/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-runs/{id}/heartbeat` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/events` — `api_public/routers/agent_runs.py`
  *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
  *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
  */
@@ -27,6 +28,27 @@ export declare const EVENT_MESSAGE_TEAM_CHAT = "message.team_chat";
 /** Terminal statuses accepted by the run-completion endpoint. */
 export declare const RUN_STATUS_SUCCEEDED = "succeeded";
 export declare const RUN_STATUS_FAILED = "failed";
+/**
+ * Completion `outcome` for a run that deliberately posted nothing.
+ *
+ * Sent with `status: succeeded`: declining is a finished run, not a failure.
+ * The server records it the way an in-product `[NO_REPLY]` run is recorded and
+ * clears the thinking indicator as a "chose silence" rather than implying a
+ * reply landed. A server that predates the field ignores it, so it needs no
+ * version negotiation.
+ */
+export declare const RUN_OUTCOME_SILENT = "silent";
+/**
+ * What the agent writes as its WHOLE answer to say "no reply".
+ *
+ * The same token the in-product brain uses, so an agent's instructions read the
+ * same on either runtime. Matched on the trimmed output, case-insensitively —
+ * and never posted: the literal token landing in a thread is the one outcome
+ * that is worse than either replying or not.
+ */
+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;
 /** 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`). */
@@ -48,6 +70,37 @@ export declare const RUN_ERROR_CANCELLED_BY_USER = "cancelled_by_user";
  * enormous block of text can't turn a keep-alive into a payload.
  */
 export declare const MAX_PROGRESS_CHARS = 200;
+/**
+ * Server-side cap on events per `POST /v1/agent-runs/{id}/events` call
+ * (`shared.agents.external_tool_events.MAX_EVENTS_PER_REQUEST`). The run event
+ * also carries it as `events.max_batch`; this is the value for a payload that
+ * omits it, and the ceiling either way.
+ */
+export declare const MAX_TOOL_EVENTS_PER_BATCH = 50;
+/**
+ * One tool-call lifecycle event, as `POST /v1/agent-runs/{id}/events` takes it.
+ *
+ * `tool_id` is the runtime's own id for the invocation (Claude Code's
+ * `tool_use.id`); the server keeps one timeline row per id, opened by a
+ * `calling` and settled by a `completed` / `failed`, and ignores anything that
+ * would move a row backwards — which is what makes re-sending a batch safe.
+ * Everything else is optional and clipped server-side.
+ */
+export interface ToolEvent {
+    tool_id: string;
+    tool_name: string;
+    status: 'calling' | 'completed' | 'failed';
+    /** ISO 8601. */
+    started_at?: string;
+    /** ISO 8601. */
+    ended_at?: string;
+    /** The command, the path, the query — one short line. */
+    args_preview?: string;
+    /** One short line of what came back. */
+    result_summary?: string;
+    /** Why it failed, on `failed` only. */
+    error_summary?: string;
+}
 /** `POST` — exchange a one-time pairing code for a scoped credential. */
 export declare const REDEEM_PATH = "/v1/agent-pairing/redeem";
 /** `POST` — send a message into a conversation as the paired agent. */
@@ -148,6 +201,8 @@ export declare const MAX_ATTACHMENTS = 10;
  * quietly stop half-way through with nothing to explain it.
  */
 export declare const MAX_SYSTEM_PROMPT_CHARS = 20000;
+/** Ceiling on `trigger.brief` — the server's `MAX_TRIGGER_BRIEF_CHARS`. */
+export declare const MAX_TRIGGER_BRIEF_CHARS = 32000;
 /** The `agent.run_requested` payload, as far as the harness cares about it. */
 export interface AgentRunRequest {
     run_id: string;
@@ -188,6 +243,21 @@ export interface AgentRunRequest {
      */
     trigger_attachments?: RunAttachment[];
     trigger_user_id?: string;
+    /**
+     * The server's work order for this run, when it wrote one: a routine's
+     * instructions, a heartbeat's standing assignment, or — on a team-chat
+     * participant wakeup — the guidance for a message not addressed to the agent.
+     * Absent on older servers and on plain mentions.
+     */
+    trigger_brief?: string;
+    /**
+     * `false` when the message was NOT addressed to this agent: it was woken only
+     * because it is a member of the thread. Nobody is waiting on it, and the
+     * right answer is usually silence. `true` for everything else — including
+     * every event from a server that predates the field (parsed events always
+     * carry it; absent means `true`).
+     */
+    reply_expected?: boolean;
     /** For a trigger fan-out with no surface: the event type that fired it. */
     trigger_type?: string;
     /** For a trigger fan-out with no surface: the entity that event was about. */
@@ -231,6 +301,15 @@ export interface AgentRunRequest {
      * for what happens then.
      */
     heartbeat_path?: string;
+    /**
+     * Server-supplied path to report tool events at.
+     *
+     * Absent on every server built before the `events` block was added beside
+     * `heartbeat`. Unlike the heartbeat there is no fallback: with no path the
+     * events are simply not sent, and the run behaves exactly as it did before —
+     * the heartbeat line is the only narration.
+     */
+    events_path?: string;
     /**
      * Earlier messages on this surface, oldest first. Absent on a server that
      * predates the field — which is the case the harness shipped with, so an