@a2a-wrapper/core 1.2.0

package/dist/server/factory.js

@@ -0,0 +1,167 @@
+/**
+ * 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 express from "express";
+import { AGENT_CARD_PATH } from "@a2a-js/sdk";
+import { DefaultRequestHandler, InMemoryTaskStore } from "@a2a-js/sdk/server";
+import { jsonRpcHandler, restHandler, UserBuilder, } from "@a2a-js/sdk/server/express";
+import { buildAgentCard } from "./agent-card.js";
+// ─── createA2AServer ────────────────────────────────────────────────────────
+/**
+ * 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 async function createA2AServer(config, executorFactory, options) {
+    const { server: srv } = config;
+    const port = srv.port ?? 3000;
+    const hostname = srv.hostname ?? "0.0.0.0";
+    const advertiseHost = srv.advertiseHost ?? "localhost";
+    const advertiseProto = srv.advertiseProtocol ?? "http";
+    const protocolVersion = options?.protocolVersion ?? "0.3";
+    // ── 1. Executor ─────────────────────────────────────────────────────────
+    const executor = executorFactory(config);
+    await executor.initialize();
+    // ── 2. Agent card (static, used as base for dynamic rewriting) ──────────
+    const agentCard = buildAgentCard(config);
+    // ── 3. A2A SDK request handler ──────────────────────────────────────────
+    const taskStore = new InMemoryTaskStore();
+    const requestHandler = new DefaultRequestHandler(agentCard, taskStore, executor);
+    // ── 4. Express app ──────────────────────────────────────────────────────
+    const app = express();
+    // ── A2A-Version response header middleware ──────────────────────────────
+    // Every response includes the protocol version this server implements,
+    // enabling clients to detect version mismatches and future negotiation.
+    app.use((_req, res, next) => {
+        res.setHeader("A2A-Version", protocolVersion);
+        next();
+    });
+    // ── Health check ────────────────────────────────────────────────────────
+    app.get("/health", (_req, res) => {
+        res.json({ status: "healthy", agent: agentCard.name });
+    });
+    // ── Dynamic agent card handler ──────────────────────────────────────────
+    // Rewrites endpoint URLs to match the caller's Host + x-forwarded-proto
+    // headers so clients behind Docker / reverse proxies reach the correct
+    // address for JSON-RPC / REST endpoints.
+    const serveAgentCard = (req, res) => {
+        const host = req.headers.host || `${advertiseHost}:${port}`;
+        const proto = req.headers["x-forwarded-proto"] || advertiseProto;
+        const dynamicBase = `${proto}://${host}`;
+        const jsonRpcUrl = `${dynamicBase}/a2a/jsonrpc`;
+        const restUrl = `${dynamicBase}/a2a/rest`;
+        res.json({
+            ...agentCard,
+            url: jsonRpcUrl,
+            additionalInterfaces: [
+                { transport: "JSONRPC", url: jsonRpcUrl },
+                { transport: "REST", url: restUrl },
+            ],
+        });
+    };
+    // Current A2A spec path
+    app.get(`/${AGENT_CARD_PATH}`, serveAgentCard);
+    // Legacy agent card paths for older A2A Inspector versions
+    for (const p of [".well-known/agent.json", ".well-known/agent-json"]) {
+        if (p !== AGENT_CARD_PATH) {
+            app.get(`/${p}`, serveAgentCard);
+        }
+    }
+    // ── A2A transports ──────────────────────────────────────────────────────
+    app.use("/a2a/jsonrpc", jsonRpcHandler({
+        requestHandler,
+        userBuilder: UserBuilder.noAuthentication,
+    }));
+    app.use("/a2a/rest", restHandler({
+        requestHandler,
+        userBuilder: UserBuilder.noAuthentication,
+    }));
+    // ── 5. Wrapper-specific custom routes ───────────────────────────────────
+    if (options?.registerRoutes) {
+        options.registerRoutes(app, executor);
+    }
+    // ── 6. Start listening ──────────────────────────────────────────────────
+    const httpServer = app.listen(port, hostname);
+    // ── 7. Return handle ───────────────────────────────────────────────────
+    return {
+        app,
+        server: httpServer,
+        executor,
+        async shutdown() {
+            httpServer.close();
+            await executor.shutdown();
+        },
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/server/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/server/factory.ts"],"names":[],"mappings":"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"}

package/dist/session/base-session-manager.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Base Session Manager
+ *
+ * Provides the abstract foundation for session lifecycle management across
+ * all A2A wrapper projects. This module handles the mapping from A2A
+ * `contextId` values to backend-specific session entries, TTL-based
+ * expiration with periodic cleanup sweeps, and task-to-session tracking
+ * required for cancel support.
+ *
+ * Wrapper projects extend {@link BaseSessionManager} and implement the
+ * abstract {@link BaseSessionManager.getOrCreate | getOrCreate} method to
+ * provide backend-specific session creation logic (e.g. creating a Copilot
+ * SDK session or an OpenCode session). All shared bookkeeping — context map
+ * management, cleanup timers, task tracking — lives here so that each
+ * wrapper only contains its backend-specific code.
+ *
+ * The class is parameterized by `TSession`, the backend session object type,
+ * enabling full type safety without runtime coupling to any specific backend.
+ *
+ * @module session/base-session-manager
+ */
+import type { SessionConfig } from "../config/types.js";
+/**
+ * Internal session entry stored by {@link BaseSessionManager}.
+ *
+ * Each entry pairs a backend session object with metadata used for
+ * TTL-based expiration and session reuse decisions. The `lastUsed`
+ * timestamp is updated on every successful `getOrCreate` hit so that
+ * active sessions are not prematurely evicted by the cleanup sweep.
+ *
+ * @typeParam TSession - The backend-specific session object type
+ *   (e.g. `CopilotSession`, `string` session ID for OpenCode).
+ */
+export interface SessionEntry<TSession> {
+    /** Unique session identifier assigned by the backend. */
+    sessionId: string;
+    /**
+     * The backend session object.
+     * May be a rich SDK object (CopilotSession) or a simple identifier
+     * (string session ID for OpenCode), depending on the wrapper.
+     */
+    session: TSession;
+    /** Timestamp (ms since epoch) when this session was first created. */
+    createdAt: number;
+    /**
+     * Timestamp (ms since epoch) of last activity on this session.
+     * Updated on every `getOrCreate` cache hit. Used by the cleanup
+     * sweep to determine whether the session has exceeded its TTL.
+     */
+    lastUsed: number;
+}
+/**
+ * Abstract base class for session lifecycle management.
+ *
+ * Manages the mapping from A2A `contextId` to backend session entries,
+ * TTL-based cleanup, and task-to-session tracking for cancel support.
+ * Wrapper projects extend this class and implement
+ * {@link BaseSessionManager.getOrCreate | getOrCreate} to provide
+ * backend-specific session creation logic.
+ *
+ * Key behaviors:
+ * - **TTL-based cleanup**: A periodic timer removes sessions whose
+ *   `lastUsed` timestamp exceeds the configured TTL.
+ * - **Idempotent `startCleanup`**: Calling `startCleanup()` when a timer
+ *   is already running is a safe no-op.
+ * - **Task tracking**: Maps `taskId` → `sessionId` and optionally
+ *   `taskId` → `contextId` so that cancel operations can locate the
+ *   correct session and emit the correct contextId.
+ * - **Protected helpers**: Subclasses access the context map through
+ *   {@link getSessionEntry}, {@link setSessionEntry}, and
+ *   {@link deleteSessionEntry} without direct map access.
+ *
+ * @typeParam TSession - The backend-specific session object type
+ *   (e.g. `CopilotSession`, `string` session ID for OpenCode).
+ */
+export declare abstract class BaseSessionManager<TSession> {
+    /**
+     * Resolved session configuration controlling TTL, cleanup interval,
+     * context reuse, and session title prefix.
+     */
+    protected readonly sessionConfig: Required<SessionConfig>;
+    /** A2A contextId → session entry. */
+    private readonly contextMap;
+    /** taskId → sessionId for cancel support. */
+    private readonly taskMap;
+    /** taskId → contextId for cancel support. */
+    private readonly taskContexts;
+    /** Handle for the periodic cleanup interval, or `null` when stopped. */
+    private cleanupTimer;
+    /**
+     * Create a new session manager instance.
+     *
+     * @param sessionConfig - Fully resolved session configuration. All
+     *   optional fields must already be filled with defaults so that the
+     *   manager can rely on every value being present.
+     */
+    constructor(sessionConfig: Required<SessionConfig>);
+    /**
+     * Start periodic cleanup of expired sessions.
+     *
+     * Sessions whose `lastUsed` timestamp exceeds the configured
+     * {@link SessionConfig.ttl | ttl} are removed from the context map
+     * on each sweep. The sweep interval is controlled by
+     * {@link SessionConfig.cleanupInterval | cleanupInterval}.
+     *
+     * This method is idempotent — calling it when a timer is already
+     * running is a safe no-op.
+     */
+    startCleanup(): void;
+    /**
+     * Stop the periodic cleanup timer.
+     *
+     * Safe to call even if no timer is running. After calling this method,
+     * expired sessions will no longer be automatically evicted until
+     * {@link startCleanup} is called again.
+     */
+    stopCleanup(): void;
+    /**
+     * Get or create a backend session for the given A2A contextId.
+     *
+     * Subclasses implement this method to provide backend-specific session
+     * creation logic. The implementation should use the protected helpers
+     * ({@link getSessionEntry}, {@link setSessionEntry},
+     * {@link deleteSessionEntry}) to interact with the context map.
+     *
+     * When `reuseByContext` is enabled in the session config, the
+     * implementation should check for an existing entry and return its
+     * session if the entry has not exceeded TTL.
+     *
+     * @param contextId - The A2A contextId identifying the conversation.
+     * @returns The backend session object for this context.
+     */
+    abstract getOrCreate(contextId: string): Promise<TSession>;
+    /**
+     * Track a task → session + context mapping for cancel support.
+     *
+     * Called by the executor when a new task begins execution so that
+     * subsequent cancel requests can locate the correct session and
+     * emit the correct contextId in status events.
+     *
+     * @param taskId - The A2A task identifier.
+     * @param sessionId - The backend session identifier handling this task.
+     * @param contextId - Optional A2A contextId associated with this task.
+     */
+    trackTask(taskId: string, sessionId: string, contextId?: string): void;
+    /**
+     * Get the session identifier for a tracked task.
+     *
+     * Used by cancel handlers to find the backend session that should
+     * be interrupted.
+     *
+     * @param taskId - The A2A task identifier.
+     * @returns The session identifier, or `undefined` if the task is not tracked.
+     */
+    getSessionForTask(taskId: string): string | undefined;
+    /**
+     * Get the A2A contextId for a tracked task.
+     *
+     * Used by cancel handlers to emit the correct contextId in status
+     * update events when cancelling a task.
+     *
+     * @param taskId - The A2A task identifier.
+     * @returns The contextId, or `undefined` if the task is not tracked
+     *   or was tracked without a contextId.
+     */
+    getContextForTask(taskId: string): string | undefined;
+    /**
+     * Remove task tracking for a completed or cancelled task.
+     *
+     * Should be called when a task finishes (successfully or otherwise)
+     * to prevent unbounded growth of the task tracking maps.
+     *
+     * @param taskId - The A2A task identifier to stop tracking.
+     */
+    untrackTask(taskId: string): void;
+    /**
+     * Shut down the session manager.
+     *
+     * Stops the cleanup timer and clears all internal maps (context map,
+     * task map, task contexts). After calling this method, the session
+     * manager is in a clean state and should not be reused.
+     *
+     * Subclasses that need to perform additional cleanup (e.g. destroying
+     * backend sessions) should override this method and call `super.shutdown()`.
+     */
+    shutdown(): void;
+    /**
+     * Retrieve a session entry from the context map.
+     *
+     * Subclasses use this in their {@link getOrCreate} implementation to
+     * check for an existing session before creating a new one.
+     *
+     * @param contextId - The A2A contextId to look up.
+     * @returns The session entry, or `undefined` if no session exists
+     *   for this contextId.
+     */
+    protected getSessionEntry(contextId: string): SessionEntry<TSession> | undefined;
+    /**
+     * Store or update a session entry in the context map.
+     *
+     * Subclasses use this in their {@link getOrCreate} implementation to
+     * register a newly created session or update an existing entry.
+     *
+     * @param contextId - The A2A contextId to associate with the entry.
+     * @param entry - The session entry to store.
+     */
+    protected setSessionEntry(contextId: string, entry: SessionEntry<TSession>): void;
+    /**
+     * Remove a session entry from the context map.
+     *
+     * Subclasses use this when a session is destroyed or invalidated
+     * (e.g. backend reports the session no longer exists).
+     *
+     * @param contextId - The A2A contextId whose entry should be removed.
+     */
+    protected deleteSessionEntry(contextId: string): void;
+}
+//# sourceMappingURL=base-session-manager.d.ts.map

