@securecoms/agent-bridge 0.30.3 → 0.31.0

package/dist/bridge-agent.d.ts

@@ -41,6 +41,7 @@ import { type UnifiedFrameItem } from "./memory/unified/read-book.js";
 import { type MemoryNoteResultFrame } from "./memory/note-frames.js";
 import { type ChatMessage } from "./voice/fast-prompt.js";
 import { VOICE_CALL_START_MARKER } from "./voice/prompt-compiler.js";
+import { type CallBufferTurn } from "./voice/call-buffer.js";
 import { type VaultListNode, type VaultReadExpectations } from "./vault.js";
 import type { AgentActionNodeType, AgentActionNodeStatus, AgentActionNodeDetail } from "@agentvault/connect-core";
 import { removeManagedLlmSource, writeManagedFiles, writeManifestPolicy } from "./service/runtime-config-dir.js";
@@ -69,10 +70,12 @@ export type BridgeToolGrant =
  * 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
- * that DM's pinned human counterpart AND server-marked `is_agent_owner` (or a
- * relayed voice turn whose speaker is). The pin is per channel, so the
+ * lands, the owner DM's constant grant lists are OWNER_DM_DEFAULT_READ_GRANTS
+ * (`current_time` + `web_search`, read mode) on a typed turn whose sender is
+ * that DM's pinned human counterpart AND server-marked `is_agent_owner`, and
+ * RELAYED_VOICE_GRANTS (equal today, never manifest-eligible) on a relayed
+ * voice turn whose speaker is, or on any voice-scoped owner turn (P-5, G-1).
+ * The pin is per channel, so the
  * owner distinction rests on the server's flag: see authorizationFor's LIMIT
  * note. Every
  * other audience, an unpinned or anomalous owner, and the kill switch
@@ -101,9 +104,17 @@ export declare const OWNER_DM_DEFAULT_READ_GRANTS: readonly BridgeToolGrant[];
  */
 export declare const ROOM_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.
+ * Voice fast-path privacy, P-5 (spec §9). The grants of a relayed owner voice turn (and, from Task 4, of every
+ * voice-scoped owner turn). A constant of its own, frozen and written out, so a later change to
+ * OWNER_DM_DEFAULT_READ_GRANTS cannot widen a spoken turn. It still passes through effectiveToolGrants in
+ * authorizationFor, so the owner's signed web_search off-switch holds. Equal to the owner-DM default today.
+ */
+export declare const RELAYED_VOICE_GRANTS: readonly BridgeToolGrant[];
+/**
+ * Kill switch for OWNER_DM_DEFAULT_READ_GRANTS and RELAYED_VOICE_GRANTS (the
+ * relayed owner voice turn and every voice-scoped owner turn), 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.
  */
 /** Audit L-2: the owner replay prune runs at most once per this interval. */
 export declare const OWNER_REPLAY_PRUNE_INTERVAL_MS: number;
@@ -143,7 +154,8 @@ export interface BridgeAuthorization {
      * owner-DM kill switch is on. Present only when true. An OFFER HINT: the
      * bridge's W1 to W8 are the gate. Never set on the ownerRelayed branch
      * (OQ-C, Eric approved 2026-10-06): voice turns read notes, never write,
-     * and never on any turn with a relay speaker claim (review I-1).
+     * and never on any turn with a relay speaker claim (review I-1), nor on a
+     * voice-scoped owner-direct turn (G-1, voice fast-path privacy spec §1).
      * NOT a tool grant: it is not, and must never be, in `tool_grants`.
      * Reaches only the per-tool runtime consumer: withConsumerGrants strips it
      * for a harness socket and the HTTP/SSE paths (review m-3).
@@ -278,6 +290,12 @@ export interface BridgeMessage {
         identityId: string;
         displayName: string;
     };
+    /**
+     * Voice fast-path privacy, Task 4 (spec §1): set when the ingest loop found the turn VOICE-SCOPED (isVoiceScopedTurn:
+     * VS-1 relay speaker, VS-2 `transcribed`, VS-3 relay sender, VS-4 call-start marker). Absent on every other turn,
+     * including a typed message sent during a live call. A narrowing mark only: it never widens anything.
+     */
+    voice_scoped?: true;
 }
 /**
  * Task 4 (voice-mode carrier): the one-sentence reply guidance compiled in
@@ -660,6 +678,22 @@ export interface SendOptions {
     inReplyTo?: string;
     /** SEC-06 #18: caller idempotency key (WS path); names the reply part. */
     idempotencyKey?: string;
+    /**
+     * Voice fast-path privacy, Task 4b (spec §2.1 agent appends, §2.2 A-3): set ONLY by the ws send handler, computed at
+     * frame arrival, for a per-tool SecureComs runtime socket with no harness claim whose `in_reply_to` was in flight on
+     * THAT socket (same delivery), for the same channel, and not retired. Only such a reply to a voice-scoped turn may
+     * enter the call buffer. `POST /v1/send`, SSE and harness replies never set it.
+     */
+    callBufferReply?: true;
+}
+/**
+ * Task 4b (spec §2.2 A-6): a voice-scoped turn's history, read ONCE at ingest, the buffer seq it ends at and the
+ * buffer's reset generation then (final fix M-4: agent lines of a later call never join it).
+ */
+export interface VoiceSnapshot {
+    recent: CallBufferTurn[];
+    endSeq: number;
+    generation: number;
 }
 /**
  * B7 (FileSafe vault): a file-backed {@link OwnerAuthorityStore} for the
@@ -1390,6 +1424,11 @@ export declare class BridgeAgent {
     private startedAt;
     private readonly store;
     private readonly memory;
+    /**
+     * Voice fast-path privacy, Task 4b (spec §2.1, OQ-1 ruled): the current calls' spoken turns, in process only. The
+     * ONLY history a voice-scoped turn sees; read through voiceScopedHistory, once per turn, at ingest.
+     */
+    private readonly callBuffer;
     /**
      * Markdown memory 7a: the one owner of every note mutation and of the
      * delivery cache (spec §6.3, §7.2). One per store, so one per identity.
@@ -2219,6 +2258,18 @@ export declare class BridgeAgent {
      * its own text, never the prior-turn history snapshot, for every provider.
      */
     private mayReadHistoryForTurn;
