@7h3/protocol 0.4.0 → 0.5.1

package/keyInfra.d.ts

@@ -0,0 +1,64 @@
+import type { KeyRegistry } from './keyRegistry';
+export interface KeyEntry {
+    id: string;
+    algorithm: 'Ed25519';
+    publicKey: string;
+    created: number;
+    expires?: number;
+    revoked?: boolean;
+    revokedAt?: number;
+}
+export interface WellKnownKeysDocument {
+    version: '7h3/0.1';
+    updated: number;
+    keys: KeyEntry[];
+}
+export declare function serveWellKnownKeys(doc: WellKnownKeysDocument): string;
+export declare function parseWellKnownKeys(json: string): WellKnownKeysDocument;
+export declare function fetchWellKnownKeys(baseUrl: string, opts?: {
+    timeout?: number;
+}): Promise<WellKnownKeysDocument>;
+export declare function createHttpKeyRegistry(opts?: {
+    timeout?: number;
+    cacheMs?: number;
+}): KeyRegistry;
+export interface ManagedKeyPair {
+    id: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: number;
+    expiresAt?: number;
+}
+export interface KeyRotationOptions {
+    maxAgeMs: number;
+    overlapMs?: number;
+}
+export declare class KeyRotationManager {
+    private readonly maxAgeMs;
+    private readonly overlapMs;
+    private keys;
+    constructor(opts: KeyRotationOptions);
+    addKey(pair: ManagedKeyPair): void;
+    getCurrentKey(): ManagedKeyPair | null;
+    rotateIfNeeded(): Promise<ManagedKeyPair | null>;
+    getWellKnownDocument(): WellKnownKeysDocument;
+    toKeyRegistry(): KeyRegistry;
+}
+export interface RevocationEntry {
+    id: string;
+    revokedAt: number;
+    reason?: string;
+}
+export interface RevocationList {
+    version: '7h3/0.1';
+    updated: number;
+    revokedKeys: RevocationEntry[];
+}
+export declare class RevocationRegistry {
+    private revoked;
+    revoke(keyId: string, reason?: string): void;
+    isRevoked(keyId: string): boolean;
+    getList(): RevocationList;
+    importList(list: RevocationList): void;
+    wrapRegistry(inner: KeyRegistry): KeyRegistry;
+}

package/keyRegistry.d.ts

@@ -0,0 +1,9 @@
+export interface KeyRegistry {
+    getPublicKey(senderId: string): Promise<string | null>;
+    getSharedSecret?(keyId: string): Promise<string | null>;
+}
+export declare function createStaticKeyRegistry(keys: Record<string, string>): KeyRegistry;
+export declare function createCompositeKeyRegistry(...registries: KeyRegistry[]): KeyRegistry;
+export declare function createCachingKeyRegistry(inner: KeyRegistry, opts?: {
+    ttlMs?: number;
+}): KeyRegistry;

package/keyRotation.d.ts

@@ -0,0 +1,20 @@
+import type { ProtocolEnvelope, SignatureVerificationMaterial } from './protocol';
+export type KeyStatus = 'active' | 'verify-only' | 'revoked';
+export interface KeyRecord {
+    sender: string;
+    keyId: string;
+    alg: SignatureVerificationMaterial['alg'];
+    status: KeyStatus;
+    notBeforeMs: number;
+    notAfterMs: number;
+    material: SignatureVerificationMaterial;
+}
+export declare class RollingKeyring {
+    private readonly records;
+    constructor(records?: KeyRecord[]);
+    add(record: KeyRecord): void;
+    revoke(sender: string, keyId: string, revokedAtMs?: number): boolean;
+    selectSigningKey(sender: string, alg: SignatureVerificationMaterial['alg'], nowMs?: number): KeyRecord | null;
+    resolveVerificationMaterial(signature: NonNullable<ProtocolEnvelope['signature']>, sender: string, nowMs?: number): SignatureVerificationMaterial | undefined;
+}
+export declare function createKeyringSignatureResolver(keyring: RollingKeyring, nowMsProvider?: () => number): (signature: NonNullable<ProtocolEnvelope["signature"]>, sender: string) => Promise<SignatureVerificationMaterial | undefined>;

