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-pi-ai/README.md

@@ -25,6 +25,10 @@ Same shape as llm-deepseek (one-line swap in cordis.yml), with pi-ai's thinking-
     reasoning: high   # off | high | xhigh (xhigh → wire 'max')
 ```
 
+## App attribution
+
+Every request carries the shared attribution header from dsh-llm's `attributionHeaders()`, passed through pi-ai's `headers` stream option (pi-ai merges caller headers last, so it always reaches the wire - the unit suite asserts arrival on the mock server, same as llm-deepseek). OpenRouter-specific app attribution headers are intentionally not sent by this adapter contract; they are deferred to a future explicit OpenRouter adapter or mode. See [dsh-llm § App attribution](../llm/README.md#app-attribution-attributionts).
+
 ## Dependency weight
 
 pi-ai declares the openai/anthropic/google/mistral/AWS SDKs as install-time dependencies. They are lazy-loaded — only the openai SDK actually loads for this adapter — but they do land in `node_modules`. Accepted for a package whose purpose is design verification.

packages/llm/llm-pi-ai/package.json

@@ -5,17 +5,19 @@
   "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",

packages/llm/llm-pi-ai/src/adapter.ts

@@ -13,7 +13,8 @@
 
 import { stream as piStream } from '@earendil-works/pi-ai'
 import type { Model } from '@earendil-works/pi-ai'
-import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
+import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
+import { CallId } from '@deepseek-ai/dsh-llm'
 import type { GenerateOptions, StreamChunk, ToolSchema } from '@deepseek-ai/dsh-llm'
 import { toPiContext, toStreamChunks } from './convert.ts'
 
@@ -69,8 +70,8 @@ type Payload = {
   stop?: unknown
 }
 
-function rawToolArguments(options: GenerateOptions): Map<string, string> {
-  const raw = new Map<string, string>()
+function rawToolArguments(options: GenerateOptions): Map<CallId, string> {
+  const raw = new Map<CallId, string>()
   for (const message of options.messages) {
     if (message.role !== 'assistant') continue
     for (const block of message.content) {
@@ -116,7 +117,7 @@ function patchPayload(payload: unknown, options: GenerateOptions, reasoning: PiA
     for (const call of message.tool_calls ?? []) {
       /* v8 ignore next -- malformed pi-ai payload guard: real tool calls always carry a string id */
       if (typeof call.id !== 'string') continue
-      const raw = rawById.get(call.id)
+      const raw = rawById.get(CallId(call.id))
       /* v8 ignore next -- pi-ai always emits a function object for assistant tool_calls; guard malformed payloads defensively */
       if (raw !== undefined && call.function !== undefined) call.function.arguments = raw
     }
@@ -170,6 +171,9 @@ export class PiAiAdapter extends LlmAdapter {
     try {
       const events = piStream(model, toPiContext(options), {
         apiKey: this.options.apiKey,
+        // pi-ai merges caller headers last over its provider defaults, so the
+        // harness attribution always reaches the wire.
+        headers: attributionHeaders(),
         ...options.temperature !== undefined ? { temperature: options.temperature } : {},
         ...options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {},
         signal: controller.signal,

packages/llm/llm-pi-ai/src/convert.ts

@@ -57,7 +57,7 @@ function parseArguments(raw: string): Record<string, unknown> {
  * same id.
  */
 export function toPiContext(options: GenerateOptions): PiContext {
-  const toolNames = new Map<string, string>()
+  const toolNames = new Map<CallId, string>()
   const messages: PiMessage[] = []
 
   for (const message of options.messages) {

packages/llm/llm-pi-ai/tests/adapter.e2e.ts

@@ -1,10 +1,11 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId } from '@deepseek-ai/dsh-llm'
-import type { GenerateResult, Message, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
 import type { Config } from '@deepseek-ai/dsh-llm-pi-ai'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import { assemble, type AssembledResult } from './assemble.ts'
 
 /**
  * Real-API e2e for the pi-ai-backed adapter: V4 Flash + V4 Pro across all
@@ -33,14 +34,14 @@ function ask(text: string): Message[] {
   return [{ role: 'user', content: [{ type: 'text', text }] }]
 }
 
-function textOf(result: GenerateResult): string {
+function textOf(result: AssembledResult): string {
   return result.message.content
     .filter(block => block.type === 'text')
     .map(block => block.text)
     .join('')
 }
 
-function blockKinds(result: GenerateResult): string[] {
+function blockKinds(result: AssembledResult): string[] {
   return result.message.content.map(block => block.type)
 }
 
@@ -57,7 +58,7 @@ const weatherTool: ToolSchema = {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () => {
   it.each([FLASH, PRO])('%s + reasoning off: plain text generation', async (model) => {
     const ctx = await harness(model, { reasoning: 'off' })
-    const result = await ctx.llm.generate({
+    const result = await assemble(ctx,{
       model,
       messages: ask('Reply with exactly the word: pong'),
       maxTokens: 50,
@@ -69,7 +70,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
 
   it.each([FLASH, PRO])('%s + reasoning high: reasoning blocks present', async (model) => {
     const ctx = await harness(model, { reasoning: 'high' })
-    const result = await ctx.llm.generate({
+    const result = await assemble(ctx,{
       model,
       messages: ask('Which is larger, 9.11 or 9.8? Answer with just the number.'),
       maxTokens: 2000,
@@ -82,7 +83,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
   it('pro + reasoning xhigh (wire max): tool-call round trip', async () => {
     const ctx = await harness(PRO, { reasoning: 'xhigh' })
 
-    const first = await ctx.llm.generate({
+    const first = await assemble(ctx,{
       model: PRO,
       messages: ask('What is the weather in Paris right now? Use the get_weather tool.'),
       tools: [weatherTool],
@@ -94,7 +95,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
     expect(call!.name).toBe('get_weather')
     expect(JSON.parse(call!.arguments)).toMatchObject({ city: expect.stringMatching(/paris/i) as string })
 
-    const second = await ctx.llm.generate({
+    const second = await assemble(ctx,{
       model: PRO,
       messages: [
         ...ask('What is the weather in Paris right now? Use the get_weather tool.'),
@@ -128,8 +129,8 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () =>
 
     const prompt = ask('Reply with exactly the word: pong')
     const [fromDeepSeek, fromPiAi] = await Promise.all([
-      deepseekCtx.llm.generate({ model: FLASH, messages: prompt, maxTokens: 50 }),
-      piCtx.llm.generate({ model: FLASH, messages: prompt, maxTokens: 50 }),
+      assemble(deepseekCtx, { model: FLASH, messages: prompt, maxTokens: 50 }),
+      assemble(piCtx, { model: FLASH, messages: prompt, maxTokens: 50 }),
     ])
     expect(blockKinds(fromPiAi)).toEqual(blockKinds(fromDeepSeek))
     expect(fromPiAi.finish.kind).toBe(fromDeepSeek.finish.kind)

packages/llm/llm-pi-ai/tests/adapter.spec.ts

@@ -2,14 +2,17 @@ import { createServer } from 'node:http'
 import type { IncomingMessage, Server, ServerResponse } from 'node:http'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import LlmService, { CallId, LlmError } from '@deepseek-ai/dsh-llm'
+import LlmService, { CallId, LlmError, userAgent } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
 import { buildModel, PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
+import { assemble } from './assemble.ts'
 
 /** Scripted SSE responses, one per request (OpenAI chat-completions shape). */
 interface MockServer {
   url: string
   requests: unknown[]
+  /** Header bags of received requests, in order (parallel to `requests`). */
+  headers: IncomingMessage['headers'][]
   close(): Promise<void>
 }
 
@@ -21,11 +24,13 @@ afterEach(async () => {
 
 async function mockServer(script: { status?: number; events?: string[]; body?: string }[]): Promise<MockServer> {
   const requests: unknown[] = []
+  const headers: IncomingMessage['headers'][] = []
   const server = createServer((request: IncomingMessage, response: ServerResponse) => {
     let body = ''
     request.on('data', (chunk: Buffer) => { body += chunk.toString('utf8') })
     request.on('end', () => {
       requests.push(JSON.parse(body))
+      headers.push(request.headers)
       const behavior = script.shift() ?? { status: 500, body: 'script exhausted' }
       if (behavior.status !== undefined && behavior.status !== 200) {
         response.writeHead(behavior.status, { 'content-type': 'application/json' })
@@ -44,6 +49,7 @@ async function mockServer(script: { status?: number; events?: string[]; body?: s
   return {
     url: `http://127.0.0.1:${address.port}`,
     requests,
