@alvin0/ai-agent-sdk-a2a 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @alvin0/ai-agent-sdk-a2a
+
+Runtime: **Node 22.12+**.
+
+```sh
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-a2a
+```
+
+Node-elevated bridge between ai-agent-sdk agents/teams and the official A2A
+client/server APIs.
+
+```ts
+import { linkA2AAgent } from '@alvin0/ai-agent-sdk-a2a/client'
+import { createDefinedAgentA2AServer } from '@alvin0/ai-agent-sdk-a2a/server'
+```
+
+This package is intentionally classified as Node. The official A2A 1.1.0 codec
+uses `Buffer.from` for raw binary `Part` serialization. Text, structured data,
+URLs, and binary values are supported in Node, but the package must not be
+advertised for Edge/Worker runtimes until the committed negative promotion gate
+passes without Node globals.
+
+Authentication, endpoint policy, persistence, and HTTP framework adaptation
+remain host-owned. Configure explicit origins, HTTPS/private-network policy,
+resource bounds, session ownership, and deadlines for the deployment boundary.
+
+Composition: `runtime-team.linkAgent`. Lifecycle: `borrowed-caller-owned`; close
+the runtime/team first, then retain the idempotent unlink and server-dispose
+reports separately.

package/dist/cleanup-report-CTjMJ9EU.mjs

