acp-runtime 0.1.0

package/dist/transport.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026 ACP Project
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for details.
+ */
+import { messageToMap } from "./messages.js";
+import { buildFetchOptions, validateHttpUrl } from "./httpSecurity.js";
+import { parseJsonMap } from "./jsonSupport.js";
+import { transportError } from "./errors.js";
+export class TransportClient {
+    timeoutSeconds;
+    policy;
+    fetchOptions;
+    constructor(timeoutSeconds, policy) {
+        this.timeoutSeconds = timeoutSeconds;
+        this.policy = policy;
+        this.fetchOptions = buildFetchOptions(policy);
+    }
+    async postJson(url, body) {
+        validateHttpUrl(url, this.policy.allow_insecure_http, this.policy.mtls_enabled, "HTTP transport request");
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), Math.max(1, this.timeoutSeconds) * 1000);
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+                ...this.fetchOptions
+            });
+            const rawBody = await response.text();
+            let parsedBody;
+            try {
+                parsedBody = parseJsonMap(rawBody);
+            }
+            catch {
+                parsedBody = undefined;
+            }
+            return {
+                status_code: response.status,
+                raw_body: rawBody,
+                body: parsedBody
+            };
+        }
+        catch (error) {
+            throw transportError(`HTTP request failed: ${String(error)}`);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async sendToRelay(relayUrl, message) {
+        const relayEndpoint = relayUrl.endsWith("/") ? `${relayUrl}messages` : `${relayUrl}/messages`;
+        const response = await this.postJson(relayEndpoint, messageToMap(message));
+        if (response.status_code !== 200) {
+            throw transportError(`Relay returned HTTP ${response.status_code} for message ${message.envelope.message_id}`);
+        }
+        if (!response.body) {
+            throw transportError("Relay returned non-JSON response");
+        }
+        return response.body;
+    }
+}

package/dist/wellKnown.d.ts

@@ -0,0 +1,14 @@
+import { JsonMap, JsonValue } from "./jsonSupport.js";
+export declare const WELL_KNOWN_PATH = "/.well-known/acp";
+export declare const SUPPORTED_WELL_KNOWN_VERSION = "1.0";
+export declare const SUPPORTED_SECURITY_PROFILES: readonly ["http", "https", "mtls", "https+mtls"];
+export declare function wellKnownUrlFromBase(baseUrl: string): string;
+export declare function identityDocumentUrlFromBase(baseUrl: string): string;
+export declare function buildWellKnownDocument(input: {
+    identity_document: JsonMap;
+    base_url: string;
+    identity_document_url?: string;
+    version?: string;
+}): JsonMap;
+export declare function parseWellKnownDocument(value: JsonValue): JsonMap;
+export declare function resolveIdentityDocumentReference(wellKnown: JsonMap, sourceUrl: string): string;

package/dist/wellKnown.js

