@securecoms/agent-bridge 0.30.1 → 0.30.3

package/dist/bridge-agent.d.ts

@@ -46,6 +46,7 @@ import type { AgentActionNodeType, AgentActionNodeStatus, AgentActionNodeDetail
 import { removeManagedLlmSource, writeManagedFiles, writeManifestPolicy } from "./service/runtime-config-dir.js";
 import { bindRuntimeConfig } from "./grants/binding.js";
 import type { RuntimeReplyReceipt } from "./reply-receipts.js";
+import type { SearchProvider } from "./grants/search-providers.js";
 export type AgentAudience = "owner_dm" | "team_room" | "partner_room" | "other_human_dm" | "agent_to_agent" | "unknown";
 export type BridgeToolGrant = 
 /** `source: "manifest"` (owner grants plan 4): issued from an owner-signed manifest; enforced only by a manifest_grants_v1 runtime. */
@@ -444,6 +445,14 @@ export interface BridgeAgentDeps {
      * see start(). Injected so tests do not wait a minute.
      */
     bootDrainWaitMs?: number;
+    /**
+     * B-4 (D35): the debounce before the runtime-config refetch that follows a search_providers_v2 capability change.
+     * The policy file is rewritten at once; this only bounds the refetch to one per burst. Test seam; production
+     * uses {@link SEARCH_CAPABILITY_REFETCH_DEBOUNCE_MS}.
+     */
+    searchCapabilityRefetchDebounceMs?: number;
+    /** B-4 fix round 1: the longest a burst may defer its refetch after its first change. Test seam. */
+    searchCapabilityRefetchMaxWaitMs?: number;
     /**
      * SEC-06 #18: the wait between in-process reply publish retries after a rate
      * limit. Defaults to an unref'd setTimeout. Injected so tests do not sleep.
@@ -785,6 +794,10 @@ export interface AgentActionAPI {
 export declare const BRIDGE_VERSION: string;
 /** start() waits this long for its boot drain before it stops blocking on it. */
 export declare const BOOT_DRAIN_WAIT_MS_DEFAULT = 60000;
+/** B-4 (D35): the refetch after a search_providers_v2 change waits this long, so a reconnect burst (close, then hello) runs one. */
+export declare const SEARCH_CAPABILITY_REFETCH_DEBOUNCE_MS = 1000;
+/** B-4 fix round 1: a flapping socket still refetches no later than this after the first change of a burst. */
+export declare const SEARCH_CAPABILITY_REFETCH_MAX_WAIT_MS = 10000;
 export declare class BridgeAgent {
     private readonly cfg;
     private readonly transport;
@@ -1174,6 +1187,8 @@ export declare class BridgeAgent {
     private bootSweepTimer?;
     private readonly rng;
     private readonly bootDrainWaitMs;
+    private readonly searchCapabilityRefetchDebounceMs;
+    private readonly searchCapabilityRefetchMaxWaitMs;
     /** Resolved (and cleared) each time an ingest cycle settles: see start(). */
     private ingestSettledWaiters;
     /** The boot key-package publish, when start() had to defer it. Test seam. */
@@ -3299,6 +3314,51 @@ export declare class BridgeAgent {
     noteManifestConsumer(token: object): void;
     clearManifestConsumer(token: object): void;
     manifestConsumerAttached(): boolean;
+    /**
+     * D28 (B-4): every socket that said hello, with whether its latest hello declared search_providers_v2 on the
+     * manifest_grants_v1 predicate (ws-server.ts). The agent value is the AND over all of them, absent (false) with
+     * none: unlike manifestConsumer, never newest wins. The per-delivery filter judges each socket by its own hello.
+     */
+    private readonly searchProvidersSockets;
+    /**
+     * The D28 value the files were last recomputed for; null until the first socket observation, so that observation
+     * always recomputes (final review I-1), even when it is non-capable.
+     */
+    private searchProvidersState;
+    private searchCapabilityRefetchTimer;
+    /** When the current burst's first change happened (valid while the timer is set). */
+    private searchCapabilityBurstStart;
+    /** The D28 value in the last report posted (null until one is); a change needs a refetch to reach the web. */
+    private lastReportedSearchProviders;
+    noteSearchProvidersSocket(token: object, declared: boolean): void;
+    clearSearchProvidersSocket(token: object): void;
+    /** D28: every attached runtime socket declared search_providers_v2; no socket attached means absent (false). */
+    searchProvidersCapable(): boolean;
+    /**
+     * D19 item 3 (B-6): the search provider signed in the stored verified manifest in force (a pin loaded and a good
+     * manifest), never the server payload; undefined with no pin, no manifest, or no signed search block. The
+     * per-delivery filter (consumer-grants.ts withSearchCapability) and the S-28 report reason both read this.
+     */
+    signedSearchProvider(): SearchProvider | undefined;
+    /** D19 item 4, D34: the in-force signed provider is not brave, and the attached runtime(s) lack the capability. */
+    private searchProviderUnsupported;
+    /**
+     * D35 (P-4): on a capability change, rewrite manifest-policy.json at once from the stored manifest, the kill
+     * switches and the new capability, then a debounced refetch (one per burst) only when needed.
+     */
+    private onSearchProvidersMaybeChanged;
+    /**
+     * A refetch re-renders skills.json (owner_dm_search_cap counts web_extract only with the capability, D39) and posts
+     * the report. Needed under a manifest in force, or when the reported value is stale. Never before the boot fetch.
+     */
+    private searchCapabilityRefetchNeeded;
+    /**
+     * D35: the local recompute. Widening (web_extract back in) only while the binding for the in-force manifest stands,
+     * so a policy is never written ahead of its skills.json. Narrowing never waits: with no binding in force, a file that
+     * lists web_extract loses it at once, so an older runtime never reads it as unreadable (which drops every grant).
+     * Content-free; a write failure is logged and the debounced refetch tries again.
+     */
+    private recomputeManifestPolicy;
     noteConsumerCapability(state: "ok" | "missing" | "harness_consumer"): void;
     /**
      * Harness re-rule (2026-10-12, audit r2 H-3): true exactly when this agent has a pin loaded and a good

package/dist/config.d.ts

@@ -56,6 +56,19 @@ export interface BridgeConfig {
     ownerGrantPin?: OwnerGrantPinResult;
 }
 export declare const REQUIRED: readonly ["api_key", "identity_id", "device_id", "signing_private_key", "enclave_id", "api_base"];
+export type ConfigErrorReason = "credential_not_found" | "credential_unreadable" | "credential_not_json" | "credential_missing_field" | "credential_voice_invalid";
+/**
+ * A key-file load failure with a fixed reason code, set by the step that
+ * failed (spec 2026-10-15 §5.2). Callers map the code to a log field and a
+ * fixed human line; nothing reads `message`, which carries no path, no
+ * identifier and no upstream error text.
+ */
+export declare class ConfigError extends Error {
+    readonly reason: ConfigErrorReason;
+    readonly field?: (typeof REQUIRED)[number] | undefined;
+    readonly source?: "file" | "env" | undefined;
+    constructor(reason: ConfigErrorReason, field?: (typeof REQUIRED)[number] | undefined, source?: "file" | "env" | undefined);
+}
 export declare function loadConfig(opts: {
     credentialPath: string;
     storePath?: string;

package/dist/consumer-grants.d.ts

@@ -1,4 +1,5 @@
 import type { BridgeMessage } from "./bridge-agent.js";
+import type { SearchProvider } from "./grants/search-providers.js";
 /**
  * The /v1/ws hello feature a consumer sends to declare per-tool grant
  * enforcement. The runtime exports the same value (connect-agent-runtime
@@ -23,6 +24,8 @@ export declare const PER_TOOL_GRANTS_FEATURE = "per_tool_grants";
 export declare function withConsumerGrants(m: BridgeMessage, perToolConsumer: boolean): BridgeMessage;
 /** The /v1/ws hello feature of a runtime that enforces manifest grants (runtime 0.13.0+). Pinned to the runtime's by capability-parity.test.ts. */
 export declare const MANIFEST_GRANTS_FEATURE = "manifest_grants_v1";
+/** The /v1/ws hello feature of a runtime that supports the five signed search providers and web_extract (spec D3, D28). Pinned to the runtime's by capability-parity.test.ts. */
+export declare const SEARCH_PROVIDERS_FEATURE = "search_providers_v2";
 export declare const CONSTANT_TOOL_NAMES: Readonly<Record<"owner_dm" | "team_room", readonly string[]>>;
 /**
  * Spec §7.9: a consumer that did not declare manifest_grants_v1 (runtime 0.12.2, a harness,
@@ -40,3 +43,15 @@ export declare function withManifestCapability(m: BridgeMessage, manifestConsume
  * Never mutates `m`. Callers: the three harness delivery paths, after withConsumerGrants.
  */
 export declare function withHarnessGrants(m: BridgeMessage, withheld: boolean): BridgeMessage;
+/**
+ * D19 item 3, D34, M-3, P-2 (B-6): the per-delivery search filter, applied on every delivery path AFTER
+ * withManifestCapability (and so after withHarnessGrants), judged by the consumer's OWN hello. A consumer that did not
+ * declare search_providers_v2 (an older runtime, a harness, every HTTP path) never receives:
+ * - a `web_extract` grant, whatever the signed provider (defence in depth beside the policy file, D19 item 1); and
+ * - a `web_search` grant, marked OR unmarked (the owner-DM constant and `constants ∩ signed` included), whenever the
+ *   provider signed in the stored verified manifest is defined and not `brave`. `tavily` too (D34): an older runtime
+ *   reads a readable install-time Brave key first, so only a signed `brave` cannot reach an unsigned vendor.
+ * `signedProvider` comes from the agent's stored verified manifest (BridgeAgent.signedSearchProvider), never the payload.
+ * Every other grant and field is unchanged. Returns `m` by reference when nothing is dropped; never mutates `m`.
+ */
+export declare function withSearchCapability(m: BridgeMessage, consumerHasFeature: boolean, signedProvider: SearchProvider | undefined): BridgeMessage;

package/dist/grants/binding.d.ts

@@ -1,3 +1,17 @@
+/**
+ * The config binding and signed-target composer (owner-signed tool grants, spec §7.8, §7.10, §7.12;
+ * plan 4 Task 10). One pure function decides every file the bridge writes under a manifest.
+ *
+ * Rule: under a manifest the bridge writes a widening input only from a signed value, or from the
+ * payload when it equals the signed value; it never writes a mismatched widening input. Two ruled
+ * exceptions: a mismatched search block is replaced by the last applied good one (rulings item 3), or with none
+ * usable by the signed provider alone with no key file (D24 (i)),
+ * and llm-source.json is always the bridge's own render of the signed provider and model (item 5).
+ *
+ * Never throws (audit r1 H-4): every read of server data goes through `guarded`, and a failure is a
+ * mismatch of that field with nothing written for it.
+ */
+import type { SearchProvider } from "./search-providers.js";
 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"];
@@ -14,7 +28,7 @@ export interface BindPayload {
 }
 /** 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 provider: SearchProvider;
     readonly keyFile?: string;
 } | null;
 export interface BindPrior {
@@ -50,9 +64,23 @@ export declare function legacyAssignToken(d: {
     fact_hash: string;
     channel_id: string;
 }): string;
+/** The manifest's signed tools for one audience, inside the code ceiling; web_extract only with the capability (D19 item 1, D28). */
+export declare function signedManifestTools(manifest: ToolGrantManifest, audience: "owner_dm" | "team_room", searchProvidersCapable: boolean): string[];
+/**
+ * manifest-policy.json from the stored manifest, the kill switches and the capability alone (D35): the bridge
+ * recomputes it locally on a capability change, without a refetch or a cached BindResult. An audience switched off
+ * contributes no tool (review H-1).
+ */
+export declare function manifestPolicyFor(manifest: ToolGrantManifest, switches: {
+    readonly ownerDm: boolean;
+    readonly room: boolean;
+}, searchProvidersCapable: boolean): ManifestPolicyDoc;
 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;
+}, 
+/** D19 item 1, D28: every attached runtime socket declared search_providers_v2. Default false = fail closed:
+ *  an older runtime reads an unknown tool in manifest-policy.json as an unreadable file and drops every grant. */
+searchProvidersCapable?: boolean): BindResult;

package/dist/grants/manifest.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Owner-signed tool grants, step 1 (spec §7.1, §8.1): verify the owner-signed
+ * tool-grant manifest wrapper `{ manifest, algo, signature }`.
+ *
+ * A pure function: an untrusted payload value in, "verified" or one named
+ * refusal out. In step 1 a verified manifest is only RECORDED; no grant code
+ * reads it (Task 8 pins that).
+ */
+import { type SearchProvider } from "./search-providers.js";
 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"];
@@ -41,7 +50,8 @@ export interface SignedConfig {
         readonly model: string;
     };
     readonly search?: {
-        readonly provider: "brave" | "tavily";
+        readonly provider: SearchProvider;
+        readonly owner_dm_daily_cap?: number;
     };
     readonly tools_allow?: readonly string[];
     readonly flags: readonly string[];

package/dist/grants/search-providers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Search providers the bridge accepts in a signed manifest (spec 2026-10-16 5.1, D2, D36).
+ * The ONE bridge copy of the union; a parity test pins it against the runtime's SEARCH_PROVIDERS (ST-38).
+ */
+export type SearchProvider = "brave" | "tavily" | "parallel" | "exa" | "firecrawl";
+export declare const SEARCH_PROVIDERS: ReadonlySet<SearchProvider>;
+/** Upper bound of the signed owner-DM daily search cap (D36, approved OQ-7). */
+export declare const OWNER_DM_SEARCH_DAILY_CAP_MAX = 2000;
+export declare function isSearchProvider(value: unknown): value is SearchProvider;

package/dist/http-server.d.ts

@@ -1,6 +1,7 @@
 import { type Server } from "node:http";
 import { z } from "zod";
 import type { BridgeAgent, BridgeMessage } from "./bridge-agent.js";
+import type { SearchProvider } from "./grants/search-providers.js";
 /**
  * #335 handling decision: the throwing-write swallow stays (a dying socket
  * must cost only that connection's remainder — the caller requeues it and
@@ -26,6 +27,7 @@ export declare function deliverSseBatch(res: Parameters<typeof writeSse>[0], bat
     ackRuntimeMessages(ids: string[]): void;
     requeueFront(msgs: BridgeMessage[]): void;
     harnessGrantsWithheld(): boolean;
+    signedSearchProvider(): SearchProvider | undefined;
 }, onWriteError?: (error: unknown) => void): void;
 /**
  * Once-per-connection write-failure reporter (#335). A throwing `res.write`