Merge remote app attribution branch

Resolve the RFC and implementation to defer OpenRouter-specific attribution headers and keep mandatory attribution to User-Agent only.

packages/llm/llm/README.md

@@ -4,28 +4,24 @@ Provider-neutral LLM vocabulary and abstract service. This package defines the c
 
 ## Service: `LlmService` (ctx key: `llm`)
 
-An adapter registry plus streaming / non-streaming call surfaces. Both call surfaces are interceptable via waterfall events.
+An adapter registry plus a single streaming call surface, interceptable via a waterfall event.
 
 ### Public API
 
 - `ctx.llm.registerAdapter(models: string[], adapter: LlmAdapter): () => void` Register an adapter for the given model names. Disposed with the calling fiber.
 - `ctx.llm.models(): string[]` — model names with a registered adapter.
-- `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas).
-- `ctx.llm.streamBlocks(options: GenerateOptions): AsyncIterable<ContentBlock>` Stream as completed content blocks (convenience view).
-- `ctx.llm.generate(options: GenerateOptions): Promise<GenerateResult>` One model call, fully assembled.
+- `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
 ### Events
 
 | Event | Mode | Purpose |
 |---|---|---|
 | `llm/stream` | waterfall | Intercept/wrap every streaming model call (retry, caching, routing) |
-| `llm/generate` | waterfall | Intercept/wrap every non-streaming model call |
-| `llm/adapter-change` | emit | An adapter was registered or unregistered |
 
 ### Extension points
 
 - Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(models, adapter)` to add a new model provider.
-- Wrap `llm/stream` or `llm/generate` via `ctx.on()` waterfall listeners for caching, retry, logging, rate-limiting, etc.
+- Wrap `llm/stream` via `ctx.on()` waterfall listeners for caching, retry, logging, rate-limiting, etc.
 
 ### Content-block vocabulary (`types.ts`)
 
@@ -33,11 +29,14 @@ Messages are arrays of typed content blocks: `text`, `reasoning`, `tool-call`, `
 
 Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages.
 