package/mcpGateway.d.ts

@@ -0,0 +1,37 @@
+import { type BootstrapRuntimePolicyEnforcerOptions } from './policyEnforcer';
+import { type JsonRpcPolicyEvent, type JsonRpcBridgeOptions } from './frameworkAdapters';
+export interface AipMcpGatewayOptions {
+    sharedSecret: string;
+    gatewayAgentId?: string;
+    workerAgentId?: string;
+    allowedMethods?: readonly string[];
+    workerCapabilityPrefix?: string;
+    methodToCapability?: JsonRpcBridgeOptions['methodToCapability'];
+    authorizeMethod?: JsonRpcBridgeOptions['authorizeMethod'];
+    rateLimitKey?: JsonRpcBridgeOptions['rateLimitKey'];
+    rateLimiter?: JsonRpcBridgeOptions['rateLimiter'];
+    onAuditEvent?: (event: AipMcpGatewayAuditEvent) => void | Promise<void>;
+    gatewayWireFormat?: 'json' | 'compact' | 'binary';
+    workerWireFormat?: 'json' | 'compact' | 'binary';
+    runtimePolicy?: {
+        enabled?: boolean;
+        options?: BootstrapRuntimePolicyEnforcerOptions;
+        concurrencyHint?: number;
+        latencySensitive?: boolean;
+        compatibilityFirst?: boolean;
+    };
+}
+export interface AipMcpGatewayRuntime {
+    handleLine: (line: string) => Promise<string | null>;
+}
+export interface AipMcpGatewayAuditEvent {
+    phase: 'request_received' | 'policy' | 'verification_failed' | 'request_success' | 'request_error';
+    id?: string | number | null;
+    method?: string;
+    code?: number;
+    message?: string;
+    policy?: JsonRpcPolicyEvent;
+    timestampMs: number;
+}
+export declare function createAipMcpGatewayRuntime(options: AipMcpGatewayOptions): AipMcpGatewayRuntime;
+export declare function createAipMcpGatewayRuntimeWithPolicy(options: AipMcpGatewayOptions): Promise<AipMcpGatewayRuntime>;

package/mcpTransports.d.ts

@@ -0,0 +1,62 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Readable, Writable } from 'node:stream';
+import type { WireEnvelope } from './protocolTransport';
+/**
+ * Transport adapters for the MCP hardening wrapper.
+ *
+ * The wrapper (`wrapMcpServer` / `wrapMcpClient`) is transport-agnostic: it
+ * operates on `WireEnvelope`s. These adapters connect it to real transports —
+ * newline-delimited stdio and HTTP — so a secured server is deployable as-is.
+ *
+ * Note: the stdio adapter frames one envelope per line and therefore supports
+ * the string wire formats (`json`, `compact`). For `binary`, use HTTP.
+ */
+type WireHandler = (raw: WireEnvelope) => Promise<WireEnvelope>;
+export interface StdioServerHandle {
+    close(): void;
+}
+/**
+ * Serves a wrapped MCP handler over newline-delimited streams (default
+ * `process.stdin` / `process.stdout`). Lines are processed sequentially so
+ * responses are emitted in request order.
+ */
+export declare function serveMcpOverStdio(handle: WireHandler, options?: {
+    input?: Readable;
+    output?: Writable;
+    onError?: (error: unknown) => void;
+}): StdioServerHandle;
+export interface StdioClientHandle {
+    send: WireHandler;
+    close(): void;
+}
+/**
+ * Creates a stdio client `send` function for `wrapMcpClient`. Requests and
+ * responses are correlated by order over the single pipe (one envelope per line).
+ */
+export declare function createStdioMcpClient(options: {
+    input: Readable;
+    output: Writable;
+}): StdioClientHandle;
+/**
+ * Creates a `node:http`-compatible request handler that runs the wrapped MCP
+ * handler. The request body is the wire envelope; the response body is the
+ * signed reply envelope.
+ */
+export declare function createHttpMcpHandler(handle: WireHandler, options?: {
+    binary?: boolean;
+}): (req: IncomingMessage, res: ServerResponse) => void;
+export interface HttpClientHandle {
+    send: WireHandler;
+}
+/**
+ * Creates an HTTP client `send` function for `wrapMcpClient`. POSTs the request
+ * envelope to `url` and returns the response envelope. Uses the global `fetch`
+ * by default; inject `fetchImpl` for tests or custom agents.
+ */
+export declare function createHttpMcpClient(options: {
+    url: string;
+    fetchImpl?: typeof fetch;
+    binary?: boolean;
+    headers?: Record<string, string>;
+}): HttpClientHandle;
+export {};

