agent-relay-sdk 0.2.16 → 0.2.18

package/src/context-probe.ts

@@ -6,7 +6,7 @@ import type { ContextProbeMetrics } from "./types.js";
 import { sanitizeFsName } from "./fs-name.js";
 import { isRecord, stringValue } from "./types.js";
 
-export interface ContextProbeOptions {
+interface ContextProbeOptions {
   wrapCommand?: string;
   agentId?: string;
   stateDir?: string;
@@ -16,13 +16,13 @@ export interface ContextProbeOptions {
   parsePatterns?: ParsePattern[];
 }
 
-export interface ParsePattern {
+interface ParsePattern {
   name: string;
   regex: RegExp;
   extract(match: RegExpMatchArray): Partial<ContextProbeMetrics>;
 }
 
-export interface ContextProbeRunResult {
+interface ContextProbeRunResult {
   metrics: ContextProbeMetrics | null;
   stateFile?: string;
   wrappedExitCode?: number;
@@ -31,9 +31,15 @@ export interface ContextProbeRunResult {
   output: string;
 }
 
-export const DEFAULT_CONTEXT_PROBE_STATE_DIR = tmpdir();
+// Lazy on purpose: calling tmpdir() at module top level made the whole SDK
+// barrel browser-hostile — a bare-barrel import crashed the dashboard because
+// node:os.tmpdir is undefined in the browser (#281). A function defers the
+// node-only call to runtime, so importing this module never executes it.
+function defaultContextProbeStateDir(): string {
+  return tmpdir();
+}
 
-export const DEFAULT_CONTEXT_PROBE_PATTERNS: ParsePattern[] = [
+const DEFAULT_CONTEXT_PROBE_PATTERNS: ParsePattern[] = [
   {
     name: "percent",
     regex: /(\d+(?:\.\d+)?)%\s*(?:context|ctx)?/i,
@@ -54,7 +60,7 @@ export const DEFAULT_CONTEXT_PROBE_PATTERNS: ParsePattern[] = [
   },
 ];
 
-export function contextProbeStatePath(agentId: string, stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR): string {
+export function contextProbeStatePath(agentId: string, stateDir = defaultContextProbeStateDir()): string {
   return join(stateDir, `agent-relay-context-${safeStateId(agentId)}.json`);
 }
 
@@ -104,7 +110,7 @@ export function contextStateFromProbeMetrics(metrics: ContextProbeMetrics) {
   };
 }
 
-export function writeContextProbeState(metrics: ContextProbeMetrics, stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR): string {
+function writeContextProbeState(metrics: ContextProbeMetrics, stateDir = defaultContextProbeStateDir()): string {
   const file = contextProbeStatePath(metrics.agentId, stateDir);
   mkdirSync(dirname(file), { recursive: true });
   const tmp = `${file}.${process.pid}.tmp`;
@@ -113,7 +119,7 @@ export function writeContextProbeState(metrics: ContextProbeMetrics, stateDir =
   return file;
 }
 
-export function readContextProbeState(agentId: string, stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR): ContextProbeMetrics | null {
+export function readContextProbeState(agentId: string, stateDir = defaultContextProbeStateDir()): ContextProbeMetrics | null {
   try {
     const parsed = JSON.parse(readFileSync(contextProbeStatePath(agentId, stateDir), "utf8")) as unknown;
     return isContextProbeMetrics(parsed) ? parsed : null;

package/src/fs-name.ts

@@ -7,7 +7,7 @@
 //
 // Allowed characters (everything else is replaced): a-z A-Z 0-9 . _ -
 
-export interface SanitizeFsNameOptions {
+interface SanitizeFsNameOptions {
   /** Truncate the result to this many chars. Omit for no truncation. */
   maxLen?: number;
   /** Character substituted for disallowed input. Default "_". */
@@ -37,11 +37,14 @@ export function sanitizeFsName(value: string, opts: SanitizeFsNameOptions = {}):
   if (opts.collapseReplacement) {
     s = s.replace(new RegExp(`${escapeRe(repl)}+`, "g"), repl);
   }
+  if (opts.lowercase) s = s.toLowerCase();
+  if (opts.maxLen !== undefined) s = s.slice(0, opts.maxLen);
+  // Edge-trim AFTER truncating: a maxLen cut that lands on a replacement char
+  // (e.g. a UUID sliced mid-segment) would otherwise leave a dangling separator
+  // — the "branch ref severed at `…b7e1-`" bug (#282).
   if (opts.trimEdge) {
     const e = escapeRe(repl);
     s = s.replace(new RegExp(`^(?:${e})+|(?:${e})+$`, "g"), "");
   }
-  if (opts.lowercase) s = s.toLowerCase();
-  if (opts.maxLen !== undefined) s = s.slice(0, opts.maxLen);
   return s || opts.fallback || "";
 }

package/src/http-client.ts

@@ -1,20 +1,20 @@
 import type { AgentCard, Artifact, ArtifactKind, ArtifactSensitivity, PollQuery, RegisterAgentInput, SendMessageInput, Message, MessageDeliveryState, MessageDeliveryStatus, ReplyObligation, Task, TaskStatusInput } from "./types.js";
 import { RELAY_TOKEN_HEADER } from "./contracts.js";
 
-export interface HttpClientOptions {
+interface HttpClientOptions {
   baseUrl: string;
   token?: string;
   timeout?: number;
 }
 
-export interface TransportOptions {
+interface TransportOptions {
   /** External abort signal, combined (AbortSignal.any) with the internal timeout. */
   signal?: AbortSignal;
   /** Override the default request timeout (ms). `null` disables it — for streaming (SSE). */
   timeoutMs?: number | null;
 }
 
-export class RelayHttpError extends Error {
+class RelayHttpError extends Error {
   constructor(
     readonly method: string,
     readonly path: string,

package/src/process-utils.ts

@@ -15,7 +15,7 @@ export function parseProcStateIsZombie(statusText: string): boolean {
 }
 
 /** True iff <pid> exists and its /proc state is zombie. Non-Linux → false. */
-export function isZombie(pid: number): boolean {
+function isZombie(pid: number): boolean {
   try {
     return parseProcStateIsZombie(readFileSync(`/proc/${pid}/status`, "utf8"));
   } catch {

package/src/protocol.ts

@@ -24,7 +24,7 @@ export interface RegisterFrame extends BusFrame {
   };
 }
 
-export interface HeartbeatFrame extends BusFrame {
+interface HeartbeatFrame extends BusFrame {
   type: "heartbeat";
   payload: {
     status: Exclude<BusAgentStatus, "offline">;
@@ -32,7 +32,7 @@ export interface HeartbeatFrame extends BusFrame {
   };
 }
 
-export interface CommandFrame extends BusFrame {
+interface CommandFrame extends BusFrame {
   type: "command";
   id: string;
   payload: {
@@ -42,7 +42,7 @@ export interface CommandFrame extends BusFrame {
   };
 }
 
-export interface SubscribeFrame extends BusFrame {
+interface SubscribeFrame extends BusFrame {
   type: "subscribe";
   id: string;
   payload: {
@@ -51,7 +51,7 @@ export interface SubscribeFrame extends BusFrame {
   };
 }
 
-export interface StatusFrame extends BusFrame {
+interface StatusFrame extends BusFrame {
   type: "status";
   payload: {
     agentStatus: BusAgentStatus;
@@ -60,14 +60,14 @@ export interface StatusFrame extends BusFrame {
   };
 }
 
-export interface AckFrame extends BusFrame {
+interface AckFrame extends BusFrame {
   type: "ack";
   payload: {
     frameId: string;
   };
 }
 
-export interface ResumeFrame extends BusFrame {
+interface ResumeFrame extends BusFrame {
   type: "resume";
   id: string;
   payload: {
@@ -87,7 +87,7 @@ export interface RegisteredFrame extends BusFrame {
   };
 }
 
-export interface EventPayload {
+interface EventPayload {
   seq: number;
   eventType: string;
   source: string;
@@ -102,7 +102,7 @@ export interface EventFrame extends BusFrame {
   payload: EventPayload;
 }
 
-export interface CommandResultFrame extends BusFrame {
+interface CommandResultFrame extends BusFrame {
   type: "command.result";
   payload: {
     commandId: string;
@@ -118,7 +118,7 @@ export interface CommandStatusUpdateParams {
   error?: string;
 }
 
-export interface ResumedFrame extends BusFrame {
+interface ResumedFrame extends BusFrame {
   type: "resumed";
   payload: {
     events: EventPayload[];
@@ -136,7 +136,7 @@ export interface ErrorFrame extends BusFrame {
   };
 }
 
-export type ClientBusFrame =
+type ClientBusFrame =
   | RegisterFrame
   | HeartbeatFrame
   | CommandFrame
@@ -162,13 +162,13 @@ export class BusProtocolError extends Error {
   }
 }
 
-export function isRegisterFrame(f: BusFrame): f is RegisterFrame { return f.type === "register"; }
-export function isHeartbeatFrame(f: BusFrame): f is HeartbeatFrame { return f.type === "heartbeat"; }
-export function isCommandFrame(f: BusFrame): f is CommandFrame { return f.type === "command"; }
-export function isSubscribeFrame(f: BusFrame): f is SubscribeFrame { return f.type === "subscribe"; }
-export function isStatusFrame(f: BusFrame): f is StatusFrame { return f.type === "status"; }
-export function isAckFrame(f: BusFrame): f is AckFrame { return f.type === "ack"; }
-export function isResumeFrame(f: BusFrame): f is ResumeFrame { return f.type === "resume"; }
+function isRegisterFrame(f: BusFrame): f is RegisterFrame { return f.type === "register"; }
+function isHeartbeatFrame(f: BusFrame): f is HeartbeatFrame { return f.type === "heartbeat"; }
+function isCommandFrame(f: BusFrame): f is CommandFrame { return f.type === "command"; }
+function isSubscribeFrame(f: BusFrame): f is SubscribeFrame { return f.type === "subscribe"; }
+function isStatusFrame(f: BusFrame): f is StatusFrame { return f.type === "status"; }
+function isAckFrame(f: BusFrame): f is AckFrame { return f.type === "ack"; }
+function isResumeFrame(f: BusFrame): f is ResumeFrame { return f.type === "resume"; }
 
 export function parseBusFrame(data: string | ArrayBuffer | Uint8Array): BusFrame {
   const text = typeof data === "string" ? data : new TextDecoder().decode(data);

package/src/provider-base.ts

@@ -11,7 +11,7 @@ export interface ProviderAdapter {
   formatDelivery?(messages: Message[]): string;
 }
 
-export interface SpawnConfig {
+interface SpawnConfig {
   cwd: string;
   label?: string;
   approvalMode?: string;
@@ -19,13 +19,13 @@ export interface SpawnConfig {
   env?: Record<string, string>;
 }
 
-export interface SpawnResult {
+interface SpawnResult {
   agentId: string;
   pid?: number;
   sessionId?: string;
 }
 
-export interface ProviderBaseOptions {
+interface ProviderBaseOptions {
   relayUrl: string;
   adapter: ProviderAdapter;
   agentId: string;
@@ -36,7 +36,7 @@ export interface ProviderBaseOptions {
   token?: string;
 }
 
-export class ProviderBase {
+class ProviderBase {
   readonly client: RelayBusClient;
   private running = false;
   private readonly pending = new Map<number, Message>();

package/src/provider-catalog.ts

@@ -3,25 +3,25 @@ import type { SpawnProvider } from "./types.js";
 /** Valid reasoning-effort levels — runtime tuple is the single source of truth. */
 export const VALID_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 export type ProviderEffort = (typeof VALID_EFFORTS)[number];
-export function isProviderEffort(value: unknown): value is ProviderEffort {
+function isProviderEffort(value: unknown): value is ProviderEffort {
   return typeof value === "string" && (VALID_EFFORTS as readonly string[]).includes(value);
 }
-export type ProviderCatalogValueSource = "catalog" | "provider" | "runtime" | "override";
-export type ProviderCatalogConfidence = "declared" | "verified" | "estimated" | "unknown";
+type ProviderCatalogValueSource = "catalog" | "provider" | "runtime" | "override";
+type ProviderCatalogConfidence = "declared" | "verified" | "estimated" | "unknown";
 
-export interface ProviderCatalogValue<T> {
+interface ProviderCatalogValue<T> {
   value: T;
   source: ProviderCatalogValueSource;
   confidence: ProviderCatalogConfidence;
   lastUpdatedAt?: number;
 }
 
-export interface ProviderModelLimits {
+interface ProviderModelLimits {
   contextWindowTokens?: ProviderCatalogValue<number>;
   maxOutputTokens?: ProviderCatalogValue<number>;
 }
 
-export interface ProviderModelModalities {
+interface ProviderModelModalities {
   input: {
     text: boolean;
     image?: boolean;
@@ -37,7 +37,7 @@ export interface ProviderModelModalities {
   };
 }
 
-export interface ProviderModelToolCapabilities {
+interface ProviderModelToolCapabilities {
   code?: boolean;
   review?: boolean;
   debug?: boolean;
@@ -50,7 +50,7 @@ export interface ProviderModelToolCapabilities {
   imageEditing?: boolean;
 }
 
-export interface ProviderModelCapabilities {
+interface ProviderModelCapabilities {
   modalities: ProviderModelModalities;
   tools?: ProviderModelToolCapabilities;
   source: ProviderCatalogValueSource;
@@ -75,13 +75,13 @@ export interface ProviderCatalogEntry {
   models: ProviderModelCatalogEntry[];
 }
 
-export interface ProviderSelection {
+interface ProviderSelection {
   provider: SpawnProvider;
   model?: string;
   effort?: ProviderEffort;
 }
 
-export interface ResolvedProviderSelection {
+interface ResolvedProviderSelection {
   provider: SpawnProvider;
   modelAlias?: string;
   providerModel?: string;

package/src/reconnect.ts

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-export interface ReconnectOptions {
+interface ReconnectOptions {
   initialMs: number;
   maxMs: number;
   jitterMs: number;

package/src/speech-text.ts

@@ -111,7 +111,7 @@ function collapseTables(text: string): string {
  * by appending an entry. Order matters: earlier rules see the raw text, later
  * rules see the output of earlier ones (see the ordering notes in SPEECH_RULES).
  */
-export interface SpeechRule {
+interface SpeechRule {
   readonly name: string
   readonly pattern: RegExp
   readonly replace: string | ((substring: string, ...args: string[]) => string)
@@ -131,13 +131,33 @@ function spaceDigits(frac: string): string {
   return frac.split('').join(' ')
 }
 
+/**
+ * Spell a token one character at a time so the engine reads each symbol on its
+ * own: digits stay as digits, letters are upper-cased so they're heard as the
+ * letter name ("e" → "E" = "ee") rather than a syllable. Used for commit hashes
+ * ("834543e" → "8 3 4 5 4 3 E") and acronyms ("id" → "I D").
+ */
+function spellOut(token: string): string {
+  return token
+    .split('')
+    .map((c) => (/[0-9]/.test(c) ? c : c.toUpperCase()))
+    .join(' ')
+}
+
 /**
  * Ordered normalization rules. ORDER IS LOAD-BEARING:
  *  - URLs/paths first, before anything mangles their slashes/dots.
  *  - `~` → "approximately" before number rules consume the digits after it.
  *  - number ranges ("5-7") before unit expansion, so the unit attaches once: "5 to 7 seconds".
+ *  - versions ("0.27.0") before decimals, so all dots become "dot" uniformly
+ *    instead of the decimal rule eating only the first pair and stranding ".0".
  *  - decimals before unit expansion and before the sentence splitter sees the dot.
- *  - unit expansion last among the number rules.
+ *  - commit-hash spelling before nothing in particular, but after decimals so a
+ *    real number is never mistaken for a hash.
+ *  - "id" acronym expansion (camelCase suffix before the standalone word).
+ *  - unit expansion among the number rules.
+ *  - interior-dot LAST, so it only mops up dots the structured rules left behind
+ *    (identifiers like "branch.landed", "router.ts") — never a decimal or version.
  */
 export const SPEECH_RULES: readonly SpeechRule[] = [
   // Bare URLs read character-by-character → say "link".
@@ -148,14 +168,46 @@ export const SPEECH_RULES: readonly SpeechRule[] = [
     pattern: /(?:\/[A-Za-z0-9._-]+){2,}\/?/g,
     replace: (m) => ' ' + m.replace(/[/._-]+/g, ' ').trim() + ' ',
   },
+  // A lone slash between words ("src/router.ts", "TCP/IP") → a space, so the
+  // engine doesn't read "slash". Absolute multi-segment paths are already gone.
+  { name: 'slash', pattern: /(?<=[A-Za-z0-9])\/(?=[A-Za-z0-9])/g, replace: ' ' },
   // Empty-paren code identifiers ("fetchSpeech()") → drop the parens.
   { name: 'func-call', pattern: /\b([A-Za-z_$][\w$]*)\(\)/g, replace: '$1' },
   // Approximation tilde ("~0.1", "~5") → "approximately".
   { name: 'approx', pattern: /~(?=\s*[\d.])/g, replace: 'approximately ' },
   // Numeric ranges ("5-7", "100–200") → "X to Y".
   { name: 'range', pattern: /(\d)\s*[-–—]\s*(?=\d)/g, replace: '$1 to ' },
+  // Dotted versions ("0.27.0", "v1.2.3", IPs) → every dot spoken as "dot".
+  // Runs BEFORE decimal so 3+-part versions don't get half-eaten into "point".
+  // A leading v/V is voiced as "version" (unambiguous here — v then digits then ≥2 dots).
+  {
+    name: 'version',
+    pattern: /\b(v?)(\d+(?:\.\d+){2,})\b/gi,
+    replace: (_m, v: string, nums: string) =>
+      `${v ? 'version ' : ''}${nums.replace(/\./g, ' dot ')}`,
+  },
   // Decimals ("0.1", "3.14") → "0 point 1" so the sentence splitter keeps them whole.
   { name: 'decimal', pattern: /\b(\d+)\.(\d+)\b/g, replace: (_m, i: string, f: string) => `${i} point ${spaceDigits(f)}` },
+  // Commit hashes ("834543e", "3e0c66f85bd5") → spell each char so the engine
+  // doesn't read them as one giant number. Heuristic: 7–40 hex chars containing
+  // BOTH a letter and a digit — excludes plain numbers and plain words.
+  {
+    name: 'hash',
+    pattern: /\b(?=[0-9a-f]{7,40}\b)(?=[0-9a-f]*[a-f])(?=[0-9a-f]*\d)[0-9a-f]{7,40}\b/gi,
+    replace: (m: string) => spellOut(m),
+  },
+  // camelCase "Id" suffix ("messageId", "threadIds") → "message I D", "thread I Ds".
+  {
+    name: 'id-camel',
+    pattern: /([a-z])(Id|ID)(s)?\b/g,
+    replace: (_m, pre: string, _acr: string, plural: string) => `${pre} I D${plural ? 's' : ''}`,
+  },
+  // Standalone "id"/"Id"/"ID" word → "I D" (so it's not read as "iiid").
+  {
+    name: 'id-word',
+    pattern: /\b(?:id|Id|ID)(s)?\b/g,
+    replace: (_m, plural: string) => `I D${plural ? 's' : ''}`,
+  },
   // Byte units ("165KB", "2 MB") → spelled out (case-insensitive).
   {
     name: 'byte-unit',
@@ -165,6 +217,21 @@ export const SPEECH_RULES: readonly SpeechRule[] = [
   // Time units ("500ms", "5s") → spelled out. Guard against 4-digit years for "s".
   { name: 'ms-unit', pattern: /\b(\d{1,5})\s?ms\b/g, replace: (_m, n: string) => `${n} ${UNIT_WORDS.ms}` },
   { name: 's-unit', pattern: /\b(\d{1,3})\s?s\b/g, replace: (_m, n: string) => `${n} ${UNIT_WORDS.s}` },
+  // Heteronym "live": the engine defaults to the verb /lɪv/ ("I want to live"),
+  // but in deployment chatter it's the adjective /laɪv/ ("the version is live").
+  // Respell → "lyve" ONLY after a high-confidence adjective cue, so the verb is
+  // never touched. NOTE: heteronym sense can't be fully disambiguated by regex —
+  // this deliberately covers only the predicate/"go live" phrasings agents use.
+  {
+    name: 'live-adjective',
+    pattern:
+      /\b(is|are|was|were|be|been|being|now|and|stays?|staying|went|go|goes|going|deployed|it's|that's|here's|there's|we're|you're|they're)\s+live\b/gi,
+    replace: (_m, cue: string) => `${cue} lyve`,
+  },
+  // Interior dot — any dot glued directly to a following alphanumeric ("branch.landed",
+  // "router.ts", "Node.js") → " dot ". Runs LAST: real sentence-ending dots (followed by
+  // a space or end-of-string) are untouched, and versions/decimals were already consumed.
+  { name: 'interior-dot', pattern: /\.(?=[A-Za-z0-9])/g, replace: ' dot ' },
 ]
 
 /**

package/src/sse.ts

@@ -3,7 +3,7 @@
 // (voice connector). One home for the `event:`/`data:`/`retry:` field parse
 // that was hand-rolled in connectors/voice and dashboard/src/lib/api.ts.
 
-export interface ParsedSseFrame {
+interface ParsedSseFrame {
   /** Event name; defaults to "message" per the SSE spec when no `event:` field. */
   event: string;
   /** Each `data:` line, in order. Join with "\n" to reconstruct the payload. */

package/src/types.ts

@@ -26,8 +26,8 @@ export interface AgentCard {
 
 export type AgentStatus = "online" | "idle" | "busy" | "stale" | "offline";
 
-export type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
-export type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
+type CapabilitySource = "catalog" | "provider" | "runtime" | "override" | "estimate";
+type CapabilityConfidence = "declared" | "reported" | "verified" | "estimated" | "unknown";
 
 export interface ProviderCapabilities {
   lifecycle: {
@@ -99,7 +99,7 @@ export interface ProviderCapabilities {
   lastUpdatedAt: number;
 }
 
-export type ContextLifecycleState =
+type ContextLifecycleState =
   | "fresh"
   | "primed"
   | "working"
@@ -249,7 +249,7 @@ export interface ContextBudget {
   priorityCutoff: 1 | 2 | 3;
 }
 
-export interface TaskHistorySummary {
+interface TaskHistorySummary {
   taskId: number;
   agentId: string;
   status: string;
@@ -303,7 +303,7 @@ export interface MemoryBrokerContext {
 
 export type MemoryBrokerKind = "sqlite" | "http" | "command";
 
-export interface SqliteMemoryBrokerConfig {
+interface SqliteMemoryBrokerConfig {
   type: "sqlite";
 }
 
@@ -332,17 +332,44 @@ export type MessageKind =
   | "system"
   | "session";
 
+/**
+ * Mechanical message kinds: the relay's own lifecycle/observability lane, not
+ * agent-directed messaging. They bypass delivery resolution (never re-delivered
+ * into a session) and — when targeting a reserved sink — the recipient-constraint
+ * auth check (a managed token's `targets`/`policies`/`agents` constraints gate which
+ * *agents* it may message, not a session-mirror capture to the reserved sink; #284).
+ * Keep in sync with the `MessageKind` union.
+ */
+export const MECHANICAL_MESSAGE_KINDS: readonly MessageKind[] = ["system", "control", "session"];
+
+export function isMechanicalMessageKind(kind: string | undefined): boolean {
+  return MECHANICAL_MESSAGE_KINDS.includes((kind ?? "") as MessageKind);
+}
+
+/**
+ * Reserved built-in identities that are not real agents: the `user` chat/mirror sink
+ * and the `system` lifecycle sender. They are never registered, polled, or delivered to
+ * like agents, so recipient constraints don't apply to mechanical posts addressed to them.
+ */
+export const RESERVED_AGENT_IDS: readonly string[] = ["user", "system"];
+
+export function isReservedAgentId(id: string | undefined): boolean {
+  return id === "user" || id === "system";
+}
+
 /**
  * Session-mirror event taxonomy. Every `kind: "session"` message carries a
  * `payload.session` of this shape so the dashboard can render the live provider
  * session faithfully regardless of which surface (chat box or web terminal)
- * started the turn. `prompt`/`response` render as chat bubbles; `reasoning`,
- * `tool`, and `notice` render discreetly (collapsed activity, never bubbles).
+ * started the turn. `prompt`/`response` render as chat bubbles; `narration` is
+ * the agent's intermediate spoken text between tool calls (the terminal's `●`
+ * lines) and renders inline in the turn's activity trace; `reasoning`, `tool`,
+ * and `notice` render discreetly (collapsed/inline activity, never bubbles).
  * A legacy session message with no `payload.session` is treated as a `response`.
  */
-export type SessionEventType = "prompt" | "response" | "reasoning" | "tool" | "notice";
+type SessionEventType = "prompt" | "response" | "narration" | "reasoning" | "tool" | "notice";
 
-export type SessionEventOrigin = "chat" | "terminal" | "provider";
+type SessionEventOrigin = "chat" | "terminal" | "provider";
 
 export interface MessageSessionMeta {
   type: SessionEventType;
@@ -435,6 +462,10 @@ export interface Message {
   body: string;
   threadId?: number;
   replyTo?: number;
+  // Server-owned reply obligation (#283). Absent/true = the message wants a response (default);
+  // false = a notification (FYI, merge notice, lifecycle event) that must NOT be replied to.
+  // The server keys footer rendering and the reply-obligation tracker off this, not off `from`.
+  replyExpected?: boolean;
   claimable?: boolean;
   claimedBy?: string;
   claimedAt?: number;
@@ -538,6 +569,9 @@ export interface SendMessageInput {
   subject?: string;
   body: string;
   replyTo?: number;
+  // Defaults to true server-side. Set false to mark a notification (no reply wanted) — the
+  // server suppresses the reply-scaffold footer and appends a one-line no-reply nudge (#283).
+  replyExpected?: boolean;
   claimable?: boolean;
   idempotencyKey?: string;
   maxAgeSeconds?: number;
@@ -1141,14 +1175,14 @@ export type OrchestratorStatus = "online" | "offline";
 /** Spawn providers — the runtime tuple is the single source of truth; the type derives from it. */
 export const SPAWN_PROVIDERS = ["claude", "codex"] as const;
 export type SpawnProvider = (typeof SPAWN_PROVIDERS)[number];
-export function isSpawnProvider(value: unknown): value is SpawnProvider {
+function isSpawnProvider(value: unknown): value is SpawnProvider {
   return typeof value === "string" && (SPAWN_PROVIDERS as readonly string[]).includes(value);
 }
 
 /** Approval modes — runtime tuple + derived type. */
 export const APPROVAL_MODES = ["open", "guarded", "read-only"] as const;
 export type SpawnApprovalMode = (typeof APPROVAL_MODES)[number];
-export function isApprovalMode(value: unknown): value is SpawnApprovalMode {
+function isApprovalMode(value: unknown): value is SpawnApprovalMode {
   return typeof value === "string" && (APPROVAL_MODES as readonly string[]).includes(value);
 }
 
@@ -1194,7 +1228,7 @@ export interface WorkspaceProbe {
   error?: string;
 }
 
-export interface WorkspaceGitCommit {
+interface WorkspaceGitCommit {
   sha: string;
   message: string;
   at?: number;
@@ -1539,7 +1573,7 @@ export interface ManagedAgentState {
   updatedAt: number;
 }
 
-export type SpawnPolicyMode = "always-on" | "on-demand";
+type SpawnPolicyMode = "always-on" | "on-demand";
 
 export type AgentProfileProvider = SpawnProvider | "any";
 export type AgentProfileBase = "host" | "minimal" | "isolated";
@@ -1912,7 +1946,7 @@ export interface OrchestratorRuntimeInput {
   providerCatalog?: ProviderCatalogSummary[];
 }
 
-export interface OrchestratorSpawnInput {
+interface OrchestratorSpawnInput {
   provider: SpawnProvider;
   model?: string;
   effort?: SpawnEffort;
@@ -2007,7 +2041,7 @@ export interface ProviderCatalogSummary {
   }>;
 }
 
-export interface OrchestratorSpawnResult {
+interface OrchestratorSpawnResult {
   orchestratorId: string;
   provider: SpawnProvider;
   sessionName?: string;
@@ -2048,19 +2082,19 @@ export interface RecipeAgent {
   env?: Record<string, string>;
 }
 
-export interface RecipeWorkflow {
+interface RecipeWorkflow {
   trigger?: string;
   fanOut?: "all" | "first";
   collect?: string;
   routing?: RecipeRoute[];
 }
 
-export interface RecipeRoute {
+interface RecipeRoute {
   pattern: string;
   pipeline: string[];
 }
 
-export interface RecipeLifecycle {
+interface RecipeLifecycle {
   mode?: "persistent" | "ephemeral";
   idleTimeoutMs?: number;
   memory?: RecipeMemoryPolicy;
@@ -2177,7 +2211,7 @@ export interface TokenConstraints {
   canDelegate?: boolean;
 }
 
-export type TokenScope =
+type TokenScope =
   | "system:admin"
   | "token:read"
   | "token:write"
@@ -2282,7 +2316,7 @@ export function errMessage(error: unknown): string {
 // --- Relay connection defaults ---
 
 /** Default port the relay server listens on. */
-export const DEFAULT_RELAY_PORT = 4850;
+const DEFAULT_RELAY_PORT = 4850;
 
 /** Default relay base URL. Loopback spelling settled on `127.0.0.1` (not `localhost`). */
 export const DEFAULT_RELAY_URL = `http://127.0.0.1:${DEFAULT_RELAY_PORT}`;