Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
39 changes: 39 additions & 0 deletions src/runtime/adapter-utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<string, unknown> | 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<string, unknown> | null, preferredRuntime: string): string | null => {
if (!snapshot) return null;
const entries = (Array.isArray(snapshot.scopes) ? snapshot.scopes : [snapshot])
Expand Down
4 changes: 2 additions & 2 deletions src/runtime/claude-code-adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ import {
parseArgs,
sanitizeString,
shellQuote,
summarizeHotMemorySnapshot,
summarizeHotMemoryForHandoff,
summarizeJudgmentEntries,
writeManagedFile,
} from "./adapter-utils";
Expand Down Expand Up @@ -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 ?? [],
Expand Down
7 changes: 7 additions & 0 deletions src/runtime/cli/handoff.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -95,6 +96,12 @@ export const handoffFromCli = async (argv: string[]): Promise<string> => {
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.
Expand Down
4 changes: 2 additions & 2 deletions src/runtime/codex-adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ import {
parseArgs,
sanitizeString,
shellQuote,
summarizeHotMemorySnapshot,
summarizeHotMemoryForHandoff,
summarizeJudgmentEntries,
writeManagedFile,
} from "./adapter-utils";
Expand Down Expand Up @@ -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 ?? [],
Expand Down
5 changes: 3 additions & 2 deletions src/runtime/handoff-import.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand Down
19 changes: 18 additions & 1 deletion src/runtime/local-runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -5488,13 +5488,30 @@ 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) {
return "";
}
try {
const parsed = JSON.parse(content) as Record<string, unknown>;
// 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 "<query>" 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))
Expand Down
86 changes: 85 additions & 1 deletion tests/runtime/handoff-cross-machine.test.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand All @@ -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.
Expand Down Expand Up @@ -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<void> => {
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();
Expand Down
Loading