@mcpmesh/sdk 1.4.1 → 2.0.0-beta.1

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"}

package/dist/a2a/a2a-bearer.js

@@ -0,0 +1,63 @@
+/**
+ * Bearer-token credential for an outbound A2A call (issue #917).
+ *
+ * Provide either `token` (literal) or `tokenEnv` (the name of an
+ * environment variable). Resolution happens at header-build time so
+ * rotating the env var between calls picks up the new value without
+ * reconstructing the surrounding A2AClient. Mirrors
+ * `mesh._a2a_consumer.A2ABearer` (Python) and `io.mcpmesh.a2a.A2ABearer`
+ * (Java).
+ */
+import { A2AAuthError } from "./errors.js";
+export class A2ABearer {
+    token;
+    tokenEnv;
+    constructor(config) {
+        if (!config.token && !config.tokenEnv) {
+            throw new A2AAuthError("A2ABearer: must specify either 'token' or 'tokenEnv'");
+        }
+        if (config.token && config.tokenEnv) {
+            throw new A2AAuthError("A2ABearer: 'token' and 'tokenEnv' are mutually exclusive");
+        }
+        if (config.token !== undefined && config.token.trim() === "") {
+            throw new A2AAuthError("A2ABearer: 'token' must be non-blank");
+        }
+        if (config.tokenEnv !== undefined && config.tokenEnv.trim() === "") {
+            throw new A2AAuthError("A2ABearer: 'tokenEnv' must be non-blank");
+        }
+        this.token = config.token;
+        this.tokenEnv = config.tokenEnv;
+    }
+    /**
+     * 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() {
+        let resolved = this.token;
+        if (resolved === undefined && this.tokenEnv) {
+            resolved = process.env[this.tokenEnv];
+        }
+        if (!resolved || resolved.trim() === "") {
+            throw new A2AAuthError(`A2ABearer: no token resolved (token=${this.token ? "set" : "unset"}, ` +
+                `tokenEnv=${this.tokenEnv ?? "<unset>"})`);
+        }
+        return `Bearer ${resolved}`;
+    }
+}
+/**
+ * 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 function resolveBearer(auth) {
+    if (auth === undefined)
+        return undefined;
+    if (auth instanceof A2ABearer)
+        return auth;
+    return new A2ABearer(auth);
+}
+//# sourceMappingURL=a2a-bearer.js.map

package/dist/a2a/a2a-bearer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-bearer.js","sourceRoot":"","sources":["../../src/a2a/a2a-bearer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,MAAM,OAAO,SAAS;IACH,KAAK,CAAU;IACf,QAAQ,CAAU;IAEnC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,YAAY,CACpB,sDAAsD,CACvD,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpC,MAAM,IAAI,YAAY,CACpB,0DAA0D,CAC3D,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAC7D,MAAM,IAAI,YAAY,CAAC,sCAAsC,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACnE,MAAM,IAAI,YAAY,CAAC,yCAAyC,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAClC,CAAC;IAED;;;;;OAKG;IACH,mBAAmB;QACjB,IAAI,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC;QAC1B,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5C,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,YAAY,CACpB,uCAAuC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,IAAI;gBACrE,YAAY,IAAI,CAAC,QAAQ,IAAI,SAAS,GAAG,CAC5C,CAAC;QACJ,CAAC;QACD,OAAO,UAAU,QAAQ,EAAE,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,IAA6C;IAE7C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,IAAI,YAAY,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

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

@@ -0,0 +1,114 @@
+import { A2ABearer, type A2ABearerConfig } from "./a2a-bearer.js";
+import { A2AJob } from "./a2a-job.js";
+import { A2AStream } from "./a2a-stream.js";
+/** Default per-call deadline for `send`. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** Initial poll interval for `tasks/get` (ms). */
+export declare const DEFAULT_POLL_INTERVAL_MS = 500;
+/** Capped poll interval for `tasks/get` (ms). */
+export declare const DEFAULT_POLL_INTERVAL_MAX_MS = 2000;
+/** Multiplier applied between consecutive polls. */
+export declare const POLL_BACKOFF_FACTOR = 1.5;
+export declare function isTerminalState(state: string | undefined | null): boolean;
+/** A2A v1.0 message dict — `{ role, parts: [...] }` shape. */
+export type A2AMessage = Record<string, unknown>;
+export interface A2AClientConfig {
+    /** A2A endpoint URL. Trailing slashes are stripped. */
+    url: string;
+    /** Skill ID to invoke on the upstream. */
+    skillId: string;
+    /** Bearer credential (instance or config). */
+    auth?: A2ABearer | A2ABearerConfig;
+    /** Per-call deadline for `send` (ms). Default 30_000. */
+    timeoutMs?: number;
+    /** Initial backoff between `tasks/get` polls (ms). Default 500. */
+    pollIntervalMs?: number;
+    /** Cap on the backoff between polls (ms). Default 2_000. */
+    pollIntervalMaxMs?: number;
+}
+/** Result of a synchronous `A2AClient.send`. */
+export interface A2AResponse {
+    /** First artifact's first text part — the canonical sync return. */
+    artifactText: string;
+    /** Final lifecycle state (typically "completed"). */
+    state: string;
+    /** Consumer-generated task ID echoed back by the producer. */
+    taskId: string;
+    /** Full Task envelope (status, artifacts, metadata, history). */
+    rawTask: Record<string, unknown>;
+}
+/** Raw task envelope returned by `A2AJob.status` etc. */
+export type A2ATaskEnvelope = Record<string, unknown>;
+export declare class A2AClient {
+    readonly url: string;
+    readonly skillId: string;
+    readonly auth?: A2ABearer;
+    readonly timeoutMs: number;
+    readonly pollIntervalMs: number;
+    readonly pollIntervalMaxMs: number;
+    private closed;
+    private nextRpcId;
+    constructor(config: A2AClientConfig);
+    /**
+     * POST `tasks/send` and poll `tasks/get` until terminal.
+     *
+     * `message` is the A2A v1.0 request message dict — typically
+     * `{ role: "user", parts: [{ type: "text", text: "..." }] }`.
+     * Returns an `A2AResponse` whose `artifactText` carries the
+     * producer-side handler's return value (JSON-stringified for
+     * non-string returns; consumers `JSON.parse` when the upstream
+     * returns a dict).
+     */
+    send(message: A2AMessage, options?: {
+        taskId?: string;
+        timeoutMs?: number;
+    }): Promise<A2AResponse>;
+    /**
+     * POST `tasks/send` and return an `A2AJob` handle WITHOUT polling.
+     *
+     * Use this when the surrounding `addTool({ task: true, ... })` body
+     * wants explicit control over when to poll — typically via
+     * `A2AJob.bridge(jobController)` which mirrors progress into the
+     * framework-injected `JobController`.
+     */
+    submit(message: A2AMessage, options?: {
+        taskId?: string;
+    }): Promise<A2AJob>;
+    /**
+     * POST `tasks/sendSubscribe` and return an `A2AStream` of parsed events.
+     *
+     * The returned stream MUST be either iterated to completion (the
+     * terminal `final=true` frame closes it) OR explicitly closed via
+     * `await using` / `await stream.aclose()` to release the underlying
+     * connection.
+     */
+    subscribe(message: A2AMessage, options?: {
+        taskId?: string;
+    }): Promise<A2AStream>;
+    /**
+     * Lifecycle marker (forward-compat).
+     *
+     * The undici Agent pool is shared process-wide via `closeHttpPool()`
+     * — there's no per-client connection state to tear down. We mark
+     * `closed = true` so subsequent `send`/`submit`/`subscribe` raise
+     * cleanly (matches Python's `_closed` flag behaviour).
+     */
+    close(): Promise<void>;
+    /** Internal: POST `tasks/get` for the supplied task ID. */
+    tasksGet(taskId: string): Promise<A2ATaskEnvelope>;
+    /** Internal: POST `tasks/cancel`. Best-effort; transport errors swallowed by caller. */
+    tasksCancel(taskId: string, reason?: string): Promise<void>;
+    /** Internal: build an `A2AResponse` from a Task envelope. */
+    buildResponse(taskId: string, result: A2ATaskEnvelope): A2AResponse;
+    private _newTaskId;
+    private _ensureOpen;
+    private _postJsonRpc;
+    private _buildResponse;
+}
+export declare function readState(result: A2ATaskEnvelope | undefined | null): string;
+export declare function extractArtifactText(result: A2ATaskEnvelope): string;
+export declare function readStatusMessage(result: A2ATaskEnvelope): string | undefined;
+export declare function readProgress(result: A2ATaskEnvelope): number | undefined;
+export declare function maybeJsonParse(text: string): unknown;
+export declare function isCanceledState(state: string | undefined | null): boolean;
+//# sourceMappingURL=a2a-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-client.d.ts","sourceRoot":"","sources":["../../src/a2a/a2a-client.ts"],"names":[],"mappings":"AAaA,OAAO,EACL,SAAS,EACT,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,iDAAiD;AACjD,eAAO,MAAM,4BAA4B,OAAQ,CAAC;AAClD,oDAAoD;AACpD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAWvC,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAEzE;AAED,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,SAAS,GAAG,eAAe,CAAC;IACnC,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAYtD,qBAAa,SAAS;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,OAAO,CAAC,MAAM,CAAS;IAIvB,OAAO,CAAC,SAAS,CAAK;gBAEV,MAAM,EAAE,eAAe;IAuBnC;;;;;;;;;OASG;IACG,IAAI,CACR,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,OAAO,CAAC,WAAW,CAAC;IAgDvB;;;;;;;OAOG;IACG,MAAM,CACV,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,MAAM,CAAC;IAelB;;;;;;;OAOG;IACG,SAAS,CACb,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,SAAS,CAAC;IAuDrB;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,2DAA2D;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAKxD,wFAAwF;IAClF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjE,6DAA6D;IAC7D,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,WAAW;IAMnE,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,WAAW;YAQL,YAAY;IAsG1B,OAAO,CAAC,cAAc;CAWvB;AAID,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAS5E;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAWnE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAa7E;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAiBxE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAIzE"}