package/mcpWrapper.d.ts

@@ -0,0 +1,83 @@
+import { type ProtocolEnvelope } from './protocol';
+import { type ReceiveEnvelopeOptions, type WireEnvelope, type WireFormat } from './protocolTransport';
+/**
+ * MCP hardening middleware.
+ *
+ * MCP messages are plain JSON-RPC 2.0 and, as shipped, carry no signature or
+ * replay protection. These wrappers put an AIP envelope around each message on
+ * the wire — signing, TTL-bounding, and replay-checking every request and
+ * response — while the underlying MCP handler still receives plain JSON-RPC.
+ * "Zero app changes": your handler signature does not change.
+ *
+ * The wrappers enforce four bindings beyond signature verification:
+ *   - recipient binding: the server only runs the handler when the envelope is
+ *     addressed to it (`recipient === selfAgentId`) — defeats cross-server relay.
+ *   - sender binding: the client only accepts responses from its expected peer
+ *     (`sender === peerAgentId`) — defeats response spoofing.
+ *   - correlation binding: the client only accepts a response whose
+ *     `correlationId` matches the request it sent — defeats response substitution.
+ *   - replay protection on by default (an `InMemoryReplayCache` if none supplied).
+ *
+ * Verification reuses the transport pipeline (`receiveEnvelope`), so it composes
+ * directly with a Redis-backed replay cache (`createRedisReplayStore`) and
+ * fleet-wide revocation (`withRevocationCheck`) via the `receive` options.
+ */
+export type JsonRpcId = string | number | null;
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type McpJsonRpcHandler = (request: JsonRpcRequest) => JsonRpcResponse | Promise<JsonRpcResponse>;
+export interface McpSecurityOptions {
+    /** This peer's agent id, used as the envelope `sender` and enforced as the inbound `recipient`. */
+    selfAgentId: string;
+    /** The peer's agent id: set as the envelope `recipient` (client) and enforced as the response `sender`. */
+    peerAgentId?: string;
+    /** Signs an unsigned envelope, e.g. `(e) => signEnvelopeHmac(e, secret, keyId)`. */
+    sign: (envelope: Omit<ProtocolEnvelope, 'signature'>) => Promise<ProtocolEnvelope>;
+    /** Inbound verification options: signature material resolver, replay cache, clock skew, etc. */
+    receive?: ReceiveEnvelopeOptions;
+    /** Wire format for the envelope on the wire. Default `compact`. */
+    wireFormat?: WireFormat;
+    /** Envelope TTL in ms. Default 60_000. */
+    ttlMs?: number;
+}
+export interface EncodedRequest {
+    raw: WireEnvelope;
+    /** The envelope `messageId` generated for this request; bind the response's `correlationId` to it. */
+    messageId: string;
+}
+export interface DecodeResponseOptions {
+    /** When set, require the response `correlationId` to equal this value (the request's messageId). */
+    expectCorrelationId?: string;
+}
+/**
+ * Wraps an existing MCP JSON-RPC handler so every inbound message is verified
+ * (signature + replay + TTL + recipient binding) before the handler runs, and
+ * every response is signed. Returns a function over the AIP wire envelope.
+ */
+export declare function wrapMcpServer(handler: McpJsonRpcHandler, options: McpSecurityOptions): (raw: WireEnvelope) => Promise<WireEnvelope>;
+export interface McpClientCodec {
+    encodeRequest(request: JsonRpcRequest): Promise<EncodedRequest>;
+    decodeResponse(raw: WireEnvelope, options?: DecodeResponseOptions): Promise<JsonRpcResponse>;
+}
+/** Signs outbound requests and verifies inbound responses (with sender + correlation binding). */
+export declare function createMcpClientCodec(options: McpSecurityOptions): McpClientCodec;
+/**
+ * Wraps a transport send function (`stdio`, HTTP, ...) so callers issue and
+ * receive plain JSON-RPC while AIP signing, verification, and request/response
+ * correlation happen on the wire.
+ */
+export declare function wrapMcpClient(send: (raw: WireEnvelope) => Promise<WireEnvelope>, options: McpSecurityOptions): (request: JsonRpcRequest) => Promise<JsonRpcResponse>;