+### App attribution (`attribution.ts`)
+
+Every product adapter must identify the application on every provider HTTP request - attribution is part of the adapter contract, not an adapter-local nicety. `attributionHeaders(identity?)` builds the standard `User-Agent` header (`product/version (+url)`, from `userAgent()`) for every request. The default `APP_IDENTITY` carries only static public product facts (its version is read from this package's manifest); a white-label deployment passes its own `AppIdentity`, and omission falls back to the default - nothing can suppress attribution. OpenRouter-specific app attribution headers are intentionally not supported by this contract. An adapter proves compliance with a wire-level test: a mock server asserting the received header (or, for a library-backed adapter, that the library's header hook delivers the same value). Policy and rationale: [Mandatory `User-Agent` attribution](../../../docs/rfc/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md).
+
 ### Classes
 
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
-- `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. Used by the agent loop (raw chunks for replay
-  + assembled for history) and by `streamBlocks()`/`generate()`.
+- `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
 - `LlmError` — extends `HarnessError`; `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) plus an optional numeric `status` when the failure came from a non-2xx provider response.
 

packages/llm/llm/package.json

@@ -5,24 +5,28 @@
   "private": true,
   "type": "module",
   "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "types": "lib/types/index.d.ts",
   "exports": {
     ".": {
-      "types": "./lib/index.d.ts",
+      "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
-    "lib",
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
     "src"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }

packages/llm/llm/src/assembler.ts

@@ -1,13 +1,14 @@
 /**
  * Incremental chunk-to-message assembler. This is the single canonical assembly
- * algorithm used by both the agent loop and the LLM service convenience views.
+ * algorithm used by the agent loop to build an assistant message from a chunk
+ * stream while logging the raw chunks for replay fidelity.
  *
  * @module @deepseek-ai/dsh-llm/assembler
  */
 
 import { CallId } from './brand.ts'
 import { assertNever } from './never.ts'
-import type { ContentBlock, FinishReason, GenerateResult, Message, StreamChunk, TokenUsage } from './types.ts'
+import type { ContentBlock, FinishReason, Message, StreamChunk, TokenUsage } from './types.ts'
 
 interface PartialBlock {
   blockType: string
@@ -23,9 +24,8 @@ interface PartialBlock {
  * Incrementally assembles raw {@link StreamChunk}s into complete
  * {@link ContentBlock}s and a final assistant {@link Message}.
  *
- * This is the single shared assembly implementation: the agent loop feeds it
- * while logging raw chunks for replay fidelity, and `LlmService.generate()` /
- * `streamBlocks()` use it to offer assembled views of the same stream.
+ * The agent loop feeds it while logging raw chunks for replay fidelity, then
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
  *
  * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
  * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -34,7 +34,6 @@ interface PartialBlock {
 export class BlockAssembler {
   private partials = new Map<number, PartialBlock>()
   private order: number[] = []
-  private flushed = 0
   private _usage: TokenUsage | undefined
   private _finish: FinishReason | undefined
 
@@ -129,44 +128,6 @@ export class BlockAssembler {
     return this.order.map(index => this.assemble(this.mustGet(index), index))
   }
 
-  /**
-   * Streaming flush: returns (once) every block that is complete AND has no
-   * incomplete block before it in stream order. Call after each `push()`;
-   * blocks come out strictly in stream order, so a streaming consumer sees
-   * exactly the sequence `blocks()` would produce.
-   */
-  flushReady(): ContentBlock[] {
-    const ready: ContentBlock[] = []
-    while (this.flushed < this.order.length) {
-      const index = this.order[this.flushed]
-      /* v8 ignore next 3 -- noUncheckedIndexedAccess guard: loop condition guarantees index exists in a non-empty array */
-      if (index === undefined) break
-      const partial = this.mustGet(index)
-      if (!partial.block) break
-      ready.push(partial.block)
-      this.flushed += 1
-    }
-    return ready
-  }
-
-  /**
-   * End-of-stream flush: returns (once) all not-yet-flushed blocks, in stream
-   * order, assembling still-open ones from their deltas (delta-only
-   * protocols). After this, `flushReady()` + `flushRemaining()` together have
-   * yielded exactly `blocks()`.
-   */
-  flushRemaining(): ContentBlock[] {
-    const remaining: ContentBlock[] = []
-    while (this.flushed < this.order.length) {
-      const index = this.order[this.flushed]
-      /* v8 ignore next 3 -- noUncheckedIndexedAccess guard: loop condition guarantees index exists */
-      if (index === undefined) break
-      remaining.push(this.assemble(this.mustGet(index), index))
-      this.flushed += 1
-    }
-    return remaining
-  }
-
   get usage(): TokenUsage | undefined {
     return this._usage
   }
@@ -179,13 +140,4 @@ export class BlockAssembler {
   message(): Message {
     return { role: 'assistant', content: this.blocks() }
   }
-
-  /** The assembled non-streaming result. */
-  result(): GenerateResult {
-    return {
-      message: this.message(),
-      ...this._usage !== undefined ? { usage: this._usage } : {},
-      finish: this.finish,
-    }
-  }
 }

packages/llm/llm/src/attribution.ts

@@ -0,0 +1,71 @@
+/**
+ * App-attribution vocabulary for provider requests.
+ *
+ * Every product LLM adapter must identify the application on every provider
+ * HTTP request (see the adapter contract on {@link ../index.ts LlmAdapter}):
+ * a static, non-secret product identity, sent as the standard `User-Agent`.
+ * Adapters obtain the headers from {@link attributionHeaders} instead of
+ * hand-copying constants, so the identity cannot drift between
+ * implementations. The policy and its rationale are pinned in
+ * docs/rfc/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md.
+ *
+ * @module @deepseek-ai/dsh-llm/attribution
+ */
+
+import { createRequire } from 'node:module'
+
+// The package's own manifest is the single source of the version so the
+// User-Agent cannot drift from what is published (`./package.json` is an
+// export of this package; the relative path resolves from both `src/` and
+// the bundled `lib/`).
+const { version } = createRequire(import.meta.url)('../package.json') as { version: string }
+
+/**
+ * Static public application identity sent to LLM providers.
+ *
+ * Every field is a public product fact, safe on every request: no secrets,
+ * local paths, session ids, prompt text, or per-user identifiers belong here,
+ * and nothing per-request may influence the values.
+ */
+export interface AppIdentity {
+  /** `User-Agent` product token (lowercase, hyphenated). */
+  product: string
+  /** Product version; sourced from package metadata, never hand-copied. */
+  version: string
+  /** Public home URL of the app, used as the `User-Agent` comment. */
+  url: string
+}
+
+/**
+ * The harness's own identity: the default every adapter sends. Deployments
+ * that need a white-label identity pass their own {@link AppIdentity} to
+ * {@link attributionHeaders} — omission falls back to this default; nothing
+ * can suppress attribution entirely.
+ */
+export const APP_IDENTITY: AppIdentity = {
+  product: 'deepseek-harness',
+  version,
+  // FIXME: create the public deepseek-ai/deepseek-harness-sdk repository this
+  // URL promises before the first release ships attribution pointing at it.
+  url: 'https://github.com/deepseek-ai/deepseek-harness-sdk',
+}
+
+/**
+ * The standard `User-Agent` value: `product/version (+url)`. The
+ * parenthesized `+url` comment is the conventional self-identification form
+ * (RFC 9110 §10.1.5 product + comment syntax).
+ */
+export function userAgent(identity: AppIdentity = APP_IDENTITY): string {
+  return `${identity.product}/${identity.version} (+${identity.url})`
+}
+
+/**
+ * Build the attribution headers an adapter must send on every provider
+ * request. Header names are lowercase (HTTP field names are case-insensitive
+ * on the wire).
+ */
+export function attributionHeaders(
+  identity: AppIdentity = APP_IDENTITY,
+): Record<string, string> {
+  return { 'user-agent': userAgent(identity) }
+}

packages/llm/llm/src/brand.ts

@@ -1,24 +1,15 @@
 /**
- * Branded (nominal) ID types.
+ * dsh-llm's owned branded id: `CallId` (tool-call correlation).
  *
- * A brand makes structurally-identical strings non-interchangeable at the
- * type level: an `AgentId` cannot be passed where a `CallId` is expected,
- * even though both are strings at runtime. Construction goes through the
- * per-type factory (a plain cast inside — zero runtime cost); comparison,
- * logging, and serialization all behave as ordinary strings.
- *
- * Policy: core packages brand the IDs they own — `CallId` here (tool-call
- * correlation), `SessionId` in dsh-session, `AgentId` in dsh-agent. Branding
- * is for IDs that cross package boundaries and could plausibly be confused;
- * not every string needs a brand.
+ * The `Branded<B>` primitive itself lives in `@deepseek-ai/dsh-brand` (a
+ * zero-dependency type-only package) so every owner of a cross-boundary id can
+ * brand it without depending on dsh-llm; see that package's README for the
+ * nominal-typing policy.
  *
  * @module @deepseek-ai/dsh-llm/brand
  */
 
-declare const BRAND: unique symbol
-
-/** A string carrying a compile-time-only brand `B`. */
-export type Branded<B extends string> = string & { readonly [BRAND]: B }
+import type { Branded } from '@deepseek-ai/dsh-brand'
 
 /**
  * Correlates a model-issued tool call with its result. Provider-issued for

packages/llm/llm/src/index.ts

@@ -1,16 +1,16 @@
 /**
- * LLM service: adapter registry with waterfall-interceptable streaming and
- * non-streaming call surfaces. Exports the `LlmService` default, the abstract
- * `LlmAdapter` for provider backends, and `BlockAssembler` for chunk assembly.
+ * LLM service: adapter registry with a waterfall-interceptable streaming call
+ * surface. Exports the `LlmService` default, the abstract `LlmAdapter` for
+ * provider backends, and `BlockAssembler` for chunk assembly.
  *
  * @module @deepseek-ai/dsh-llm
  */
 
 import { Context, Service } from 'cordis'
-import type { ContentBlock, GenerateOptions, GenerateResult, StreamChunk } from './types.ts'
-import { BlockAssembler } from './assembler.ts'
+import type { GenerateOptions, StreamChunk } from './types.ts'
 import { HarnessError } from './error.ts'
 
+export * from './attribution.ts'
 export * from './brand.ts'
 export * from './never.ts'
 export * from './error.ts'
@@ -30,17 +30,6 @@ declare module 'cordis' {
      * @mode waterfall
      */
     'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
-    /**
-     * Waterfall around every non-streaming model call. Bound to the
-     * {@link LlmService}; call `next()` to delegate to the adapter.
-     * @mode waterfall
-     */
-    'llm/generate'(this: LlmService, options: GenerateOptions, next: () => Promise<GenerateResult>): Promise<GenerateResult>
-    /**
-     * An adapter was registered or unregistered (the model→adapter map changed).
-     * @mode emit
-     */
-    'llm/adapter-change'(): void
   }
 }
 
@@ -68,6 +57,13 @@ export class LlmError extends HarnessError {
  * fetch/SSE) and `@deepseek-ai/dsh-llm-pi-ai` (pi-ai-backed) — two
  * deliberately different internals over the same contract; see the
  * adapter contract documented on `StreamChunk` in `./types.ts`.
+ *
+ * App attribution is part of the adapter contract: every HTTP request to a
+ * provider carries the headers from `attributionHeaders()` (`./attribution.ts`)
+ * — the standard `User-Agent` baseline everywhere. An adapter proves it with
+ * a wire-level test (a mock server asserting the received header), or, for a
+ * library-backed adapter, by asserting the library's header hook delivers the
+ * same value to the wire.
  */
 export abstract class LlmAdapter {
   /** Stream one model call as raw chunks. The only required method. */
@@ -75,8 +71,8 @@ export abstract class LlmAdapter {
 }
 
 /**
- * The abstract `llm` service: an adapter registry plus streaming /
- * non-streaming call surfaces, both interceptable via waterfall events.
+ * The abstract `llm` service: an adapter registry plus a streaming model-call
+ * surface, interceptable via the `llm/stream` waterfall.
  */
 export class LlmService extends Service {
   private adapters = new Map<string, LlmAdapter>()
@@ -88,8 +84,7 @@ export class LlmService extends Service {
   /**
    * Register an adapter for the given model names. Throws `LlmError` with code
    * `DUPLICATE_ADAPTER` if any model already has an adapter (all-or-nothing).
-   * Emits `llm/adapter-change` on registration and disposal. Disposed with the
-   * fiber.
+   * Disposed with the fiber.
    */
   registerAdapter(models: string[], adapter: LlmAdapter): () => void {
     const dispose = this.ctx.effect(function* (this: LlmService) {
@@ -99,17 +94,9 @@ export class LlmService extends Service {
         }
       }
       for (const model of models) this.adapters.set(model, adapter)
-      // Yield the rollback BEFORE emitting the change event: a generator effect
-      // collects each yielded disposer before running the next step, so a
-      // throwing `llm/adapter-change` listener rolls the mutation back instead
-      // of leaking the entry (which would wedge the duplicate check until
-      // restart). The duplicate throws above fire before any mutation, so they
-      // correctly leak nothing.
       yield () => {
         for (const model of models) this.adapters.delete(model)
-        this.ctx.emit('llm/adapter-change')
       }
-      this.ctx.emit('llm/adapter-change')
     }.bind(this), 'llm.registerAdapter()')
     // ctx.effect's disposer returns Promise<void>; our disposer API is
     // synchronous fire-and-forget — discard the (always-resolved) promise.
@@ -137,36 +124,6 @@ export class LlmService extends Service {
       return this.adapter(options.model).stream(options)
     })
   }
-
-  /**
-   * Stream one model call as completed content blocks — a convenience view
-   * for consumers that don't care about token-level deltas. Blocks are
-   * yielded strictly in stream order as soon as they (and everything before
-   * them) complete; blocks left open at end of stream (delta-only protocols)
-   * are assembled and flushed last, so the sequence always equals
-   * `generate()`'s `message.content`.
-   */
-  async * streamBlocks(options: GenerateOptions): AsyncIterable<ContentBlock> {
-    const assembler = new BlockAssembler()
-    for await (const chunk of this.stream(options)) {
-      assembler.push(chunk)
-      yield * assembler.flushReady()
-    }
-    yield * assembler.flushRemaining()
-  }
-
-  /**
-   * One model call, fully assembled (drains the chunk stream). Dispatches
-   * through the `llm/generate` waterfall (and the inner stream through
-   * `llm/stream`). Same completion guarantees as `streamBlocks()`.
-   */
-  generate(options: GenerateOptions): Promise<GenerateResult> {
-    return this.ctx.waterfall(this, 'llm/generate', options, async () => {
-      const assembler = new BlockAssembler()
-      for await (const chunk of this.stream(options)) assembler.push(chunk)
-      return assembler.result()
-    })
-  }
 }
 
 export default LlmService

packages/llm/llm/src/types.ts

@@ -19,6 +19,7 @@
  * ```
  */
 
