@mcpmesh/sdk 1.3.4 → 2.0.0-beta.1

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

@@ -0,0 +1,58 @@
+/**
+ * Handle to a long-running A2A task — returned by `A2AClient.submit`
+ * (issue #917).
+ *
+ * Provides direct task lifecycle methods (`status`, `wait`, `cancel`)
+ * AND a convenience `bridge(jobController)` that mirrors A2A polling
+ * state into a mesh `JobController` for the typical
+ * `addTool({ task: true, a2aConfig: { ... } })` consumer pattern.
+ *
+ * Mirrors `mesh._a2a_consumer.A2AJob` (Python) and
+ * `io.mcpmesh.a2a.A2AJob` (Java).
+ */
+import { JobController } from "@mcpmesh/core";
+import { A2AClient, type A2AResponse, type A2ATaskEnvelope } from "./a2a-client.js";
+export declare class A2AJob {
+    private readonly client;
+    readonly taskId: string;
+    readonly initialState: string;
+    private readonly initialResult;
+    constructor(client: A2AClient, taskId: string, initialState: string, initialResult: A2ATaskEnvelope);
+    /** POST `tasks/get` once and return the raw `result` envelope. */
+    status(): Promise<A2ATaskEnvelope>;
+    /**
+     * POST `tasks/cancel`. Idempotent — already-terminal tasks should
+     * return cleanly per A2A v1.0; transport-level errors are logged
+     * and swallowed so callers can still raise `A2AJobCanceledError`
+     * or similar.
+     */
+    cancel(reason?: string): Promise<void>;
+    /**
+     * Poll `tasks/get` until terminal; return `A2AResponse` on completed.
+     *
+     * Throws `A2AJobFailedError` on `state=failed`,
+     * `A2AJobCanceledError` on `state=canceled`, `A2ATimeoutError` if
+     * the deadline elapses.
+     */
+    wait(timeoutMs?: number): Promise<A2AResponse>;
+    /**
+     * Mirror A2A polling into the supplied `JobController` until terminal.
+     * Returns the final artifact value: parsed JSON when the artifact
+     * text is valid JSON, otherwise the raw text. Empty artifacts return
+     * an empty string.
+     *
+     * Cancel handling: races each iteration's sleep against
+     * `awaitJobCancel(jobId)` so a mesh-side cancel arriving DURING a
+     * sleep wakes us immediately instead of waiting for the next poll
+     * boundary. On detection POSTs `tasks/cancel` upstream so the
+     * producer stops billing for the work, then throws
+     * `A2AJobCanceledError` so the framework's `task: true` wrapper
+     * records a canceled outcome.
+     */
+    bridge(controller: JobController): Promise<unknown>;
+    private _mirrorProgress;
+    private _propagateCancelUpstream;
+    private _terminalToResponseOrThrow;
+    private _terminalToArtifactOrThrow;
+}
+//# sourceMappingURL=a2a-job.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-job.d.ts","sourceRoot":"","sources":["../../src/a2a/a2a-job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,aAAa,EAAkB,MAAM,eAAe,CAAC;AAC9D,OAAO,EACL,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,eAAe,EASrB,MAAM,iBAAiB,CAAC;AAOzB,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkB;gBAG9C,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,eAAe;IAQhC,kEAAkE;IAC5D,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC;IAIxC;;;;;OAKG;IACG,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5C;;;;;;OAMG;IACG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgCpD;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;YAwF3C,eAAe;YAyCf,wBAAwB;IAWtC,OAAO,CAAC,0BAA0B;IAalC,OAAO,CAAC,0BAA0B;CAcnC"}

package/dist/a2a/a2a-job.js