package/otel.d.ts

@@ -0,0 +1,65 @@
+/**
+ * otel.ts — Optional OpenTelemetry integration for 7h3 Protocol
+ *
+ * Pass your @opentelemetry/api Tracer provider via setOtelProvider.
+ * No hard dependency — works with any OTel-compatible SDK or without any OTel at all.
+ *
+ * Duck-typed interfaces: any object matching the shape will work, including
+ * the real @opentelemetry/api TracerProvider.
+ *
+ * Usage:
+ *   import { setOtelProvider } from '@7h3/protocol/otel'
+ *   import { trace } from '@opentelemetry/api'
+ *
+ *   setOtelProvider(trace.getTracerProvider())
+ *
+ * Without OTel configured, withVerificationSpan and withAuditSpan call fn(null)
+ * with zero overhead.
+ */
+/**
+ * A minimal OTel-compatible span interface.
+ * Compatible with @opentelemetry/api Span.
+ */
+export interface OtelSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    end(): void;
+    recordException(error: Error): void;
+}
+/**
+ * A minimal OTel-compatible tracer interface.
+ * Compatible with @opentelemetry/api Tracer.
+ */
+export interface OtelTracer {
+    startSpan(name: string, attrs?: Record<string, string | number>): OtelSpan;
+}
+/**
+ * A minimal OTel-compatible provider interface.
+ * Compatible with @opentelemetry/api TracerProvider.
+ */
+export interface OtelProvider {
+    getTracer(name: string): OtelTracer;
+}
+/**
+ * Register an OTel provider. Call once at application startup.
+ * Subsequent calls replace the previous provider.
+ */
+export declare function setOtelProvider(provider: OtelProvider): void;
+/**
+ * Returns the active OTel tracer for '7h3/protocol', or null if no provider
+ * has been registered.
+ */
+export declare function getOtelTracer(): OtelTracer | null;
+/**
+ * Creates a span named '7h3.verify' if OTel is configured, calls fn(span),
+ * records any exception, and ends the span on completion.
+ *
+ * If no OTel provider is registered, calls fn(null) directly with zero overhead.
+ */
+export declare function withVerificationSpan<T>(fn: (span: OtelSpan | null) => Promise<T>, attrs?: Record<string, string | number>): Promise<T>;
+/**
+ * Creates a span named '7h3.audit.write' if OTel is configured, calls fn(span),
+ * records any exception, and ends the span on completion.
+ *
+ * If no OTel provider is registered, calls fn(null) directly with zero overhead.
+ */
+export declare function withAuditSpan<T>(fn: (span: OtelSpan | null) => Promise<T>): Promise<T>;

package/package.json

