@securecoms/agent-bridge 0.21.0 → 0.24.0

package/dist/coordination.d.ts

@@ -1,24 +1,131 @@
-/** 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.
+ *
+ * Idempotent per message: delivery is at-least-once (a failed ack redelivers
+ * the row, and custody serves it again), so the same message can reach
+ * {@link noteInbound} more than once. Each (channel, message id) is counted
+ * once, and a repeat returns the hop count its first sighting got, so the
+ * repeat gets the same verdict and leaves the run untouched. Counting a repeat
+ * inflated the run until the NEXT agent message was suppressed and acked, a
+ * silent loss. The key is sound because a message id is globally unique at the
+ * backend (`mls_messages_pkey`): a second, different message under a reused id
+ * is refused (`message_id_conflict`) and never fanned out, so a peer cannot
+ * use it to slip past the cap.
+ */
+export declare class AgentHopTracker {
+    private readonly maxChannels;
+    private readonly hops;
+    /** `${channelId}\u0000${messageId}` → the hop count its first sighting got. Map order = age. */
+    private readonly seen;
+    private readonly now;
+    private readonly quietMs;
+    private readonly maxSeenIds;
+    constructor(maxChannels?: number, opts?: {
+        now?: () => number;
+        quietMs?: number;
+        maxSeenIds?: number;
+    });
+    /**
+     * Record an inbound message; returns the consecutive agent hops including it.
+     * `messageId` makes the call idempotent (see the class comment). Without one
+     * the message is counted every time, the conservative direction for a loop
+     * guard.
+     */
+    noteInbound(channelId: string, senderIsAgent: boolean | undefined, messageId?: string): number;
+    /** Test seam: how many message ids are remembered. */
+    seenIdCount(): 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" | "group_superseded" | "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[];
@@ -34,32 +53,32 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     message_id: z.ZodOptional<z.ZodString>;
     idempotency_key: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    role: "agent" | "peer";
     text: string;
+    role: "agent" | "peer";
     conversation_id: string;
     modality: "voice" | "text";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
 }, {
-    role: "agent" | "peer";
     text: string;
+    role: "agent" | "peer";
     conversation_id: string;
     modality: "voice" | "text";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
 }>, {
-    role: "agent" | "peer";
     text: string;
+    role: "agent" | "peer";
     conversation_id: string;
     modality: "voice" | "text";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
 }, {
-    role: "agent" | "peer";
     text: string;
+    role: "agent" | "peer";
     conversation_id: string;
     modality: "voice" | "text";
     message_id?: string | undefined;