dsh-switchman 1.8.1 → 1.10.2

package/host/context-trim/metrics.js

@@ -0,0 +1,128 @@
+/** dsh-switchman context-trim stream metrics.
+ *
+ * Meter duality (design §8): trim thresholds run on VIEW-estimated tokens
+ * (buildView output, the meter the fold logic controls), while the
+ * watermark keeps its STORED-token meter — the two signals are kept
+ * separate on purpose. This module wraps the llm/stream result generator
+ * so every provider response is sampled for usage (input/cached/output)
+ * without ever breaking the stream: sampling errors are swallowed, the
+ * chunk always flows through untouched.
+ */
+
+/** Extract usage fields from a stream chunk. Returns
+ * { inputTokens, cachedTokens, cacheWriteTokens, outputTokens } or null when
+ * the chunk carries none. Defensive field walk — providers shape usage
+ * differently (usage.input_tokens, usage.prompt_tokens, cached_tokens,
+ * cache_read_input_tokens, ...).
+ *
+ * Two shapes matter here. The host's own stream chunks carry a normalized
+ * TokenUsage ({ inputTokens, cacheReadTokens, cacheWriteTokens, ... }) where
+ * inputTokens counts UNCACHED prompt tokens only — the camelCase buckets do
+ * not overlap (llm-deepseek/src/translate.ts). Raw provider payloads use the
+ * snake_case twins, which on the Anthropic side have the same meaning. Only
+ * the OpenAI-style prompt_tokens shape would make inputTokens the inclusive
+ * total; summing there would over-count the prompt, which merely folds
+ * earlier — the safe direction for this plugin. */
+export function extractUsage(chunk) {
+	if (chunk === null || typeof chunk !== "object") return null;
+	const candidates = [chunk.usage, chunk.metadata?.usage, chunk.response?.usage];
+	for (const usage of candidates) {
+		if (usage === null || typeof usage !== "object") continue;
+		const input = usage.input_tokens ?? usage.prompt_tokens ?? usage.inputTokens;
+		const cached = usage.cache_read_input_tokens ?? usage.cached_tokens ?? usage.cachedTokens ?? usage.cacheReadTokens ?? usage.prompt_tokens_details?.cached_tokens;
+		const cacheWrite = usage.cache_creation_input_tokens ?? usage.cache_write_tokens ?? usage.cacheWriteTokens;
+		const output = usage.output_tokens ?? usage.completion_tokens ?? usage.outputTokens;
+		if (!Number.isFinite(input) && !Number.isFinite(cached) && !Number.isFinite(cacheWrite) && !Number.isFinite(output)) continue;
+		return {
+			inputTokens: Number.isFinite(input) ? input : null,
+			cachedTokens: Number.isFinite(cached) ? cached : null,
+			cacheWriteTokens: Number.isFinite(cacheWrite) ? cacheWrite : null,
+			outputTokens: Number.isFinite(output) ? output : null,
+		};
+	}
+	return null;
+}
+
+/** Total prompt tokens for one metrics record: uncached input + cache read +
+ * cache write (host TokenUsage buckets do not overlap). Null when no input
+ * sample has ever been recorded — callers must treat unknown as "no wire
+ * signal" and stay on the view estimate. Missing cache buckets count as 0. */
+export function promptTokensOf(record) {
+	if (record === null || record === undefined) return null;
+	if (!Number.isFinite(record.lastInputTokens)) return null;
+	const total = record.lastInputTokens + (Number.isFinite(record.cachedTokens) ? record.cachedTokens : 0) + (Number.isFinite(record.cacheWriteTokens) ? record.cacheWriteTokens : 0);
+	return total > 0 ? Math.round(total) : null;
+}
+
+/** Per-session metrics store. */
+export function createMetrics() {
+	const sessions = new Map(); // sessionId -> record
+
+	function recordOf(sessionId) {
+		let record = sessions.get(sessionId);
+		if (record === undefined) {
+			record = {
+				lastInputTokens: null, // UNCACHED prompt tokens of the last sample
+				cachedTokens: null, // cache-read bucket of the last sample
+				cacheWriteTokens: null, // cache-write bucket of the last sample
+				outputTokens: null,
+				viewTokens: null, // view estimate noted by the listener pre-request
+				lastModel: null, // { provider, model } of the last stream
+				lastStreamAt: 0,
+				totalStreams: 0,
+			};
+		}
+		sessions.delete(sessionId); // drop first so re-insert refreshes recency order
+		sessions.set(sessionId, record);
+		// Prune: keep only the 50 most recently active sessions (bounded memory).
+		if (sessions.size > 50) {
+			const oldest = sessions.keys().next().value;
+			if (oldest !== undefined && oldest !== sessionId) sessions.delete(oldest);
+		}
+		return record;
+	}
+
+	return {
+		/** Note the outbound-view estimate + model before/around a request. */
+		noteView(sessionId, viewTokens, model) {
+			const record = recordOf(sessionId);
+			if (Number.isFinite(viewTokens)) record.viewTokens = Math.round(viewTokens);
+			if (model !== null && typeof model === "object") record.lastModel = { provider: model.provider ?? null, model: model.model ?? null };
+			record.lastStreamAt = Date.now();
+			record.totalStreams += 1;
+			return record;
+		},
+		/** Merge a usage sample (from extractUsage) into the record. */
+		recordUsage(sessionId, usage) {
+			if (usage === null) return null;
+			const record = recordOf(sessionId);
+			if (usage.inputTokens !== null) record.lastInputTokens = usage.inputTokens;
+			if (usage.cachedTokens !== null) record.cachedTokens = usage.cachedTokens;
+			if (usage.cacheWriteTokens !== null) record.cacheWriteTokens = usage.cacheWriteTokens;
+			if (usage.outputTokens !== null) record.outputTokens = usage.outputTokens;
+			return record;
+		},
+		/** Record of one session (or null when never streamed). */
+		of(sessionId) {
+			return sessions.get(sessionId) ?? null;
+		},
+	};
+}
+
+/** Wrap a stream result so each chunk flows through a (failing-open)
+ * sampler before being yielded. Returns the original value untouched when
+ * it is not an async iterable (non-stream fallbacks must pass through). */
+export function wrapStreamForMetrics(result, onChunk) {
+	if (result === null || typeof result !== "object" || typeof result[Symbol.asyncIterator] !== "function") return result;
+	async function* sampled() {
+		for await (const chunk of result) {
+			try {
+				onChunk(chunk);
+			} catch {
+				/* sampling must never break the stream */
+			}
+			yield chunk;
+		}
+	}
+	return sampled();
+}

