@securecoms/agent-bridge 0.26.0 → 0.26.2

package/dist/bridge-agent.d.ts

@@ -51,10 +51,32 @@ export type BridgeToolGrant = {
 };
 /**
  * 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.
+ * data. The E2E plaintext never contributes to these claims, with ONE bounded
+ * exception: a relayed voice turn's `speaker_identity_id`, honoured only when
+ * the envelope's authenticated sender is the channel's server-marked relay.
+ *
+ * Tool grants (architect ruling, 2026-10-02): until channel-grant persistence
+ * lands, the ONLY non-empty grant list is OWNER_DM_DEFAULT_READ_GRANTS
+ * (`current_time` + `web_search`, read mode), and only on a DM whose sender is
+ * the pinned structural owner (or a relayed voice turn whose speaker is). Every
+ * other audience, an unpinned or anomalous owner, and the kill switch
+ * `SECURECOMS_OWNER_DM_DEFAULT_GRANTS` (anything but unset/`on`) get `[]`.
+ * SEC-06 is LIVE for these two tools: docs/security/sec-06-runtime-bounds-audit.md.
+ */
+/**
+ * Architect ruling 2026-10-02: the default read grants an owner DM carries.
+ * A frozen constant in the daemon, NOT runtime config: a runtime cannot widen
+ * it, and the runtime's own tool allow-list still intersects it (a tool the
+ * runtime does not load is never offered). `fetch_url`, `echo`, `sql_query`
+ * and `http_request` are deliberately absent.
  */
