privateer-agent 0.3.5 → 0.4.0

package/src/auth/privateer.ts

@@ -16,6 +16,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync }
 import { hostname, userInfo } from "node:os";
 import { globalDir, credentialsPath } from "../config/paths.ts";
 import { isAccountCapCode } from "../engine/errors.ts";
+import { terminalPublicKeyBase64 } from "../crypto/terminalKey.ts";
+import { pinAccountSignKey, clearAccountSignKey } from "../crypto/accountTrust.ts";
 
 // Default Privateer API host. NOTE: this is still the legacy "helix" Render
 // hostname the mobile/web client also points at (client/config/environment.ts);
@@ -97,14 +99,42 @@ let _child: ChildSession | null = null;
 let _spawnInFlight: Promise<ChildSession> | null = null;
 let _refreshInFlight: Promise<ChildSession> | null = null;
 
+// The most recent ACCOUNT-provider session (spawnAccountCredentials /
+// refreshAccountCredentials). Pi owns this credential's lifecycle — it drives the
+// account inference channel in the TUI — so it's a distinct server-side session
+// (device row) from _child. We record only its latest access token here so exit
+// cleanup / an explicit sign-out (revokeAccountSession) can kill it. Rotations
+// overwrite it; the previous token is already dead server-side, so tracking only
+// the latest is right.
+//
+// LIFECYCLE HAZARD: Pi PERSISTS this session to auth.json (with a ~24h `expires`) and
+// reuses it on the next launch, refreshing only when `Date.now() >= expires` — it does
+// NOT refresh reactively on a 401. So revoking it at exit while leaving the persisted
+// copy in place would let the next run send a token that still looks valid but is dead
+// server-side → inference fails with a dead-end `401 {code: SESSION_REVOKED}`.
+// The fix is to revoke it AND drop the persisted credential together: the caller must
+// remove the "privateer" entry from Pi's authStorage (authStorage.remove("privateer"))
+// right after revokeLocalSessions() so the next launch spawns a fresh session instead
+// of reusing the revoked one. Doing both is safe; doing only one is not. See
+// revokeLocalSessions and its callers (cli/chat.ts, daemon/index.ts).
+let _account: { accessToken: string } | null = null;
+
 export function loadCredentials(): Credentials | null {
-  if (_cache !== undefined) return _cache;
+  // Only a successfully-read credential is memoized. A NEGATIVE result (file absent
+  // or unreadable) is deliberately NOT cached: the credential can appear mid-session
+  // — the account /login writes credentials.json AFTER the extensions have already
+  // booted, and under jiti each extension gets its OWN module instance of this file,
+  // so a login's saveCredentials() never reaches another extension's `_cache`. If we
+  // memoized the pre-login "absent" as null, that instance would report "not signed
+  // in" forever (e.g. /remote-access refusing after a successful sign-in). Re-reading
+  // disk on each miss lets a later call see what a sign-in just wrote.
+  if (_cache) return _cache;
   const path = credentialsPath();
-  if (!existsSync(path)) return (_cache = null);
+  if (!existsSync(path)) return null;
   try {
     _cache = JSON.parse(readFileSync(path, "utf8")) as Credentials;
   } catch {
-    _cache = null;
+    return null;
   }
   return _cache;
 }
@@ -125,8 +155,12 @@ export function clearCredentials(): void {
   } catch {
     /* nothing to remove */
   }
+  // Drop the pinned account signing key too — it belongs to the account that just
+  // signed out; a different account must re-pin its own at link.
+  clearAccountSignKey();
   _cache = null;
   _child = null;
+  _account = null;
 }
 
 export function hasCredentials(): boolean {
@@ -171,6 +205,52 @@ function notifySessionExpired(): void {
   }
 }
 
