@owlmeans/llm 0.1.18-rc.48 → 0.1.18-rc.49

package/README.md

@@ -20,7 +20,7 @@ abstraction that resolves models from an inheritable policy.
 ## Installation
 
 ```bash
-bun add @owlmeans/llm@^0.1.18-rc.48 @owlmeans/llm-common@^0.1.18-rc.39
+bun add @owlmeans/llm@^0.1.18-rc.49 @owlmeans/llm-common@^0.1.18-rc.39
 bun add @langchain/core @langchain/openai @langchain/anthropic   # peer dependencies
 ```
 
@@ -134,7 +134,7 @@ spectator entry), `filter` (reject a result and force a retry), `useCache` / `ca
 
 | Problem | What the package does |
 |---------|-----------------------|
-| Provider accepts the request and never streams | Idle (per-token) deadline aborts and retries — `ModelConfig.streamTimeout` |
+| Provider accepts the request and never streams | Independent idle deadline rejects stream creation or reads and aborts the SDK; late values and cleanup cannot delay the retry — `ModelConfig.streamTimeout` |
 | Duplicate final SSE chunk corrupts tool-call arguments | Stream breaks at the first non-empty `finish_reason` |
 | Reasoning eats the whole output budget | Retry doubles `maxTokens` toward `maxTokensCap` **and** shrinks an absolute reasoning cap |
 | A weak cheap model keeps failing | Walks the `ModelConfig.fallback` chain, `FALLBACK_AFTER_ATTEMPTS` attempts per rung; a rung may be another provider, called in its own dialect |

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/llm",
-  "version": "0.1.18-rc.48",
-  "generatedAt": "2026-10-09T11:30:42.745Z",
+  "version": "0.1.18-rc.49",
+  "generatedAt": "2026-10-09T18:54:30.297Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/llm/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/llm
 
 **Layer:** Core
-**Install:** `"@owlmeans/llm": "^0.1.18-rc.48"` in `dependencies` (plus the `@langchain/*` peers)
+**Install:** `"@owlmeans/llm": "^0.1.18-rc.49"` in `dependencies` (plus the `@langchain/*` peers)
 
 The inference runtime. Everything provider-specific is a **plugin**; the model itself only owns the
 provider-independent parts (streaming discipline, retries, validation, observability). Serializable
@@ -195,7 +195,11 @@ becomes a foreign type and `instanceof` starts lying.
 ## Hangs are bounded by an IDLE deadline, not a total one
 
 A stalled provider is aborted after `MODEL_STREAM_TIMEOUT_MS` (3 min) of SILENCE and surfaces as a
-retryable `LlmModelError`, so the escalator moves on. The timer re-arms on every token, so a
+retryable `LlmModelError`, so the escalator moves on. Stream creation and each iterator read race
+an independently rejecting deadline; forwarding an abort signal alone does not bound an SDK
+promise that ignores cancellation. Late values never reach the caller, late failures are observed,
+and best-effort iterator cleanup never delays timeout, terminal chunks or consumer cancellation.
+The timer re-arms on every token, so a
 long-but-productive generation is never cut off — which is why the value can be low. Set it for a
 deployment with `LlmServiceOptions.streamTimeout` where the application composes its context; a
 preset naming its own `ModelConfig.streamTimeout` keeps it. It does NOT bound a call that keeps
@@ -461,6 +465,12 @@ the retry on a text-only reply) through `ChatAnthropic.invocationParams`; `struc
 pins the refusal of a hidden property name before any request. `plugins.spec.ts` covers the
 `Compatible` provider offline.
 
+`internals.spec.ts` covers abort-insensitive stream creation, reads and cleanup, observed late
+failures, ignored late values, consumer cancellation and active streams exceeding multiple idle
+windows. `bun test ./tests/stream-sdk.spec.ts` exercises actual ChatOpenAI Responses against local
+HTTP fixtures: missing headers, open headers without SSE, and a productive SSE control. It checks
+socket cancellation and absence of late callbacks without spending provider tokens.
+
 ## Depends On
 
 - `@owlmeans/llm-common` · `@owlmeans/context` · `@owlmeans/error` · `@owlmeans/basic-ids` · `ajv`

package/build/utils/stream/types.d.ts

@@ -10,9 +10,10 @@ export interface StreamUtils {
      * `AbortSignal` to forward to `model.stream(..., { signal })`; the timer is re-armed on
      * every received chunk, so it only fires after `timeoutMs` of SILENCE — a provider that
      * accepted the request but stalls and never streams another token. On fire the call is
-     * aborted and surfaced as a retryable {@link LlmModelError} so the retry escalator moves
-     * on instead of hanging forever. Because the timer resets per token, long but actively
-     * streaming generations are never aborted.
+     * aborted and surfaced as a retryable {@link LlmModelError} independently of SDK
+     * cancellation settling. Both stream creation and iterator reads race the deadline;
+     * late results and cleanup cannot delay or resume the failed call. Because the timer
+     * resets per token, long but actively streaming generations are never aborted.
      *
      * The loop also breaks after the first chunk carrying a non-empty `finish_reason`. Some
      * providers send the final SSE data event twice, which makes `AIMessageChunk.concat()`

package/build/utils/stream/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/stream/types.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,oBAAoB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAA;IAC5D;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,EAAE,CAAC,CAAC,EACpB,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EACzD,SAAS,CAAC,EAAE,MAAM,KACf,cAAc,CAAC,CAAC,CAAC,CAAA;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/stream/types.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,oBAAoB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAA;IAC5D;;;;;;;;;;;;;;;OAeG;IACH,kBAAkB,EAAE,CAAC,CAAC,EACpB,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EACzD,SAAS,CAAC,EAAE,MAAM,KACf,cAAc,CAAC,CAAC,CAAC,CAAA;CACvB"}

package/build/utils/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,eAAO,MAAM,iBAAiB,QAAO,WAuCpC,CAAA;AAED,eAAO,MAAM,WAAW,aAAsB,CAAA"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,eAAO,MAAM,iBAAiB,QAAO,WAiEpC,CAAA;AAED,eAAO,MAAM,WAAW,aAAsB,CAAA"}

package/build/utils/stream.js

@@ -7,15 +7,47 @@ export const createStreamUtils = () => {
     };
     async function* streamWithDeadline(start, timeoutMs = MODEL_STREAM_TIMEOUT_MS) {
         const controller = new AbortController();
-        let timer;
+        let rejectIdle = () => { };
+        const idle = new Promise((_, reject) => { rejectIdle = reject; });
+        // A consumer may pause at `yield` when the deadline fires.
+        void idle.catch(() => { });
+        let disarm = () => { };
         const arm = () => {
-            clearTimeout(timer);
-            timer = setTimeout(() => controller.abort(), timeoutMs);
+            disarm();
+            const timer = setTimeout(() => {
+                controller.abort();
+                rejectIdle(new LlmModelError(`stream-stalled:no token for ${timeoutMs}ms (idle deadline)`));
+            }, timeoutMs);
+            disarm = () => clearTimeout(timer);
+        };
+        let iterator;
+        let closed = false;
+        const close = () => {
+            if (iterator == null || closed)
+                return;
+            closed = true;
+            // SDK cancellation and iterator cleanup may themselves never settle.
+            try {
+                void Promise.resolve(iterator.return?.()).catch(() => { });
+            }
+            catch { }
         };
         arm();
         try {
-            const stream = await start(controller.signal);
-            for await (const chunk of stream) {
+            const starting = Promise.resolve().then(() => start(controller.signal)).then(stream => {
+                iterator = stream[Symbol.asyncIterator]();
+                if (controller.signal.aborted)
+                    close();
+                return iterator;
+            });
+            const current = await Promise.race([starting, idle]);
+            for (;;) {
+                const next = await Promise.race([Promise.resolve().then(() => current.next()), idle]);
+                if (next.done) {
+                    closed = true;
+                    break;
+                }
+                const chunk = next.value;
                 arm(); // reset the idle timer on each received token
                 yield chunk;
                 const reason = getChunkFinishReason(chunk);
@@ -30,7 +62,10 @@ export const createStreamUtils = () => {
             throw e;
         }
         finally {
-            clearTimeout(timer);
+            disarm();
+            if (!closed)
+                controller.abort();
+            close();
         }
     }
     return { getChunkFinishReason, streamWithDeadline };

package/build/utils/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAGtD,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAgB,EAAE;IACjD,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAsB,EAAE;QAClE,MAAM,CAAC,GAAG,KAGT,CAAA;QACD,OAAO,CAAC,CAAC,iBAAiB,EAAE,aAAa,IAAI,CAAC,CAAC,GAAG,EAAE,iBAAiB,EAAE,aAAa,CAAA;IACtF,CAAC,CAAA;IAED,KAAK,SAAS,CAAC,CAAC,kBAAkB,CAChC,KAAyD,EACzD,SAAS,GAAW,uBAAuB;QAE3C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,IAAI,KAAoC,CAAA;QACxC,MAAM,GAAG,GAAG,GAAG,EAAE;YACf,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAA;QACzD,CAAC,CAAA;QACD,GAAG,EAAE,CAAA;QACL,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;YAC7C,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBACjC,GAAG,EAAE,CAAA,CAAC,8CAA8C;gBACpD,MAAM,KAAK,CAAA;gBACX,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAA;gBAC1C,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,EAAE;oBAAE,MAAK;YAC5C,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC9B,MAAM,IAAI,aAAa,CAAC,+BAA+B,SAAS,oBAAoB,CAAC,CAAA;YACvF,CAAC;YACD,MAAM,CAAC,CAAA;QACT,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAM,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,CAAA;AACrD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/utils/stream.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/llm",
-  "version": "0.1.18-rc.48",
+  "version": "0.1.18-rc.49",
   "license": "MIT",
   "type": "module",
   "scripts": {

package/src/utils/stream/types.ts

@@ -10,9 +10,10 @@ export interface StreamUtils {
    * `AbortSignal` to forward to `model.stream(..., { signal })`; the timer is re-armed on
    * every received chunk, so it only fires after `timeoutMs` of SILENCE — a provider that
    * accepted the request but stalls and never streams another token. On fire the call is
-   * aborted and surfaced as a retryable {@link LlmModelError} so the retry escalator moves
-   * on instead of hanging forever. Because the timer resets per token, long but actively
-   * streaming generations are never aborted.
+   * aborted and surfaced as a retryable {@link LlmModelError} independently of SDK
+   * cancellation settling. Both stream creation and iterator reads race the deadline;
+   * late results and cleanup cannot delay or resume the failed call. Because the timer
+   * resets per token, long but actively streaming generations are never aborted.
    *
    * The loop also breaks after the first chunk carrying a non-empty `finish_reason`. Some
    * providers send the final SSE data event twice, which makes `AIMessageChunk.concat()`

package/src/utils/stream.ts

@@ -16,15 +16,39 @@ export const createStreamUtils = (): StreamUtils => {
     timeoutMs: number = MODEL_STREAM_TIMEOUT_MS,
   ): AsyncGenerator<T> {
     const controller = new AbortController()
-    let timer: ReturnType<typeof setTimeout>
+    let rejectIdle: (error: LlmModelError) => void = () => {}
+    const idle = new Promise<never>((_, reject) => { rejectIdle = reject })
+    // A consumer may pause at `yield` when the deadline fires.
+    void idle.catch(() => {})
+    let disarm = () => {}
     const arm = () => {
-      clearTimeout(timer)
-      timer = setTimeout(() => controller.abort(), timeoutMs)
+      disarm()
+      const timer = setTimeout(() => {
+        controller.abort()
+        rejectIdle(new LlmModelError(`stream-stalled:no token for ${timeoutMs}ms (idle deadline)`))
+      }, timeoutMs)
+      disarm = () => clearTimeout(timer)
+    }
+    let iterator: AsyncIterator<T> | undefined
+    let closed = false
+    const close = () => {
+      if (iterator == null || closed) return
+      closed = true
+      // SDK cancellation and iterator cleanup may themselves never settle.
+      try { void Promise.resolve(iterator.return?.()).catch(() => {}) } catch {}
     }
     arm()
     try {
-      const stream = await start(controller.signal)
-      for await (const chunk of stream) {
+      const starting = Promise.resolve().then(() => start(controller.signal)).then(stream => {
+        iterator = stream[Symbol.asyncIterator]()
+        if (controller.signal.aborted) close()
+        return iterator
+      })
+      const current = await Promise.race([starting, idle])
+      for (;;) {
+        const next = await Promise.race([Promise.resolve().then(() => current.next()), idle])
+        if (next.done) { closed = true; break }
+        const chunk = next.value
         arm() // reset the idle timer on each received token
         yield chunk
         const reason = getChunkFinishReason(chunk)
@@ -36,7 +60,9 @@ export const createStreamUtils = (): StreamUtils => {
       }
       throw e
     } finally {
-      clearTimeout(timer!)
+      disarm()
+      if (!closed) controller.abort()
+      close()
     }
   }
 

package/tests/internals.spec.ts

@@ -4,6 +4,7 @@ import { EMPTY_CONTENT_STUB, JSON_INSTRUCTION, NO_THINK_DIRECTIVE } from '../src
 import { streamUtils } from '../src/utils/stream.js'
 import { promptUtils } from '../src/utils/prompt.js'
 import { schemaUtils } from '../src/utils/schema.js'
+import { LlmModelError } from '../src/errors.js'
 
 /**
  * Internal utilities — deliberately not part of the package surface (`utils/` is
@@ -102,7 +103,7 @@ describe('utils/prompt — blank content sanitization', () => {
     ] as MessageFieldWithRole[]
     promptUtils.dropBlankContent(msgs)
     expect(msgs).toHaveLength(2)
-    expect((msgs[1] as ToolMessage).content).toBe(EMPTY_CONTENT_STUB)
+    expect((msgs[1] as unknown as ToolMessage).content).toBe(EMPTY_CONTENT_STUB)
   })
 
   test('keeps a blank AI message that carries tool calls, with empty string content', () => {
@@ -112,7 +113,7 @@ describe('utils/prompt — blank content sanitization', () => {
     ] as MessageFieldWithRole[]
     promptUtils.dropBlankContent(msgs)
     expect(msgs).toHaveLength(2)
-    expect((msgs[1] as AIMessage).content).toBe('')
+    expect((msgs[1] as unknown as AIMessage).content).toBe('')
   })
 
   test('replaces an all-blank input with a single stub user message', () => {
@@ -135,7 +136,7 @@ describe('utils/schema — tool naming and unwrapping', () => {
   })
 
   test('unwraps a named envelope, and passes anything else through', () => {
-    expect(schemaUtils.unwrapNamed({ spec: { a: 1 } }, 'spec')).toEqual({ a: 1 })
+    expect(schemaUtils.unwrapNamed<object>({ spec: { a: 1 } }, 'spec')).toEqual({ a: 1 })
     expect(schemaUtils.unwrapNamed({ a: 1 }, 'spec')).toEqual({ a: 1 })
     expect(schemaUtils.unwrapNamed({ a: 1 }, undefined)).toEqual({ a: 1 })
     expect(schemaUtils.unwrapNamed('plain' as unknown as object, 'spec')).toBe('plain' as unknown as object)
@@ -202,4 +203,131 @@ describe('utils/stream — idle deadline and duplicate-final-chunk dedup', () =>
     }
     await expect(collect(streamUtils.streamWithDeadline(failing, 1000))).rejects.toThrow('401 unauthorized')
   })
+
+  test('bounds stream creation even when the provider ignores abort', async () => {
+    let signal: AbortSignal | undefined
+    const started = Date.now()
+    await expect(collect(streamUtils.streamWithDeadline(async received => {
+      signal = received
+      return await new Promise<AsyncIterable<unknown>>(() => {})
+    }, 60))).rejects.toBeInstanceOf(LlmModelError)
+    expect(signal?.aborted).toBe(true)
+    expect(Date.now() - started).toBeLessThan(1500)
+  }, 2000)
+
+  test('bounds iterator reads without waiting for uncooperative cleanup', async () => {
+    let signal: AbortSignal | undefined
+    let returned = 0
+    const iterator: AsyncIterator<unknown> = {
+      next: async () => await new Promise<IteratorResult<unknown>>(() => {}),
+      return: async () => { returned += 1; return await new Promise<IteratorResult<unknown>>(() => {}) },
+    }
+    const started = Date.now()
+    await expect(collect(streamUtils.streamWithDeadline(async received => {
+      signal = received
+      return { [Symbol.asyncIterator]: () => iterator }
+    }, 60))).rejects.toThrow('stream-stalled')
+    expect(signal?.aborted).toBe(true)
+    expect(returned).toBe(1)
+    expect(Date.now() - started).toBeLessThan(1500)
+  }, 2000)
+
+  test('closes a stream created after the deadline without reading late values', async () => {
+    let resolveStart!: (stream: AsyncIterable<unknown>) => void
+    let reads = 0
+    let returned = 0
+    const pending = collect(streamUtils.streamWithDeadline(async () => await new Promise<AsyncIterable<unknown>>(resolve => {
+      resolveStart = resolve
+    }), 60))
+    await expect(pending).rejects.toThrow('stream-stalled')
+    resolveStart({ [Symbol.asyncIterator]: () => ({
+      next: async () => { reads += 1; return { done: false, value: 'late' } },
+      return: async () => { returned += 1; throw new Error('late cleanup failure') },
+    }) })
+    await Bun.sleep(20)
+    expect(reads).toBe(0)
+    expect(returned).toBe(1)
+  }, 2000)
+
+  test('observes a late stream-creation failure after the caller has already failed', async () => {
+    let rejectStart!: (error: Error) => void
+    const pending = collect(streamUtils.streamWithDeadline(async () => await new Promise<AsyncIterable<unknown>>((_, reject) => {
+      rejectStart = reject
+    }), 60))
+    const failure = await pending.catch(error => error)
+    expect(failure).toBeInstanceOf(LlmModelError)
+    rejectStart(new Error('late provider failure'))
+    await Bun.sleep(20)
+    // Bun would fail this spec on an unhandled late rejection.
+    expect(failure.message).toContain('stream-stalled')
+  }, 2000)
+
+  test('ignores an iterator value arriving after the deadline', async () => {
+    let resolveNext!: (item: IteratorResult<unknown>) => void
+    let reads = 0
+    let returned = 0
+    const received: unknown[] = []
+    const iterator: AsyncIterator<unknown> = {
+      next: async () => { reads += 1; return await new Promise<IteratorResult<unknown>>(resolve => { resolveNext = resolve }) },
+      return: async () => { returned += 1; return { done: true, value: undefined } },
+    }
+    const pending = (async () => {
+      for await (const value of streamUtils.streamWithDeadline(async () => ({ [Symbol.asyncIterator]: () => iterator }), 60)) received.push(value)
+    })()
+    await expect(pending).rejects.toThrow('stream-stalled')
+    resolveNext({ done: false, value: 'late' })
+    await Bun.sleep(20)
+    expect(received).toEqual([])
+    expect(reads).toBe(1)
+    expect(returned).toBe(1)
+  }, 2000)
+
+  test('allows active streams to exceed multiple idle windows', async () => {
+    let signal: AbortSignal | undefined
+    const started = Date.now()
+    const output = await collect(streamUtils.streamWithDeadline(async received => {
+      signal = received
+      return { async *[Symbol.asyncIterator]() {
+        for (let i = 0; i < 12; i += 1) { await Bun.sleep(20); yield i }
+      } }
+    }, 100))
+    expect(output).toEqual(Array.from({ length: 12 }, (_, i) => i))
+    expect(Date.now() - started).toBeGreaterThan(200)
+    expect(signal?.aborted).toBe(false)
+  }, 3000)
+
+  test('a terminal chunk is delivered even when iterator cleanup never settles', async () => {
+    let signal: AbortSignal | undefined
+    let returned = 0
+    const final = { response_metadata: { finish_reason: 'stop' } }
+    const output = await collect(streamUtils.streamWithDeadline(async received => {
+      signal = received
+      return { [Symbol.asyncIterator]: () => ({
+        next: async () => ({ done: false, value: final }),
+        return: async () => { returned += 1; return await new Promise<IteratorResult<unknown>>(() => {}) },
+      }) }
+    }, 60))
+    expect(output).toEqual([final])
+    expect(signal?.aborted).toBe(true)
+    expect(returned).toBe(1)
+  }, 2000)
+
+  test('consumer cancellation aborts the provider and observes cleanup failures', async () => {
+    let signal: AbortSignal | undefined
+    let reads = 0
+    let returned = 0
+    const stream = streamUtils.streamWithDeadline(async received => {
+      signal = received
+      return { [Symbol.asyncIterator]: () => ({
+        next: async () => { reads += 1; return { done: false, value: 'first' } },
+        return: async () => { returned += 1; throw new Error('cleanup failure') },
+      }) }
+    }, 60)
+    expect(await stream.next()).toEqual({ done: false, value: 'first' })
+    expect((await stream.return(undefined)).done).toBe(true)
+    expect(signal?.aborted).toBe(true)
+    await Bun.sleep(80)
+    expect(reads).toBe(1)
+    expect(returned).toBe(1)
+  }, 2000)
 })

package/tests/stream-sdk.spec.ts

@@ -0,0 +1,218 @@
+import { describe, expect, test } from 'bun:test'
+import { createServer, type ServerResponse } from 'node:http'
+import type { AddressInfo, Socket } from 'node:net'
+import { ChatOpenAI } from '@langchain/openai'
+import type { AIMessage } from '@langchain/core/messages'
+import { ModelProvider, type SpectatorArgument } from '@owlmeans/llm-common'
+import { LlmModelError, LlmRetryExceededError } from '../src/errors.js'
+import { makeLlmModel } from '../src/model.js'
+import type { LlmModel, RefferedResult } from '../src/types.js'
+
+interface ResponsesRequest {
+  method: string | undefined
+  path: string | undefined
+  body: { model: string, stream: boolean, input: unknown[] }
+}
+
+interface LocalResponses {
+  baseURL: string
+  request: Promise<ResponsesRequest>
+  disconnected: Promise<void>
+  requests: () => number
+  delta: (text: string) => void
+  complete: () => void
+  stop: () => Promise<void>
+}
+
+interface ObservedModel {
+  model: LlmModel
+  tokens: string[]
+  traces: SpectatorArgument[]
+  ref: RefferedResult<AIMessage>
+  accepted: string[]
+}
+
+/** Real HTTP and SDK parsing; only the remote provider is replaced by a local fixture. */
+const localResponses = async (sendHeaders: boolean): Promise<LocalResponses> => {
+  let resolveRequest: (request: ResponsesRequest) => void = () => {}
+  const request = new Promise<ResponsesRequest>(resolve => { resolveRequest = resolve })
+  let resolveDisconnected: () => void = () => {}
+  const disconnected = new Promise<void>(resolve => { resolveDisconnected = resolve })
+  let response: ServerResponse | undefined
+  let requests = 0
+  let sequence = 0
+  const sockets = new Set<Socket>()
+  const server = createServer((req, res) => {
+    requests += 1
+    response = res
+    req.socket.once('close', resolveDisconnected)
+    // A deliberate late write after the client's cancellation is part of these tests.
+    res.on('error', () => {})
+    const body: Buffer[] = []
+    req.on('data', chunk => body.push(Buffer.from(chunk)))
+    req.on('end', () => {
+      if (sendHeaders) {
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' })
+        res.flushHeaders()
+      }
+      resolveRequest({ method: req.method, path: req.url, body: JSON.parse(Buffer.concat(body).toString()) })
+    })
+  })
+  server.on('connection', socket => {
+    sockets.add(socket)
+    socket.once('close', () => sockets.delete(socket))
+  })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+
+  const event = (value: Record<string, unknown>): void => {
+    if (response == null) throw new Error('Responses fixture has received no request')
+    if (!response.headersSent) {
+      response.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' })
+    }
+    response.write(`event: ${value.type}\ndata: ${JSON.stringify({ ...value, sequence_number: sequence++ })}\n\n`)
+  }
+
+  return {
+    baseURL: `http://127.0.0.1:${(server.address() as AddressInfo).port}/v1`,
+    request,
+    disconnected,
+    requests: () => requests,
+    delta: text => event({
+      type: 'response.output_text.delta', item_id: 'msg_local', output_index: 0,
+      content_index: 0, delta: text, logprobs: [],
+    }),
+    complete: () => {
+      event({
+        type: 'response.completed',
+        response: {
+          id: 'resp_local', object: 'response', model: 'gpt-6.1-sol', status: 'completed',
+          created_at: 1, output: [], usage: { input_tokens: 1, output_tokens: 1, total_tokens: 2 },
+        },
+      })
+      response!.end()
+    },
+    stop: async () => {
+      await new Promise<void>(resolve => {
+        server.close(() => resolve())
+        for (const socket of sockets) socket.destroy()
+      })
+    },
+  }
+}
+
+const observedModel = (baseURL: string, idleMs: number): ObservedModel => {
+  const tokens: string[] = []
+  const traces: SpectatorArgument[] = []
+  const accepted: string[] = []
+  const ref: RefferedResult<AIMessage> = {}
+  const model = makeLlmModel({
+    model: new ChatOpenAI({
+      apiKey: 'local-sdk-regression', model: 'gpt-6.1-sol', useResponsesApi: true,
+      configuration: { baseURL }, maxRetries: 5, timeout: 10_000, maxTokens: 64,
+      metadata: { config: { provider: ModelProvider.OpenAI, model: 'gpt-6.1-sol', streamTimeout: idleMs } },
+      callbacks: [{ handleLLMNewToken: token => { tokens.push(token) } }],
+    }),
+    purpose: { type: 'local-sdk-regression' }, retries: 1,
+  }, {
+    log: async entry => {
+      traces.push(entry)
+      return {
+        ...entry, id: 'local-trace', kind: 'general', model: 'gpt-6.1-sol',
+        purpose: { type: 'local-sdk-regression' }, timestamp: Date.now(),
+      }
+    },
+  })
+
+  return { model, tokens, traces, accepted, ref }
+}
+
+/** The test's guard is deliberately longer than the model's independent idle deadline. */
+const bounded = async <T>(promise: Promise<T>): Promise<T> => {
+  let timer: NodeJS.Timeout | undefined
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error('Local SDK operation did not settle within 2 seconds')), 2_000)
+      }),
+    ])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+describe('@owlmeans/llm — Responses SDK stream cancellation over real HTTP', () => {
+  for (const sendHeaders of [false, true]) {
+    test(`rejects and closes a ${sendHeaders ? 'headers-open/no-SSE' : 'never-headers'} response without accepting late output`, async () => {
+      const transport = await localResponses(sendHeaders)
+      const observed = observedModel(transport.baseURL, 180)
+      try {
+        const startedAt = performance.now()
+        const result = observed.model.ask('Local transport fixture only', {
+          action: 'local-stalled-response', ref: observed.ref,
+          filter: async text => { observed.accepted.push(text); return text },
+        }).then(value => ({ value, error: undefined }), (error: unknown) => ({ value: undefined, error }))
+        const request = await bounded(transport.request)
+        expect(request.method).toBe('POST')
+        expect(request.path).toBe('/v1/responses')
+        expect(request.body.model).toBe('gpt-6.1-sol')
+        expect(request.body.stream).toBe(true)
+        expect(request.body.input).toHaveLength(1)
+
+        const outcome = await bounded(result)
+        expect(outcome.error).toBeInstanceOf(LlmRetryExceededError)
+        expect((outcome.error as LlmRetryExceededError).cause).toBeInstanceOf(LlmModelError)
+        expect(((outcome.error as LlmRetryExceededError).cause as Error).message).toContain('stream-stalled')
+        expect(outcome.value).toBeUndefined()
+        expect(performance.now() - startedAt).toBeLessThan(1_500)
+
+        // Prove the client closed the network before the fixture's cleanup can do it.
+        await bounded(transport.disconnected)
+        expect(transport.requests()).toBe(1)
+        transport.delta('late output must not be accepted')
+        transport.complete()
+        await new Promise<void>(resolve => setTimeout(resolve, 40))
+        expect(observed.tokens).toEqual([])
+        expect(observed.traces).toEqual([])
+        expect(observed.accepted).toEqual([])
+        expect(observed.ref.value).toBeUndefined()
+        expect(observed.ref.spectatorEntry).toBeUndefined()
+      } finally {
+        await transport.stop()
+      }
+    })
+  }
+
+  test('accepts real Responses deltas that keep arriving beyond one idle window', async () => {
+    const transport = await localResponses(true)
+    const observed = observedModel(transport.baseURL, 250)
+    try {
+      const result = observed.model.ask('Local transport fixture only', {
+        action: 'local-active-response', ref: observed.ref,
+        filter: async text => { observed.accepted.push(text); return text },
+      })
+      // Attach the failure observer before driving the response, including when this regresses.
+      const completed = result.then(value => ({ value, error: undefined }), (error: unknown) => ({ value: undefined, error }))
+      await bounded(transport.request)
+      const startedAt = performance.now()
+      for (const text of ['Long ', 'active ', 'stream ', 'is ', 'valid.']) {
+        transport.delta(text)
+        await new Promise<void>(resolve => setTimeout(resolve, 85))
+      }
+      transport.complete()
+      const outcome = await bounded(completed)
+
+      expect(outcome.error).toBeUndefined()
+      expect(outcome.value).toBe('Long active stream is valid.')
+      expect(performance.now() - startedAt).toBeGreaterThan(250)
+      expect(observed.tokens.join('')).toBe('Long active stream is valid.')
+      expect(observed.accepted).toEqual(['Long active stream is valid.'])
+      expect(observed.traces).toHaveLength(1)
+      expect(observed.ref.value).toBeDefined()
+      expect(observed.ref.spectatorEntry?.id).toBe('local-trace')
+      expect(transport.requests()).toBe(1)
+    } finally {
+      await transport.stop()
+    }
+  })
+})