acp-runtime 0.1.0

package/dist/agent.js

@@ -0,0 +1,798 @@
+/*
+ * Copyright 2026 ACP Project
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for details.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { AgentCapabilities } from "./capabilities.js";
+import { ACP_VERSION, DEFAULT_CRYPTO_SUITE } from "./constants.js";
+import { signBytes, decryptForRecipient, encryptForRecipients, signProtectedPayload, verifyProtectedPayloadSignature } from "./crypto.js";
+import { DiscoveryClient } from "./discovery.js";
+import { processingError, transportError, validationError, keyProviderError } from "./errors.js";
+import { validateHttpClientPolicy, validateHttpUrl, warnIfInsecureHttpUsed } from "./httpSecurity.js";
+import { buildIdentityDocument, createIdentity, identityFromProvider, parseAgentId, readIdentity, verifyIdentityDocument, writeIdentity } from "./identity.js";
+import { canonicalJsonBytes } from "./jsonSupport.js";
+import { buildAckPayload, buildEnvelope, buildFailPayload, isExpired, messageToMap, parseAcpMessage, parseMessageClass } from "./messages.js";
+import { AmqpTransportClient } from "./amqpTransport.js";
+import { MqttTransportClient } from "./mqttTransport.js";
+import { defaultAgentOptions } from "./options.js";
+import { LocalKeyProvider, VaultKeyProvider } from "./keyProvider.js";
+import { TransportClient } from "./transport.js";
+import { buildWellKnownDocument } from "./wellKnown.js";
+class DedupStore {
+    ttlMs;
+    processed = new Map();
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+    }
+    isDuplicate(messageId) {
+        this.cleanup();
+        return this.processed.has(messageId);
+    }
+    markProcessed(messageId) {
+        this.processed.set(messageId, Date.now());
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [messageId, timestamp] of this.processed.entries()) {
+            if (now - timestamp > this.ttlMs) {
+                this.processed.delete(messageId);
+            }
+        }
+    }
+}
+function firstNonBlank(...values) {
+    for (const value of values) {
+        if (value && value.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function failedOutcome(recipient, reasonCode, detail) {
+    return {
+        recipient,
+        state: "FAILED",
+        reason_code: reasonCode,
+        detail
+    };
+}
+function toPublicKeyMap(targets) {
+    const output = {};
+    for (const target of targets) {
+        output[target.recipient] = target.public_key;
+    }
+    return output;
+}
+function buildLocalAmqpService(agentId, options) {
+    if (!options.amqp_broker_url) {
+        return undefined;
+    }
+    return AmqpTransportClient.buildServiceHint(agentId, options.amqp_broker_url, options.amqp_exchange);
+}
+function buildLocalMqttService(agentId, options) {
+    if (!options.mqtt_broker_url) {
+        return undefined;
+    }
+    return MqttTransportClient.buildServiceHint(agentId, options.mqtt_broker_url, undefined, options.mqtt_qos, options.mqtt_topic_prefix);
+}
+function applyHttpSecurityProfile(identityDocument, mtlsEnabled) {
+    const serviceRaw = identityDocument.service;
+    const service = serviceRaw && typeof serviceRaw === "object" && !Array.isArray(serviceRaw) ? serviceRaw : {};
+    const directEndpoint = service.direct_endpoint;
+    if (typeof directEndpoint === "string" && directEndpoint.trim()) {
+        service.http = {
+            endpoint: directEndpoint.trim(),
+            security_profile: mtlsEnabled ? "mtls" : directEndpoint.startsWith("https://") ? "https" : "http"
+        };
+    }
+    if (Array.isArray(service.relay_hints) && service.relay_hints.length > 0) {
+        const endpoint = typeof service.relay_hints[0] === "string" ? service.relay_hints[0] : undefined;
+        if (endpoint) {
+            service.relay = {
+                endpoint,
+                security_profile: mtlsEnabled ? "mtls" : endpoint.startsWith("https://") ? "https" : "http"
+            };
+        }
+    }
+    identityDocument.service = service;
+}
+function resignIdentityDocument(identityDocument, identity) {
+    const unsigned = { ...identityDocument };
+    delete unsigned.signature;
+    identityDocument.signature = {
+        algorithm: "Ed25519",
+        signed_by: identity.signing_kid,
+        value: signBytes(canonicalJsonBytes(unsigned), identity.signing_private_key)
+    };
+}
+function parseReasonForCapabilityMismatch(reason) {
+    const normalized = (reason ?? "").toLowerCase();
+    if (normalized.includes("protocol")) {
+        return "UNSUPPORTED_VERSION";
+    }
+    if (normalized.includes("crypto")) {
+        return "UNSUPPORTED_CRYPTO_SUITE";
+    }
+    if (normalized.includes("profile")) {
+        return "UNSUPPORTED_PROFILE";
+    }
+    return "POLICY_REJECTED";
+}
+function deliveryStateFromResponse(statusCode, responseClass, reasonCode) {
+    if (statusCode >= 200 && statusCode < 300) {
+        if (responseClass === "FAIL") {
+            if (reasonCode === "EXPIRED_MESSAGE") {
+                return "EXPIRED";
+            }
+            if (reasonCode === "POLICY_REJECTED") {
+                return "DECLINED";
+            }
+            return "FAILED";
+        }
+        if (responseClass === "ACK" || responseClass === "CAPABILITIES") {
+            return "ACKNOWLEDGED";
+        }
+        return "DELIVERED";
+    }
+    if (statusCode === 410) {
+        return "EXPIRED";
+    }
+    if ([401, 403, 409, 422].includes(statusCode)) {
+        return "DECLINED";
+    }
+    return "FAILED";
+}
+function outcomeFromHttpResponse(recipient, response) {
+    const body = response.body;
+    const responseMessage = body?.response_message && typeof body.response_message === "object" && !Array.isArray(body.response_message)
+        ? body.response_message
+        : undefined;
+    const responseClass = parseMessageClass(responseMessage && responseMessage.envelope && typeof responseMessage.envelope === "object"
+        ? responseMessage.envelope.message_class
+        : undefined);
+    const reasonCode = typeof body?.reason_code === "string" ? body.reason_code : undefined;
+    const detail = typeof body?.detail === "string"
+        ? body.detail
+        : response.status_code >= 400
+            ? `Recipient HTTP ${response.status_code}`
+            : undefined;
+    return {
+        recipient,
+        state: deliveryStateFromResponse(response.status_code, responseClass, reasonCode),
+        status_code: response.status_code,
+        response_class: responseClass,
+        reason_code: reasonCode,
+        detail,
+        response_message: responseMessage
+    };
+}
+export class AcpAgent {
+    identity;
+    identity_document;
+    discovery;
+    transport;
+    amqp_transport;
+    mqtt_transport;
+    capabilities;
+    storage_dir;
+    trust_profile;
+    relay_url;
+    default_delivery_mode;
+    key_provider_info;
+    dedup = new DedupStore(60 * 60 * 1000);
+    delivery_states = new Map();
+    constructor(identity, identity_document, discovery, transport, amqp_transport, mqtt_transport, capabilities, storage_dir, trust_profile, relay_url, default_delivery_mode, key_provider_info) {
+        this.identity = identity;
+        this.identity_document = identity_document;
+        this.discovery = discovery;
+        this.transport = transport;
+        this.amqp_transport = amqp_transport;
+        this.mqtt_transport = mqtt_transport;
+        this.capabilities = capabilities;
+        this.storage_dir = storage_dir;
+        this.trust_profile = trust_profile;
+        this.relay_url = relay_url;
+        this.default_delivery_mode = default_delivery_mode;
+        this.key_provider_info = key_provider_info;
+    }
+    static async loadOrCreate(agentId, optionsInput) {
+        parseAgentId(agentId);
+        const options = { ...defaultAgentOptions(), ...optionsInput };
+        mkdirSync(options.storage_dir, { recursive: true });
+        const keyProvider = await AcpAgent.resolveKeyProvider(options);
+        const keyProviderInfo = keyProvider.describe();
+        const providerIdentityKeys = await keyProvider.loadIdentityKeys(agentId).catch(() => undefined);
+        const providerTls = await keyProvider.loadTlsMaterial(agentId).catch(() => ({}));
+        const providerCa = await keyProvider.loadCaBundle(agentId).catch(() => undefined);
+        const externalKeyProvider = keyProviderInfo.provider === "vault";
+        const effectiveCaFile = firstNonBlank(options.ca_file, providerTls.ca_file, providerCa);
+        const effectiveCertFile = firstNonBlank(options.cert_file, providerTls.cert_file);
+        const effectiveKeyFile = firstNonBlank(options.key_file, providerTls.key_file);
+        const policy = {
+            allow_insecure_http: options.allow_insecure_http,
+            allow_insecure_tls: options.allow_insecure_tls,
+            mtls_enabled: options.mtls_enabled,
+            ca_file: effectiveCaFile,
+            cert_file: effectiveCertFile,
+            key_file: effectiveKeyFile
+        };
+        validateHttpClientPolicy(policy, "Agent HTTP security configuration");
+        if (options.endpoint) {
+            validateHttpUrl(options.endpoint, policy.allow_insecure_http, policy.mtls_enabled, "Agent direct endpoint configuration");
+            if (policy.allow_insecure_http) {
+                warnIfInsecureHttpUsed(options.endpoint, "Agent direct endpoint configuration");
+            }
+        }
+        validateHttpUrl(options.relay_url, policy.allow_insecure_http, policy.mtls_enabled, "Agent relay URL configuration");
+        for (const relayHint of options.relay_hints) {
+            validateHttpUrl(relayHint, policy.allow_insecure_http, policy.mtls_enabled, "Agent relay hint configuration");
+        }
+        for (const directoryHint of options.enterprise_directory_hints) {
+            validateHttpUrl(directoryHint, policy.allow_insecure_http, policy.mtls_enabled, "Agent enterprise directory hint configuration");
+        }
+        const localAmqpService = buildLocalAmqpService(agentId, options);
+        const localMqttService = buildLocalMqttService(agentId, options);
+        const bundle = readIdentity(options.storage_dir, agentId);
+        let identity;
+        let identityDocument;
+        let capabilities;
+        if (!bundle) {
+            if (providerIdentityKeys) {
+                identity = identityFromProvider({
+                    agent_id: agentId,
+                    ...providerIdentityKeys
+                });
+            }
+            else if (externalKeyProvider) {
+                throw keyProviderError("Unable to load identity keys from key provider");
+            }
+            else {
+                identity = createIdentity(agentId);
+            }
+            capabilities = new AgentCapabilities(agentId);
+            identityDocument = buildIdentityDocument({
+                identity,
+                direct_endpoint: options.endpoint,
+                relay_hints: options.relay_hints,
+                trust_profile: options.trust_profile,
+                capabilities: capabilities.toMap(),
+                valid_days: 365,
+                amqp_service: localAmqpService,
+                mqtt_service: localMqttService,
+                http_security_profile: options.mtls_enabled ? "mtls" : undefined,
+                relay_security_profile: options.mtls_enabled ? "mtls" : undefined
+            });
+            applyHttpSecurityProfile(identityDocument, options.mtls_enabled);
+            resignIdentityDocument(identityDocument, identity);
+            writeIdentity(options.storage_dir, identity, identityDocument);
+        }
+        else {
+            identity = bundle.identity;
+            identityDocument = bundle.identity_document;
+            if (providerIdentityKeys) {
+                identity = identityFromProvider({
+                    agent_id: identity.agent_id,
+                    ...providerIdentityKeys,
+                    signing_kid: providerIdentityKeys.signing_kid ?? identity.signing_kid,
+                    encryption_kid: providerIdentityKeys.encryption_kid ?? identity.encryption_kid
+                });
+            }
+            else if (externalKeyProvider) {
+                throw keyProviderError("Unable to load identity keys from key provider");
+            }
+            capabilities = AgentCapabilities.fromMap(identityDocument.capabilities && typeof identityDocument.capabilities === "object"
+                ? identityDocument.capabilities
+                : undefined, agentId);
+            const shouldRewrite = !verifyIdentityDocument(identityDocument) ||
+                Boolean(options.endpoint) ||
+                options.relay_hints.length > 0 ||
+                Boolean(localAmqpService) ||
+                Boolean(localMqttService);
+            if (shouldRewrite) {
+                const serviceRaw = identityDocument.service;
+                const service = serviceRaw && typeof serviceRaw === "object" && !Array.isArray(serviceRaw)
+                    ? serviceRaw
+                    : {};
+                const existingEndpoint = typeof service.direct_endpoint === "string" ? service.direct_endpoint : undefined;
+                const existingRelayHints = Array.isArray(service.relay_hints)
+                    ? service.relay_hints.filter((item) => typeof item === "string")
+                    : [];
+                identityDocument = buildIdentityDocument({
+                    identity,
+                    direct_endpoint: options.endpoint ?? existingEndpoint,
+                    relay_hints: options.relay_hints.length > 0 ? options.relay_hints : existingRelayHints,
+                    trust_profile: options.trust_profile,
+                    capabilities: capabilities.toMap(),
+                    valid_days: 365,
+                    amqp_service: localAmqpService ?? service.amqp,
+                    mqtt_service: localMqttService ?? service.mqtt,
+                    http_security_profile: options.mtls_enabled ? "mtls" : undefined,
+                    relay_security_profile: options.mtls_enabled ? "mtls" : undefined
+                });
+                applyHttpSecurityProfile(identityDocument, options.mtls_enabled);
+                resignIdentityDocument(identityDocument, identity);
+                writeIdentity(options.storage_dir, identity, identityDocument);
+            }
+        }
+        const effectiveRelayHints = options.relay_hints.length > 0
+            ? options.relay_hints
+            : Array.isArray(identityDocument.service?.relay_hints)
+                ? (identityDocument.service.relay_hints ?? []).filter((item) => typeof item === "string")
+                : [];
+        const discovery = new DiscoveryClient(join(options.storage_dir, "discovery-cache.json"), options.discovery_scheme, effectiveRelayHints, options.enterprise_directory_hints, options.http_timeout_seconds, policy);
+        discovery.seed(identityDocument);
+        const transport = new TransportClient(options.http_timeout_seconds, policy);
+        const amqpTransport = options.amqp_broker_url
+            ? new AmqpTransportClient(options.amqp_broker_url, options.amqp_exchange, options.amqp_exchange_type, options.http_timeout_seconds)
+            : undefined;
+        const mqttTransport = options.mqtt_broker_url
+            ? new MqttTransportClient(options.mqtt_broker_url, options.mqtt_qos, options.mqtt_topic_prefix, options.http_timeout_seconds)
+            : undefined;
+        return new AcpAgent(identity, identityDocument, discovery, transport, amqpTransport, mqttTransport, capabilities, options.storage_dir, options.trust_profile, options.relay_url, options.default_delivery_mode, keyProviderInfo);
+    }
+    static async resolveKeyProvider(options) {
+        if (options.key_provider === "vault") {
+            if (!options.vault_url || !options.vault_path) {
+                throw keyProviderError("vault_url and vault_path are required when key_provider=vault");
+            }
+            return new VaultKeyProvider(options.vault_url, options.vault_path, options.vault_token_env, options.vault_token, options.http_timeout_seconds, options.ca_file, options.allow_insecure_tls, options.allow_insecure_http);
+        }
+        return new LocalKeyProvider(options.storage_dir, options.cert_file, options.key_file, options.ca_file);
+    }
+    agentId() {
+        return this.identity.agent_id;
+    }
+    getDeliveryStates() {
+        const output = {};
+        for (const [operationId, states] of this.delivery_states.entries()) {
+            output[operationId] = Object.fromEntries(states.entries());
+        }
+        return output;
+    }
+    buildWellKnownDocument(baseUrl, identityDocumentUrl) {
+        const resolvedBaseUrl = baseUrl ??
+            (() => {
+                const service = this.identity_document.service;
+                const endpoint = service?.direct_endpoint;
+                if (typeof endpoint !== "string" || !endpoint.trim()) {
+                    return undefined;
+                }
+                const parsed = new URL(endpoint);
+                return `${parsed.protocol}//${parsed.host}`;
+            })();
+        if (!resolvedBaseUrl) {
+            throw validationError("Unable to build /.well-known/acp metadata without base_url or direct_endpoint");
+        }
+        return buildWellKnownDocument({
+            identity_document: this.identity_document,
+            base_url: resolvedBaseUrl,
+            identity_document_url: identityDocumentUrl,
+            version: ACP_VERSION
+        });
+    }
+    registerIdentityDocument(identityDocument) {
+        this.discovery.registerIdentityDocument(identityDocument);
+    }
+    async resolveWellKnown(baseUrl, expectedAgentId) {
+        return this.discovery.resolveWellKnown(baseUrl, expectedAgentId);
+    }
+    async resolveRecipients(recipients, mode) {
+        const deliverable = [];
+        const preflight = [];
+        for (const recipient of recipients) {
+            let identityDocument;
+            try {
+                identityDocument = await this.discovery.resolve(recipient);
+            }
+            catch (error) {
+                preflight.push(failedOutcome(recipient, "POLICY_REJECTED", String(error)));
+                continue;
+            }
+            const remoteCapabilities = AgentCapabilities.fromMap(identityDocument.capabilities && typeof identityDocument.capabilities === "object"
+                ? identityDocument.capabilities
+                : undefined, recipient);
+            const capabilityMatch = this.capabilities.chooseCompatible(remoteCapabilities);
+            if (!capabilityMatch.compatible) {
+                preflight.push(failedOutcome(recipient, parseReasonForCapabilityMismatch(capabilityMatch.reason), capabilityMatch.reason ?? "No compatible capabilities"));
+                continue;
+            }
+            const choice = this.chooseDeliveryChannel(remoteCapabilities, identityDocument, mode);
+            if (!choice.channel) {
+                preflight.push(failedOutcome(recipient, "POLICY_REJECTED", choice.detail ?? "Delivery channel unavailable"));
+                continue;
+            }
+            const publicKey = identityDocument.keys?.encryption
+                ?.public_key ?? "";
+            if (!publicKey.trim()) {
+                preflight.push(failedOutcome(recipient, "POLICY_REJECTED", "Recipient identity document missing encryption public key"));
+                continue;
+            }
+            deliverable.push({
+                recipient,
+                public_key: publicKey.trim(),
+                channel: choice.channel,
+                endpoint: choice.endpoint,
+                amqp_service: choice.amqp_service,
+                mqtt_service: choice.mqtt_service
+            });
+        }
+        return { deliverable, preflight_outcomes: preflight };
+    }
+    chooseDeliveryChannel(remoteCapabilities, identityDocument, mode) {
+        const shared = this.capabilities.transports
+            .map((item) => item.toLowerCase())
+            .filter((transport) => remoteCapabilities.transports.map((t) => t.toLowerCase()).includes(transport));
+        const serviceRaw = identityDocument.service;
+        const service = serviceRaw && typeof serviceRaw === "object" && !Array.isArray(serviceRaw)
+            ? serviceRaw
+            : {};
+        const directEndpoint = typeof service.direct_endpoint === "string" ? service.direct_endpoint.trim() : "";
+        const hasDirect = Boolean(directEndpoint);
+        const amqpService = service.amqp && typeof service.amqp === "object" && !Array.isArray(service.amqp)
+            ? service.amqp
+            : undefined;
+        const mqttService = service.mqtt && typeof service.mqtt === "object" && !Array.isArray(service.mqtt)
+            ? service.mqtt
+            : undefined;
+        const directAvailable = hasDirect && shared.some((t) => t === "https" || t === "http" || t === "direct");
+        const relayAvailable = this.relay_url.trim().length > 0 && shared.includes("relay");
+        const amqpAvailable = Boolean(amqpService) && shared.includes("amqp");
+        const mqttAvailable = Boolean(mqttService) && shared.includes("mqtt");
+        if (mode === "direct") {
+            if (directAvailable) {
+                return { channel: "direct", endpoint: directEndpoint };
+            }
+            return { detail: "Recipient direct endpoint is unavailable or incompatible" };
+        }
+        if (mode === "relay") {
+            if (relayAvailable) {
+                return { channel: "relay" };
+            }
+            return { detail: "Relay delivery is unavailable or incompatible" };
+        }
+        if (mode === "amqp") {
+            if (amqpAvailable) {
+                return { channel: "amqp", amqp_service: amqpService };
+            }
+            return { detail: "AMQP delivery is unavailable or incompatible" };
+        }
+        if (mode === "mqtt") {
+            if (mqttAvailable) {
+                return { channel: "mqtt", mqtt_service: mqttService };
+            }
+            return { detail: "MQTT delivery is unavailable or incompatible" };
+        }
+        if (directAvailable) {
+            return { channel: "direct", endpoint: directEndpoint };
+        }
+        if (relayAvailable) {
+            return { channel: "relay" };
+        }
+        if (amqpAvailable) {
+            return { channel: "amqp", amqp_service: amqpService };
+        }
+        if (mqttAvailable) {
+            return { channel: "mqtt", mqtt_service: mqttService };
+        }
+        return {
+            detail: "Recipient identity document is missing direct_endpoint/amqp/mqtt and no relay fallback is compatible"
+        };
+    }
+    buildMessage(recipients, payload, recipientPublicKeys, messageClass, contextId, operationId, expiresInSeconds, correlationId, inReplyTo) {
+        const envelope = buildEnvelope({
+            sender: this.agentId(),
+            recipients,
+            message_class: messageClass,
+            context_id: contextId,
+            operation_id: operationId,
+            expires_in_seconds: expiresInSeconds,
+            correlation_id: correlationId,
+            in_reply_to: inReplyTo,
+            crypto_suite: DEFAULT_CRYPTO_SUITE
+        });
+        let protectedPayload = encryptForRecipients(payload, envelope, recipientPublicKeys);
+        protectedPayload = signProtectedPayload(envelope, protectedPayload, this.identity.signing_private_key, this.identity.signing_kid);
+        return {
+            envelope,
+            protected: protectedPayload,
+            sender_identity_document: this.identity_document
+        };
+    }
+    async deliverDirect(message, targets) {
+        const messageMap = messageToMap(message);
+        const outcomes = [];
+        for (const target of targets) {
+            if (!target.endpoint) {
+                outcomes.push(failedOutcome(target.recipient, "POLICY_REJECTED", "Recipient direct endpoint missing"));
+                continue;
+            }
+            try {
+                const response = await this.transport.postJson(target.endpoint, messageMap);
+                outcomes.push(outcomeFromHttpResponse(target.recipient, response));
+            }
+            catch (error) {
+                outcomes.push(failedOutcome(target.recipient, "POLICY_REJECTED", `Direct transport failure: ${String(error)}`));
+            }
+        }
+        return outcomes;
+    }
+    async deliverRelay(message, targets) {
+        const outcomes = [];
+        try {
+            const relayResponse = await this.transport.sendToRelay(this.relay_url, message);
+            const relayOutcomes = Array.isArray(relayResponse.outcomes) && relayResponse.outcomes.length > 0
+                ? relayResponse.outcomes
+                : targets.map((target) => ({ recipient: target.recipient, state: "DELIVERED" }));
+            for (const relayOutcome of relayOutcomes) {
+                const item = relayOutcome && typeof relayOutcome === "object" && !Array.isArray(relayOutcome)
+                    ? relayOutcome
+                    : {};
+                outcomes.push({
+                    recipient: typeof item.recipient === "string" ? item.recipient : "",
+                    state: (typeof item.state === "string" ? item.state : "DELIVERED"),
+                    status_code: typeof item.status_code === "number" ? item.status_code : undefined,
+                    response_class: parseMessageClass(item.response_class),
+                    reason_code: typeof item.reason_code === "string" ? item.reason_code : undefined,
+                    detail: typeof item.detail === "string" ? item.detail : undefined,
+                    response_message: item.response_message && typeof item.response_message === "object" && !Array.isArray(item.response_message)
+                        ? item.response_message
+                        : undefined
+                });
+            }
+        }
+        catch (error) {
+            for (const target of targets) {
+                outcomes.push(failedOutcome(target.recipient, "POLICY_REJECTED", `Relay transport failure: ${String(error)}`));
+            }
+        }
+        return outcomes;
+    }
+    async deliverAmqp(message, target) {
+        const outcome = { recipient: target.recipient, state: "PENDING" };
+        try {
+            const client = this.amqp_transport;
+            if (!client && !target.amqp_service) {
+                throw transportError("AMQP delivery selected but sender is not configured with an AMQP broker");
+            }
+            const brokerUrl = target.amqp_service?.broker_url ?? this.amqp_transport?.broker_url;
+            if (!client && !brokerUrl) {
+                throw transportError("AMQP delivery selected but sender is not configured with an AMQP broker");
+            }
+            const transportClient = client ??
+                new AmqpTransportClient(brokerUrl, target.amqp_service?.exchange, undefined, 10);
+            await transportClient.publish(messageToMap(message), target.recipient, target.amqp_service);
+            outcome.state = "DELIVERED";
+        }
+        catch (error) {
+            outcome.state = "FAILED";
+            outcome.reason_code = "POLICY_REJECTED";
+            outcome.detail = `AMQP transport failure: ${String(error)}`;
+        }
+        return outcome;
+    }
+    async deliverMqtt(message, target) {
+        const outcome = { recipient: target.recipient, state: "PENDING" };
+        try {
+            const client = this.mqtt_transport;
+            if (!client && !target.mqtt_service) {
+                throw transportError("MQTT delivery selected but sender is not configured with an MQTT broker");
+            }
+            const brokerUrl = target.mqtt_service?.broker_url ?? this.mqtt_transport?.broker_url;
+            if (!client && !brokerUrl) {
+                throw transportError("MQTT delivery selected but sender is not configured with an MQTT broker");
+            }
+            const transportClient = client ??
+                new MqttTransportClient(brokerUrl, Number(target.mqtt_service?.qos ?? 1), this.default_delivery_mode === "mqtt" ? undefined : "acp/agent", 10);
+            await transportClient.publish(messageToMap(message), target.recipient, target.mqtt_service);
+            outcome.state = "DELIVERED";
+        }
+        catch (error) {
+            outcome.state = "FAILED";
+            outcome.reason_code = "POLICY_REJECTED";
+            outcome.detail = `MQTT transport failure: ${String(error)}`;
+        }
+        return outcome;
+    }
+    syncDeliveryStates(operationId, outcomes) {
+        const states = new Map();
+        for (const outcome of outcomes) {
+            states.set(outcome.recipient, outcome.state);
+        }
+        this.delivery_states.set(operationId, states);
+    }
+    async send(recipients, payload, context, messageClass = "SEND", expiresInSeconds = 300, correlationId, inReplyTo, deliveryMode) {
+        if (recipients.length === 0) {
+            throw validationError("send() requires at least one recipient");
+        }
+        const mode = deliveryMode ?? this.default_delivery_mode;
+        const operationId = randomUUID();
+        const contextId = context ?? `ctx:${randomUUID()}`;
+        const resolved = await this.resolveRecipients(recipients, mode);
+        const outcomes = [...resolved.preflight_outcomes];
+        const messageIds = [];
+        const directTargets = resolved.deliverable.filter((target) => target.channel === "direct");
+        const relayTargets = resolved.deliverable.filter((target) => target.channel === "relay");
+        const amqpTargets = resolved.deliverable.filter((target) => target.channel === "amqp");
+        const mqttTargets = resolved.deliverable.filter((target) => target.channel === "mqtt");
+        if (directTargets.length > 0) {
+            const message = this.buildMessage(directTargets.map((target) => target.recipient), payload, toPublicKeyMap(directTargets), messageClass, contextId, operationId, expiresInSeconds, correlationId, inReplyTo);
+            messageIds.push(message.envelope.message_id);
+            outcomes.push(...(await this.deliverDirect(message, directTargets)));
+        }
+        if (relayTargets.length > 0) {
+            const message = this.buildMessage(relayTargets.map((target) => target.recipient), payload, toPublicKeyMap(relayTargets), messageClass, contextId, operationId, expiresInSeconds, correlationId, inReplyTo);
+            messageIds.push(message.envelope.message_id);
+            outcomes.push(...(await this.deliverRelay(message, relayTargets)));
+        }
+        for (const target of amqpTargets) {
+            const message = this.buildMessage([target.recipient], payload, { [target.recipient]: target.public_key }, messageClass, contextId, operationId, expiresInSeconds, correlationId, inReplyTo);
+            messageIds.push(message.envelope.message_id);
+            outcomes.push(await this.deliverAmqp(message, target));
+        }
+        for (const target of mqttTargets) {
+            const message = this.buildMessage([target.recipient], payload, { [target.recipient]: target.public_key }, messageClass, contextId, operationId, expiresInSeconds, correlationId, inReplyTo);
+            messageIds.push(message.envelope.message_id);
+            outcomes.push(await this.deliverMqtt(message, target));
+        }
+        if (messageIds.length === 0) {
+            messageIds.push(randomUUID());
+        }
+        const result = {
+            operation_id: operationId,
+            message_id: messageIds[0],
+            message_ids: messageIds,
+            outcomes
+        };
+        this.syncDeliveryStates(operationId, outcomes);
+        return result;
+    }
+    async sendBasic(recipients, payload, context) {
+        return this.send(recipients, payload, context, "SEND", 300, undefined, undefined, this.default_delivery_mode);
+    }
+    async resolveSenderIdentityDocument(rawMessage, senderId) {
+        if (rawMessage.sender_identity_document &&
+            typeof rawMessage.sender_identity_document === "object" &&
+            !Array.isArray(rawMessage.sender_identity_document)) {
+            const embedded = rawMessage.sender_identity_document;
+            if (embedded.agent_id === senderId && verifyIdentityDocument(embedded)) {
+                return embedded;
+            }
+        }
+        return this.discovery.resolve(senderId);
+    }
+    validateEnvelopeForInbound(envelope) {
+        if (envelope.acp_version !== ACP_VERSION) {
+            throw processingError("UNSUPPORTED_VERSION", `Unsupported ACP version: ${envelope.acp_version}`);
+        }
+        if (envelope.crypto_suite !== DEFAULT_CRYPTO_SUITE) {
+            throw processingError("UNSUPPORTED_CRYPTO_SUITE", `Unsupported crypto suite: ${envelope.crypto_suite}`);
+        }
+        if (isExpired(envelope)) {
+            throw processingError("EXPIRED_MESSAGE", "Message is expired");
+        }
+    }
+    createResponseMessage(senderIdentityDocument, requestEnvelope, responseClass, responsePayload) {
+        const senderId = requestEnvelope.sender;
+        const senderPublicKey = (senderIdentityDocument.keys.encryption.public_key ?? "").trim();
+        if (!senderPublicKey) {
+            throw processingError("POLICY_REJECTED", "Sender identity document missing encryption key");
+        }
+        return this.buildMessage([senderId], responsePayload, { [senderId]: senderPublicKey }, responseClass, requestEnvelope.context_id, requestEnvelope.operation_id, 300, requestEnvelope.correlation_id ?? requestEnvelope.operation_id, requestEnvelope.message_id);
+    }
+    async decryptMessageForSelf(rawMessage) {
+        const message = parseAcpMessage(rawMessage);
+        this.validateEnvelopeForInbound(message.envelope);
+        if (!message.envelope.recipients.includes(this.agentId())) {
+            throw processingError("POLICY_REJECTED", "Message is not addressed to this agent");
+        }
+        const senderDoc = await this.resolveSenderIdentityDocument(rawMessage, message.envelope.sender);
+        const senderSigningKey = (senderDoc.keys.signing.public_key ?? "").trim();
+        if (!senderSigningKey) {
+            throw processingError("INVALID_SIGNATURE", "Sender signing public key missing");
+        }
+        if (!verifyProtectedPayloadSignature(message.envelope, message.protected, senderSigningKey)) {
+            throw processingError("INVALID_SIGNATURE", "Message signature verification failed");
+        }
+        const payload = decryptForRecipient(message.envelope, message.protected, this.agentId(), this.identity.encryption_private_key);
+        return { message, payload };
+    }
+    async receive(rawMessage, handler) {
+        const result = {
+            state: "FAILED"
+        };
+        let requestMessage;
+        try {
+            requestMessage = parseAcpMessage(rawMessage);
+        }
+        catch (error) {
+            result.reason_code = "POLICY_REJECTED";
+            result.detail = `Invalid ACP message structure: ${String(error)}`;
+            return result;
+        }
+        let senderDoc;
+        try {
+            this.validateEnvelopeForInbound(requestMessage.envelope);
+            if (!requestMessage.envelope.recipients.includes(this.agentId())) {
+                throw processingError("POLICY_REJECTED", `Recipient ${this.agentId()} not in message recipients`);
+            }
+            senderDoc = await this.resolveSenderIdentityDocument(rawMessage, requestMessage.envelope.sender);
+            const senderSigningKey = (senderDoc.keys.signing.public_key ?? "").trim();
+            if (!senderSigningKey) {
+                throw processingError("INVALID_SIGNATURE", "Sender signing key missing from identity document");
+            }
+            if (!verifyProtectedPayloadSignature(requestMessage.envelope, requestMessage.protected, senderSigningKey)) {
+                throw processingError("INVALID_SIGNATURE", "Signature verification failed");
+            }
+            if (this.dedup.isDuplicate(requestMessage.envelope.message_id)) {
+                result.state = "ACKNOWLEDGED";
+                result.detail = "Duplicate message acknowledged";
+                if (requestMessage.envelope.message_class !== "ACK" && requestMessage.envelope.message_class !== "FAIL") {
+                    result.response_message = messageToMap(this.createResponseMessage(senderDoc, requestMessage.envelope, "ACK", buildAckPayload(requestMessage.envelope.message_id, "duplicate")));
+                }
+                return result;
+            }
+            const decrypted = decryptForRecipient(requestMessage.envelope, requestMessage.protected, this.agentId(), this.identity.encryption_private_key);
+            result.decrypted_payload = decrypted;
+            let responseMessage;
+            if (requestMessage.envelope.message_class === "CAPABILITIES") {
+                responseMessage = this.createResponseMessage(senderDoc, requestMessage.envelope, "CAPABILITIES", this.capabilities.toMap());
+            }
+            else if (requestMessage.envelope.message_class !== "ACK" && requestMessage.envelope.message_class !== "FAIL") {
+                const ackPayload = buildAckPayload(requestMessage.envelope.message_id, "accepted");
+                const handlerPayload = handler?.(decrypted, requestMessage.envelope);
+                if (handlerPayload && Object.keys(handlerPayload).length > 0) {
+                    ackPayload.handler = handlerPayload;
+                }
+                responseMessage = this.createResponseMessage(senderDoc, requestMessage.envelope, "ACK", ackPayload);
+            }
+            this.dedup.markProcessed(requestMessage.envelope.message_id);
+            result.state = "ACKNOWLEDGED";
+            result.response_message = responseMessage ? messageToMap(responseMessage) : undefined;
+            return result;
+        }
+        catch (error) {
+            const processing = error instanceof Error ? error : new Error(String(error));
+            if (error instanceof Error && "reason" in error && typeof error.reason === "string") {
+                result.reason_code = error.reason;
+            }
+            else {
+                result.reason_code = "POLICY_REJECTED";
+            }
+            result.detail = processing.message;
+            const terminal = requestMessage.envelope.message_class === "ACK" || requestMessage.envelope.message_class === "FAIL";
+            if (!terminal) {
+                try {
+                    const sender = await this.resolveSenderIdentityDocument(rawMessage, requestMessage.envelope.sender);
+                    result.response_message = messageToMap(this.createResponseMessage(sender, requestMessage.envelope, "FAIL", buildFailPayload(result.reason_code, result.detail ?? "processing error", false)));
+                }
+                catch {
+                    result.response_message = undefined;
+                }
+            }
+            return result;
+        }
+    }
+    async requestCapabilities(recipient) {
+        const result = await this.send([recipient], {}, `capabilities:${randomUUID()}`, "CAPABILITIES", 300, undefined, undefined, this.default_delivery_mode);
+        let capabilities;
+        for (const outcome of result.outcomes) {
+            if (!outcome.response_message) {
+                continue;
+            }
+            try {
+                const decrypted = await this.decryptMessageForSelf(outcome.response_message);
+                if (decrypted.message.envelope.message_class === "CAPABILITIES") {
+                    capabilities = decrypted.payload;
+                    break;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        return { result, capabilities };
+    }
+}