@mcpmesh/sdk 1.3.4 → 2.0.0-beta.1

package/dist/__tests__/resolver-meshjob.spec.js

@@ -0,0 +1,201 @@
+/**
+ * DDDI resolver tests for the `MeshJob` injectable (Phase 1).
+ *
+ * These tests are the TypeScript instance of the cross-runtime test
+ * seam specified in `MESHJOB_DDDI_CONTRACT.md` → "Equivalence across
+ * SDKs". The same scenarios MUST be covered by the Python and Java
+ * SDKs in their corresponding files
+ * (`tests/test_resolver_meshjob.py` and `MeshJobResolverTest.java`).
+ *
+ * If any behaviour here changes, update the contract first, then
+ * mirror across both other SDK test files. Each numbered scenario maps
+ * to the checklist in the contract document.
+ *
+ * # TS-shape note
+ *
+ * Python's resolver classifies parameters by reflection on
+ * `inspect.signature` + `typing.get_type_hints`. TypeScript erases
+ * types at runtime, so the TS resolver's input is the explicit
+ * `addTool({ dependencies, meshJobParamIndex })` declaration. The
+ * scenarios below translate the contract's signature-shape examples
+ * into the equivalent declarative form, then assert the same
+ * `meshToolDeps[*].signaturePosition` and `meshJobParamIndex` outputs
+ * the contract requires.
+ */
+import { describe, it, expect } from "vitest";
+import { resolveMeshJobSignature, ResolverError, } from "../resolver-meshjob.js";
+// ===========================================================================
+// Contract scenarios 1-5 (must mirror across all three SDK test seams)
+// ===========================================================================
+describe("Resolver contract scenarios", () => {
+    it("scenario 1: MeshTool only — unchanged behaviour", () => {
+        // Python equivalent: fn(name, dep_a: McpMeshTool, dep_b: McpMeshTool)
+        // → mesh_tool_positions == [1, 2], no MeshJob.
+        //
+        // TS declarative form: dependencies ["dep_a", "dep_b"], no
+        // meshJobParamIndex. `args` lives at signature position 0; deps
+        // start at position 1.
+        const result = resolveMeshJobSignature({
+            dependencies: ["dep_a", "dep_b"],
+        });
+        expect(result.meshToolDeps).toEqual([
+            { depIndex: 0, signaturePosition: 1 },
+            { depIndex: 1, signaturePosition: 2 },
+        ]);
+        expect(result.meshJobParamIndex).toBeUndefined();
+    });
+    it("scenario 2: MeshJob only — no tools, MeshJob index recorded", () => {
+        // Python: fn(user_id, job: MeshJob) → mesh_tool_positions == [],
+        // mesh_job_param_index == 1.
+        const result = resolveMeshJobSignature({
+            dependencies: [],
+            meshJobParamIndex: 1,
+        });
+        expect(result.meshToolDeps).toEqual([]);
+        expect(result.meshJobParamIndex).toBe(1);
+    });
+    it("scenario 3: both, MeshJob in middle — MeshTool positions skip MeshJob", () => {
+        // Python: plan_trip(
+        //   user_id: str,                      # pos 0
+        //   weather_lookup: McpMeshTool,       # pos 1 — MeshTool[0]
+        //   job: MeshJob,                      # pos 2 — orthogonal
+        //   flight_search: McpMeshTool,        # pos 3 — MeshTool[1]
+        // )
+        // → mesh_tool_positions == [1, 3] (NOT [1, 2]); the resolver MUST
+        // NOT renumber tool slots when MeshJob is interleaved.
+        const result = resolveMeshJobSignature({
+            dependencies: ["weather_lookup", "flight_search"],
+            meshJobParamIndex: 2,
+        });
+        expect(result.meshToolDeps).toEqual([
+            { depIndex: 0, signaturePosition: 1 },
+            { depIndex: 1, signaturePosition: 3 }, // 3, not 2 — MeshJob skipped
+        ]);
+        expect(result.meshJobParamIndex).toBe(2);
+    });
+    it("scenario 4: neither — no DDDI metadata", () => {
+        // Python: fn(a, b) → empty resolution.
+        const result = resolveMeshJobSignature({ dependencies: [] });
+        expect(result.meshToolDeps).toEqual([]);
+        expect(result.meshJobParamIndex).toBeUndefined();
+    });
+    it("scenario 5: MeshJob trailing — index = last signature position", () => {
+        // Python: fn(a, b, tool: McpMeshTool, job: MeshJob)
+        // → mesh_tool_positions == [2], mesh_job_param_index == 3.
+        //
+        // TS form: one dep, MeshJob at the end. Note: in TS the user-arg
+        // shape is a single `args` object, so positions a/b are inside
+        // args (signature pos 0). The MeshTool dep takes pos 1 and the
+        // MeshJob takes pos 2 (the last slot).
+        const result = resolveMeshJobSignature({
+            dependencies: ["tool"],
+            meshJobParamIndex: 2,
+        });
+        expect(result.meshToolDeps).toEqual([
+            { depIndex: 0, signaturePosition: 1 },
+        ]);
+        expect(result.meshJobParamIndex).toBe(2);
+    });
+});
+// ===========================================================================
+// Contract edge cases — "Edge cases (REQUIRED)" in MESHJOB_DDDI_CONTRACT.md
+// ===========================================================================
+describe("Resolver edge cases", () => {
+    it("multiple MeshJob params raises ResolverError with the contract wording", () => {
+        // Phase 1: a tool function may declare at most one MeshJob param.
+        // The resolver MUST reject with the exact wording the contract
+        // specifies so the developer sees the misuse at registration time.
+        expect(() => resolveMeshJobSignature({
+            dependencies: [],
+            meshJobParamIndex: 1,
+            meshJobParamNames: ["firstJob", "secondJob"],
+        })).toThrow(ResolverError);
+        try {
+            resolveMeshJobSignature({
+                dependencies: [],
+                meshJobParamIndex: 1,
+                meshJobParamNames: ["firstJob", "secondJob"],
+            });
+        }
+        catch (err) {
+            const msg = err.message.toLowerCase();
+            // Contract wording: "a tool function may declare at most one MeshJob parameter"
+            expect(msg).toContain("at most one");
+            expect(msg).toContain("meshjob");
+            // Both offending names should appear so the developer can fix it.
+            expect(msg).toContain("firstjob");
+            expect(msg).toContain("secondjob");
+        }
+    });
+    it("MeshJob first position — orthogonal at any signature index", () => {
+        // Per contract: "MeshJob mixed with MeshTool at any position —
+        // permitted". The resolver MUST NOT enforce a trailing-position
+        // rule.
+        const result = resolveMeshJobSignature({
+            dependencies: ["dep_a"],
+            meshJobParamIndex: 1, // MeshJob at sig pos 1, dep slides to pos 2
+        });
+        expect(result.meshToolDeps).toEqual([
+            { depIndex: 0, signaturePosition: 2 },
+        ]);
+        expect(result.meshJobParamIndex).toBe(1);
+    });
+    it("explicit meshToolPositions — collision with MeshJob throws", () => {
+        // Defensive: if the caller supplies both meshToolPositions and
+        // meshJobParamIndex and they overlap, that's a contract violation
+        // — fail loudly rather than silently overwrite.
+        expect(() => resolveMeshJobSignature({
+            dependencies: ["x"],
+            meshToolPositions: [2],
+            meshJobParamIndex: 2,
+        })).toThrow(ResolverError);
+    });
+    it("explicit meshToolPositions — length mismatch throws", () => {
+        expect(() => resolveMeshJobSignature({
+            dependencies: ["a", "b"],
+            meshToolPositions: [1], // length 1 vs deps length 2
+        })).toThrow(ResolverError);
+    });
+});
+// ===========================================================================
+// Surface tests — the public exports + JS-side contextvar (job-context.ts)
+// ===========================================================================
+describe("MeshJob public surface", () => {
+    it("MeshJob type marker is importable from the package types module", async () => {
+        // Smoke test the export so a typo doesn't silently break the
+        // public API. We dynamic-import to assert it parses; the
+        // type-only import at the top of this file would be erased by
+        // tsc and not fail at runtime if the export disappeared.
+        const types = await import("../types.js");
+        // MeshJob is an interface (erased at runtime) — verify it's at
+        // least a key on the module type so consumers can `import type`
+        // it. The runtime presence we care about is the resolver +
+        // job-context, exercised by the other suites.
+        expect(types).toBeDefined();
+    });
+    it("currentJob() returns null outside any active job scope", async () => {
+        const { currentJob, remainingSeconds } = await import("../job-context.js");
+        expect(currentJob()).toBeNull();
+        expect(remainingSeconds()).toBeNull();
+    });
+    it("withJobAsync sets CURRENT_JOB visible to currentJob() inside the scope", async () => {
+        const { currentJob, remainingSeconds, withJobAsync } = await import("../job-context.js");
+        const inside = await withJobAsync({ jobId: "job-set", deadlineSecsRemaining: 12.5 }, async () => {
+            const cur = currentJob();
+            expect(cur).not.toBeNull();
+            expect(cur?.jobId).toBe("job-set");
+            expect(remainingSeconds()).toBe(12.5);
+            return "done";
+        });
+        expect(inside).toBe("done");
+        // Outside the scope: gone again.
+        expect(currentJob()).toBeNull();
+    });
+    it("snapshot with no deadline returns null remainingSeconds", async () => {
+        const { remainingSeconds, withJobAsync } = await import("../job-context.js");
+        await withJobAsync({ jobId: "job-no-deadline", deadlineSecsRemaining: null }, async () => {
+            expect(remainingSeconds()).toBeNull();
+        });
+    });
+});
+//# sourceMappingURL=resolver-meshjob.spec.js.map