+export declare const OWNER_DM_DEFAULT_READ_GRANTS: readonly BridgeToolGrant[];
+/**
+ * Kill switch for OWNER_DM_DEFAULT_READ_GRANTS, read once at BridgeAgent
+ * construction (daemon startup). Unset or exactly `on` keeps the grants;
+ * any other value (`off`, `0`, `false`, empty) sends `[]` on every turn.
+ */
+export declare function ownerDmDefaultGrantsEnabled(env?: NodeJS.ProcessEnv): boolean;
 export interface BridgeAuthorization {
     readonly version: 1;
     readonly audience: AgentAudience;
@@ -272,6 +294,13 @@ export interface BridgeAgentDeps {
     fastLlm?: {
         complete(messages: ChatMessage[]): Promise<string>;
     };
+    /**
+     * Voice repeats (a): how long a relayed transcribed voice turn waits for
+     * the rest of a VAD-split utterance, measured from its first fragment
+     * (default: env `SECURECOMS_VOICE_COALESCE_MS`, else 0 = disabled).
+     * Injected so tests do not wait the full window.
+     */
+    voiceCoalesceWindowMs?: number;
     /**
      * B7 (FileSafe vault): persistence for the vault kekset's owner-pin TOFU
      * state. Defaults to a {@link FileOwnerAuthorityStore} at
@@ -280,6 +309,22 @@ export interface BridgeAgentDeps {
      */
     vaultOwnerStore?: OwnerAuthorityStore;
 }
+/**
+ * Voice repeats (a), owner report 2026-10-02: one spoken question reached the
+ * bridge as two relayed turns ~2 s apart (the relay's VAD split it), which
+ * produced a fast reply to the fragment, an ack, and a runtime answer.
+ * Relayed transcribed voice turns from the same speaker on the same channel
+ * that arrive within this window of the FIRST fragment are joined into one
+ * turn before the fast path plans it. The cost is that every relayed voice
+ * turn waits this long before it is answered, so it is OFF by default (0):
+ * the observed ~2 s split would not fit a window short enough for live
+ * voice. Enable with env `SECURECOMS_VOICE_COALESCE_MS` (read at startup).
+ */
+export declare const VOICE_COALESCE_WINDOW_MS = 0;
+/** Upper bound for the window: a typo must not park every voice turn for minutes. */
+export declare const VOICE_COALESCE_WINDOW_MAX_MS = 5000;
+/** `SECURECOMS_VOICE_COALESCE_MS` as integer ms, clamped to VOICE_COALESCE_WINDOW_MAX_MS; anything else is 0 (disabled). */
+export declare function voiceCoalesceWindowFromEnv(env?: NodeJS.ProcessEnv): number;
 /** Default inbound-buffer cap (messages) when deps.maxBuffer is unset. */
 export declare const DEFAULT_MAX_BUFFER = 1000;
 /**
@@ -382,7 +427,7 @@ export declare class InvalidMessageIdError extends Error {
  * `messageId`, formatted as an RFC 4122 UUID. Live finding 2026-09-06: the
  * previous `fast-<messageId>` string failed `resolveMessageId` ("message_id
  * must be a UUID") on every turn, so the fast path never sent once. Same input
- * → same UUID, so the idempotency argument in `runFastPath`'s doc still holds.
+ * → same UUID, so the idempotency argument in `runFastReply`'s doc still holds.
  *
  * SEC-06 #18: KEYED with the identity-seed-derived reply key and bound to the
  * agent and channel. It used to be SHA-256 of `fast:<messageId>` alone, which
@@ -732,6 +777,29 @@ export declare class BridgeAgent {
     private fastPathFailed;
     /** Cumulative count of fast-path turns skipped in a room channel because the shared send-floor bucket lacked headroom for both the ack and the runtime's own reply (controller ruling) — surfaced on health()/metrics(). */
     private fastPathSkipped;
+    /** Off-cycle fast replies: per-channel promise chains + the in-flight job count. */
+    private readonly fastReplyChains;
+    private fastReplyJobs;
+    /** Room send-floor tokens reserved by queued fast replies, per channel (F3). */
+    private readonly fastReplyReserved;
+    private static readonly FAST_REPLY_MAX_JOBS;
+    /** Voice repeats (a): see {@link VOICE_COALESCE_WINDOW_MS}. */
+    private readonly voiceCoalesceWindowMs;
+    /** H1: fast-path reply ids being published right now (recorded as voice memory). */
+    private readonly spokenReplyIds;
+    /** Open coalescing windows, keyed by channel + speaker. */
+    private readonly voiceCoalescing;
+    /** Ids of every coalesced fragment (capped FIFO): a redelivered row is acked, never a second turn. */
+    private readonly voiceCoalescedIds;
+    /** Merged turn id -> the absorbed fragments' held frames, retired with it. */
+    private readonly voiceCoalescedTails;
+    /** (4) recv.lag: application queue ids already measured (capped FIFO), so a re-pulled row is not re-counted. */
+    private readonly recvLagSeen;
+    private static readonly RECV_LAG_SEEN_CAP;
+    /** Fast-path turns handed to the runtime behind a spoken ack (LLM [[DEFER]], pre-check, or ack_only). */
+    private fastPathDeferred;
+    /** Of those, `full`-mode turns the deterministic pre-check deferred without calling the fast model. */
+    private fastPathIntentDeferred;
     /**
      * 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
@@ -820,6 +888,8 @@ export declare class BridgeAgent {
      * back to the delivery-row-driven Task 11 behaviour only.
      */
     private readonly selfHealSweepEnabled;
+    /** Read once at startup; see ownerDmDefaultGrantsEnabled. */
+    private readonly ownerDmDefaultGrants;
     /** Task 12: proactive sweep cadence (in addition to the once-at-boot fire). */
     private static readonly SELF_HEAL_SWEEP_INTERVAL_MS;
     /**
@@ -1632,37 +1702,96 @@ export declare class BridgeAgent {
     private memoryForTurn;
     memoryContext(conversationId: string, limit?: number): Promise<import("@agentvault/connect-mls-store").MemoryContextResult>;
     /**
-     * Task 4 (self-hosted fast voice): instant persona-voiced acknowledgement
-     * for a live voice turn, sent ahead of the full agent reply — fired from
-     * the ingestOnce text branch as `void this.runFastPath(...)`.
-     *
-     * MUST NEVER throw into ingestOnce: every failure path (memory lookup, the
-     * LLM call, normalization, or the send itself) is caught internally, counted
-     * in `fastPathFailed`, and logged at most once — WITHOUT the turn text or
-     * the model's reply (only the channel/message id, never conversation
-     * content, reaches stderr).
-     *
-     * Dedupe: `fastPathSeen` is keyed by messageId so a redelivered/duplicate
-     * InboxEntry (e.g. after an ack race) never fires the fast LLM — and never
-     * double-sends — twice for the same turn. The `fastReplyId(...)` send
-     * id is itself also deterministic, so even a duplicate call that slipped past the
-     * in-memory dedupe (e.g. a process restart) resolves to the same envelope
-     * message id rather than a second spoken reply.
-     *
-     * Room token reservation (controller ruling): `send()` charges the shared
-     * `room:<channelId>` bucket (see `enforceRateFloor`) for any non-DM
-     * channel. A fast-path ack spent from the SAME bucket could starve the
-     * runtime's own reply moments later, so the CALL SITE (the ingestOnce text
-     * branch) only calls `runFastPath` at all when the bucket has at least 2
-     * tokens available — one earmarked for this ack, one reserved for the
-     * runtime's reply — and, critically, decides the buffered turn's guidance
-     * text using that SAME decision. That decision must not be re-made (and
-     * cannot silently diverge) here: `runFastPath` itself no longer touches the
-     * room bucket at all, it only handles messageId dedupe and the LLM/send
-     * mechanics. See the call site's `fastPathRoomBlocked` for the skip +
-     * `fastPathSkipped` counting.
-     */
-    private runFastPath;
+     * Voice front desk, step 1 — decided SYNCHRONOUSLY inside the ingest cycle,
+     * so the cycle never waits on a model call or a publish (Cortina011
+     * recv.cycle max 10.8 s came from two inline fast replies back to back).
+     * Pure: it changes no state; the caller commits a plan (markFastPathSeen,
+     * counters) only after the turn is durably staged.
+     * - "dup": this turn already went through the fast path (a redelivery);
+     *   it is neither spoken again nor handed to the runtime again.
+     * - "skip": no fast path; the runtime gets the turn with plain guidance
+     *   (mode `off`, no fast client, or the reply queue is full).
+     * - "ack": the turn certainly goes to the runtime (mode `ack_only`, or the
+     *   deterministic pre-check in `full`): `line` is spoken first.
+     * - "fast": the fast model (or, in `ack_only`, the greeting template)
+     *   decides whether the runtime answers next.
+     * Owner report 2026-10-02 (calls never used tools) motivates "ack".
+     */
+    private planFastPath;
+    private noteVoiceCoalesced;
+    private markFastPathSeen;
+    /**
+     * Off-cycle per-channel queue: one promise chain per channel, so within a
+     * channel spoken lines publish, and runtime frames are released, strictly
+     * in turn order (a turn's ack always publishes before its frame reaches
+     * the runtime). `spends` marks a job that will publish a fast reply: those
+     * are bounded by FAST_REPLY_MAX_JOBS (planFastPath degrades to "skip") and
+     * reserve a room send-floor token until they finish. A job never throws.
+     */
+    private enqueueFastReply;
+    /** Count a fast reply against FAST_REPLY_MAX_JOBS and reserve its room send-floor token; returns the release. */
+    private reserveFastReply;
+    /**
+     * Speak a planned fast turn ("ack" or "fast") and settle its held frame:
+     * retired when the fast model answered alone, otherwise released to the
+     * runtime (with the "ack already spoken" guidance only when an ack or a
+     * deferring fast reply was actually published — F3).
+     */
+    private speakAndSettle;
+    /**
+     * Stage a runtime frame without overtaking a turn of the same channel that
+     * is still queued behind the fast path (F2): while the channel has a queue,
+     * the frame is staged durably but held, and released in queue order.
+     */
+    private stageRuntimeMessageInOrder;
+    /** Test seam: resolves once every queued fast reply has settled. */
+    settleFastReplies(): Promise<void>;
+    /** Send a line the voice fast path speaks: its memory record is "voice" (H1). */
+    private sendSpoken;
+    /** Speak a fixed acknowledgement line; failures are counted, never thrown. */
+    private sendFastLine;
+    /**
+     * Voice front desk, step 2 for a "fast" plan (runs off the ingest cycle):
+     * the fast model's reply — or, in `ack_only`, the greeting template — is
+     * spoken, and the outcome decides whether the runtime answers next.
+     *
+     * MUST NEVER throw: every failure path (memory lookup, the LLM call,
+     * normalization, or the send itself) is caught, counted in
+     * `fastPathFailed`, and logged WITHOUT the turn text or the model's reply.
+     * The `fastReplyId(...)` send id is deterministic, so a duplicate that
+     * slipped past the in-memory dedupe (e.g. a restart) resolves to the same
+     * envelope message id rather than a second spoken reply.
+     *
+     * Room token reservation (controller ruling): the CALL SITE only plans a
+     * fast path when the room bucket has headroom for this reply AND the
+     * runtime's, and decides the buffered guidance from that same decision.
+     */
+    private runFastReply;
+    /**
+     * Durably stage a runtime frame WITHOUT handing it to the runtime yet (a
+     * "fast" plan: the fast reply decides). Same durability and backpressure
+     * as stageRuntimeMessage; a restart restores it as an ordinary pending
+     * frame (the "fast path failed" semantics), so a crash mid-call never loses
+     * the turn.
+     */
+    private stageHeldRuntimeMessage;
+    /** Settle a held frame: the fast path answered alone (retire it) or the runtime answers next (release it, in channel order). */
+    private settleHeldRuntimeMessage;
+    /**
+     * Voice repeats (b): a held frame's memory was read when its turn ARRIVED,
+     * before the replies queued ahead of it (an earlier turn's fast reply, this
+     * turn's own ack) were spoken. The runtime replaces its history with the
+     * frame's memory, so with the arrival snapshot it answered an
+     * already-answered turn again. At release the context is re-read and the
+     * AGENT turns it holds beyond the snapshot (afterPublish ->
+     * recordOutboundMemory) are appended to the snapshot. Peer turns recorded
+     * since (this turn itself, later turns) are not, so the frame stays
+     * prior-turn-only for what the runtime is about to answer. New turns are
+     * found by recorded time, never by `seq` (the OpenClaw provider renumbers
+     * seq per read). A failed re-read keeps the arrival snapshot.
+     */
+    private memoryAtRelease;
+    private static readonly TURN_MEMORY_LIMIT;
     /**
      * List channels in one enclave (default: the daemon's own home enclave).
      * Task 3: called per-*known* enclave by refreshChannelMeta so a
@@ -1717,6 +1846,15 @@ export declare class BridgeAgent {
      * 5xx, and genuine non-member 404s only.
      */
     private refreshChannelMeta;
+    /**
+     * Cache server-listed channel metadata (is_dm, name) for the receive cycle.
+     * The ONLY input is a `listChannels` result, the same backend rows
+     * refreshChannelMeta has always cached: refreshChannelMeta and the
+     * self-heal sweep both feed it, so the sweep's own listing (every 90-120 s)
+     * keeps the 5 min cache warm and a turn arriving after idle does not pay a
+     * listing round trip per enclave before it reaches the runtime.
+     */
+    private recordListedChannelMeta;
     /** Cache for the server-side enclave enumeration (see enclavesToCover). */
     private enclaveEnumCache;
     /** Enclaves whose channel listing failed on the NEWEST sweep (audit HIGH:
@@ -1816,6 +1954,17 @@ export declare class BridgeAgent {
      * 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.
+     *
+     * Grants (architect ruling 2026-10-02): OWNER_DM_DEFAULT_READ_GRANTS only when
+     * the kill switch is on, the channel is a DM, and EITHER
+     *   (a) audience is owner_dm AND the sender is the pinned structural owner
+     *       (`channelOwner`, never "anomalous") — a lying `is_agent_owner` flag
+     *       alone gets nothing; OR
+     *   (b) the sender is this channel's server-marked relay (`is_relay`) and the
+     *       relayed `speaker_identity_id` (passed by the caller only for relay
+     *       turns) is that same pinned owner, whose roster row is the agent's
+     *       owner. A speaker claim from any non-relay sender gets nothing.
+     * Everything else gets the frozen empty list.
      */
     private authorizationFor;
     /**
@@ -1964,6 +2113,15 @@ export declare class BridgeAgent {
      */
     private ingestOnce;
     private startIngestCycle;
+    /**
+     * (4) recv.lag = server message created_at -> this pull's completion, per
+     * application row, counted once per queue id. It makes the daemon-side
+     * receive delay measurable (recv.pull alone times only the HTTP call).
+     * Cross-clock: daemon-vs-server skew lands in the sample; a negative lag
+     * is clamped to 0. The server serialises a naive UTC datetime (no offset),
+     * which Date.parse would read as LOCAL time, so a bare timestamp is UTC.
+     */
+    private recordRecvLag;
     private ingestCycle;
     drain(channelId: string | undefined, waitSeconds: number): Promise<BridgeMessage[]>;
     /** Notify-only SSE signal: fired after a buffer push. Listener pulls via takeBuffered. */
@@ -2164,6 +2322,12 @@ export declare class BridgeAgent {
         fast_path_failed: number;
         /** Task 4 (self-hosted fast voice): cumulative fast-path turns skipped in a room because the send-floor bucket lacked headroom for both the ack and the runtime's reply. */
         fast_path_skipped: number;
+        /** Fast-path turns handed to the runtime behind a spoken ack (LLM [[DEFER]], pre-check, or ack_only). */
+        fast_path_deferred: number;
+        /** `full`-mode turns deferred by the deterministic pre-check (no fast model call). */
+        fast_path_intent_deferred: number;
+        /** Credential `voice_fast_path_mode`: "full" (default), "ack_only" or "off". */
+        fast_path_mode: "full" | "ack_only" | "off";
         /** Plan 2026-09-06 (agent voice settings): version of the loaded backend
          *  voice-settings row, or null when no backend row has ever loaded
          *  (source is "file" or "none"). */

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { type VoiceConfig } from "./voice/persona.js";
+import { type FastPathMode } from "./voice/defer-intent.js";
 export interface BridgeConfig {
     apiKey: string;
     identityId: string;
@@ -30,6 +31,13 @@ export interface BridgeConfig {
     memoryFactsCharBudget?: number;
     /** Optional voice persona + fast-path LLM config (self-hosted fast voice reply). Undefined when the credential has no `voice` block. */
     voice?: VoiceConfig;
+    /**
+     * Voice fast-path mode (credential top-level `voice_fast_path_mode`):
+     * "full" (default), "ack_only" or "off" — see voice/defer-intent.ts. Kept
+     * outside `voice` because backend-managed agents have no `voice` block and
+     * a backend voice-settings refetch replaces `voice` wholesale.
+     */
+    voiceFastPathMode?: FastPathMode;
 }
 export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
 export declare function loadConfig(opts: {