package/host/context-trim/state.js

@@ -0,0 +1,241 @@
+/** dsh-switchman context-trim fold ledger store (host side).
+ *
+ * One ledger per session: the ordered list of fold blocks plus fold
+ * metadata (last fold's view-token estimate for the growth gate, fold
+ * timestamps for the hourly cadence cap). Ledgers persist as one JSON
+ * file per session under <dshHome>/.dsh-switchman/state/trim/ (or an
+ * explicit state dir) — atomic tmp+rename writes, corrupt files reset the
+ * ledger (fail-open: trimming must never brick a session over its own
+ * bookkeeping).
+ *
+ * commitFold validates a new block against the CURRENT messages snapshot
+ * (the posMap: refs -> indices) before it enters the ledger — ref range
+ * must be locatable, segment-aligned, disjoint from every existing block,
+ * and strictly monotonic (behind or inside the existing frontier is
+ * rejected). Without a posMap (ctx_trim_fold against a stale capture) only
+ * structural checks and exact-duplicate guards apply.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { dshHome } from "../lib/dsh-home.js";
+import { estimateTokensOf, refPositions } from "./view.js";
+
+/** Current ledger file format version. */
+export const LEDGER_VERSION = 1;
+
+/** Filenames are session-id-derived; keep them filesystem-safe. */
+function sanitizeSessionId(sessionId) {
+	const raw = typeof sessionId === "string" && sessionId !== "" ? sessionId : "default";
+	// Percent-encode % and path separators FIRST so the mapping is injective
+	// ("a/b" and "a_b" must never share one ledger file).
+	const safe = Array.from(raw, (ch) => (ch === "%" ? "%25" : ch === "/" ? "%2F" : ch === "\\" ? "%5C" : ch)).join("").slice(0, 128);
+	return safe === "" ? "default" : safe;
+}
+
+/** Empty ledger for one session. frontier = ref of the newest folded
+ * message (the fold boundary); it only ever advances (monotonic). */
+export function emptyLedger(sessionId) {
+	return {
+		version: LEDGER_VERSION,
+		sessionId,
+		blocks: [],
+		frontier: null,
+		lastFoldViewTokens: 0,
+		lastFoldLowTokens: 0,
+		lastFoldAt: 0,
+		foldsThisHour: [],
+		// Fork-state inheritance marker (fork.js): set only when this ledger
+		// was cloned from a parent session — one inheritance per child.
+		inheritedFrom: null,
+		inheritedAt: 0,
+	};
+}
+
+/** Structural validation of a candidate block (refRange/count/summary).
+ * Returns the normalized block or null. */
+export function normalizeBlock(candidate, now) {
+	if (candidate === null || typeof candidate !== "object") return null;
+	const firstId = candidate.refRange?.firstId;
+	const lastId = candidate.refRange?.lastId;
+	if (typeof firstId !== "string" || firstId === "" || typeof lastId !== "string" || lastId === "") return null;
+	const summary = typeof candidate.summary === "string" ? candidate.summary.trim() : "";
+	if (summary === "") return null;
+	const count = Number.isInteger(candidate.count) && candidate.count > 0 ? candidate.count : 0;
+	if (count <= 0) return null;
+	const approxTokens = Number.isFinite(candidate.approxTokens) && candidate.approxTokens > 0 ? Math.round(candidate.approxTokens) : count;
+	const kind = candidate.kind === "mechanical" ? "mechanical" : "summary";
+	const tier = candidate.tier === "emergency" || candidate.tier === "pressure" || candidate.tier === "growth" || candidate.tier === "model" ? candidate.tier : "model";
+	return {
+		id: typeof candidate.id === "string" && candidate.id !== "" ? candidate.id : `b${now}`,
+		kind,
+		tier,
+		refRange: { firstId, lastId },
+		count,
+		approxTokens,
+		summary,
+		createdAt: now,
+	};
+}
+
+/** Create the ledger store. options: { stateDir?, warn? }. stateDir wins
+ * over the dshHome default; warn receives soft failures. */
+export function createStore(options = {}) {
+	const warn = typeof options.warn === "function" ? options.warn : () => {};
+	const stateDir = options.stateDir ?? join(dshHome(), ".dsh-switchman", "state", "trim");
+	const ledgers = new Map(); // sessionId -> ledger (loaded lazily)
+
+	function fileFor(sessionId) {
+		return join(stateDir, `${sanitizeSessionId(sessionId)}.json`);
+	}
+
+	/** Load one ledger (cached). Corrupt or unreadable files reset the
+	 * ledger and are moved aside (best effort) for forensics. */
+	function ledgerOf(sessionId) {
+		const cached = ledgers.get(sessionId);
+		if (cached !== undefined) return cached;
+		let ledger = emptyLedger(sessionId);
+		const file = fileFor(sessionId);
+		try {
+			if (existsSync(file)) {
+				const parsed = JSON.parse(readFileSync(file, "utf8"));
+				if (parsed !== null && typeof parsed === "object" && Array.isArray(parsed.blocks) && parsed.version === LEDGER_VERSION) {
+					ledger = {
+						version: LEDGER_VERSION,
+						sessionId,
+						blocks: parsed.blocks,
+						frontier: typeof parsed.frontier === "string" ? parsed.frontier : null,
+						lastFoldViewTokens: Number.isFinite(parsed.lastFoldViewTokens) ? parsed.lastFoldViewTokens : 0,
+						lastFoldLowTokens: Number.isFinite(parsed.lastFoldLowTokens) ? parsed.lastFoldLowTokens : 0,
+						lastFoldAt: Number.isFinite(parsed.lastFoldAt) ? parsed.lastFoldAt : 0,
+						foldsThisHour: Array.isArray(parsed.foldsThisHour) ? parsed.foldsThisHour.filter((ts) => Number.isFinite(ts)) : [],
+						inheritedFrom: typeof parsed.inheritedFrom === "string" ? parsed.inheritedFrom : null,
+						inheritedAt: Number.isFinite(parsed.inheritedAt) ? parsed.inheritedAt : 0,
+					};
+				} else {
+					warn(`[context-trim] ledger for ${sanitizeSessionId(sessionId)} has an unknown format — resetting`);
+					try {
+						renameSync(file, `${file}.corrupt`);
+					} catch {
+						/* best effort */
+					}
+				}
+			}
+		} catch (error) {
+			warn(`[context-trim] ledger load failed (${error?.message ?? error}) — resetting`);
+			ledger = emptyLedger(sessionId);
+			try {
+				renameSync(file, `${file}.corrupt`);
+			} catch {
+				/* best effort */
+			}
+		}
+		ledgers.set(sessionId, ledger);
+		return ledger;
+	}
+
+	/** Persist one ledger atomically (tmp + rename). */
+	function persist(ledger) {
+		try {
+			mkdirSync(stateDir, { recursive: true });
+			const file = fileFor(ledger.sessionId);
+			const tmp = `${file}.tmp`;
+			writeFileSync(tmp, JSON.stringify(ledger));
+			renameSync(tmp, file);
+			return true;
+		} catch (error) {
+			warn(`[context-trim] ledger persist failed (${error?.message ?? error})`);
+			return false;
+		}
+	}
+
+	/** Commit a fold block. posMap (refs -> indices of the CURRENT capture)
+	 * enables full validation; returns { ok, ledger, block } or
+	 * { ok: false, reason }. Memory only — persist() separately. */
+	function commitFold(sessionId, candidate, posMap = null, now = Date.now()) {
+		const block = normalizeBlock(candidate, now);
+		if (block === null) return { ok: false, reason: "invalid-block" };
+		const ledger = ledgerOf(sessionId);
+		// exact-duplicate guard (same range already folded)
+		for (const existing of ledger.blocks) {
+			if (existing.refRange.firstId === block.refRange.firstId && existing.refRange.lastId === block.refRange.lastId) {
+				return { ok: false, reason: "duplicate-range" };
+			}
+		}
+		if (posMap !== null) {
+			const positions = posMap instanceof Map ? posMap : refPositions(posMap);
+			const firstList = positions.get(block.refRange.firstId);
+			const lastList = positions.get(block.refRange.lastId);
+			if (firstList === undefined || lastList === undefined) return { ok: false, reason: "refs-not-found" };
+			// Content-addressed refs collide for duplicate messages, so one ref
+			// may map to many positions. Anchor the pair on block.count and
+			// search occurrences instead of trusting list extremes.
+			let firstIdx = -1;
+			let lastIdx = -1;
+			for (const start of firstList) {
+				const end = start + block.count - 1;
+				if (lastList.includes(end)) {
+					firstIdx = start;
+					lastIdx = end;
+					break;
+				}
+			}
+			if (firstIdx < 0) return { ok: false, reason: "count-mismatch" };
+			// monotonicity: the new range must sit strictly behind the
+			// frontier range and be disjoint from every existing block.
+			for (const existing of ledger.blocks) {
+				const eFirst = positions.get(existing.refRange.firstId);
+				const eLast = positions.get(existing.refRange.lastId);
+				if (eFirst === undefined || eLast === undefined) continue; // stale block outside this capture
+				const eStart = eFirst[0];
+				const eEnd = eLast[eLast.length - 1];
+				if (firstIdx <= eEnd && eStart <= lastIdx) return { ok: false, reason: "overlaps-existing-fold" };
+			}
+		}
+		ledger.blocks.push(block);
+		ledger.frontier = block.refRange.lastId;
+		ledger.lastFoldAt = now;
+		ledger.foldsThisHour = ledger.foldsThisHour.filter((ts) => now - ts < 3_600_000);
+		ledger.foldsThisHour.push(now);
+		ledgers.set(sessionId, ledger);
+		return { ok: true, ledger, block };
+	}
+
+	/** Adopt a fully-built ledger as one session's ledger (fork-state
+	 * inheritance, fork.js resolveInheritance). One-shot: refused when the
+	 * session already carries fold blocks or an inheritance marker — real
+	 * state is never overwritten. Caches AND persists; returns true when
+	 * adopted. */
+	function adoptLedger(sessionId, ledger) {
+		const current = ledgerOf(sessionId);
+		if ((Array.isArray(current.blocks) && current.blocks.length > 0) || current.inheritedFrom !== null) return false;
+		if (ledger === null || typeof ledger !== "object" || ledger.sessionId !== sessionId) return false;
+		ledgers.set(sessionId, ledger);
+		return persist(ledger);
+	}
+
+	/** Record the view-token estimate captured at the last fold (growth-gate
+	 * baseline) and persist. */
+	function recordFoldBaseline(sessionId, viewTokens, lowTokens) {
+		const ledger = ledgerOf(sessionId);
+		if (Number.isFinite(viewTokens) && viewTokens > 0) ledger.lastFoldViewTokens = Math.round(viewTokens);
+		if (Number.isFinite(lowTokens) && lowTokens > 0) ledger.lastFoldLowTokens = Math.round(lowTokens);
+		persist(ledger);
+		return ledger;
+	}
+
+	return { ledgerOf, commitFold, recordFoldBaseline, adoptLedger, persist, stateDir };
+}
+
+/** Test/inspection helper: estimated tokens of a ledger's folds. */
+export function ledgerFoldedTokens(messages, ledger) {
+	const positions = refPositions(messages);
+	let total = 0;
+	for (const block of ledger?.blocks ?? []) {
+		const firstList = positions.get(block.refRange?.firstId);
+		const lastList = positions.get(block.refRange?.lastId);
+		if (firstList === undefined || lastList === undefined) continue;
+		total += estimateTokensOf(messages, firstList[0], lastList[lastList.length - 1]);
+	}
+	return total;
+}

