@iowarp/clio-coder 0.3.4 → 0.3.7

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/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/domains/share/archive.ts

@@ -11,9 +11,16 @@ import {
 	safeResourceWrite,
 } from "../../core/safe-resource-write.js";
 import { clioConfigDir, resolveClioDirs } from "../../core/xdg.js";
+import { parseFrontmatter } from "../agents/frontmatter.js";
+import {
+	assertAgentSpecPolicy,
+	normalizeAgentSpec,
+	parseAgentRecipeSchema,
+	parseFleetContract,
+} from "../agents/index.js";
 
 export type ShareScope = "project" | "user";
-export type ShareEntryType = "project-context" | "prompt" | "skill" | "settings" | "extension";
+export type ShareEntryType = "project-context" | "prompt" | "skill" | "agent" | "fleet" | "settings" | "extension";
 
 export interface ShareArchiveFile {
 	type: ShareEntryType;
@@ -61,6 +68,8 @@ export interface ShareExportOptions {
 	includeContext?: boolean;
 	includePrompts?: boolean;
 	includeSkills?: boolean;
+	includeAgents?: boolean;
+	includeFleets?: boolean;
 	includeSettings?: boolean;
 	includeExtensions?: boolean;
 }
@@ -206,7 +215,13 @@ function defaultedIncludes(
 ): Required<
 	Pick<
 		ShareExportOptions,
-		"includeContext" | "includePrompts" | "includeSkills" | "includeSettings" | "includeExtensions"
+		| "includeContext"
+		| "includePrompts"
+		| "includeSkills"
+		| "includeAgents"
+		| "includeFleets"
+		| "includeSettings"
+		| "includeExtensions"
 	>
 > {
 	// True when the caller named at least one include flag explicitly. In that
@@ -216,12 +231,16 @@ function defaultedIncludes(
 		options.includeContext !== undefined ||
 		options.includePrompts !== undefined ||
 		options.includeSkills !== undefined ||
+		options.includeAgents !== undefined ||
+		options.includeFleets !== undefined ||
 		options.includeSettings !== undefined ||
 		options.includeExtensions !== undefined;
 	return {
 		includeContext: hasExplicitInclude ? options.includeContext === true : true,
 		includePrompts: hasExplicitInclude ? options.includePrompts === true : true,
 		includeSkills: hasExplicitInclude ? options.includeSkills === true : true,
+		includeAgents: hasExplicitInclude ? options.includeAgents === true : true,
+		includeFleets: hasExplicitInclude ? options.includeFleets === true : true,
 		includeSettings: hasExplicitInclude ? options.includeSettings === true : true,
 		includeExtensions: hasExplicitInclude ? options.includeExtensions === true : true,
 	};
@@ -263,6 +282,18 @@ export function createShareArchive(options: ShareExportOptions = {}): ClioShareA
 			addTree(files, "skill", scope, root, `${scope}/skills`);
 		}
 	}
+	if (includes.includeAgents) {
+		for (const scope of scopes) {
+			const root = scope === "user" ? path.join(clioConfigDir(), "agents") : path.join(cwd, ".clio-coder", "agents");
+			addTree(files, "agent", scope, root, `${scope}/agents`);
+		}
+	}
+	if (includes.includeFleets) {
+		for (const scope of scopes) {
+			const root = scope === "user" ? path.join(clioConfigDir(), "fleets") : path.join(cwd, ".clio-coder", "fleets");
+			addTree(files, "fleet", scope, root, `${scope}/fleets`);
+		}
+	}
 	if (includes.includeExtensions) {
 		for (const scope of scopes) {
 			const root =
@@ -313,9 +344,19 @@ function parseArchive(raw: unknown): ClioShareArchive {
 		throw new Error("share archive manifest is malformed");
 	}
 	const archive = raw as unknown as ClioShareArchive;
+	const allowedTypes = new Set<ShareEntryType>([
+		"project-context",
+		"prompt",
+		"skill",
+		"agent",
+		"fleet",
+		"settings",
+		"extension",
+	]);
 	for (const file of archive.files) {
 		if (
 			!isRecord(file) ||
+			!allowedTypes.has(file.type as ShareEntryType) ||
 			typeof file.archivePath !== "string" ||
 			typeof file.relativePath !== "string" ||
 			typeof file.sha256 !== "string" ||
@@ -392,6 +433,10 @@ function targetRootForFile(entry: ShareArchiveFile, options: ShareImportOptions)
 			return scope === "user"
 				? { root: path.join(config, "skills"), containmentRoot: config, scope }
 				: { root: path.join(cwd, ".clio-coder", "skills"), containmentRoot: cwd, scope };
+		case "agent":
+			return { root: path.join(config, "agents"), containmentRoot: config, scope: "user" };
+		case "fleet":
+			return { root: path.join(config, "fleets"), containmentRoot: config, scope: "user" };
 		case "extension":
 			return scope === "user"
 				? { root: path.join(config, "extensions"), containmentRoot: config, scope }
@@ -563,6 +608,26 @@ function prepareShareImport(filePath: string, options: ShareImportOptions = {}):
 	}
 	for (const targetInfo of preflight.targets) {
 		const { entry, target, scope, buffer } = targetInfo;
+		if (entry.type === "fleet") {
+			try {
+				parseFleetContract(buffer.toString("utf8"), target);
+			} catch (error) {
+				diagnostics.push({ type: "error", message: error instanceof Error ? error.message : String(error), path: target });
+				continue;
+			}
+		}
+		if (entry.type === "agent") {
+			try {
+				const parsed = parseFrontmatter(buffer.toString("utf8"), target);
+				const id = path.basename(target, ".md");
+				assertAgentSpecPolicy(
+					normalizeAgentSpec(parseAgentRecipeSchema({ id, source: "user", filepath: target, ...parsed })),
+				);
+			} catch (error) {
+				diagnostics.push({ type: "error", message: error instanceof Error ? error.message : String(error), path: target });
+				continue;
+			}
+		}
 		if (entry.type === "settings") {
 			diagnostics.push(...settingsPlan(buffer, options));
 			actions.push({ action: "settings", type: entry.type, scope, path: target });

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,12 +5,18 @@ 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";
@@ -1265,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,
@@ -1381,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/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;