@iowarp/clio-coder 0.3.2 → 0.3.4

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/engine/acp/server.ts

@@ -12,6 +12,7 @@ import type { SessionContract, SessionMeta } from "../../domains/session/contrac
 import type { MessageEntry, SessionEntry } from "../../domains/session/entries.js";
 import { filterEntriesToActivePath } from "../../domains/session/tree/active-path.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 +538,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;

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/session.ts

@@ -57,13 +57,19 @@ export interface ClioSessionMeta {
 	platform: string;
 	nodeVersion: string;
 	/**
-	 * Version 3 on every new session. Readers reject earlier versions and
-	 * sessions that omit this field.
+	 * Version 4 on every new session. Readers reject earlier versions, sessions
+	 * that omit this field, and versions from the future.
 	 */
 	sessionFormatVersion?: number;
 }
 
-export const CURRENT_SESSION_FORMAT_VERSION = 3;
+/**
+ * Version 4 adds the working-set ledger kinds (`contextEviction`,
+ * `contextRecall`). A version-3 reader would parse those entries as unknown
+ * kinds and replay a session as if nothing had been evicted, so the bump is
+ * what makes an older Clio refuse the file instead of misreading it.
+ */
+export const CURRENT_SESSION_FORMAT_VERSION = 4;
 
 export interface ClioSessionJsonlHeader {
 	type: "session";

package/src/entry/orchestrator.ts

@@ -161,8 +161,8 @@ import {
 import { openSession, readSessionTailTurns, sessionCurrentPath, sessionPaths } from "../engine/session.js";
 import type { EngineModel } from "../engine/types.js";
 import { createChatLoop } from "../interactive/chat-loop.js";
-import { buildReplayAgentMessagesFromTurns } from "../interactive/chat-renderer.js";
 import { type RunIo, startInteractive } from "../interactive/index.js";
+import { buildModelReplayAgentMessagesFromTurns } from "../interactive/model-session-replay.js";
 import type { BootOptions } from "./boot-options.js";
 
 export type { BootOptions, HeadlessSamplingOverrides } from "./boot-options.js";
@@ -1236,7 +1236,16 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 	// one object the dispatch tool and the keypress both hold.
 	const dispatchBackground = createDispatchBackgroundRegistry();
 	registerAllTools(toolRegistry, {
-		...(session ? { session } : {}),
+		...(session
+			? {
+					session,
+					readSessionEntries: () => {
+						const meta = session.current();
+						return meta ? readSessionEntriesForCompact(meta.id) : [];
+					},
+					onContextRecalled: (payload) => bus.emit(BusChannels.ContextRecalled, payload),
+				}
+			: {}),
 		taskBoard,
 		userTasks,
 		dispatch,
@@ -1612,7 +1621,10 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 				// parent onto.
 				chat.resetForSession(
 					leafTurnId,
-					buildReplayAgentMessagesFromTurns(readCurrentSessionEntries(), leafTurnId ? { activeLeafTurnId: leafTurnId } : {}),
+					buildModelReplayAgentMessagesFromTurns(
+						readCurrentSessionEntries(),
+						leafTurnId ? { activeLeafTurnId: leafTurnId } : {},
+					),
 				);
 			} catch (err) {
 				chat.resetForSession(leafTurnId);
@@ -1664,7 +1676,7 @@ export async function bootOrchestrator(options: BootOptions = {}): Promise<BootR
 					? {
 							readSessionEntries: readSessionEntriesForCompact,
 							buildReplayMessages: (entries: ReadonlyArray<SessionEntry>, leafTurnId: string | null) =>
-								buildReplayAgentMessagesFromTurns(entries, leafTurnId === null ? {} : { activeLeafTurnId: leafTurnId }),
+								buildModelReplayAgentMessagesFromTurns(entries, leafTurnId === null ? {} : { activeLeafTurnId: leafTurnId }),
 						}
 					: {}),
 				providers,

package/src/interactive/chat-loop-messages.ts

@@ -555,21 +555,33 @@ export function toolResultSummary(result: unknown): Record<string, unknown> {
 	const bytes = Buffer.byteLength(text, "utf8");
 	const details = recordValue(obj?.details);
 	const size = recordValue(details?.resultSize);
+	const disposition = recordValue(details?.resultDisposition);
 	const truncation = recordValue(details?.truncation);
 	const observation = recordValue(details?.observation);
 	const offloadPath =
-		typeof observation?.offloadPath === "string"
-			? observation.offloadPath
-			: typeof size?.offloadPath === "string"
-				? size.offloadPath
-				: null;
+		typeof disposition?.offloadPath === "string"
+			? disposition.offloadPath
+			: typeof observation?.offloadPath === "string"
+				? observation.offloadPath
+				: typeof size?.offloadPath === "string"
+					? size.offloadPath
+					: null;
+	const displayedBytes =
+		typeof disposition?.displayedBytes === "number" && Number.isFinite(disposition.displayedBytes)
+			? disposition.displayedBytes
+			: bytes;
 	return {
-		bytes,
+		bytes: displayedBytes,
 		truncated:
+			disposition?.presentationTruncated === true ||
 			size?.truncated === true ||
 			truncation?.truncated === true ||
 			observation?.truncated === true ||
 			text.includes("[tool result truncated]"),
+		...(typeof disposition?.capturedBytes === "number" ? { capturedBytes: disposition.capturedBytes } : {}),
+		...(typeof disposition?.displayedBytes === "number" ? { displayedBytes: disposition.displayedBytes } : {}),
+		...(typeof disposition?.contextBytes === "number" ? { contextBytes: disposition.contextBytes } : {}),
+		...(disposition?.contextTruncated === true ? { contextTruncated: true } : {}),
 		...(typeof size?.policy === "string" ? { policy: size.policy } : {}),
 		...(typeof size?.followUpHint === "string" ? { followUpHint: size.followUpHint } : {}),
 		...(offloadPath !== null ? { offloadPath } : {}),