@@ -0,0 +1,146 @@
+//#region src/common/integration-operation.ts
+const A2A_INTEGRATION_OPERATIONS = Object.freeze({
+	"a2a-client-link": Object.freeze([
+		"agent-card-resolve",
+		"link",
+		"send",
+		"stream",
+		"unlink"
+	]),
+	"a2a-server": Object.freeze([
+		"request",
+		"execute",
+		"cancel",
+		"dispose"
+	])
+});
+function beginA2AIntegrationOperation(logger, family, operation) {
+	assertIdentity(operation, 64, "integration operation");
+	const operationId = crypto.randomUUID(), startedAt = now();
+	log(logger, "info", "SDK integration operation started", {
+		integrationSchemaVersion: 1,
+		integrationFamily: family,
+		integrationOperation: operation,
+		operationId,
+		kind: "logical-start"
+	});
+	let terminal = false;
+	const finish = (status, errorCode) => {
+		if (terminal) return;
+		terminal = true;
+		log(logger, status === "error" ? "error" : "info", message(status), {
+			integrationSchemaVersion: 1,
+			integrationFamily: family,
+			integrationOperation: operation,
+			operationId,
+			kind: "logical-terminal",
+			status,
+			durationMs: elapsed(startedAt),
+			...errorCode === void 0 ? {} : { errorCode: boundedCode(errorCode) }
+		});
+	};
+	return {
+		attempt(attemptNumber) {
+			if (!Number.isSafeInteger(attemptNumber) || attemptNumber < 1) throw new TypeError("integration attemptNumber must be a positive safe integer");
+			const attemptId = crypto.randomUUID(), attemptStartedAt = now();
+			log(logger, "info", "SDK integration attempt started", {
+				integrationSchemaVersion: 1,
+				integrationFamily: family,
+				integrationOperation: operation,
+				operationId,
+				kind: "attempt-start",
+				attemptId,
+				attemptNumber
+			});
+			let ended = false;
+			const end = (status, errorCode) => {
+				if (ended) return;
+				ended = true;
+				log(logger, status === "error" ? "error" : "info", message(status), {
+					integrationSchemaVersion: 1,
+					integrationFamily: family,
+					integrationOperation: operation,
+					operationId,
+					kind: "attempt-terminal",
+					attemptId,
+					attemptNumber,
+					status,
+					durationMs: elapsed(attemptStartedAt),
+					...errorCode === void 0 ? {} : { errorCode: boundedCode(errorCode) }
+				});
+			};
+			return {
+				success: () => end("success"),
+				fail: (code) => end("error", code),
+				abort: () => end("aborted")
+			};
+		},
+		success: () => finish("success"),
+		fail: (code) => finish("error", code),
+		abort: () => finish("aborted")
+	};
+}
+function a2aErrorCode(error) {
+	if (typeof error === "object" && error !== null) for (const key of ["code", "name"]) {
+		const descriptor = Object.getOwnPropertyDescriptor(error, key);
+		if (descriptor !== void 0 && "value" in descriptor && typeof descriptor.value === "string") return boundedCode(descriptor.value);
+	}
+	return "A2A_OPERATION_FAILED";
+}
+function a2aIntegrationChildLogger(logger, scope) {
+	assertIdentity(scope, 64, "integration scope");
+	try {
+		return logger?.child({ integrationScope: scope });
+	} catch {
+		return;
+	}
+}
+function log(logger, level, message, fields) {
+	try {
+		logger?.[level](message, fields);
+	} catch {}
+}
+function now() {
+	return globalThis.performance?.now() ?? Date.now();
+}
+function elapsed(startedAt) {
+	const value = now() - startedAt;
+	return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+function message(status) {
+	return status === "success" ? "SDK integration operation completed" : status === "error" ? "SDK integration operation failed" : "SDK integration operation aborted";
+}
+function boundedCode(value) {
+	const normalized = value.replace(/[^A-Za-z0-9_.:-]/g, "_");
+	return (normalized.length === 0 ? "A2A_OPERATION_FAILED" : normalized).slice(0, 128);
+}
+function assertIdentity(value, limit, label) {
+	if (value.length === 0 || value.length > limit) throw new TypeError(`${label} must contain 1-${limit} characters`);
+}
+
+//#endregion
+//#region src/common/cleanup-report.ts
+const NO_USAGE = Object.freeze({
+	logicalCalls: 0,
+	attempts: 0,
+	complete: 0,
+	partial: 0,
+	estimated: 0,
+	missing: 0,
+	notApplicable: 0,
+	possiblyBilledAttemptsWithoutUsage: 0
+});
+/** Build static metadata-only teardown evidence without retaining the thrown value. */
+function cleanupFailure(code, stage, message) {
+	return Object.freeze({
+		code,
+		stage,
+		message,
+		usageCoverage: NO_USAGE,
+		possiblyBilledAttemptsWithoutUsage: 0
+	});
+}
+
+//#endregion
+export { beginA2AIntegrationOperation as i, a2aErrorCode as n, a2aIntegrationChildLogger as r, cleanupFailure as t };
+//# sourceMappingURL=cleanup-report-CTjMJ9EU.mjs.map

package/dist/cleanup-report-CTjMJ9EU.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup-report-CTjMJ9EU.mjs","names":[],"sources":["../src/common/integration-operation.ts","../src/common/cleanup-report.ts"],"sourcesContent":["import type { IntegrationOperationEvidenceFields, SdkLogger } from '@alvin0/ai-agent-sdk-core/observability'\n\nexport const A2A_INTEGRATION_OPERATIONS = Object.freeze({\n  'a2a-client-link': Object.freeze(['agent-card-resolve', 'link', 'send', 'stream', 'unlink']),\n  'a2a-server': Object.freeze(['request', 'execute', 'cancel', 'dispose']),\n} as const)\n\nexport type A2AIntegrationFamily = keyof typeof A2A_INTEGRATION_OPERATIONS\nexport type A2AIntegrationOperationName = (typeof A2A_INTEGRATION_OPERATIONS)[A2AIntegrationFamily][number]\ntype TerminalStatus = 'success' | 'error' | 'aborted'\n\nexport interface A2AIntegrationAttempt {\n  success(): void\n  fail(errorCode?: string): void\n  abort(): void\n}\n\nexport interface A2AIntegrationOperation extends A2AIntegrationAttempt {\n  attempt(attemptNumber: number): A2AIntegrationAttempt\n}\n\nexport function beginA2AIntegrationOperation(\n  logger: SdkLogger | undefined,\n  family: A2AIntegrationFamily,\n  operation: A2AIntegrationOperationName,\n): A2AIntegrationOperation {\n  assertIdentity(operation, 64, 'integration operation')\n  const operationId = crypto.randomUUID(), startedAt = now()\n  log(logger, 'info', 'SDK integration operation started', {\n    integrationSchemaVersion: 1, integrationFamily: family,\n    integrationOperation: operation, operationId, kind: 'logical-start',\n  })\n  let terminal = false\n  const finish = (status: TerminalStatus, errorCode?: string): void => {\n    if (terminal) return\n    terminal = true\n    log(logger, status === 'error' ? 'error' : 'info', message(status), {\n      integrationSchemaVersion: 1, integrationFamily: family,\n      integrationOperation: operation, operationId, kind: 'logical-terminal',\n      status, durationMs: elapsed(startedAt),\n      ...(errorCode === undefined ? {} : { errorCode: boundedCode(errorCode) }),\n    })\n  }\n  return {\n    attempt(attemptNumber) {\n      if (!Number.isSafeInteger(attemptNumber) || attemptNumber < 1) {\n        throw new TypeError('integration attemptNumber must be a positive safe integer')\n      }\n      const attemptId = crypto.randomUUID(), attemptStartedAt = now()\n      log(logger, 'info', 'SDK integration attempt started', {\n        integrationSchemaVersion: 1, integrationFamily: family,\n        integrationOperation: operation, operationId, kind: 'attempt-start',\n        attemptId, attemptNumber,\n      })\n      let ended = false\n      const end = (status: TerminalStatus, errorCode?: string): void => {\n        if (ended) return\n        ended = true\n        log(logger, status === 'error' ? 'error' : 'info', message(status), {\n          integrationSchemaVersion: 1, integrationFamily: family,\n          integrationOperation: operation, operationId, kind: 'attempt-terminal',\n          attemptId, attemptNumber, status, durationMs: elapsed(attemptStartedAt),\n          ...(errorCode === undefined ? {} : { errorCode: boundedCode(errorCode) }),\n        })\n      }\n      return { success: () => end('success'), fail: code => end('error', code), abort: () => end('aborted') }\n    },\n    success: () => finish('success'),\n    fail: code => finish('error', code),\n    abort: () => finish('aborted'),\n  }\n}\n\nexport function a2aErrorCode(error: unknown): string {\n  if (typeof error === 'object' && error !== null) {\n    for (const key of ['code', 'name']) {\n      const descriptor = Object.getOwnPropertyDescriptor(error, key)\n      if (descriptor !== undefined && 'value' in descriptor && typeof descriptor.value === 'string') {\n        return boundedCode(descriptor.value)\n      }\n    }\n  }\n  return 'A2A_OPERATION_FAILED'\n}\n\nexport function a2aIntegrationChildLogger(logger: SdkLogger | undefined, scope: string): SdkLogger | undefined {\n  assertIdentity(scope, 64, 'integration scope')\n  try { return logger?.child({ integrationScope: scope }) } catch { return undefined }\n}\n\nfunction log(logger: SdkLogger | undefined, level: 'info' | 'error', message: string,\n  fields: IntegrationOperationEvidenceFields): void {\n  try { logger?.[level](message, fields) } catch { /* diagnostic observers never own operation correctness */ }\n}\nfunction now(): number { return globalThis.performance?.now() ?? Date.now() }\nfunction elapsed(startedAt: number): number {\n  const value = now() - startedAt\n  return Number.isFinite(value) ? Math.max(0, value) : 0\n}\nfunction message(status: TerminalStatus): string {\n  return status === 'success' ? 'SDK integration operation completed'\n    : status === 'error' ? 'SDK integration operation failed' : 'SDK integration operation aborted'\n}\nfunction boundedCode(value: string): string {\n  const normalized = value.replace(/[^A-Za-z0-9_.:-]/g, '_')\n  return (normalized.length === 0 ? 'A2A_OPERATION_FAILED' : normalized).slice(0, 128)\n}\nfunction assertIdentity(value: string, limit: number, label: string): void {\n  if (value.length === 0 || value.length > limit) throw new TypeError(`${label} must contain 1-${limit} characters`)\n}\n","import type { SupportSafeError } from '@alvin0/ai-agent-sdk-core'\n\nconst NO_USAGE = Object.freeze({ logicalCalls: 0, attempts: 0, complete: 0, partial: 0,\n  estimated: 0, missing: 0, notApplicable: 0, possiblyBilledAttemptsWithoutUsage: 0 })\n\n/** Build static metadata-only teardown evidence without retaining the thrown value. */\nexport function cleanupFailure(code: string, stage: string, message: string): SupportSafeError {\n  return Object.freeze({ code, stage, message, usageCoverage: NO_USAGE,\n    possiblyBilledAttemptsWithoutUsage: 0 })\n}\n"],"mappings":"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"}