@securecoms/agent-bridge 0.26.1 → 0.26.3

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;
 /**
@@ -738,6 +783,19 @@ export declare class BridgeAgent {
     /** 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. */
@@ -830,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;
     /**
@@ -1658,6 +1718,7 @@ export declare class BridgeAgent {
      * 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
@@ -1668,6 +1729,15 @@ export declare class BridgeAgent {
      * 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,
@@ -1676,6 +1746,8 @@ export declare class BridgeAgent {
     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;
     /**
@@ -1705,6 +1777,21 @@ export declare class BridgeAgent {
     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
@@ -1867,8 +1954,37 @@ 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;
+    /**
+     * One content-free INFO line per authorization decision (every call site of
+     * authorizationFor stages exactly one runtime turn). It says WHY a turn got
+     * the grants it got, without any identifier, name or text: every field is a
+     * boolean, a count, or a closed-set label.
+     *
+     *   owner_pin                pinned | anomalous | missing (channelOwner cache)
+     *   owner_row_is_agent_owner the pinned owner's roster row; `absent` when
+     *                            there is no pin or the row is not in the roster
+     *   sender_is_owner          sender identity == pinned owner identity
+     *   relay                    sender's roster row has is_relay
+     *   relay_speaker_is_owner   `na` unless a relay speaker was passed
+     *   kill_switch              SECURECOMS_OWNER_DM_DEFAULT_GRANTS as read at
+     *                            startup: `on` = default grants enabled
+     *   meta_fresh / roster_fresh whether the channel meta / roster caches were
+     *                            fresh (either stale forces audience=unknown)
+     */
+    private logAuthzDecision;
     /**
      * 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
@@ -2015,6 +2131,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. */