open-multi-agent-kit 0.90.9 → 0.92.0

package/examples/extensions/subagent/adaptive-agent-runtime.ts

@@ -0,0 +1,240 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	attemptOutcome,
+	createBaseResult,
+	finalizeResult,
+	mergeForUpdate,
+	mergeResult,
+	parseProviderModel,
+	resultOutput,
+} from "./adaptive-result.ts";
+import {
+	buildCheckpointTask,
+	checkpointMadeProgress,
+	createCheckpointWorkspace,
+	createEmptyCheckpoint,
+	readCheckpoint,
+	removeCheckpointWorkspace,
+	writeCheckpoint,
+} from "./checkpoint-runtime.ts";
+import {
+	allocateAttemptBudget,
+	type DeadlineProfile,
+	type ExecutionBudget,
+	estimateTaskDemand,
+	planTaskShards,
+	recommendAttemptCutoff,
+	remainingExecutionMs,
+} from "./deadline-budget.ts";
+import type { DeadlineProfileStore } from "./deadline-profile-store.ts";
+import type {
+	DeadlineAttemptMetadata,
+	DeadlineOutcome,
+	SingleResult,
+	SubagentAttemptResult,
+} from "./subagent-runtime-types.ts";
+
+export interface RunAttemptInput {
+	readonly logicalTask: string;
+	readonly task: string;
+	readonly cutoffMs: number;
+	readonly attempt: number;
+	readonly shardId: string;
+	readonly shardIndex: number;
+	readonly shardCount: number;
+	readonly checkpointFilePath: string;
+	readonly onUpdate?: (partial: SingleResult) => void;
+}
+
+interface AdaptiveRuntimePolicy {
+	readonly fallbackAttemptMs: number;
+	readonly minimumAttemptMs: number;
+	readonly maxTokensPerShard: number;
+}
+
+interface RunAdaptiveAgentOptions {
+	readonly agentName: string;
+	readonly agentSource: "user" | "project";
+	readonly logicalTask: string;
+	readonly model?: string;
+	readonly step?: number;
+	readonly signal?: AbortSignal;
+	readonly budget: ExecutionBudget;
+	readonly pendingSequentialTasks: number;
+	readonly checkpointPrefix?: string;
+	readonly profileStore: DeadlineProfileStore;
+	readonly policy: AdaptiveRuntimePolicy;
+	readonly onUpdate?: (partial: SingleResult) => void;
+	readonly runAttempt: (input: RunAttemptInput) => Promise<SubagentAttemptResult>;
+}
+
+export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promise<SingleResult> {
+	const startedAtMs = Date.now();
+	let identity = parseProviderModel(options.model);
+	let profile = await options.profileStore.profileFor(identity.provider, identity.model);
+	const initialCutoff = cutoffFor(profile, options, remainingExecutionMs(options.budget));
+	const demand = estimateTaskDemand(options.logicalTask);
+	const shards = planTaskShards(options.logicalTask, demand, {
+		attemptCutoffMs: initialCutoff,
+		maxTaskShards: options.budget.maxTaskShards,
+		maxTokensPerShard: options.policy.maxTokensPerShard,
+	});
+	const taskAllocation = allocateAttemptBudget({
+		budget: options.budget,
+		pendingSequentialTasks: options.pendingSequentialTasks,
+		pendingShards: 1,
+		recommendedCutoffMs: remainingExecutionMs(options.budget),
+		minimumAttemptMs: 1,
+	});
+	const taskBudget: ExecutionBudget = {
+		...options.budget,
+		hardDeadlineMs: Math.max(1, taskAllocation.taskDeadlineAtMs - startedAtMs),
+		deadlineAtMs: Math.min(options.budget.deadlineAtMs, taskAllocation.taskDeadlineAtMs),
+	};
+	const aggregate = createBaseResult(options);
+	const attempts: DeadlineAttemptMetadata[] = [];
+	const completedShardIds: string[] = [];
+	let resumeCount = 0;
+	let duplicateResumeBlocked = false;
+	let lastCheckpoint: Awaited<ReturnType<typeof readCheckpoint>> | undefined;
+	let terminalOutcome: DeadlineOutcome = "budget-exhausted";
+	const checkpointPrefix = options.checkpointPrefix ?? path.join(os.tmpdir(), "omk-subagent-checkpoint-");
+	const workspace = await createCheckpointWorkspace(checkpointPrefix);
+
+	try {
+		outer: for (const shard of shards) {
+			let shardAttempt = 0;
+			let shardMessageCount = 0;
+			let checkpoint: typeof lastCheckpoint;
+			while (true) {
+				const pendingShards = shards.length - completedShardIds.length;
+				const recommended = cutoffFor(profile, options, remainingExecutionMs(taskBudget));
+				const allocation = allocateAttemptBudget({
+					budget: taskBudget,
+					pendingSequentialTasks: 1,
+					pendingShards,
+					recommendedCutoffMs: recommended,
+					minimumAttemptMs: options.policy.minimumAttemptMs,
+				});
+				if (allocation.cutoffMs === 0 || options.signal?.aborted) {
+					terminalOutcome = options.signal?.aborted ? "aborted" : "budget-exhausted";
+					break outer;
+				}
+
+				const attemptNumber = shardAttempt + 1;
+				const task = buildCheckpointTask({
+					originalTask: options.logicalTask,
+					shardTask: shard.task,
+					shardId: shard.id,
+					shardIndex: shard.index,
+					shardCount: shards.length,
+					attempt: attemptNumber,
+					cutoffMs: allocation.cutoffMs,
+					checkpointFilePath: workspace.filePath,
+					...(checkpoint === undefined ? {} : { checkpoint }),
+				});
+				const attempt = await options.runAttempt({
+					logicalTask: options.logicalTask,
+					task,
+					cutoffMs: allocation.cutoffMs,
+					attempt: attemptNumber,
+					shardId: shard.id,
+					shardIndex: shard.index,
+					shardCount: shards.length,
+					checkpointFilePath: workspace.filePath,
+					onUpdate: options.onUpdate
+						? (partial) => options.onUpdate?.(mergeForUpdate(aggregate, partial))
+						: undefined,
+				});
+				mergeResult(aggregate, attempt.result);
+				shardMessageCount += attempt.result.messages.length;
+				const outcome = attemptOutcome(attempt);
+				const observedIdentity = parseProviderModel(attempt.result.model ?? options.model);
+				if (observedIdentity.provider !== identity.provider || observedIdentity.model !== identity.model) {
+					identity = observedIdentity;
+					profile = await options.profileStore.profileFor(identity.provider, identity.model);
+				}
+				try {
+					profile = await options.profileStore.record({
+						provider: identity.provider,
+						model: identity.model,
+						outcome,
+						elapsedMs: attempt.process.elapsedMs,
+						estimatedTokens: demand.estimatedTokens,
+						workUnits: demand.workUnits,
+					});
+				} catch {
+					profile = await options.profileStore.profileFor(identity.provider, identity.model);
+				}
+				lastCheckpoint = await readCheckpoint(workspace.filePath, {
+					messageCount: shardMessageCount,
+					outputTail: resultOutput(attempt.result),
+					lastEventAtMs: Date.now(),
+				});
+				attempts.push({
+					attempt: attemptNumber,
+					shardId: shard.id,
+					cutoffMs: allocation.cutoffMs,
+					elapsedMs: attempt.process.elapsedMs,
+					outcome,
+					exitCode: attempt.result.exitCode,
+					messageCount: attempt.result.messages.length,
+					processReason: attempt.process.reason,
+					cleanup: attempt.process.cleanup,
+				});
+
+				if (outcome === "completed") {
+					completedShardIds.push(shard.id);
+					terminalOutcome = "completed";
+					checkpoint = undefined;
+					await writeCheckpoint(workspace.filePath, createEmptyCheckpoint());
+					continue outer;
+				}
+				terminalOutcome = outcome;
+				if (outcome !== "cutoff" || resumeCount >= taskBudget.maxResumeAttempts) break outer;
+				if (!checkpointMadeProgress(checkpoint, lastCheckpoint)) {
+					duplicateResumeBlocked = true;
+					break outer;
+				}
+				checkpoint = lastCheckpoint;
+				shardAttempt += 1;
+				resumeCount += 1;
+			}
+		}
+	} finally {
+		await removeCheckpointWorkspace(workspace);
+	}
+
+	const remainingShardIds = shards.map((shard) => shard.id).filter((id) => !completedShardIds.includes(id));
+	if (remainingShardIds.length === 0) terminalOutcome = "completed";
+	finalizeResult(aggregate, terminalOutcome);
+	aggregate.deadline = {
+		outcome: terminalOutcome,
+		startedAtMs,
+		elapsedMs: Date.now() - startedAtMs,
+		hardDeadlineMs: taskBudget.hardDeadlineMs,
+		estimatedTokens: demand.estimatedTokens,
+		workUnits: demand.workUnits,
+		predictedMs: demand.predictedMs,
+		plannedShardIds: shards.map((shard) => shard.id),
+		completedShardIds,
+		remainingShardIds,
+		resumeCount,
+		duplicateResumeBlocked,
+		provider: identity.provider,
+		model: identity.model,
+		profileSamples: profile?.samples ?? 0,
+		attempts,
+		...(lastCheckpoint === undefined ? {} : { checkpoint: lastCheckpoint }),
+	};
+	return aggregate;
+}
+
+function cutoffFor(profile: DeadlineProfile | undefined, options: RunAdaptiveAgentOptions, maximumMs: number): number {
+	return recommendAttemptCutoff(profile, {
+		fallbackMs: options.policy.fallbackAttemptMs,
+		minimumMs: Math.min(options.policy.minimumAttemptMs, maximumMs),
+		maximumMs: Math.max(1, maximumMs),
+	});
+}