+import type { Branded } from '@deepseek-ai/dsh-brand'
 import type { CallId } from './brand.ts'
 
 /** Cache hint attached to a content block (provider-interpreted). */
@@ -192,11 +193,18 @@ export interface GenerateOptions {
    */
   stop?: string[]
   signal?: AbortSignal
-}
-
-/** Non-streaming result, assembled from the chunk stream. */
-export interface GenerateResult {
-  message: Message
-  usage?: TokenUsage
-  finish: FinishReason
+  /**
+   * The id of the session this request belongs to — stamped by the agent loop
+   * from `agent.session.id`. Adapters ignore it; it lets an `llm/stream` listener
+   * route a call by WHICH session issued it (the replay adapter keys its per-call
+   * cursor by session, so a parent and its in-process subagent — each with its
+   * own session on one context — replay from their own recorded scripts).
+   *
+   * Typed as `Branded<'SessionId'>` rather than importing `SessionId` from
+   * `dsh-session`: that package imports `Message` from here, so importing its
+   * `SessionId` back would cycle. `SessionId` IS `Branded<'SessionId'>`, so a
+   * real session id assigns with no cast. (A future ids package could own the
+   * brand and dissolve this note.)
+   */
+  sessionId?: Branded<'SessionId'>
 }

packages/llm/llm/tests/assembler.spec.ts

