@securecoms/agent-bridge 0.28.2 → 0.30.0

package/dist/grants/binding.d.ts

@@ -0,0 +1,58 @@
+import { type ToolGrantManifest } from "./manifest.js";
+import type { ManifestPolicyDoc } from "../service/runtime-config-dir.js";
+export declare const CONFIG_BINDING_FIELDS: readonly ["persona", "memory", "search", "tools_allow", "flags", "llm", "files", "legacy_assign"];
+export type ConfigBindingField = (typeof CONFIG_BINDING_FIELDS)[number];
+export interface BindPayload {
+    readonly version?: number;
+    readonly files?: Record<string, string>;
+    readonly skills_json?: Record<string, unknown>;
+    readonly memory?: unknown;
+    readonly persona?: unknown;
+    /** Raw, unfiltered saved tokens (runtime_config_service.py memory_prunes). Untrusted. */
+    readonly memory_prunes?: unknown;
+    readonly legacy_memory_fact_decisions?: unknown;
+}
+/** The search block last written under a good search match for this pinned key (Task 11's sealed record); undefined = never. */
+export type AppliedSearch = {
+    readonly provider: "brave" | "tavily";
+    readonly keyFile?: string;
+} | null;
+export interface BindPrior {
+    readonly search: AppliedSearch | undefined;
+}
+export interface BindResult {
+    readonly mismatches: readonly ConfigBindingField[];
+    readonly targetMismatches: {
+        readonly endpoint: number;
+        readonly database: number;
+    };
+    readonly files: Record<string, string>;
+    readonly memory: unknown;
+    readonly signedTargets: {
+        readonly endpoints: number;
+        readonly databases: number;
+    };
+    readonly policy: ManifestPolicyDoc;
+    /** Set only when `search` matched: the block written, to be saved as the new last good one after the write succeeds. */
+    readonly appliedSearch: AppliedSearch | undefined;
+    /**
+     * P-5 (Task 14): the decisions to hand applyLegacyMemoryFactDecisions. On a legacy_assign match: the
+     * deletes plus each assign whose token, rebuilt from its own fields, is in the verified saved set. On a
+     * mismatch: the deletes only.
+     */
+    readonly legacyDecisions: unknown[];
+}
+/** P4 OQ-7: hex SHA-256 of JCS(sorted, deduplicated memory_prunes entries that begin "legacy-fact-assign:"). Non-strings are ignored. */
+export declare function legacyAssignSha256(prunes: readonly unknown[]): string;
+/** The backend's assign token (runtime_config_service.py _legacy_memory_fact_decision_token), rebuilt from the fields. */
+export declare function legacyAssignToken(d: {
+    source_id: string;
+    fact_hash: string;
+    channel_id: string;
+}): string;
+export declare function bindRuntimeConfig(manifest: ToolGrantManifest, payload: BindPayload, prior: BindPrior, 
+/** Review H-1: the two manifest kill switches; an audience switched off contributes no tool to the policy file. */
+switches?: {
+    readonly ownerDm: boolean;
+    readonly room: boolean;
+}): BindResult;

