@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/domains/session/entries.ts

@@ -13,6 +13,7 @@
 
 import { isSkillActivation, type SkillActivation } from "../../core/skill-activation.js";
 import type { ClioTurnRecord } from "../../engine/session.js";
+import { AUTONOMY_EXPOSURES, type AutonomyExposure } from "../safety/autonomy.js";
 
 export interface SessionHeader {
 	type: "session";
@@ -229,6 +230,7 @@ export interface DecisionLedgerEntry extends BaseSessionEntry {
 	roundCount: number;
 	summary?: string;
 	transcriptPath?: string;
+	exposure?: AutonomyExposure;
 	decisions: DecisionRecord[];
 }
 
@@ -276,6 +278,75 @@ export interface WorkerRunEntry extends BaseSessionEntry {
 	parentToolCallId?: string;
 }
 
+/**
+ * Working-set layer (context domain) ledger records. Eviction is a projection:
+ * these entries say what left the model's working set and what came back; the
+ * original bodies stay in the ledger untouched. The context domain owns the
+ * semantics (`src/domains/context/working-set/contract.ts`); the session
+ * domain owns the wire shape because it owns the ledger format.
+ */
+export const EVICTION_REASONS = [
+	"superseded_read",
+	"stale_after_mutation",
+	"listing_consumed",
+	"failure_resolved",
+	"thinking_turn_closed",
+	"age_horizon",
+	"operator",
+] as const;
+export type EvictionReason = (typeof EVICTION_REASONS)[number];
+
+export const EVICTION_TRIGGERS = ["pressure", "operator"] as const;
+export type EvictionTrigger = (typeof EVICTION_TRIGGERS)[number];
+
+export const RECALL_TRIGGERS = ["tool", "operator"] as const;
+export type RecallTrigger = (typeof RECALL_TRIGGERS)[number];
+
+/**
+ * Identity of an evictable unit: the `turnId` of a ledger entry. For a
+ * `tool_result` message the unit is the result body; for an `assistant`
+ * message the unit is every thinking block it carries. Partial (per-block)
+ * eviction is deliberately not modelled; add a `block` field here when it is.
+ */
+export interface WorkingSetRef {
+	entry: string;
+}
+
+export interface EvictedItem {
+	ref: WorkingSetRef;
+	reason: EvictionReason;
+	/** Estimated tokens the projection removes for this item (marker cost already subtracted). */
+	tokensFreed: number;
+	/**
+	 * Byte-stable one-line stub the projection renders in place of the body.
+	 * Empty for thinking-block eviction, which removes without a marker.
+	 */
+	marker: string;
+	/** Ref key of the entry that superseded or resolved this one, when the reason names one. */
+	by?: string;
+}
+
+export interface ContextEvictionEntry extends BaseSessionEntry {
+	kind: "contextEviction";
+	policyId: string;
+	trigger: EvictionTrigger;
+	evicted: ReadonlyArray<EvictedItem>;
+	tokensBefore: number;
+	tokensAfter: number;
+	/** Used/window ratio that fired the event; null for operator-triggered events. */
+	pressureBefore: number | null;
+	snapshotIdBefore: string | null;
+}
+
+export interface ContextRecallEntry extends BaseSessionEntry {
+	kind: "contextRecall";
+	ref: WorkingSetRef;
+	trigger: RecallTrigger;
+	tokensReadmitted: number;
+	/** The tool call that performed the recall, when `trigger` is `tool`. */
+	toolCallId?: string;
+}
+
 export type SessionEntry =
 	| MessageEntry
 	| BashExecutionEntry
@@ -291,7 +362,9 @@ export type SessionEntry =
 	| SkillActivationEntry
 	| TaskLedgerEntry
 	| DecisionLedgerEntry
-	| WorkerRunEntry;
+	| WorkerRunEntry
+	| ContextEvictionEntry
+	| ContextRecallEntry;
 
 export type SessionFileEntry = SessionHeader | SessionEntry;
 
@@ -317,6 +390,8 @@ export const SESSION_ENTRY_KINDS = [
 	"taskLedger",
 	"decisionLedger",
 	"workerRun",
+	"contextEviction",
+	"contextRecall",
 ] as const;
 
 export type SessionEntryKind = (typeof SESSION_ENTRY_KINDS)[number];
@@ -477,6 +552,21 @@ export function isSessionHeader(value: unknown): value is SessionHeader {
 	);
 }
 
