@prohost/cli 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.8.0
+
+A paired agent woken as a bystander can now stay silent.
+
+- **`reply_expected: false`.** When a team-chat message lands in a thread the
+  agent belongs to but is addressed to someone else (ProhostAI's participation
+  walk), the run event now says so. The prompt tells the agent the message was
+  not addressed to it and nobody is waiting on it — instead of "someone is
+  waiting on a reply" — and renders the server's `trigger.brief`, the same
+  bystander guidance ProhostAI's in-product agents get. Absent (every older
+  server) keeps today's prompt.
+- **`[NO_REPLY]`.** An agent whose whole answer is `[NO_REPLY]` (any case,
+  surrounding whitespace ignored) posts nothing, and the run is completed
+  `{status: "succeeded", outcome: "silent"}` so ProhostAI records a deliberate
+  silence and clears the thinking indicator as one. Checked on every run, so
+  the literal token can never reach a thread. A server that predates `outcome`
+  ignores it and records a plain success.
+- **`trigger.brief` is rendered** whenever the server sends one that is not just
+  the message restated — a work order used to be dropped on any run that also
+  had a message.
+
 ## 0.7.0
 
 Machines, accounts and agents: a paired AI employee now runs on a named

package/README.md

@@ -117,6 +117,10 @@ nothing is posted and the run is left open.
 4. Your command's **stdout** is the reply. It's posted into the conversation
    verbatim, so print the message and nothing else — no preamble, no reasoning.
    (Claude Code and Codex are the exceptions: see below.)
+   To reply with nothing, print exactly `[NO_REPLY]`: nothing is posted and the
+   run is completed as a deliberate silence. That is the expected answer when
+   your agent is woken only because it is in a thread where someone else was
+   addressed — the prompt says so when that is the case.
 5. The run is completed either way. A command that crashes, times out, or prints
    nothing reports `failed`; a run is never left hanging.
 

package/dist/agent/api.d.ts