@@ -0,0 +1,202 @@
+/*
+ * Copyright 2026 ACP Project
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for details.
+ */
+import { ACP_VERSION, DEFAULT_IDENTITY_DOCUMENT_PATH } from "./constants.js";
+import { toJsonMap } from "./jsonSupport.js";
+import { validationError } from "./errors.js";
+export const WELL_KNOWN_PATH = "/.well-known/acp";
+export const SUPPORTED_WELL_KNOWN_VERSION = ACP_VERSION;
+export const SUPPORTED_SECURITY_PROFILES = ["http", "https", "mtls", "https+mtls"];
+export function wellKnownUrlFromBase(baseUrl) {
+    const normalized = baseUrl.trim();
+    if (!normalized) {
+        throw validationError("base_url is required");
+    }
+    if (normalized.endsWith(WELL_KNOWN_PATH)) {
+        return normalized;
+    }
+    return `${normalized.replace(/\/+$/, "")}${WELL_KNOWN_PATH}`;
+}
+export function identityDocumentUrlFromBase(baseUrl) {
+    const normalized = baseUrl.trim();
+    if (!normalized) {
+        throw validationError("base_url is required");
+    }
+    return `${normalized.replace(/\/+$/, "")}${DEFAULT_IDENTITY_DOCUMENT_PATH}`;
+}
+function inferSecurityProfile(transports) {
+    for (const transportName of ["http", "relay"]) {
+        const transport = transports[transportName];
+        if (transport && typeof transport === "object" && !Array.isArray(transport)) {
+            const securityProfile = transport.security_profile;
+            if (typeof securityProfile === "string" && securityProfile.trim()) {
+                return securityProfile.trim();
+            }
+        }
+    }
+    const endpoint = (transports.http ?? {}).endpoint ?? "";
+    if (endpoint.startsWith("https://")) {
+        return "https";
+    }
+    if (endpoint.startsWith("http://")) {
+        return "http";
+    }
+    return "https";
+}
+function validateIdentityDocumentReference(reference) {
+    try {
+        const parsed = new URL(reference);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw validationError("identity_document URL must use http or https");
+        }
+        if (!parsed.hostname.trim()) {
+            throw validationError("identity_document URL is missing host");
+        }
+        return;
+    }
+    catch {
+        if (!reference.startsWith("/")) {
+            throw validationError("identity_document URL must be absolute http(s) or root-relative path");
+        }
+    }
+}
+function validateTransports(transports) {
+    for (const [transportName, transportValue] of Object.entries(transports)) {
+        if (!transportValue || typeof transportValue !== "object" || Array.isArray(transportValue)) {
+            throw validationError(`Well-known transport hint ${transportName} must be an object`);
+        }
+        const hint = transportValue;
+        if (hint.endpoint !== undefined) {
+            if (typeof hint.endpoint !== "string") {
+                throw validationError(`Well-known transport hint ${transportName}.endpoint must be a string`);
+            }
+            const endpoint = hint.endpoint.trim();
+            try {
+                const parsed = new URL(endpoint);
+                if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+                    !parsed.hostname.trim()) {
+                    throw validationError(`Well-known transport hint ${transportName}.endpoint must be an absolute http(s) URL`);
+                }
+            }
+            catch {
+                throw validationError(`Well-known transport hint ${transportName}.endpoint must be an absolute http(s) URL`);
+            }
+        }
+        if (hint.security_profile !== undefined) {
+            if (typeof hint.security_profile !== "string" ||
+                !SUPPORTED_SECURITY_PROFILES.includes(hint.security_profile)) {
+                throw validationError(`Well-known transport hint ${transportName}.security_profile is invalid`);
+            }
+        }
+    }
+}
+export function buildWellKnownDocument(input) {
+    const agentId = input.identity_document.agent_id;
+    if (typeof agentId !== "string" || !agentId.trim()) {
+        throw validationError("identity_document.agent_id is required");
+    }
+    const version = input.version ?? SUPPORTED_WELL_KNOWN_VERSION;
+    if (version !== SUPPORTED_WELL_KNOWN_VERSION) {
+        throw validationError(`Unsupported well-known version ${version}; expected ${SUPPORTED_WELL_KNOWN_VERSION}`);
+    }
+    const serviceRaw = input.identity_document.service;
+    const service = serviceRaw && typeof serviceRaw === "object" && !Array.isArray(serviceRaw)
+        ? serviceRaw
+        : {};
+    const capabilitiesRaw = input.identity_document.capabilities;
+    const capabilities = capabilitiesRaw && typeof capabilitiesRaw === "object" && !Array.isArray(capabilitiesRaw)
+        ? capabilitiesRaw
+        : {};
+    const transports = {};
+    const directEndpoint = service.direct_endpoint;
+    if (typeof directEndpoint === "string" && directEndpoint.trim()) {
+        const httpHint = { endpoint: directEndpoint.trim() };
+        const httpSecurityProfile = service.http && typeof service.http === "object" && !Array.isArray(service.http)
+            ? service.http.security_profile
+            : undefined;
+        if (typeof httpSecurityProfile === "string" && httpSecurityProfile.trim()) {
+            httpHint.security_profile = httpSecurityProfile.trim();
+        }
+        transports.http = httpHint;
+    }
+    if (Array.isArray(service.relay_hints)) {
+        const relayHints = service.relay_hints
+            .filter((item) => typeof item === "string")
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0);
+        if (relayHints.length > 0) {
+            const relayHint = { endpoint: relayHints[0] };
+            const relaySecurityProfile = service.relay && typeof service.relay === "object" && !Array.isArray(service.relay)
+                ? service.relay.security_profile
+                : undefined;
+            if (typeof relaySecurityProfile === "string" && relaySecurityProfile.trim()) {
+                relayHint.security_profile = relaySecurityProfile.trim();
+            }
+            if (relayHints.length > 1) {
+                relayHint.hints = relayHints;
+            }
+            transports.relay = relayHint;
+        }
+    }
+    if (service.amqp && typeof service.amqp === "object" && !Array.isArray(service.amqp)) {
+        transports.amqp = service.amqp;
+    }
+    if (service.mqtt && typeof service.mqtt === "object" && !Array.isArray(service.mqtt)) {
+        transports.mqtt = service.mqtt;
+    }
+    const identityReference = input.identity_document_url ?? identityDocumentUrlFromBase(input.base_url);
+    validateIdentityDocumentReference(identityReference);
+    const doc = {
+        agent_id: agentId,
+        identity_document: identityReference,
+        transports,
+        version,
+        security_profile: inferSecurityProfile(transports)
+    };
+    const supportsRaw = capabilities.supports;
+    if (supportsRaw && typeof supportsRaw === "object" && !Array.isArray(supportsRaw)) {
+        const supported = Object.entries(supportsRaw)
+            .filter(([, enabled]) => Boolean(enabled))
+            .map(([name]) => name)
+            .sort();
+        doc.capabilities = supported;
+    }
+    return doc;
+}
+export function parseWellKnownDocument(value) {
+    const map = toJsonMap(value);
+    if (typeof map.agent_id !== "string" || !map.agent_id.trim()) {
+        throw validationError("Well-known response missing agent_id");
+    }
+    if (typeof map.version !== "string" || map.version !== SUPPORTED_WELL_KNOWN_VERSION) {
+        throw validationError(`Well-known response version must be ${SUPPORTED_WELL_KNOWN_VERSION}`);
+    }
+    if (typeof map.identity_document !== "string" || !map.identity_document.trim()) {
+        throw validationError("Well-known response identity_document must be a URL string");
+    }
+    validateIdentityDocumentReference(map.identity_document);
+    const transports = toJsonMap(map.transports);
+    validateTransports(transports);
+    if (map.security_profile !== undefined) {
+        if (typeof map.security_profile !== "string" ||
+            !SUPPORTED_SECURITY_PROFILES.includes(map.security_profile)) {
+            throw validationError("Well-known response security_profile is invalid");
+        }
+    }
+    return map;
+}
+export function resolveIdentityDocumentReference(wellKnown, sourceUrl) {
+    const reference = wellKnown.identity_document;
+    if (typeof reference !== "string" || !reference.trim()) {
+        throw validationError("Well-known response identity_document reference is invalid");
+    }
+    validateIdentityDocumentReference(reference);
+    try {
+        return new URL(reference).toString();
+    }
+    catch {
+        return new URL(reference, sourceUrl).toString();
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "acp-runtime",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Agent Communication Protocol (ACP)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beltxa/acp.git",
+    "directory": "sdks/typescript"
+  },
+  "homepage": "https://github.com/beltxa/acp",
+  "bugs": {
+    "url": "https://github.com/beltxa/acp/issues"
+  },
+  "scripts": {
+    "build": "node_modules/.bin/tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "node_modules/.bin/vitest run",
+    "test:watch": "node_modules/.bin/vitest",
+    "lint": "node_modules/.bin/tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "amqplib": "^0.10.9",
+    "mqtt": "5.14.1",
+    "tweetnacl": "^1.0.3",
+    "undici": "^7.16.0",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.8",
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}