package/dist/grants/effective.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The effective grant (owner-signed tool grants, spec §5.2, §5.4, §7.4; plan 4 Task 6).
+ * The one formula, pure, so every rule has its own test and the issuing code decides nothing.
+ *
+ *   signed(a)    = manifest.grants[a] ∩ TOOL_GRANT_CODE_CEILING[a]
+ *   effective(a) = signed(a) ∖ disabled, minus http_request with no signed endpoint, minus sql_query
+ *                  with no signed database, minus team_room web_search when capped, ∪ {current_time}
+ *                  (only when every precondition holds: `eligible` and the manifest switch on)
+ *   fallback(a)  = (constants(a) ∩ signed(a)) ∪ {current_time}   when a precondition fails
+ *                = constants(a) by reference                      with no good manifest
+ *   []                                                            when today's predicate gives []
+ */
+import { type ToolGrantManifest } from "./manifest.js";
+/** Spec §5.4 code ceiling. The same frozen lists Plan 1 uses to drop unknown entries. */
+export declare const TOOL_GRANT_CODE_CEILING: {
+    readonly owner_dm: readonly string[];
+    readonly team_room: readonly string[];
+};
+export type GrantAudience = "owner_dm" | "team_room";
+export type GrantSource = "constant" | "manifest" | "fallback" | "none";
+export interface ReadGrant {
+    readonly tool: string;
+    readonly mode: "read";
+    readonly source?: "manifest";
+}
+export interface EffectiveInput {
+    readonly audience: GrantAudience;
+    /** Today's list from the existing predicate: OWNER_DM_DEFAULT_READ_GRANTS, ROOM_DEFAULT_READ_GRANTS, or a frozen []. */
+    readonly base: readonly ReadGrant[];
+    /** The last good manifest, or null (no pin, or none verified). */
+    readonly manifest: ToolGrantManifest | null;
+    /** Every manifest-only precondition held (Task 13 computes it). */
+    readonly eligible: boolean;
+    readonly manifestSwitchOn: boolean;
+    readonly disabled: ReadonlySet<string>;
+    readonly signedTargets: {
+        readonly endpoints: number;
+        readonly databases: number;
+    };
+    readonly roomSearchCapped: boolean;
+}
+export interface EffectiveGrant {
+    readonly grants: readonly ReadGrant[];
+    readonly source: GrantSource;
+    readonly withheldBySearchCap: boolean;
+}
+export declare function effectiveToolGrants(i: EffectiveInput): EffectiveGrant;

package/dist/grants/manifest.d.ts

@@ -0,0 +1,68 @@
+import { type OwnerGrantPin } from "./pin.js";
+export declare const TOOL_GRANTS_DOMAIN = "SECURECOMS-TOOL-GRANTS-V1:";
+export declare const MANIFEST_STATES: readonly ["ok", "unchanged", "no_pin", "no_manifest", "malformed", "unsupported_algo", "bad_signature", "wrong_agent", "wrong_owner", "rollback", "unknown_entry", "kept_last_good"];
+export type ManifestState = (typeof MANIFEST_STATES)[number];
+/** Known names only for dropping unknown entries (§7.1 step 6). These are the §5.4 code-ceiling names; step 4 uses them as the ceiling. */
+export declare const MANIFEST_KNOWN_TOOLS: {
+    readonly owner_dm: readonly string[];
+    readonly team_room: readonly string[];
+};
+export interface ToolGrantManifest {
+    readonly type: "securecoms.tool-grants";
+    readonly v: 1;
+    readonly agent_identity_id: string;
+    readonly owner_identity_id: string;
+    readonly owner_dm_channel_id?: string;
+    readonly owner_dm_relay_identity_id?: string;
+    readonly counter: number;
+    readonly grants: {
+        readonly owner_dm?: readonly string[];
+        readonly team_room?: readonly string[];
+    };
+    /** Plan 4 Task 7 (spec §8.1): signed targets. Absent in the wrapper = {}. A `headersFile: ""` is dropped (L-4). */
+    readonly endpoints: Readonly<Record<string, SignedEndpoint>>;
+    readonly databases: Readonly<Record<string, SignedDatabase>>;
+    /** Plan 4 Task 7 (spec §8.1, §7.10): the signed values the config binding compares. Required. */
+    readonly config: SignedConfig;
+}
+export interface SignedEndpoint {
+    readonly baseUrl: string;
+    readonly headersFile?: string;
+}
+export type SignedDatabase = {
+    readonly sqlite: string;
+} | {
+    readonly postgresUrlFile: string;
+};
+export interface SignedConfig {
+    readonly persona_sha256: string;
+    readonly llm?: {
+        readonly provider: string;
+        readonly model: string;
+    };
+    readonly search?: {
+        readonly provider: "brave" | "tavily";
+    };
+    readonly tools_allow?: readonly string[];
+    readonly flags: readonly string[];
+    readonly memory: {
+        readonly mode: "markdown" | "semantic" | "off";
+        readonly recall_days?: 30 | 90 | 365;
+    };
+    readonly legacy_assign_sha256: string;
+}
+export type ManifestVerdict = {
+    state: "ok";
+    manifest: ToolGrantManifest;
+    droppedUnknown: boolean;
+    wrapper: unknown;
+} | {
+    state: "unchanged" | "malformed" | "unsupported_algo" | "bad_signature" | "wrong_agent" | "wrong_owner" | "rollback";
+};
+/** utf8(TOOL_GRANTS_DOMAIN) || canonicalize(manifest). The domain keeps an envelope signature from ever verifying as a manifest. */
+export declare function manifestSignedBytes(manifest: unknown): Uint8Array;
+export declare function verifyToolGrantManifest(raw: unknown, ctx: {
+    pin: OwnerGrantPin;
+    agentIdentityId: string;
+    storedCounter: number | null;
+}): ManifestVerdict;