package/examples/extensions/subagent/adaptive-result.ts

@@ -0,0 +1,112 @@
+import type { Message } from "omk-ai";
+import {
+	type DeadlineOutcome,
+	emptyUsage,
+	type SingleResult,
+	type SubagentAttemptResult,
+	type UsageStats,
+} from "./subagent-runtime-types.ts";
+
+interface BaseResultOptions {
+	readonly agentName: string;
+	readonly agentSource: "user" | "project";
+	readonly logicalTask: string;
+	readonly model?: string;
+	readonly step?: number;
+}
+
+export function createBaseResult(options: BaseResultOptions): SingleResult {
+	return {
+		agent: options.agentName,
+		agentSource: options.agentSource,
+		task: options.logicalTask,
+		exitCode: 0,
+		messages: [],
+		stderr: "",
+		usage: emptyUsage(),
+		model: options.model,
+		step: options.step,
+	};
+}
+
+export function attemptOutcome(attempt: SubagentAttemptResult): Exclude<DeadlineOutcome, "budget-exhausted"> {
+	if (attempt.process.reason === "cutoff") return "cutoff";
+	if (attempt.process.reason === "aborted") return "aborted";
+	return attempt.result.exitCode === 0 && attempt.result.stopReason !== "error" ? "completed" : "failed";
+}
+
+export function mergeResult(target: SingleResult, source: SingleResult): void {
+	target.messages.push(...source.messages);
+	target.stderr = [target.stderr, source.stderr].filter(Boolean).join("\n");
+	target.usage = mergeUsage(target.usage, source.usage);
+	target.output = mergeOutput(target.output ?? "", resultOutput(source));
+	target.exitCode = source.exitCode;
+	target.stopReason = source.stopReason;
+	target.errorMessage = source.errorMessage;
+	target.model = source.model ?? target.model;
+}
+
+export function mergeForUpdate(base: SingleResult, partial: SingleResult): SingleResult {
+	const merged: SingleResult = { ...base, messages: [...base.messages], usage: { ...base.usage } };
+	mergeResult(merged, partial);
+	return merged;
+}
+
+export function resultOutput(result: SingleResult): string {
+	if (result.output !== undefined) return result.output;
+	for (let index = result.messages.length - 1; index >= 0; index--) {
+		const message: Message = result.messages[index];
+		if (message.role !== "assistant") continue;
+		for (const part of message.content) if (part.type === "text") return part.text;
+	}
+	return "";
+}
+
+export function finalizeResult(result: SingleResult, outcome: DeadlineOutcome): void {
+	if (outcome === "completed") {
+		result.exitCode = 0;
+		result.stopReason = "end";
+		result.errorMessage = undefined;
+		return;
+	}
+	if (outcome === "failed") {
+		result.exitCode = Math.max(1, result.exitCode);
+		result.stopReason = "error";
+		result.errorMessage ??= "Subagent process failed";
+		return;
+	}
+	result.exitCode = outcome === "aborted" ? 130 : 124;
+	result.stopReason = outcome === "aborted" ? "aborted" : "deadline";
+	result.errorMessage ??=
+		outcome === "budget-exhausted" ? "Subagent execution budget exhausted" : "Subagent deadline cutoff";
+}
+
+export function parseProviderModel(value: string | undefined): { provider: string; model: string } {
+	if (!value) return { provider: "unknown", model: "default" };
+	const separator = value.indexOf("/");
+	return separator < 1
+		? { provider: "unknown", model: value }
+		: { provider: value.slice(0, separator), model: value.slice(separator + 1) || "default" };
+}
+
+function mergeUsage(left: UsageStats, right: UsageStats): UsageStats {
+	return {
+		input: left.input + right.input,
+		output: left.output + right.output,
+		cacheRead: left.cacheRead + right.cacheRead,
+		cacheWrite: left.cacheWrite + right.cacheWrite,
+		cost: left.cost + right.cost,
+		contextTokens: Math.max(left.contextTokens, right.contextTokens),
+		turns: left.turns + right.turns,
+	};
+}
+
+function mergeOutput(left: string, right: string): string {
+	if (right === "" || left === right || left.endsWith(right)) return left;
+	if (left === "") return right;
+	const maxOverlap = Math.min(left.length, right.length, 4_096);
+	for (let overlap = maxOverlap; overlap > 0; overlap--) {
+		if (left.endsWith(right.slice(0, overlap))) return `${left}${right.slice(overlap)}`;
+	}
+	return `${left}\n\n${right}`;
+}