@@ -136,6 +136,7 @@ export declare function heartbeatRun(options: ApiOptions, path: string, progress
  */
 export declare function completeRun(options: ApiOptions, path: string, outcome: {
     ok: true;
+    silent?: boolean;
 } | {
     ok: false;
     error: string;

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_STATUS_FAILED, RUN_STATUS_SUCCEEDED, } from './contract.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';
 /** Deadline for the cheap calls — a heartbeat answers in milliseconds. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 /**
@@ -176,7 +176,7 @@ export async function heartbeatRun(options, path, progress) {
  */
 export async function completeRun(options, path, outcome, model) {
     const body = outcome.ok
-        ? { status: RUN_STATUS_SUCCEEDED }
+        ? { status: RUN_STATUS_SUCCEEDED, ...(outcome.silent ? { outcome: RUN_OUTCOME_SILENT } : {}) }
         : { status: RUN_STATUS_FAILED, error: outcome.error.slice(0, MAX_ERROR_CHARS) };
     if (model)
         body.model = model.slice(0, MAX_MODEL_CHARS);

package/dist/agent/contract.d.ts

@@ -28,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`). */
@@ -180,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;
@@ -220,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. */

package/dist/agent/contract.js

@@ -28,6 +28,29 @@ export const EVENT_MESSAGE_TEAM_CHAT = 'message.team_chat';
 /** Terminal statuses accepted by the run-completion endpoint. */
 export const RUN_STATUS_SUCCEEDED = 'succeeded';
 export 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 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 const NO_REPLY_TOKEN = '[NO_REPLY]';
+/** Whether the agent's output is the no-reply token and nothing else. */
+export function isNoReply(output) {
+    return output.trim().toUpperCase() === NO_REPLY_TOKEN;
+}
 /** 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`). */
@@ -125,6 +148,8 @@ export const MAX_ATTACHMENTS = 10;
  * quietly stop half-way through with nothing to explain it.
  */
 export const MAX_SYSTEM_PROMPT_CHARS = 20_000;
+/** Ceiling on `trigger.brief` — the server's `MAX_TRIGGER_BRIEF_CHARS`. */
+export const MAX_TRIGGER_BRIEF_CHARS = 32_000;
 /**
  * Fallback for a server that predates `reply_instructions.body_field`.
  *
@@ -229,6 +254,16 @@ function systemPrompt(value) {
         return undefined;
     return text.length > MAX_SYSTEM_PROMPT_CHARS ? text.slice(0, MAX_SYSTEM_PROMPT_CHARS) : text;
 }
+/**
+ * Bound the server's work order. Same backstop as {@link systemPrompt}, at the
+ * server's own ceiling for the field (`MAX_TRIGGER_BRIEF_CHARS`).
+ */
+function brief(value) {
+    const text = str(value);
+    if (!text)
+        return undefined;
+    return text.length > MAX_TRIGGER_BRIEF_CHARS ? text.slice(0, MAX_TRIGGER_BRIEF_CHARS) : text;
+}
 function parseMessage(entry) {
     const attachments = attachmentList(entry.attachments);
     // Not `str()`: an image-only message carries an empty string here and is a
@@ -304,6 +339,11 @@ export function parseRunRequest(data) {
         trigger_text: str(trigger.text_excerpt),
         trigger_attachments: attachmentList(trigger.attachments ?? data.trigger_attachments),
         trigger_user_id: str(trigger.user_id),
+        trigger_brief: brief(trigger.brief),
+        // Only an explicit `false` opts out. Absent, null, or anything malformed
+        // keeps today's behaviour — an agent that stays quiet when it was asked
+        // something is a worse failure than one that answers an aside.
+        reply_expected: data.reply_expected !== false,
         trigger_type: str(trigger.type),
         trigger_entity_id: str(trigger.entity_id),
         reply_surface: surface,

package/dist/agent/prompt.js

@@ -6,6 +6,7 @@
  * a shell script that greps it. The reply contract is stated explicitly so an
  * agent that would otherwise narrate its reasoning returns something sendable.
  */
+import { NO_REPLY_TOKEN } from './contract.js';
 /**
  * Say the run's budget in a unit a reader thinks in.
  *
@@ -129,15 +130,23 @@ export function buildPrompt(run, context) {
     const name = run.agent_name ?? context.agentName;
     const canReply = Boolean(run.reply_surface !== 'none' && run.reply_path && run.reply_body_key);
     const title = run.agent_title ? ` (${run.agent_title})` : '';
+    // Woken as a bystander: a message landed in a thread the agent belongs to,
+    // addressed to somebody else. Telling it "someone is waiting on a reply"
+    // here is what made a paired agent post a long, unrequested summary onto a
+    // message that @-mentioned three people — so the opening says the opposite.
+    const bystander = canReply && run.reply_expected === false;
     const lines = [
         `You are "${name}"${title}, an AI teammate in a ProhostAI workspace.`,
-        canReply && run.reply_surface === 'conversation'
-            ? 'You were mentioned in a conversation and someone is waiting on a reply.'
-            : run.reply_surface === 'none'
-                ? 'You have been given work to do. There is nowhere to reply.'
-                : canReply
-                    ? `You were mentioned on a ${run.reply_surface} and someone is waiting on a reply.`
-                    : `You have been given work on a ${run.reply_surface}. There is nowhere to post a reply.`,
+        bystander
+            ? `A new message was posted in a ${run.reply_surface} you are a member of. It was not ` +
+                'addressed to you, and nobody is waiting on a reply from you.'
+            : canReply && run.reply_surface === 'conversation'
+                ? 'You were mentioned in a conversation and someone is waiting on a reply.'
+                : run.reply_surface === 'none'
+                    ? 'You have been given work to do. There is nowhere to reply.'
+                    : canReply
+                        ? `You were mentioned on a ${run.reply_surface} and someone is waiting on a reply.`
+                        : `You have been given work on a ${run.reply_surface}. There is nowhere to post a reply.`,
         '',
     ];
     // The operator's own configuration comes first, above everything the server
@@ -187,6 +196,12 @@ export function buildPrompt(run, context) {
     if (run.recent_messages?.length) {
         lines.push('Conversation so far (oldest first):', ...run.recent_messages.map(renderMessage), '--- end of conversation history ---', '');
     }
+    // The server's own work order, when it wrote one that is not simply the
+    // message restated (a run with no message of its own already received the
+    // brief as its excerpt).
+    if (run.trigger_brief && run.trigger_brief !== run.trigger_text) {
+        lines.push('Your instructions for this run, from ProhostAI:', run.trigger_brief, '');
+    }
     const triggerAttachments = run.trigger_attachments ?? [];
     if (run.trigger_text) {
         // The server caps this excerpt, so say so rather than let an agent assume
@@ -305,6 +320,13 @@ export function buildPrompt(run, context) {
     // Postability is a separate question from what the run is about: a task run
     // has no comment route in the external API yet, so the agent must be told its
     // output won't be posted rather than left to assume it will.
+    if (bystander) {
+        // Silence is stated as the default and given a concrete spelling, because
+        // "reply only if useful" without a way to NOT reply still ends in stdout
+        // that gets posted.
+        lines.push('Staying silent is the expected outcome here. Reply only if you can add', 'something clearly distinct that nobody else in the thread was asked for. If', `you decide not to reply, output ONLY the token ${NO_REPLY_TOKEN} — nothing is`, 'posted and the run is recorded as a deliberate silence. Never write a message', 'explaining that you are staying quiet.', 'If you do reply, write the message text only — no preamble, no explanation of', `your reasoning, no surrounding quotes. Anything other than ${NO_REPLY_TOKEN} is`, `posted verbatim as your reply on the ${run.reply_surface}.`);
+        return `${lines.join('\n')}\n`;
+    }
     lines.push(canReply
         ? 'Write your reply to that message. Reply with the message text only — no'
         : 'Summarize what you did, in one short message. Output the message only — no', 'preamble, no explanation of your reasoning, no surrounding quotes. Your', canReply

package/dist/agent/run.js

@@ -33,7 +33,7 @@ import { APPS_FEATURE, MCP_API_KEY_ENV_VAR, PLUGINS_DISABLED_OVERRIDE, codexBina
 import { ToolEventQueue } from './events.js';
 import { EXTRA_MCP_FILENAME, loadExtraMcpServers } from './extras.js';
 import { MCP_SERVER_NAME, MCP_TOOL_PATTERN } from './mcp.js';
-import { EVENT_AGENT_RUN_REQUESTED, EVENT_MENTION_CREATED, EVENT_MESSAGE_TEAM_CHAT, RUN_ERROR_CANCELLED_BY_USER, eventData, heartbeatPathFor, parseRunRequest, } from './contract.js';
+import { EVENT_AGENT_RUN_REQUESTED, EVENT_MENTION_CREATED, EVENT_MESSAGE_TEAM_CHAT, RUN_ERROR_CANCELLED_BY_USER, eventData, heartbeatPathFor, isNoReply, parseRunRequest, } from './contract.js';
 import { ensureWorkspace, streamUrlFor, workspacePath } from './credentials.js';
 import { execAgent } from './exec.js';
 import { HeartbeatLoop } from './heartbeat.js';
@@ -927,6 +927,23 @@ async function handleRun(run, options, runtime, api, log, sleep, control) {
         log(`    [dry-run] nothing was sent and the run was left open`);
         return 'skipped';
     }
+    // The agent decided not to reply — the usual answer when it was woken as a
+    // bystander (`reply_expected: false`). A finished run, not a failure: nothing
+    // is posted, and the completion says so, so the server records a deliberate
+    // silence and clears the thinking indicator as one. Checked on every run, not
+    // only bystander ones: the literal token must never reach a thread.
+    if (isNoReply(reply)) {
+        log(`${timestamp()} ✓ ${label} chose not to reply (${seconds}s)`);
+        const completed = await completeWithRetry(api, run.completion_path, { ok: true, silent: true }, log, sleep, runtime.model());
+        if (!completed.ok) {
+            log(`    ! could not mark the run complete (${describeFailure(completed)})`);
+            return 'unreported';
+        }
+        if (result.sessionId) {
+            runtime.sessions.remember(sessionKeyFor(run), result.sessionId);
+        }
+        return 'succeeded';
+    }
     // A run with no reply surface is a legitimate outcome, not an error: it was
     // started by a trigger rather than by someone addressing the agent, so there
     // is nowhere to post. Complete it as succeeded so any thinking indicator

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.7.0";
+export declare const CLI_VERSION = "0.8.0";
 /** Sent on every HTTP request the CLI makes back into ProhostAI. */
-export declare const USER_AGENT = "prohost-cli/0.7.0";
+export declare const USER_AGENT = "prohost-cli/0.8.0";

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.7.0';
+export const CLI_VERSION = '0.8.0';
 /** 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.7.0",
+  "version": "0.8.0",
   "description": "Run your own AI agent as a ProhostAI teammate, and stream your account's webhooks to your laptop.",
   "type": "module",
   "license": "MIT",