package/dist/grants/owner-turn.d.ts

@@ -0,0 +1,52 @@
+import type { AgentVaultEnvelope } from "@agentvault/connect-core";
+import { type OwnerGrantPin } from "./pin.js";
+export declare const OWNER_VERIFY_STATES: readonly ["ok", "bad_signature", "malformed", "unknown_algo", "no_signature", "not_owner_dm_leaves", "wrong_dm_channel", "replay", "verify_error"];
+export type OwnerVerifyFailure = Exclude<(typeof OWNER_VERIFY_STATES)[number], "ok">;
+export type OwnerTurnVerdict = {
+    readonly kind: "unchecked";
+} | {
+    readonly kind: "verified";
+    readonly replay: {
+        readonly channelId: string;
+        readonly groupId: string;
+        readonly epoch: number;
+    };
+} | {
+    readonly kind: "constants_only";
+    readonly replay: {
+        readonly channelId: string;
+        readonly groupId: string;
+        readonly epoch: number;
+    };
+} | {
+    readonly kind: "failed";
+    readonly reason: OwnerVerifyFailure;
+};
+export type OwnerSignatureResult = {
+    readonly state: "ok";
+    readonly envelope: AgentVaultEnvelope;
+} | {
+    readonly state: "no_signature" | "bad_signature" | "malformed" | "unknown_algo";
+};
+export declare function verifyOwnerSignature(entry: {
+    readonly payloadHex?: string;
+    readonly identitySignature?: string;
+}, pin: OwnerGrantPin): OwnerSignatureResult;
+export type OwnerDmLeafClass = "ok" | "unsigned_relay" | "foreign";
+/**
+ * §7.2 check 2, decision D-4. Any number of owner leaves passes (multi-device:
+ * leaf credentials encode identity, not device). Fails closed on an empty tree,
+ * a non-basic leaf, or no owner leaf. A signed relay is admitted by
+ * `relayIdentityId` alone; the roster flag only chooses between
+ * `unsigned_relay` (today's constants) and `foreign` (zero), so it can never
+ * widen past today's constants.
+ */
+export declare function classifyOwnerDmLeaves(leaves: readonly {
+    basic: boolean;
+    identity: string | null;
+}[], allowed: {
+    ownerIdentityId: string;
+    agentIdentityId: string;
+    relayIdentityId?: string;
+    isServerRelay: (identityId: string) => boolean;
+}): OwnerDmLeafClass;

package/dist/grants/persona-render.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The bridge's persona renderer (owner-signed tool grants, spec §7.12; plan 4 Task 8).
+ *
+ * Under a manifest the bridge writes IDENTITY.md, SOUL.md and AGENTS.md from the
+ * raw persona whose hash the owner signed, never the server's text. It is a port
+ * of render_persona (backend/app/services/runtime_config_render.py) and is pinned
+ * to it byte for byte by persona-render.vectors.json, which the backend test
+ * test_persona_render_vectors.py re-renders with the Python function.
+ *
+ * Python str.strip() semantics, not JavaScript trim (trim also removes U+FEFF).
+ * `tone` is rendered in a fixed field order (TONE_FIELD_ORDER, the JSONB key
+ * order the backend reads), never the payload's key order (rulings item 8(a)).
+ */
+export declare const PERSONA_MAX_BYTES = 8192;
+export type PersonaRender = {
+    readonly ok: true;
+    readonly files: {
+        "IDENTITY.md": string;
+        "SOUL.md": string;
+        "AGENTS.md": string;
+    };
+} | {
+    readonly ok: false;
+    readonly reason: "shape" | "over_cap";
+};
+/** Postgres JSONB returns object keys shorter-first, then bytewise; render_persona iterates that order. */
+export declare const TONE_FIELD_ORDER: readonly ["humor", "length", "warmth", "formality"];
+export declare function pyStrip(s: string): string;
+/** A port of render_persona(persona, tool_names). Never throws. */
+export declare function renderPersonaFiles(persona: unknown): PersonaRender;