+    headers,
     close: () => new Promise(resolve => server.close(() => { resolve() })),
   }
 }
@@ -79,24 +85,32 @@ async function harness(baseURL: string, config: object = {}) {
 }
 
 describe('PiAiAdapter against a mock server', () => {
-  it('streams a text generation through ctx.llm.generate', async () => {
+  it('streams a text generation through the assembler', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
 
-    const result = await ctx.llm.generate({
+    const result = await assemble(ctx, {
       model: 'deepseek-v4-flash',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
     })
     expect(result.message.content).toEqual([{ type: 'text', text: 'hello' }])
     expect(result.finish).toEqual({ kind: 'stop' })
     expect(result.usage).toMatchObject({ inputTokens: 3, outputTokens: 1 })
+
+    // Attribution reaches the wire through pi-ai's headers hook: the exact
+    // shared User-Agent, and no provider-specific headers without an
+    // explicitly configured target.
+    expect(server.headers[0]?.['user-agent']).toBe(userAgent())
+    expect(server.headers[0]).not.toHaveProperty('http-referer')
+    expect(server.headers[0]).not.toHaveProperty('x-openrouter-title')
+    expect(server.headers[0]).not.toHaveProperty('x-openrouter-categories')
   })
 
   it('streams tool calls with re-stringified arguments', async () => {
     const server = await mockServer([{ events: toolEvents }])
     const ctx = await harness(server.url)
 
-    const result = await ctx.llm.generate({
+    const result = await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'weather?' }] }],
       tools: [{
@@ -114,7 +128,7 @@ describe('PiAiAdapter against a mock server', () => {
     const server = await mockServer([{ events: thinkingEvents }])
     const ctx = await harness(server.url, { reasoning: 'high' })
 
-    const result = await ctx.llm.generate({
+    const result = await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [{ role: 'user', content: [{ type: 'text', text: 'think' }] }],
     })
@@ -127,7 +141,7 @@ describe('PiAiAdapter against a mock server', () => {
   it('sends DeepSeek thinking fields when reasoning is configured', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url, { reasoning: 'xhigh' })
-    await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [] })
+    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(server.requests[0]).toMatchObject({
       thinking: { type: 'enabled' },
       reasoning_effort: 'max', // xhigh maps to max via thinkingLevelMap
@@ -137,21 +151,21 @@ describe('PiAiAdapter against a mock server', () => {
   it('disables thinking for reasoning: off', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url, { reasoning: 'off' })
-    await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [] })
+    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(server.requests[0]).toMatchObject({ thinking: { type: 'disabled' } })
   })
 
   it('injects stop sequences through onPayload', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
-    await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [], stop: ['END'] })
+    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [], stop: ['END'] })
     expect(server.requests[0]).toMatchObject({ stop: ['END'] })
   })
 
   it('preserves per-tool strict exactly through onPayload', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
-    await ctx.llm.generate({
+    await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [],
       tools: [
@@ -173,7 +187,7 @@ describe('PiAiAdapter against a mock server', () => {
   it('preserves raw replayed tool-call arguments in the provider payload', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
-    await ctx.llm.generate({
+    await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [{
         role: 'assistant',
@@ -192,7 +206,7 @@ describe('PiAiAdapter against a mock server', () => {
       body: JSON.stringify({ error: { message: 'bad key' } }),
     }])
     const ctx = await harness(server.url)
-    const result = await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [] })
+    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(result.finish).toMatchObject({ kind: 'error', code: 'AUTH' })
     expect((result.finish as { message: string }).message).toMatch(/bad key|401/)
   })
@@ -204,13 +218,13 @@ describe('PiAiAdapter against a mock server', () => {
   ] as const)('maps HTTP %s to stable error code %s', async (status, code) => {
     const server = await mockServer([{ status, body: JSON.stringify({ error: { message: `provider ${status}` } }) }])
     const ctx = await harness(server.url)
-    const result = await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [] })
+    const result = await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     expect(result.finish).toMatchObject({ kind: 'error', code })
   })
 
   it('rejects prefill with UNSUPPORTED', async () => {
     const ctx = await harness('http://127.0.0.1:1')
-    await expect(ctx.llm.generate({
+    await expect(assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [],
       prefill: [{ type: 'text', text: 'Sure' }],
@@ -244,7 +258,7 @@ describe('option spreads and env fallbacks', () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
     const controller = new AbortController()
-    await ctx.llm.generate({
+    await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [],
       temperature: 0.5,
@@ -262,7 +276,7 @@ describe('option spreads and env fallbacks', () => {
       const ctx = new Context()
       await ctx.plugin(LlmService)
       await ctx.plugin(LlmPiAi, { models: ['deepseek-v4-flash'] })
-      await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [] })
+      await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
       expect(server.requests).toHaveLength(1)
     } finally {
       vi.unstubAllEnvs()
@@ -311,7 +325,7 @@ describe('review fixes', () => {
   it('defaults omitted reasoning config to thinking ENABLED (provider default)', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url) // no reasoning key at all
-    await ctx.llm.generate({ model: 'deepseek-v4-flash', messages: [] })
+    await assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
     const request = server.requests[0] as Record<string, unknown>
     expect(request.thinking).toEqual({ type: 'enabled' })
     expect('reasoning_effort' in request).toBe(false)
@@ -320,7 +334,7 @@ describe('review fixes', () => {
   it('replays reasoning_content on assistant tool-call turns (passback rule)', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
-    await ctx.llm.generate({
+    await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [
         { role: 'user', content: [{ type: 'text', text: 'weather?' }] },
@@ -376,7 +390,7 @@ describe('review fixes: abort wiring', () => {
     const controller = new AbortController()
     controller.abort('already cancelled')
     // pi-ai surfaces the abort as an in-stream error event → aborted finish.
-    const result = await ctx.llm.generate({
+    const result = await assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [],
       signal: controller.signal,
@@ -388,7 +402,7 @@ describe('review fixes: abort wiring', () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
     const controller = new AbortController()
-    const pending = ctx.llm.generate({
+    const pending = assemble(ctx,{
       model: 'deepseek-v4-flash',
       messages: [],
       signal: controller.signal,

packages/llm/llm-pi-ai/tests/assemble.ts

@@ -0,0 +1,26 @@
+/**
+ * Test helper: drive `ctx.llm.stream()` through a `BlockAssembler` and return
+ * the assembled message + usage + finish reason. This exercises the same
+ * streaming path production uses (the loop), rather than a service-level
+ * one-shot convenience method.
+ */
+
+import { BlockAssembler } from '@deepseek-ai/dsh-llm'
+import type { Context } from 'cordis'
+import type { FinishReason, GenerateOptions, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+
+export interface AssembledResult {
+  message: Message
+  usage?: TokenUsage
+  finish: FinishReason
+}
+
+export async function assemble(ctx: Context, options: GenerateOptions): Promise<AssembledResult> {
+  const assembler = new BlockAssembler()
+  for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
+  return {
+    message: assembler.message(),
+    ...assembler.usage !== undefined ? { usage: assembler.usage } : {},
+    finish: assembler.finish,
+  }
+}

packages/llm/llm-pi-ai/tsconfig.json

@@ -2,7 +2,7 @@
   "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib"
+    "outDir": "lib/types"
   },
   "include": [
     "src"