@securecoms/agent-bridge 0.20.0 → 0.23.0

package/dist/bridge-agent.d.ts

@@ -1,4 +1,5 @@
 import { MlsGroupKeyProvider } from "@agentvault/connect-sdk-ts";
+import type { MemoryContextResult } from "@agentvault/connect-mls-store";
 /**
  * M6 (ADR-0013 Decision H): what the sweep observed about one channel.
  *
@@ -35,12 +36,45 @@ import { type ChatMessage } from "./voice/fast-prompt.js";
 import { VOICE_CALL_START_MARKER } from "./voice/prompt-compiler.js";
 import { type VaultListNode } from "./vault.js";
 import type { AgentActionNodeType, AgentActionNodeStatus, AgentActionNodeDetail } from "@agentvault/connect-core";
+import type { RuntimeReplyReceipt } from "./reply-receipts.js";
+export type AgentAudience = "owner_dm" | "team_room" | "partner_room" | "other_human_dm" | "agent_to_agent" | "unknown";
+export type BridgeToolGrant = {
+    readonly tool: string;
+    readonly mode: "read";
+} | {
+    readonly tool: string;
+    readonly mode: "side_effect";
+    readonly operation_sha256: string;
+    readonly confirmation_id: string;
+    readonly idempotency_key: string;
+    readonly expires_at: string;
+};
+/**
+ * Immutable authorization context derived from authenticated backend roster
+ * data. The E2E plaintext never contributes to these claims. Tool grants are
+ * intentionally empty until the channel-grant persistence/API lands; this
+ * makes the new contract fail closed during staged deployment.
+ */
+export interface BridgeAuthorization {
+    readonly version: 1;
+    readonly audience: AgentAudience;
+    readonly sender_membership: "active" | "unknown";
+    readonly tool_grants: readonly BridgeToolGrant[];
+}
 export interface BridgeMessage {
     channel_id: string;
     message_id: string;
     sender_id: string;
     text: string;
     ts: number;
+    authorization: BridgeAuthorization;
+    /**
+     * Protected, channel-scoped memory captured before this inbound turn is
+     * recorded. The runtime can therefore prepend prior context without owning
+     * a second plaintext persistence path or duplicating the current message.
+     * Missing only for non-text/legacy buffered entries.
+     */
+    memory?: MemoryContextResult;
     /**
      * Phase 2 (sender attribution): the sender's display name, resolved from the
      * channel roster cache. Undefined when the roster hasn't resolved the
@@ -179,6 +213,19 @@ export interface BridgeAgentDeps {
      * recent (a real-time messaging consumer cares about the newest). Default 1000.
      */
     maxBuffer?: number;
+    /**
+     * Phase 3 F1: how many times one inbound message may be delivered to a
+     * runtime consumer over /v1/ws before it is dead-lettered (content-free log +
+     * ack) instead of redelivered forever. Every redelivery can re-run the
+     * owner's model on their own key. Default {@link DEFAULT_MAX_DELIVERY_ATTEMPTS}.
+     */
+    maxDeliveryAttempts?: number;
+    /**
+     * Phase 3 F3: consecutive agent-authored messages allowed in one channel
+     * before this agent stops answering other agents there (a human message
+     * resets the count). Default {@link DEFAULT_MAX_AGENT_HOPS}.
+     */
+    maxAgentHops?: number;
     /**
      * Review I3/M3: clock seam for the agent.action.* partial-throttle token
      * buckets AND the unsettled-run stale-TTL sweep. Defaults to Date.now.
@@ -211,10 +258,46 @@ export interface BridgeAgentDeps {
 }
 /** Default inbound-buffer cap (messages) when deps.maxBuffer is unset. */
 export declare const DEFAULT_MAX_BUFFER = 1000;
+/**
+ * Phase 3 F1: default per-message delivery cap for the /v1/ws runtime handoff.
+ * Deliberately ABOVE the OpenClaw connector's own MAX_INBOUND_ATTEMPTS (3,
+ * connectors/openclaw/openclaw-entry.js): that connector acks a poison
+ * message itself after three failed turns, so this daemon cap is only the
+ * backstop for consumers without one, and the two extra deliveries leave
+ * headroom for the connector's "runtime not ready" / receipt-lookup retries,
+ * which it deliberately does not count.
+ */
+export declare const DEFAULT_MAX_DELIVERY_ATTEMPTS = 5;
+/**
+ * Final-wave I1(a): a runtime delivery that failed (a `nack`, or the socket
+ * closing with the message in flight) is not redelivered before
+ * 2^attempts × this base. With the default cap of 5 the deliveries span
+ * minutes, not seconds, so a provider outage no longer dead-letters work
+ * within seconds. The attempt counter is durable, and the delay is derived
+ * from it — a restart re-arms the same backoff from the restore.
+ */
+export declare const REDELIVERY_BACKOFF_BASE_MS = 5000;
+export declare function redeliveryDelayMs(attempts: number): number;
+/**
+ * Final-wave I1(c): the one content-free reply a channel gets when one of its
+ * messages is dead-lettered. Fixed text — it never echoes the message.
+ */
+export declare const DEAD_LETTER_NOTICE = "I couldn't process a message. Please resend it.";
+/** At most one {@link DEAD_LETTER_NOTICE} per channel per this window. */
+export declare const DEAD_LETTER_NOTICE_INTERVAL_MS: number;
+/**
+ * Phase 3 F1 (pause stops inference): after a send is refused with
+ * `agent_paused`, inbound traffic for that channel is not handed to the
+ * runtime (no model call). The pause is reversible, so once this long has
+ * passed since it was last confirmed, the next inbound message re-probes the
+ * agent's own membership row before deciding.
+ */
+export declare const PAUSE_RECHECK_MS = 30000;
 /**
  * TTL for the Phase 2 channelMeta cache. `is_dm` is immutable for a channel_id,
- * so this exists only so a cached `name` (the room display name used by the
- * @mention filter) re-resolves after a channel rename. Lazy expiry on read.
+ * so this exists only so a cached channel `name` re-resolves after a channel
+ * rename. The channel name is NOT an @mention name for this agent (2026-09-25:
+ * the filter uses this agent's own roster display_name). Lazy expiry on read.
  */
 export declare const CHANNEL_META_TTL_MS: number;
 /**
@@ -289,6 +372,17 @@ export declare class AgentPausedSendError extends Error {
     readonly channelId: string;
     constructor(channelId: string);
 }
+/**
+ * Phase 3 F1: the backend refused a publish with a bare 401/403 (not the
+ * typed `agent_paused` body) — the agent's credential or device has been
+ * revoked or it is no longer a member. Retrying cannot succeed, so this is
+ * TERMINAL for the reply: the runtime's inbound message is acknowledged and
+ * the model is not run again for it.
+ */
+export declare class SendForbiddenError extends Error {
+    readonly channelId: string;
+    constructor(channelId: string);
+}
 /** Thrown by `agent.action.*` when a runId (or nodeId within a run) is unknown
  * or the run has already settled — settle() is terminal, mirroring the client
  * ingest side's "later partials for a settled run are dropped" rule. */
@@ -372,6 +466,15 @@ export declare class BridgeAgent {
      * per channel on a miss.
      */
     private readonly channelRoster;
+    /**
+     * 2026-09-25: this agent's own display_name (`ConnectIdentity.display_name`,
+     * identity-level, so the same in every channel) from the MOST RECENT roster
+     * refresh that listed it. Read by the room @mention filter as its
+     * `roomDisplayName`. Kept across a later failed refresh, so a transient
+     * members-fetch error does not make the agent deaf to its own name; a
+     * successful refresh after a rename replaces it.
+     */
+    private lastOwnDisplayName;
     /**
      * Task 8 (owner-attested Reset Secure Session): per-channel STRUCTURAL owner
      * cache, fed by resolveAndPinOwner() on every roster refresh and consumed by
@@ -382,7 +485,37 @@ export declare class BridgeAgent {
      */
     private readonly channelOwner;
     private readonly buffer;
+    /** Message ids durably staged for the attached runtime but not yet acked. */
+    private readonly runtimePendingIds;
     private readonly maxBuffer;
+    /** Phase 3 F1: deliveries so far per pending runtime message (seeded from the store). */
+    private readonly deliveryAttempts;
+    private readonly maxDeliveryAttempts;
+    /** Phase 3 F1: cumulative messages dead-lettered at the delivery cap. */
+    private deadLetteredMessages;
+    /** Final-wave I1(a): message id → earliest redelivery time (epoch ms). */
+    private readonly redeliverNotBefore;
+    /** Final-wave I1(a): one timer poking consumers when the earliest backoff ends. */
+    private redeliveryTimer;
+    private redeliveryTimerAt;
+    /** Final-wave I1(c): channel → when its last dead-letter notice was posted. */
+    private readonly deadLetterNoticeAt;
+    /** Phase 3 F1: channel → when a pause was last confirmed (send 403 or probe). */
+    private readonly pausedChannels;
+    /**
+     * Phase 3 F1: runtime messages retired by a TERMINAL reply failure reported
+     * outside the /v1/ws socket that holds them in flight (HTTP /v1/send). The
+     * socket consults this so it neither redelivers them nor stays busy on them.
+     * Bounded; oldest forgotten first.
+     */
+    private readonly retiredRuntimeIds;
+    /** Phase 3 F1: one pending membership recheck per paused channel holding work. */
+    private readonly pauseRecheckTimers;
+    /** Phase 3 F3: consecutive agent turns per channel. */
+    private readonly agentHops;
+    private readonly maxAgentHops;
+    /** Phase 3 F3: cumulative agent-authored messages not answered (no explicit mention / hop limit). */
+    private agentLoopSuppressed;
     /** Cumulative count of messages shed by the buffer cap (surfaced on health()/metrics()). */
     private droppedMessages;
     /**
@@ -519,7 +652,7 @@ export declare class BridgeAgent {
     private static readonly REQUEST_WELCOME_COOLDOWN_MS;
     private static readonly GRACEFUL_DRAIN_MS;
     /**
-     * P0b (daemon-stability): collapses the onDecryptError console.warn from
+     * P0b (daemon-stability): collapses the onDecryptError diagnostic from
      * "one line per failure" (the 114 MB/765k-line-in-a-day log source) to at
      * most one line immediately + one summary line per 60s per channel. LOG
      * OUTPUT ONLY — does not touch errorStats()/quarantine counters, which
@@ -601,6 +734,7 @@ export declare class BridgeAgent {
     private readonly waiters;
     private pingHandle?;
     private safetyTimer?;
+    private runtimeConfigTimer?;
     private readonly listeners;
     private startedAt;
     private readonly store;
@@ -819,9 +953,16 @@ export declare class BridgeAgent {
      * reads `null` and therefore degraded.
      */
     private keypackageExpired;
+    /** #335: dedupes the expiry-measurement warning to once per failure STREAK —
+     * any non-throwing resolution (including the known-unknown `null` returns,
+     * which are answers, not failures) re-arms it. Mirrors `enclaveListWarned`. */
+    private keypackageExpiryUnknownWarned;
     /** Resolve the flag from the SAME two inputs the guard uses, with every unknown
      * mapped to `null`. Never throws: a failure to measure is itself unknown. */
     private resolveKeypackageExpired;
+    /** Every non-throwing resolution ends the failure streak (the next throw is
+     * a NEW streak and warns again) and passes the value through unchanged. */
+    private kpExpiryResolved;
     private rotateDeviceKeyPackage;
     private selfHealSweep;
     /**
@@ -853,7 +994,14 @@ export declare class BridgeAgent {
      * already resolves internally) propagates unchanged.
      */
     private sendWithSelfHealTerminal;
-    send(channelId: string, text: string, messageId?: string): Promise<{
+    /**
+     * `opts.agentTurn` (default true): whether this send is a SUBSTANTIVE agent
+     * turn for the Phase 3 F3 hop count. Notices (daily limit, dead letter) and
+     * continuation parts of one multi-part reply pass false (final-wave I2).
+     */
+    send(channelId: string, text: string, messageId?: string, opts?: {
+        agentTurn?: boolean;
+    }): Promise<{
         message_id: string;
         status: "sent";
     }>;
@@ -861,7 +1009,9 @@ export declare class BridgeAgent {
         a2a_version: string;
         kind: "message" | "task" | "artifact";
         object: Record<string, unknown>;
-    }, messageId?: string): Promise<{
+    }, messageId?: string, opts?: {
+        agentTurn?: boolean;
+    }): Promise<{
         message_id: string;
         status: "sent";
     }>;
@@ -937,6 +1087,21 @@ export declare class BridgeAgent {
         seq: number;
         deduped: boolean;
     }>;
+    /**
+     * OpenClaw collapses text history and workspace facts into the owner's
+     * session. Resolve the channel from fresh, authenticated server metadata
+     * before exposing that provider through the local bridge API. A cold or
+     * stale cache is refreshed once; any failure remains a fail-closed denial.
+     */
+    private mayReadOpenClawMemory;
+    /** An inbound turn may receive OpenClaw memory only from an active owner DM. */
+    private mayReadOpenClawMemoryForTurn;
+    /**
+     * Resolve the prior-turn snapshot carried to the native runtime. OpenClaw
+     * stays owner-DM-only; every provider failure degrades to empty context and
+     * never falls back to the runtime's retired plaintext JSON files.
+     */
+    private memoryForTurn;
     memoryContext(conversationId: string, limit?: number): Promise<import("@agentvault/connect-mls-store").MemoryContextResult>;
     /**
      * Task 4 (self-hosted fast voice): instant persona-voiced acknowledgement
@@ -1118,6 +1283,13 @@ export declare class BridgeAgent {
      * attribution must NEVER block or drop a message.
      */
     private refreshChannelRoster;
+    /**
+     * Classify the sender only from server-authenticated channel/roster data.
+     * Missing or stale metadata is UNKNOWN with zero grants, never a permissive
+     * guess. The returned object and grant array are frozen before they cross the
+     * daemon boundary so one consumer cannot widen a later execution check.
+     */
+    private authorizationFor;
     /**
      * Task 8 (owner-attested Reset Secure Session): STRUCTURAL owner selection —
      * NEVER read the server's `role` field to pick the owner. In a DM the owner
@@ -1174,9 +1346,6 @@ export declare class BridgeAgent {
     /** call_summary rides a system_event envelope with a body-level type, the
      *  same shape sendActionFrame uses for agent_action. */
     private sendSummary;
-    /** Minimal stderr logger for non-fatal daemon events (mirrors the ad hoc
-     *  `process.stderr.write` calls elsewhere in this file). */
-    private log;
     /**
      * The coalescing throttle (review H4 / Global Constraint: ~1/sec per run).
      * If the run has no dirty nodes, no-op. If the per-run bucket has no token,
@@ -1211,6 +1380,97 @@ export declare class BridgeAgent {
     subscribe(listener: () => void): () => void;
     /** Synchronous splice of buffered messages (all, or one channel). Shared by drain + SSE. */
     takeBuffered(channelId?: string): BridgeMessage[];
+    /**
+     * Phase 3 F2: per-channel ordered delivery for the /v1/ws runtime consumer.
+     * Splices out, oldest first, at most ONE buffered message per channel that
+     * is not in `busyChannels` (the channels the consumer still holds a message
+     * in flight for); everything else stays buffered in order. A runtime is
+     * therefore never handed a second message for a channel it is still
+     * working on — which it used to refuse with a "busy" reply and ack — and a
+     * backlog replays one message per channel at a time after a restart.
+     */
+    takeDeliverable(busyChannels: ReadonlySet<string>): BridgeMessage[];
+    /**
+     * Phase 3 F1: gate ONE delivery of `message` to the runtime consumer. Returns
+     * true when it may be sent (and counts the attempt durably), false when the
+     * message already reached the delivery cap — then it is dead-lettered:
+     * acknowledged, never redelivered, never reaching a model. (Paused channels
+     * never get here: takeDeliverable holds them, so a pause spends no attempts.)
+     * Logs are content-free (event + counts only).
+     */
+    admitRuntimeDelivery(message: BridgeMessage): boolean;
+    /**
+     * Final-wave I1: put back runtime deliveries that FAILED — the runtime sent a
+     * `nack` for the message, or the socket closed while it was in flight (an
+     * older runtime closes on any failed turn). Each one's attempt was already
+     * counted durably at delivery; here it either dead-letters (cap reached) or
+     * is requeued at the front behind a 2^attempts × 5 s redelivery backoff.
+     * Messages that were never handed to the runtime go back via requeueFront
+     * instead and are not affected.
+     */
+    requeueFailedRuntimeDeliveries(messages: BridgeMessage[]): void;
+    /**
+     * Phase 3 F1 dead letter: acknowledged, never redelivered, never reaching a
+     * model — plus (final-wave I1(c)) one content-free notice to the channel,
+     * at most once per channel per hour. Logs carry counts only.
+     */
+    private deadLetter;
+    private noticeDeadLetter;
+    /** Poke consumers once the earliest redelivery backoff ends. */
+    private armRedeliveryWake;
+    /**
+     * 2026-09-25: this agent's OWN display_name for the room @mention filter
+     * (`roomDisplayName`). Never the channel's name: a channel called
+     * "Hermesav, Cortina011" must not make `@hermesav` address this agent. A pure
+     * field read; the roster refresh that fills it runs once per ingest cycle,
+     * TTL-gated, before the filter. Undefined until any roster has listed this
+     * agent, in which case the filter still matches the credential agentName and
+     * the identity id.
+     */
+    private ownRoomDisplayName;
+    /** Phase 3 F3: the loop guard's view of the sender — server roster first. */
+    private loopSenderIsAgent;
+    private noteAgentTurnSuppressed;
+    /**
+     * Phase 3 F1: whether `channelId`'s buffered work must be HELD because the
+     * agent is paused there. Held work stays durably pending (never acked, no
+     * delivery attempt spent) and is released by {@link recheckPause} once the
+     * owner resumes the agent. Only a channel whose send was refused with
+     * `agent_paused` is ever held. Holding arms a recheck at the end of the
+     * PAUSE_RECHECK_MS window, so release does not depend on new traffic.
+     */
+    private heldForPause;
+    private schedulePauseRecheck;
+    /**
+     * Re-read this agent's own membership row. Still paused → keep holding and
+     * re-arm while work is held. Resumed — or a failed/inconclusive probe, which
+     * fails OPEN so a channel is never left deaf (the worst case is one model
+     * call whose reply is refused again, re-arming the pause) — releases the
+     * held work and pokes consumers to drain it now.
+     */
+    private recheckPause;
+    private clearPause;
+    /** Read this agent's own `paused_at` from the enclave roster; undefined = unknown. */
+    private probeOwnPause;
+    recordRuntimeReply(inReplyTo: string, channelId: string, replyMessageId: string): RuntimeReplyReceipt;
+    runtimeReplyReceipt(inReplyTo: string): RuntimeReplyReceipt | null;
+    /**
+     * Phase 3 F1: retire a runtime message whose reply failed TERMINALLY
+     * (agent_paused / send_forbidden): acknowledged durably, never redelivered,
+     * so the model is not run again for it. Pokes consumers so a socket holding
+     * it in flight frees the channel for its next message.
+     */
+    retireRuntimeMessage(messageId: string): void;
+    isRuntimeMessageRetired(messageId: string): boolean;
+    /** Complete the durable handoff only after the runtime explicitly acks. */
+    ackRuntimeMessages(messageIds: string[]): void;
+    private restoreRuntimeInbox;
+    /**
+     * Seal a runtime frame before the backend queue id may be acknowledged.
+     * Returning false is backpressure: the caller leaves the backend row unacked
+     * so it remains the durable queue rather than shedding accepted work.
+     */
+    private stageRuntimeMessage;
     /**
      * Put messages back at the front (SSE/disconnect write-failure recovery).
      *
@@ -1256,6 +1516,12 @@ export declare class BridgeAgent {
         dropped: number;
         /** Cumulative ROOM messages dropped by the @mention filter (correct filtering ≠ idle). */
         filtered_room: number;
+        /** Phase 3 F1: inbound messages retired at the runtime delivery-attempt cap. */
+        dead_lettered: number;
+        /** Phase 3 F1: channels whose inbound is currently held because the agent is paused. */
+        paused_channels: number;
+        /** Phase 3 F3: agent-authored messages not answered (no explicit mention / hop limit). */
+        agent_loop_suppressed: number;
         /** Cumulative sends shed by the per-channel rate-limit floor (correct backpressure ≠ idle). */
         rate_limited: number;
         /** Cumulative inbound rows acked-and-dropped because they were provably past-epoch undecryptable (forward-secrecy secret gone). */
@@ -1374,6 +1640,12 @@ export declare class BridgeAgent {
         errors: ReturnType<MlsGroupKeyProvider["errorStats"]>;
         dropped: number;
         filteredRoomMessages: number;
+        /** Phase 3 F1: inbound messages retired at the runtime delivery cap. */
+        deadLetteredMessages: number;
+        /** Phase 3 F1: channels whose inbound is currently held (agent paused). */
+        pausedChannels: number;
+        /** Phase 3 F3: agent-authored messages not answered by the loop guard. */
+        agentLoopSuppressed: number;
         rateLimitedSends: number;
         permanentlySkipped: number;
         /** SDK-6: cumulative rows ack-drained via QUARANTINE, distinct from the

package/dist/coordination.d.ts

@@ -1,24 +1,109 @@
-/** Extract @mention names from plaintext. Returns lowercased names. */
+/**
+ * Extract @mention names from plaintext. Returns lowercased names.
+ *
+ * A token starts with a word character and may contain `.` and `-`, so an agent
+ * handle (`@sc-agent-01`) and a full identity UUID mention stay whole (the gen2
+ * `@(\w[\w]*)` cut both at the first hyphen, so neither could ever address its
+ * agent). Trailing `.`/`-` is sentence punctuation and is trimmed
+ * (`thanks @Stephen.` → "stephen").
+ */
 export declare function parseMentions(text: string): string[];
 /**
  * Lower-cased set of names that count as "this agent" in a room: framework
  * agentName + its first word, accountId + its first word, and (when known) the
  * AgentVault room display_name + its first word. First word = split on
- * whitespace or "(".
+ * whitespace or "("; it also counts with trailing punctuation removed
+ * ("Stephen, PhD" → "stephen,", "stephen"), matching {@link parseMentions}.
+ *
+ * `roomDisplayName` is THIS AGENT's own display_name as a member of the room
+ * (its roster row), never the channel's name: a channel called
+ * "Hermesav, Cortina011" must not make `@hermesav` address this agent.
  */
 export declare function ownRoomNames(agentName: string, accountId: string, roomDisplayName?: string): Set<string>;
+/**
+ * Phase 3 F3 — default per-room agent-to-agent hop limit: at most this many
+ * CONSECUTIVE agent-authored messages (since the last human message) in one
+ * channel. Two agents that keep @mentioning each other stop after this many
+ * turns instead of spending the owners' BYOK budget forever.
+ */
+export declare const DEFAULT_MAX_AGENT_HOPS = 3;
+/**
+ * Whether an agent-authored message may be answered. `agentHops` counts the
+ * consecutive agent-authored messages in the channel INCLUDING this one; our
+ * reply would be one more agent turn, so it is allowed only while
+ * `agentHops < maxAgentHops`.
+ */
+export declare function agentHopAllowed(agentHops: number, maxAgentHops?: number): boolean;
 /**
  * Whether this agent should process a room message based on its @mentions.
  *
- * Loop prevention is the rate-limiter's job (a later slice), so this filter does
- * NOT gate on senderIsAgent — every message is processed unless it @mentions a
- * *different* agent specifically:
+ * Human (or unknown) sender — the gen2 floor, unchanged:
  *   - no mentions            → true (broadcast)
  *   - @all / @everyone       → true
  *   - this agent is mentioned → true
  *   - else (a different agent is mentioned) → false
+ *
+ * Agent sender (Phase 3 F3 loop guard): processed ONLY when that agent
+ * @mentions THIS agent by name (a broadcast, @all or @everyone from an agent
+ * is not an address) AND the per-room hop limit is not exhausted
+ * (`agentHops`, see {@link agentHopAllowed}). An unknown sender type keeps the
+ * fail-open human semantics so an unclassifiable message is never dropped.
  */
 export declare function shouldProcessRoomMessage(plaintext: string, agentName: string, accountId: string, opts?: {
     senderIsAgent?: boolean;
     roomDisplayName?: string;
+    /** Consecutive agent-authored messages in this room, including this one. */
+    agentHops?: number;
+    maxAgentHops?: number;
+}): boolean;
+/**
+ * Final-wave I2: a channel's agent-hop count resets once this long has passed
+ * since the last agent-authored message in it. Without it, two agents in a DM
+ * (where no human ever speaks) went permanently deaf to each other after
+ * DEFAULT_MAX_AGENT_HOPS turns. A live loop is seconds apart, so the cap still
+ * stops it; a conversation resumed ten quiet minutes later starts a new run.
+ */
+export declare const AGENT_HOP_QUIET_MS: number;
+/**
+ * Per-channel count of consecutive agent-authored messages since the last
+ * human message (or the last quiet window, {@link AGENT_HOP_QUIET_MS}). Fed
+ * with EVERY inbound text message of a channel (whether or not this agent
+ * processes it) plus this agent's own SUBSTANTIVE sends, so two agents in one
+ * room keep the same count from their own vantage points.
+ *
+ * In memory and bounded (oldest channel evicted first): a restart resets the
+ * counts, which can at worst allow one more bounded run of hops.
+ */
+export declare class AgentHopTracker {
+    private readonly maxChannels;
+    private readonly hops;
+    private readonly now;
+    private readonly quietMs;
+    constructor(maxChannels?: number, opts?: {
+        now?: () => number;
+        quietMs?: number;
+    });
+    /** Record an inbound message; returns the consecutive agent hops including it. */
+    noteInbound(channelId: string, senderIsAgent: boolean | undefined): number;
+    /**
+     * Record one of this agent's own SUBSTANTIVE sends (an agent turn in the
+     * channel). Callers do not report status frames, daily-limit or dead-letter
+     * notices, or continuation parts of one multi-part reply.
+     */
+    noteOwnSend(channelId: string): void;
+    size(): number;
+    private bump;
+    private set;
+}
+/**
+ * Final-wave I2: whether a runtime `send` is a SUBSTANTIVE agent turn for the
+ * hop count. Not one: a notice (`notice: true` — e.g. the daily-limit reply)
+ * or a continuation part of a multi-part reply (its in_reply_to already has a
+ * durable reply receipt, i.e. an earlier part was published).
+ */
+export declare function isAgentTurn(receipts: {
+    runtimeReplyReceipt(inReplyTo: string): unknown;
+}, frame: {
+    notice?: unknown;
+    in_reply_to?: unknown;
 }): boolean;

package/dist/decrypt-error-log-limiter.d.ts

@@ -1,25 +1,19 @@
+import { type ServiceLog } from "./service-log.js";
 export interface DecryptErrorInfo {
-    /** MLS epoch the failing row was at, if known. */
+    /** MLS epoch the failing row was at, when it is a finite number. */
     epoch?: number | string;
-    /** Delivery queue id the failing row came from, if known. */
-    queueId?: string;
-    /** The decrypt error's message (already stringified by the caller). */
-    message: string;
+    /** Original thrown value; reduced to a bounded class by the service logger. */
+    error: unknown;
 }
 export interface DecryptErrorLogLimiterOpts {
     /** Suppression window in ms. Default 60_000 (60s). */
     windowMs?: number;
     /** Clock seam for tests. Defaults to Date.now. */
     now?: () => number;
-    /** Log sink. Defaults to console.warn. Injectable so tests can assert on
-     *  emitted lines without capturing the real console. */
-    log?: (line: string) => void;
+    /** Structured service-log seam for tests. */
+    log?: ServiceLog;
 }
-/** Default suppression window: 60 seconds. */
 export declare const DEFAULT_DECRYPT_ERROR_LOG_WINDOW_MS = 60000;
-/** Hard cap on distinct error reasons surfaced per channel per window. A wedged
- *  channel has a small handful of genuine reasons; beyond this the extra volume
- *  is noise (or an adversarial/buggy server cycling messages) and is suppressed. */
 export declare const MAX_DISTINCT_PER_WINDOW = 4;
 export declare class DecryptErrorLogLimiter {
     private readonly windowMs;
@@ -27,25 +21,7 @@ export declare class DecryptErrorLogLimiter {
     private readonly log;
     private readonly windows;
     constructor(opts?: DecryptErrorLogLimiterOpts);
-    /**
-     * Record one decrypt error for `channelId`. Logs immediately if this is
-     * the channel's first error since its window opened (or its prior window
-     * had already elapsed, in which case a summary for that just-closed
-     * window is flushed first); otherwise the error is counted silently
-     * toward the window's eventual summary line.
-     */
     record(channelId: string, info: DecryptErrorInfo): void;
-    /**
-     * Clear a channel's window (e.g. once the caller learns the channel
-     * cleared/healed) so its NEXT error logs immediately as a fresh "first"
-     * rather than being folded into a stale window's summary. There is
-     * currently no onDecryptSuccess-style hook from the SDK to wire this to
-     * automatically (see bridge-agent.ts's onDecryptError wiring comment) —
-     * exposed here so a future success signal (or a caller with its own
-     * channel-cleared signal) can reset explicitly. In its absence, the
-     * window simply rolls over on interval elapse, which is an accepted
-     * simplification (see report).
-     */
     reset(channelId: string): void;
     private logFirst;
     private flushSummary;

package/dist/errors.d.ts

@@ -6,7 +6,7 @@
  * WebSocket returns `{type:"error", error, message, detail?}`. A client gets the
  * same `error` code regardless of which transport it used. (A2A §9.5/§10.6 pattern.)
  */
-export type BridgeErrorCode = "unauthorized" | "forbidden_origin" | "not_found" | "invalid_request" | "invalid_json" | "body_too_large" | "channel_pending" | "rate_limited" | "unknown_action_run" | "vault_integrity_failed" | "internal";
+export type BridgeErrorCode = "unauthorized" | "forbidden_origin" | "not_found" | "invalid_request" | "invalid_json" | "body_too_large" | "channel_pending" | "rate_limited" | "agent_paused" | "send_forbidden" | "unknown_action_run" | "vault_integrity_failed" | "internal";
 export interface BridgeErrorSpec {
     /** HTTP status this code maps to (the WS binding ignores it). */
     http: number;

package/dist/http-server.d.ts

@@ -1,11 +1,30 @@
 import { type Server } from "node:http";
 import { z } from "zod";
 import type { BridgeAgent, BridgeMessage } from "./bridge-agent.js";
+/**
+ * #335 handling decision: the throwing-write swallow stays (a dying socket
+ * must cost only that connection's remainder — the caller requeues it and
+ * only acks what was written — never crash the flush loop), but it is no
+ * longer invisible: the optional `onWriteError` hook reports the thrown
+ * value so the caller can service-log its sanitized class. The hook is
+ * telemetry-only by contract: a throwing hook is contained here, so it can
+ * never change the returned remainder or turn a skipped write into a crash.
+ * (Relay precedent: connect-room-relay src/http.ts `writeSse`, PR #654.)
+ */
 export declare function writeSse(res: {
     destroyed?: boolean;
     writableEnded?: boolean;
     write: (s: string) => boolean;
-}, msgs: BridgeMessage[]): BridgeMessage[];
+}, msgs: BridgeMessage[], onWriteError?: (error: unknown) => void): BridgeMessage[];
+/**
+ * Once-per-connection write-failure reporter (#335). A throwing `res.write`
+ * means the socket is dying — teardown follows via the request's `'close'` —
+ * so one WARN per connection is the whole story; repeats from a re-entered
+ * flush on the same corpse stay silent. Logs the sanitized `error_class`
+ * only (ServiceLogFields is number/boolean-typed by design — message text,
+ * channel ids, and exception prose cannot reach the log line).
+ */
+export declare function sseWriteFailureReporter(): (error: unknown) => void;
 export interface HttpServerOptions {
     token: string;
     allowOrigins: string[];