@securecoms/agent-bridge 0.31.0 → 0.33.0

package/dist/service/runtime-config-dir.d.ts

@@ -46,7 +46,8 @@ export declare const LOCAL_REPORT_FILE = "local-config.json";
  * and it never affects which file the runtime actually reads.
  */
 export interface LocalReport {
-    persona: Record<string, string>;
+    /** F-0 (spec D-3): name and UTF-8 size of each non-blank persona file. The text never leaves readLocalReport. */
+    local_persona_files: LocalPersonaFileReport[];
     has_search_key: boolean;
     has_llm_key: boolean;
     /** L-2 (spec §7.9): a readable key for an extract-capable provider. Only a real true counts; absent is false. */
@@ -64,6 +65,11 @@ export interface LocalReport {
  * so no path (the owner's `allowed_secret_paths` sits in the same file) can
  * ride along to the backend.
  */
+export declare const LOCAL_PERSONA_FILE_NAMES: readonly ["IDENTITY.md", "SOUL.md", "AGENTS.md"];
+export interface LocalPersonaFileReport {
+    name: (typeof LOCAL_PERSONA_FILE_NAMES)[number];
+    bytes: number;
+}
 export interface SecretPathsReport {
     mode: "report" | "enforce";
     inside: number;
@@ -80,11 +86,11 @@ export interface SecretPathsReport {
 export type LegacyMemoryKind = "global-memory" | "conversation-history" | "captured-memory";
 export declare const LEGACY_MEMORY_FACT_MAX_BYTES = 1024;
 export declare const LEGACY_MEMORY_FACT_DECISION_MAX = 500;
+/** What leaves the machine for one legacy source: metadata only (F-0 G-5). Never `content`, never `path`. */
 export interface LegacyMemoryReport {
     id: string;
     kind: LegacyMemoryKind;
     channel_id?: string;
-    content: string | null;
     bytes: number;
     exportable: boolean;
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const BRIDGE_VERSION = "0.31.0";
+export declare const BRIDGE_VERSION = "0.33.0";

package/dist/voice/persona.d.ts

@@ -28,6 +28,10 @@ export interface FastPathConfig {
     maxTokens: number;
     /** Extra request headers. Set only by settingsToVoiceConfig (the SecureComs proxy); never by parseVoiceConfig. */
     headers?: Readonly<Record<string, string>>;
+    /** E.2 (spec §6, OQ-4): the credential file's explicit opt-in to call this provider directly from the agent's
+     *  machine. Set only by parseVoiceConfig, only for `route: "direct"`; a backend settings fetch then never replaces
+     *  this config with the SecureComs proxy's. */
+    route?: "direct";
 }
 export interface VoiceConfig {
     persona: VoicePersona;

package/dist/voice-channel-binding.d.ts

@@ -0,0 +1,201 @@
+/**
+ * ADR-0024 step 2a, plan Task 19 (spec §9, B.8): the lookup and binding rule for the hidden per-conversation voice
+ * channel V (channel_kind "voice", immutable parent_channel_id = P).
+ *
+ * Pure functions plus one small cache class; BridgeAgent holds only the wiring (network reads, held MLS state, the
+ * ingest cycle). Nothing here logs, reads message content or touches the network.
+ *
+ * Lookup. V is hidden from the enclave listing, so it reaches the bridge as an unknown channel (a Welcome or a row).
+ * The bridge resolves it with GET /api/v1/channels/{V}, which returns channel_kind "voice" and parent_channel_id to a
+ * P member and the same 404 to an absent channel and to an unauthorized caller. Only a 200 voice row with a parent is
+ * cached forever (the parent link is immutable, spec §1). This channel's own 200 row with another kind is cached as
+ * "not a V" (channel_kind is immutable); any other 200, and a voice claim without a usable parent, is an error. A 404 or an error is retried with a bounded back-off: 30 s, doubling, capped at 10 min, never given up
+ * (a 404 can become a 200 once the bridge's own Welcome lands).
+ *
+ * Binding. The bridge binds V to P only when, in its OWN ratchet trees at their current epochs, every leaf identity
+ * of V is a leaf identity of P, or exactly one identity R that is not a leaf of P and that V's member list marks
+ * is_relay. Any other leaf, a second non-P identity (even a second relay), a non-basic credential, or a tree the
+ * bridge does not hold refuses. A P member not yet in V is allowed.
+ */
+/** One non-blank leaf, as `MlsGroupKeyProvider.leafTreeSummary` reports it (identity null for a non-basic credential). */
+export interface VoiceLeaf {
+    readonly basic: boolean;
+    readonly identity: string | null;
+}
+/** A local ratchet tree summary: `ownLeafIndex` null means the bridge holds no group for the channel. */
+export interface VoiceTreeSummary {
+    readonly ownLeafIndex: number | null;
+    readonly leaves: readonly VoiceLeaf[];
+}
+export type VoiceBindingRefusal = 
+/** The bridge holds no V group (an empty tree is not a vacuous subset of P). */
+"v_not_held"
+/** The bridge holds no P group. */
+ | "p_not_held"
+/** A leaf of V (or P) carries a non-basic credential, whose identity cannot be compared. */
+ | "non_basic_leaf"
+/** Exactly one non-P identity, and V's member list does not mark it is_relay. */
+ | "foreign_leaf"
+/** Two or more non-P identities, whatever their relay marks. */
+ | "two_non_parent"
+/** Task 20 ruling 2: two or more V leaf identities that V's member list marks is_relay (P leaves or not). */
+ | "two_relays"
+/** Exactly one non-P identity, and V's member list could not be read. */
+ | "relay_unknown"
+/** The trees moved while they were read; re-evaluated next time (fail closed meanwhile). */
+ | "moved"
+/** parent_channel_id names a known V, or a channel no listing has classified (fix M-4). */
+ | "parent_not_conversation";
+export type VoiceBindingVerdict = {
+    readonly bound: true;
+} | {
+    readonly bound: false;
+    readonly reason: VoiceBindingRefusal;
+};
+/**
+ * The binding rule (spec §9). `isVRelay` reads V's member list (server-set `is_relay`); `undefined` means the list is
+ * unavailable, which refuses only when a relay candidate actually needs it.
+ */
+export declare function evaluateVoiceBinding(v: VoiceTreeSummary, p: VoiceTreeSummary, isVRelay: ((identityId: string) => boolean) | undefined): VoiceBindingVerdict;
+/**
+ * Task 20 ruling 2: R, the relay identity a bound V admits: the unique V leaf identity V's fresh member list marks
+ * is_relay, whether or not it is also a P leaf. Undefined when there is none, more than one, or the list is unreadable
+ * (no relay frame is accepted then). Call it only for a V that {@link evaluateVoiceBinding} bound on the same inputs.
+ */
+export declare function voiceRelayIdentity(v: VoiceTreeSummary, isVRelay: ((identityId: string) => boolean) | undefined): string | undefined;
+/** What one get_channel(V) answer means. */
+export type VoiceResolution = {
+    readonly kind: "voice";
+    readonly parentChannelId: string;
+} | {
+    readonly kind: "not_voice";
+}
+/** 404: absent, or not visible to this caller (the route answers both the same). */
+ | {
+    readonly kind: "absent";
+}
+/** Any other status, a network error, or a voice row without a usable parent. */
+ | {
+    readonly kind: "error";
+};
+/** Classify a get_channel response. `status` is "threw" for a network error or deadline. */
+export declare function parseVoiceResolution(channelId: string, status: number | "threw", body: unknown): VoiceResolution;
+/** First retry after a failed lookup; doubles per consecutive failure up to {@link VOICE_RESOLVE_RETRY_MAX_MS}. */
+export declare const VOICE_RESOLVE_RETRY_BASE_MS = 30000;
+export declare const VOICE_RESOLVE_RETRY_MAX_MS: number;
+/** Final review M-f: a 404 is retried within this when the bridge holds an MLS group for the channel. */
+export declare const VOICE_RESOLVE_ABSENT_HELD_MAX_MS = 60000;
+/** How the receive cycle treats one channel's frames. */
+export type VoiceChannelGate = 
+/** Not a V: today's path. */
+"normal"
+/** A resolved V, or a channel get_channel answered 404: never a normal channel; acked, not processed. */
+ | "drop"
+/** Unclassified (lookup errored, or not yet tried): not processed and not acked, so it is re-served. */
+ | "hold";
+/** A held MLS position: the group and epoch of one channel's manager. */
+export interface VoicePosition {
+    readonly groupId: string;
+    readonly epoch: number;
+}
+/**
+ * The positions a verdict was computed at (fix I-1, Task 20 R1). `v` is V's held (group, epoch), compared with each
+ * frame's own `openedAt` (the epoch whose secret opened it, from the receive path); null when V was not held. `p` is
+ * P's held (group, epoch) as one string, compared with the frame's conservative pre-batch P stamp (no cross-group order
+ * is known, so any P commit in the frame's batch refuses it).
+ */
+export interface VoiceVerdictPositions {
+    readonly v: VoicePosition | null;
+    readonly p: string;
+}
+/** What the accept filter needs about a bound V, captured with its verdict (Task 20). */
+export interface VoiceFrameContext {
+    readonly parent: string;
+    /** R: the relay identity this binding admitted (ruling 2), if any. */
+    readonly relay: string | undefined;
+    /** P's leaf identities at the verdict's P position. */
+    readonly parentMembers: ReadonlySet<string>;
+}
+/**
+ * Receipt records kept at most. Task 20 R2: nothing is ever evicted (an evicted record let a re-served frame take a
+ * fresh stamp). At the cap a new arrival is simply not recorded, and a frame without a record is refused.
+ */
+export declare const VOICE_RECEIPT_CAP = 10000;
+/**
+ * Final review M-d: a receipt record older than this is pruned when the map is full. Safe since R2's earlier-cycle
+ * guard: a frame first received in an earlier cycle never takes a fresh stamp, record or not. Above the lookup
+ * back-off cap, so a frame held across a lookup outage keeps its record while it can still be re-served.
+ */
+export declare const VOICE_RECEIPT_MAX_AGE_MS: number;
+/** P's held position as the receipt stamp's comparable string. */
+export declare function voiceParentStamp(p: {
+    groupId: string | null;
+    epoch: number | null;
+}): string;
+/**
+ * The V cache: successful resolutions (forever), failures (bounded back-off), and each V's current binding verdict.
+ * Time is passed in, so the class is deterministic.
+ */
+export declare class VoiceChannelRegistry {
+    private readonly parents;
+    private readonly notVoice;
+    private readonly failures;
+    private readonly bindings;
+    private readonly generations;
+    /** Fix I-1 / Task 20 R1: message id -> P's held position before the batch that first received it; null = not knowable. */
+    private readonly receipts;
+    /** Final review M-d: arrivals not recorded because the map was full of young records. */
+    private capReached;
+    /** True when a lookup should run now: never once resolved; after a failure, only past its back-off. */
+    resolveDue(channelId: string, now: number, opts?: {
+        heldGroup?: boolean;
+    }): boolean;
+    record(channelId: string, r: VoiceResolution, now: number): void;
+    /** True once get_channel has answered for this channel (voice or not). */
+    isResolved(channelId: string): boolean;
+    /** Final review M-a: true once get_channel answered this channel's own row with a kind other than voice. */
+    isNotVoice(channelId: string): boolean;
+    /** Final review (R∈P): bound Vs whose admitted R is also a P leaf (the pre-stamp shape; a sunset signal). */
+    relayInParentCount(): number;
+    /** True for a resolved V, bound or not. */
+    isVoice(channelId: string): boolean;
+    /** P of a resolved V, bound or not; undefined otherwise. Never use this to route: see {@link boundParentOf}. */
+    parentOf(channelId: string): string | undefined;
+    /** Every resolved V with its P. */
+    voiceChannels(): Array<[string, string]>;
+    /** The gate for a channel the bridge's listing has never classified (`unlisted`), or for a resolved V. */
+    gate(channelId: string, unlisted: boolean): VoiceChannelGate;
+    bindingKey(channelId: string): string | undefined;
+    setBinding(channelId: string, key: string, verdict: VoiceBindingVerdict, positions?: VoiceVerdictPositions | null, admitted?: {
+        relay?: string;
+        parentMembers?: ReadonlySet<string>;
+    }): void;
+    /** Fix M-1: each evaluation of a V takes a generation; only the newest started may store its verdict. */
+    beginEvaluation(channelId: string): number;
+    isLatestEvaluation(channelId: string, generation: number): boolean;
+    /**
+     * Fix I-1: records a frame's receipt stamp the FIRST time it is seen; a re-served frame keeps its first record.
+     * Task 20 R2: at the cap nothing is evicted and the new arrival is not recorded (refused: no record, no parent).
+     */
+    noteReceipt(messageId: string, pStamp: string | null, now?: number): void;
+    /** Final review M-d: arrivals refused because the receipt map was full (a number only). */
+    receiptCapReached(): number;
+    /** Test visibility: receipt records held. */
+    receiptCount(): number;
+    forgetReceipt(messageId: string): void;
+    /**
+     * Fix I-1: P for one frame on V only when V is bound now AND both groups' held positions are exactly those at the
+     * frame's receipt. A frame received at other positions (or with none recorded) gets undefined: dropped, never held.
+     */
+    boundParentForFrame(channelId: string, messageId: string, openedAt?: VoicePosition | null): string | undefined;
+    /**
+     * Task 20: the per-frame verdict with what the accept filter needs. Bound now AND the frame's pre-batch P stamp equals
+     * the verdict's P position AND (R1) the frame's own opening position equals the verdict's V position. A frame with
+     * no record, a null record, or no `openedAt` is refused.
+     */
+    frameContext(channelId: string, messageId: string, openedAt?: VoicePosition | null): VoiceFrameContext | undefined;
+    /** The current verdict, or undefined when never evaluated. */
+    binding(channelId: string): VoiceBindingVerdict | undefined;
+    /** P only while V is a resolved V whose last verdict is bound; undefined otherwise. */
+    boundParentOf(channelId: string): string | undefined;
+}

package/dist/voice-channel-frame.d.ts

@@ -0,0 +1,22 @@
+export type VoiceFrameClass = 
+/** A text frame from R: a model turn (voice-scoped by VS-3). */
+"relay_turn"
+/** The call-start greeting marker from a P member (VS-4). */
+ | "greeting"
+/** A call transcript: acked, not a model turn. */
+ | "call_transcript"
+/** Anything else: dropped unprocessed, never recorded. */
+ | "drop";
+export interface VoiceFrameInput {
+    /** The envelope's sender identity. */
+    readonly senderId: string;
+    /** This agent's own identity (its own frames are never a turn). */
+    readonly ownIdentityId: string;
+    /** R, or undefined when the binding admitted no relay. */
+    readonly relay: string | undefined;
+    /** P's leaf identities at the verdict's position. */
+    readonly parentMembers: ReadonlySet<string>;
+    /** The decrypted plaintext. */
+    readonly plaintext: Uint8Array;
+}
+export declare function classifyVoiceFrame(f: VoiceFrameInput): VoiceFrameClass;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "type": "module",
   "engines": {
     "node": ">=24"