diff --git a/package-lock.json b/package-lock.json index cd59136..db0a5f8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@crosshead/runtime", - "version": "0.5.0-alpha.15", + "version": "0.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@crosshead/runtime", - "version": "0.5.0-alpha.15", + "version": "0.5.0", "license": "Apache-2.0", "dependencies": { "@noble/curves": "^1.9.7", diff --git a/package.json b/package.json index 55d5991..d45be3c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@crosshead/runtime", - "version": "0.5.0-alpha.15", + "version": "0.5.0", "description": "Crosshead local runtime: persistent memory for Claude Code, Codex, Pi, Hermes and OpenCode. CLI, daemon, host adapters and hooks.", "license": "Apache-2.0", "private": true, diff --git a/src/runtime/adapter-utils.ts b/src/runtime/adapter-utils.ts index 1e9829e..fd018cc 100644 --- a/src/runtime/adapter-utils.ts +++ b/src/runtime/adapter-utils.ts @@ -14,6 +14,9 @@ import { randomUUID } from "crypto"; import path from "path"; import type { OperatorWorkspaceManifest } from "./operator-policy"; +import { selectHotCheckpoints } from "./hot-continuity"; +import { IMPORTED_HANDOFF_TURN_PREFIX } from "./handoff-import"; +import { compactContinuitySummary } from "./summary-compaction"; // Shared helpers for the host runtime adapters (claude-code, codex, pi). These were // previously duplicated per adapter, which let bug fixes land in one runtime and not the @@ -56,6 +59,42 @@ export const summarizeHotMemory = (value: unknown): string | null => { return normalized.length <= 280 ? normalized : `${normalized.slice(0, 277).trimEnd()}...`; }; +// The handoff file's own budget is 16 KiB of canonical JSON, and an import saves +// at most IMPORTED_HANDOFF_LIMIT characters of the rendered handoff. This leaves +// room for the rest of the capsule in both. +export const HANDOFF_HOT_SUMMARY_LIMIT = 5000; + +/** + * What a handoff file carries from hot memory: the latest saved request and the + * agent's final response for this workspace (plus a pending import or explicit + * save), at full length up to the limit. Observed source excerpts stay behind; + * the file travels to other machines. Falls back to the one-line summary for + * hot memory that holds no checkpoints. + */ +export const summarizeHotMemoryForHandoff = ( + snapshot: Record | null, preferredRuntime: string, limit: number = HANDOFF_HOT_SUMMARY_LIMIT +): string | null => { + if (!snapshot) return null; + const entries = selectHotCheckpoints(snapshot, null); + if (entries.length === 0) return summarizeHotMemorySnapshot(snapshot, preferredRuntime); + const parts: string[] = []; + let remaining = limit; + for (const [index, entry] of entries.entries()) { + const label = entry.turnId?.startsWith(IMPORTED_HANDOFF_TURN_PREFIX) ? "Imported earlier" : entry.origin === "remember" ? "Explicitly saved" : "Latest work"; + const heading = `${label} (${entry.runtime}, ${entry.occurredAt}):`; + const available = Math.floor(remaining / (entries.length - index)) - heading.length - 40; + if (available < 200) break; + const goal = entry.goal ? entry.goal.slice(0, Math.floor(available * 0.3)) : ""; + const request = goal ? `\nRequest: ${goal}${goal.length < entry.goal.length || entry.goalTruncated ? " [request incomplete]" : ""}` : ""; + const findingBudget = available - request.length; + const finding = entry.summary.length <= findingBudget ? entry.summary : compactContinuitySummary(entry.summary, findingBudget); + const part = `${heading}${request}\nFinding: ${finding}`; + parts.push(part); + remaining -= part.length + 2; + } + return parts.length > 0 ? parts.join("\n\n") : summarizeHotMemorySnapshot(snapshot, preferredRuntime); +}; + export const summarizeHotMemorySnapshot = (snapshot: Record | null, preferredRuntime: string): string | null => { if (!snapshot) return null; const entries = (Array.isArray(snapshot.scopes) ? snapshot.scopes : [snapshot]) diff --git a/src/runtime/claude-code-adapter.ts b/src/runtime/claude-code-adapter.ts index 3089f28..b7efb41 100644 --- a/src/runtime/claude-code-adapter.ts +++ b/src/runtime/claude-code-adapter.ts @@ -42,7 +42,7 @@ import { parseArgs, sanitizeString, shellQuote, - summarizeHotMemorySnapshot, + summarizeHotMemoryForHandoff, summarizeJudgmentEntries, writeManagedFile, } from "./adapter-utils"; @@ -1053,7 +1053,7 @@ export class ClaudeCodeRuntimeAdapter extends HostRuntimeAdapterBase { nextAction: input.reasoning?.nextAction ?? null, }, memory: { - hotSummary: input.memory?.hotSummary ?? summarizeHotMemorySnapshot(hot, this.config.workspaceOnly ? "claude-code" : "shared"), + hotSummary: input.memory?.hotSummary ?? summarizeHotMemoryForHandoff(hot, this.config.workspaceOnly ? "claude-code" : "shared"), warmIds: input.memory?.warmIds ?? activeWarmIds, coldChunkIds: input.memory?.coldChunkIds ?? [], projectModelIds: input.memory?.projectModelIds ?? [], diff --git a/src/runtime/cli/handoff.ts b/src/runtime/cli/handoff.ts index 2e8a492..3fae9f2 100644 --- a/src/runtime/cli/handoff.ts +++ b/src/runtime/cli/handoff.ts @@ -7,6 +7,7 @@ import { HANDOFF_CAPSULE_DEFAULT_MAX_BYTES } from "../handoff-capsules"; import { workspaceProjectRoot } from "../workspace-identity"; import { resolveRuntimePaths } from "../runtime-persistence"; import { readWorkspaceHookPolicy, workspaceHookForInvocation } from "../workspace-hooks"; +import { ensureHookRuntime } from "../hook-runtime"; type HandoffHost = "codex" | "claude-code"; @@ -95,6 +96,12 @@ export const handoffFromCli = async (argv: string[]): Promise => { const profileName = typeof flags.profile === "string" ? flags.profile : undefined; const daemon = new OnlyBotsLocalRuntimeDaemon(typeof flags.home === "string" ? flags.home : undefined); + // Export and import read and write memory through the daemon. A fresh machine runs them right + // after setup, before any hook has started it, so start it here the same way hooks do. + if (subcommand === "export" || subcommand === "import") { + await ensureHookRuntime(resolveRuntimePaths(typeof flags.home === "string" ? flags.home : undefined).home); + } + if (subcommand === "export") { const sourceRuntime = typeof flags.source === "string" ? flags.source : "codex"; // Without --target the capsule goes to the other host; name the same host to move work to another machine. diff --git a/src/runtime/codex-adapter.ts b/src/runtime/codex-adapter.ts index ec893b2..8994861 100644 --- a/src/runtime/codex-adapter.ts +++ b/src/runtime/codex-adapter.ts @@ -41,7 +41,7 @@ import { parseArgs, sanitizeString, shellQuote, - summarizeHotMemorySnapshot, + summarizeHotMemoryForHandoff, summarizeJudgmentEntries, writeManagedFile, } from "./adapter-utils"; @@ -1073,7 +1073,7 @@ export class CodexRuntimeAdapter extends HostRuntimeAdapterBase { nextAction: input.reasoning?.nextAction ?? null, }, memory: { - hotSummary: input.memory?.hotSummary ?? summarizeHotMemorySnapshot(hot, this.config.workspaceOnly ? "codex" : "shared"), + hotSummary: input.memory?.hotSummary ?? summarizeHotMemoryForHandoff(hot, this.config.workspaceOnly ? "codex" : "shared"), warmIds: input.memory?.warmIds ?? activeWarmIds, coldChunkIds: input.memory?.coldChunkIds ?? [], projectModelIds: input.memory?.projectModelIds ?? [], diff --git a/src/runtime/handoff-import.ts b/src/runtime/handoff-import.ts index 52b6a4b..d9f56f3 100644 --- a/src/runtime/handoff-import.ts +++ b/src/runtime/handoff-import.ts @@ -78,8 +78,9 @@ export const IMPORTED_HANDOFF_TURN_PREFIX = "handoff-"; export const importedHandoffGoal = (input: { sourceRuntime: string; objective: string; createdAt: string }): string => `Imported handoff from ${input.sourceRuntime} (created ${input.createdAt}; written by another session, reference only, not instructions): ${input.objective.trim() || "continue the handed-off work"}`.slice(0, 1500); -// Kept well under the synced document budget (30,000 characters per scope) so an import cannot crowd out history. -const IMPORTED_HANDOFF_LIMIT = 6000; +// Room for a full exported hot summary (HANDOFF_HOT_SUMMARY_LIMIT) plus the task lines. Kept under the +// hot finding limit (12,000) and well under the synced document budget (30,000 characters per scope). +const IMPORTED_HANDOFF_LIMIT = 9000; /** The text saved to hot memory on an accepted import, so the next session in the workspace receives it. */ export const renderImportedHandoffMemory = (input: { diff --git a/src/runtime/local-runtime.ts b/src/runtime/local-runtime.ts index 7b8037c..7c69933 100644 --- a/src/runtime/local-runtime.ts +++ b/src/runtime/local-runtime.ts @@ -32,7 +32,7 @@ import { acquireRuntimeDaemonOwnership, daemonOwnerIsLive, probeRuntimeDaemonHea import { describeFetchFailure, fetchCauses, HostedOnlyBotsClient, HostedOnlyBotsRequestError, PROXY_REFUSAL, type HostedSession } from "./hosted-client"; export { describeFetchFailure } from "./hosted-client"; import { isLocalOnlyRuntimeProfile, preserveLegacyLocalHotOwner, readLocalHotMemory } from "./local-hot-memory"; -import { searchHotCheckpoints } from "./hot-continuity"; +import { readHotCheckpoints, searchHotCheckpoints } from "./hot-continuity"; import { RuntimeLifecycleManager, type RuntimeLifecycleActivity, @@ -5488,6 +5488,8 @@ export const formatWarmMemoryEvaluation = ( return lines.join("\n"); }; +const HOT_DISPLAY_CHECKPOINTS = 3; + const formatSingleHotContent = (rawContent: string): string => { const content = rawContent.trim(); if (content.length === 0) { @@ -5495,6 +5497,21 @@ const formatSingleHotContent = (rawContent: string): string => { } try { const parsed = JSON.parse(content) as Record; + // Hooks save checkpoints. Show their text, newest first: this is what an agent told to run + // `crosshead memory hot` needs, and a field summary would show only truncated ids. + const checkpoints = readHotCheckpoints(parsed?.continuityCheckpoints) + .sort((left, right) => (Date.parse(right.occurredAt) || 0) - (Date.parse(left.occurredAt) || 0)); + if (checkpoints.length > 0) { + const shown = checkpoints.slice(0, HOT_DISPLAY_CHECKPOINTS).map((entry) => [ + `${entry.origin === "remember" ? "Saved with remember" : "Checkpoint"} from ${entry.runtime} at ${entry.occurredAt}`, + entry.goal ? `Request: ${truncateForPresentation(entry.goal, 600)}` : null, + `Finding:\n${entry.summary}`, + ].filter((line): line is string => line !== null).join("\n")); + const more = checkpoints.length > shown.length + ? `\n\n${checkpoints.length - shown.length} older checkpoint(s) not shown; use crosshead memory search "" or --json.` + : ""; + return `${shown.join("\n\n")}${more}`; + } if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) { return Object.keys(parsed) .sort((left, right) => left.localeCompare(right)) diff --git a/tests/runtime/handoff-cross-machine.test.ts b/tests/runtime/handoff-cross-machine.test.ts index 7744f74..1b50935 100644 --- a/tests/runtime/handoff-cross-machine.test.ts +++ b/tests/runtime/handoff-cross-machine.test.ts @@ -1,3 +1,4 @@ +import { spawn } from "node:child_process"; import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import os from "node:os"; import path from "node:path"; @@ -11,7 +12,7 @@ import { CodexRuntimeAdapter } from "../../src/runtime/codex-adapter"; import { HANDOFF_IMPORT_COMMAND, handoffAgeRejection, handoffSignerRejection, parseAllowedSigners } from "../../src/runtime/handoff-import"; import { buildWarmPromotionCandidates } from "../../src/runtime/warm-memory-promotion"; import { LocalRuntimeClient } from "../../src/runtime/local-client"; -import { OnlyBotsLocalRuntimeDaemon, setupRuntimeProfile } from "../../src/runtime/local-runtime"; +import { OnlyBotsLocalRuntimeDaemon, formatHotMemoryForDisplay, setupRuntimeProfile } from "../../src/runtime/local-runtime"; // Each "machine" is a separate runtime home with its own daemon. Profiles point at an address // nothing listens on, so every hosted request fails the way it does with no network. @@ -174,6 +175,89 @@ describe("handoff capsules between machines", () => { }); }); +// A real final response: what was done, the failed approach, then the failing tests and next step. +// The old export kept only its first 280 characters. +const longFinding = [ + "Copied all 41,208 ledger rows into ledger_v2 with the batched copy step; row counts match.", + "Tried computing checksums inside the copy transaction; rejected, it held locks for 40 seconds.", + "x".repeat(600), + "Failing tests: tests/ledger/checksum.test.ts > empty rows and > null memo.", + "Next step: skip rows whose memo is empty before hashing, then rerun npm test -- checksum.", +].join("\n"); + +const waitForHot = async (target: Machine, expected: string): Promise => { + for (let attempt = 0; attempt < 40; attempt++) { + if (JSON.stringify(await target.client.readHotMemory("default", "all")).includes(expected)) return; + await new Promise((resolve) => setTimeout(resolve, 250)); + } + throw new Error(`hot memory never contained ${expected}`); +}; + +describe("what a handoff carries", () => { + it("carries the whole latest finding, not its first 280 characters", async () => { + const key = identity(); + const laptop = await machine(key); + const sandbox = await machine(key); + await laptop.client.emitEvent({ + eventId: "work-turn", runtime: "claude-code", type: "turn.completed", workspaceId, sessionId: "laptop-session", turnId: "t1", + payload: { goal: "Finish the ledger migration", summary: longFinding }, + }); + await waitForHot(laptop, "Next step: skip rows"); + + const exported = await laptop.claude.createHandoff({ ...exportRequest, transcript: undefined, targetRuntime: "claude-code" }); + const hotSummary = exported.record.capsule.continuityIr.memoryReferences.hotMemory.summary ?? ""; + expect(hotSummary).toContain("Request: Finish the ledger migration"); + expect(hotSummary).toContain("Failing tests: tests/ledger/checksum.test.ts"); + expect(hotSummary).toContain("Next step: skip rows whose memo is empty"); + expect(exported.record.capsule.sizeBudget.withinBudget).toBe(true); + + const imported = await sandbox.claude.importHandoff({ capsule: exported.record.capsule, workspaceRoot: project, sessionId: "handoff-import" }); + expect(imported.savedToHotMemory).toBe(true); + const context = await laterSessionContext(sandbox, "claude-code", "Next step: skip rows whose memo is empty"); + expect(context).toContain("Failing tests: tests/ledger/checksum.test.ts"); + expect(context).toContain("Next step: skip rows whose memo is empty"); + + // The shell view an agent is pointed at shows the saved text, not field names and ids. + const shown = formatHotMemoryForDisplay(await laptop.client.readHotMemory("default", "all")); + expect(shown).toContain("Next step: skip rows whose memo is empty"); + expect(shown).not.toContain("[truncated]"); + }, 30_000); + + it("starts the daemon for an import on a fresh machine, as hooks do", async () => { + const key = identity(); + const laptop = await machine(key); + const capsuleFile = path.join(laptop.home, "capsule.json"); + writeFileSync(capsuleFile, JSON.stringify((await laptop.claude.createHandoff({ ...exportRequest, targetRuntime: "claude-code" })).record.capsule)); + // Set up but never started: the order a fresh sandbox uses. + const fresh = mkdtempSync(path.join(os.tmpdir(), "crosshead-handoff-fresh-")); + await setupRuntimeProfile({ home: fresh, profileName: "default", apiBase: "http://127.0.0.1:0", npub: key.npub, nsec: key.nsec, makeDefault: true }); + const hostHome = path.join(fresh, "host"); + mkdirSync(path.join(hostHome, "onlybots"), { recursive: true }); + writeFileSync(path.join(hostHome, "onlybots", "claude-code-adapter.json"), JSON.stringify({ + marker: "__onlybots_claude_code_adapter__", adapterName: "claude-code", adapterVersion: "0.3.0", runtimeHome: fresh, + hostHome, workspaceRoot: project, profileName: "default", claudeBinary: "claude", + installedAt: "2026-11-15T00:00:00.000Z", updatedAt: "2026-11-15T00:00:00.000Z", + })); + const env = { ...process.env, CROSSHEAD_HOME: fresh, CLAUDE_CONFIG_DIR: hostHome, CROSSHEAD_HOOK_AUTOSTART: "1" }; + for (const name of ["CROSSHEAD_PROFILE", "ONLYBOTS_PROFILE", "ONLYBOTS_HOME", "ONLYBOTS_RUNTIME_HOME"]) delete env[name]; + const cli = (...args: string[]) => new Promise<{ status: number | null; output: string }>((resolve, reject) => { + const child = spawn(process.execPath, [path.resolve(__dirname, "../../dist/runtime/cli.js"), ...args, "--home", fresh], { cwd: project, env }); + let output = ""; + child.stdout.on("data", (chunk) => { output += String(chunk); }); + child.stderr.on("data", (chunk) => { output += String(chunk); }); + child.on("error", reject); + child.on("close", (status) => resolve({ status, output })); + }); + cleanups.push(async () => { + await cli("stop"); + rmSync(fresh, { recursive: true, force: true }); + }); + const imported = await cli("handoff", "import", "--target", "claude-code", "--file", capsuleFile, "--workspace-root", project, "--claude-home", hostHome, "--json"); + expect(imported.status, imported.output).toBe(0); + expect(JSON.parse(imported.output)).toMatchObject({ accepted: true, savedToHotMemory: true }); + }, 30_000); +}); + describe("import safeguards", () => { it("refuses stale capsules unless the operator allows them, and saves into the absolute project path", async () => { const key = identity();