package/dist/__tests__/resolver-meshjob.spec.js.map

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

package/dist/__tests__/schema-verdict-policy.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Issue #547 Phase 4: unit tests for the schema verdict policy helpers in
+ * `schema-normalize.ts`.
+ */
+export {};
+//# sourceMappingURL=schema-verdict-policy.test.d.ts.map

package/dist/__tests__/schema-verdict-policy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-verdict-policy.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/schema-verdict-policy.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/__tests__/schema-verdict-policy.test.js

@@ -0,0 +1,126 @@
+/**
+ * Issue #547 Phase 4: unit tests for the schema verdict policy helpers in
+ * `schema-normalize.ts`.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+// Mock @mcpmesh/core so we don't load the napi binding for these unit tests.
+vi.mock("@mcpmesh/core", () => ({
+    normalizeSchema: vi.fn(),
+}));
+import * as core from "@mcpmesh/core";
+import { clusterStrictEnabled, normalizeSchemaWithPolicy, shouldRefuseStartup, } from "../schema-normalize.js";
+describe("shouldRefuseStartup", () => {
+    it("OK never refuses regardless of flags", () => {
+        expect(shouldRefuseStartup("OK", false, true)).toBe(false);
+        expect(shouldRefuseStartup("OK", true, true)).toBe(false);
+        expect(shouldRefuseStartup("OK", true, false)).toBe(false);
+    });
+    it("BLOCK with default tool_strict refuses", () => {
+        expect(shouldRefuseStartup("BLOCK", false, true)).toBe(true);
+    });
+    it("BLOCK with per-tool override does not refuse", () => {
+        expect(shouldRefuseStartup("BLOCK", false, false)).toBe(false);
+    });
+    it("WARN with defaults does not refuse", () => {
+        expect(shouldRefuseStartup("WARN", false, true)).toBe(false);
+    });
+    it("WARN with cluster strict refuses", () => {
+        expect(shouldRefuseStartup("WARN", true, true)).toBe(true);
+    });
+    it("per-tool override wins over cluster strict", () => {
+        expect(shouldRefuseStartup("BLOCK", true, false)).toBe(false);
+        expect(shouldRefuseStartup("WARN", true, false)).toBe(false);
+    });
+});
+describe("clusterStrictEnabled", () => {
+    const originalEnv = process.env.MCP_MESH_SCHEMA_STRICT;
+    afterEach(() => {
+        if (originalEnv === undefined) {
+            delete process.env.MCP_MESH_SCHEMA_STRICT;
+        }
+        else {
+            process.env.MCP_MESH_SCHEMA_STRICT = originalEnv;
+        }
+    });
+    it.each(["1", "true", "TRUE", "True", "yes", "YES"])("truthy value %s -> true", (v) => {
+        process.env.MCP_MESH_SCHEMA_STRICT = v;
+        expect(clusterStrictEnabled()).toBe(true);
+    });
+    it.each(["", "0", "false", "no", "off", "anything-else"])("falsy value %s -> false", (v) => {
+        process.env.MCP_MESH_SCHEMA_STRICT = v;
+        expect(clusterStrictEnabled()).toBe(false);
+    });
+    it("unset -> false", () => {
+        delete process.env.MCP_MESH_SCHEMA_STRICT;
+        expect(clusterStrictEnabled()).toBe(false);
+    });
+});
+describe("normalizeSchemaWithPolicy", () => {
+    const mockNormalize = core.normalizeSchema;
+    let warnSpy;
+    beforeEach(() => {
+        mockNormalize.mockReset();
+        warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    });
+    afterEach(() => {
+        warnSpy.mockRestore();
+    });
+    it("OK passes through with canonical+hash", () => {
+        mockNormalize.mockReturnValue(JSON.stringify({
+            canonical: { type: "string" },
+            hash: "sha256:deadbeef",
+            verdict: "OK",
+            warnings: [],
+        }));
+        const r = normalizeSchemaWithPolicy({}, "ctx", false, true);
+        expect(r.verdict).toBe("OK");
+        expect(r.canonicalJson).toBe('{"type":"string"}');
+        expect(r.hash).toBe("sha256:deadbeef");
+        expect(r.warnings).toEqual([]);
+    });
+    it("BLOCK with toolStrict=true throws", () => {
+        mockNormalize.mockReturnValue(JSON.stringify({ verdict: "BLOCK", warnings: ["unsupported keyword"] }));
+        expect(() => normalizeSchemaWithPolicy({}, "ctx", false, true)).toThrow(/BLOCK for ctx.*unsupported keyword.*Cannot start agent/);
+    });
+    it("BLOCK with toolStrict=false does not throw, tags warnings", () => {
+        mockNormalize.mockReturnValue(JSON.stringify({
+            canonical: { type: "string" },
+            hash: "sha256:abc",
+            verdict: "BLOCK",
+            warnings: ["something bad"],
+        }));
+        const r = normalizeSchemaWithPolicy({}, "ctx", false, false);
+        expect(r.verdict).toBe("BLOCK");
+        expect(r.warnings).toEqual(["[demoted from BLOCK] something bad"]);
+        expect(r.canonicalJson).toBe('{"type":"string"}');
+        expect(warnSpy).toHaveBeenCalled();
+    });
+    it("WARN with cluster strict + tool strict throws (promoted)", () => {
+        mockNormalize.mockReturnValue(JSON.stringify({ verdict: "WARN", warnings: ["soft issue"] }));
+        expect(() => normalizeSchemaWithPolicy({}, "ctx", true, true)).toThrow(/WARN for ctx \(MCP_MESH_SCHEMA_STRICT=true upgraded WARN.*soft issue/);
+    });
+    it("WARN with cluster strict + tool override does not throw", () => {
+        mockNormalize.mockReturnValue(JSON.stringify({
+            canonical: { type: "string" },
+            hash: "sha256:abc",
+            verdict: "WARN",
+            warnings: ["soft issue"],
+        }));
+        const r = normalizeSchemaWithPolicy({}, "ctx", true, false);
+        expect(r.verdict).toBe("WARN");
+        expect(r.warnings).toEqual(["soft issue"]);
+    });
+    it("WARN without cluster strict logs and continues", () => {
+        mockNormalize.mockReturnValue(JSON.stringify({
+            canonical: { type: "string" },
+            hash: "sha256:abc",
+            verdict: "WARN",
+            warnings: ["soft issue"],
+        }));
+        const r = normalizeSchemaWithPolicy({}, "ctx", false, true);
+        expect(r.verdict).toBe("WARN");
+        expect(r.warnings).toEqual(["soft issue"]);
+        expect(warnSpy).toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=schema-verdict-policy.test.js.map

package/dist/__tests__/schema-verdict-policy.test.js.map

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

package/dist/__tests__/sse-stream.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unit tests for sse-stream.ts (mesh.sseStream).
+ *
+ * Verifies the SSE wire format mirrors the Python ``mesh.route`` adapter:
+ * - ``data: <chunk>\n\n`` per item
+ * - ``data: [DONE]\n\n`` terminator on normal completion
+ * - ``event: error\ndata: <json>\n\n`` on per-chunk error
+ * - Standard headers (Content-Type, Cache-Control, Connection, X-Accel-Buffering)
+ * - Idempotent end()
+ */
+export {};
+//# sourceMappingURL=sse-stream.test.d.ts.map