@@ -1,90 +1,24 @@
 {
   "name": "@7h3/protocol",
-  "version": "0.4.0",
-  "description": "7h3 Protocol: deterministic, signed, replay-safe AI-to-AI messaging with TypeScript/Python/Rust parity. Wire version 7h3/0.1.",
+  "version": "0.5.1",
+  "description": "7h3 Protocol: deterministic, signed, replay-safe AI-to-AI message envelopes (wire 7h3/0.1).",
   "type": "module",
-  "license": "MIT",
-  "main": "./dist/protocol/index.js",
-  "types": "./dist/protocol/index.d.ts",
+  "main": "./index.js",
+  "types": "./index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/protocol/index.d.ts",
-      "import": "./dist/protocol/index.js"
-    },
-    "./protocol": {
-      "types": "./dist/protocol/index.d.ts",
-      "import": "./dist/protocol/index.js"
-    },
-    "./http": { "types": "./dist/protocol/httpBinding.d.ts", "import": "./dist/protocol/httpBinding.js" },
-    "./webhook": { "types": "./dist/protocol/webhookBinding.d.ts", "import": "./dist/protocol/webhookBinding.js" },
-    "./queue": { "types": "./dist/protocol/queueBinding.d.ts", "import": "./dist/protocol/queueBinding.js" },
-    "./ws": { "types": "./dist/protocol/wsBinding.d.ts", "import": "./dist/protocol/wsBinding.js" },
-    "./grpc": { "types": "./dist/protocol/grpcBinding.d.ts", "import": "./dist/protocol/grpcBinding.js" },
-    "./keys": { "types": "./dist/protocol/keyInfra.d.ts", "import": "./dist/protocol/keyInfra.js" },
-    "./key-registry": { "types": "./dist/protocol/keyRegistry.d.ts", "import": "./dist/protocol/keyRegistry.js" },
-    "./gateway": { "types": "./dist/protocol/gateway.d.ts", "import": "./dist/protocol/gateway.js" },
-    "./audit-log": { "types": "./dist/protocol/auditLog.d.ts", "import": "./dist/protocol/auditLog.js" },
-    "./signed-response": { "types": "./dist/protocol/signedResponse.d.ts", "import": "./dist/protocol/signedResponse.js" },
-    "./rate-limiter": { "types": "./dist/protocol/rateLimiter.d.ts", "import": "./dist/protocol/rateLimiter.js" },
-    "./route-policy": { "types": "./dist/protocol/routePolicy.d.ts", "import": "./dist/protocol/routePolicy.js" }
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
   },