@@ -81,36 +81,6 @@ describe('BlockAssembler', () => {
     expect(() => assembler.blocks()).toThrow('BlockAssembler invariant violated')
   })
 
-  it('assembles open blocks at end of stream via flushRemaining', () => {
-    const assembler = new BlockAssembler()
-    assembler.push({ type: 'text-delta', index: 0, text: 'open' })
-    assembler.push({ type: 'reasoning-delta', index: 1, text: 'thinking' })
-
-    // flushReady returns nothing because index 0 is incomplete and blocking
-    const ready = assembler.flushReady()
-    expect(ready).toEqual([])
-
-    // flushRemaining assembles everything still open
-    const remaining = assembler.flushRemaining()
-    expect(remaining).toEqual([
-      { type: 'text', text: 'open' },
-      { type: 'reasoning', text: 'thinking' },
-    ])
-
-    // blocks() now matches the flushed view
-    expect(assembler.blocks()).toEqual(remaining)
-  })
-
-  it('result() omits usage key when no usage was received', () => {
-    const assembler = new BlockAssembler()
-    assembler.push({ type: 'text-delta', index: 0, text: 'msg' })
-    const result = assembler.result()
-    expect(result.message).toBeDefined()
-    expect(result.finish).toEqual({ kind: 'stop' })
-    // usage should NOT be present on the object at all
-    expect('usage' in result).toBe(false)
-  })
-
   it('ignores duplicate block-start for the same index', () => {
     const assembler = new BlockAssembler()
     assembler.push({ type: 'block-start', index: 0, blockType: 'text' })
@@ -142,13 +112,11 @@ describe('BlockAssembler', () => {
     ])
   })
 