+    /**
+     * Voice fast-path privacy (spec §2.1, OQ-1 ruled): the ONLY history source of a voice-scoped turn, the call buffer.
+     * Never reads the memory provider, the store, the unified store or the 7b index. A-6: called once per turn, at ingest
+     * (takeVoiceSnapshot), after the reset signals and before the turn's own append.
+     */
+    private voiceScopedHistory;
+    /**
+     * Task 4b (A-6): the turn's snapshot, taken BEFORE its own text is appended (audit finding 2). Final fix I-1: a turn
+     * already admitted to this call (a redelivered row) is snapshotted up to just before its own entry, as it was the
+     * first time, so its snapshot never contains itself.
+     */
+    private takeVoiceSnapshot;
     /** An inbound turn may receive OpenClaw memory only from an active owner DM. */
     private mayReadOpenClawMemoryForTurn;
     /**
@@ -2227,6 +2278,12 @@ export declare class BridgeAgent {
      * never falls back to the runtime's retired plaintext JSON files.
      */
     private memoryForTurn;
+    /**
+     * Task 6 (spec §2.2 A-1, N1): call-buffer entries as runtime-frame turns. Under the voice fence (a pin is loaded) the
+     * fast model's own lines (origin "fast_path") are dropped, as fenceMemory drops them from store history; the fast
+     * prompt keeps them. The internal origin is not carried into the frame; `seq` stays 0 (A-5).
+     */
+    private voiceFrameTurns;
     /**
      * Owner grants plan 4 Task 16 (T-30, audit r2 H-1): the voice fence is on whenever a pin is loaded, on EVERY runtime
      * turn (manifest, fallback, greeting, relayed, constants-only alike). It never depends on a turn's grants.
@@ -2336,6 +2393,12 @@ export declare class BridgeAgent {
      * but lack an epoch give no recall (fail closed). Never throws.
      */
     private prepareRecallForTurn;
+    /**
+     * Voice fast-path privacy, Task 7 (spec §4): the frame-keyed delivery check. A voice-scoped frame gets no notes, no
+     * recall and no unified items, whatever its authorization says. Keys on the frame's own marks, NEVER on the call
+     * buffer's id set (a reset evicts ids; the staged frame must stay scoped).
+     */
+    private frameIsVoiceScoped;
     /** ws flush (synchronous). Q1 to Q3 and Q6 again at delivery, on the ORIGINAL message; Q4 lives in withConsumerRecall. */
     recallForDelivery(m: BridgeMessage): readonly RecallItem[] | undefined;
     /** ws-server: a runtime socket with no harness claim declared memory_recall. */
@@ -2590,7 +2653,13 @@ 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). */
+    /**
+     * Send a line the voice fast path speaks: its memory record is "voice" (H1).
+     * Task 4b (spec §2.1 agent appends (1), A-1, A-2): once published, the line enters the call buffer as "fast_path",
+     * unless the turn it answers failed owner verification (its id, or any fragment of a coalesced turn). A line answering
+     * a turn the ingest did not find voice-scoped is not appended either (defense in depth: the fast path fires only on
+     * voice-scoped turns, Task 5).
+     */
     private sendSpoken;
     /** Speak a fixed acknowledgement line; failures are counted, never thrown. */
     private sendFastLine;
@@ -2599,8 +2668,8 @@ export declare class BridgeAgent {
      * 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
+     * MUST NEVER throw: every failure path (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
@@ -2856,17 +2925,22 @@ export declare class BridgeAgent {
      * 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
+     * Grants (architect ruling 2026-10-02; P-5 and G-1, spec §9): an owner-DM
+     * constant only when the kill switch is on, the channel is a DM, and EITHER
      *   (a) audience is owner_dm AND the sender is the channel's pinned DM
      *       counterpart (`channelOwner`, never "anomalous"). A server-marked
      *       `is_agent_owner` on a member who is NOT the DM's single human
      *       counterpart gets nothing; on the counterpart it is trusted (see
-     *       LIMIT below); OR
+     *       LIMIT below). OWNER_DM_DEFAULT_READ_GRANTS on a typed turn;
+     *       RELAYED_VOICE_GRANTS and no memory_write when `opts.voiceScoped`
+     *       (G-1: the ingest predicate isVoiceScopedTurn, spec §1); 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.
+     *       owner: RELAYED_VOICE_GRANTS. A speaker claim from any non-relay
+     *       sender gets nothing.
+     * RELAYED_VOICE_GRANTS is never manifest-eligible: effectiveToolGrants gives
+     * the constant by reference, or the fallback when a good manifest is held.
      * Both need the roster fetched at `heldEpoch` (the agent's current MLS
      * epoch for the channel), or the DM marked epoch-fresh at this ingest
      * cycle's refresh (audit M-B4).