+  "files": [
+    "index.js",
+    "*.d.ts",
+    "README.md"
+  ],
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/IceMasterT/7h3-protocol-aip.git"
-  },
-  "bin": {
-    "7h3": "./bin/7h3.js"
-  },
-  "scripts": {
-    "cli:help": "tsx bin/7h3.ts help",
-    "cli:keygen": "tsx bin/7h3.ts keygen",
-    "lint": "eslint .",
-    "test": "vitest run",
-    "build:protocol": "tsc -p tsconfig.lib.json && vite build --config vite.lib.config.ts",
-    "package:protocol": "npm run build:protocol && tsx scripts/prepare-aip-package.ts",
-    "bench:protocol": "vitest bench src/protocol.bench.ts",
-    "bench:e2e:quick": "tsx scripts/bench-protocol-e2e.ts --profile quick",
-    "bench:e2e:full": "tsx scripts/bench-protocol-e2e.ts --profile full",
-    "aip:quickstart": "tsx scripts/aip-quickstart.ts",
-    "aip:framework:quickstart": "tsx scripts/aip-framework-quickstart.ts",
-    "aip:mcp:gateway": "tsx scripts/aip-mcp-gateway.ts",
-    "aip:mcp:wrap": "tsx scripts/aip-mcp-wrap-demo.ts",
-    "bench:openloop:quick": "tsx scripts/bench-protocol-openloop.ts --profile quick --adaptive --p99-threshold 200 --drop-threshold-pct 2",
-    "bench:openloop:full": "tsx scripts/bench-protocol-openloop.ts --profile full --adaptive --p99-threshold 200 --drop-threshold-pct 2 --adaptive-max-doublings 6 --adaptive-binary-steps 8",
-    "bench:openloop:stress:quick": "tsx scripts/bench-protocol-openloop.ts --profile quick",
-    "bench:openloop:stress:full": "tsx scripts/bench-protocol-openloop.ts --profile full",
-    "bench:signatures:quick": "tsx scripts/bench-signature-profiles.ts --profile quick",
-    "bench:signatures:full": "tsx scripts/bench-signature-profiles.ts --profile full",
-    "bench:wire:quick": "tsx scripts/bench-wire-codecs.ts --profile quick",
-    "bench:wire:full": "tsx scripts/bench-wire-codecs.ts --profile full",
-    "bench:replay:quick": "tsx scripts/bench-replay-cache.ts --profile quick",
-    "bench:replay:full": "tsx scripts/bench-replay-cache.ts --profile full",
-    "conformance:binary": "tsx scripts/build-binary-conformance.ts",
-    "release:gate": "tsx scripts/release-gate.ts",
-    "policy:validate": "tsx scripts/validate-runtime-policy.ts",
-    "canary:plan": "tsx scripts/canary-rollout.ts",
-    "release:dashboard": "tsx scripts/build-release-dashboard.ts",
-    "bench:diff": "tsx scripts/bench-diff.ts",
-    "conformance:python": "PYTHONPATH=sdk/python python3 -m unittest discover -s sdk/python/tests -v",
-    "conformance:rust": "cargo test --manifest-path sdk/rust/Cargo.toml",
-    "fuzz:ts": "tsx fuzz/ts/run.ts",
-    "fuzz:ts:decode": "tsx fuzz/ts/harness-decode.ts",
-    "fuzz:ts:verify": "tsx fuzz/ts/harness-verify.ts",
-    "fuzz:rust:setup": "cargo install cargo-fuzz 2>/dev/null || true",
-    "fuzz:rust:decode": "cargo +nightly fuzz run fuzz_decode --manifest-path sdk/rust/fuzz/Cargo.toml -- -max_total_time=60",
-    "fuzz:rust:canonicalize": "cargo +nightly fuzz run fuzz_canonicalize --manifest-path sdk/rust/fuzz/Cargo.toml -- -max_total_time=60"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^25.9.3",
-    "eslint": "^10.5.0",
-    "fast-check": "^4.8.0",
-    "globals": "^17.6.0",
-    "tsx": "^4.20.6",
-    "typescript": "~6.0.3",
-    "typescript-eslint": "^8.61.0",
-    "vite": "^8.0.16",
-    "vitest": "^4.1.8",
-    "ws": "^8.18.3"
   }
 }

package/policyEnforcer.d.ts

@@ -0,0 +1,50 @@
+import { type LoadRuntimePolicyOptions, type RuntimePolicy } from './runtimePolicy';
+export type RuntimeMode = 'http' | 'ws' | 'http-binary' | 'http-batch' | 'http-binary-batch' | 'ws-batch' | 'ws-binary' | 'ws-binary-batch';
+export interface ModeSelectionInput {
+    concurrency: number;
+    latencySensitive?: boolean;
+    compatibilityFirst?: boolean;
+}
+export interface TuningInput {
+    trafficClass: 'low' | 'medium' | 'high';
+    p99Ms?: number;
+    dropPct?: number;
+}
+export interface TuningDecision {
+    batchSizeRange: [number, number];
+    inflightCapRange: [number, number];
+    retryBackoffMsRange: [number, number];
+    actions: string[];
+}
+export interface RetryInput {
+    error: unknown;
+    attempt: number;
+}
+export interface InvariantConfig {
+    signatureVerification: boolean;
+    canonicalization: boolean;
+    replayDefense: boolean;
+    ttlClockSkewEnforcement: boolean;
+}
+export declare function createPolicyEnforcer(policy: RuntimePolicy): {
+    selectMode: (input: ModeSelectionInput) => RuntimeMode;
+    tune: (input: TuningInput) => TuningDecision;
+    shouldRetry: (input: RetryInput) => boolean;
+    assertInvariant: (config: InvariantConfig) => void;
+    metadata: {
+        policyName: string;
+        policyVersion: string;
+        policyStatus: string;
+        enforcedSlo: {
+            dropPctMax: number;
+            p99MsMax: number;
+        };
+    };
+};
+export type PolicyEnforcer = ReturnType<typeof createPolicyEnforcer>;
+export type BootstrapRuntimePolicyEnforcerOptions = LoadRuntimePolicyOptions;
+export declare function bootstrapRuntimePolicyEnforcer(options?: BootstrapRuntimePolicyEnforcerOptions): Promise<{
+    policy: RuntimePolicy;
+    enforcer: PolicyEnforcer;
+}>;
+export declare function isRuntimeMode(value: string): value is RuntimeMode;