package/examples/extensions/subagent/checkpoint-runtime.test.ts

@@ -0,0 +1,125 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	buildCheckpointTask,
+	checkpointMadeProgress,
+	createCheckpointWorkspace,
+	readCheckpoint,
+	removeCheckpointWorkspace,
+} from "./checkpoint-runtime.ts";
+
+const cleanupPaths: string[] = [];
+
+afterEach(async () => {
+	await Promise.all(cleanupPaths.splice(0).map((entry) => fs.promises.rm(entry, { force: true, recursive: true })));
+});
+
+describe("subagent checkpoint runtime", () => {
+	it("loads a bounded, typed checkpoint written by a child", async () => {
+		const workspace = await createCheckpointWorkspace(path.join(os.tmpdir(), "omk-checkpoint-test-"));
+		cleanupPaths.push(workspace.dir);
+		await fs.promises.writeFile(
+			workspace.filePath,
+			JSON.stringify({
+				version: 1,
+				completed: ["inspect boundary"],
+				remaining: ["add tests"],
+				summary: "boundary inspected",
+				artifacts: ["src/runtime.ts"],
+			}),
+			"utf8",
+		);
+
+		const checkpoint = await readCheckpoint(workspace.filePath, {
+			messageCount: 3,
+			outputTail: "stream tail",
+			lastEventAtMs: 123,
+		});
+
+		expect(checkpoint).toMatchObject({
+			completed: ["inspect boundary"],
+			remaining: ["add tests"],
+			summary: "boundary inspected",
+			artifacts: ["src/runtime.ts"],
+			messageCount: 3,
+			outputTail: "stream tail",
+			lastEventAtMs: 123,
+		});
+	});
+
+	it("rejects a checkpoint path replaced with a symbolic link", async () => {
+		const workspace = await createCheckpointWorkspace(path.join(os.tmpdir(), "omk-checkpoint-symlink-"));
+		cleanupPaths.push(workspace.dir);
+		const targetPath = path.join(workspace.dir, "target.json");
+		await fs.promises.writeFile(
+			targetPath,
+			JSON.stringify({ version: 1, completed: ["untrusted target"], remaining: [], summary: "leak", artifacts: [] }),
+			"utf8",
+		);
+		await fs.promises.rm(workspace.filePath);
+		await fs.promises.symlink(targetPath, workspace.filePath);
+
+		const checkpoint = await readCheckpoint(workspace.filePath, {
+			messageCount: 0,
+			outputTail: "",
+			lastEventAtMs: 0,
+		});
+
+		expect(checkpoint.completed).toEqual([]);
+		expect(checkpoint.summary).toBe("");
+	});
+
+	it("builds a bounded resume prompt that forbids replaying completed side effects", () => {
+		const hugeTail = `old-output-${"x".repeat(20_000)}`;
+		const prompt = buildCheckpointTask({
+			originalTask: "Implement the deadline runtime.",
+			shardTask: "Add the process cleanup path.",
+			shardId: "shard-2",
+			shardIndex: 1,
+			shardCount: 3,
+			attempt: 2,
+			cutoffMs: 30_000,
+			checkpointFilePath: "/tmp/checkpoint.json",
+			checkpoint: {
+				version: 1,
+				completed: ["sent SIGTERM"],
+				remaining: ["verify SIGKILL"],
+				summary: "graceful termination implemented",
+				artifacts: ["process-runtime.ts"],
+				messageCount: 4,
+				outputTail: hugeTail,
+				lastEventAtMs: 100,
+			},
+		});
+
+		expect(prompt).toContain("Do not repeat completed side effects");
+		expect(prompt).toContain("sent SIGTERM");
+		expect(prompt).toContain("verify SIGKILL");
+		expect(prompt).toContain("Only unresolved checkpoint units");
+		expect(prompt).not.toContain("Add the process cleanup path.");
+		expect(prompt.length).toBeLessThan(12_000);
+	});
+
+	it("blocks duplicate resume when neither checkpoint nor streamed evidence advanced", () => {
+		const before = {
+			version: 1 as const,
+			completed: ["a"],
+			remaining: ["b"],
+			summary: "same",
+			artifacts: [],
+			messageCount: 2,
+			outputTail: "same tail",
+			lastEventAtMs: 10,
+		};
+		expect(checkpointMadeProgress(before, { ...before })).toBe(false);
+		expect(checkpointMadeProgress(before, { ...before, messageCount: 3 })).toBe(true);
+	});
+
+	it("removes checkpoint artifacts after the logical task settles", async () => {
+		const workspace = await createCheckpointWorkspace(path.join(os.tmpdir(), "omk-checkpoint-cleanup-"));
+		await removeCheckpointWorkspace(workspace);
+		expect(fs.existsSync(workspace.dir)).toBe(false);
+	});
+});

