@mcpmesh/sdk 1.3.4 → 2.0.0-beta.1

package/dist/a2a/producer/public-url-cache.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Process-local cache of registry-stamped public URLs for each
+ * `mesh.a2a.mount(...)` surface (spec §8.2).
+ *
+ * Populated from the registry's heartbeat-response handler when it returns
+ * a `surfaces[].public_url` entry for each surface. Read by the agent-card
+ * endpoint at request time.
+ *
+ * Mirrors Python's module-level `_PUBLIC_URL_CACHE` in
+ * `mesh/a2a.py:202-228` and Java's `MeshA2APublicUrlCache`. Process-local,
+ * not persisted across restarts — the registry re-stamps on the next
+ * heartbeat.
+ *
+ * When the cache has no entry for a given `(path, skillId)`, the agent
+ * card falls back to building a local-form URL from the agent's
+ * configured host:port. Returning an externally-reachable FQDN matters
+ * once the producer is deployed behind a load balancer or ingress.
+ *
+ * ## Cross-runtime parity status
+ *
+ * The Rust core does NOT currently emit a `surface_updated` mesh event
+ * back to TypeScript (or Java) consumers — `JsMeshEvent` covers only
+ * dependency / LLM / lifecycle signals today. When the registry adds
+ * surface URL stamping events (separate follow-up issue), the
+ * api-runtime event loop populates this cache via {@link put}. Until then
+ * the cache stays empty and the agent card uses the local-fallback URL
+ * (which is what Python does today when the registry hasn't stamped a
+ * URL yet).
+ */
+/**
+ * Process-wide singleton cache of registry-stamped public URLs.
+ *
+ * Mirrors Java's `MeshA2APublicUrlCache` API.
+ */
+export declare class A2APublicUrlCache {
+    private static instance;
+    private readonly cache;
+    private constructor();
+    static getInstance(): A2APublicUrlCache;
+    /** Reset the cache (mainly for testing). */
+    static reset(): void;
+    /**
+     * Cache (or clear) the registry-stamped public URL for one surface.
+     * Pass `null` / empty `publicUrl` to clear the cached entry — matches
+     * Python's `update_public_url_cache` behavior (drops the entry when
+     * the registry stops stamping it).
+     */
+    put(path: string, skillId: string, publicUrl: string | null | undefined): void;
+    /**
+     * @returns the cached public URL for `(path, skillId)`, or `undefined`
+     *     when no entry exists. Callers MUST fall back to a locally-built
+     *     URL form when this returns `undefined`.
+     */
+    get(path: string, skillId: string): string | undefined;
+    /** @returns current cache size. For diagnostics + tests. */
+    size(): number;
+    /** Drop every cached entry. For tests and shutdown cleanup. */
+    clear(): void;
+    private makeKey;
+}
+/**
+ * Build the local-form fallback URL for one surface. Used when the
+ * registry hasn't stamped a public URL yet (spec §2.4).
+ *
+ * Format: `http://{host}:{port}{path}` — not addressable from outside
+ * the local network, but appropriate for dev/CI.
+ *
+ * IPv6 hosts are bracketed per RFC 3986 §3.2.2 (parity with Java's
+ * `MeshA2ACardBuilder.localFallbackUrl` #934 A6 fix). Hosts that already
+ * arrive bracketed (e.g. `[::1]`) are not re-bracketed.
+ */
+export declare function buildLocalFallbackUrl(host: string | undefined, port: number | undefined, path: string): string;
+//# sourceMappingURL=public-url-cache.d.ts.map

package/dist/a2a/producer/public-url-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-url-cache.d.ts","sourceRoot":"","sources":["../../../src/a2a/producer/public-url-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IAEnD,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,iBAAiB;IAOvC,4CAA4C;IAC5C,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAS9E;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAItD,4DAA4D;IAC5D,IAAI,IAAI,MAAM;IAId,+DAA+D;IAC/D,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,OAAO;CAGhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GACX,MAAM,CAaR"}