package/policyTelemetryFeedback.d.ts

@@ -0,0 +1,11 @@
+export interface TelemetryFeedbackInput {
+    mode: string;
+    p99Ms: number;
+    dropPct: number;
+    concurrency: number;
+}
+export interface TelemetryFeedbackRecommendation {
+    severity: 'normal' | 'warn' | 'critical';
+    actions: string[];
+}
+export declare function recommendPolicyAdjustments(input: TelemetryFeedbackInput): TelemetryFeedbackRecommendation;

package/protocol.d.ts

@@ -0,0 +1,66 @@
+export type ProtocolVersion = '7h3/0.1';
+export type IntentKind = 'PING' | 'PONG' | 'CAPS' | 'TASK' | 'RESULT' | 'ERROR' | 'ENCRYPTED';
+export interface ProtocolHeader {
+    version: ProtocolVersion;
+    messageId: string;
+    timestampMs: number;
+    ttlMs: number;
+    sender: string;
+    recipient?: string;
+    nonce: string;
+}
+export interface ProtocolBody {
+    intent: IntentKind;
+    content: string;
+    capability?: string;
+    correlationId?: string;
+}
+export interface ProtocolSignature {
+    alg: 'HS256' | 'ED25519';
+    keyId: string;
+    value: string;
+}
+export interface ProtocolEnvelope {
+    header: ProtocolHeader;
+    body: ProtocolBody;
+    signature?: ProtocolSignature;
+}
+export interface ProtocolDiagnostic {
+    level: 'error' | 'warning';
+    message: string;
+}
+export type SignatureVerificationMaterial = {
+    alg: 'HS256';
+    secret: string;
+} | {
+    alg: 'ED25519';
+    publicKey: string;
+};
+export declare function canonicalizeEnvelope(envelope: Omit<ProtocolEnvelope, 'signature'>): string;
+export declare function signCanonicalPayloadHmac(payload: string, secret: string): Promise<string>;
+export declare function verifyCanonicalPayloadHmac(payload: string, signature: string, secret: string): Promise<boolean>;
+export declare function generateEd25519KeypairBase64Url(): Promise<{
+    publicKey: string;
+    privateKey: string;
+}>;
+export declare function signCanonicalPayloadEd25519(payload: string, privateKeyPkcs8Base64Url: string): Promise<string>;
+export declare function verifyCanonicalPayloadEd25519(payload: string, signature: string, publicKeySpkiBase64Url: string): Promise<boolean>;
+export declare function signEnvelopeHmac(envelope: Omit<ProtocolEnvelope, 'signature'>, secret: string, keyId?: string): Promise<ProtocolEnvelope>;
+export declare function verifyEnvelopeHmac(envelope: ProtocolEnvelope, secret: string): Promise<boolean>;
+export declare function signEnvelopeEd25519(envelope: Omit<ProtocolEnvelope, 'signature'>, privateKeyPkcs8Base64Url: string, keyId?: string): Promise<ProtocolEnvelope>;
+export declare function verifyEnvelopeEd25519(envelope: ProtocolEnvelope, publicKeySpkiBase64Url: string): Promise<boolean>;
+export declare function verifyEnvelopeSignature(envelope: ProtocolEnvelope, material: SignatureVerificationMaterial): Promise<boolean>;
+export declare function verifyCanonicalPayloadSignature(payload: string, signature: ProtocolSignature | undefined, material: SignatureVerificationMaterial): Promise<boolean>;
+export declare function validateEnvelope(envelope: ProtocolEnvelope, nowMs?: number): ProtocolDiagnostic[];
+export declare function createEnvelope(input: {
+    sender: string;
+    recipient?: string;
+    intent: IntentKind;
+    content: string;
+    capability?: string;
+    correlationId?: string;
+    ttlMs?: number;
+    messageId?: string;
+    nonce?: string;
+    nowMs?: number;
+}): Omit<ProtocolEnvelope, 'signature'>;

