docs: trim generated prose

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

@@ -1,13 +1,6 @@
 /**
- * `PiAiAdapter`: the `@earendil-works/pi-ai`-backed implementation of the
- * harness LLM seam, pointed at a DeepSeek (OpenAI-compatible) endpoint.
- *
- * This adapter exists as a design-verification twin of
- * `@deepseek-ai/dsh-llm-deepseek`: same models, same wire protocol,
- * completely different internals (a unified LLM library with its own event
- * vocabulary vs hand-rolled fetch/SSE). Anything the StreamChunk protocol
- * cannot express for BOTH implementations is a core-vocabulary bug.
- *
+ * `PiAiAdapter`: the `@earendil-works/pi-ai`-backed implementation of the harness LLM seam,
+ * pointed at a DeepSeek (OpenAI-compatible) endpoint.
  * @module dsh-llm-pi-ai/adapter
  */
 
@@ -44,11 +37,8 @@ export function buildModel(modelId: string, options: PiAiAdapterOptions): Model<
     api: 'openai-completions',
     provider: 'deepseek',
     baseUrl: options.baseURL,
-    // Always true: pi-ai only emits the DeepSeek `thinking` field for
-    // reasoning-capable models, deriving enabled/disabled from whether a
-    // reasoningEffort option is passed. DeepSeek's provider default is
-    // ENABLED, so 'off' must send an explicit {type: 'disabled'} — which
-    // requires this flag to stay on.
+    // Always true: pi-ai only emits the DeepSeek `thinking` field for reasoning-capable models,
+    // deriving enabled/disabled from whether a reasoningEffort option is passed.
     reasoning: true,
     // DeepSeek's official effort levels: high|max (xhigh maps to max).
     thinkingLevelMap: { minimal: null, low: null, medium: null, high: 'high', xhigh: 'max' },
@@ -153,10 +143,8 @@ export class PiAiAdapter extends LlmAdapter {
     // `reasoning_effort` so the provider chooses its default effort.
     const reasoning = this.options.reasoning ?? 'high'
 
-    // pi-ai's event stream has no iterator-return cancellation hook: if our
-    // consumer stops early (break / loop abort), the underlying HTTP stream
-    // would keep draining. Chain an internal controller onto the caller's
-    // signal and abort it when this generator exits for any reason.
+    // pi-ai's event stream has no iterator-return cancellation hook: if our consumer stops
+    // early (break / loop abort), the underlying HTTP stream would keep draining.
     const controller = new AbortController()
     const onCallerAbort = (): void => { controller.abort(options.signal?.reason) }
     if (options.signal?.aborted) controller.abort(options.signal.reason)

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

@@ -1,20 +1,7 @@
 /**
  * Bidirectional mapping between the harness vocabulary and pi-ai's:
- * `GenerateOptions`/`Message[]` → pi-ai `Context`, and pi-ai
- * `AssistantMessageEvent`s → harness `StreamChunk`s.
- *
- * Vocabulary differences worth knowing (they are exactly why this adapter
- * exists — an independent implementation stress-tests the StreamChunk
- * protocol):
- * - pi-ai tool-call `arguments` are PARSED OBJECTS; the harness keeps the
- *   raw JSON string. We parse on the way into pi-ai, patch provider payloads
- *   back to the original raw string in the adapter, and re-stringify on output.
- * - pi-ai reports errors as in-stream `error` events (it never throws
- *   mid-stream); the harness expresses those as `finish {kind:'error'}` /
- *   `{kind:'aborted'}` chunks.
- * - pi-ai folds reasoning tokens into `usage.output`; there is no separate
- *   reasoning count to map.
- *
+ * `GenerateOptions`/`Message[]` → pi-ai `Context`, and pi-ai `AssistantMessageEvent`s →
+ * harness `StreamChunk`s.
  * @module dsh-llm-pi-ai/convert
  */
 
@@ -78,11 +65,7 @@ export function toPiContext(options: GenerateOptions): PiContext {
             content.push({ type: 'text', text: block.text })
             break
           case 'reasoning':
-            // thinkingSignature names the wire field pi-ai replays the CoT
-            // under. Without it pi-ai falls back to reasoning_content: ""
-            // (its requiresReasoningContentOnAssistantMessages shim), which
-            // violates DeepSeek's thinking-mode passback rule on tool-call
-            // turns (guides/thinking_mode.mdx § Tool Calls).
+            // thinkingSignature names the wire field pi-ai replays the CoT under.
             content.push({ type: 'thinking', thinking: block.text, thinkingSignature: 'reasoning_content' })
             break
           case 'tool-call':