+function isWorkingSetRef(value: unknown): value is WorkingSetRef {
+	return isRecord(value) && isString(value.entry);
+}
+
+function isEvictedItem(value: unknown): value is EvictedItem {
+	return (
+		isRecord(value) &&
+		isWorkingSetRef(value.ref) &&
+		isOneOf(value.reason, EVICTION_REASONS) &&
+		isNumber(value.tokensFreed) &&
+		isString(value.marker) &&
+		isOptionalString(value.by)
+	);
+}
+
 export function isSessionEntry(value: unknown): value is SessionEntry {
 	if (!value || typeof value !== "object") return false;
 	const v = value as Record<string, unknown>;
@@ -555,6 +645,7 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 				v.roundCount >= 0 &&
 				isOptionalString(v.summary) &&
 				isOptionalString(v.transcriptPath) &&
+				(v.exposure === undefined || isOneOf(v.exposure, AUTONOMY_EXPOSURES)) &&
 				Array.isArray(v.decisions) &&
 				v.decisions.every(isDecisionRecord)
 			);
@@ -567,6 +658,24 @@ export function isSessionEntry(value: unknown): value is SessionEntry {
 				isWorkerRunRuntime(v.runtime) &&
 				isOptionalString(v.parentToolCallId)
 			);
+		case "contextEviction":
+			return (
+				isString(v.policyId) &&
+				isOneOf(v.trigger, EVICTION_TRIGGERS) &&
+				Array.isArray(v.evicted) &&
+				v.evicted.every(isEvictedItem) &&
+				isNumber(v.tokensBefore) &&
+				isNumber(v.tokensAfter) &&
+				(v.pressureBefore === null || isNumber(v.pressureBefore)) &&
+				(v.snapshotIdBefore === null || isString(v.snapshotIdBefore))
+			);
+		case "contextRecall":
+			return (
+				isWorkingSetRef(v.ref) &&
+				isOneOf(v.trigger, RECALL_TRIGGERS) &&
+				isNumber(v.tokensReadmitted) &&
+				isOptionalString(v.toolCallId)
+			);
 	}
 	return false;
 }

package/src/domains/session/history.ts

@@ -48,21 +48,15 @@ function collapseWhitespace(text: string): string {
 }
 
 /**
- * Pull the first non-empty piece of user-authored text out of a payload.
- * Structured message payloads may contain a bare string, a text property,
- * or pi-ai content blocks.
+ * Pull the first non-empty piece of text out of a message payload. Structured
+ * message payloads may contain a bare string, a text property, or pi-ai
+ * content blocks.
  */
