@securecoms/agent-bridge 0.4.0 → 0.6.0

package/dist/bridge-agent.d.ts

@@ -1,4 +1,32 @@
 import { MlsGroupKeyProvider } from "@agentvault/connect-sdk-ts";
+/**
+ * M6 (ADR-0013 Decision H): what the sweep observed about one channel.
+ *
+ * `state` and `diverged` are deliberately separate. `diverged` is a VERDICT and
+ * is `null` whenever the sweep could not earn one — an unresolvable group or a
+ * failed probe are faults in their own right, and reporting either as
+ * `diverged: false` would repeat the exact mistake this whole track is about:
+ * an indicator asserting a condition it did not actually measure.
+ */
+export type ChannelObservation = {
+    channel_id: string;
+    /** healthy   — group matches AND held epoch is level with the server
+     *  behind    — group matches but held epoch trails the server (REPORTED
+     *              divergence; the sweep's ACTION predicate is group-id only,
+     *              so this state does not by itself cause a welcome-request)
+     *  diverged  — held group id does not match the server's live group
+     *  no_local_state / group_unresolvable / probe_failed — see `diverged` */
+    state: "healthy" | "behind" | "stuck" | "diverged" | "no_local_state" | "group_unresolvable" | "probe_failed";
+    held_group_id: string | null;
+    server_group_id: string | null;
+    held_epoch: number | null;
+    server_epoch: number | null;
+    /** true/false only when actually determined; null means "not established". */
+    diverged: boolean | null;
+    /** Evidence, not assertion: wall-clock ms of the last successful decrypt. */
+    last_decrypt_at: number | null;
+    observed_at: number;
+};
 import type { BridgeConfig } from "./config.js";
 import { LatencyRecorder } from "./latency.js";
 import type { AttachmentMeta } from "./attachments.js";
@@ -105,6 +133,16 @@ export declare class InvalidPathError extends Error {
     readonly filePath: string;
     constructor(filePath: string, cause?: unknown);
 }
+/**
+ * The envelope message_id becomes `mls_messages.id` (a UUID primary key) on the
+ * backend, which parses it with `uuid.UUID()`. A non-UUID message_id is a
+ * client-triggerable 500. `send`/`sendA2A` fail closed rather than hand a
+ * malformed id to the wire.
+ */
+export declare class InvalidMessageIdError extends Error {
+    readonly messageId: string;
+    constructor(messageId: string);
+}
 /**
  * Per-room agent pause toggle (daemon side): the backend rejected a publish
  * with `403 {detail:{error:"agent_paused"}}`, which the SDK's `RestTransport`
@@ -236,9 +274,74 @@ export declare class BridgeAgent {
      * counter is incremented. Surfaced on health()/metrics().
      */
     private failedAttachments;
+    /**
+     * Task 8: count of live AUTHENTICATED /v1/ws sessions, so a later `status`
+     * verb can tell "bridge process up" (the app's green dot, which only
+     * proves bridge<->backend) apart from "a harness is actually attached"
+     * (a real consumer holding an authenticated session). Only ws-server.ts
+     * mutates this, and only after authedUpgrade() passes — an unauthenticated
+     * socket, or the HTTP /healthz probe, must never move this counter.
+     * Surfaced on health()/metrics().
+     */
+    private authSessions;
+    /**
+     * Task 3 (audit M3): count of newest-wins evictions of a prior /v1/ws
+     * session. The daemon's WS is single-consumer newest-wins, so
+     * `agent_sessions` alone can stay >=1 while two connectors flap the same
+     * identity in and out — this counter makes that split-brain visible.
+     * Only ws-server.ts mutates this, via noteSessionEvicted(). Surfaced on
+     * health()/status.
+     */
+    private evictions;
     /** Per-channel timestamp of last requestWelcome call, for cooldown enforcement. */
     private readonly lastWelcomeRequest;
     /** Minimum gap between requestWelcome calls for the same channel (2 minutes). */