package/dist/a2a/producer/public-url-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-url-cache.js","sourceRoot":"","sources":["../../../src/a2a/producer/public-url-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IACpB,MAAM,CAAC,QAAQ,GAA6B,IAAI,CAAC;IACxC,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEnD,gBAAuB,CAAC;IAExB,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,CAAC;YAChC,iBAAiB,CAAC,QAAQ,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACvD,CAAC;QACD,OAAO,iBAAiB,CAAC,QAAQ,CAAC;IACpC,CAAC;IAED,4CAA4C;IAC5C,MAAM,CAAC,KAAK;QACV,iBAAiB,CAAC,QAAQ,GAAG,IAAI,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,SAAoC;QACrE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAY,EAAE,OAAe;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,4DAA4D;IAC5D,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,+DAA+D;IAC/D,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,uEAAuE;IACvE,iEAAiE;IACzD,OAAO,CAAC,IAAY,EAAE,OAAe;QAC3C,OAAO,GAAG,IAAI,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;IACpC,CAAC;;AAGH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAwB,EACxB,IAAwB,EACxB,IAAY;IAEZ,MAAM,QAAQ,GAAG,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;IAC9D,0EAA0E;IAC1E,uEAAuE;IACvE,uEAAuE;IACvE,MAAM,QAAQ,GACZ,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC;QACjD,CAAC,CAAC,IAAI,QAAQ,GAAG;QACjB,CAAC,CAAC,QAAQ,CAAC;IACf,IAAI,IAAI,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,UAAU,QAAQ,IAAI,IAAI,GAAG,IAAI,EAAE,CAAC;IAC7C,CAAC;IACD,OAAO,UAAU,QAAQ,GAAG,IAAI,EAAE,CAAC;AACrC,CAAC"}