@@ -0,0 +1,264 @@
+/**
+ * Handle to a long-running A2A task — returned by `A2AClient.submit`
+ * (issue #917).
+ *
+ * Provides direct task lifecycle methods (`status`, `wait`, `cancel`)
+ * AND a convenience `bridge(jobController)` that mirrors A2A polling
+ * state into a mesh `JobController` for the typical
+ * `addTool({ task: true, a2aConfig: { ... } })` consumer pattern.
+ *
+ * Mirrors `mesh._a2a_consumer.A2AJob` (Python) and
+ * `io.mcpmesh.a2a.A2AJob` (Java).
+ */
+import { awaitJobCancel } from "@mcpmesh/core";
+import { POLL_BACKOFF_FACTOR, extractArtifactText, isCanceledState, isTerminalState, maybeJsonParse, readProgress, readState, readStatusMessage, } from "./a2a-client.js";
+import { A2AJobCanceledError, A2AJobFailedError, A2ATimeoutError, } from "./errors.js";
+export class A2AJob {
+    client;
+    taskId;
+    initialState;
+    initialResult;
+    constructor(client, taskId, initialState, initialResult) {
+        this.client = client;
+        this.taskId = taskId;
+        this.initialState = initialState;
+        this.initialResult = initialResult;
+    }
+    /** POST `tasks/get` once and return the raw `result` envelope. */
+    async status() {
+        return this.client.tasksGet(this.taskId);
+    }
+    /**
+     * POST `tasks/cancel`. Idempotent — already-terminal tasks should
+     * return cleanly per A2A v1.0; transport-level errors are logged
+     * and swallowed so callers can still raise `A2AJobCanceledError`
+     * or similar.
+     */
+    async cancel(reason) {
+        try {
+            await this.client.tasksCancel(this.taskId, reason);
+        }
+        catch (err) {
+            // Mirror the Python+Java posture (best-effort): the remote may
+            // have already terminated the task. Log and move on so callers
+            // can still raise A2AJobCanceledError or similar.
+            console.info(`A2A tasks/cancel: remote raised for task ${this.taskId} on ` +
+                `${this.client.url} (may already be terminal): ` +
+                `${err?.message ?? String(err)}`);
+        }
+    }
+    /**
+     * Poll `tasks/get` until terminal; return `A2AResponse` on completed.
+     *
+     * Throws `A2AJobFailedError` on `state=failed`,
+     * `A2AJobCanceledError` on `state=canceled`, `A2ATimeoutError` if
+     * the deadline elapses.
+     */
+    async wait(timeoutMs) {
+        const timeout = timeoutMs ?? this.client.timeoutMs;
+        if (timeout <= 0) {
+            throw new Error("A2AJob.wait: timeoutMs must be > 0");
+        }
+        if (isTerminalState(this.initialState)) {
+            return this._terminalToResponseOrThrow(this.initialResult);
+        }
+        const deadline = Date.now() + timeout;
+        let intervalMs = this.client.pollIntervalMs;
+        while (Date.now() < deadline) {
+            await sleep(Math.min(intervalMs, Math.max(1, deadline - Date.now())));
+            if (Date.now() >= deadline)
+                break;
+            const result = await this.status();
+            const state = readState(result);
+            if (isTerminalState(state)) {
+                return this._terminalToResponseOrThrow(result);
+            }
+            intervalMs = Math.min(this.client.pollIntervalMaxMs, Math.floor(intervalMs * POLL_BACKOFF_FACTOR));
+        }
+        throw new A2ATimeoutError(`A2A task '${this.taskId}' on ${this.client.url} did not reach ` +
+            `terminal state within ${timeout}ms`);
+    }
+    /**
+     * Mirror A2A polling into the supplied `JobController` until terminal.
+     * Returns the final artifact value: parsed JSON when the artifact
+     * text is valid JSON, otherwise the raw text. Empty artifacts return
+     * an empty string.
+     *
+     * Cancel handling: races each iteration's sleep against
+     * `awaitJobCancel(jobId)` so a mesh-side cancel arriving DURING a
+     * sleep wakes us immediately instead of waiting for the next poll
+     * boundary. On detection POSTs `tasks/cancel` upstream so the
+     * producer stops billing for the work, then throws
+     * `A2AJobCanceledError` so the framework's `task: true` wrapper
+     * records a canceled outcome.
+     */
+    async bridge(controller) {
+        if (controller == null) {
+            throw new Error("A2AJob.bridge: controller must be non-null");
+        }
+        const jobId = controller.jobId;
+        const cancelPromise = awaitJobCancel(jobId);
+        const mirrorState = { lastProgress: undefined, lastMessage: undefined };
+        if (this.initialResult) {
+            await this._mirrorProgress(controller, this.initialResult, mirrorState);
+        }
+        if (isTerminalState(this.initialState)) {
+            return this._terminalToArtifactOrThrow(this.initialResult);
+        }
+        let cancelObserved = false;
+        // ONE shared AbortController fans out the cancelPromise resolution
+        // to every per-iteration `raceSleep` listener. Without this the
+        // polling loop would attach a fresh `.then` to cancelPromise on
+        // every iteration — for a 30-min job at sub-second polling that's
+        // hundreds of accumulated handlers on a never-resolving promise,
+        // i.e. linear memory creep. AbortController makes the fan-out O(1).
+        const cancelAbort = new AbortController();
+        cancelPromise
+            .then(() => {
+            cancelObserved = true;
+            cancelAbort.abort();
+        })
+            .catch((err) => {
+            // awaitJobCancel rejects only when the napi binding itself
+            // fails (binding loss mid-job). If we ignored the rejection
+            // the polling loop would never observe a cancel signal and
+            // could poll the A2A backend until the user-supplied deadline.
+            // Treat as a degraded-but-recoverable cancel signal so the
+            // bridge fails fast and propagates `tasks/cancel` upstream.
+            console.warn(`[a2a-job] bridge: awaitJobCancel observer failed for task ` +
+                `${this.taskId} (treating as degraded cancel): ` +
+                `${err?.message ?? String(err)}`);
+            cancelObserved = true;
+            cancelAbort.abort();
+        });
+        let intervalMs = this.client.pollIntervalMs;
+        while (true) {
+            if (cancelObserved) {
+                await this._propagateCancelUpstream("mesh-side cancel");
+                throw new A2AJobCanceledError(`A2A task ${this.taskId} canceled by mesh-side request`);
+            }
+            let result;
+            try {
+                result = await this.status();
+            }
+            catch (err) {
+                // tasks/get itself failed (network error, HTTP 5xx, malformed
+                // envelope, ...). The upstream producer is almost certainly
+                // still running — best-effort POST tasks/cancel so it stops
+                // billing for work whose result we'll never observe.
+                await this._propagateCancelUpstream("consumer poll failed");
+                throw new A2AJobFailedError(`A2A status poll failed for task ${this.taskId}: ` +
+                    `${err?.message ?? String(err)}`, err);
+            }
+            const state = readState(result);
+            await this._mirrorProgress(controller, result, mirrorState);
+            if (isTerminalState(state)) {
+                return this._terminalToArtifactOrThrow(result);
+            }
+            // Race the sleep against the cancel signal — if cancel fires
+            // mid-sleep we wake immediately and propagate on the next loop
+            // iteration without wasting one more `tasks/get` round trip.
+            await raceSleep(intervalMs, cancelAbort.signal);
+            intervalMs = Math.min(this.client.pollIntervalMaxMs, Math.floor(intervalMs * POLL_BACKOFF_FACTOR));
+        }
+    }
+    // --- helpers -------------------------------------------------------------
+    async _mirrorProgress(controller, result, state) {
+        const progress = readProgress(result);
+        const message = readStatusMessage(result);
+        if (progress === undefined && message === undefined) {
+            return;
+        }
+        if (progress === state.lastProgress && message === state.lastMessage) {
+            return;
+        }
+        // Coerce missing progress to last-known or 0.0 — the controller
+        // requires a number, but the consumer surface allows message-only
+        // events. Clamp to [0, 1] — updateProgress expects a normalized
+        // fraction; raw A2A producer progress values are advisory.
+        const rawP = progress !== undefined
+            ? progress
+            : state.lastProgress !== undefined
+                ? state.lastProgress
+                : 0.0;
+        const clamped = Math.min(1.0, Math.max(0.0, rawP));
+        try {
+            await controller.updateProgress(clamped, message ?? null);
+        }
+        catch (err) {
+            // Do NOT advance lastProgress / lastMessage on delivery failure
+            // — leaving them stale ensures the next poll's equality check
+            // sees a delta and retries the update.
+            console.warn(`[a2a-job] bridge: controller.updateProgress failed ` +
+                `(task=${this.taskId}, progress=${progress}, msg=${message}) — ` +
+                `will retry on next poll: ${err?.message ?? String(err)}`);
+            return;
+        }
+        if (progress !== undefined)
+            state.lastProgress = progress;
+        state.lastMessage = message;
+    }
+    async _propagateCancelUpstream(reason) {
+        try {
+            await this.client.tasksCancel(this.taskId, reason);
+        }
+        catch (err) {
+            console.debug(`[a2a-job] bridge: upstream cancel after ${reason} also failed ` +
+                `(task=${this.taskId}): ${err?.message ?? String(err)}`);
+        }
+    }
+    _terminalToResponseOrThrow(result) {
+        const state = readState(result);
+        if (state.toLowerCase() === "completed") {
+            return this.client.buildResponse(this.taskId, result);
+        }
+        const msg = readStatusMessage(result) ?? `A2A task ${this.taskId} state=${state}`;
+        if (isCanceledState(state)) {
+            throw new A2AJobCanceledError(msg);
+        }
+        throw new A2AJobFailedError(msg);
+    }
+    _terminalToArtifactOrThrow(result) {
+        const state = readState(result);
+        if (state.toLowerCase() === "completed") {
+            const text = extractArtifactText(result);
+            if (!text)
+                return text;
+            return maybeJsonParse(text);
+        }
+        const msg = readStatusMessage(result) ?? `A2A task ${this.taskId} state=${state}`;
+        if (isCanceledState(state)) {
+            throw new A2AJobCanceledError(msg);
+        }
+        throw new A2AJobFailedError(msg);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Sleep for `ms` OR until `signal` aborts — whichever is first. The
+ * abort wakes us early; the timer is cleared in either path so we
+ * don't leak handles. Uses an `AbortSignal` instead of a raw promise
+ * so the polling loop can attach ONE upstream listener (the
+ * AbortController) and fan out to per-iteration `raceSleep` calls
+ * without accumulating handlers on a long-running cancelPromise.
+ */
+function raceSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=a2a-job.js.map

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * Async iterator over parsed A2A SSE events — returned by
+ * `A2AClient.subscribe` (issue #917).
+ *
+ * Implements `AsyncIterable<A2AEvent>` so callers can write
+ * `for await (const event of stream) { ... }` idiomatically.
+ * Implements TC39 `Symbol.asyncDispose` (Node 20+) for `await using`,
+ * AND exposes `aclose()` as a manual fallback for older runtimes.
+ *
+ * Per A2A v1.0, client disconnect is a transient signal — the producer
+ * continues running unless explicitly canceled. `bridge` therefore does
+ * NOT POST `tasks/cancel` upstream when the mesh-side job is cancelled
+ * (it just closes the SSE connection). Users who need cancel
+ * propagation should use `submit` + `A2AJob.bridge` instead, which
+ * polls for cancel between iterations and propagates upstream.
+ *
+ * Mirrors `mesh._a2a_consumer.A2AStream` (Python) and
+ * `io.mcpmesh.a2a.A2AStream` (Java).
+ */
+import { JobController } from "@mcpmesh/core";
+import type { A2AEvent } from "./a2a-event.js";
+export declare class A2AStream implements AsyncIterable<A2AEvent> {
+    private readonly response;
+    readonly taskId: string;
+    private closed;
+    private reader;
+    constructor(response: Response, taskId: string);
+    [Symbol.asyncIterator](): AsyncIterator<A2AEvent>;
+    /** Mirror events into a JobController; return the final artifact value. */
+    bridge(controller: JobController): Promise<unknown>;
+    /**
+     * Explicit close — releases the reader lock + cancels the
+     * underlying ReadableStream so the undici Agent reclaims the
+     * connection promptly. Idempotent.
+     */
+    aclose(): Promise<void>;
+    private _iterate;
+}
+//# sourceMappingURL=a2a-stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-stream.d.ts","sourceRoot":"","sources":["../../src/a2a/a2a-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAW/C,qBAAa,SAAU,YAAW,aAAa,CAAC,QAAQ,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAwD;gBAE1D,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;IAK9C,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,QAAQ,CAAC;IAcjD,2EAA2E;IACrE,MAAM,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAsFzD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;YA4Bd,QAAQ;CAkFxB"}

package/dist/a2a/a2a-stream.js

@@ -0,0 +1,290 @@
+import { A2AJobCanceledError, A2AJobFailedError, } from "./errors.js";
+import { maybeJsonParse } from "./a2a-client.js";
+const ASYNC_DISPOSE = Symbol.asyncDispose ??
+    Symbol.for("Symbol.asyncDispose");
+export class A2AStream {
+    response;
+    taskId;
+    closed = false;
+    reader = null;
+    constructor(response, taskId) {
+        this.response = response;
+        this.taskId = taskId;
+    }
+    [Symbol.asyncIterator]() {
+        return this._iterate();
+    }
+    /**
+     * TC39 explicit-resource-management hook — Node 20+ supports
+     * `await using stream = await client.subscribe(...)`. The fallback
+     * below uses Symbol.for so older runtimes still surface a usable
+     * symbol on the prototype (idempotent close).
+     */
+    async [ASYNC_DISPOSE]() {
+        await this.aclose();
+    }
+    /** Mirror events into a JobController; return the final artifact value. */
+    async bridge(controller) {
+        if (controller == null) {
+            throw new Error("A2AStream.bridge: controller must be non-null");
+        }
+        let lastProgress;
+        let lastMessage;
+        let artifactValue = "";
+        let sawArtifact = false;
+        let terminalState;
+        let terminalMessage;
+        try {
+            for await (const event of this) {
+                if (event.kind === "artifact") {
+                    const text = event.artifactText ?? "";
+                    artifactValue = !text ? text : maybeJsonParse(text);
+                    sawArtifact = true;
+                    continue;
+                }
+                if (event.progress !== undefined || event.message !== undefined) {
+                    const changed = event.progress !== lastProgress || event.message !== lastMessage;
+                    if (changed) {
+                        const rawP = event.progress !== undefined
+                            ? event.progress
+                            : lastProgress !== undefined
+                                ? lastProgress
+                                : 0.0;
+                        const clamped = Math.min(1.0, Math.max(0.0, rawP));
+                        try {
+                            await controller.updateProgress(clamped, event.message ?? null);
+                            if (event.progress !== undefined)
+                                lastProgress = event.progress;
+                            lastMessage = event.message;
+                        }
+                        catch (err) {
+                            // Do NOT advance lastProgress / lastMessage on delivery
+                            // failure — leaving them stale ensures the next event
+                            // still passes the equality check and retries.
+                            console.warn(`[a2a-stream] bridge: controller.updateProgress failed ` +
+                                `(task=${this.taskId}, progress=${event.progress}, ` +
+                                `msg=${event.message}) — will retry on next event: ` +
+                                `${err?.message ?? String(err)}`);
+                        }
+                    }
+                }
+                if (event.final) {
+                    terminalState = event.state;
+                    terminalMessage = event.message;
+                    break;
+                }
+            }
+        }
+        finally {
+            // Ensure the SSE stream is closed on any exit path (normal
+            // completion, throw, etc.). aclose() is idempotent.
+            await this.aclose();
+        }
+        if (terminalState) {
+            const lower = terminalState.toLowerCase();
+            if (lower === "canceled" || lower === "cancelled") {
+                throw new A2AJobCanceledError(terminalMessage ?? `A2A task ${this.taskId} canceled`);
+            }
+            if (lower === "failed") {
+                throw new A2AJobFailedError(terminalMessage ?? `A2A task ${this.taskId} failed`);
+            }
+            // Parity with A2AJob._terminalToArtifactOrThrow — completed
+            // with no artifact event seen returns "" rather than throwing,
+            // matching the polling-bridge semantics.
+            if (lower === "completed" && !sawArtifact) {
+                return "";
+            }
+        }
+        if (!sawArtifact) {
+            throw new A2AJobFailedError(`A2A subscribe stream ${this.taskId} ended without artifact`);
+        }
+        return artifactValue;
+    }
+    /**
+     * Explicit close — releases the reader lock + cancels the
+     * underlying ReadableStream so the undici Agent reclaims the
+     * connection promptly. Idempotent.
+     */
+    async aclose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            if (this.reader) {
+                try {
+                    await this.reader.cancel();
+                }
+                catch {
+                    // best-effort
+                }
+                try {
+                    this.reader.releaseLock();
+                }
+                catch {
+                    // best-effort
+                }
+                this.reader = null;
+            }
+            else if (this.response.body) {
+                try {
+                    await this.response.body.cancel();
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        }
+        catch {
+            // swallow — close is best-effort
+        }
+    }
+    async *_iterate() {
+        if (this.closed)
+            return;
+        if (!this.response.body) {
+            throw new A2AJobFailedError(`A2AStream(${this.taskId}): response body is null`);
+        }
+        if (!this.reader) {
+            this.reader = this.response.body.getReader();
+        }
+        const reader = this.reader;
+        const decoder = new TextDecoder("utf-8");
+        let pending = "";
+        const dataBuf = [];
+        const flushEvent = () => {
+            if (dataBuf.length === 0)
+                return null;
+            const payload = dataBuf.join("\n");
+            dataBuf.length = 0;
+            let envelope;
+            try {
+                envelope = JSON.parse(payload);
+            }
+            catch {
+                // Skip non-JSON SSE frames silently — matches Python behavior.
+                return null;
+            }
+            return parseSseEnvelope(envelope);
+        };
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                pending += decoder.decode(value, { stream: true });
+                let nlIdx;
+                while ((nlIdx = pending.search(/\r\n|\n/)) !== -1) {
+                    // Accept both LF and CRLF line endings.
+                    const isCrLf = pending.charCodeAt(nlIdx) === 13 &&
+                        pending.charCodeAt(nlIdx + 1) === 10;
+                    const line = pending.slice(0, nlIdx);
+                    pending = pending.slice(nlIdx + (isCrLf ? 2 : 1));
+                    if (line === "") {
+                        const event = flushEvent();
+                        if (event !== null) {
+                            yield event;
+                            if (event.final) {
+                                await this.aclose();
+                                return;
+                            }
+                        }
+                        continue;
+                    }
+                    if (line.startsWith(":")) {
+                        // SSE comment / keepalive — ignore.
+                        continue;
+                    }
+                    if (line.startsWith("data:")) {
+                        // Strip "data:" prefix and one optional space.
+                        let payload = line.slice(5);
+                        if (payload.startsWith(" "))
+                            payload = payload.slice(1);
+                        dataBuf.push(payload);
+                        continue;
+                    }
+                    // event:/id:/retry:/unknown — ignore for v1.0.
+                }
+            }
+            // Stream ended without a trailing blank — flush any pending frame.
+            pending += decoder.decode();
+            if (pending.length > 0 && pending.startsWith("data:")) {
+                let payload = pending.slice(5);
+                if (payload.startsWith(" "))
+                    payload = payload.slice(1);
+                dataBuf.push(payload);
+            }
+            const tail = flushEvent();
+            if (tail !== null) {
+                yield tail;
+            }
+        }
+        finally {
+            await this.aclose();
+        }
+    }
+}
+function parseSseEnvelope(envelope) {
+    if (!envelope || typeof envelope !== "object")
+        return null;
+    const result = envelope.result;
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    // ARTIFACT events have the "artifact" key.
+    const artifact = r.artifact;
+    if (artifact && typeof artifact === "object") {
+        const text = extractFirstTextPart(artifact) ?? "";
+        return {
+            kind: "artifact",
+            artifactText: text,
+            final: false,
+            raw: envelope,
+        };
+    }
+    // STATUS events have the "status" key.
+    const status = r.status;
+    if (status && typeof status === "object") {
+        const statusObj = status;
+        const stateRaw = statusObj.state;
+        const state = typeof stateRaw === "string" ? stateRaw : undefined;
+        const msgObj = statusObj.message;
+        let message;
+        if (msgObj && typeof msgObj === "object") {
+            message = extractFirstTextPart(msgObj);
+        }
+        let progress;
+        const metadata = r.metadata;
+        if (metadata && typeof metadata === "object") {
+            const p = metadata.progress;
+            if (typeof p === "number" && Number.isFinite(p))
+                progress = p;
+            else if (typeof p === "string") {
+                const n = Number.parseFloat(p);
+                if (Number.isFinite(n))
+                    progress = n;
+            }
+        }
+        const finalRaw = r.final;
+        const final = finalRaw === true;
+        return {
+            kind: "status",
+            state,
+            progress,
+            message,
+            final,
+            raw: envelope,
+        };
+    }
+    return null;
+}
+function extractFirstTextPart(container) {
+    const parts = container.parts;
+    if (!Array.isArray(parts) || parts.length === 0)
+        return undefined;
+    const first = parts[0];
+    if (!first || typeof first !== "object")
+        return undefined;
+    const text = first.text;
+    return typeof text === "string" ? text : undefined;
+}
+//# sourceMappingURL=a2a-stream.js.map