package/protocolAgent.d.ts

@@ -0,0 +1,58 @@
+import { type IntentKind, type ProtocolDiagnostic, type ProtocolEnvelope } from './protocol';
+import { type AckMode } from './protocolCapabilities';
+import { InMemoryReplayCache } from './protocolReplay';
+import { type WireEnvelope, type WireFormat } from './protocolTransport';
+export interface TaskHandlerResult {
+    intent?: 'RESULT' | 'ERROR';
+    content: string;
+    capability?: string;
+}
+export interface AgentSessionConfig {
+    agentId: string;
+    outboundSecret: string;
+    keyId?: string;
+    capabilities?: string[];
+    supportedWireFormats?: WireFormat[];
+    maxBatchSize?: number;
+    ackModes?: AckMode[];
+    requireSignature?: boolean;
+    replayCache?: InMemoryReplayCache;
+    sharedSecrets?: Record<string, string>;
+    resolveInboundSecret?: (keyId: string, sender: string) => string | undefined | Promise<string | undefined>;
+    onTask?: (envelope: ProtocolEnvelope) => TaskHandlerResult | Promise<TaskHandlerResult>;
+}
+export interface AgentReceiveResult {
+    ok: boolean;
+    diagnostics: ProtocolDiagnostic[];
+    received: ProtocolEnvelope | null;
+    response: ProtocolEnvelope | null;
+}
+export declare class AgentSession {
+    private readonly agentId;
+    private readonly outboundSecret;
+    private readonly keyId;
+    private readonly capabilities;
+    private readonly supportedWireFormats;
+    private readonly maxBatchSize;
+    private readonly ackModes;
+    private readonly requireSignature;
+    private readonly replayCache;
+    private readonly sharedSecrets;
+    private readonly resolveInboundSecret?;
+    private readonly onTask?;
+    constructor(config: AgentSessionConfig);
+    private inboundSecretResolver;
+    createSignedIntent(input: {
+        recipient?: string;
+        intent: IntentKind;
+        content: string;
+        capability?: string;
+        correlationId?: string;
+        ttlMs?: number;
+        messageId?: string;
+        nonce?: string;
+        nowMs?: number;
+    }): Promise<ProtocolEnvelope>;
+    receiveAndRespond(input: WireEnvelope | ProtocolEnvelope, nowMs?: number): Promise<AgentReceiveResult>;
+    private buildAutoResponse;
+}

package/protocolBinary.d.ts

@@ -0,0 +1,8 @@
+import type { ProtocolEnvelope } from './protocol';
+import type { ReceiveEnvelopeResult } from './protocolTransport';
+export declare const DEFAULT_MAX_BINARY_ENVELOPE_BYTES: number;
+export interface BinaryDecodeOptions {
+    maxFrameBytes?: number;
+}
+export declare function encodeEnvelopeBinary(envelope: ProtocolEnvelope): Uint8Array;
+export declare function decodeEnvelopeBinary(payload: Uint8Array, options?: BinaryDecodeOptions): ReceiveEnvelopeResult;