-function extractUserText(payload: unknown): string | null {
-	if (typeof payload === "string") {
-		const collapsed = collapseWhitespace(payload);
-		return collapsed.length > 0 ? collapsed : null;
-	}
+function rawMessageText(payload: unknown): string | null {
+	if (typeof payload === "string") return payload.trim().length > 0 ? payload : null;
 	if (!payload || typeof payload !== "object") return null;
 	const obj = payload as Record<string, unknown>;
-	if (typeof obj.text === "string") {
-		const collapsed = collapseWhitespace(obj.text);
-		if (collapsed.length > 0) return collapsed;
-	}
+	if (typeof obj.text === "string" && obj.text.trim().length > 0) return obj.text;
 	if (Array.isArray(obj.content)) {
 		const parts: string[] = [];
 		for (const part of obj.content) {
@@ -75,14 +69,65 @@ function extractUserText(payload: unknown): string | null {
 				parts.push((part as { text: string }).text);
 			}
 		}
-		const joined = collapseWhitespace(parts.join(" "));
-		if (joined.length > 0) return joined;
+		const joined = parts.join("\n");
+		if (joined.trim().length > 0) return joined;
 	}
 	return null;
 }
 
+function extractMessageText(payload: unknown): string | null {
+	const raw = rawMessageText(payload);
+	if (raw === null) return null;
+	const collapsed = collapseWhitespace(raw);
+	return collapsed.length > 0 ? collapsed : null;
+}
+
+/**
+ * What the operator typed for a user turn, for the picker preview.
+ *
+ * The persisted text is the composed prompt: a `<system-reminder>` block and
+ * any `[Skill request]` preamble ride ahead of the operator's words as visible
+ * text the model receives. Reading that verbatim made every row of the
+ * `/resume` picker read `<system-reminder> [Skills] 9 installed…`, so sessions
+ * were indistinguishable and the type-to-filter matched them all (issue #188).
+ * Entries written since the operator text was persisted carry it as
+ * `operatorText`; older ones drop the leading scaffolding. Null when nothing
+ * operator-authored remains, so the caller moves on to the next turn.
+ */
+function operatorTextOfUserPayload(payload: unknown): string | null {
+	if (
+		payload &&
+		typeof payload === "object" &&
+		typeof (payload as { operatorText?: unknown }).operatorText === "string"
+	) {
+		const collapsed = collapseWhitespace((payload as { operatorText: string }).operatorText);
+		return collapsed.length > 0 ? collapsed : null;
+	}
+	// Strip before collapsing: the preamble's line structure is what the
+	// patterns anchor on.
+	const text = rawMessageText(payload);
+	if (text === null) return null;
+	const stripped = collapseWhitespace(stripInjectedPreamble(text));
+	return stripped.length > 0 ? stripped : null;
+}
+
+const LEADING_SYSTEM_REMINDER = /^\s*<system-reminder>[\s\S]*?<\/system-reminder>\s*/u;
+const LEADING_SKILL_REQUEST =
+	/^\s*\[Skill request\][\s\S]*?Only these pending skill names are allowed this turn\.[^\n]*\s*/u;
+
+function stripInjectedPreamble(text: string): string {
+	let current = text;
+	for (;;) {
+		const next = current.replace(LEADING_SYSTEM_REMINDER, "").replace(LEADING_SKILL_REQUEST, "");
+		if (next === current) return current;
+		current = next;
+	}
+}
+
 interface ScanResult {
 	firstUserMessage: string | null;
+	/** The first assistant text, the preview when no turn carries operator words. */
+	firstAssistantMessage: string | null;
 	messageCount: number;
 	lastTimestamp: string | null;
 	name: string | null;
@@ -92,6 +137,7 @@ interface ScanResult {
 function scanCurrentJsonl(currentPath: string): ScanResult {
 	const result: ScanResult = {
 		firstUserMessage: null,
+		firstAssistantMessage: null,
 		messageCount: 0,
 		lastTimestamp: null,
 		name: null,
@@ -106,10 +152,14 @@ function scanCurrentJsonl(currentPath: string): ScanResult {
 		if (parsed.kind === "message" && parsed.role === "user") {
 			result.messageCount += 1;
 			if (result.firstUserMessage === null) {
-				const text = extractUserText(parsed.payload);
+				const text = operatorTextOfUserPayload(parsed.payload);
 				if (text !== null) result.firstUserMessage = text;
 			}
 		}
+		if (parsed.kind === "message" && parsed.role === "assistant" && result.firstAssistantMessage === null) {
+			const text = extractMessageText(parsed.payload);
+			if (text !== null) result.firstAssistantMessage = text;
+		}
 		if (parsed.kind === "sessionInfo") {
 			const info = parsed as SessionInfoEntry;
 			if (info.name !== undefined) {
@@ -139,11 +189,10 @@ function enrichMetaForListing(meta: SessionMeta, currentPath: string): void {
 	if (scan.name) meta.name = scan.name;
 	const labelValues = [...scan.labels.values()].map((entry) => entry.label.trim()).filter((label) => label.length > 0);
 	if (labelValues.length > 0) meta.labels = labelValues;
-	if (scan.firstUserMessage) {
+	const preview = scan.firstUserMessage ?? scan.firstAssistantMessage;
+	if (preview) {
 		meta.firstMessagePreview =
-			scan.firstUserMessage.length > PREVIEW_MAX_CHARS
-				? `${scan.firstUserMessage.slice(0, PREVIEW_MAX_CHARS - 1)}…`
-				: scan.firstUserMessage;
+			preview.length > PREVIEW_MAX_CHARS ? `${preview.slice(0, PREVIEW_MAX_CHARS - 1)}…` : preview;
 	}
 	if (scan.messageCount > 0) meta.messageCount = scan.messageCount;
 	const fallbackMtime = readMtimeIso(currentPath);

package/src/domains/session/manager.ts

@@ -70,9 +70,16 @@ export function resumeSessionState(sessionId: string): {
 } {
 	const persistedMeta = readSessionMeta(sessionId) as SessionMeta;
 	const paths = sessionPaths(persistedMeta);
-	runMigrations(persistedMeta, paths.meta);
+	const migration = runMigrations(persistedMeta, paths.meta);
 	const { meta, writer, tree } = engineResumeSession(sessionId);
-	return { state: { meta: meta as SessionMeta, writer }, nodes: tree };
+	const state: SessionManagerState = { meta: meta as SessionMeta, writer };
+	if (migration.migrated) {
+		// The ledger needed no transformation; only the stamp moves, so the next
+		// reader does not re-run the same no-op.
+		state.meta.sessionFormatVersion = migration.to;
+		persistSessionMeta(state);
+	}
+	return { state, nodes: tree };
 }
 
 export function appendTurn(state: SessionManagerState, input: TurnInput): ClioTurnRecord {

package/src/domains/session/migrations/index.ts

@@ -2,7 +2,15 @@
  * Strict session-format version reader.
  *
  * Runs before every session resume. Earlier pre-1.0 formats are disposable
- * local state and must not be transformed into the current format.
+ * local state and must not be transformed into the current format. A version
+ * from the future is refused for the opposite reason: the file is not
+ * disposable, it belongs to a newer Clio, and this build would silently drop
+ * whatever that build understood and this one does not. Downgrading and
+ * resuming would then write the truncated reading back over the original.
+ *
+ * Version 3 to 4 is the one additive step: 4 only adds the working-set kinds
+ * (`contextEviction`, `contextRecall`), so a version-3 ledger is read as-is
+ * and the metadata is restamped. Nothing in the file changes.
  */
 
 import { CURRENT_SESSION_FORMAT_VERSION } from "../../../engine/session.js";
@@ -10,6 +18,9 @@ import type { SessionMeta } from "../contract.js";
 
 export { CURRENT_SESSION_FORMAT_VERSION };
 
+/** Oldest version this build reads without transforming the ledger. */
+export const OLDEST_READABLE_SESSION_FORMAT_VERSION = 3;
+
 export interface MigrationResult {
 	migrated: boolean;
 	from: number;
@@ -18,10 +29,18 @@ export interface MigrationResult {
 
 export function runMigrations(meta: SessionMeta, sessionPath: string): MigrationResult {
 	const from = meta.sessionFormatVersion ?? 1;
-	if (from < CURRENT_SESSION_FORMAT_VERSION) {
+	if (from < OLDEST_READABLE_SESSION_FORMAT_VERSION) {
+		throw new Error(
+			`session metadata has an unsupported format version (expected version ${CURRENT_SESSION_FORMAT_VERSION}, got ${from}): ${sessionPath}. Remove the session directory to start a new session.`,
+		);
+	}
+	if (from > CURRENT_SESSION_FORMAT_VERSION) {
 		throw new Error(
-			`session metadata has an unsupported format version (expected version 3, got ${from}): ${sessionPath}. Remove the session directory to start a new session.`,
+			`session was written by a newer Clio (format version ${from}, this build reads version ${CURRENT_SESSION_FORMAT_VERSION}): ${sessionPath}. Upgrade clio-coder to resume this session.`,
 		);
 	}
+	if (from < CURRENT_SESSION_FORMAT_VERSION) {
+		return { migrated: true, from, to: CURRENT_SESSION_FORMAT_VERSION };
+	}
 	return { migrated: false, from, to: from };
 }

package/src/domains/session/usage.ts

@@ -1,8 +1,8 @@
 /**
  * Fold a session ledger's assistant turns into the per-call usage the rest of
  * Clio reports: tokens in and out, cache reads and writes, reasoning tokens,
- * and provider-reported cost, attributed to the target and wire model that
- * served each call.
+ * and provider-reported cost, attributed to the target and observed model id
+ * for each call.
  *
  * This lives in the session domain because the ledger is the only durable
  * record of what a session spent, and three surfaces read it: the `/cost`
@@ -19,12 +19,22 @@
  * counting it would add an API call worth nothing.
  */
 
+import {
+	attributedModelId,
+	type ResponseModelIdObservation,
+	responseModelIdObservationFromRecord,
+} from "../../core/response-model-id.js";
 import type { SessionEntry } from "./entries.js";
 
 /** One completed assistant API call, as the ledger recorded it. */
 export interface LedgerUsageCall {
 	providerId: string;
-	modelId: string;
+	/** Model id the accounting row uses, or `unknown` when an observed response omitted it. */
+	attributedModelId: string;
+	/** The id the session asked for (the configured model, or the message's own `model`). */
+	requestedModelId: string;
+	/** Direct presence observation, with the pre-#193 difference-only shape labeled separately. */
+	responseModelIdObservation: ResponseModelIdObservation;
 	input: number;
 	output: number;
 	cacheRead: number;
@@ -71,8 +81,8 @@ function stringAt(source: Record<string, unknown>, ...keys: string[]): string |
  * payload instead split one endpoint into two blocks in `/cost`, so a single
  * `node-a` target on `llamacpp` rendered as two providers whose turn counts
  * diverged with every resume. `modelChange` rows are replayed in order so a
- * session that switched targets mid-way attributes each call to the one that
- * served it.
+ * session that switched targets mid-way attributes each call to the active
+ * target.
  */
 export function ledgerUsageCalls(
 	entries: ReadonlyArray<SessionEntry>,
@@ -92,7 +102,9 @@ export function ledgerUsageCalls(
 			if (!usage || usage.totalTokens <= 0) continue;
 			calls.push({
 				providerId: currentTarget ?? "unknown",
-				modelId: currentModel ?? "unknown",
+				attributedModelId: currentModel ?? "unknown",
+				requestedModelId: currentModel ?? "unknown",
+				responseModelIdObservation: { state: "not-observed" },
 				input: usage.input,
 				output: usage.output,
 				cacheRead: usage.cacheRead,
@@ -132,9 +144,14 @@ export function ledgerUsageCalls(
 		if (totalTokens === 0) continue;
 		const cost = usage.cost;
 		const costUsd = cost && typeof cost === "object" ? numberAt(cost as Record<string, unknown>, "total") : 0;
+		const requestedModelId = currentModel ?? stringAt(record, "model") ?? "unknown";
+		const differingResponseModelId = stringAt(record, "responseModel");
+		const responseModelIdObservation = responseModelIdObservationFromRecord(record, "legacy-difference-only");
 		calls.push({
 			providerId: currentTarget ?? stringAt(record, "provider", "api") ?? "unknown",
-			modelId: currentModel ?? stringAt(record, "responseModel", "model") ?? "unknown",
+			attributedModelId: attributedModelId(responseModelIdObservation, requestedModelId, differingResponseModelId),
+			requestedModelId,
+			responseModelIdObservation,
 			input,
 			output,
 			cacheRead,

package/src/engine/acp/event-mapper.ts

@@ -1,4 +1,5 @@
 import { performance } from "node:perf_hooks";
+import { describeCallAction } from "../../domains/safety/call-target.js";
 import type { AgentEvent, AgentMessage } from "../types.js";
 import type { ClioWorkerEvent } from "../worker-events.js";
 import type { AcpPromptResponse, AcpSessionUpdateParams, AcpToolCallUpdate } from "./types.js";
@@ -111,12 +112,17 @@ export class AcpEventMapper {
 			// keeps the monotonic twin, which is what the duration below spans.
 			const startedAt = Date.now();
 			this.toolStarts.set(toolCallId, performance.now());
+			// A peer's `rawInput` is its own argument object and never reaches an
+			// operator surface. The descriptor composed from it here does.
+			const action = describeCallAction(update.kind ?? title, update.rawInput);
 			out.push({
 				type: "clio_tool_start",
 				payload: {
 					tool: update.kind ?? title,
+					toolCallId,
 					posture: "operating",
 					startedAt,
+					...(action !== null ? { action } : {}),
 				},
 			});
 			out.push({
@@ -142,6 +148,7 @@ export class AcpEventMapper {
 				type: "clio_tool_finish",
 				payload: {
 					tool: update.kind ?? title,
+					toolCallId,
 					posture: "operating",
 					durationMs: Math.round(performance.now() - startedAtClock),
 					outcome: isError ? "error" : "ok",

package/src/engine/acp/server.ts

@@ -5,13 +5,20 @@ import { BusChannels, type LoopBlockedPayload } from "../../core/bus-events.js";
 import { DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS } from "../../core/defaults.js";
 import type { SafeEventBus } from "../../core/event-bus.js";
 import { MAX_TIMER_DELAY_MS } from "../../core/timers.js";
+import { ToolNames } from "../../core/tool-names.js";
 import type { ProvidersContract } from "../../domains/providers/contract.js";
 import { isOrchestratorEligibleRuntime } from "../../domains/providers/eligibility.js";
 import { type AutonomyLevel, DEFAULT_AUTONOMY_LEVEL } from "../../domains/safety/autonomy.js";
+import {
+	classifyDecisionPresentation,
+	decisionFactsForPermission,
+} from "../../domains/safety/decision-presentation.js";
 import type { SessionContract, SessionMeta } from "../../domains/session/contract.js";
 import type { MessageEntry, SessionEntry } from "../../domains/session/entries.js";
 import { filterEntriesToActivePath } from "../../domains/session/tree/active-path.js";
+import { askUserExposure } from "../../tools/ask-user.js";
 import type { ToolRegistry } from "../../tools/registry.js";
+import { toolResultPresentationText } from "../../tools/result-disposition.js";
 import type { AgentMessage } from "../types.js";
 import { ACP_TURN_FAILED_MESSAGE, AcpRequestError, AcpTimeoutError, acpErrorMessage } from "./errors.js";
 import type { AcpJsonRpcPeerTransport } from "./transport.js";
@@ -537,6 +544,8 @@ function applyStopReason(active: ActivePrompt, message: unknown): void {
 function outputText(value: unknown): string {
 	if (typeof value === "string") return value;
 	if (!isRecord(value)) return "";
+	const presentationText = toolResultPresentationText(value);
+	if (presentationText !== null) return presentationText;
 	if (Array.isArray(value.content)) return contentText(value.content);
 	if (typeof value.output === "string") return value.output;
 	if (typeof value.text === "string") return value.text;
@@ -1262,6 +1271,19 @@ function installPermissionBridge(input: {
 	const queuedRequestDetails = new Map<string, { tool: string; actionClass: string }>();
 	const unregister = input.toolRegistry.onPermissionRequired((call, decision, meta) => {
 		if (queuedRequestIds.has(meta.requestId)) return;
+		const presentation = classifyDecisionPresentation(
+			decisionFactsForPermission({
+				tool: call.tool,
+				actionClass: decision.classification.actionClass,
+				axis: meta.axis.startsWith("net:")
+					? { kind: "safety-net", ruleId: meta.axis.slice("net:".length) || "unknown" }
+					: { kind: "autonomy", level: meta.axis.slice("autonomy:".length) || DEFAULT_AUTONOMY_LEVEL },
+				origin: { kind: "main" },
+				...(call.tool === ToolNames.AskUser ? { exposure: askUserExposure(call.args) } : {}),
+			}),
+		);
+		const approveAction = presentation.requiredActions.find((action) => action.id === "approve-once");
+		const denyAction = presentation.requiredActions.find((action) => action.id === "deny");
 		queuedRequestIds.add(meta.requestId);
 		queuedRequestDetails.set(meta.requestId, {
 			tool: call.tool,
@@ -1378,8 +1400,16 @@ function installPermissionBridge(input: {
 									...(snapshot.locations !== undefined ? { locations: snapshot.locations } : {}),
 								},
 								options: [
-									{ optionId: "allow-once", name: "Allow once", kind: "allow_once" },
-									{ optionId: "reject-once", name: "Reject", kind: "reject_once" },
+									{
+										optionId: "allow-once",
+										name: approveAction?.label ?? "Approve once",
+										kind: "allow_once",
+									},
+									{
+										optionId: "reject-once",
+										name: denyAction?.label ?? "Deny this request",
+										kind: "reject_once",
+									},
 								],
 							},
 							input.permissionTimeoutMs,

package/src/engine/agent.ts

@@ -11,6 +11,7 @@
  */
 
 import { Agent, type AgentOptions, type StreamFn } from "@earendil-works/pi-agent-core";
+import { isDispositionedToolResultError } from "../tools/result-disposition.js";
 import { engineStreamSimple } from "./api-registry.js";
 
 export type EngineAgentOptions = Omit<AgentOptions, "streamFn"> & { streamFn?: StreamFn };
@@ -20,8 +21,24 @@ export interface EngineAgentHandle {
 	state(): Agent["state"];
 }
 
+function dispositionAwareAfterToolCall(
+	delegate: AgentOptions["afterToolCall"],
+): NonNullable<AgentOptions["afterToolCall"]> {
+	return async (context, signal) => {
+		const override = await delegate?.(context, signal);
+		const effectiveResult =
+			override?.details === undefined ? context.result : { ...context.result, details: override.details };
+		if (isDispositionedToolResultError(effectiveResult)) return { ...override, isError: true };
+		return override;
+	};
+}
+
 export function createEngineAgent(options: EngineAgentOptions = {}): EngineAgentHandle {
-	const agent = new Agent({ streamFn: engineStreamSimple, ...options });
+	const agent = new Agent({
+		streamFn: engineStreamSimple,
+		...options,
+		afterToolCall: dispositionAwareAfterToolCall(options.afterToolCall),
+	});
 	return {
 		agent,
 		state: () => agent.state,

package/src/engine/apis/lmstudio.ts

@@ -130,6 +130,25 @@ async function loadOwnedInstance(
 	return instanceId;
 }
 
+/**
+ * Residency runs before every request, and the same co-residency facts held
+ * every turn, so the peer warning printed once per turn (issue #185). Each
+ * distinct fact is said once per process; a new target, model, or peer set is
+ * a new fact.
+ */
+const announcedResidencyFacts = new Set<string>();
+
+function emitResidencyNoticeOnce(key: string, notice: Parameters<typeof emitResidencyNotice>[0]): void {
+	if (announcedResidencyFacts.has(key)) return;
+	announcedResidencyFacts.add(key);
+	emitResidencyNotice(notice);
+}
+
+/** Test seam: forget which residency facts were announced. */
+export function resetAnnouncedResidencyFacts(): void {
+	announcedResidencyFacts.clear();
+}
+
 export async function ensureLmStudioResidency(
 	model: Model<"openai-completions">,
 	options: { apiKey?: string; signal?: AbortSignal } = {},
@@ -155,7 +174,7 @@ export async function ensureLmStudioResidency(
 		);
 	}
 	if (resolution.wireModelId !== model.id) {
-		emitResidencyNotice({
+		emitResidencyNoticeOnce(`resolved|${info.targetId}|${model.id}|${resolution.wireModelId}`, {
 			kind: "co-resident",
 			level: "info",
 			targetId: info.targetId,
@@ -166,14 +185,16 @@ export async function ensureLmStudioResidency(
 		});
 	}
 	if (resolution.peerTargets.length > 0) {
-		emitResidencyNotice({
+		const peers = resolution.peerTargets.join(", ");
+		const requested = resolution.wireModelId === model.id ? "" : ` (requested '${model.id}')`;
+		emitResidencyNoticeOnce(`peer|${info.targetId}|${model.id}|${resolution.wireModelId}|${peers}`, {
 			kind: "co-resident",
 			level: "warning",
 			targetId: info.targetId,
 			runtimeId: "lmstudio",
 			model: resolution.wireModelId,
-			message: `LM Studio instance '${resolution.wireModelId}' is also loaded on ${resolution.peerTargets.join(", ")}; this request may be served by that LM Link peer.`,
-			detail: { peerTargets: resolution.peerTargets.join(", ") },
+			message: `LM Studio instance '${resolution.wireModelId}'${requested} is also loaded on ${peers}; a request may be served by that LM Link peer, and the footer and usage ledger name the id that answered when it differs.`,
+			detail: { requestedModel: model.id, wireModel: resolution.wireModelId, peerTargets: peers },
 		});
 	}
 	if (!load || Object.keys(load).length === 0 || resolution.instance) return resolution.wireModelId;