package/dist/__tests__/sse-stream.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/sse-stream.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/__tests__/sse-stream.test.js

@@ -0,0 +1,170 @@
+/**
+ * Unit tests for sse-stream.ts (mesh.sseStream).
+ *
+ * Verifies the SSE wire format mirrors the Python ``mesh.route`` adapter:
+ * - ``data: <chunk>\n\n`` per item
+ * - ``data: [DONE]\n\n`` terminator on normal completion
+ * - ``event: error\ndata: <json>\n\n`` on per-chunk error
+ * - Standard headers (Content-Type, Cache-Control, Connection, X-Accel-Buffering)
+ * - Idempotent end()
+ */
+import { describe, it, expect, vi } from "vitest";
+import { sseStream } from "../sse-stream.js";
+function makeFakeRes() {
+    const res = {
+        headersSent: false,
+        writableEnded: false,
+        destroyed: false,
+        setHeader: vi.fn(),
+        write: vi.fn((data) => {
+            res._written.push(data);
+            return true;
+        }),
+        end: vi.fn(() => {
+            res.writableEnded = true;
+        }),
+        flushHeaders: vi.fn(() => {
+            res.headersSent = true;
+        }),
+        _written: [],
+    };
+    return res;
+}
+async function* asyncIter(items) {
+    for (const item of items) {
+        yield item;
+    }
+}
+describe("sseStream", () => {
+    it("sets the standard SSE headers", async () => {
+        const res = makeFakeRes();
+        await sseStream(res, asyncIter(["a"]));
+        const setHeaderCalls = Object.fromEntries(res.setHeader.mock.calls.map((c) => [c[0], c[1]]));
+        expect(setHeaderCalls["Content-Type"]).toBe("text/event-stream");
+        expect(setHeaderCalls["Cache-Control"]).toBe("no-cache");
+        expect(setHeaderCalls["Connection"]).toBe("keep-alive");
+        expect(setHeaderCalls["X-Accel-Buffering"]).toBe("no");
+        expect(res.flushHeaders).toHaveBeenCalledTimes(1);
+    });
+    it("writes data: <chunk>\\n\\n per item then data: [DONE]\\n\\n and ends once", async () => {
+        const res = makeFakeRes();
+        await sseStream(res, asyncIter(["a", "b", "c"]));
+        expect(res._written).toEqual([
+            "data: a\n\n",
+            "data: b\n\n",
+            "data: c\n\n",
+            "data: [DONE]\n\n",
+        ]);
+        expect(res.end).toHaveBeenCalledTimes(1);
+    });
+    it("does not double-end on already-completed response", async () => {
+        const res = makeFakeRes();
+        await sseStream(res, asyncIter([]));
+        // No items: should still write [DONE] and end exactly once
+        expect(res._written).toEqual(["data: [DONE]\n\n"]);
+        expect(res.end).toHaveBeenCalledTimes(1);
+    });
+    it("emits one data: line per newline in a multi-line chunk", async () => {
+        const res = makeFakeRes();
+        await sseStream(res, asyncIter(["line1\nline2\nline3"]));
+        // Per SSE spec, multi-line data is multiple data: prefixes inside one event
+        expect(res._written[0]).toBe("data: line1\ndata: line2\ndata: line3\n\n");
+        expect(res._written[1]).toBe("data: [DONE]\n\n");
+        expect(res.end).toHaveBeenCalledTimes(1);
+    });
+    it("emits a heartbeat-style empty data line for empty chunks", async () => {
+        const res = makeFakeRes();
+        await sseStream(res, asyncIter([""]));
+        expect(res._written[0]).toBe("data: \n\n");
+        expect(res._written[1]).toBe("data: [DONE]\n\n");
+    });
+    it("writes event: error on iterator throw and ends without sending [DONE]", async () => {
+        const res = makeFakeRes();
+        async function* throwing() {
+            yield "first";
+            throw new Error("upstream blew up");
+        }
+        await sseStream(res, throwing());
+        expect(res._written[0]).toBe("data: first\n\n");
+        // Last frame is the error; [DONE] should NOT have been sent
+        expect(res._written.at(-1)).toMatch(/^event: error\ndata: /);
+        const errFrame = res._written.at(-1);
+        const payloadJson = errFrame.replace(/^event: error\ndata: /, "").replace(/\n\n$/, "");
+        const payload = JSON.parse(payloadJson);
+        expect(payload.error).toBe("upstream blew up");
+        expect(payload.type).toBe("Error");
+        // No [DONE] anywhere
+        expect(res._written.some((s) => s === "data: [DONE]\n\n")).toBe(false);
+        expect(res.end).toHaveBeenCalledTimes(1);
+    });
+    it("writes event: error and stops on non-string chunks (TypeError)", async () => {
+        const res = makeFakeRes();
+        // Iterator yields a non-string — should be rejected with a structured error
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async function* bad() {
+            yield "ok";
+            yield 42;
+            yield "never-reached";
+        }
+        await sseStream(res, bad());
+        expect(res._written[0]).toBe("data: ok\n\n");
+        expect(res._written[1]).toMatch(/^event: error\ndata: /);
+        const payloadJson = res._written[1].replace(/^event: error\ndata: /, "").replace(/\n\n$/, "");
+        const payload = JSON.parse(payloadJson);
+        expect(payload.type).toBe("TypeError");
+        expect(payload.error).toMatch(/expected string chunk/);
+        expect(res.end).toHaveBeenCalledTimes(1);
+    });
+    it("stops iterating and calls return() on consumer disconnect (write returns false)", async () => {
+        const res = makeFakeRes();
+        let returnCalled = false;
+        let yielded = 0;
+        const iter = {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        yielded += 1;
+                        if (yielded > 5)
+                            return { value: undefined, done: true };
+                        return { value: `chunk${yielded}`, done: false };
+                    },
+                    async return() {
+                        returnCalled = true;
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+        // After first write, simulate disconnect
+        res.write = vi.fn(() => {
+            res._written.push("first-write");
+            res.writableEnded = true; // Simulate consumer disconnect
+            return false;
+        });
+        await sseStream(res, iter);
+        expect(returnCalled).toBe(true);
+        // Only one chunk was attempted, then disconnect detected
+        expect(yielded).toBe(1);
+        // [DONE] was NOT written
+        expect(res._written).not.toContain("data: [DONE]\n\n");
+    });
+    it("does not set headers if headersSent is already true", async () => {
+        const res = makeFakeRes();
+        res.headersSent = true;
+        await sseStream(res, asyncIter(["a"]));
+        expect(res.setHeader).not.toHaveBeenCalled();
+        expect(res.flushHeaders).not.toHaveBeenCalled();
+        // Still writes data + [DONE]
+        expect(res._written).toEqual(["data: a\n\n", "data: [DONE]\n\n"]);
+    });
+    it("handles synchronous res.write throwing without crashing", async () => {
+        const res = makeFakeRes();
+        res.write = vi.fn(() => {
+            throw new Error("socket closed");
+        });
+        // Should not throw out of sseStream — it swallows write errors and ends
+        await expect(sseStream(res, asyncIter(["a", "b"]))).resolves.toBeUndefined();
+        expect(res.end).toHaveBeenCalledTimes(1);
+    });
+});
+//# sourceMappingURL=sse-stream.test.js.map

package/dist/__tests__/sse-stream.test.js.map

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

package/dist/a2a/a2a-bearer.d.ts

@@ -0,0 +1,27 @@
+export interface A2ABearerConfig {
+    /** Literal bearer token. Mutually exclusive with `tokenEnv`. */
+    token?: string;
+    /** Env-var name to read the token from on each call. Mutually exclusive with `token`. */
+    tokenEnv?: string;
+}
+export declare class A2ABearer {
+    private readonly token?;
+    private readonly tokenEnv?;
+    constructor(config: A2ABearerConfig);
+    /**
+     * Build the value for the `Authorization` header at call time.
+     *
+     * Reads the env var (when configured) on every call so a rotated
+     * credential is honoured mid-process.
+     */
+    authorizationHeader(): string;
+}
+/**
+ * Helper: normalise the user-friendly union (`A2ABearer | A2ABearerConfig`)
+ * into a concrete `A2ABearer` instance, or `undefined` for "no auth".
+ *
+ * Lets the consumer-side `addTool({ a2aConfig: { auth: { tokenEnv: "X" } } })`
+ * shortcut work without forcing the user to `new A2ABearer(...)` every time.
+ */
+export declare function resolveBearer(auth: A2ABearer | A2ABearerConfig | undefined): A2ABearer | undefined;
+//# sourceMappingURL=a2a-bearer.d.ts.map

package/dist/a2a/a2a-bearer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-bearer.d.ts","sourceRoot":"","sources":["../../src/a2a/a2a-bearer.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;gBAEvB,MAAM,EAAE,eAAe;IAqBnC;;;;;OAKG;IACH,mBAAmB,IAAI,MAAM;CAa9B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAC5C,SAAS,GAAG,SAAS,CAIvB"}