+    /**
+     * M6 (ADR-0013 Decision H): the sweep's per-channel observation cache, and the
+     * only thing {@link health} reports divergence from.
+     *
+     * Written by `selfHealSweep` in a `finally`, read synchronously by `health()`.
+     * `health()` must NEVER fan out network calls of its own: a health endpoint
+     * that does I/O hangs under exactly the conditions it exists to report, and
+     * the conditions here are "the delivery service is unreachable or lying".
+     */
+    private readonly observations;
+    /**
+     * A3 (dr-evil must-fix #3): true when the sweep found the provider missing a
+     * required capability (stale SDK dist under a newer bridge dist) and ABORTED.
+     * Folded into `observations_stale` (and therefore `degraded`) on health():
+     * a bridge that cannot heal must never present trustworthy-looking data.
+     */
+    private providerCapabilityMissing;
+    /**
+     * ADR-0013 Decision D: the wipe's OWN anti-thrash bound, deliberately
+     * separate from {@link REQUEST_WELCOME_COOLDOWN_MS} and separately keyed.
+     *
+     * Two bounds exist because they protect different things and must never
+     * share a gate. The request cooldown protects the single committer from
+     * churn; deferring an ask costs a little latency. The wipe bound only stops
+     * the member thrashing its own session; skipping a wipe costs the member its
+     * ONLY route back, permanently. Sharing one map is what starved the repair.
+     */
+    private static readonly WIPE_ANTI_THRASH_MS;
+    /**
+     * ADR-0013 Decision A (wipe-first): the SHORTER re-wipe floor used only when
+     * the fork is PROVEN (the self-heal sweep's resyncByReplay returned false).
+     *
+     * The 600s WIPE_ANTI_THRASH_MS is the right duty cycle for the reactive
+     * onWedged path, but it is a TRAP for a proven-forked member: while the member
+     * holds forked state the owner's re-Welcome is stray-acked (mls.ts, rowGroup ==
+     * heldGroup) and destroyed, so the member never returns to no-state and the
+     * Welcome never lands via the first-join path. Suppressing the re-wipe for a
+     * full 10 minutes means every owner Welcome in that window is destroyed — the
+     * observed hermes flap. This floor lets a proven-forked member re-wipe promptly
+     * (return to no-state so the next Welcome opens) while still bounding the loop:
+     * ~one 25s member ingest poll + margin, which preserves Decision D ("cannot
+     * loop") because two wipes still cannot fire inside a single poll interval.
+     */
+    private static readonly PROVEN_FORK_REWIPE_FLOOR_MS;
+    /** Per-channel timestamp of the last state repudiation (Decision D). */
+    private readonly lastWipe;
     private static readonly REQUEST_WELCOME_COOLDOWN_MS;
     private static readonly GRACEFUL_DRAIN_MS;
     /**
@@ -430,6 +533,16 @@ export declare class BridgeAgent {
      * rather than dropping it with no replacement in flight. Never throws.
      */
     private healSupersedeUnopenable;
+    /**
+     * Task 2 (MLS convergence slice): true when we hold persisted state for
+     * `channelId` whose group id does NOT match `serverGroupId` — the group
+     * the server currently says is live for that channel. Holding SOME state
+     * is not proof of health; it is proof of health only for the group the
+     * server currently attests. A null held group id (state present but the
+     * manager can't be loaded from it) is treated as diverged too — we can't
+     * confirm health, so we ask rather than silently trusting stale state.
+     */
+    private isChannelDiverged;
     /**
      * Task 12: proactive self-heal sweep. ingestOnce's Task-11 divergence
      * branch only fires reactively — off a delivery ROW that already arrived
@@ -438,11 +551,22 @@ export declare class BridgeAgent {
      * first thing lost. This sweep walks every member channel — rooms AND DMs
      * (H2: a wiped, idle DM with no traffic since the wipe otherwise never
      * proactively re-Welcomes, so it stays dark until the owner happens to send)
-     * — fired once at boot + on SELF_HEAL_SWEEP_INTERVAL_MS, and, for any with no
-     * persisted state even after a reconcile attempt, resolves group_id via
-     * the READ-ONLY getConnectChannelGroup probe (never initConnectChannelGroup,
-     * which would side-effect a member_device_ids union + commit) and applies
-     * the same held-KP signal — respecting the existing per-channel cooldown.
+     * — fired once at boot + on SELF_HEAL_SWEEP_INTERVAL_MS.
+     *
+     * Task 2: holding persisted state is NOT proof of health by itself — it is
+     * proof of health only for the group the server currently says is live for
+     * the channel. The prior rule ("I have persisted state ⇒ healthy ⇒ don't
+     * ask") silently stopped filing welcome-requests for any channel that had
+     * been superseded (e.g. a server-side reset/rotation) while the member
+     * still held state for the OLD group: it could hold state, hold the WRONG
+     * state, and never say anything. So the server's current group_id is
+     * fetched FIRST via the READ-ONLY getConnectChannelGroup probe (never
+     * initConnectChannelGroup, which would side-effect a member_device_ids
+     * union + commit), then the branch is: persisted state whose group id
+     * matches the server's current group ⇒ healthy, skip; persisted state for
+     * a STALE group id ⇒ diverged, signal; no persisted state at all ⇒
+     * reconcile-first (consume an already-queued Welcome) before concluding
+     * divergence. All three paths go through the same per-channel cooldown.
      *
      * Each channel is wrapped in its own try/catch: `listChannels` filters at
      * the identity level while `requestWelcome` (via request_welcome) gates at
@@ -643,6 +767,25 @@ export declare class BridgeAgent {
      * Mirrors the notify tail of ingestOnce.
      */
     wakeListeners(): void;