package/dist/a2a/producer/registry.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Registry for `mesh.a2a.mount(...)` producer surfaces (issue #933).
+ *
+ * Mirrors the role of `RouteRegistry` on the `mesh.route()` side: built at
+ * mount time, queried during request dispatch (for path-to-surface lookup),
+ * card render, auth gating, and heartbeat envelope construction.
+ *
+ * Single process-wide singleton (matches `RouteRegistry`). Each mount call
+ * registers a unique path; duplicate paths throw at mount time so wiring
+ * mistakes surface synchronously instead of as silent overrides.
+ *
+ * Cross-cuts with `RouteRegistry`: A2A surfaces declare mesh dependencies
+ * just like routes, and the producer reuses `RouteRegistry` for dependency
+ * resolution so the same DDDI plumbing powers both surfaces. Each mount
+ * registers its dependencies as a synthetic route in `RouteRegistry`; the
+ * surface keeps a back-reference to that route's `routeId` so dispatch can
+ * resolve injected `McpMeshTool` proxies.
+ */
+import type { DependencySpec, NormalizedDependency } from "../../types.js";
+/**
+ * Captured metadata for a single `mesh.a2a.mount(...)` call.
+ *
+ * Constructed once at mount time and immutable thereafter — the dispatcher
+ * reads these fields on every request.
+ */
+export interface A2ASurfaceMetadata {
+    /** URL path prefix for this surface; must start with `/` and not end with `/`. */
+    readonly path: string;
+    /** A2A skill identifier, kebab-case canonical (e.g., `"get-date"`). */
+    readonly skillId: string;
+    /** Human-readable skill name (defaults to `skillId` when unset). */
+    readonly skillName: string;
+    /** Free-form skill description (`""` when unset). */
+    readonly description: string;
+    /** Skill tags surfaced on the agent card. */
+    readonly tags: readonly string[];
+    /** Normalized dependencies (matches `RouteMetadata.dependencies`). */
+    readonly dependencies: readonly NormalizedDependency[];
+    /**
+     * Auth scheme — `"bearer"` enables the presence-check gate (spec §6.2),
+     * `""` leaves the path open. Phase 1 supports only `"bearer"`.
+     */
+    readonly auth: "" | "bearer";
+    /**
+     * The `routeId` returned by `RouteRegistry.registerRoute` for this surface's
+     * dependencies — used by the dispatcher to look up resolved `McpMeshTool`
+     * proxies by position via `RouteRegistry.getDependenciesForRoute(routeId)`.
+     */
+    readonly routeId: string;
+}
+/**
+ * Configuration object passed to `mesh.a2a.mount(...)`.
+ */
+export interface A2AMountConfig {
+    /** URL path prefix for this surface. MUST start with `/`. */
+    path: string;
+    /** A2A skill identifier (kebab-case). MUST be non-empty. */
+    skillId: string;
+    /** Human-readable skill name. Defaults to `skillId` when unset. */
+    skillName?: string;
+    /** Free-form skill description. */
+    description?: string;
+    /** Skill tags surfaced on the agent card. */
+    tags?: string[];
+    /** Mesh dependencies to inject into the handler (DDDI). */
+    dependencies?: DependencySpec[];
+    /**
+     * Auth scheme — `"bearer"` enables the presence-check gate (spec §6.2).
+     * Default: no auth gate.
+     */
+    auth?: "bearer";
+}
+/**
+ * Singleton registry for `mesh.a2a.mount(...)` producer surfaces.
+ *
+ * Insertion order is preserved (mirrors Java's `MeshA2ARegistry`) so the
+ * heartbeat envelope's `surfaces[]` array order stays stable across
+ * restarts.
+ */
+export declare class A2AProducerRegistry {
+    private static instance;
+    private readonly surfacesByPath;
+    private constructor();
+    static getInstance(): A2AProducerRegistry;
+    /** Reset the registry (mainly for testing). */
+    static reset(): void;
+    /**
+     * Register an A2A surface. Throws on duplicate path so wiring mistakes
+     * fail loudly instead of silently overriding (matches Java's
+     * `MeshA2ARegistry.register`).
+     */
+    register(metadata: A2ASurfaceMetadata): void;
+    /** Look up a surface by path. Returns `undefined` when no surface owns it. */
+    getByPath(path: string): A2ASurfaceMetadata | undefined;
+    /** @returns insertion-ordered list of every registered surface. */
+    getAll(): A2ASurfaceMetadata[];
+    /** @returns `true` when at least one surface is registered. */
+    hasSurfaces(): boolean;
+    /** @returns number of registered surfaces. */
+    size(): number;
+    /**
+     * Build the `(agentType, surfacesJson)` pair the napi binding expects on
+     * `JsAgentSpec.surfaces` and on `JsAgentHandle.updateSurfaces(...)` (issue
+     * #938). Centralizes the {@link buildHeartbeatSurfaces} → JSON.stringify
+     * → flip-agentType logic so the three callers — `ApiRuntime.start`,
+     * `MeshAgent.startHeartbeat`, and `mesh.a2a.mount` — emit identical
+     * payloads.
+     *
+     * `nonA2aType` is the agent_type to use when no A2A surfaces are
+     * registered ({@code "api"} for consumer-only Express apps, {@code "mcp_agent"}
+     * for full MCP agents). When at least one surface is registered the
+     * agent_type flips to {@code "a2a"} (matches Python's
+     * `heartbeat_preparation.py:371-389`).
+     *
+     * Empty surfaces arrays are encoded as `undefined` so the wire stays
+     * clean — the napi binding's `surfaces?: string` field is omitted by
+     * `skip_serializing_if` in Rust when None.
+     */
+    buildAgentSpecContribution(nonA2aType?: "api" | "mcp_agent"): {
+        agentType: "a2a" | "api" | "mcp_agent";
+        surfacesJson: string | undefined;
+    };
+    /**
+     * Build the heartbeat `a2a_surfaces[]` array (spec §2.1).
+     *
+     * Required fields (`path`, `skill_id`) are always emitted. `name` is
+     * always emitted because mount-time defaults `skillName` to `skillId`
+     * (see mount.ts), so it is never empty at this point. The remaining
+     * optional fields (`description`, `tags`) are emitted ONLY when set —
+     * never as empty strings or empty arrays — so the registry's OpenAPI
+     * defaults (`input_modes: ["application/json"]`, etc.) aren't overridden
+     * with empty values. Spec §2.1 is explicit about this.
+     *
+     * @returns list of plain-object surface entries ready for JSON serialization
+     */
+    buildHeartbeatSurfaces(): Array<Record<string, unknown>>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/a2a/producer/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/a2a/producer/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,EAAE,GAAG,QAAQ,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAoC;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyC;IAExE,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,mBAAmB;IAOzC,+CAA+C;IAC/C,MAAM,CAAC,KAAK,IAAI,IAAI;IAIpB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;IAW5C,8EAA8E;IAC9E,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIvD,mEAAmE;IACnE,MAAM,IAAI,kBAAkB,EAAE;IAI9B,+DAA+D;IAC/D,WAAW,IAAI,OAAO;IAItB,8CAA8C;IAC9C,IAAI,IAAI,MAAM;IAId;;;;;;;;;;;;;;;;;OAiBG;IACH,0BAA0B,CACxB,UAAU,GAAE,KAAK,GAAG,WAAmB,GACtC;QAAE,SAAS,EAAE,KAAK,GAAG,KAAK,GAAG,WAAW,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE;IAW/E;;;;;;;;;;;;OAYG;IACH,sBAAsB,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAwBzD"}

package/dist/a2a/producer/registry.js

@@ -0,0 +1,117 @@
+/**
+ * Singleton registry for `mesh.a2a.mount(...)` producer surfaces.
+ *
+ * Insertion order is preserved (mirrors Java's `MeshA2ARegistry`) so the
+ * heartbeat envelope's `surfaces[]` array order stays stable across
+ * restarts.
+ */
+export class A2AProducerRegistry {
+    static instance = null;
+    surfacesByPath = new Map();
+    constructor() { }
+    static getInstance() {
+        if (!A2AProducerRegistry.instance) {
+            A2AProducerRegistry.instance = new A2AProducerRegistry();
+        }
+        return A2AProducerRegistry.instance;
+    }
+    /** Reset the registry (mainly for testing). */
+    static reset() {
+        A2AProducerRegistry.instance = null;
+    }
+    /**
+     * Register an A2A surface. Throws on duplicate path so wiring mistakes
+     * fail loudly instead of silently overriding (matches Java's
+     * `MeshA2ARegistry.register`).
+     */
+    register(metadata) {
+        if (this.surfacesByPath.has(metadata.path)) {
+            const existing = this.surfacesByPath.get(metadata.path);
+            throw new Error(`mesh.a2a.mount: path collision: '${metadata.path}' is already registered ` +
+                `(existing skillId=${existing.skillId}). Each producer path must be unique.`);
+        }
+        this.surfacesByPath.set(metadata.path, metadata);
+    }
+    /** Look up a surface by path. Returns `undefined` when no surface owns it. */
+    getByPath(path) {
+        return this.surfacesByPath.get(path);
+    }
+    /** @returns insertion-ordered list of every registered surface. */
+    getAll() {
+        return Array.from(this.surfacesByPath.values());
+    }
+    /** @returns `true` when at least one surface is registered. */
+    hasSurfaces() {
+        return this.surfacesByPath.size > 0;
+    }
+    /** @returns number of registered surfaces. */
+    size() {
+        return this.surfacesByPath.size;
+    }
+    /**
+     * Build the `(agentType, surfacesJson)` pair the napi binding expects on
+     * `JsAgentSpec.surfaces` and on `JsAgentHandle.updateSurfaces(...)` (issue
+     * #938). Centralizes the {@link buildHeartbeatSurfaces} → JSON.stringify
+     * → flip-agentType logic so the three callers — `ApiRuntime.start`,
+     * `MeshAgent.startHeartbeat`, and `mesh.a2a.mount` — emit identical
+     * payloads.
+     *
+     * `nonA2aType` is the agent_type to use when no A2A surfaces are
+     * registered ({@code "api"} for consumer-only Express apps, {@code "mcp_agent"}
+     * for full MCP agents). When at least one surface is registered the
+     * agent_type flips to {@code "a2a"} (matches Python's
+     * `heartbeat_preparation.py:371-389`).
+     *
+     * Empty surfaces arrays are encoded as `undefined` so the wire stays
+     * clean — the napi binding's `surfaces?: string` field is omitted by
+     * `skip_serializing_if` in Rust when None.
+     */
+    buildAgentSpecContribution(nonA2aType = "api") {
+        if (!this.hasSurfaces()) {
+            return { agentType: nonA2aType, surfacesJson: undefined };
+        }
+        const surfaces = this.buildHeartbeatSurfaces();
+        return {
+            agentType: "a2a",
+            surfacesJson: JSON.stringify(surfaces),
+        };
+    }
+    /**
+     * Build the heartbeat `a2a_surfaces[]` array (spec §2.1).
+     *
+     * Required fields (`path`, `skill_id`) are always emitted. `name` is
+     * always emitted because mount-time defaults `skillName` to `skillId`
+     * (see mount.ts), so it is never empty at this point. The remaining
+     * optional fields (`description`, `tags`) are emitted ONLY when set —
+     * never as empty strings or empty arrays — so the registry's OpenAPI
+     * defaults (`input_modes: ["application/json"]`, etc.) aren't overridden
+     * with empty values. Spec §2.1 is explicit about this.
+     *
+     * @returns list of plain-object surface entries ready for JSON serialization
+     */
+    buildHeartbeatSurfaces() {
+        const out = [];
+        for (const md of this.surfacesByPath.values()) {
+            const entry = {
+                path: md.path,
+                skill_id: md.skillId,
+            };
+            // skill_name is always present (defaulted to skillId at mount time) —
+            // emit it as `name` so the registry can use it for human-readable
+            // discovery. Mirrors Java's MeshA2ARegistry.buildHeartbeatSurfaces.
+            entry.name = md.skillName;
+            if (md.description && md.description.length > 0) {
+                entry.description = md.description;
+            }
+            if (md.tags.length > 0) {
+                entry.tags = [...md.tags];
+            }
+            // input_modes / output_modes default at card-render time, not at
+            // heartbeat-emit time (spec §2.1). The mount config doesn't expose
+            // them yet — omit so the registry's defaults apply.
+            out.push(entry);
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/a2a/producer/registry.js.map

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

package/dist/a2a/producer/sse-emitter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Express SSE adapter for the framework-agnostic
+ * {@link SseStreamPlan} produced by {@link buildSendSubscribeStream} /
+ * {@link buildResubscribeStream} (spec §4.6 / §4.7 / §5).
+ *
+ * The dispatcher returns a stream-plan value object describing one of
+ * four SSE shapes. This adapter materialises that plan as `data: <json>\n\n`
+ * frames on an Express {@link Response} plus `: keepalive\n\n` comment
+ * lines every {@link KEEPALIVE_MILLIS} milliseconds of inactivity.
+ *
+ * ## Why a separate file?
+ *
+ * Keeping the dispatcher framework-agnostic makes it unit-testable
+ * without an HTTP server. This adapter contains the only dependency on
+ * Express's `Response` streaming API. Mirrors Java's
+ * `MeshA2ASseDispatcher` → `MeshA2ADispatcher` split.
+ *
+ * ## Client-disconnect handling
+ *
+ * Per spec §7.3 / §5.4: a client-side SSE disconnect MUST NOT cancel the
+ * underlying job — the client may rejoin via `tasks/resubscribe`. We
+ * detect disconnect via:
+ *   1. `res.writableEnded` / `res.destroyed` (Node http.ServerResponse).
+ *   2. `res.write(...)` returning `false` on an already-closed socket.
+ *   3. `req.on("close", ...)` firing while the poll loop is sleeping.
+ * In all three cases we exit the loop cleanly without calling
+ * `JobProxy.cancel()` — the job continues running and the task store is
+ * preserved.
+ *
+ * ## BLOCKER-fix invariants (Java #934 carry-over)
+ *
+ * 1. Transient `proxy.status()` failures during the poll loop emit a
+ *    `state=working` (NOT terminal `state=failed`) frame and continue
+ *    polling. Spec §4.4 conformance: transient unreachability is NOT
+ *    authoritative evidence the job is dead.
+ *
+ * 2. After {@link MAX_CONSECUTIVE_STATUS_FAILURES} consecutive status()
+ *    exceptions the adapter closes the SSE stream WITHOUT marking the
+ *    task store record terminal — subsequent `tasks/get` resumes
+ *    polling normally.
+ *
+ * 3. The {@link MAX_STREAM_MILLIS} cap emits a `state=working, final=false`
+ *    frame (NOT `final=true`) so the client knows to reconnect via
+ *    `tasks/resubscribe` — the task is still running, only the SSE
+ *    transport is closed.
+ */
+import type { Request, RequestHandler, Response } from "express";
+import { A2ATaskStore } from "./task-store.js";
+import { type DispatcherDeps, type SseStreamPlan } from "./dispatcher.js";
+/** Poll cadence for the long-running stream (spec §4.6 sequence diagram: 1s). */
+export declare const POLL_INTERVAL_MILLIS = 1000;
+/** Keepalive interval — SSE comment frame after this much inactivity (spec §5.1: 15s). */
+export declare const KEEPALIVE_MILLIS = 15000;
+/** Maximum total stream duration as a defensive cap (1 hour, matches Java). */
+export declare const MAX_STREAM_MILLIS: number;
+/**
+ * Consecutive `proxy.status()` failures to tolerate during the SSE poll
+ * loop before giving up. Spec §4.4: transient unreachability is NOT
+ * authoritative evidence the job is dead, so we keep emitting
+ * `state=working` status frames and continue polling until this cap.
+ * Once reached we close the SSE stream WITHOUT marking the task store
+ * record terminal — subsequent `tasks/get` resumes polling normally.
+ *
+ * Matches Java's `MAX_CONSECUTIVE_STATUS_FAILURES`.
+ */
+export declare const MAX_CONSECUTIVE_STATUS_FAILURES = 5;
+/**
+ * Build the SSE dispatcher middleware. Mounted in front of the JSON-RPC
+ * dispatcher: when the request body's `method` is `tasks/sendSubscribe`
+ * or `tasks/resubscribe`, this middleware consumes the request and
+ * streams an SSE response. Otherwise it calls `next()` and execution
+ * falls through to the JSON-RPC dispatcher.
+ *
+ * The middleware peeks at the parsed body (`req.body.method`) rather
+ * than `Accept` header — even when the client sends both, we want to
+ * route by JSON-RPC method to keep the dispatch deterministic.
+ */
+export declare function buildSseDispatcherMiddleware(deps: DispatcherDeps): RequestHandler;
+/**
+ * Materialise an SSE stream-plan as an Express response. Exposed for
+ * advanced wiring / tests; the public mount API calls this via the
+ * middleware above.
+ */
+export declare function renderSsePlan(req: Request, res: Response, plan: SseStreamPlan, taskStore: A2ATaskStore): Promise<void>;
+//# sourceMappingURL=sse-emitter.d.ts.map

package/dist/a2a/producer/sse-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-emitter.d.ts","sourceRoot":"","sources":["../../../src/a2a/producer/sse-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGjE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,aAAa,EAEnB,MAAM,iBAAiB,CAAC;AAWzB,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,QAAS,CAAC;AACvC,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAC7C;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CA4CjF;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,YAAY,GACtB,OAAO,CAAC,IAAI,CAAC,CAwCf"}