-  it('includes usage in result() when usage was received', () => {
+  it('exposes usage via the getter when a usage chunk was received', () => {
     const assembler = new BlockAssembler()
     assembler.push({ type: 'text-delta', index: 0, text: 'msg' })
     assembler.push({ type: 'usage', usage: { inputTokens: 5, outputTokens: 3 } })
-    const result = assembler.result()
-    expect(result.usage).toEqual({ inputTokens: 5, outputTokens: 3 })
-    expect('usage' in result).toBe(true)
+    expect(assembler.usage).toEqual({ inputTokens: 5, outputTokens: 3 })
   })
 })
 
@@ -172,25 +140,25 @@ describe('BlockAssembler regressions (property-test findings)', () => {
     // Found by fast-check (the property-testing RFC): two block-ends at the same index made the
     // streamed prefix (first block) disagree with final blocks() (second
     // block). The first close must win — same straggler rule as post-close
-    // deltas — so streaming and one-shot assembly stay identical.
+    // deltas — so the prefix returned incrementally by push() and the final
+    // blocks() stay identical.
     const chunks: StreamChunk[] = [
       { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'first' } },
       { type: 'block-end', index: 0, block: { type: 'text', text: 'second' } },
     ]
     const streaming = new BlockAssembler()
-    const flushed = []
+    const closed = []
     for (const chunk of chunks) {
-      streaming.push(chunk)
-      flushed.push(...streaming.flushReady())
+      const block = streaming.push(chunk)
+      if (block) closed.push(block)
     }
-    flushed.push(...streaming.flushRemaining())
 
     const oneShot = new BlockAssembler()
     for (const chunk of chunks) oneShot.push(chunk)
 
-    expect(flushed).toEqual([{ type: 'reasoning', text: 'first' }])
+    expect(closed).toEqual([{ type: 'reasoning', text: 'first' }])
     expect(oneShot.blocks()).toEqual([{ type: 'reasoning', text: 'first' }])
-    expect(flushed).toEqual(oneShot.blocks())
+    expect(closed).toEqual(oneShot.blocks())
   })
 
   it('push returns undefined for a duplicate block-end (it closed nothing)', () => {

packages/llm/llm/tests/attribution.spec.ts

@@ -0,0 +1,51 @@
+import { createRequire } from 'node:module'
+import { describe, expect, it } from 'vitest'
+import { APP_IDENTITY, attributionHeaders, userAgent } from '@deepseek-ai/dsh-llm'
+import type { AppIdentity } from '@deepseek-ai/dsh-llm'
+
+const manifest = createRequire(import.meta.url)('../package.json') as { version: string }
+
+/** A white-label identity exercising every override seam. */
+const forkIdentity: AppIdentity = {
+  product: 'fork-agent',
+  version: '9.9.9',
+  url: 'https://example.com/fork-agent',
+}
+
+describe('APP_IDENTITY', () => {
+  it('sources the version from the package manifest, never a hand-copied constant', () => {
+    expect(APP_IDENTITY.version).toBe(manifest.version)
+  })
+
+  it('carries only static public product facts', () => {
+    expect(APP_IDENTITY).toEqual({
+      product: 'deepseek-harness',
+      version: manifest.version,
+      url: 'https://github.com/deepseek-ai/deepseek-harness-sdk',
+    })
+  })
+})
+
+describe('userAgent', () => {
+  it('renders product/version with the +url comment', () => {
+    expect(userAgent()).toBe(
+      `deepseek-harness/${manifest.version} (+https://github.com/deepseek-ai/deepseek-harness-sdk)`,
+    )
+  })
+
+  it('renders a custom identity', () => {
+    expect(userAgent(forkIdentity)).toBe('fork-agent/9.9.9 (+https://example.com/fork-agent)')
+  })
+})
+
+describe('attributionHeaders', () => {
+  it('defaults to the provider-neutral baseline: User-Agent and nothing else', () => {
+    expect(attributionHeaders()).toEqual({ 'user-agent': userAgent() })
+  })
+
+  it('maps a custom identity onto the User-Agent header only', () => {
+    expect(attributionHeaders(forkIdentity)).toEqual({
+      'user-agent': 'fork-agent/9.9.9 (+https://example.com/fork-agent)',
+    })
+  })
+})

packages/llm/llm/tests/properties.spec.ts

@@ -4,13 +4,13 @@
  * The assembler is protocol-shaped: arbitrary interleavings of block-start,
  * deltas, block-end, usage, and finish — valid and malformed (duplicate
  * indices, stragglers after block-end, missing block-start, delta-only). The
- * invariants below are the contract the agent loop and LlmService rely on.
+ * invariants below are the contract the agent loop relies on.
  */
 
 import { describe, expect, it } from 'vitest'
 import fc from 'fast-check'
 import { BlockAssembler } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import { CallId } from '@deepseek-ai/dsh-llm'
 
 // A small pool of indices so collisions (duplicate-index bugs) are common.
@@ -55,38 +55,6 @@ function feed(chunks: StreamChunk[]): BlockAssembler {
 }
 
 describe('BlockAssembler properties', () => {
-  it('flushReady() ++ flushRemaining() === blocks(), in order', () => {
-    fc.assert(fc.property(streamArb, (chunks) => {
-      const streaming = new BlockAssembler()
-      const flushed: ContentBlock[] = []
-      for (const chunk of chunks) {
-        streaming.push(chunk)
-        flushed.push(...streaming.flushReady())
-      }
-      flushed.push(...streaming.flushRemaining())
-
-      const oneShot = feed(chunks).blocks()
-      expect(flushed).toEqual(oneShot)
-    }))
-  })
-
-  it('streamBlocks-style flush never yields a block before an earlier open one', () => {
-    // flushReady is strict-order: once it stops at an open index, no later
-    // index may be emitted until that one closes. We assert the flushed prefix
-    // is always a prefix of the final blocks() order.
-    fc.assert(fc.property(streamArb, (chunks) => {
-      const streaming = new BlockAssembler()
-      const flushed: ContentBlock[] = []
-      for (const chunk of chunks) {
-        streaming.push(chunk)
-        flushed.push(...streaming.flushReady())
-      }
-      const finalSoFar = streaming.blocks()
-      // Everything flushed mid-stream is a prefix of the full ordered blocks.
-      expect(finalSoFar.slice(0, flushed.length)).toEqual(flushed)
-    }))
-  })
-
   it('partials map size never exceeds the number of distinct indices seen', () => {
     fc.assert(fc.property(streamArb, (chunks) => {
       const distinct = new Set<number>()
@@ -131,20 +99,4 @@ describe('BlockAssembler properties', () => {
       }
     }))
   })
-
-  it('streaming and one-shot assembly agree on usage and finish', () => {
-    fc.assert(fc.property(streamArb, (chunks) => {
-      // Streaming consumer: push + flush as it goes.
-      const streaming = new BlockAssembler()
-      for (const chunk of chunks) {
-        streaming.push(chunk)
-        streaming.flushReady()
-      }
-      streaming.flushRemaining()
-      // One-shot consumer: push all, then read.
-      const oneShot = feed(chunks)
-      expect(streaming.usage).toEqual(oneShot.usage)
-      expect(streaming.finish).toEqual(oneShot.finish)
-    }))
-  })
 })

packages/llm/llm/tests/service.spec.ts

@@ -19,24 +19,22 @@ const SCRIPT: StreamChunk[] = [
 ]
 
 describe('LlmService', () => {
-  it('routes stream() to the registered adapter and generate() assembles it', async () => {
+  it('routes stream() to the registered adapter', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
     ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter(SCRIPT))
 
     const chunks: StreamChunk[] = []
     for await (const chunk of ctx.llm.stream({ model: 'test-model', messages: [] })) chunks.push(chunk)
-    expect(chunks).toHaveLength(3)
-
-    const result = await ctx.llm.generate({ model: 'test-model', messages: [] })
-    expect(result.message.content).toEqual([{ type: 'text', text: 'hi' }])
-    expect(result.finish).toEqual({ kind: 'stop' })
+    expect(chunks).toEqual(SCRIPT)
   })
 
   it('throws NO_ADAPTER for unregistered models', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
-    await expect(ctx.llm.generate({ model: 'nope', messages: [] })).rejects.toThrow('no adapter registered')
+    await expect((async () => {
+      for await (const _ of ctx.llm.stream({ model: 'nope', messages: [] })) { /* drain */ }
+    })()).rejects.toThrow('no adapter registered')
   })
 
   it('unregisters adapters when the owning fiber is disposed (HMR safety)', async () => {
@@ -71,21 +69,6 @@ describe('LlmService', () => {
     expect(chunks[0]).toMatchObject({ index: 99 })
   })
 
-  it('lets llm/generate waterfall listeners intercept and transform the result', async () => {
-    const ctx = new Context()
-    await ctx.plugin(LlmService)
-    ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter(SCRIPT))
-
-    ctx.on('llm/generate', async function (_options, next) {
-      const result = await next()
-      return { ...result, finish: { kind: 'max-tokens' } as const }
-    })
-
-    const result = await ctx.llm.generate({ model: 'test-model', messages: [] })
-    expect(result.finish).toEqual({ kind: 'max-tokens' })
-    expect(result.message.content).toEqual([{ type: 'text', text: 'hi' }])
-  })
-
   it('creates LlmError with a code for programmatic handling', () => {
     const err = new LlmError('something went wrong', 'CUSTOM_CODE')
     expect(err).toBeInstanceOf(Error)
@@ -116,20 +99,13 @@ describe('LlmService', () => {
     expect(isHarnessError('nope')).toBe(false)
   })
 
-  it('disposes adapter registration on adapter-change event emission', async () => {
+  it('removes the adapter when the returned disposer is called', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
 
-    const changes: string[][] = []
-    ctx.on('llm/adapter-change', () => {
-      changes.push([...ctx.llm.models()])
-    })
-
     const dispose = ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))
-    expect(changes).toEqual([['m1']])
-
+    expect(ctx.llm.models()).toEqual(['m1'])
     dispose()
-    expect(changes).toEqual([['m1'], []])
     expect(ctx.llm.models()).toEqual([])
   })
 
@@ -147,25 +123,19 @@ describe('LlmService', () => {
     }
   })
 
-  it('rolls back the adapter entry when an adapter-change listener throws (P1-1)', async () => {
+  it('re-registers a model after its prior registration is disposed', async () => {
     const ctx = new Context()
     await ctx.plugin(LlmService)
 
-    // A change listener that throws on the FIRST emit only.
-    let threw = false
-    ctx.on('llm/adapter-change', () => {
-      if (!threw) { threw = true; throw new Error('boom change listener') }
-    })
-
-    // The throwing emit must roll the mutation back, not leak it.
-    expect(() => ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))).toThrow('boom change listener')
-    expect(ctx.llm.models()).toEqual([]) // entry rolled back, not leaked
-
-    // A subsequent listener-free register of the SAME model succeeds and
-    // contributes exactly once (the duplicate check is not wedged).
     const dispose = ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))
     expect(ctx.llm.models()).toEqual(['m1'])
     dispose()
     expect(ctx.llm.models()).toEqual([])
+
+    // The duplicate check is not wedged: the same model registers cleanly again.
+    const disposeAgain = ctx.llm.registerAdapter(['m1'], new ScriptedAdapter(SCRIPT))
+    expect(ctx.llm.models()).toEqual(['m1'])
+    disposeAgain()
+    expect(ctx.llm.models()).toEqual([])
   })
 })

packages/llm/llm/tsconfig.json

@@ -2,7 +2,7 @@
   "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib/types"
   },
   "include": [
     "src"
@@ -13,6 +13,9 @@
     },
     {
       "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../util/brand"
     }
   ]
 }