hilos-agent 0.9.4 → 0.10.0

package/README.md

@@ -53,7 +53,9 @@ Running from elsewhere, or want to map several repos explicitly? Use a config:
   "defaultBranch": "main",
   "gate": false,               // default: open a PR directly. true = approve-before-push
   "heartbeatMs": 180000,       // long runs post one "still working…" thread reply this often (0 = off, min 15s)
-  "chatTimeoutMs": 90000       // cap a chat reply / plan-ack so a stalled model can't go silent
+  "chatTimeoutMs": 90000,      // cap a chat reply / plan-ack so a stalled model can't go silent
+  "longPollMs": 20000,         // ask the server to HOLD the mention poll and answer the moment work lands (0 = plain 5s polling; older servers fall back automatically)
+  "catchupMs": 86400000        // how far back a restart replays mentions from the persisted cursor (default 24h; 0 = restart at "now", the pre-0866 behavior)
 }
 ```
 
@@ -68,7 +70,11 @@ to a short "done" line. A run that **times out or errors** says so honestly (wit
 a stderr tail) instead of claiming "no changes". Chat replies use the faster
 `chatCmd` (when unset, derived from `codingCmd`'s tool — a Claude daemon chats
 with Haiku, a Codex daemon with `codex exec`, and so on) bounded by
-`chatTimeoutMs`. The responsive surface needs a hilos server new enough to expose
+`chatTimeoutMs`. The chat-vs-code pass only classifies; the separate chat
+responder keeps the CLI's normal tools. Generated Codex chat and code commands
+explicitly enable its built-in web search (an explicit operator override still
+wins), while other vendors keep their own tool configuration. The responsive
+surface needs a hilos server new enough to expose
 `edit_message`; older servers just skip the live edits.
 
 ```sh
@@ -76,6 +82,45 @@ hilos-agent          # watch every channel the agent is in
 hilos-agent --channel <id>   # scope to one channel
 ```
 
+## WebMCP site tools
+
+The local daemon can give its coding and chat agents a narrow bridge to
+third-party WebMCP sites. It is off until you name exact origins and exact read
+tools in the machine's config:
+
+```jsonc
+{
+  "webMcp": {
+    "origins": {
+      "https://docs.example.com": {
+        "readTools": ["search_docs", "read_reference"]
+      }
+    }
+  }
+}
+```
+
+The site does not authorize itself: `readOnlyHint` is informational, while this
+person-owned list decides what may run. Site descriptions are omitted, schema
+prose is stripped, results are bounded and labeled untrusted, and cookies stay
+inside a separate browser profile. The bundled browser bridge currently needs
+Node.js 24 or newer; the rest of the daemon keeps its existing Node.js support.
+
+```sh
+hilos-agent webmcp doctor
+hilos-agent webmcp login https://docs.example.com  # person signs in in the opened browser
+hilos-agent webmcp open https://docs.example.com/reference
+hilos-agent webmcp tools
+hilos-agent webmcp call search_docs '{"query":"WebMCP"}'
+hilos-agent webmcp close
+```
+
+The daemon adds this capability and its citation rules to agent prompts only
+when the config is valid. Unlisted tools — including writes — are refused with
+`human_approval_required`; there is no approval flag the agent can set. WebMCP
+can never approve or merge hilos work. See the complete contract in
+[WebMCP in hilos](https://hilos.sh/docs/webmcp).
+
 ## How it works
 
 - **Trigger** — an `@mention` of your agent in a channel that's linked to a repo,

package/bin/hilos-agent.mjs

@@ -7,6 +7,7 @@
 //   hilos-agent --join <blob>      connect with a copy-paste link from hilos
 //   hilos-agent --join-stdin       read a private link without exposing it in argv
 //   hilos-agent init               write a starter config (~/.hilos/agent.json)
+//   hilos-agent webmcp doctor      verify the local site-tool bridge
 //   hilos-agent                    run with the resolved config (default)
 //   hilos-agent run                same as above, explicit
 //
@@ -24,6 +25,7 @@ import { resolveConfig, decodeJoin, writeStarterConfig, GLOBAL_CONFIG } from "..
 import { readPrivateJoin } from "../src/join-input.mjs";
 import { run } from "../src/run.mjs";
 import { hookMain, hooksMain } from "../src/hook.mjs";
+import { runWebMcpCommand } from "../src/webmcp-bridge.mjs";
 
 function packageVersion() {
   const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
@@ -67,6 +69,12 @@ const HELP = `hilos-agent — your coding agent as a teammate in hilos
   hilos-agent --join <blob>      connect using a link copied from hilos
   hilos-agent --join-stdin       paste the private link at a no-echo prompt
   hilos-agent init               write a starter config to ~/.hilos/agent.json