+    /**
+     * Task 8: record a newly authenticated /v1/ws session. Called by
+     * ws-server.ts exactly once per connection, AFTER authedUpgrade() passes
+     * (never for a socket closed 1008 for bad auth, and never for the HTTP
+     * /healthz probe, which is not a /v1/ws session at all).
+     */
+    noteSessionOpen(): void;
+    /**
+     * Task 8: record an authenticated /v1/ws session ending. Clamped at 0 so a
+     * stray extra close (e.g. a double-fired cleanup) can't go negative and
+     * poison the next open/close cycle.
+     */
+    noteSessionClose(): void;
+    /**
+     * Task 3 (audit M3): record a prior /v1/ws session being evicted by a
+     * newer connection for the same identity (newest-wins). Called by
+     * ws-server.ts right after prior.cleanup() in the eviction path.
+     */
+    noteSessionEvicted(): void;
     health(): {
         status: "ok";
         identity_id: string;
@@ -661,8 +804,38 @@ export declare class BridgeAgent {
         /** 2026-07-03 latency triage: delivery pings received on the WS stream.
          *  0 while messages flow = push is dead; inbound rides the 25s floor. */
         delivery_pings: number;
+        /** Task 8: count of live authenticated /v1/ws sessions (0 = bridge is up
+         *  but no harness is attached — a true "no brain" signal for `status`). */
+        agent_sessions: number;
+        /** Task 3 (audit M3): cumulative newest-wins evictions of a prior /v1/ws
+         *  session for this identity — a nonzero/climbing value while
+         *  agent_sessions stays >=1 means two connectors are flapping the same
+         *  identity (split-brain), not one stable harness. */
+        evictions: number;
         uptime_s: number;
         version: string;
+        /** M6: is the self-heal sweep running at all? It is the SOLE writer of the
+         *  observation cache below, so `SECURECOMS_SELF_HEAL_SWEEP=false` blanks all
+         *  of it. That switch was set on cortina as a 2026-07-04 perf mitigation and
+         *  silently disabled repair on the one agent that then stayed permanently
+         *  diverged, so it must be reported rather than inferred from empty data. */
+        sweep_enabled: boolean;
+        /** M6: true when the newest observation is older than one full sweep period
+         *  (or there are none). Means the SWEEP is dead — a different fault from
+         *  divergence, and it must not read as a clean fleet. */
+        observations_stale: boolean;
+        /** M6: channels whose divergence verdict is definitively true. Excludes
+         *  unresolvable/failed probes, which are counted as neither. */
+        diverged_channels: number;
+        /** A2 (dr-evil F3, decision D-3): the truthful roll-up — true when any
+         *  channel is definitively diverged OR the observations cannot be trusted
+         *  (stale/absent). Additive: `status` stays "ok" until the flip ships as
+         *  its own deploy (external monitors restart non-ok bridges, and a
+         *  restart loop cannot fix divergence). Gates read THIS field, never
+         *  `status`. */
+        degraded: boolean;
+        /** M6: per-channel observations, newest sweep. Read from cache; no I/O. */
+        channels: ChannelObservation[];
         /** Optional memory-adapter counters (e.g. Hermes provider); present only when the active provider exposes stats(). */
         hermes_no_session?: number;
         hermes_skipped?: number;

package/dist/config.d.ts

@@ -24,6 +24,7 @@ export interface BridgeConfig {
     /** For memoryProvider="openclaw": the OpenClaw agent dir slug, e.g. "cortina" (→ <base_dir>/agents/<agent>/). */
     memoryAgent?: string;
 }
+export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
 export declare function loadConfig(opts: {
     credentialPath: string;
     storePath?: string;