package/host/context-trim/summarizer.js

@@ -0,0 +1,179 @@
+/** dsh-switchman context-trim summarizer.
+ *
+ * Produces the summary text for one fold block, two ways:
+ *
+ * - summarizeWithModel — the L3 path (design §5): a side-model call via
+ *   llm.prepareCall + call.stream (receiver-bound on the llm service, the
+ *   same waterfall pattern intent classification uses). Guarded by a hard
+ *   deadline (AbortController); ANY failure (timeout, error chunk, empty
+ *   output) returns null and the caller skips the fold cycle — fail-open.
+ * - mechanicalSummary — the deterministic fallback used by the emergency
+ *   tier: structural heads of each message, no model round trip.
+ *
+ * The summary prompt carries the bili compression rules: message refs and
+ * file paths verbatim, decisions WITH rationale, exact values, open
+ * objectives carry forward, verbose logs drop.
+ */
+
+import { randomUUID } from "node:crypto";
+
+/** Default side-model summary deadline. Large increments legitimately
+ * take a while; the emergency tier does not wait on this path at all. */
+export const SUMMARY_TIMEOUT_MS = 120_000;
+
+/** Material cap: beyond this the render keeps head+tail and marks the cut
+ * (a 1M-token material would burn the side-model call for no fidelity). */
+export const MAX_MATERIAL_CHARS = 400_000;
+
+/** System prompt for the side-model summarizer. English per repo docs
+ * style; the OUTPUT language follows the summarized material. */
+export const SUMMARY_SYSTEM_PROMPT = [
+	"You compress one contiguous range of a coding-agent conversation into ONE self-contained plain-text summary that will replace that range permanently.",
+	"",
+	"KEEP VERBATIM:",
+	"- Full file paths with line numbers (lib/hooks.ts:347) — never bare filenames.",
+	"- Function/class/type signatures and the critical code line that encodes a finding.",
+	"- Error messages and stack-trace key lines (exact text).",
+	"- Exact values: versions, config keys, thresholds, magic numbers.",
+	"- Decisions WITH their rationale (the because is load-bearing).",
+	"- Open objectives, unresolved TODOs, and open questions, each tagged with its message ref.",
+	"",
+	"DROP (keep one line of lesson for failures): verbose logs once the error line is captured, repeated file reads, dead-end exploration details, back-and-forth discussion once the outcome is recorded.",
+	"",
+	"FORMAT:",
+	"- Dense bullets, short thematic headers; no narrative prose.",
+	"- Reference messages as [m<ref>] using the refs in the material.",
+	"- Write the summary in the same language as the material.",
+	"- Output ONLY the summary text.",
+].join("\n");
+
+/** Render the fold material for one message range: labeled, ref-stamped
+ * blocks. Deterministic (same slice, same bytes) — refs come from refOf so
+ * id-less messages stay stable across re-sends. */
+export function renderMaterial(messages, startIdx, endIdx, refOf) {
+	const parts = [];
+	let chars = 0;
+	let truncated = false;
+	for (let i = startIdx; i <= endIdx; i++) {
+		const message = messages[i];
+		const ref = refOf(message, i);
+		const role = typeof message?.role === "string" ? message.role : "unknown";
+		let text;
+		const content = message?.content;
+		if (typeof content === "string") text = content;
+		else if (Array.isArray(content)) {
+			const chunks = [];
+			for (const block of content) {
+				if (block !== null && typeof block === "object" && typeof block.text === "string") chunks.push(block.text);
+				else {
+					try {
+						chunks.push(JSON.stringify(block ?? null));
+					} catch {
+						chunks.push("[unserializable]");
+					}
+				}
+			}
+			text = chunks.join("\n");
+		} else {
+			try {
+				text = JSON.stringify(message ?? null);
+			} catch {
+				text = "[unserializable]";
+			}
+		}
+		if (Array.isArray(message?.tool_calls) && message.tool_calls.length > 0) {
+			try {
+				text += `\n[tool_calls] ${JSON.stringify(message.tool_calls)}`;
+			} catch {
+				/* keep the base text */
+			}
+		}
+		const head = `--- [m${ref}] (${role}) ---\n`;
+		const body = `${text}\n\n`;
+		if (chars + head.length + body.length > MAX_MATERIAL_CHARS) {
+			truncated = true;
+			break;
+		}
+		parts.push(head + body);
+		chars += head.length + body.length;
+	}
+	if (truncated) parts.push(`--- [...material truncated after ${chars} chars; ${endIdx - startIdx + 1 - parts.length} messages dropped from this render...] ---\n`);
+	return parts.join("");
+}
+
+/** Emergency-tier mechanical summary: deterministic structural heads (no
+ * model call). One line per message: ref, role, first line (capped). */
+export function mechanicalSummary(messages, startIdx, endIdx, refOf) {
+	const lines = [`Mechanical fold of ${endIdx - startIdx + 1} messages (emergency tier; no model summary available).`, ""];
+	for (let i = startIdx; i <= endIdx; i++) {
+		const message = messages[i];
+		const ref = refOf(message, i);
+		const role = typeof message?.role === "string" ? message.role : "unknown";
+		const content = message?.content;
+		let firstLine = "";
+		if (typeof content === "string") firstLine = content;
+		else if (Array.isArray(content)) {
+			for (const block of content) {
+				if (block !== null && typeof block === "object" && typeof block.text === "string" && block.text.trim() !== "") {
+					firstLine = block.text;
+					break;
+				}
+			}
+		}
+		const line = firstLine.replace(/\s+/gu, " ").trim().slice(0, 160);
+		lines.push(`- [m${ref}] (${role}) ${line === "" ? "(no text content)" : line}`);
+	}
+	lines.push("", "Open objectives and exact details are NOT preserved by this mechanical fold; the next model-driven fold will supersede it.");
+	return lines.join("\n");
+}
+
+/** Side-model summary. llm: the dsh llm service (receiver-bound methods);
+ * route: { provider, model } | null (null → caller skips); materialText:
+ * renderMaterial output; deadlineMs: hard budget. Returns the summary
+ * text, or null on ANY failure (caller skips the fold cycle). */
+export async function summarizeWithModel(llm, route, materialText, options = {}) {
+	const fail = typeof options.onFail === "function" ? options.onFail : null;
+	if (route === null || route === undefined) { fail?.("no-route"); return null; }
+	if (typeof llm?.prepareCall !== "function") { fail?.("no-prepare-call"); return null; }
+	const deadlineMs = Number.isFinite(options.deadlineMs) && options.deadlineMs > 0 ? options.deadlineMs : SUMMARY_TIMEOUT_MS;
+	const maxTokens = Number.isFinite(options.maxTokens) && options.maxTokens > 0 ? options.maxTokens : 8_192;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(new Error("trim summary deadline")), deadlineMs);
+	try {
+		const call = await llm.prepareCall(
+			{ provider: route.provider, model: route.model, maxTokens },
+			controller.signal,
+			(controls) => controls,
+		);
+		let text = "";
+			let finishKind = null;
+		// stream options MUST carry the prepared call config — the adapter
+		// dispatch binds credentials/routing from it (same waterfall shape as
+		// the intent classifier; dropping it fails prepare-time integrity).
+		// system rides as a top-level option and the user message carries a
+		// source tag, exactly like the intent classifier's proven shape.
+		const streamOptions = {
+			...call.config,
+			system: SUMMARY_SYSTEM_PROMPT,
+			messages: [
+				{ id: randomUUID(), role: "user", content: [{ type: "text", text: materialText }], source: { kind: "dsh-switchman-trim-summary" } },
+			],
+			signal: controller.signal,
+		};
+		for await (const chunk of call.stream(streamOptions)) {
+			if (chunk?.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+			else if (chunk?.type === "finish") {
+				finishKind = chunk.kind ?? null;
+				if (chunk.kind === "error" || chunk.kind === "aborted") { fail?.(`stream-${chunk.kind}`); return null; }
+			}
+		}
+		const summary = text.trim();
+		if (summary === "") { fail?.(`empty-output finish=${finishKind ?? "none"}`); return null; }
+		return summary;
+	} catch (error) {
+		fail?.(`error: ${error?.message ?? error}`);
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}