+  hilos-agent webmcp doctor      verify the local WebMCP browser bridge
+  hilos-agent webmcp login <url> open the isolated profile for person sign-in
+  hilos-agent webmcp open <url>  open a person-allowlisted site for an agent
+  hilos-agent webmcp tools       list registered, person-allowlisted read tools
+  hilos-agent webmcp call <name> '<json object>'
+  hilos-agent webmcp close       close the isolated browser session
   hilos-agent                    run the daemon (watch @mentions, propose diffs)
   hilos-agent hooks install      stream this repo's Codex, Claude, and Cursor
                                  sessions to hilos and continue replies in the same
@@ -150,6 +158,17 @@ async function main() {
     return;
   }
 
+  if (cmd === "webmcp") {
+    const cliFlags = { ...flags };
+    delete cliFlags.help;
+    const cfg = resolveConfig({ flags: cliFlags });
+    const operation = positional[1] || "doctor";
+    const result = await runWebMcpCommand(cfg, operation, positional.slice(2));
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
   // run (default) — when --join is passed without init, connect straight away.
   const cliFlags = { ...flags };
   delete cliFlags.join;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Run your own coding agent (Claude Code / Codex / Cursor) as an autonomous teammate in a hilos channel. Picks up @mentions in channels and threads, makes the change, and opens a PR for review — your code and credentials never leave your machine. (Approve-before-push is available via gate:true.)",
   "type": "module",
   "bin": {
@@ -32,5 +32,8 @@
     "cursor",
     "coding-agent"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "agent-browser": "^0.35.0"
+  }
 }

package/src/codex-mcp-session.mjs

@@ -461,6 +461,10 @@ export async function runCodexMcpSession({
             cwd,
             "approval-policy": approvalPolicy,
             sandbox,
+            // The gated transport cannot inherit `codex exec` argv. Carry the
+            // same public web-search capability through the MCP tool's config;
+            // permission policy and sandboxing remain unchanged.
+            config: { tools: { web_search: true } },
             ...(model ? { model } : {}),
           },
         };

package/src/config.mjs