package/dist/grants/pin-command.d.ts

@@ -0,0 +1,31 @@
+export type PinCommandStep = "pin_tmp_written" | "cred_tmp_written" | "pin_renamed" | "cred_renamed";
+export type PinCommandResult = {
+    ok: true;
+    changedKey: boolean;
+} | {
+    ok: false;
+    reason: "pin_invalid" | "credential_invalid" | "symlink_refused" | "agent_mismatch" | "directory_mismatch" | "io_error";
+};
+export declare const PIN_COPY: {
+    readonly saved: string;
+    readonly pinInvalid: string;
+    readonly credentialInvalid: string;
+    readonly symlink: string;
+    readonly ioError: string;
+    readonly agentMismatch: string;
+    readonly directoryMismatch: string;
+    readonly announce: (agentIdentityId: string) => string;
+    readonly usage: string;
+};
+export declare function runPinCommand(opts: {
+    credentialPath: string;
+    pinSourcePath: string;
+    agentIdentityId: string;
+    /** Required. Called exactly once, after every check passes and before the first write, with the credential's identity_id. Never called on a refusal. */
+    announce: (agentIdentityId: string) => void;
+    afterStep?: (s: PinCommandStep) => void;
+}): PinCommandResult;
+export declare function runPinCli(argv: readonly string[], io: {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}): 0 | 1 | 2;

package/dist/grants/pin.d.ts

@@ -0,0 +1,35 @@
+export declare const PIN_FILE_NAME = "owner-signing-key.json";
+export declare const PIN_STATES: readonly ["ok", "no_pin", "pin_conflict", "malformed", "unsupported_algo", "symlink_refused", "unreadable", "server_owner_mismatch"];
+export type PinState = (typeof PIN_STATES)[number];
+export interface OwnerGrantPin {
+    readonly ownerIdentityId: string;
+    readonly keyAlgo: "ed25519";
+    readonly publicKey: Uint8Array;
+    readonly publicKeyB64: string;
+}
+export interface OwnerGrantPinResult {
+    readonly state: Exclude<PinState, "server_owner_mismatch">;
+    readonly pin: OwnerGrantPin | null;
+}
+/** Canonical base64 of exactly `len` bytes: decode, re-encode, compare. */
+export declare function canonicalBase64Bytes(v: unknown, len: number): Uint8Array | null;
+export declare function parsePinObject(v: unknown): {
+    ok: true;
+    pin: OwnerGrantPin;
+} | {
+    ok: false;
+    state: "malformed" | "unsupported_algo";
+};
+export interface PinFs {
+    lstat(path: string): {
+        isSymbolicLink(): boolean;
+        mode: number;
+    };
+    readFile(path: string): string;
+}
+/** Spec §6.5. A symlinked pin file is `symlink_refused` whatever the credential holds. */
+export declare function loadOwnerGrantPin(opts: {
+    credentialPath: string;
+    credentialJson: Record<string, unknown>;
+    fs?: PinFs;
+}): OwnerGrantPinResult;

