@iowarp/clio-coder 0.3.3 → 0.3.4

package/src/interactive/context-recall-command.ts

@@ -0,0 +1,110 @@
+/**
+ * `/context recall <ref>`: the operator's half of working-set recall.
+ *
+ * The model recalls through `context(scope="recall", ref=...)`, which puts the
+ * body back in front of the model at the tail of the working set. This command
+ * answers a different question, asked by a person: what was in the result the
+ * marker replaced. So the body goes to the transcript and nowhere else. It is
+ * never submitted as a turn, never replayed, and never counted against the
+ * context window, which is why an operator can read a 40k-line build log back
+ * without paying for it.
+ *
+ * Everything else is identical to the tool path, deliberately: the same
+ * `resolveRecall` over the same fold at the same live leaf, the same
+ * `contextRecall` ledger entry (with `trigger: "operator"`), and the same
+ * `BusChannels.ContextRecalled` publication. A recall is a churn signal
+ * whoever asked for it, and a policy that keeps evicting something a human
+ * keeps reading back is a policy worth changing.
+ */
+
+import type { ContextRecalledPayload } from "../core/bus-events.js";
+import type { EvictedState } from "../domains/context/working-set/contract.js";
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
+import {
+	buildRecallFields,
+	recallErrorMessage,
+	recallParentTurnId,
+	resolveRecall,
+} from "../domains/context/working-set/recall.js";
+import type { SessionEntryInput } from "../domains/session/contract.js";
+import type { SessionEntry } from "../domains/session/entries.js";
+
+/** Ledger access the command needs, mirroring the context tool's `ContextSessionDeps`. */
+export interface OperatorRecallDeps {
+	hasSession(): boolean;
+	readEntries(): ReadonlyArray<SessionEntry>;
+	/** The live append point (`/tree` pin or tree leaf); undefined lets the fold infer it. */
+	activeLeafTurnId(): string | undefined;
+	appendEntry(entry: SessionEntryInput): SessionEntry;
+	/** Publisher for `BusChannels.ContextRecalled`; the runtime supplies the bus. */
+	onRecalled?: (payload: ContextRecalledPayload) => void;
+	now?: () => number;
+}
+
+export type OperatorRecallOutcome =
+	| {
+			ok: true;
+			/** One-line summary for the notice bar. */
+			headline: string;
+			/** The original body, byte-exact, for the transcript. */
+			body: string;
+	  }
+	| { ok: false; message: string };
+
+function formatTokens(tokens: number): string {
+	return tokens.toLocaleString("en-US");
+}
+
+/**
+ * Ref, why it left, what it costs to read, and where the full artifact lives
+ * when the original result was offloaded. Nothing else: the body is on the next
+ * line and the operator is already looking at it.
+ */
+function headlineFor(ref: string, tokens: number, state: EvictedState | undefined, offloadPath?: string): string {
+	const parts = [ref];
+	if (state !== undefined) {
+		parts.push(state.by === undefined ? `evicted: ${state.reason}` : `evicted: ${state.reason} by ${state.by}`);
+	}
+	parts.push(`${formatTokens(tokens)} tokens`);
+	if (offloadPath !== undefined) parts.push(`offload: ${offloadPath}`);
+	return `[/context recall] ${parts.join(" · ")}`;
+}
+
+export function runOperatorRecall(ref: string, deps: OperatorRecallDeps): OperatorRecallOutcome {
+	if (!deps.hasSession()) {
+		return { ok: false, message: "[/context recall] no active session; start one with /new or /resume first" };
+	}
+	const trimmed = ref.trim();
+	if (trimmed.length === 0) {
+		return { ok: false, message: "[/context recall] needs a ref: the turnId named in an [evicted ...] marker" };
+	}
+	const entries = deps.readEntries();
+	const leaf = deps.activeLeafTurnId();
+	const view = foldWorkingSet(entries, leaf);
+	const resolved = resolveRecall(entries, view, trimmed, leaf);
+	// A ref that resolves to nothing is usually a typo or a stale marker; the
+	// shared message ends with the refs the operator could have typed instead.
+	if (!resolved.ok)
+		return { ok: false, message: `[/context recall] ${recallErrorMessage(resolved.error, entries, view)}` };
+	const { result } = resolved;
+	const fields = buildRecallFields(result, { trigger: "operator" });
+	try {
+		deps.appendEntry({ ...fields, parentTurnId: recallParentTurnId(entries, leaf) });
+	} catch (err) {
+		return {
+			ok: false,
+			message: `[/context recall] recall of ${result.ref.entry} could not be recorded: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+	deps.onRecalled?.({
+		ref: result.ref.entry,
+		trigger: "operator",
+		tokensReadmitted: result.tokens,
+		at: deps.now?.() ?? Date.now(),
+	});
+	return {
+		ok: true,
+		headline: headlineFor(result.ref.entry, result.tokens, view.evicted.get(result.ref.entry), result.offloadPath),
+		body: result.body,
+	};
+}

package/src/interactive/interactive-slash-runtime.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { BusChannels } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import type { PendingSkillRequest } from "../core/skill-activation.js";
@@ -28,6 +29,7 @@ import { type ChatPanel, createChatPanel } from "./chat-panel.js";
 import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { runCompactWithNotice } from "./command-fallbacks.js";
 import { appendNotice, appendOperatorCommand } from "./command-output.js";
+import { runOperatorRecall } from "./context-recall-command.js";
 import { renderSessionHtml } from "./export-html/index.js";
 import { dateLocal } from "./format-time.js";
 import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
@@ -100,8 +102,10 @@ export interface InteractiveSlashRuntimeDeps {
 	 * Leaf lookup for `/export`, so the export follows the branch the session
 	 * is actually on. current.jsonl still holds the abandoned turns after a
 	 * `/tree` pin, and an unscoped rehydrate reproduced them (issue #109).
+	 * `/context recall` uses the same leaf for its fold, plus `appendEntry` for
+	 * the `contextRecall` record.
 	 */
-	session?: Pick<SessionContract, "tree">;
+	session?: Pick<SessionContract, "tree" | "current" | "appendEntry">;
 	expandSubmit: (text: string) => Promise<InteractiveSlashSubmitExpansion>;
 	openAskUser: AskUserHandler;
 	openSkillsHub: () => void;
@@ -512,6 +516,38 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 			}
 			deps.openContextReset();
 		},
+		...(deps.session
+			? {
+					runContextRecall: (ref: string) => {
+						const session = deps.session;
+						if (!session) return;
+						const outcome = runOperatorRecall(ref, {
+							hasSession: () => session.current() !== null,
+							readEntries: () => {
+								const sessionId = deps.chat.getSessionId();
+								return sessionId ? deps.readStructuredEntries(sessionId) : [];
+							},
+							activeLeafTurnId: () => {
+								const meta = session.current();
+								return meta ? (session.tree(meta.id).leafId ?? undefined) : undefined;
+							},
+							appendEntry: (entry) => session.appendEntry(entry),
+							onRecalled: (payload) => deps.bus.emit(BusChannels.ContextRecalled, payload),
+							...(deps.now ? { now: () => (deps.now?.() ?? new Date()).getTime() } : {}),
+						});
+						if (!outcome.ok) {
+							appendCommandNotice("error", outcome.message);
+							return;
+						}
+						appendCommandNotice("success", outcome.headline);
+						// The body is transcript output, not a notice: notices collapse
+						// newlines, and a recalled build log is worth nothing on one line.
+						// It is a replay block either way, so it never enters model context.
+						deps.io.stdout(`${outcome.body}\n`);
+						deps.requestRender();
+					},
+				}
+			: {}),
 		runContextRefresh: () => {
 			if (!deps.onContextRefresh) {
 				deps.io.stderr("[/context refresh] context refresh not wired; pass onContextRefresh to startInteractive\n");

package/src/interactive/model-session-replay.ts

@@ -0,0 +1,21 @@
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
+import { projectWorkingSet } from "../domains/context/working-set/project.js";
+import type { SessionEntry } from "../domains/session/entries.js";
+import type { AgentMessage } from "../engine/types.js";
+import { buildReplayAgentMessagesFromTurns, type RehydrateChatPanelOptions } from "./chat-renderer.js";
+
+/**
+ * Build provider-facing replay messages from the durable session ledger.
+ * Projection always honors existing eviction and recall entries; the enabled
+ * setting gates creation of new evictions, not replay of durable state.
+ * Visible transcript and export callers intentionally keep using the raw
+ * rehydration helpers so eviction remains a model projection, not data loss.
+ */
+export function buildModelReplayAgentMessagesFromTurns(
+	entries: ReadonlyArray<SessionEntry>,
+	options: RehydrateChatPanelOptions = {},
+): AgentMessage[] {
+	const activeLeafTurnId = options.activeLeafTurnId ?? options.uptoTurnId;
+	const projected = projectWorkingSet(entries, foldWorkingSet(entries, activeLeafTurnId));
+	return buildReplayAgentMessagesFromTurns(projected, options);
+}

package/src/interactive/overlay-general-openers.ts

@@ -1,4 +1,5 @@
 import type { SafeEventBus } from "../core/event-bus.js";
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
 import type { DispatchContract } from "../domains/dispatch/index.js";
 import { loadMemoryRecordsSync, type MemoryRecord } from "../domains/memory/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
@@ -107,6 +108,11 @@ export function createOverlayGeneralOpeners(deps: OverlayGeneralOpenersDeps): Ov
 		deps.transitions.handle = openContextOverlayFactory(deps.tui, deps.getContextLedger, {
 			bus: deps.bus,
 			chat: deps.contextChat,
+			getWorkingSet: () => {
+				const readSessionEntries = deps.readSessionEntries;
+				if (!readSessionEntries) return null;
+				return foldWorkingSet(readSessionEntries(), deps.getSessionMeta()?.pinnedLeafTurnId ?? undefined);
+			},
 		});
 		deps.requestRender();
 	};

package/src/interactive/overlay-session-lifecycle.ts

@@ -3,9 +3,10 @@ import type { SessionContract, SessionEntry } from "../domains/session/index.js"
 import type { TUI } from "../engine/tui.js";
 import type { ChatLoop } from "./chat-loop.js";
 import type { ChatPanel } from "./chat-panel.js";
-import { buildReplayAgentMessagesFromTurns, rehydrateChatPanelFromTurns } from "./chat-renderer.js";
+import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { emitCommandNotice } from "./command-fallbacks.js";
 import type { InteractiveNoticeLevel } from "./interactive-subscriptions.js";
+import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
 import type { OverlayTransitions } from "./overlay-transitions.js";
 import { openCwdFallbackOverlay } from "./overlays/cwd-fallback.js";
 import { openMessagePickerOverlay } from "./overlays/message-picker.js";
@@ -159,7 +160,7 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 					const replayOptions = leafTurnId ? { activeLeafTurnId: leafTurnId } : {};
 					deps.resetTranscript();
 					rehydrateChatPanelFromTurns(deps.chatPanel, turns, replayOptions);
-					const replayMessages = buildReplayAgentMessagesFromTurns(turns, replayOptions);
+					const replayMessages = buildModelReplayAgentMessagesFromTurns(turns, replayOptions);
 					deps.chat.resetForSession(leafTurnId, replayMessages);
 					rescopeToBranch(session, turns, leafTurnId);
 				} catch (error) {
@@ -209,7 +210,7 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 					const turns = deps.readStructuredEntries(sessionId);
 					deps.resetTranscript();
 					rehydrateChatPanelFromTurns(deps.chatPanel, turns, { uptoTurnId: turnId });
-					const replayMessages = buildReplayAgentMessagesFromTurns(turns, { uptoTurnId: turnId });
+					const replayMessages = buildModelReplayAgentMessagesFromTurns(turns, { uptoTurnId: turnId });
 					deps.chat.resetForSession(turnId, replayMessages);
 					// The same branch the transcript above was just scoped to. Without the
 					// leaf, /cost, the footer Σ, and the last-turn line kept reporting the
@@ -287,8 +288,11 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		try {
 			const turns = deps.readStructuredEntries(forkedSessionId);
 			rehydrateChatPanelFromTurns(deps.chatPanel, turns);
-			const replayMessages = buildReplayAgentMessagesFromTurns(turns);
 			const leafTurnId = session.tree(forkedSessionId).leafId ?? parentTurnId;
+			const replayMessages = buildModelReplayAgentMessagesFromTurns(
+				turns,
+				leafTurnId ? { activeLeafTurnId: leafTurnId } : {},
+			);
 			deps.chat.resetForSession(leafTurnId, replayMessages);
 			rescopeToBranch(session, turns, leafTurnId);
 		} catch (error) {

package/src/interactive/renderers/tool-execution.ts

@@ -16,6 +16,7 @@ import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
 import { formatSize } from "../../engine/truncate.js";
 import { visibleWidth, wrapTextWithAnsi } from "../../engine/tui.js";
 import { classifyResourceRead, toolPresentationPolicy } from "../../tools/presentation.js";
+import { toolResultPresentationPolicy, toolResultPresentationText } from "../../tools/result-disposition.js";
 import type { ApprovalRequestView } from "../permission-overlay.js";
 import { clioTheme, formatCompactMs, GLYPH } from "../theme/index.js";
 import { renderDiffLines } from "./diff.js";
@@ -81,6 +82,13 @@ export interface ToolExecutionFinished {
 	 * model reading the same transcript, to guess at the rule.
 	 */
 	blockReason?: string | undefined;
+	/**
+	 * Working-set eviction reason, when the projection has replaced this
+	 * result's body for the model. The transcript still renders the full body:
+	 * the ledger is what the operator scrolls, the projection is only what the
+	 * next request carries. The tag says the two now differ here.
+	 */
+	evictedReason?: string | undefined;
 	/** Structured exit status when the caller has one; text parsing is legacy fallback only. */
 	exitCode?: number | string | null | undefined;
 	/** Local `!!` bash output is visible to the operator but excluded from model context. */
@@ -456,6 +464,7 @@ function ledgerTail(finished: ToolExecutionFinished): { facts: string; offload:
 		if (details?.outputCapped === true) parts.push("output capped");
 	}
 	if (finished.excludeFromContext === true) parts.push("excluded from context");
+	if (finished.evictedReason !== undefined) parts.push("evicted", finished.evictedReason);
 	const offloadPath = executed ? offloadPathOf(finished) : null;
 	return {
 		facts: parts.length > 0 ? dim(` · ${parts.join(" · ")}`) : "",
@@ -473,7 +482,9 @@ const FAILURE_EXCERPT_LIMIT = 80;
  * its failures carry one; the renderer never names a tool here.
  */
 function failureExcerpt(finished: ToolExecutionFinished, width: number): string {
-	if (!finished.isError || !toolPresentationPolicy(finished.toolName, finished.args).failureExcerpt) return "";
+	const presentation =
+		toolResultPresentationPolicy(finished.result) ?? toolPresentationPolicy(finished.toolName, finished.args);
+	if (!finished.isError || !presentation.failureExcerpt) return "";
 	if (isNonExecutedOutcome(finished.outcome)) return "";
 	const text = unwrapResultEnvelope(finished.result);
 	if (typeof text !== "string") return "";
@@ -871,6 +882,8 @@ function renderArgsBody(toolName: string, args: unknown, width: number, isError:
  */
 function unwrapResultEnvelope(result: unknown): unknown {
 	if (typeof result === "string" || result === null || result === undefined) return result;
+	const presentationText = toolResultPresentationText(result);
+	if (presentationText !== null) return presentationText;
 	const blocks = Array.isArray(result)
 		? result
 		: isPlainObject(result) && Array.isArray(result.content)
@@ -1041,6 +1054,7 @@ function outputFacts(finished: ToolExecutionFinished): string[] {
 	}
 	if (isPlainObject(finished.result) && finished.result.terminate === true) parts.push("terminal result");
 	if (finished.excludeFromContext === true) parts.push("excluded from context");
+	if (finished.evictedReason !== undefined) parts.push("evicted", finished.evictedReason);
 	return parts;
 }
 
@@ -1174,7 +1188,9 @@ export interface ToolSublineRenderOptions {
 function foldedDiffRows(finished: ToolExecutionFinished, width: number, opts: ToolSublineRenderOptions): string[] {
 	if (opts.foldedExtras === "none") return [];
 	if (finished.isError || isNonExecutedOutcome(finished.outcome)) return [];
-	if (!toolPresentationPolicy(finished.toolName, finished.args).showDiffWhenFolded) return [];
+	const presentation =
+		toolResultPresentationPolicy(finished.result) ?? toolPresentationPolicy(finished.toolName, finished.args);
+	if (!presentation.showDiffWhenFolded) return [];
 	const diff = resultDiff(finished.result);
 	if (diff === null) return [];
 	return truncateRowsMiddle(

package/src/interactive/session-transcript.ts

@@ -3,7 +3,7 @@ import { collectSessionEntries } from "../domains/session/compaction/session-ent
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
 import { openSession, sessionPaths } from "../engine/session.js";
 import type { ChatLoop } from "./chat-loop.js";
-import { buildReplayAgentMessagesFromTurns } from "./chat-renderer.js";
+import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
 
 type SessionOwner = Pick<SessionContract, "create" | "current">;
 type SessionChat = Pick<ChatLoop, "resetForSession">;
@@ -87,7 +87,7 @@ export function createSessionTranscript(deps: SessionTranscriptDeps): SessionTra
 		const turns = deps.readSessionEntries();
 		deps.chat.resetForSession(
 			leafTurnId,
-			buildReplayAgentMessagesFromTurns(turns, {
+			buildModelReplayAgentMessagesFromTurns(turns, {
 				...(leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
 			}),
 		);

package/src/interactive/slash-commands.ts

@@ -44,6 +44,8 @@ type SlashCommandVariant =
 	| { kind: "init"; options: InitCommandOptions }
 	| { kind: "context-clear"; options: ContextClearCommandOptions }
 	| { kind: "context-refresh" }
+	/** `ref` is the turnId an `[evicted ...]` marker names. */
+	| { kind: "context-recall"; ref: string }
 	| { kind: "skill-selector" }
 	| { kind: "skill-invocation"; text: string }
 	| { kind: "prompts" }
@@ -343,6 +345,13 @@ export interface SlashCommandContext {
 	 * Optional until the host wires onContextRefresh.
 	 */
 	runContextRefresh?: () => void;
+	/**
+	 * Read an evicted tool-result body back into the transcript by ref, and
+	 * record the `contextRecall` entry. Transcript-only: an operator recall
+	 * answers the person, so the body never becomes model context. Optional
+	 * until the host wires a session.
+	 */
+	runContextRecall?: (ref: string) => void;
 	openSkillsHub?: () => void;
 	listPrompts: () => ResourceList<PromptTemplate>;
 	/**
@@ -481,6 +490,13 @@ const COMPACT_POSITIONALS: ReadonlyArray<CommandPositionalSpec> = [
 	{ name: "instructions", required: false, rest: true },
 ];
 
+/**
+ * `/context recall <ref>` takes exactly one ref, not a rest tail: a ref is a
+ * single turnId, and a second token is a mistake worth reporting rather than
+ * text to fold into the first.
+ */
+const RECALL_POSITIONALS: ReadonlyArray<CommandPositionalSpec> = [{ name: "ref", required: true }];
+
 /**
  * A registered command whose arguments do not parse is a mistake to report,
  * not a chat message to send. Falling through to `unknown` submitted the raw
@@ -859,11 +875,12 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 	},
 	{
 		name: "context",
-		description: "Context hub: window overlay plus compact, init, refresh, and reset",
+		description: "Context hub: window overlay plus compact, recall, init, refresh, and reset",
 		group: "Inspect",
-		kinds: ["context-view", "compact", "init", "context-clear", "context-refresh"],
+		kinds: ["context-view", "compact", "context-recall", "init", "context-clear", "context-refresh"],
 		subcommandDescriptions: {
 			compact: "Compact session context",
+			recall: "Recall an evicted result",
 			init: "Initialize project context",
 			refresh: "Refresh project context",
 			reset: "Reset project context",
@@ -871,6 +888,7 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 		args: {
 			subcommands: {
 				compact: { positionals: [...COMPACT_POSITIONALS] },
+				recall: { positionals: [...RECALL_POSITIONALS] },
 				init: {},
 				refresh: {},
 				reset: {},
@@ -881,6 +899,8 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			switch (parsed.subcommand) {
 				case "compact":
 					return { kind: "compact", instructions: parsed.rest };
+				case "recall":
+					return { kind: "context-recall", ref: parsed.positionals[0] ?? "" };
 				case "init":
 					return { kind: "init", options: {} };
 				case "refresh":
@@ -899,6 +919,13 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 				case "compact":
 					ctx.runCompact(command.instructions);
 					return;
+				case "context-recall":
+					if (ctx.runContextRecall) {
+						ctx.runContextRecall(command.ref);
+					} else {
+						ctx.notice("error", "context recall is not wired; no session is bound to this process");
+					}
+					return;
 				case "init":
 					ctx.runInit(command.options);
 					return;