Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
import * as NodeFS from "node:fs";
import * as NodeOS from "node:os";
import * as NodePath from "node:path";
import { ProviderDriverKind } from "@akeru/contracts";
import {
CommandId,
CheckpointRef,
DEFAULT_PROVIDER_INTERACTION_MODE,
EventId,
MessageId,
ThreadId,
} from "@akeru/contracts";
import { it as effectIt } from "@effect/vitest";
import * as Effect from "effect/Effect";
import { afterEach, describe, expect, it } from "vite-plus/test";
import { checkpointRefForThreadTurn } from "../../checkpointing/Utils.ts";
import {
asTurnId,
waitForGitRefExists,
waitForThread,
waitForEvent,
gitRefExists,
gitShowFileAtRef,
runGit,
createCheckpointHarness,
} from "./test-support/CheckpointHarness.ts";
describe("CheckpointReactor", () => {
const testScope = createCheckpointHarness();
const { createHarness, tempDirs } = testScope;
afterEach(testScope.dispose);
it("ignores auxiliary thread turn completion while primary turn is active", async () => {
const harness = await createHarness({ seedFilesystemCheckpoints: false });
const createdAt = "2026-01-01T00:00:00.000Z";
await harness.run(
harness.engine.dispatch({
type: "thread.session.set",
commandId: CommandId.make("cmd-session-set-primary-running"),
threadId: ThreadId.make("thread-1"),
session: {
threadId: ThreadId.make("thread-1"),
status: "running",
providerName: "codex",
runtimeMode: "approval-required",
activeTurnId: asTurnId("turn-main"),
lastError: null,
updatedAt: createdAt,
},
createdAt,
}),
);
harness.provider.emit({
type: "turn.started",
eventId: EventId.make("evt-turn-started-main"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-main"),
});
await waitForGitRefExists(
harness,
harness.cwd,
checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0),
);
NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "v2\n", "utf8");
harness.provider.emit({
type: "turn.completed",
eventId: EventId.make("evt-turn-completed-aux"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-aux"),
payload: { state: "completed" },
});
await harness.drain();
const midReadModel = await harness.readModel();
const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
expect(midThread?.checkpoints).toHaveLength(0);
harness.provider.emit({
type: "turn.completed",
eventId: EventId.make("evt-turn-completed-main"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-main"),
payload: { state: "completed" },
});
const thread = await waitForThread(
harness,
(entry) => entry.latestTurn?.turnId === "turn-main" && entry.checkpoints.length === 1,
);
expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
});
it("captures pre-turn and completion checkpoints for claude runtime events", async () => {
const harness = await createHarness({
seedFilesystemCheckpoints: false,
providerName: ProviderDriverKind.make("claudeAgent"),
});
const createdAt = "2026-01-01T00:00:00.000Z";
await harness.run(
harness.engine.dispatch({
type: "thread.session.set",
commandId: CommandId.make("cmd-session-set-capture-claude"),
threadId: ThreadId.make("thread-1"),
session: {
threadId: ThreadId.make("thread-1"),
status: "ready",
providerName: "claudeAgent",
runtimeMode: "approval-required",
activeTurnId: null,
lastError: null,
updatedAt: createdAt,
},
createdAt,
}),
);
harness.provider.emit({
type: "turn.started",
eventId: EventId.make("evt-turn-started-claude-1"),
provider: ProviderDriverKind.make("claudeAgent"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-claude-1"),
});
await waitForGitRefExists(
harness,
harness.cwd,
checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0),
);
NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "v2\n", "utf8");
harness.provider.emit({
type: "turn.completed",
eventId: EventId.make("evt-turn-completed-claude-1"),
provider: ProviderDriverKind.make("claudeAgent"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-claude-1"),
payload: { state: "completed" },
});
await waitForEvent(harness, (event) => event.type === "thread.turn-diff-completed");
const thread = await waitForThread(
harness,
(entry) => entry.latestTurn?.turnId === "turn-claude-1" && entry.checkpoints.length === 1,
);
expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
expect(
gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1)),
).toBe(true);
});
effectIt.effect.each(["turn.completed", "turn.aborted"] as const)(
"captures every edit after a mid-turn diff update on %s",
(terminalEventType) =>
Effect.gen(function* () {
const harness = yield* Effect.promise(() =>
createHarness({ seedFilesystemCheckpoints: false }),
);
const threadId = ThreadId.make("thread-1");
const turnId = asTurnId("turn-1");
const assistantMessageId = MessageId.make("assistant:mid-turn");
const createdAt = "2026-01-01T00:00:00.000Z";
yield* harness.engine.dispatch({
type: "thread.session.set",
commandId: CommandId.make("cmd-mid-turn-running"),
threadId,
session: {
threadId,
status: "running",
providerName: "codex",
runtimeMode: "approval-required",
activeTurnId: turnId,
lastError: null,
updatedAt: createdAt,
},
createdAt,
});
harness.provider.emit({
type: "turn.started",
eventId: EventId.make("evt-mid-turn-start"),
provider: ProviderDriverKind.make("codex"),
createdAt,
threadId,
turnId,
});
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.baseline.captured",
});
NodeFS.writeFileSync(NodePath.join(harness.cwd, "early.ts"), "export const early = 1;\n");
yield* harness.engine.dispatch({
type: "thread.turn.diff.complete",
commandId: CommandId.make("cmd-mid-turn-diff"),
threadId,
turnId,
completedAt: createdAt,
checkpointRef: CheckpointRef.make("provider-diff:mid-turn"),
assistantMessageId,
status: "missing",
files: [],
checkpointTurnCount: 1,
createdAt,
});
yield* Effect.promise(harness.drain);
NodeFS.writeFileSync(NodePath.join(harness.cwd, "late.ts"), "export const late = 2;\n");
yield* harness.engine.dispatch({
type: "thread.session.set",
commandId: CommandId.make("cmd-mid-turn-settled"),
threadId,
session: {
threadId,
status: terminalEventType === "turn.aborted" ? "interrupted" : "ready",
providerName: "codex",
runtimeMode: "approval-required",
activeTurnId: null,
lastError: null,
updatedAt: createdAt,
},
createdAt,
});
harness.provider.emit({
eventId: EventId.make("evt-mid-turn-complete"),
provider: ProviderDriverKind.make("codex"),
createdAt,
threadId,
turnId,
...(terminalEventType === "turn.completed"
? { type: "turn.completed", payload: { state: "completed" } }
: { type: "turn.aborted", payload: { reason: "Interrupted by user." } }),
});
yield* Effect.promise(harness.drain);
expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(threadId, 1))).toBe(true);
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.diff.finalized",
turnId,
checkpointTurnCount: 1,
});
expect(yield* harness.nextReceipt).toMatchObject({
type: "turn.processing.quiesced",
turnId,
});
yield* Effect.promise(harness.drain);
const thread = (yield* Effect.promise(harness.readModel)).threads.find(
(entry) => entry.id === threadId,
);
expect(thread?.checkpoints).toHaveLength(1);
expect(thread?.checkpoints[0]?.status).toBe("ready");
expect(thread?.latestTurn?.state).toBe(
terminalEventType === "turn.aborted" ? "interrupted" : "completed",
);
expect(thread?.checkpoints[0]?.assistantMessageId).toBe(assistantMessageId);
expect(thread?.checkpoints[0]?.files.map((file) => file.path)).toEqual([
"early.ts",
"late.ts",
]);
expect(
gitShowFileAtRef(harness.cwd, checkpointRefForThreadTurn(threadId, 1), "late.ts"),
).toBe("export const late = 2;\n");
const followUpTurnId = asTurnId("turn-2");
harness.provider.emit({
type: "turn.started",
eventId: EventId.make("evt-follow-up-start"),
provider: ProviderDriverKind.make("codex"),
createdAt,
threadId,
turnId: followUpTurnId,
});
harness.provider.emit({
type: "turn.completed",
eventId: EventId.make("evt-follow-up-complete"),
provider: ProviderDriverKind.make("codex"),
createdAt,
threadId,
turnId: followUpTurnId,
payload: { state: "completed" },
});
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.diff.finalized",
turnId: followUpTurnId,
checkpointTurnCount: 2,
});
const followUp = (yield* Effect.promise(harness.readModel)).threads.find(
(entry) => entry.id === threadId,
);
expect(
followUp?.checkpoints.find((checkpoint) => checkpoint.turnId === followUpTurnId),
).toMatchObject({ checkpointTurnCount: 2, files: [] });
}),
);
it("does not capture an aborted turn without a matching start or active session", async () => {
const harness = await createHarness({ seedFilesystemCheckpoints: false });
harness.provider.emit({
type: "turn.aborted",
eventId: EventId.make("evt-untracked-abort"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-untracked"),
payload: { reason: "Interrupted before the turn started." },
});
await harness.drain();
const thread = (await harness.readModel()).threads.find((entry) => entry.id === "thread-1");
expect(thread?.checkpoints).toEqual([]);
expect(
gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1)),
).toBe(false);
});
effectIt.effect("captures a checkpoint without a summary when the baseline is missing", () =>
Effect.gen(function* () {
const harness = yield* Effect.promise(() =>
createHarness({ seedFilesystemCheckpoints: false }),
);
harness.provider.emit({
type: "turn.completed",
eventId: EventId.make("evt-turn-completed-missing-baseline"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-missing-baseline"),
payload: { state: "completed" },
});
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.diff.finalized",
checkpointTurnCount: 1,
});
yield* Effect.promise(harness.drain);
const thread = (yield* Effect.promise(harness.readModel)).threads[0];
expect(thread?.checkpoints[0]).toMatchObject({
status: "ready",
checkpointTurnCount: 1,
files: [],
});
expect(
gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1)),
).toBe(true);
expect(
thread?.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
).toBe(false);
}),
);
effectIt.effect.each([
{ timing: "between turns", commit: false },
{ timing: "between turns", commit: true },
{ timing: "during a turn", commit: false },
{ timing: "during a turn", commit: true },
])("resumes checkpointing after git init $timing (commit: $commit)", ({ timing, commit }) =>
Effect.gen(function* () {
const harness = yield* Effect.promise(() =>
createHarness({ initializeGit: false, seedFilesystemCheckpoints: false }),
);
const threadId = ThreadId.make("thread-1");
const createdAt = "2026-01-01T00:00:00.000Z";
const emit = (type: "turn.started" | "turn.completed", turn: number) =>
harness.provider.emit(
type === "turn.started"
? {
type: "turn.started",
eventId: EventId.make(`${type}-${turn}`),
provider: ProviderDriverKind.make("codex"),
createdAt,
threadId,
turnId: asTurnId(`turn-${turn}`),
}
: {
type: "turn.completed",
eventId: EventId.make(`${type}-${turn}`),
provider: ProviderDriverKind.make("codex"),
createdAt,
threadId,
turnId: asTurnId(`turn-${turn}`),
payload: { state: "completed" },
},
);
emit("turn.started", 1);
yield* Effect.promise(harness.drain);
NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "before git\n");
emit("turn.completed", 1);
yield* Effect.promise(harness.drain);
expect((yield* Effect.promise(harness.readModel)).threads[0]?.checkpoints).toEqual([]);
if (timing === "during a turn") {
emit("turn.started", 2);
yield* Effect.promise(harness.drain);
}
runGit(harness.cwd, ["init", "--initial-branch=main"]);
if (commit) {
runGit(harness.cwd, ["add", "."]);
runGit(harness.cwd, [
"-c",
"user.name=Test",
"-c",
"[email protected]",
"commit",
"-m",
"Initial",
]);
}
if (timing === "between turns") {
yield* harness.engine.dispatch({
type: "thread.turn.start",
commandId: CommandId.make("cmd-after-git-init"),
threadId,
message: {
messageId: MessageId.make("message-after-git-init"),
role: "user",
text: "continue",
attachments: [],
},
interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
runtimeMode: "approval-required",
createdAt,
});
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.baseline.captured",
checkpointTurnCount: 0,
});
emit("turn.started", 2);
yield* Effect.promise(harness.drain);
}
NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "after git\n");
emit("turn.completed", 2);
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.diff.finalized",
checkpointTurnCount: 1,
});
expect(yield* harness.nextReceipt).toMatchObject({ type: "turn.processing.quiesced" });
yield* Effect.promise(harness.drain);
const firstCheckpoint = (yield* Effect.promise(harness.readModel)).threads[0]?.checkpoints[0];
expect(firstCheckpoint?.files).toEqual(
timing === "between turns"
? [{ path: "README.md", kind: "modified", additions: 1, deletions: 1 }]
: [],
);
expect(
gitShowFileAtRef(harness.cwd, checkpointRefForThreadTurn(threadId, 1), "README.md"),
).toBe("after git\n");
expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(threadId, 0))).toBe(
timing === "between turns",
);
emit("turn.started", 3);
yield* Effect.promise(harness.drain);
NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "next turn\n");
emit("turn.completed", 3);
expect(yield* harness.nextReceipt).toMatchObject({
type: "checkpoint.diff.finalized",
checkpointTurnCount: 2,
});
yield* Effect.promise(harness.drain);
const thread = (yield* Effect.promise(harness.readModel)).threads[0];
expect(thread?.checkpoints[1]?.files).toEqual([
{ path: "README.md", kind: "modified", additions: 1, deletions: 1 },
]);
expect(
thread?.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
).toBe(false);
}),
);
it("ignores non-v2 checkpoint.captured runtime events", async () => {
const harness = await createHarness();
const createdAt = "2026-01-01T00:00:00.000Z";
await harness.run(
harness.engine.dispatch({
type: "thread.session.set",
commandId: CommandId.make("cmd-session-set-checkpoint-captured"),
threadId: ThreadId.make("thread-1"),
session: {
threadId: ThreadId.make("thread-1"),
status: "ready",
providerName: "codex",
runtimeMode: "approval-required",
activeTurnId: null,
lastError: null,
updatedAt: createdAt,
},
createdAt,
}),
);
harness.provider.emitUnsafe({
type: "checkpoint.captured",
eventId: EventId.make("evt-checkpoint-captured-3"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-3"),
turnCount: 3,
status: "completed",
});
await harness.drain();
const readModel = await harness.readModel();
const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
expect(thread?.checkpoints.some((checkpoint) => checkpoint.checkpointTurnCount === 3)).toBe(
false,
);
});
it("continues processing runtime events after a single checkpoint runtime failure", async () => {
const nonRepositorySessionCwd = NodeFS.mkdtempSync(
NodePath.join(NodeOS.tmpdir(), "t3-checkpoint-runtime-non-repo-"),
);
tempDirs.push(nonRepositorySessionCwd);
const harness = await createHarness({
seedFilesystemCheckpoints: false,
providerSessionCwd: nonRepositorySessionCwd,
});
const createdAt = "2026-01-01T00:00:00.000Z";
await harness.run(
harness.engine.dispatch({
type: "thread.session.set",
commandId: CommandId.make("cmd-session-set-non-repo-runtime"),
threadId: ThreadId.make("thread-1"),
session: {
threadId: ThreadId.make("thread-1"),
status: "ready",
providerName: "codex",
runtimeMode: "approval-required",
activeTurnId: null,
lastError: null,
updatedAt: createdAt,
},
createdAt,
}),
);
harness.provider.emit({
type: "turn.completed",
eventId: EventId.make("evt-runtime-capture-failure"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-runtime-failure"),
payload: { state: "completed" },
});
harness.provider.emit({
type: "turn.started",
eventId: EventId.make("evt-turn-started-after-runtime-failure"),
provider: ProviderDriverKind.make("codex"),
createdAt: "2026-01-01T00:00:00.000Z",
threadId: ThreadId.make("thread-1"),
turnId: asTurnId("turn-after-runtime-failure"),
});
await waitForGitRefExists(
harness,
harness.cwd,
checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0),
);
expect(
gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0)),
).toBe(true);
});
});