package/dist/grants/room-search-cap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Owner grants plan 4, Task 12 (spec §7.5, OQ-2, audit r1 L-3): the bridge's copy of the runtime's
+ * operator-cap parser (connect-agent-runtime/src/room-search-cap.ts). The two packages share no
+ * dependency; bridge-agent.room-search-cap.test.ts pins them equal on every listed input.
+ */
+export declare const ROOM_SEARCH_DAILY_CAP = 50;
+export declare const ROOM_SEARCH_CAP_ENV = "SECURECOMS_ROOM_SEARCH_DAILY_CAP";
+/** /^\d+$/ and <= 50 is used (0 = no room search); anything else is 50 with one warning. Never a widening. */
+export declare function parseRoomSearchCap(v: string | undefined, warn?: () => void): number;
+/** Review M-3 (ERIC APPROVALS 3): the per-agent total across rooms, the runtime's parser copied (parity-tested). */
+export declare const AGENT_ROOM_SEARCH_DAILY_CAP = 200;
+export declare const AGENT_ROOM_SEARCH_CAP_ENV = "SECURECOMS_AGENT_ROOM_SEARCH_DAILY_CAP";
+export declare function parseAgentRoomSearchCap(v: string | undefined, warn?: () => void): number;
+/** The store row that holds the per-agent total (never a channel id: channel ids are UUIDs). */
+export declare const AGENT_TOTAL_KEY = "agent-total";

package/dist/grants/voice-fence.d.ts

@@ -0,0 +1,53 @@
+/** "untrusted" (review H-3): an agent reply whose turn saw a relay-class line, or that could not be attributed. */
+export type LineOrigin = "fast_path" | "reply" | "untrusted";
+/** 2026-09-07T00:00:00Z: before this the deterministic fast-reply id did not exist (`date -u -r 1788739200`). */
+export declare const FAST_ID_EPOCH_MS = 1788739200000;
+/**
+ * The unkeyed fastReplyId of e1369a7c (2026-09-06) to 60365953 (2026-09-25): SHA-256 of `fast:<messageId>`, first 16
+ * bytes, RFC 4122 version and variant nibbles, as a hyphenated UUID. Rows of that period carry this form.
+ */
+export declare function legacyFastReplyId(messageId: string): string;
+export interface AgentLine {
+    readonly origin?: LineOrigin;
+    readonly modality?: string;
+    readonly messageId?: string;
+    readonly ts?: number;
+}
+/** `fastIds`: the keyed AND the legacy fast-reply id of every peer row of the conversation (not the 50-row window). */
+export interface FenceContext {
+    readonly fastIds: ReadonlySet<string>;
+}
+/** Rule 4, history. */
+export declare function classifyAgentLine(line: AgentLine, ctx: FenceContext): LineOrigin;
+export interface UnifiedItemFacts {
+    readonly channelId: string;
+    readonly source: string;
+    readonly originId: string;
+    readonly role?: "peer" | "agent";
+    readonly origin?: LineOrigin;
+    readonly sourceRef?: string;
+}
+export type TraceRow = ({
+    readonly role: "peer" | "agent";
+    readonly peerId?: string;
+} & AgentLine) | null;
+/**
+ * Review H-3 (ruling): a peer line is relay-class when its authenticated sender is not the pinned owner identity
+ * (the relay, incl. owner-speaker voice transcripts) or its modality is voice.
+ */
+export declare function isRelayClassPeer(line: {
+    readonly peerId?: string;
+    readonly modality?: string;
+}, ownerId: string): boolean;
+export type Trace = (conversationId: string, at: {
+    seq?: number;
+    messageId?: string;
+}) => TraceRow;
+/**
+ * Rule 4, unified. `strict` (review H-3): a turn that holds a manifest grant, which also excludes owner-voice items
+ * and imported peer lines that trace to a relay-class row (or cannot be traced).
+ */
+export declare function classifyUnifiedItem(item: UnifiedItemFacts, trace: Trace, ctx: FenceContext, strict?: {
+    readonly ownerId: string;
+    readonly turnChannelId?: string;
+}, keepUntrusted?: boolean): "keep" | "exclude";

package/dist/http-server.d.ts

@@ -25,6 +25,7 @@ export declare function writeSse(res: {
 export declare function deliverSseBatch(res: Parameters<typeof writeSse>[0], batch: BridgeMessage[], agent: {
     ackRuntimeMessages(ids: string[]): void;
     requeueFront(msgs: BridgeMessage[]): void;
+    harnessGrantsWithheld(): boolean;
 }, onWriteError?: (error: unknown) => void): void;
 /**
  * Once-per-connection write-failure reporter (#335). A throwing `res.write`