@a2a-wrapper/core 1.2.0

package/dist/executor/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @module executor/types
+ *
+ * Defines the {@link A2AExecutor} interface — the contract that every wrapper
+ * project's executor must satisfy in order to plug into the shared A2A server
+ * infrastructure provided by `@a2a-wrapper/core`.
+ *
+ * The interface is structurally compatible with the `AgentExecutor` type
+ * exported by `@a2a-js/sdk/server`, so implementations can be passed directly
+ * to `DefaultRequestHandler` without an adapter layer. It extends the SDK
+ * contract with lifecycle hooks (`initialize`, `shutdown`) and optional
+ * context-file operations (`getContextContent`, `buildContext`) that are
+ * common across all current wrapper projects.
+ *
+ * @example
+ * ```typescript
+ * import type { A2AExecutor } from "@a2a-wrapper/core";
+ *
+ * class MyExecutor implements A2AExecutor {
+ *   async initialize() { // connect to backend }
+ *   async shutdown()    { // release resources  }
+ *   async execute(ctx, bus) { // handle A2A task }
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/a2a-js/a2a-js | @a2a-js/sdk} for the
+ *   upstream `AgentExecutor` and `RequestContext` definitions.
+ */
+import type { RequestContext, ExecutionEventBus } from "@a2a-js/sdk/server";
+/**
+ * Contract that every wrapper project's executor must satisfy.
+ *
+ * `A2AExecutor` is the single integration point between the shared server
+ * infrastructure (`createA2AServer`, `createCli`) and the backend-specific
+ * logic each wrapper project provides. Implementations are responsible for:
+ *
+ * 1. **Lifecycle** — allocating and releasing backend resources via
+ *    {@link initialize} and {@link shutdown}.
+ * 2. **Task execution** — translating an inbound A2A request into backend
+ *    calls and publishing progress / artifact events via {@link execute}.
+ * 3. **Cancellation** *(optional)* — aborting a running task when the client
+ *    sends a cancel request via {@link cancelTask}.
+ * 4. **Context management** *(optional)* — reading or building a domain
+ *    context file that enriches the backend's system prompt via
+ *    {@link getContextContent} and {@link buildContext}.
+ *
+ * The `execute` and `cancelTask` signatures are intentionally identical to
+ * those on `AgentExecutor` from `@a2a-js/sdk/server`, ensuring that any
+ * `A2AExecutor` instance (with `cancelTask` implemented) is structurally
+ * assignable to the SDK type and can be passed directly to
+ * `DefaultRequestHandler`.
+ *
+ * @remarks
+ * CMMI Level 5 — This interface is the primary extension point for new
+ * wrapper projects. Adding a new backend requires only implementing this
+ * interface; no changes to `@a2a-wrapper/core` are necessary.
+ */
+export interface A2AExecutor {
+    /**
+     * Perform asynchronous startup logic.
+     *
+     * Called once by the server factory after the executor is constructed and
+     * before the HTTP server begins accepting requests. Typical work includes
+     * establishing backend connections, running health checks, registering MCP
+     * servers, and pre-loading configuration or context files.
+     *
+     * @returns A promise that resolves when the executor is fully ready to
+     *   handle requests. The server will not start listening until this
+     *   promise settles.
+     *
+     * @throws If initialization fails, the promise should reject with a
+     *   descriptive error. The server factory will propagate the error and
+     *   prevent the server from starting.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Release all resources held by the executor.
+     *
+     * Called once during graceful shutdown (SIGINT / SIGTERM) after the HTTP
+     * server has stopped accepting new connections. Implementations should
+     * close backend connections, cancel in-flight requests, stop timers, and
+     * perform any other cleanup necessary to avoid resource leaks.
+     *
+     * @returns A promise that resolves when all resources have been released.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Execute an A2A task request.
+     *
+     * This is the core method required by the `@a2a-js/sdk/server`
+     * `AgentExecutor` interface. The server framework calls it for every
+     * inbound `message/send` or `message/stream` JSON-RPC request.
+     *
+     * Implementations should:
+     * 1. Extract the user message and any reference tasks from `ctx`.
+     * 2. Forward the request to the backend system.
+     * 3. Publish progress status events and artifact events on `bus` as
+     *    results arrive from the backend.
+     * 4. Publish a final status event (`completed`, `failed`, or `canceled`)
+     *    before the returned promise resolves.
+     *
+     * @param ctx - The request context containing the user message, task ID,
+     *   context ID, and optional reference tasks. Provided by the A2A SDK's
+     *   `DefaultRequestHandler`.
+     * @param bus - The event bus for publishing `TaskStatusUpdateEvent` and
+     *   `TaskArtifactUpdateEvent` instances back to the client.
+     *
+     * @returns A promise that resolves when execution is complete and all
+     *   events have been published.
+     */
+    execute(ctx: RequestContext, bus: ExecutionEventBus): Promise<void>;
+    /**
+     * Cancel a running task.
+     *
+     * Called when the client sends a `tasks/cancel` JSON-RPC request.
+     * Implementations should abort any in-flight backend work for the given
+     * task and publish a final `canceled` status event on the bus.
+     *
+     * This method is optional. If not implemented, the server will report
+     * that cancellation is not supported for the task.
+     *
+     * @param taskId - The unique identifier of the task to cancel.
+     * @param bus - The event bus for publishing the final `canceled` status
+     *   event.
+     *
+     * @returns A promise that resolves once cancellation is complete and the
+     *   status event has been published.
+     */
+    cancelTask?(taskId: string, bus: ExecutionEventBus): Promise<void>;
+    /**
+     * Read the pre-built domain context file content.
+     *
+     * Returns the current contents of the context file that was previously
+     * generated by {@link buildContext}, or `null` if no context file exists.
+     * The server factory exposes this via the `GET /context` route so that
+     * clients can inspect the active context.
+     *
+     * This method is optional. Executors that do not support context files
+     * may omit it entirely.
+     *
+     * @returns A promise resolving to the context file content as a string,
+     *   or `null` if no context file is available.
+     */
+    getContextContent?(): Promise<string | null>;
+    /**
+     * Build or refresh the domain context file.
+     *
+     * Generates a context file that enriches the backend's system prompt with
+     * domain-specific knowledge (e.g., repository structure, API docs). The
+     * server factory exposes this via the `POST /context/build` route.
+     *
+     * This method is optional. Executors that do not support context building
+     * may omit it entirely.
+     *
+     * @param prompt - An optional prompt or instruction to guide context
+     *   generation. When omitted, the executor should use its default
+     *   context-building strategy.
+     *
+     * @returns A promise resolving to the generated context content as a
+     *   string.
+     */
+    buildContext?(prompt?: string): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/executor/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/executor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;;;;;;OASG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjD"}

package/dist/executor/types.js

@@ -0,0 +1,30 @@
+/**
+ * @module executor/types
+ *
+ * Defines the {@link A2AExecutor} interface — the contract that every wrapper
+ * project's executor must satisfy in order to plug into the shared A2A server
+ * infrastructure provided by `@a2a-wrapper/core`.
+ *
+ * The interface is structurally compatible with the `AgentExecutor` type
+ * exported by `@a2a-js/sdk/server`, so implementations can be passed directly
+ * to `DefaultRequestHandler` without an adapter layer. It extends the SDK
+ * contract with lifecycle hooks (`initialize`, `shutdown`) and optional
+ * context-file operations (`getContextContent`, `buildContext`) that are
+ * common across all current wrapper projects.
+ *
+ * @example
+ * ```typescript
+ * import type { A2AExecutor } from "@a2a-wrapper/core";
+ *
+ * class MyExecutor implements A2AExecutor {
+ *   async initialize() { // connect to backend }
+ *   async shutdown()    { // release resources  }
+ *   async execute(ctx, bus) { // handle A2A task }
+ * }
+ * ```
+ *
+ * @see {@link https://github.com/a2a-js/a2a-js | @a2a-js/sdk} for the
+ *   upstream `AgentExecutor` and `RequestContext` definitions.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/executor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/executor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @a2a-wrapper/core — Public API
+ *
+ * Barrel export for the shared A2A wrapper infrastructure package. Every
+ * symbol re-exported here is part of the public API surface and is covered
+ * by semantic versioning guarantees.
+ *
+ * Wrapper projects should import exclusively from `@a2a-wrapper/core`
+ * rather than reaching into internal module paths. This allows the core
+ * package to reorganise internals without breaking downstream consumers.
+ *
+ * A2A SDK types that wrapper projects commonly reference are re-exported
+ * here behind core-owned names. This isolates downstream code from SDK
+ * major-version upgrades — only this barrel file needs updating when the
+ * SDK ships breaking type changes.
+ *
+ * @module @a2a-wrapper/core
+ * @packageDocumentation
+ */
+export { LogLevel, Logger, createLogger } from "./utils/logger.js";
+export { type Deferred, createDeferred, sleep } from "./utils/deferred.js";
+export { deepMerge, substituteEnvTokens } from "./utils/deep-merge.js";
+export type { SkillConfig, AgentCardConfig, ServerConfig, SessionConfig, BaseFeatureFlags, TimeoutConfig, LoggingConfig, BaseMcpServerConfig, BaseAgentConfig, } from "./config/types.js";
+export { loadConfigFile, resolveConfig } from "./config/loader.js";
+export { publishStatus, publishFinalArtifact, publishStreamingChunk, publishLastChunkMarker, publishTraceArtifact, publishThoughtArtifact, } from "./events/event-publisher.js";
+export { buildAgentCard, type BuildAgentCardInput } from "./server/agent-card.js";
+export { createA2AServer, type ServerOptions, type ServerHandle, } from "./server/factory.js";
+export { BaseSessionManager, type SessionEntry } from "./session/base-session-manager.js";
+export type { A2AExecutor } from "./executor/types.js";
+export { createCli, type CliOptions, parseCommonArgs, type CommonArgsResult, } from "./cli/scaffold.js";
+/** @see {@link https://github.com/a2a-js/a2a-js | @a2a-js/sdk} */
+export type { AgentCard } from "@a2a-js/sdk";
+/** @see {@link https://github.com/a2a-js/a2a-js | @a2a-js/sdk} */
+export type { TaskState, TaskStatusUpdateEvent, TaskArtifactUpdateEvent } from "@a2a-js/sdk";
+/** @see {@link https://github.com/a2a-js/a2a-js | @a2a-js/sdk/server} */
+export type { ExecutionEventBus, RequestContext } from "@a2a-js/sdk/server";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAIvE,YAAY,EACV,WAAW,EACX,eAAe,EACf,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInE,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AAIrC,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAI1F,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,OAAO,EACL,SAAS,EACT,KAAK,UAAU,EACf,eAAe,EACf,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAS3B,kEAAkE;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,kEAAkE;AAClE,YAAY,EAAE,SAAS,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE7F,yEAAyE;AACzE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @a2a-wrapper/core — Public API
+ *
+ * Barrel export for the shared A2A wrapper infrastructure package. Every
+ * symbol re-exported here is part of the public API surface and is covered
+ * by semantic versioning guarantees.
+ *
+ * Wrapper projects should import exclusively from `@a2a-wrapper/core`
+ * rather than reaching into internal module paths. This allows the core
+ * package to reorganise internals without breaking downstream consumers.
+ *
+ * A2A SDK types that wrapper projects commonly reference are re-exported
+ * here behind core-owned names. This isolates downstream code from SDK
+ * major-version upgrades — only this barrel file needs updating when the
+ * SDK ships breaking type changes.
+ *
+ * @module @a2a-wrapper/core
+ * @packageDocumentation
+ */
+// ─── Utilities ──────────────────────────────────────────────────────────────
+export { LogLevel, Logger, createLogger } from "./utils/logger.js";
+export { createDeferred, sleep } from "./utils/deferred.js";
+export { deepMerge, substituteEnvTokens } from "./utils/deep-merge.js";
+export { loadConfigFile, resolveConfig } from "./config/loader.js";
+// ─── Events ─────────────────────────────────────────────────────────────────
+export { publishStatus, publishFinalArtifact, publishStreamingChunk, publishLastChunkMarker, publishTraceArtifact, publishThoughtArtifact, } from "./events/event-publisher.js";
+// ─── Server ─────────────────────────────────────────────────────────────────
+export { buildAgentCard } from "./server/agent-card.js";
+export { createA2AServer, } from "./server/factory.js";
+// ─── Session ────────────────────────────────────────────────────────────────
+export { BaseSessionManager } from "./session/base-session-manager.js";
+// ─── CLI ────────────────────────────────────────────────────────────────────
+export { createCli, parseCommonArgs, } from "./cli/scaffold.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,+EAA+E;AAE/E,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAiB,cAAc,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAgBvE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnE,+EAA+E;AAE/E,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AAErC,+EAA+E;AAE/E,OAAO,EAAE,cAAc,EAA4B,MAAM,wBAAwB,CAAC;AAElF,OAAO,EACL,eAAe,GAGhB,MAAM,qBAAqB,CAAC;AAE7B,+EAA+E;AAE/E,OAAO,EAAE,kBAAkB,EAAqB,MAAM,mCAAmC,CAAC;AAM1F,+EAA+E;AAE/E,OAAO,EACL,SAAS,EAET,eAAe,GAEhB,MAAM,mBAAmB,CAAC"}

package/dist/server/agent-card.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Agent Card Builder
+ *
+ * Constructs an A2A-spec-compliant {@link AgentCard} from resolved
+ * {@link AgentCardConfig} and {@link ServerConfig} sections. This module
+ * is the single source of truth for agent card construction across all
+ * wrapper projects, ensuring consistent endpoint URL computation,
+ * capability flag mapping, and skill serialization.
+ *
+ * Ported from `a2a-copilot/src/server/agent-card.ts` with the following
+ * changes for core-package reuse:
+ *
+ * 1. Accepts `{ agentCard, server }` instead of a full `AgentConfig`.
+ * 2. No logger dependency — the core package does not own a singleton logger.
+ * 3. `stateTransitionHistory` is always `false` (removed in A2A v1.0).
+ *
+ * @module server/agent-card
+ */
+import type { AgentCard } from "@a2a-js/sdk";
+import type { AgentCardConfig, ServerConfig } from "../config/types.js";
+/**
+ * Input shape accepted by {@link buildAgentCard}.
+ *
+ * Only the `agentCard` and `server` configuration sections are required to
+ * construct a complete agent card. This keeps the builder decoupled from
+ * backend-specific configuration and session/timeout settings.
+ */
+export interface BuildAgentCardInput {
+    /** Agent identity and capability configuration. */
+    agentCard: AgentCardConfig;
+    /** Server networking configuration used to compute endpoint URLs. */
+    server: ServerConfig;
+}
+/**
+ * Constructs an A2A {@link AgentCard} from resolved configuration.
+ *
+ * Computes endpoint URLs from the `server` section, maps capability flags
+ * and skills from the `agentCard` section, and advertises both JSON-RPC and
+ * REST transports via `additionalInterfaces`.
+ *
+ * Key behaviors:
+ * - `stateTransitionHistory` is always set to `false` regardless of input,
+ *   because this capability was removed in the A2A v1.0 specification.
+ * - The primary `url` field points to the JSON-RPC endpoint for backward
+ *   compatibility with v0.3.x clients.
+ * - `protocolVersion` defaults to `"0.3.0"` when not explicitly configured.
+ * - `supportsAuthenticatedExtendedCard` is always `false` unless explicitly
+ *   configured otherwise in a future extension.
+ *
+ * @param config - Object containing `agentCard` and `server` configuration
+ *   sections. See {@link BuildAgentCardInput} for the expected shape.
+ * @returns A fully populated {@link AgentCard} ready to be served at
+ *   `/.well-known/agent-card.json`.
+ *
+ * @example
+ * ```typescript
+ * import { buildAgentCard } from "@a2a-wrapper/core";
+ *
+ * const card = buildAgentCard({
+ *   agentCard: { name: "My Agent", description: "Does things" },
+ *   server: { port: 3000, advertiseHost: "localhost" },
+ * });
+ * ```
+ */
+export declare function buildAgentCard(config: BuildAgentCardInput): AgentCard;
+//# sourceMappingURL=agent-card.d.ts.map

package/dist/server/agent-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-card.d.ts","sourceRoot":"","sources":["../../src/server/agent-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAe,MAAM,oBAAoB,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,SAAS,EAAE,eAAe,CAAC;IAC3B,qEAAqE;IACrE,MAAM,EAAE,YAAY,CAAC;CACtB;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,CA6CrE"}

package/dist/server/agent-card.js

@@ -0,0 +1,114 @@
+/**
+ * Agent Card Builder
+ *
+ * Constructs an A2A-spec-compliant {@link AgentCard} from resolved
+ * {@link AgentCardConfig} and {@link ServerConfig} sections. This module
+ * is the single source of truth for agent card construction across all
+ * wrapper projects, ensuring consistent endpoint URL computation,
+ * capability flag mapping, and skill serialization.
+ *
+ * Ported from `a2a-copilot/src/server/agent-card.ts` with the following
+ * changes for core-package reuse:
+ *
+ * 1. Accepts `{ agentCard, server }` instead of a full `AgentConfig`.
+ * 2. No logger dependency — the core package does not own a singleton logger.
+ * 3. `stateTransitionHistory` is always `false` (removed in A2A v1.0).
+ *
+ * @module server/agent-card
+ */
+/**
+ * Maps a {@link SkillConfig} to the A2A `AgentSkill` shape expected by the SDK.
+ *
+ * The `examples` field is included only when the source array is non-empty,
+ * keeping the serialized agent card minimal.
+ *
+ * @param skill - The skill configuration to transform.
+ * @returns An object conforming to the A2A `AgentSkill` interface.
+ *
+ * @internal
+ */
+function mapSkill(skill) {
+    return {
+        id: skill.id,
+        name: skill.name,
+        description: skill.description,
+        tags: skill.tags ?? [],
+        ...(skill.examples?.length ? { examples: skill.examples } : {}),
+    };
+}
+/**
+ * Constructs an A2A {@link AgentCard} from resolved configuration.
+ *
+ * Computes endpoint URLs from the `server` section, maps capability flags
+ * and skills from the `agentCard` section, and advertises both JSON-RPC and
+ * REST transports via `additionalInterfaces`.
+ *
+ * Key behaviors:
+ * - `stateTransitionHistory` is always set to `false` regardless of input,
+ *   because this capability was removed in the A2A v1.0 specification.
+ * - The primary `url` field points to the JSON-RPC endpoint for backward
+ *   compatibility with v0.3.x clients.
+ * - `protocolVersion` defaults to `"0.3.0"` when not explicitly configured.
+ * - `supportsAuthenticatedExtendedCard` is always `false` unless explicitly
+ *   configured otherwise in a future extension.
+ *
+ * @param config - Object containing `agentCard` and `server` configuration
+ *   sections. See {@link BuildAgentCardInput} for the expected shape.
+ * @returns A fully populated {@link AgentCard} ready to be served at
+ *   `/.well-known/agent-card.json`.
+ *
+ * @example
+ * ```typescript
+ * import { buildAgentCard } from "@a2a-wrapper/core";
+ *
+ * const card = buildAgentCard({
+ *   agentCard: { name: "My Agent", description: "Does things" },
+ *   server: { port: 3000, advertiseHost: "localhost" },
+ * });
+ * ```
+ */
+export function buildAgentCard(config) {
+    const { agentCard, server } = config;
+    const host = server.advertiseHost ?? server.hostname ?? "localhost";
+    const port = server.port ?? 3000;
+    // Use configured protocol; defaults to "http" for local dev.
+    // Set advertiseProtocol: "https" in config for production deployments.
+    const proto = server.advertiseProtocol ?? "http";
+    const baseUrl = `${proto}://${host}:${port}`;
+    const jsonRpcUrl = `${baseUrl}/a2a/jsonrpc`;
+    const restUrl = `${baseUrl}/a2a/rest`;
+    const card = {
+        name: agentCard.name,
+        description: agentCard.description,
+        // Primary endpoint (v0.3.x required field; retained for backward compat with
+        // v0.3.x clients and the current SDK, which still reads this field).
+        url: jsonRpcUrl,
+        ...(agentCard.provider
+            ? { provider: { organization: agentCard.provider.organization, url: agentCard.provider.url ?? "" } }
+            : {}),
+        version: agentCard.version ?? "1.0.0",
+        capabilities: {
+            streaming: agentCard.streaming ?? true,
+            pushNotifications: agentCard.pushNotifications ?? false,
+            // stateTransitionHistory was removed in A2A v1.0 as unimplemented.
+            // We advertise false so v0.3.x clients that check this flag don't expect history.
+            stateTransitionHistory: false,
+        },
+        // Retain protocolVersion for v0.3.x client backward compatibility.
+        // When the SDK ships v1.0 types this moves into additionalInterfaces[].protocolVersion.
+        protocolVersion: agentCard.protocolVersion ?? "0.3.0",
+        skills: (agentCard.skills ?? []).map(mapSkill),
+        defaultInputModes: agentCard.defaultInputModes ?? ["text"],
+        defaultOutputModes: agentCard.defaultOutputModes ?? ["text"],
+        // additionalInterfaces: advertise all supported transports so that v1.0-aware
+        // clients can discover the REST endpoint and future protocol versions.
+        additionalInterfaces: [
+            { transport: "JSONRPC", url: jsonRpcUrl },
+            { transport: "REST", url: restUrl },
+        ],
+        // Do not advertise an authenticated extended card unless explicitly configured.
+        supportsAuthenticatedExtendedCard: false,
+    };
+    return card;
+}
+//# sourceMappingURL=agent-card.js.map

package/dist/server/agent-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-card.js","sourceRoot":"","sources":["../../src/server/agent-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmBH;;;;;;;;;;GAUG;AACH,SAAS,QAAQ,CAAC,KAAkB;IAClC,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,cAAc,CAAC,MAA2B;IACxD,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,QAAQ,IAAI,WAAW,CAAC;IACpE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC;IACjC,6DAA6D;IAC7D,uEAAuE;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,iBAAiB,IAAI,MAAM,CAAC;IACjD,MAAM,OAAO,GAAG,GAAG,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;IAC7C,MAAM,UAAU,GAAG,GAAG,OAAO,cAAc,CAAC;IAC5C,MAAM,OAAO,GAAG,GAAG,OAAO,WAAW,CAAC;IAEtC,MAAM,IAAI,GAAc;QACtB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,6EAA6E;QAC7E,qEAAqE;QACrE,GAAG,EAAE,UAAU;QACf,GAAG,CAAC,SAAS,CAAC,QAAQ;YACpB,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,YAAY,EAAE,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,EAAE,EAAE,EAAE;YACpG,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,OAAO;QACrC,YAAY,EAAE;YACZ,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,IAAI;YACtC,iBAAiB,EAAE,SAAS,CAAC,iBAAiB,IAAI,KAAK;YACvD,mEAAmE;YACnE,kFAAkF;YAClF,sBAAsB,EAAE,KAAK;SAC9B;QACD,mEAAmE;QACnE,wFAAwF;QACxF,eAAe,EAAE,SAAS,CAAC,eAAe,IAAI,OAAO;QACrD,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC9C,iBAAiB,EAAE,SAAS,CAAC,iBAAiB,IAAI,CAAC,MAAM,CAAC;QAC1D,kBAAkB,EAAE,SAAS,CAAC,kBAAkB,IAAI,CAAC,MAAM,CAAC;QAC5D,8EAA8E;QAC9E,uEAAuE;QACvE,oBAAoB,EAAE;YACpB,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE;YACzC,EAAE,SAAS,EAAE,MAAM,EAAK,GAAG,EAAE,OAAO,EAAE;SACvC;QACD,gFAAgF;QAChF,iCAAiC,EAAE,KAAK;KACzC,CAAC;IAEF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/server/factory.d.ts

@@ -0,0 +1,159 @@
+/**
+ * A2A Server Factory
+ *
+ * Creates, wires, and starts an Express-based A2A HTTP server with all
+ * standard protocol routes. This module is the single entry point for
+ * server bootstrapping across all wrapper projects, ensuring consistent
+ * route registration, middleware ordering, and lifecycle management.
+ *
+ * Ported from `a2a-copilot/src/server/index.ts` and
+ * `a2a-opencode/src/server/index.ts` with the following changes for
+ * core-package reuse:
+ *
+ * 1. Accepts a generic `executorFactory` callback instead of importing a
+ *    concrete executor class — the core package has zero knowledge of any
+ *    specific backend.
+ * 2. Supports an optional {@link ServerOptions.registerRoutes} hook so that
+ *    wrapper projects can mount custom routes (e.g. `/context`, `/mcp/status`)
+ *    before the server starts listening.
+ * 3. The `A2A-Version` response header value is configurable via
+ *    {@link ServerOptions.protocolVersion} (default `"0.3"`).
+ * 4. Wrapper-specific routes (context API, MCP status) are **not** included —
+ *    those belong in each wrapper's `registerRoutes` hook.
+ *
+ * @module server/factory
+ */
+import { type Express } from "express";
+import type { BaseAgentConfig } from "../config/types.js";
+/**
+ * Minimal executor contract required by the server factory.
+ *
+ * Every wrapper project implements this interface with its backend-specific
+ * logic (e.g. `CopilotExecutor`, `OpenCodeExecutor`). The server factory
+ * calls {@link initialize} during startup and {@link shutdown} during
+ * graceful teardown.
+ *
+ * The `execute` and `cancelTask` methods are inherited from the SDK's
+ * `AgentExecutor` type and are invoked by {@link DefaultRequestHandler}
+ * when processing A2A JSON-RPC / REST requests.
+ */
+export interface A2AExecutor {
+    /**
+     * Perform asynchronous startup logic (e.g. connect to backend, register
+     * MCP servers, warm caches). Called once before the HTTP server begins
+     * accepting requests.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Perform graceful cleanup (e.g. close backend connections, flush buffers).
+     * Called when the server is shutting down.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Optional customization hooks for the A2A server.
+ *
+ * Wrapper projects pass these options to {@link createA2AServer} to inject
+ * custom routes and override protocol-level defaults without modifying the
+ * core server wiring.
+ */
+export interface ServerOptions {
+    /**
+     * A2A protocol version advertised in the `A2A-Version` response header.
+     *
+     * This value is sent on **every** HTTP response so that clients can
+     * detect the server's protocol level. Future A2A spec versions can be
+     * supported by changing this single value.
+     *
+     * @default "0.3"
+     */
+    protocolVersion?: string;
+    /**
+     * Hook invoked after standard routes are registered but **before** the
+     * server starts listening. Use this to mount wrapper-specific endpoints
+     * (e.g. `/context`, `/context/build`, `/mcp/status`).
+     *
+     * @param app      - The Express application instance.
+     * @param executor - The initialized executor, available for route handlers
+     *                   that need to delegate to the backend.
+     */
+    registerRoutes?: (app: Express, executor: A2AExecutor) => void;
+}
+/**
+ * Handle returned by {@link createA2AServer} for lifecycle management.
+ *
+ * Callers use this handle to access the Express app (e.g. for supertest),
+ * the underlying HTTP server, the initialized executor, and a `shutdown`
+ * method for graceful teardown.
+ */
+export interface ServerHandle {
+    /** The Express application instance with all routes registered. */
+    app: Express;
+    /** The Node.js HTTP server returned by `app.listen()`. */
+    server: ReturnType<Express["listen"]>;
+    /** The initialized backend executor. */
+    executor: A2AExecutor;
+    /**
+     * Gracefully shut down the server and executor.
+     *
+     * Closes the HTTP server so no new connections are accepted, then
+     * calls `executor.shutdown()` for backend cleanup.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create, wire, and start an A2A-compliant Express server.
+ *
+ * This function is the primary entry point for all wrapper projects. It:
+ *
+ * 1. Instantiates the backend executor via the supplied `executorFactory`.
+ * 2. Builds the static agent card from resolved configuration.
+ * 3. Creates the A2A SDK request handler with an in-memory task store.
+ * 4. Mounts middleware and standard routes:
+ *    - `A2A-Version` response header on every response.
+ *    - `GET /health` — health check endpoint.
+ *    - `GET /.well-known/agent-card.json` — dynamic agent card with URL
+ *      rewriting for reverse proxy compatibility.
+ *    - Legacy agent card paths (`.well-known/agent.json`,
+ *      `.well-known/agent-json`).
+ *    - `POST /a2a/jsonrpc` — JSON-RPC transport.
+ *    - `/a2a/rest` — REST transport.
+ * 5. Invokes the optional `registerRoutes` hook for wrapper-specific routes.
+ * 6. Starts listening on the configured hostname and port.
+ * 7. Returns a {@link ServerHandle} for lifecycle management.
+ *
+ * @typeParam T - The full configuration type, extending {@link BaseAgentConfig}.
+ *   The generic parameter ensures the `executorFactory` receives the same
+ *   fully-resolved config type that the wrapper project defined.
+ *
+ * @param config          - Fully resolved configuration with all fields populated.
+ * @param executorFactory - Factory function that creates the backend-specific
+ *                          executor from the resolved config. The server factory
+ *                          calls `executor.initialize()` before registering routes.
+ * @param options         - Optional server customization (protocol version,
+ *                          custom route hooks).
+ * @returns A promise resolving to a {@link ServerHandle} once the server is
+ *   listening and ready to accept requests.
+ *
+ * @example
+ * ```typescript
+ * import { createA2AServer } from "@a2a-wrapper/core";
+ * import { MyExecutor } from "./my-executor.js";
+ *
+ * const handle = await createA2AServer(
+ *   resolvedConfig,
+ *   (cfg) => new MyExecutor(cfg),
+ *   {
+ *     protocolVersion: "0.3",
+ *     registerRoutes: (app, executor) => {
+ *       app.get("/custom", (_req, res) => res.json({ ok: true }));
+ *     },
+ *   },
+ * );
+ *
+ * // Graceful shutdown on SIGTERM
+ * process.on("SIGTERM", () => handle.shutdown());
+ * ```
+ */
+export declare function createA2AServer<T extends BaseAgentConfig<unknown>>(config: Required<T>, executorFactory: (config: Required<T>) => A2AExecutor, options?: ServerOptions): Promise<ServerHandle>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/server/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/server/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAgB,EAAE,KAAK,OAAO,EAAuB,MAAM,SAAS,CAAC;AASrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK1D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAID;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAChE;AAID;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,GAAG,EAAE,OAAO,CAAC;IAEb,0DAA0D;IAC1D,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtC,wCAAwC;IACxC,QAAQ,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAsB,eAAe,CAAC,CAAC,SAAS,eAAe,CAAC,OAAO,CAAC,EACtE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,eAAe,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,WAAW,EACrD,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAwGvB"}