@@ -53,6 +53,12 @@ const DEFAULTS = {
   // and preview (default) vs production. Shape:
   // { "<channelId>": { provider: "vercel" | "netlify", prod: false } }.
   deploy: {},
+  // Local WebMCP consumer (0959). Disabled until the person names exact site
+  // origins and exact read-only tools. A site's readOnlyHint is never an
+  // authorization signal. Shape:
+  // { origins: { "https://example.com": { readTools: ["search_docs"] } },
+  //   profile?: "/absolute/private/browser/profile" }
+  webMcp: null,
   // acceptEdits lets the CLI make file edits without prompting (bias to action);
   // it still won't run arbitrary commands. Override in hilos-agent.json if you
   // want a stricter (or `--dangerously-skip-permissions`) command.
@@ -121,6 +127,17 @@ const DEFAULTS = {
   gate: false,
   maxRounds: 3,
   pollMs: 5000,
+  // Long-poll (0866): when the server supports it, list_mentions is asked to
+  // HOLD this many ms and answer the moment a mention lands — pickup latency
+  // stops being pollMs. 0 disables and falls back to plain pollMs polling.
+  // The server caps a hold at 25s regardless of what is asked for here.
+  longPollMs: 20000,
+  // How far back a restart may replay missed mentions from the persisted
+  // cursor (0866). A daemon that was off for a week should not open a week of
+  // stale branches; a day covers the overnight-laptop case the cursor exists
+  // for. 0 disables catch-up entirely (restart starts at "now", the old
+  // behavior).
+  catchupMs: 24 * 60 * 60 * 1000,
   // On a long code run, post ONE thread progress reply at the first beat then
   // edit it on later beats, so a human sees the agent is alive without thread
   // spam. 0 disables. Clamped to >=15s so a misconfig can't spam realtime
@@ -224,6 +241,8 @@ const LIVE_FIELDS = [
   "gate",
   "maxRounds",
   "pollMs",
+  "longPollMs",
+  "catchupMs",
   "runTimeoutMs",
   "decisionTimeoutMs",
   "decisionPollMs",
@@ -238,6 +257,7 @@ const LIVE_FIELDS = [
   // like `repos`, so a partial edit doesn't drop the defaults.
   "folders",
   "deploy",
+  "webMcp",
 ];
 
 /**
@@ -280,6 +300,10 @@ export function reloadConfig(prev) {
   // the normal on state. An explicit launch flag remains pinned when the file
   // was never changed, preserving the 0576 precedence rule above.
   if (changed("replyBridge")) next.replyBridge = file.replyBridge !== false;
+  // WebMCP is an authorization allowlist. Removing it must revoke the browser
+  // bridge on the next poll rather than preserving stale origins/tools until a
+  // restart. An explicit null and a deleted edited key both mean disabled.
+  if (changed("webMcp")) next.webMcp = file.webMcp ?? null;
   // The environment stays the operator's override on reload, in both
   // directions — a machine that opted out with =0 must not be opted back in by
   // a file edit (0792).

package/src/cursor-store.mjs

@@ -0,0 +1,76 @@
+// Durable mention cursor (0866).
+//
+// The poll loop's cursor and dedupe set lived only in memory, so a daemon
+// restart began at "now" and every mention that arrived while it was down was
+// silently skipped (backfill:false, the default). This file is the fix's whole
+// mechanism: the cursor is persisted per agent after each delivery, and a
+// restart resumes from it — bounded by `catchupMs`, because replaying a week of
+// stale asks after a vacation would be worse than skipping them.
+//
+// Telegram semantics, deliberately: persisting the cursor acknowledges
+// DELIVERY into the daemon's queue, not completion of the work. A crash after
+// enqueue can still lose an in-flight task (exactly as today); what can no
+// longer happen is a mention arriving into a dead daemon and never being seen.
+//
+// Dependency-free and injectable-dir like hook.mjs's state store, so tests run
+// against a temp dir and never touch a real ~/.hilos.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Same parent as ~/.hilos/agent.json (config.mjs) and state.json (resume.mjs). */
+export const CURSOR_STATE_DIR = join(homedir(), ".hilos", "mention-cursors");
+
+/** One file per agent — two agents on one machine must never share a cursor. */
+export function cursorPath(agentId, dir = CURSOR_STATE_DIR) {
+  return join(dir, `${String(agentId).replace(/[^a-zA-Z0-9-]/g, "")}.json`);
+}
+
+/**
+ * The cursor a restart should resume from, or null when there is nothing
+ * usable — no file, unreadable JSON, a malformed timestamp, or a cursor older
+ * than `catchupMs` allows (clamped to the window's edge rather than dropped,
+ * so a long-dead daemon still catches the most recent day, not nothing).
+ *
+ * @param {string} agentId
+ * @param {{ catchupMs?: number, dir?: string, now?: () => number }} [opts]
+ * @returns {string|null} ISO timestamp
+ */
+export function loadMentionCursor(agentId, { catchupMs = 0, dir = CURSOR_STATE_DIR, now = Date.now } = {}) {
+  if (!agentId || !(catchupMs > 0)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(cursorPath(agentId, dir), "utf8"));
+  } catch {
+    return null;
+  }
+  const value = parsed && typeof parsed.mentionCursor === "string" ? parsed.mentionCursor : null;
+  if (!value) return null;
+  const at = new Date(value).getTime();
+  if (Number.isNaN(at)) return null;
+  const floor = now() - catchupMs;
+  return at < floor ? new Date(floor).toISOString() : value;
+}
+
+/**
+ * Persist the cursor after a delivery. Best-effort by design: a full disk or
+ * read-only home must never take the poll loop down — the daemon just degrades
+ * to today's restart-at-now behavior.
+ *
+ * @param {string} agentId
+ * @param {string} isoTimestamp
+ * @param {{ dir?: string, log?: { error?: (m: string) => void } }} [opts]
+ * @returns {boolean} whether the write landed
+ */
+export function saveMentionCursor(agentId, isoTimestamp, { dir = CURSOR_STATE_DIR, log } = {}) {
+  if (!agentId || typeof isoTimestamp !== "string" || !isoTimestamp) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(cursorPath(agentId, dir), JSON.stringify({ mentionCursor: isoTimestamp }));
+    return true;
+  } catch (e) {
+    log?.error?.(`mention cursor not persisted: ${e?.message || e}`);
+    return false;
+  }
+}

package/src/daemon.mjs

@@ -1,6 +1,13 @@
 // Pure daemon helpers — no I/O. (Mirror of the app's scripts/lib/daemon.mjs so
 // the package stands alone; keep them equivalent.)
 
+import {
+  agentCoauthorTrailer,
+  agentCommitBody,
+  githubArtifactBody,
+  selectGithubArtifactTitle,
+} from "./github-artifacts.mjs";
+
 /** Branch name from a task: `hilos/<kebab-first-words>-<suffix>`. */
 export function branchSlug(text, suffix) {
   const base =
@@ -121,18 +128,33 @@ export function decisionKind(report) {
 }
 
 /** Commit message for an approved proposal. */
-export function commitMessage(task) {
-  const first = String(task || "").split("\n")[0].slice(0, 72) || "hilos change";
-  return `${first}\n\nProposed via hilos and approved by a human reviewer.`;
+/** @param {unknown} task @param {Record<string, any>} [provenance] */
+export function commitMessage(task, provenance = {}) {
+  const title = selectGithubArtifactTitle({
+    summary: provenance.summary,
+    originalTask: task,
+    fallback: "hilos change",
+  });
+  const trailer = agentCoauthorTrailer(provenance.agentName, provenance.agentId);
+  // The agent's own account of the change becomes the commit body, so the log
+  // says what shipped and not only that a person approved it.
+  const body = agentCommitBody(provenance.summary);
+  return [title, body, "Proposed via hilos and approved by a person.", trailer]
+    .filter(Boolean)
+    .join("\n\n");
 }
 
-/** PR title + body for an approved proposal. */
-export function prTitleBody(task, branch) {
-  const title = String(task || "").split("\n")[0].slice(0, 72) || branch;
-  const body =
-    "Proposed by a hilos agent from a channel request, approved by a human reviewer.\n\n" +
-    `Task: ${String(task || "").trim()}`;
-  return { title, body };
+/** PR title + body for an approved proposal. The body carries the agent's own
+ *  description of the change (from `provenance.summary`) above the provenance
+ *  block, so a reviewer on GitHub reads what shipped before who proposed it. */
+/** @param {unknown} task @param {string} branch @param {Record<string, any>} [provenance] */
+export function prTitleBody(task, branch, provenance = {}) {
+  const title = selectGithubArtifactTitle({
+    summary: provenance.summary,
+    originalTask: task,
+    fallback: branch,
+  });
+  return { title, body: githubArtifactBody(provenance) };
 }
 
 /** Build the post_report payload that serves as the approval card. */

package/src/github-artifacts.mjs

@@ -0,0 +1,253 @@
+const TITLE_MAX = 72;
+// A pull-request description is a reviewer's first read, not an essay: enough
+// room for the agent's own account of the change, bounded so a runaway summary
+// can never become the PR body. The commit log gets a shorter form still.
+const DESCRIPTION_MAX = 1400;
+const COMMIT_BODY_MAX = 600;
+
+const REJECTED_TITLE_LINES = [
+  /^(?:sure|okay|ok|yes|got it|sounds good|absolutely|certainly|done|working on it)\b/i,
+  /^(?:i(?:'ll| will| have|’ll)|let me|here(?:'s| is))\b/i,
+  /^(?:address|apply|handle|incorporate|respond to|update)\b.{0,36}\b(?:feedback|review|comments?|pr)\b/i,
+  /^@\S+/,
+  /https?:\/\//i,
+  /^```/,
+  /^visual_?preview\s*:/i,
+];
+
+function oneLine(value, max = 160) {
+  return String(value ?? "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, max);
+}
+
+function cleanTitleLine(value) {
+  return oneLine(value)
+    .replace(/^#{1,6}\s+/, "")
+    .replace(/^[-*+]\s+/, "")
+    .replace(/^\d+[.)]\s+/, "")
+    .replace(/^(?:(?:pr|pull request|commit)\s+)?title\s*[:\-–—]\s*/i, "")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/[*_~]/g, "")
+    .replace(/^@[a-z0-9][a-z0-9-]*\s*[:,–—-]?\s*/i, "")
+    .replace(/[.\s]+$/, "")
+    .trim();
+}
+
+function candidateLines(value) {
+  return String(value ?? "")
+    .split(/\r?\n/)
+    .map(cleanTitleLine)
+    .filter(Boolean);
+}
+
+function usableTitle(line) {
+  if (line.length < 4) return false;
+  return !REJECTED_TITLE_LINES.some((pattern) => pattern.test(line));
+}
+
+function truncateTitle(title) {
+  if (title.length <= TITLE_MAX) return title;
+  return `${title.slice(0, TITLE_MAX - 1).trimEnd()}…`;
+}
+
+/**
+ * The title the agent wrote for its OWN change, or null when its summary never
+ * offered a usable one. Callers that must always end up with something use
+ * `selectGithubArtifactTitle` (which falls back to the request text); callers
+ * that need to know whether the agent actually authored a headline — an
+ * iteration commit deciding between the agent's words and a canned subject —
+ * use this.
+ */
+/** @param {unknown} summary */
+export function agentAuthoredTitle(summary) {
+  const line = candidateLines(summary).find(usableTitle);
+  return line ? truncateTitle(line) : null;
+}
+
+/**
+ * One title selector for hosted and local-daemon GitHub output. Agent summaries
+ * win only when they actually describe a change; acknowledgements, mentions,
+ * Markdown wrappers, links, and review-process chatter are rejected. Iteration
+ * callers keep their existing PR title and use this only for the new commit.
+ */
+/** @param {{ summary?: unknown, originalTask?: unknown, fallback?: string }} [input] */
+export function selectGithubArtifactTitle({ summary, originalTask, fallback = "Update" } = {}) {
+  const summaryTitle = agentAuthoredTitle(summary);
+  const taskTitle = candidateLines(originalTask)
+    .map((line) => line.replace(/@[a-z0-9][a-z0-9-]*/gi, "").trim())
+    .find(usableTitle);
+  return truncateTitle(summaryTitle || taskTitle || cleanTitleLine(fallback) || "Update");
+}
+
+/**
+ * Neutralize the two things in agent prose that would ACT on GitHub instead of
+ * describing the change: HTML comment delimiters (which could otherwise forge
+ * or break the provenance marker this body ends with) and @handles (which ping
+ * whatever unrelated GitHub account happens to own that name). Everything else
+ * — including code fences — is the agent's writing and survives intact.
+ */
+function defuseMarkup(line) {
+  return line
+    .replace(/<!--+/g, "")
+    .replace(/--+>/g, "")
+    .replace(/(^|[\s(\[])@([a-z0-9][a-z0-9-]{0,38})/gi, "$1$2");
+}
+
+/** Drop fenced code blocks — a commit log is not the place for a snippet. */
+function stripFences(text) {
+  return String(text ?? "").replace(/^\s*```[\s\S]*?^\s*```\s*$/gm, "");
+}
+
+/** Trim leading/trailing blank lines and collapse blank runs to one. */
+function tidyLines(lines) {
+  const out = [];
+  for (const line of lines) {
+    const value = line.replace(/\s+$/, "");
+    if (!value.trim() && (!out.length || !out[out.length - 1].trim())) continue;
+    out.push(value);
+  }
+  while (out.length && !out[out.length - 1].trim()) out.pop();
+  return out;
+}
+
+/** Keep whole lines up to `max` characters, marking a cut rather than hiding it. */
+function clampLines(lines, max) {
+  const kept = [];
+  let used = 0;
+  for (const line of lines) {
+    const next = used + line.length + 1;
+    if (next > max) {
+      kept.push("…");
+      break;
+    }
+    kept.push(line);
+    used = next;
+  }
+  return tidyLines(kept).join("\n").trim();
+}
+
+/**
+ * The agent's own account of the change, ready to be a pull-request
+ * description: its summary MINUS the headline it leads with (that becomes the
+ * title, and a PR should not open by repeating its own title) and minus the
+ * machine directives it ends with (`VISUAL_PREVIEW:`), sanitized and bounded on
+ * whole lines.
+ *
+ * Returns "" when the agent wrote nothing past a title — the caller then ships
+ * provenance alone rather than inventing prose it cannot stand behind.
+ */
+/** @param {unknown} summary @param {{ max?: number }} [options] */
+export function agentChangeDescription(summary, { max = DESCRIPTION_MAX } = {}) {
+  const lines = String(summary ?? "")
+    .replace(/\r\n?/g, "\n")
+    .split("\n");
+  const headline = lines.findIndex((line) => usableTitle(cleanTitleLine(line)));
+  const body = (headline === -1 ? lines : lines.slice(headline + 1))
+    .filter((line) => !/^\s*visual_?preview\s*:/i.test(line))
+    .map(defuseMarkup);
+  return clampLines(tidyLines(body), max);
+}
+
+/** The same account of the change, shortened and de-fenced for a commit body. */
+/** @param {unknown} summary */
+export function agentCommitBody(summary) {
+  return agentChangeDescription(stripFences(summary), { max: COMMIT_BODY_MAX });
+}
+
+function safeLabel(value, fallback) {
+  const label = oneLine(value, 80)
+    .replace(/[<>`[\]{}*_]/g, "")
+    .replace(/https?:\/\/\S+/gi, "")
+    .trim();
+  return label || fallback;
+}
+
+function safeId(value) {
+  const id = oneLine(value, 100);
+  return /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,99}$/.test(id) ? id : null;
+}
+
+function safeHilosUrl(value) {
+  try {
+    const url = new URL(String(value ?? ""));
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    url.username = "";
+    url.password = "";
+    // Room and message links use their query/hash to identify the exact place
+    // a request came from. Keep that stable context after removing credentials.
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+function linkLine(label, url, fallback) {
+  return url ? `- ${label}: [Open in hilos](${url})` : `- ${label}: ${fallback}`;
+}
+
+/**
+ * A bounded PR body: the agent's own description of the change on top, then the
+ * provenance block. It still deliberately never accepts task text — the raw
+ * chat message is not a description of what shipped — but it does accept the
+ * agent's `summary`, which is the one piece of writing on this path that was
+ * actually authored about the diff.
+ */
+/**
+ * @param {{ agentName?: unknown, personName?: unknown, roomName?: unknown,
+ * roomUrl?: unknown, messageId?: unknown, messageUrl?: unknown, runId?: unknown,
+ * reportId?: unknown, partial?: boolean, summary?: unknown }} [input]
+ */
+export function githubArtifactBody(input = {}) {
+  const agent = safeLabel(input.agentName, "hilos agent");
+  const person = safeLabel(input.personName, "a team member");
+  const room = safeLabel(input.roomName, "project room");
+  const roomUrl = safeHilosUrl(input.roomUrl);
+  const messageUrl = safeHilosUrl(input.messageUrl);
+  const runId = safeId(input.runId);
+  const reportId = safeId(input.reportId);
+  const partial = input.partial === true;
+  const machine = {
+    version: 1,
+    agent,
+    person,
+    room,
+    messageId: safeId(input.messageId),
+    runId,
+    reportId,
+  };
+  const partialNote = partial
+    ? "\nThis is a partial run. Mention the agent in the room to continue."
+    : "";
+
+  // The agent's account of the change leads, because that is what a reviewer
+  // opens the pull request to read. Provenance follows it under a rule.
+  const description = agentChangeDescription(input.summary);
+
+  return [
+    ...(description ? [description, "", "---", ""] : []),
+    `Proposed by **${agent}** for **${person}** in **${room}**. A person remains the creator of record and decides whether to merge.`,
+    "",
+    linkLine("Room", roomUrl, room),
+    linkLine("Request", messageUrl, machine.messageId ? `message \`${machine.messageId}\`` : "room request"),
+    `- Run: ${runId ? `\`${runId}\`` : "not recorded"}`,
+    `- Report: ${reportId ? `\`${reportId}\`` : "posted in the room after this pull request opens"}`,
+    partialNote,
+    "",
+    `<!-- hilos-provenance ${JSON.stringify(machine).replace(/--/g, "—")} -->`,
+  ]
+    .filter((line, index, all) => line !== "" || index === 1 || all[index - 1] !== "")
+    .join("\n")
+    .trim();
+}
+
+/** A stable Git co-author trailer for the named agent, without user input. */
+/** @param {unknown} agentName @param {unknown} agentId */
+export function agentCoauthorTrailer(agentName, agentId) {
+  const name = safeLabel(agentName, "hilos agent");
+  const id = safeId(agentId)?.replace(/[^a-zA-Z0-9]/g, "").slice(0, 48) || "agent";
+  return `Co-authored-by: ${name} <agent+${id}@hilos.sh>`;
+}