@securecoms/agent-bridge 0.25.4 → 0.26.1

package/dist/bridge-agent.d.ts

@@ -31,10 +31,10 @@ export type ChannelObservation = {
 import { type OwnerAuthorityStore, type OwnerPin } from "@agentvault/connect-clients-core";
 import type { BridgeConfig } from "./config.js";
 import { LatencyRecorder } from "./latency.js";
-import type { AttachmentMeta } from "./attachments.js";
+import type { AttachmentMeta, VaultRefEntry } from "./attachments.js";
 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 VaultListNode, type VaultReadExpectations } 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";
@@ -94,6 +94,16 @@ export interface BridgeMessage {
      * Undefined for plain `text` messages.
      */
     attachments?: AttachmentMeta[];
+    /**
+     * Files link (`vault_ref`, review 2026-10-01 section 6): references to
+     * FileSafe items, NOT fetched. Open one with POST /v1/vault-read passing
+     * `enclave_id`, `node_id`, `expected_content_hash` = `content_hash` and
+     * `expected_dek_commit` = `dek_commit`; the daemon refuses it if the item
+     * changed after it was shared. `name_hint`/`mime_hint`/`size_hint` are
+     * UNTRUSTED claims by the sender, data only (like `speaker`): never a path,
+     * an instruction or an authorization input. Undefined for every other turn.
+     */
+    vault_refs?: VaultRefEntry[];
     /**
      * Task 4 (voice-mode carrier): true when the InboxEntry that produced this
      * buffered message had `voiceMode` set by the server (the agent device's
@@ -129,6 +139,8 @@ export interface BridgeMessage {
  * for voice-flagged turns. Selected by `InboxEntry.voiceMode` in the entry
  * loop below — never transmitted, never a playback trigger.
  */
+/** Files link: the turn text of a `vault_ref` that carries no caption. */
+export declare const VAULT_REF_BARE_TEXT = "[Files link]";
 export declare const VOICE_MODE_GUIDANCE = "Reply immediately and conversationally, one short sentence per message; never bundle multiple points into one message.";
 /**
  * Task 2 (room voice guidance): compiled reply guidance for a voice-flagged
@@ -370,7 +382,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
@@ -678,6 +690,8 @@ export declare class BridgeAgent {
      * counter is incremented. Surfaced on health()/metrics().
      */
     private failedAttachments;
+    /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding). */
+    private refusedVaultRefs;
     /**
      * Task 4 (self-hosted fast voice): test/deploy seam for the fast-path LLM
      * client. Undefined whenever `cfg.voice?.fastPath.enabled` is not true —
@@ -718,6 +732,16 @@ 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;
+    /** 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
@@ -1581,7 +1605,7 @@ export declare class BridgeAgent {
      *  useVault.downloadFile returns `{name, bytes}` in-memory — here the
      *  caller already supplies nodeId so we return bytes, not a re-resolved
      *  name the bridge has no cached listing to look up). */
-    vaultRead(enclaveId: string, vaultChannelId: string | null | undefined, nodeId: string): Promise<{
+    vaultRead(enclaveId: string, vaultChannelId: string | null | undefined, nodeId: string, expected?: VaultReadExpectations): Promise<{
         bytes_b64: string;
     }>;
     /** List + decrypt names for the vault nodes under `parentId` (null = root). */
@@ -1618,37 +1642,69 @@ 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 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;
+    /**
+     * 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>;
+    /** 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;
     /**
      * List channels in one enclave (default: the daemon's own home enclave).
      * Task 3: called per-*known* enclave by refreshChannelMeta so a
@@ -1703,6 +1759,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:
@@ -2142,12 +2207,20 @@ export declare class BridgeAgent {
         custody_store_unavailable: boolean;
         /** Track 5: cumulative artifact_share messages where download/decrypt/digest failed (fail-soft — acked, no redeliver). */
         failed_attachments: number;
+        /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding), acked. */
+        refused_vault_refs: number;
         /** Task 4 (self-hosted fast voice): cumulative fast-path replies actually sent. */
         fast_path_sent: number;
         /** Task 4 (self-hosted fast voice): cumulative fast-path attempts that errored (LLM call, normalization, or send) — fail-soft, never blocks the buffered turn. */
         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"). */
@@ -2292,6 +2365,8 @@ export declare class BridgeAgent {
         welcomeRequestsSent: number;
         /** Track 5: cumulative artifact_share failures (download/decrypt/digest). */
         failedAttachments: number;
+        /** Files link: vault_ref bodies refused by R1 (strict parse) or R2 (enclave binding), acked. */
+        refusedVaultRefs: number;
         /** SDK-6: bridge build id, so a /v1/metrics reading captured across a daemon
          * restart can be attributed to a version — counters are process-lifetime
          * and zero on restart (spec §5.5). */

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: {

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" | "agent_paused" | "send_forbidden" | "group_superseded" | "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" | "vault_ref_changed" | "internal";
 export interface BridgeErrorSpec {
     /** HTTP status this code maps to (the WS binding ignores it). */
     http: number;

package/dist/http-server.d.ts

@@ -43,6 +43,7 @@ export declare function capabilities(opts: {
     receive_modes: string[];
     send_types: string[];
     webhook_push: boolean;
+    vault_ref: number;
 };
 export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     conversation_id: z.ZodString;
@@ -56,7 +57,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
@@ -64,7 +65,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
@@ -72,7 +73,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;
@@ -80,7 +81,7 @@ export declare const memoryRecordSchema: z.ZodEffects<z.ZodObject<{
     text: string;
     role: "agent" | "peer";
     conversation_id: string;
-    modality: "voice" | "text";
+    modality: "text" | "voice";
     message_id?: string | undefined;
     idempotency_key?: string | undefined;
     peer_id?: string | undefined;