+// A server-pushed `session_revoked` relay frame arrived: the account signed this
+// terminal out (from the app's Linked Devices). Treat it exactly like a lazily-
+// detected expiry — wipe the local machine login and announce it via
+// onSessionExpired — but PROMPTLY, while the process is live, instead of waiting
+// for the next authedFetch/launch to hit a 401. The relay owner additionally
+// drops remote access. No-op if we're already signed out, so a duplicate frame
+// (or a frame racing an in-flight /signout) doesn't fire a spurious notice.
+export function handleServerRevoke(): void {
+  if (!hasCredentials()) return;
+  clearCredentials();
+  notifySessionExpired();
+}
+
+// ── Sign-in notification ─────────────────────────────────────────────────────
+// Fired when a Privateer login completes on this terminal — the cue for the UI to
+// re-render its header/badge to the signed-in state. It reaches every sign-in entry
+// point:
+//   - our dedicated /signin command and a FRESH /login → "Use a subscription" OAuth
+//     login both run the device-code flow, which fires this from pollForToken once
+//     credentials are written; and
+//   - an ALREADY-LINKED machine selecting the subscription runs no device code (it
+//     just spawns an account session), so privateerOAuthProvider.login() fires this
+//     itself — otherwise that path had no hook back to the header and it kept showing
+//     the stale "not signed in" banner until the next launch.
+// A listener here refreshes the UI regardless of which path the user took.
+
+type SignedInListener = () => void;
+const _signedInListeners = new Set<SignedInListener>();
+
+export function onSignedIn(listener: SignedInListener): () => void {
+  _signedInListeners.add(listener);
+  return () => _signedInListeners.delete(listener);
+}
+
+// Emit the sign-in signal. Exported so the account OAuth provider can announce a
+// completed subscription login on the already-linked path (see the note above).
+export function notifySignedIn(): void {
+  for (const listener of _signedInListeners) {
+    try {
+      listener();
+    } catch {
+      /* a failing listener must not break the auth path */
+    }
+  }
+}
+
 // ── Device authorization flow ────────────────────────────────────────────────
 
 export interface DeviceCode {
@@ -197,7 +277,17 @@ async function postJson(base: string, path: string, body: unknown, init: Request
 // Step 1: ask the server for a device + user code the human will approve in-app.
 export async function requestDeviceCode(deviceLabel = defaultDeviceLabel()): Promise<DeviceCode> {
   const base = serverBaseUrl();
-  const res = await postJson(base, "/auth/device/code", { deviceLabel });
+  // This terminal's public key rides the grant so the app can PIN it on approval
+  // (TOFU) — the trust anchor for later sealing secrets (channel tokens) that only
+  // this machine can open. Best-effort: if keygen fails we just omit it and the app
+  // falls back to terminal-only secret entry rather than blocking login.
+  let terminalPub: string | undefined;
+  try {
+    terminalPub = terminalPublicKeyBase64();
+  } catch {
+    /* no key → no app-sealed secrets for this terminal; login still proceeds */
+  }
+  const res = await postJson(base, "/auth/device/code", { deviceLabel, terminalPub });
   if (!res.ok) {
     throw new Error(`Couldn't start login (${res.status}). Check your connection or PRIVATEER_SERVER_URL.`);
   }
@@ -226,9 +316,13 @@ export async function pollForToken(
     const res = await postJson(base, "/auth/device/token", { device_code: code.device_code });
 
     if (res.ok) {
-      const data = (await res.json()) as Omit<Credentials, "serverBaseUrl">;
-      const creds: Credentials = { ...data, serverBaseUrl: base };
+      const data = (await res.json()) as Omit<Credentials, "serverBaseUrl"> & { accountSignPub?: string };
+      const creds: Credentials = { accessToken: data.accessToken, refreshToken: data.refreshToken, user: data.user, serverBaseUrl: base };
       saveCredentials(creds);
+      // Pin the account's signing public key (TOFU) so channel-config from the app can
+      // be verified as genuinely coming from the account, not a forging relay (F7/F8).
+      pinAccountSignKey(data.accountSignPub);
+      notifySignedIn();
       return creds;
     }
 
@@ -409,23 +503,17 @@ export async function apiRequest(path: string, init: RequestInit = {}): Promise<
 }
 
 /**
- * Best-effort revoke of THIS terminal's child session on exit, so the terminal
- * disappears from the app's Linked Devices list immediately instead of
- * lingering until its access-token rows expire (24h server-side).
- *
- * Deliberately NOT authedFetch: that would spawn/refresh a session just to kill
- * it. If no child was ever spawned (e.g. BYO-key run), there's nothing to do.
- * Bounded by a short timeout — exit must never hang on a slow network — and all
- * failures are swallowed; the server's TTL remains the fallback.
+ * DELETE the server-side session identified by `accessToken` (RFC-style bearer
+ * possession proof). Deliberately a raw fetch, NOT authedFetch — authedFetch would
+ * spawn/refresh a brand-new session just to kill this one. Bounded by a short
+ * timeout so exit never hangs on a slow network, and all failures are swallowed;
+ * the server's TTL is the fallback.
  */
-export async function revokeChildSession(timeoutMs = 1500): Promise<void> {
-  const child = _child;
-  if (!child) return;
-  _child = null; // never reuse a session we've asked the server to revoke
+async function deleteSession(accessToken: string, timeoutMs: number): Promise<void> {
   try {
     await fetch(`${serverBaseUrl()}/auth/session/current`, {
       method: "DELETE",
-      headers: { Authorization: `Bearer ${child.accessToken}` },
+      headers: { Authorization: `Bearer ${accessToken}` },
       signal: AbortSignal.timeout(timeoutMs),
     });
   } catch {
@@ -433,6 +521,48 @@ export async function revokeChildSession(timeoutMs = 1500): Promise<void> {
   }
 }
 
+/**
+ * Best-effort revoke of THIS terminal's child session (from authedFetch/apiRequest).
+ * If no child was ever spawned (e.g. BYO-key run), there's nothing to do.
+ */
+export async function revokeChildSession(timeoutMs = 1500): Promise<void> {
+  const child = _child;
+  if (!child) return;
+  _child = null; // never reuse a session we've asked the server to revoke
+  await deleteSession(child.accessToken, timeoutMs);
+}
+
+/**
+ * Best-effort revoke of the account-provider session (the one Pi drives for account
+ * inference). Called both on EXPLICIT sign-out AND as part of exit cleanup (via
+ * revokeLocalSessions) — safe in the exit path ONLY because the caller also drops Pi's
+ * persisted copy (authStorage.remove("privateer")) so the next launch spawns fresh
+ * rather than reusing this now-dead token. See the _account note and revokeLocalSessions.
+ */
+export async function revokeAccountSession(timeoutMs = 1500): Promise<void> {
+  const account = _account;
+  if (!account) return;
+  _account = null;
+  await deleteSession(account.accessToken, timeoutMs);
+}
+
+/**
+ * Revoke ALL server-side sessions this terminal created — the in-memory child session
+ * (authedFetch/apiRequest) AND the account-provider inference session — so the terminal
+ * drops off the app's Linked Devices list the moment it exits (Ctrl+C, /quit, SIGTERM …)
+ * instead of lingering until its token TTL (~24h). Best-effort, time-bounded, and the
+ * two revokes run in parallel so a slow network can't double the exit delay.
+ *
+ * IMPORTANT: the account session is persisted by Pi (auth.json) and reused on the next
+ * launch without a reactive-on-401 refresh, so the caller MUST also drop the persisted
+ * copy right after this resolves — `authStorage.remove("privateer")` — or the next run
+ * will reuse the token we just revoked and dead-end on a 401 (see the _account note).
+ * Callers: cli/chat.ts cleanup() and daemon/index.ts shutdown().
+ */
+export async function revokeLocalSessions(timeoutMs = 1500): Promise<void> {
+  await Promise.all([revokeChildSession(timeoutMs), revokeAccountSession(timeoutMs)]);
+}
+
 // ── Logout ───────────────────────────────────────────────────────────────────
 
 /**
@@ -493,6 +623,7 @@ export async function spawnAccountCredentials(): Promise<AccountCredential> {
     throw new Error("Your Privateer session expired. Run /login to sign in again.");
   }
   const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
+  _account = { accessToken }; // track for explicit sign-out revoke (revokeAccountSession)
   return { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
 }
 
@@ -502,6 +633,7 @@ export async function refreshAccountCredentials(refresh: string): Promise<Accoun
   const res = await postJson(serverBaseUrl(), "/auth/refresh", { refreshToken: refresh });
   if (!res.ok) throw new Error(`account refresh failed (${res.status})`);
   const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
+  _account = { accessToken }; // the rotated session is the one an explicit sign-out revokes
   return { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
 }
 

package/src/channels/bridge.ts

@@ -0,0 +1,293 @@
+// The transport-agnostic core of the messaging channels — the analog of
+// RemoteBridge for the relay. It owns the policy that must be identical on every
+// platform:
+//   - allowlist    (who may drive the agent; fail-closed + silent to strangers)
+//   - serialization (one turn per conversation at a time; extra messages queue)
+//   - redaction     (chat platforms are external egress — scrub before send)
+//   - chunking      (respect the platform's per-message length cap)
+//
+// The agent itself is injected as `runTurn`, so this file stays Pi-free and
+// unit-testable against a fake adapter + fake runner (see tests/channels.test.ts).
+// The Pi-backed runner lives in ./run.ts.
+
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+// A minimal view of the permission request the gate hands us (see
+// src/permissions/gate.ts PermissionRequest). Kept local so the bridge doesn't
+// depend on the gate module.
+export interface ApprovalRequest {
+  kind: string;
+  title: string;
+  detail: string;
+}
+
+// Run one agent turn for a conversation. `onText` receives streamed text deltas as
+// they arrive; the bridge buffers/coalesces them. Resolves when the turn is done.
+// `signal` aborts a queued/in-flight turn (e.g. the user sent "/stop").
+export type TurnRunner = (
+  chatId: string,
+  text: string,
+  onText: (delta: string) => void,
+  signal: AbortSignal,
+  // The triggering user + their role, so the runner (and the gate it drives) can
+  // cap a member to read-only regardless of the channel's posture.
+  meta: TurnMeta,
+) => Promise<{ ok: boolean; error?: string }>;
+
+export interface TurnMeta {
+  userId: string;
+  isAdmin: boolean;
+}
+
+// A security-audit event. The bridge emits these at authorization-relevant moments;
+// run.ts appends them to an on-disk log. `detail` is redacted before it's emitted.
+export interface AuditEvent {
+  at: string;
+  event: "prompt" | "approval_request" | "approval_decision" | "interrupt" | "denied";
+  chatId: string;
+  userId?: string;
+  role?: "admin" | "member";
+  detail?: string;
+}
+
+export interface MessagingBridgeConfig {
+  adapter: ChannelAdapter;
+  runTurn: TurnRunner;
+  // Who may interact at all (admin OR member). False → ignored (fail-closed and
+  // SILENT: we don't confirm the bot exists to un-allowlisted senders).
+  isAllowed: (msg: InboundMessage) => boolean;
+  // Is this user an admin? Admins are governed by the channel posture and are the
+  // ONLY users whose yes/no resolves an approval. Members are read-only and can't
+  // approve.
+  isAdmin: (msg: InboundMessage) => boolean;
+  // Scrub secrets from every outbound message. Wired to redactText in ./run.ts.
+  redact?: (text: string) => string;
+  onLog?: (msg: string) => void;
+  // Optional append-only security audit sink.
+  onAudit?: (event: AuditEvent) => void;
+}
+
+// Stay comfortably under Telegram's 4096-char hard cap (Slack ~40k, Discord 2000 —
+// pick the tightest common bound for the shared path; a platform with a smaller cap
+// can override in its adapter later).
+const MAX_MSG = 1900;
+
+// How long to wait for a yes/no approval reply before failing closed (deny).
+const APPROVAL_TIMEOUT_MS = 120_000;
+
+const YES = new Set(["yes", "y", "allow", "ok", "okay", "approve", "approved", "👍", "✅"]);
+const NO = new Set(["no", "n", "deny", "denied", "stop", "cancel", "reject", "👎", "❌"]);
+
+// Interpret an approval reply. Returns null for anything that isn't a clear
+// yes/no, so the bridge can re-prompt instead of guessing (fail-safe: never treat
+// ambiguous text as allow).
+export function approvalDecision(text: string): "allow" | "deny" | null {
+  const t = text.trim().toLowerCase();
+  if (YES.has(t)) return "allow";
+  if (NO.has(t)) return "deny";
+  return null;
+}
+
+// The message a user sees when the agent wants to run a gated action.
+export function approvalPrompt(req: ApprovalRequest): string {
+  const detail = req.detail.length > 600 ? req.detail.slice(0, 600) + "\n…(truncated)" : req.detail;
+  return `⚠️ Approval needed — ${req.title} (${req.kind})\n\n${detail}\n\nReply "yes" to allow or "no" to deny (times out in 2 min).`;
+}
+
+// Split text into <=max chunks, preferring newline boundaries so code/paragraphs
+// aren't cut mid-line when possible.
+export function chunkText(text: string, max = MAX_MSG): string[] {
+  const out: string[] = [];
+  let rest = text;
+  while (rest.length > max) {
+    let cut = rest.lastIndexOf("\n", max);
+    if (cut < max * 0.5) cut = max; // no usable newline in the back half → hard cut
+    out.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n/, "");
+  }
+  if (rest) out.push(rest);
+  return out;
+}
+
+export class MessagingBridge {
+  // Per-chat promise tail: each new turn chains onto the previous so turns in the
+  // same conversation never interleave (they share one agent session downstream).
+  private readonly tails = new Map<string, Promise<void>>();
+  // Per-chat abort handle for the in-flight turn, so "/stop" can interrupt it.
+  private readonly aborts = new Map<string, AbortController>();
+  // Per-chat pending tool approval awaiting a yes/no reply. At most one at a time
+  // per chat (turns are serialized and a turn's tool calls are sequential).
+  private readonly approvals = new Map<string, (decision: "allow" | "deny") => void>();
+
+  constructor(private readonly cfg: MessagingBridgeConfig) {}
+
+  async start(): Promise<void> {
+    await this.cfg.adapter.start((m) => this.onMessage(m));
+    this.log(`channel "${this.cfg.adapter.name}" listening`);
+  }
+
+  stop(): void {
+    this.cfg.adapter.stop();
+    for (const a of this.aborts.values()) a.abort();
+    this.aborts.clear();
+    // Fail any pending approvals closed so no turn hangs on shutdown.
+    for (const resolve of this.approvals.values()) resolve("deny");
+    this.approvals.clear();
+  }
+
+  // Ask the user in `chatId` to approve a gated tool action, and await their yes/no
+  // reply. Wired to the permission gate's remote approver (see channels/run.ts): the
+  // gate suspends the tool until this resolves. Fail-closed — timeout, abort (/stop),
+  // or shutdown all resolve to "deny". Public because the gate calls it directly
+  // (via an AsyncLocalStorage handle to this bridge + the current chat id).
+  requestApproval(chatId: string, req: ApprovalRequest, signal?: AbortSignal): Promise<"allow" | "deny"> {
+    // Only one outstanding approval per chat; deny any stale one first.
+    this.approvals.get(chatId)?.("deny");
+
+    const prompt = approvalPrompt(req);
+    const detail = `${req.title}: ${req.detail}`;
+    this.cfg.onAudit?.({
+      at: new Date().toISOString(),
+      event: "approval_request",
+      chatId,
+      role: "admin", // approvals only arise from admin turns (members are read-only)
+      detail: this.cfg.redact ? this.cfg.redact(detail) : detail,
+    });
+    void this.cfg.adapter.sendText(chatId, this.cfg.redact ? this.cfg.redact(prompt) : prompt);
+
+    return new Promise<"allow" | "deny">((resolve) => {
+      let timer: ReturnType<typeof setTimeout>;
+      const settle = (decision: "allow" | "deny") => {
+        if (this.approvals.get(chatId) !== settle) return; // already settled
+        this.approvals.delete(chatId);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(decision);
+      };
+      const onAbort = () => {
+        void this.cfg.adapter.sendText(chatId, "🚫 request interrupted — denied.");
+        settle("deny");
+      };
+      timer = setTimeout(() => {
+        void this.cfg.adapter.sendText(chatId, "⌛ approval timed out — denied.");
+        settle("deny");
+      }, APPROVAL_TIMEOUT_MS);
+      this.approvals.set(chatId, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+
+  private log(msg: string): void {
+    this.cfg.onLog?.(msg);
+  }
+
+  private audit(m: InboundMessage, event: AuditEvent["event"], detail?: string): void {
+    if (!this.cfg.onAudit) return;
+    const red = detail && this.cfg.redact ? this.cfg.redact(detail) : detail;
+    this.cfg.onAudit({
+      at: new Date().toISOString(),
+      event,
+      chatId: m.chatId,
+      userId: m.userId,
+      role: this.cfg.isAdmin(m) ? "admin" : "member",
+      detail: red,
+    });
+  }
+
+  private onMessage(m: InboundMessage): void {
+    const text = m.text?.trim();
+    if (!text) return;
+
+    if (!this.cfg.isAllowed(m)) {
+      // Fail closed and stay silent — replying would confirm the bot to strangers.
+      this.log(`ignored message from unauthorized user ${m.userId} in chat ${m.chatId}`);
+      return;
+    }
+
+    // A pending tool approval in this chat consumes the next message as its answer —
+    // BEFORE the per-chat queue, because the turn awaiting approval is itself holding
+    // that queue open (routing the reply through the queue would deadlock it).
+    const pending = this.approvals.get(m.chatId);
+    if (pending) {
+      // Only admins may answer an approval. A member's reply is refused (and audited)
+      // — never silently treated as a decision.
+      if (!this.cfg.isAdmin(m)) {
+        this.audit(m, "denied", "non-admin attempted to answer an approval");
+        void this.cfg.adapter.sendText(m.chatId, "Only an admin can approve the pending action.");
+        return;
+      }
+      if (text === "/stop") {
+        this.audit(m, "approval_decision", "deny (/stop)");
+        pending("deny"); // interrupt while awaiting approval → deny it
+        return;
+      }
+      const decision = approvalDecision(text);
+      if (decision === null) {
+        void this.cfg.adapter.sendText(m.chatId, 'Reply "yes" to allow or "no" to deny the pending action.');
+        return;
+      }
+      this.audit(m, "approval_decision", decision);
+      pending(decision);
+      return;
+    }
+
+    // "/stop" interrupts the running turn instead of queueing another.
+    if (text === "/stop") {
+      this.aborts.get(m.chatId)?.abort();
+      return;
+    }
+
+    // Serialize per conversation: chain onto this chat's tail.
+    const prev = this.tails.get(m.chatId) ?? Promise.resolve();
+    const next = prev
+      .then(() => this.handle(m))
+      .catch((e) => this.log(`turn error: ${e instanceof Error ? e.message : String(e)}`));
+    this.tails.set(m.chatId, next);
+    // Drop the tail once this was the last queued turn, so the map doesn't grow.
+    void next.finally(() => {
+      if (this.tails.get(m.chatId) === next) this.tails.delete(m.chatId);
+    });
+  }
+
+  private async handle(m: InboundMessage): Promise<void> {
+    const { chatId } = m;
+    const isAdmin = this.cfg.isAdmin(m);
+    this.audit(m, "prompt", m.text.trim().slice(0, 200));
+    const ac = new AbortController();
+    this.aborts.set(chatId, ac);
+    this.cfg.adapter.sendTyping?.(chatId);
+
+    // Buffer the whole turn's text, then send once (coalesced) — the simplest
+    // correct choice. Streaming partial edits back to the channel is a future
+    // enhancement; buffering avoids a race between deltas and async sends and
+    // keeps this unit-testable without timers.
+    let buf = "";
+    let result: { ok: boolean; error?: string };
+    try {
+      result = await this.cfg.runTurn(chatId, m.text.trim(), (d) => (buf += d), ac.signal, {
+        userId: m.userId,
+        isAdmin,
+      });
+    } catch (e) {
+      result = { ok: false, error: e instanceof Error ? e.message : String(e) };
+    } finally {
+      this.aborts.delete(chatId);
+    }
+
+    const body = this.cfg.redact ? this.cfg.redact(buf) : buf;
+
+    // Deliver any text the turn produced (even on error — a partial answer is
+    // useful), then an error line if it failed.
+    if (body.trim()) {
+      for (const chunk of chunkText(body)) await this.cfg.adapter.sendText(chatId, chunk);
+    } else if (result.ok) {
+      await this.cfg.adapter.sendText(chatId, "✓ done (no text output).");
+    }
+    if (!result.ok) {
+      await this.cfg.adapter.sendText(chatId, `⚠️ ${result.error ?? "the agent hit an error"}`);
+    }
+  }
+}