package/examples/extensions/subagent/checkpoint-runtime.ts

@@ -0,0 +1,198 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface CheckpointWorkspace {
+	readonly dir: string;
+	readonly filePath: string;
+}
+
+export interface AgentCheckpoint {
+	readonly version: 1;
+	readonly completed: readonly string[];
+	readonly remaining: readonly string[];
+	readonly summary: string;
+	readonly artifacts: readonly string[];
+	readonly messageCount: number;
+	readonly outputTail: string;
+	readonly lastEventAtMs: number;
+}
+
+interface CheckpointEvidence {
+	readonly messageCount: number;
+	readonly outputTail: string;
+	readonly lastEventAtMs: number;
+}
+
+interface BuildCheckpointTaskOptions {
+	readonly originalTask: string;
+	readonly shardTask: string;
+	readonly shardId: string;
+	readonly shardIndex: number;
+	readonly shardCount: number;
+	readonly attempt: number;
+	readonly cutoffMs: number;
+	readonly checkpointFilePath: string;
+	readonly checkpoint?: AgentCheckpoint;
+}
+
+const CHECKPOINT_FILE_LIMIT = 32 * 1024;
+const MAX_LIST_ITEMS = 24;
+const MAX_ITEM_CHARS = 512;
+
+export async function createCheckpointWorkspace(prefix: string): Promise<CheckpointWorkspace> {
+	const dir = await fs.promises.mkdtemp(prefix);
+	const filePath = path.join(dir, "checkpoint.json");
+	await writeCheckpoint(filePath, createEmptyCheckpoint());
+	return { dir, filePath };
+}
+
+export async function removeCheckpointWorkspace(workspace: CheckpointWorkspace): Promise<void> {
+	await fs.promises.rm(workspace.dir, { recursive: true, force: true });
+}
+
+export async function writeCheckpoint(filePath: string, checkpoint: AgentCheckpoint): Promise<void> {
+	const serialized = JSON.stringify({
+		version: 1,
+		completed: checkpoint.completed,
+		remaining: checkpoint.remaining,
+		summary: checkpoint.summary,
+		artifacts: checkpoint.artifacts,
+	});
+	await fs.promises.writeFile(filePath, serialized, { encoding: "utf8", mode: 0o600 });
+}
+
+export async function readCheckpoint(filePath: string, evidence: CheckpointEvidence): Promise<AgentCheckpoint> {
+	let parsed: unknown;
+	try {
+		const pathStats = await fs.promises.lstat(filePath);
+		if (!pathStats.isFile() || pathStats.isSymbolicLink()) return withEvidence(createEmptyCheckpoint(), evidence);
+		const handle = await fs.promises.open(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+		try {
+			const stats = await handle.stat();
+			if (stats.size > CHECKPOINT_FILE_LIMIT) return withEvidence(createEmptyCheckpoint(), evidence);
+			parsed = JSON.parse(await handle.readFile("utf8"));
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		return withEvidence(createEmptyCheckpoint(), evidence);
+	}
+	if (!isRecord(parsed) || parsed.version !== 1) return withEvidence(createEmptyCheckpoint(), evidence);
+	return withEvidence(
+		{
+			version: 1,
+			completed: readStringList(parsed.completed),
+			remaining: readStringList(parsed.remaining),
+			summary: readString(parsed.summary, 2_000),
+			artifacts: readStringList(parsed.artifacts),
+			messageCount: 0,
+			outputTail: "",
+			lastEventAtMs: 0,
+		},
+		evidence,
+	);
+}
+
+export function buildCheckpointTask(options: BuildCheckpointTaskOptions): string {
+	const prior = options.checkpoint;
+	const currentTask =
+		prior !== undefined && prior.remaining.length > 0
+			? [
+					"Only unresolved checkpoint units:",
+					...prior.remaining.map((unit, index) => `${index + 1}. ${boundedTail(unit, 512)}`),
+				].join("\n")
+			: boundedTail(options.shardTask, 3_500);
+	const priorSection = prior
+		? [
+				"Resume checkpoint:",
+				`- Completed: ${formatList(prior.completed)}`,
+				`- Remaining: ${formatList(prior.remaining)}`,
+				`- Summary: ${boundedTail(prior.summary, 1_500) || "(none)"}`,
+				`- Artifacts: ${formatList(prior.artifacts)}`,
+				`- Last streamed evidence: ${boundedTail(prior.outputTail, 2_500) || "(none)"}`,
+			]
+		: ["No prior checkpoint exists for this shard."];
+	return [
+		"[OMK deadline/checkpoint execution contract]",
+		`Execution shard: ${options.shardId} (${options.shardIndex + 1}/${options.shardCount}), attempt ${options.attempt}.`,
+		`This attempt has about ${options.cutoffMs}ms. Work in small, complete semantic units.`,
+		`After each completed unit, overwrite ${options.checkpointFilePath} with JSON:`,
+		'{"version":1,"completed":["..."],"remaining":["..."],"summary":"...","artifacts":["..."]}',
+		"Only checkpoint work that is actually complete. Keep each field concise.",
+		"On resume, inspect the current workspace first. Do not repeat completed side effects or rerun expensive discovery already evidenced below.",
+		...priorSection,
+		"",
+		"Original logical task (context only):",
+		boundedTail(options.originalTask, 2_500),
+		"",
+		"Current shard:",
+		currentTask,
+		"Return a self-contained result for this shard.",
+	].join("\n");
+}
+
+export function checkpointMadeProgress(before: AgentCheckpoint | undefined, after: AgentCheckpoint): boolean {
+	if (before === undefined) {
+		return after.messageCount > 0 || after.completed.length > 0 || after.summary !== "" || after.outputTail !== "";
+	}
+	return (
+		after.messageCount > before.messageCount ||
+		after.outputTail !== before.outputTail ||
+		after.summary !== before.summary ||
+		!arrayEquals(after.completed, before.completed) ||
+		!arrayEquals(after.remaining, before.remaining) ||
+		!arrayEquals(after.artifacts, before.artifacts)
+	);
+}
+
+export function boundedTail(value: string, maxChars: number): string {
+	if (value.length <= maxChars) return value;
+	return `[...${value.length - maxChars} earlier chars omitted...]\n${value.slice(-maxChars)}`;
+}
+
+export function createEmptyCheckpoint(): AgentCheckpoint {
+	return {
+		version: 1,
+		completed: [],
+		remaining: [],
+		summary: "",
+		artifacts: [],
+		messageCount: 0,
+		outputTail: "",
+		lastEventAtMs: 0,
+	};
+}
+
+function withEvidence(checkpoint: AgentCheckpoint, evidence: CheckpointEvidence): AgentCheckpoint {
+	return {
+		...checkpoint,
+		messageCount: Math.max(0, evidence.messageCount),
+		outputTail: boundedTail(evidence.outputTail, 4_000),
+		lastEventAtMs: Math.max(0, evidence.lastEventAtMs),
+	};
+}
+
+function readStringList(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return value
+		.filter((item): item is string => typeof item === "string")
+		.map((item) => readString(item, MAX_ITEM_CHARS))
+		.filter((item) => item !== "")
+		.slice(0, MAX_LIST_ITEMS);
+}
+
+function readString(value: unknown, maxChars: number): string {
+	return typeof value === "string" ? value.trim().slice(0, maxChars) : "";
+}
+
+function formatList(values: readonly string[]): string {
+	return values.length === 0 ? "(none)" : values.map((value) => boundedTail(value, 256)).join("; ");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function arrayEquals(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}