@iicp/web-node 0.2.4 → 0.2.5

package/README.md

@@ -5,6 +5,11 @@ from the network *and* **serve** a model from a browser tab. ESM, built on the p
 native `fetch` / `SubtleCrypto` / WebGPU (and runs in Node ≥18). The browser
 client refuses keyless providers rather than silently sending plaintext.
 
+IICP supplies intent resolution and provider eligibility/selection. MCP, A2A,
+HTTP or another negotiated binding may then execute the selected task. See the
+public [protocol positioning](https://github.com/RobLe3/IICP/blob/main/standards/IICP_PROTOCOL_POSITIONING.md)
+and [adjacent-protocol comparison](https://github.com/RobLe3/IICP/blob/main/standards/PROTOCOL_COMPARISON_2026-08-15.md).
+
 ```
 npm install @iicp/web-node
 ```
@@ -36,6 +41,20 @@ When the chosen node advertises an encryption key (`nodeCxKey(node)`), the paylo
 no opt-out. A node that does not advertise `cx_public_key`/`public_key` is refused before
 any network send so browser use cannot silently fall back to plaintext.
 
+## Runtime self-description
+
+Browser `chat()` calls add a small IICP runtime identity context by default. It
+tells the selected model that it is being accessed through IICP, identifies the
+active intent and browser package version, and includes a model or capability
+fact only when it comes from the selected node's advertisement. It does not
+expose endpoints, full node identities, candidate sets, scores or credentials,
+and it is not a prompt-injection security boundary.
+
+Set `runtime_identity: { mode: "disabled" }` to preserve the application
+messages without the capsule, or use `mode: "required"` to refuse when a
+supported instruction channel is unavailable. Non-chat operations and the
+plaintext envelope helper remain unchanged.
+
 ## Serve — be a node from the browser
 
 ```ts

package/dist/build-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "iicp.browser_build_provenance.v1",
   "package": "@iicp/web-node",
-  "implementation_version": "0.2.4",
+  "implementation_version": "0.2.5",
   "sdk_compatibility_version": "0.7.102",
-  "source_commit": "c26bf228708a5bfad0f8574407ea1a45e4d377c7",
-  "lockfile_sha256": "54183560d240a4f8573274dfab6dda6c297fc1bcbe5ae18b12d5fa5c801f0ffe"
+  "source_commit": "6f28256d0d67cf08beddadbc762dbd339786fcd8",
+  "lockfile_sha256": "1a398bdcc85e5a650a394aac26851a04c44bd3e6ec9c8c1c359d4d3015338a7e"
 }

package/dist/iicpConsumer.d.ts

@@ -170,7 +170,6 @@ export declare function createRedactedRoutingReceipt(args: {
     allowedRegions?: readonly string[] | null;
     requiredManifestIdentityLevel?: RequiredManifestIdentityLevel | null;
 }): RoutingReceipt;
-/** Browser-native, consumer-only IICP client. */
 export declare class IicpBrowserClient {
     private readonly directory;
     private readonly timeout;

package/dist/iicpConsumer.js

@@ -17,7 +17,8 @@
 // Epic: #446 · Dev: #447 · Research: research/wasm/WASM-1-feasibility.md (#292).
 import { encryptPayload } from "./cxConfidentiality.js";
 import { verifyDispatchTicket } from "./dispatchTicket.js";
-import { composeRuntimeIdentity } from "./runtimeIdentity.js";
+import { composeRuntimeIdentity, withRuntimeFacts } from "./runtimeIdentity.js";
+import { BROWSER_NODE_VERSION } from "./version.js";
 const REFUSED_INTENT_RULES = [
     { category: "prohibited", rule_id: "eu-ai-act-social-scoring", label: "social scoring", fragments: ["social-scoring", "social_scoring", "social:scoring"] },
     { category: "prohibited", rule_id: "eu-ai-act-criminal-risk", label: "individual criminal risk prediction", fragments: ["criminal-risk", "criminal_risk", "criminal:risk", "predict-crime"] },
@@ -273,6 +274,41 @@ export function createRedactedRoutingReceipt(args) {
     };
 }
 /** Browser-native, consumer-only IICP client. */
+function selectedAdvertisedModel(node, requestedModel) {
+    if (requestedModel && node?.models?.includes(requestedModel))
+        return requestedModel;
+    return node?.models?.length === 1 ? node.models[0] : undefined;
+}
+function effectiveCapabilityLabels(node, intent, model) {
+    const raw = node?.capabilities;
+    if (!Array.isArray(raw))
+        return [];
+    const variants = raw.filter((candidate) => Boolean(candidate) && typeof candidate === "object" && candidate.intent === intent);
+    const exact = model
+        ? variants.filter((candidate) => Array.isArray(candidate.models) && candidate.models.includes(model))
+        : variants;
+    const selected = exact.length === 1 ? exact[0] : variants.length === 1 ? variants[0] : undefined;
+    if (!selected)
+        return [];
+    const labels = [];
+    for (const value of Array.isArray(selected.input_modalities) ? selected.input_modalities : []) {
+        if (typeof value === "string")
+            labels.push(`input_modality:${value}`);
+    }
+    for (const value of Array.isArray(selected.output_modalities) ? selected.output_modalities : []) {
+        if (typeof value === "string")
+            labels.push(`output_modality:${value}`);
+    }
+    for (const value of Array.isArray(selected.features) ? selected.features : []) {
+        if (typeof value === "string")
+            labels.push(value);
+    }
+    for (const value of Array.isArray(selected.execution_capabilities) ? selected.execution_capabilities : []) {
+        if (typeof value === "string")
+            labels.push(`execution:${value}`);
+    }
+    return [...new Set(labels)].sort();
+}
 export class IicpBrowserClient {
     directory;
     timeout;
@@ -444,7 +480,15 @@ export class IicpBrowserClient {
     async chatWithReceipt(messages, opts) {
         const intent = opts.intent ?? "urn:iicp:intent:llm:chat:v1";
         validateIntent(intent);
-        messages = composeRuntimeIdentity(messages, intent, opts.runtime_identity);
+        const selectedModel = selectedAdvertisedModel(opts.node, opts.model);
+        messages = composeRuntimeIdentity(messages, intent, withRuntimeFacts(opts.runtime_identity, {
+            client_name: "@iicp/web-node",
+            client_version: BROWSER_NODE_VERSION,
+            connection_mode: "routed",
+            selected_model: selectedModel,
+            effective_capabilities: effectiveCapabilityLabels(opts.node, intent, selectedModel),
+            selection_reason: "matched_intent_and_constraints",
+        }));
         const taskId = globalThis.crypto?.randomUUID?.() ?? `task-${Date.now()}-${Math.random().toString(16).slice(2)}`;
         const payload = { messages, model: opts.model };
         // IICP-CX S.16: encryption is MANDATORY (privacy-first #360) — no opt-out.

package/dist/runtimeIdentity.d.ts

@@ -3,17 +3,23 @@ export declare const RUNTIME_IDENTITY_PROFILE_ID = "urn:iicp:profile:runtime-ide
 export declare const RUNTIME_IDENTITY_MARKER = "IICP-RUNTIME-CONTEXT/1";
 export declare const RUNTIME_IDENTITY_CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
 export declare const RUNTIME_IDENTITY_MAX_BYTES = 2048;
-export type RuntimeIdentityMode = "disabled" | "explicit" | "required";
+export type RuntimeIdentityMode = "auto" | "disabled" | "explicit" | "required";
 export type RuntimeIdentityInstructionChannel = "system" | "unsupported";
+export type RuntimeIdentityConnectionMode = "routed" | "local_browser";
+export type RuntimeIdentitySelectionReason = "matched_intent_and_constraints" | "explicit_model_match" | "fallback_after_unavailable_candidate" | "intentional_exploration" | "local_browser_execution";
 export interface RuntimeIdentityOptions {
     mode?: RuntimeIdentityMode;
     instruction_channel?: RuntimeIdentityInstructionChannel;
     selected_model?: string;
     effective_capabilities?: string[];
-    selection_reason?: "matched_intent_and_constraints";
+    selection_reason?: RuntimeIdentitySelectionReason;
+    client_name?: string;
+    client_version?: string;
+    connection_mode?: RuntimeIdentityConnectionMode;
 }
 export declare class RuntimeIdentityContextUnsupported extends Error {
     constructor();
 }
+export declare function withRuntimeFacts(options: RuntimeIdentityOptions | undefined, facts: Required<Pick<RuntimeIdentityOptions, "client_name" | "client_version" | "connection_mode" | "selection_reason">> & Pick<RuntimeIdentityOptions, "selected_model" | "effective_capabilities">): RuntimeIdentityOptions;
 export declare function renderRuntimeIdentity(intent: string, options: RuntimeIdentityOptions): string;
 export declare function composeRuntimeIdentity(messages: readonly ChatMessage[], intent: string, options?: RuntimeIdentityOptions): ChatMessage[];

package/dist/runtimeIdentity.js

@@ -2,6 +2,8 @@ export const RUNTIME_IDENTITY_PROFILE_ID = "urn:iicp:profile:runtime-identity-co
 export const RUNTIME_IDENTITY_MARKER = "IICP-RUNTIME-CONTEXT/1";
 export const RUNTIME_IDENTITY_CHAT_INTENT = "urn:iicp:intent:llm:chat:v1";
 export const RUNTIME_IDENTITY_MAX_BYTES = 2048;
+const MAX_FACT_BYTES = 160;
+const MAX_CAPABILITIES = 32;
 const BASE_CAPSULE = "This request reached you through IICP, the Intent-based Inter-agent Communication Protocol. IICP discovers eligible services and routes requests. You are the selected model or service, not IICP. When asked about this connection, use only supplied runtime facts; do not guess missing facts.";
 export class RuntimeIdentityContextUnsupported extends Error {
     constructor() {
@@ -9,15 +11,59 @@ export class RuntimeIdentityContextUnsupported extends Error {
         this.name = "RuntimeIdentityContextUnsupported";
     }
 }
+const selectionText = {
+    matched_intent_and_constraints: "This service matched the requested intent and constraints.",
+    explicit_model_match: "This service matched the requested model and constraints.",
+    fallback_after_unavailable_candidate: "This service was selected after an earlier candidate was unavailable.",
+    intentional_exploration: "This service was selected for an intentional routing exploration.",
+    local_browser_execution: "This model is running locally in the browser.",
+};
+export function withRuntimeFacts(options, facts) {
+    return {
+        ...(options ?? {}),
+        ...facts,
+        selected_model: facts.selected_model,
+        effective_capabilities: [...(facts.effective_capabilities ?? [])],
+    };
+}
+function boundedFact(value, name) {
+    if (!value || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new Error(`runtime identity ${name} contains control characters`);
+    }
+    if (new TextEncoder().encode(value).byteLength > MAX_FACT_BYTES) {
+        throw new Error(`runtime identity ${name} exceeds the bounded fact limit`);
+    }
+    return value;
+}
 export function renderRuntimeIdentity(intent, options) {
-    const lines = [`[${RUNTIME_IDENTITY_MARKER}]`, BASE_CAPSULE, "Runtime facts:", `- intent: ${intent}`];
+    const lines = [`[${RUNTIME_IDENTITY_MARKER}]`, BASE_CAPSULE, "Runtime facts:", `- intent: ${boundedFact(intent, "intent")}`];
+    if (options.client_name || options.client_version) {
+        if (!options.client_name || !options.client_version)
+            throw new Error("runtime identity client name and version must be supplied together");
+        lines.push(`- client: ${boundedFact(options.client_name, "client name")} ${boundedFact(options.client_version, "client version")}`);
+    }
+    if (options.connection_mode === "routed") {
+        lines.push("- connection: routed through IICP to an eligible provider.");
+    }
+    else if (options.connection_mode === "local_browser") {
+        lines.push("- connection: This model is running locally in the browser; no remote IICP provider was selected.");
+    }
+    else if (options.connection_mode !== undefined) {
+        throw new Error("runtime identity connection mode is unsupported");
+    }
     if (options.selected_model)
-        lines.push(`- selected model (provider assertion): ${options.selected_model}`);
+        lines.push(`- selected model: ${boundedFact(options.selected_model, "selected model")}`);
+    if ((options.effective_capabilities?.length ?? 0) > MAX_CAPABILITIES) {
+        throw new Error("runtime identity effective capabilities exceed the bounded count");
+    }
     if (options.effective_capabilities?.length) {
-        lines.push(`- effective capabilities: ${options.effective_capabilities.join(", ")}`);
+        lines.push(`- effective capabilities: ${options.effective_capabilities.map((value) => boundedFact(value, "effective capability")).join(", ")}`);
     }
-    if (options.selection_reason === "matched_intent_and_constraints") {
-        lines.push("- selection: This service matched the requested intent and constraints.");
+    if (options.selection_reason) {
+        const selection = selectionText[options.selection_reason];
+        if (!selection)
+            throw new Error("runtime identity selection reason is unsupported");
+        lines.push(`- selection: ${selection}`);
     }
     const rendered = lines.join("\n");
     if (new TextEncoder().encode(rendered).byteLength > RUNTIME_IDENTITY_MAX_BYTES) {
@@ -27,10 +73,20 @@ export function renderRuntimeIdentity(intent, options) {
 }
 export function composeRuntimeIdentity(messages, intent, options) {
     const original = [...messages];
-    const mode = options?.mode ?? "disabled";
-    if (mode === "disabled" || intent !== RUNTIME_IDENTITY_CHAT_INTENT)
+    const resolved = options ?? {};
+    const mode = resolved.mode ?? "auto";
+    if (intent !== RUNTIME_IDENTITY_CHAT_INTENT)
         return original;
-    if (options?.instruction_channel === "unsupported") {
+    if (!["auto", "disabled", "explicit", "required"].includes(mode)) {
+        throw new Error("runtime identity mode is unsupported");
+    }
+    if (mode === "disabled")
+        return original;
+    if (resolved.instruction_channel !== undefined
+        && !["system", "unsupported"].includes(resolved.instruction_channel)) {
+        throw new Error("runtime identity instruction channel is unsupported");
+    }
+    if (resolved.instruction_channel === "unsupported") {
         if (mode === "required")
             throw new RuntimeIdentityContextUnsupported();
         return original;
@@ -43,7 +99,7 @@ export function composeRuntimeIdentity(messages, intent, options) {
         insertion += 1;
     return [
         ...original.slice(0, insertion),
-        { role: "system", content: renderRuntimeIdentity(intent, options ?? {}) },
+        { role: "system", content: renderRuntimeIdentity(intent, resolved) },
         ...original.slice(insertion),
     ];
 }

package/dist/version.d.ts

@@ -1,4 +1,4 @@
-export declare const BROWSER_NODE_VERSION = "0.2.4";
+export declare const BROWSER_NODE_VERSION = "0.2.5";
 export declare const BROWSER_NODE_SDK_COMPATIBILITY_VERSION = "0.7.102";
 /** Backward-compatible registration value for directories that know only sdk_version. */
 export declare const BROWSER_NODE_SDK_VERSION = "0.7.102";

package/dist/version.js

@@ -1,7 +1,7 @@
 // Browser implementation and IICP SDK-compatibility versions are separate axes.
 // Keep package.json synchronized with BROWSER_NODE_VERSION; the quality gate
 // rejects drift. SDK compatibility describes the registration contract only.
-export const BROWSER_NODE_VERSION = "0.2.4";
+export const BROWSER_NODE_VERSION = "0.2.5";
 export const BROWSER_NODE_SDK_COMPATIBILITY_VERSION = "0.7.102";
 /** Backward-compatible registration value for directories that know only sdk_version. */
 export const BROWSER_NODE_SDK_VERSION = BROWSER_NODE_SDK_COMPATIBILITY_VERSION;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iicp/web-node",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Browser-native IICP node (consume + serve): discovery-mesh client with mandatory E2E encryption (IICP-CX) + WebLLM provider. Zero-config, ESM.",
   "type": "module",
   "main": "dist/index.js",