package/dist/session/base-session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-session-manager.d.ts","sourceRoot":"","sources":["../../src/session/base-session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY,CAAC,QAAQ;IACpC,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,OAAO,EAAE,QAAQ,CAAC;IAElB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,kBAAkB,CAAC,QAAQ;IAC/C;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAE1D,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6C;IAExE,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D,wEAAwE;IACxE,OAAO,CAAC,YAAY,CAA+C;IAEnE;;;;;;OAMG;gBACS,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC;IAMlD;;;;;;;;;;OAUG;IACH,YAAY,IAAI,IAAI;IAkBpB;;;;;;OAMG;IACH,WAAW,IAAI,IAAI;IASnB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI1D;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;IAOtE;;;;;;;;OAQG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIrD;;;;;;;;;OASG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIrD;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAOjC;;;;;;;;;OASG;IACH,QAAQ,IAAI,IAAI;IAShB;;;;;;;;;OASG;IACH,SAAS,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,SAAS;IAIhF;;;;;;;;OAQG;IACH,SAAS,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI;IAIjF;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAGtD"}

package/dist/session/base-session-manager.js

@@ -0,0 +1,222 @@
+/**
+ * Base Session Manager
+ *
+ * Provides the abstract foundation for session lifecycle management across
+ * all A2A wrapper projects. This module handles the mapping from A2A
+ * `contextId` values to backend-specific session entries, TTL-based
+ * expiration with periodic cleanup sweeps, and task-to-session tracking
+ * required for cancel support.
+ *
+ * Wrapper projects extend {@link BaseSessionManager} and implement the
+ * abstract {@link BaseSessionManager.getOrCreate | getOrCreate} method to
+ * provide backend-specific session creation logic (e.g. creating a Copilot
+ * SDK session or an OpenCode session). All shared bookkeeping — context map
+ * management, cleanup timers, task tracking — lives here so that each
+ * wrapper only contains its backend-specific code.
+ *
+ * The class is parameterized by `TSession`, the backend session object type,
+ * enabling full type safety without runtime coupling to any specific backend.
+ *
+ * @module session/base-session-manager
+ */
+// ─── Abstract Base Class ────────────────────────────────────────────────────
+/**
+ * Abstract base class for session lifecycle management.
+ *
+ * Manages the mapping from A2A `contextId` to backend session entries,
+ * TTL-based cleanup, and task-to-session tracking for cancel support.
+ * Wrapper projects extend this class and implement
+ * {@link BaseSessionManager.getOrCreate | getOrCreate} to provide
+ * backend-specific session creation logic.
+ *
+ * Key behaviors:
+ * - **TTL-based cleanup**: A periodic timer removes sessions whose
+ *   `lastUsed` timestamp exceeds the configured TTL.
+ * - **Idempotent `startCleanup`**: Calling `startCleanup()` when a timer
+ *   is already running is a safe no-op.
+ * - **Task tracking**: Maps `taskId` → `sessionId` and optionally
+ *   `taskId` → `contextId` so that cancel operations can locate the
+ *   correct session and emit the correct contextId.
+ * - **Protected helpers**: Subclasses access the context map through
+ *   {@link getSessionEntry}, {@link setSessionEntry}, and
+ *   {@link deleteSessionEntry} without direct map access.
+ *
+ * @typeParam TSession - The backend-specific session object type
+ *   (e.g. `CopilotSession`, `string` session ID for OpenCode).
+ */
+export class BaseSessionManager {
+    /**
+     * Resolved session configuration controlling TTL, cleanup interval,
+     * context reuse, and session title prefix.
+     */
+    sessionConfig;
+    /** A2A contextId → session entry. */
+    contextMap = new Map();
+    /** taskId → sessionId for cancel support. */
+    taskMap = new Map();
+    /** taskId → contextId for cancel support. */
+    taskContexts = new Map();
+    /** Handle for the periodic cleanup interval, or `null` when stopped. */
+    cleanupTimer = null;
+    /**
+     * Create a new session manager instance.
+     *
+     * @param sessionConfig - Fully resolved session configuration. All
+     *   optional fields must already be filled with defaults so that the
+     *   manager can rely on every value being present.
+     */
+    constructor(sessionConfig) {
+        this.sessionConfig = sessionConfig;
+    }
+    // ─── Cleanup ────────────────────────────────────────────────────────────
+    /**
+     * Start periodic cleanup of expired sessions.
+     *
+     * Sessions whose `lastUsed` timestamp exceeds the configured
+     * {@link SessionConfig.ttl | ttl} are removed from the context map
+     * on each sweep. The sweep interval is controlled by
+     * {@link SessionConfig.cleanupInterval | cleanupInterval}.
+     *
+     * This method is idempotent — calling it when a timer is already
+     * running is a safe no-op.
+     */
+    startCleanup() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [contextId, entry] of this.contextMap) {
+                if (now - entry.lastUsed > this.sessionConfig.ttl) {
+                    this.contextMap.delete(contextId);
+                }
+            }
+        }, this.sessionConfig.cleanupInterval);
+        // Allow the Node.js process to exit even if the timer is still active.
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Stop the periodic cleanup timer.
+     *
+     * Safe to call even if no timer is running. After calling this method,
+     * expired sessions will no longer be automatically evicted until
+     * {@link startCleanup} is called again.
+     */
+    stopCleanup() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    // ─── Task Tracking ──────────────────────────────────────────────────────
+    /**
+     * Track a task → session + context mapping for cancel support.
+     *
+     * Called by the executor when a new task begins execution so that
+     * subsequent cancel requests can locate the correct session and
+     * emit the correct contextId in status events.
+     *
+     * @param taskId - The A2A task identifier.
+     * @param sessionId - The backend session identifier handling this task.
+     * @param contextId - Optional A2A contextId associated with this task.
+     */
+    trackTask(taskId, sessionId, contextId) {
+        this.taskMap.set(taskId, sessionId);
+        if (contextId) {
+            this.taskContexts.set(taskId, contextId);
+        }
+    }
+    /**
+     * Get the session identifier for a tracked task.
+     *
+     * Used by cancel handlers to find the backend session that should
+     * be interrupted.
+     *
+     * @param taskId - The A2A task identifier.
+     * @returns The session identifier, or `undefined` if the task is not tracked.
+     */
+    getSessionForTask(taskId) {
+        return this.taskMap.get(taskId);
+    }
+    /**
+     * Get the A2A contextId for a tracked task.
+     *
+     * Used by cancel handlers to emit the correct contextId in status
+     * update events when cancelling a task.
+     *
+     * @param taskId - The A2A task identifier.
+     * @returns The contextId, or `undefined` if the task is not tracked
+     *   or was tracked without a contextId.
+     */
+    getContextForTask(taskId) {
+        return this.taskContexts.get(taskId);
+    }
+    /**
+     * Remove task tracking for a completed or cancelled task.
+     *
+     * Should be called when a task finishes (successfully or otherwise)
+     * to prevent unbounded growth of the task tracking maps.
+     *
+     * @param taskId - The A2A task identifier to stop tracking.
+     */
+    untrackTask(taskId) {
+        this.taskMap.delete(taskId);
+        this.taskContexts.delete(taskId);
+    }
+    // ─── Shutdown ───────────────────────────────────────────────────────────
+    /**
+     * Shut down the session manager.
+     *
+     * Stops the cleanup timer and clears all internal maps (context map,
+     * task map, task contexts). After calling this method, the session
+     * manager is in a clean state and should not be reused.
+     *
+     * Subclasses that need to perform additional cleanup (e.g. destroying
+     * backend sessions) should override this method and call `super.shutdown()`.
+     */
+    shutdown() {
+        this.stopCleanup();
+        this.contextMap.clear();
+        this.taskMap.clear();
+        this.taskContexts.clear();
+    }
+    // ─── Protected Helpers ──────────────────────────────────────────────────
+    /**
+     * Retrieve a session entry from the context map.
+     *
+     * Subclasses use this in their {@link getOrCreate} implementation to
+     * check for an existing session before creating a new one.
+     *
+     * @param contextId - The A2A contextId to look up.
+     * @returns The session entry, or `undefined` if no session exists
+     *   for this contextId.
+     */
+    getSessionEntry(contextId) {
+        return this.contextMap.get(contextId);
+    }
+    /**
+     * Store or update a session entry in the context map.
+     *
+     * Subclasses use this in their {@link getOrCreate} implementation to
+     * register a newly created session or update an existing entry.
+     *
+     * @param contextId - The A2A contextId to associate with the entry.
+     * @param entry - The session entry to store.
+     */
+    setSessionEntry(contextId, entry) {
+        this.contextMap.set(contextId, entry);
+    }
+    /**
+     * Remove a session entry from the context map.
+     *
+     * Subclasses use this when a session is destroyed or invalidated
+     * (e.g. backend reports the session no longer exists).
+     *
+     * @param contextId - The A2A contextId whose entry should be removed.
+     */
+    deleteSessionEntry(contextId) {
+        this.contextMap.delete(contextId);
+    }
+}
+//# sourceMappingURL=base-session-manager.js.map

package/dist/session/base-session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-session-manager.js","sourceRoot":"","sources":["../../src/session/base-session-manager.ts"],"names":[],"mappings":"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"}