@clinebot/core 0.0.29 → 0.0.32

package/dist/types/config.d.ts

@@ -66,6 +66,66 @@ export interface CoreCompactionConfig {
     summarizer?: CoreCompactionSummarizerConfig;
     compact?: (context: CoreCompactionContext) => Promise<CoreCompactionResult | undefined> | CoreCompactionResult | undefined;
 }
+/**
+ * Context passed to a custom `createCheckpoint` implementation.
+ */
+export interface CoreCheckpointContext {
+    /** Absolute path to the working directory of the session. */
+    cwd: string;
+    /** The session identifier. */
+    sessionId: string;
+    /** Monotonically increasing run counter for this session (starts at 1). */
+    runCount: number;
+}
+/**
+ * Configuration for the built-in git-based checkpoint feature.
+ *
+ * Checkpoints capture a restorable snapshot of the workspace at the start of
+ * each root-agent run so that changes made during a session can be rolled back.
+ *
+ * @example Disable checkpoints entirely:
+ * ```ts
+ * checkpoint: { enabled: false }
+ * ```
+ *
+ * @example Bring your own checkpoint implementation:
+ * ```ts
+ * checkpoint: {
+ *   createCheckpoint: async ({ cwd, sessionId, runCount }) => {
+ *     const ref = await mySnapshotFn(cwd);
+ *     return { ref, createdAt: Date.now(), runCount };
+ *   },
+ * }
+ * ```
+ */
+export interface CoreCheckpointConfig {
+    /**
+     * Whether to create checkpoints on each root-agent run start.
+     * Defaults to `false` — checkpoints are **opt-in**. Set to `true` to
+     * enable the built-in git stash/ref checkpoint behaviour for this session.
+     */
+    enabled?: boolean;
+    /**
+     * Replace the built-in git stash/ref checkpoint logic with a custom
+     * implementation. Called once at the start of each root-agent run (before
+     * the first agent iteration).
+     *
+     * Return an object with at least `ref`, `createdAt`, and `runCount` to have
+     * the entry recorded in session metadata, or return `undefined` to skip
+     * writing a checkpoint for that run.
+     */
+    createCheckpoint?: (context: CoreCheckpointContext) => Promise<{
+        ref: string;
+        createdAt: number;
+        runCount: number;
+        kind?: "stash" | "commit";
+    } | undefined> | {
+        ref: string;
+        createdAt: number;
+        runCount: number;
+        kind?: "stash" | "commit";
+    } | undefined;
+}
 export interface CoreSessionConfig extends CoreModelConfig, CoreRuntimeFeatures, Omit<SessionWorkspaceConfig, "workspaceRoot">, Omit<SessionPromptConfig, "systemPrompt">, Omit<SessionExecutionConfig, "enableTools" | "teamName" | "missionLogIntervalSteps" | "missionLogIntervalMs" | "maxConsecutiveMistakes"> {
     sessionId?: string;
     workspaceRoot?: string;
@@ -83,6 +143,7 @@ export interface CoreSessionConfig extends CoreModelConfig, CoreRuntimeFeatures,
     extensions?: AgentConfig["extensions"];
     execution?: AgentConfig["execution"];
     compaction?: CoreCompactionConfig;
+    checkpoint?: CoreCheckpointConfig;
     onTeamEvent?: (event: TeamEvent) => void;
     onConsecutiveMistakeLimitReached?: (context: ConsecutiveMistakeLimitContext) => Promise<ConsecutiveMistakeLimitDecision> | ConsecutiveMistakeLimitDecision;
     toolRoutingRules?: ToolRoutingRule[];

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@clinebot/core",
 	"description": "Cline Core SDK for Node Runtime",
-	"version": "0.0.29",
+	"version": "0.0.32",
 	"type": "module",
 	"types": "./dist/index.d.ts",
 	"main": "./dist/index.js",
@@ -36,8 +36,8 @@
 		"test:watch": "vitest --config vitest.config.ts"
 	},
 	"dependencies": {
-		"@clinebot/agents": "0.0.29",
-		"@clinebot/llms": "0.0.29",
+		"@clinebot/agents": "0.0.32",
+		"@clinebot/llms": "0.0.32",
 		"@opentelemetry/api": "^1.9.0",
 		"@opentelemetry/api-logs": "^0.214.0",
 		"@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
@@ -58,7 +58,7 @@
 	},
 	"devDependencies": {
 		"@clinebot/rpc": "0.0.28",
-		"@clinebot/shared": "0.0.29"
+		"@clinebot/shared": "0.0.32"
 	},
 	"engines": {
 		"node": ">=22"

package/src/index.ts

@@ -535,6 +535,8 @@ export type { SessionStatus } from "./types/common";
 export { SESSION_STATUSES, SessionSource } from "./types/common";
 export type {
 	CoreAgentMode,
+	CoreCheckpointConfig,
+	CoreCheckpointContext,
 	CoreCompactionConfig,
 	CoreCompactionContext,
 	CoreCompactionResult,

package/src/runtime/checkpoint-hooks.test.ts

@@ -30,7 +30,8 @@ async function createGitRepo(): Promise<string> {
 	return cwd;
 }
 
-describe("createCheckpointHooks", () => {
+// Currently disabled for process?.env?.CLINE_CHECKPOINT
+describe.skip("createCheckpointHooks", () => {
 	it("creates one checkpoint at the start of each root run and appends metadata", async () => {
 		const cwd = await createGitRepo();
 		let metadata: Record<string, unknown> | undefined;

package/src/runtime/checkpoint-hooks.ts

@@ -24,6 +24,16 @@ type CreateCheckpointHooksOptions = {
 	writeSessionMetadata: (
 		metadata: Record<string, unknown>,
 	) => Promise<void> | void;
+	/**
+	 * Optional custom checkpoint implementation. When provided, the built-in
+	 * git stash/ref logic is skipped entirely and this function is called
+	 * instead. Return `undefined` to skip writing a checkpoint for that run.
+	 */
+	createCheckpoint?: (context: {
+		cwd: string;
+		sessionId: string;
+		runCount: number;
+	}) => Promise<CheckpointEntry | undefined> | CheckpointEntry | undefined;
 };
 
 function warn(logger: BasicLogger | undefined, message: string): void {
@@ -99,6 +109,14 @@ export function createCheckpointHooks(
 	};
 
 	const createCheckpoint = async (): Promise<CheckpointEntry | undefined> => {
+		if (options.createCheckpoint) {
+			return await options.createCheckpoint({
+				cwd: options.cwd,
+				sessionId: options.sessionId,
+				runCount,
+			});
+		}
+
 		if (!(await ensureGitRepository())) {
 			return undefined;
 		}
@@ -137,8 +155,15 @@ export function createCheckpointHooks(
 			};
 		}
 
+		// Store the stash commit under a private ref namespace so it is
+		// invisible to the user's normal `git stash list` workflow.
+		// `refs/stash` is what populates that list; writing to any other
+		// ref path keeps the object reachable (GC-safe) without surfacing
+		// it to the user.  The raw SHA already works with `git stash apply`
+		// on the restore path, so no restore-side changes are needed.
+		const privateRef = `refs/cline/checkpoints/${options.sessionId}/${runCount}`;
 		try {
-			await runGit(options.cwd, ["stash", "store", "-m", message, ref]);
+			await runGit(options.cwd, ["update-ref", privateRef, ref]);
 		} catch (error) {
 			warn(
 				options.logger,

package/src/session/default-session-manager.test.ts

@@ -150,7 +150,6 @@ describe("DefaultSessionManager", () => {
 	const envSnapshot = {
 		HOME: process.env.HOME,
 		CLINE_DIR: process.env.CLINE_DIR,
-		CLINE_CHECKPOINT: process.env.CLINE_CHECKPOINT,
 	};
 	let isolatedHomeDir = "";
 
@@ -158,7 +157,6 @@ describe("DefaultSessionManager", () => {
 		isolatedHomeDir = mkdtempSync(join(tmpdir(), "core-session-home-"));
 		process.env.HOME = isolatedHomeDir;
 		process.env.CLINE_DIR = join(isolatedHomeDir, ".cline");
-		delete process.env.CLINE_CHECKPOINT;
 		setHomeDir(isolatedHomeDir);
 		setClineDir(process.env.CLINE_DIR);
 	});
@@ -166,7 +164,6 @@ describe("DefaultSessionManager", () => {
 	afterEach(() => {
 		process.env.HOME = envSnapshot.HOME;
 		process.env.CLINE_DIR = envSnapshot.CLINE_DIR;
-		process.env.CLINE_CHECKPOINT = envSnapshot.CLINE_CHECKPOINT;
 		setHomeDir(envSnapshot.HOME ?? "~");
 		setClineDir(envSnapshot.CLINE_DIR ?? join("~", ".cline"));
 		rmSync(isolatedHomeDir, { recursive: true, force: true });
@@ -652,7 +649,7 @@ describe("DefaultSessionManager", () => {
 		);
 	});
 
-	it("does not install checkpoint hooks unless CLINE_CHECKPOINT=true", async () => {
+	it("does not install checkpoint hooks when checkpoint.enabled is not set in config", async () => {
 		const sessionId = "sess-checkpoint-default-off";
 		const manifest = createManifest(sessionId);
 		const updateSession = vi.fn().mockResolvedValue({ updated: true });
@@ -737,10 +734,8 @@ describe("DefaultSessionManager", () => {
 		});
 	});
 
-	it("installs checkpoint hooks when CLINE_CHECKPOINT=true", async () => {
-		process.env.CLINE_CHECKPOINT = "true";
-
-		const sessionId = "sess-checkpoint-env-on";
+	it("installs checkpoint hooks when checkpoint.enabled=true in config", async () => {
+		const sessionId = "sess-checkpoint-config-on";
 		const repoCwd = mkdtempSync(join(isolatedHomeDir, "checkpoint-repo-"));
 		createGitRepo(repoCwd);
 		const manifest = createManifest(sessionId);
@@ -813,7 +808,10 @@ describe("DefaultSessionManager", () => {
 		});
 
 		await manager.start({
-			config: createConfig({ sessionId, cwd: repoCwd }),
+			config: {
+				...createConfig({ sessionId, cwd: repoCwd }),
+				checkpoint: { enabled: true },
+			},
 			prompt: "hello",
 			interactive: false,
 		});

package/src/session/default-session-manager.ts

@@ -115,11 +115,6 @@ type SessionBackend =
 const MAX_SCAN_LIMIT = 5000;
 const MAX_USER_FILE_BYTES = 20 * 1_000 * 1_024;
 
-// NOTE: Temporarily disabled until checkpoint is ready for production.
-function isCheckpointFeatureEnabled(): boolean {
-	return process?.env?.CLINE_CHECKPOINT === "true";
-}
-
 async function loadUserFileContent(path: string): Promise<string> {
 	const fileStat = await stat(path);
 	if (!fileStat.isFile()) {
@@ -277,11 +272,12 @@ export class DefaultSessionManager implements SessionManager {
 		};
 		configWithProvider.hooks = mergeAgentHooks([
 			effectiveConfig.hooks,
-			isCheckpointFeatureEnabled()
+			effectiveConfig.checkpoint?.enabled === true
 				? createCheckpointHooks({
 						cwd: configWithProvider.cwd,
 						sessionId,
 						logger: configWithProvider.logger,
+						createCheckpoint: effectiveConfig.checkpoint?.createCheckpoint,
 						readSessionMetadata: async () =>
 							(await this.get(sessionId))?.metadata as
 								| Record<string, unknown>
@@ -344,6 +340,7 @@ export class DefaultSessionManager implements SessionManager {
 			onConsecutiveMistakeLimitReached:
 				configWithProvider.onConsecutiveMistakeLimitReached,
 			completionGuard: runtime.completionGuard,
+			consumePendingUserMessage: () => this.consumeSteerMessage(sessionId),
 			logger: runtime.logger ?? configWithProvider.logger,
 			extensionContext: configWithProvider.extensionContext,
 			onEvent: (event: AgentEvent) =>
@@ -964,6 +961,27 @@ export class DefaultSessionManager implements SessionManager {
 		});
 	}
 
+	/**
+	 * Consume the first steer-delivery pending prompt for injection into the
+	 * running agent loop. Called synchronously by the agent between iterations.
+	 */
+	private consumeSteerMessage(sessionId: string): string | undefined {
+		const session = this.sessions.get(sessionId);
+		if (!session) {
+			return undefined;
+		}
+		const steerIndex = session.pendingPrompts.findIndex(
+			(entry) => entry.delivery === "steer",
+		);
+		if (steerIndex < 0) {
+			return undefined;
+		}
+		const [steer] = session.pendingPrompts.splice(steerIndex, 1);
+		this.emitPendingPrompts(session);
+		this.emitPendingPromptSubmitted(session, steer);
+		return steer.prompt;
+	}
+
 	private enqueuePendingPrompt(
 		sessionId: string,
 		entry: {

package/src/session/persistence-service.test.ts

@@ -160,13 +160,11 @@ describe("UnifiedSessionPersistenceService", () => {
 			row.sessionId.includes("__teamtask__java-haiku-agent__"),
 		)?.sessionId;
 		expect(teammateSessionId).toBeTruthy();
-		const path = join(
-			sessionsDir,
-			rootSessionId,
-			"java-haiku-agent__" +
-				teammateSessionId?.slice(teammateSessionId?.lastIndexOf("__") + 2) +
-				".messages.json",
+		const row = childSessions.find(
+			(item) => item.sessionId === teammateSessionId,
 		);
+		expect(row?.messagesPath).toBeTruthy();
+		const path = row?.messagesPath as string;
 		const payload = JSON.parse(readFileSync(path, "utf8")) as {
 			agent?: string;
 			sessionId?: string;
@@ -195,18 +193,11 @@ describe("UnifiedSessionPersistenceService", () => {
 			cacheWriteTokens: 0,
 			cost: 0.123,
 		});
-		const row = childSessions.find(
-			(item) => item.sessionId === teammateSessionId,
-		);
 		expect(row?.messagesPath).toBe(path);
-		expect(row?.transcriptPath).toBe(
-			join(
-				sessionsDir,
-				rootSessionId,
-				"java-haiku-agent__" +
-					teammateSessionId?.slice(teammateSessionId?.lastIndexOf("__") + 2) +
-					".log",
-			),
+		expect(row?.transcriptPath).toBeTruthy();
+		expect(row?.transcriptPath).toContain(
+			join(sessionsDir, rootSessionId, "java-haiku-agent__"),
 		);
+		expect(row?.transcriptPath).toMatch(/\.log$/);
 	});
 });

package/src/telemetry/OpenTelemetryAdapter.ts

@@ -229,8 +229,8 @@ export class OpenTelemetryAdapter implements ITelemetryAdapter {
 	): TelemetryProperties {
 		return {
 			...this.commonProperties,
-			...properties,
 			...this.metadata,
+			...properties,
 			...(this.distinctId ? { distinct_id: this.distinctId } : {}),
 			...(required ? { _required: true } : {}),
 		};

package/src/telemetry/OpenTelemetryProvider.test.ts

@@ -98,6 +98,197 @@ describe("createOpenTelemetryTelemetryService", () => {
 		expect(telemetry).toBeInstanceOf(TelemetryService);
 	});
 
+	it("preserves metadata when disabled", () => {
+		const metadata = {
+			extension_version: "1.0.0",
+			cline_type: "kanban",
+			platform: "kanban",
+			platform_version: "v22.0.0",
+			os_type: "darwin",
+			os_version: "15.0",
+		};
+		const { telemetry } = createConfiguredTelemetryService({
+			metadata,
+			enabled: false,
+		});
+		const spy = vi.fn();
+		(telemetry as any).adapters.push({
+			name: "test",
+			emit: spy,
+			emitRequired: spy,
+			isEnabled: () => true,
+			recordCounter: vi.fn(),
+			recordHistogram: vi.fn(),
+			recordGauge: vi.fn(),
+			flush: async () => {},
+			dispose: async () => {},
+		});
+		telemetry.captureRequired("test.event", {});
+		expect(spy).toHaveBeenCalledWith(
+			"test.event",
+			expect.objectContaining({
+				cline_type: "kanban",
+				platform: "kanban",
+			}),
+		);
+	});
+
+	it("preserves metadata in the enabled (OTEL) path", async () => {
+		const metadata = {
+			extension_version: "1.0.0",
+			cline_type: "kanban",
+			platform: "kanban",
+			platform_version: "v22.0.0",
+			os_type: "darwin",
+			os_version: "15.0",
+		};
+		const { telemetry, provider } = createOpenTelemetryTelemetryService({
+			metadata,
+			enabled: true,
+			logsExporter: "console",
+		});
+		const spy = vi.fn();
+		(telemetry as any).adapters.push({
+			name: "test",
+			emit: spy,
+			emitRequired: spy,
+			isEnabled: () => true,
+			recordCounter: vi.fn(),
+			recordHistogram: vi.fn(),
+			recordGauge: vi.fn(),
+			flush: async () => {},
+			dispose: async () => {},
+		});
+		telemetry.captureRequired("test.event", {});
+		expect(spy).toHaveBeenCalledWith(
+			"test.event",
+			expect.objectContaining({
+				cline_type: "kanban",
+				platform: "kanban",
+			}),
+		);
+		await provider.dispose();
+	});
+
+	it("delivers metadata to the OTEL logger without duplication", async () => {
+		const otelEmit = vi.fn();
+		const provider = new OpenTelemetryProvider({
+			enabled: true,
+		});
+		// Replace the loggerProvider with a mock so we can inspect emit calls
+		(provider as any).loggerProvider = {
+			getLogger: () => ({ emit: otelEmit }),
+			forceFlush: async () => {},
+			shutdown: async () => {},
+		};
+
+		const metadata = {
+			extension_version: "1.0.0",
+			cline_type: "kanban",
+			platform: "kanban",
+			platform_version: "v22.0.0",
+			os_type: "darwin",
+			os_version: "15.0",
+		};
+
+		const telemetry = provider.createTelemetryService({ metadata });
+
+		telemetry.captureRequired("test.otel_event", { custom_prop: "value" });
+
+		expect(otelEmit).toHaveBeenCalledTimes(1);
+		const emittedAttributes = otelEmit.mock.calls[0][0].attributes;
+
+		// Metadata fields must be present
+		expect(emittedAttributes).toMatchObject({
+			cline_type: "kanban",
+			platform: "kanban",
+			extension_version: "1.0.0",
+			custom_prop: "value",
+		});
+
+		// Verify no key appears more than once (flattened object can't have
+		// duplicate keys, but this guards against nested duplication patterns
+		// like metadata appearing under a sub-prefix)
+		const keys = Object.keys(emittedAttributes);
+		const metadataKeys = Object.keys(metadata);
+		for (const mk of metadataKeys) {
+			const occurrences = keys.filter((k) => k === mk || k.endsWith(`.${mk}`));
+			expect(
+				occurrences,
+				`metadata key "${mk}" should appear exactly once, found: ${occurrences.join(", ")}`,
+			).toHaveLength(1);
+		}
+
+		await provider.dispose();
+	});
+
+	it("propagates updateMetadata to OTEL logger output", async () => {
+		const otelEmit = vi.fn();
+		const provider = new OpenTelemetryProvider({
+			enabled: true,
+		});
+		(provider as any).loggerProvider = {
+			getLogger: () => ({ emit: otelEmit }),
+			forceFlush: async () => {},
+			shutdown: async () => {},
+		};
+
+		const metadata = {
+			extension_version: "1.0.0",
+			cline_type: "kanban",
+			platform: "kanban",
+			platform_version: "v22.0.0",
+			os_type: "darwin",
+			os_version: "15.0",
+		};
+
+		const telemetry = provider.createTelemetryService({ metadata });
+
+		// Update metadata after construction
+		telemetry.updateMetadata({ cline_type: "kanban-updated" });
+
+		telemetry.captureRequired("test.updated_event", {});
+
+		// The OTEL logger should see the updated value
+		const emittedAttributes =
+			otelEmit.mock.calls[otelEmit.mock.calls.length - 1][0].attributes;
+		expect(emittedAttributes.cline_type).toBe("kanban-updated");
+
+		await provider.dispose();
+	});
+
+	it("preserves logger when disabled", () => {
+		const logger: BasicLogger = {
+			debug: vi.fn(),
+			log: vi.fn(),
+			error: vi.fn(),
+		};
+		const { telemetry } = createConfiguredTelemetryService({
+			metadata: {
+				extension_version: "1.0.0",
+				cline_type: "kanban",
+				platform: "kanban",
+				platform_version: "v22.0.0",
+				os_type: "darwin",
+				os_version: "15.0",
+			},
+			enabled: false,
+			logger,
+		});
+
+		telemetry.capture({
+			event: "session.started",
+			properties: { sessionId: "session-1" },
+		});
+
+		expect(logger.log).toHaveBeenCalledWith(
+			"telemetry.event",
+			expect.objectContaining({
+				event: "session.started",
+			}),
+		);
+	});
+
 	it("attaches the logger adapter when creating configured telemetry", () => {
 		const logger: BasicLogger = {
 			debug: vi.fn(),

package/src/telemetry/OpenTelemetryProvider.ts

@@ -133,10 +133,9 @@ export class OpenTelemetryProvider {
 			metadata: options.metadata,
 		});
 		return new TelemetryService({
+			...options,
 			adapters: [adapter],
 			distinctId: resolveCoreDistinctId(options.distinctId),
-			commonProperties: options.commonProperties,
-			logger: options.logger,
 		});
 	}
 
@@ -299,6 +298,7 @@ export function createConfiguredTelemetryService(
 	if (options.enabled !== true) {
 		return {
 			telemetry: new TelemetryService({
+				...options,
 				distinctId: resolveCoreDistinctId(options.distinctId),
 			}),
 		};

package/src/types/config.ts

@@ -95,6 +95,74 @@ export interface CoreCompactionConfig {
 		| undefined;
 }
 
+/**
+ * Context passed to a custom `createCheckpoint` implementation.
+ */
+export interface CoreCheckpointContext {
+	/** Absolute path to the working directory of the session. */
+	cwd: string;
+	/** The session identifier. */
+	sessionId: string;
+	/** Monotonically increasing run counter for this session (starts at 1). */
+	runCount: number;
+}
+
+/**
+ * Configuration for the built-in git-based checkpoint feature.
+ *
+ * Checkpoints capture a restorable snapshot of the workspace at the start of
+ * each root-agent run so that changes made during a session can be rolled back.
+ *
+ * @example Disable checkpoints entirely:
+ * ```ts
+ * checkpoint: { enabled: false }
+ * ```
+ *
+ * @example Bring your own checkpoint implementation:
+ * ```ts
+ * checkpoint: {
+ *   createCheckpoint: async ({ cwd, sessionId, runCount }) => {
+ *     const ref = await mySnapshotFn(cwd);
+ *     return { ref, createdAt: Date.now(), runCount };
+ *   },
+ * }
+ * ```
+ */
+export interface CoreCheckpointConfig {
+	/**
+	 * Whether to create checkpoints on each root-agent run start.
+	 * Defaults to `false` — checkpoints are **opt-in**. Set to `true` to
+	 * enable the built-in git stash/ref checkpoint behaviour for this session.
+	 */
+	enabled?: boolean;
+	/**
+	 * Replace the built-in git stash/ref checkpoint logic with a custom
+	 * implementation. Called once at the start of each root-agent run (before
+	 * the first agent iteration).
+	 *
+	 * Return an object with at least `ref`, `createdAt`, and `runCount` to have
+	 * the entry recorded in session metadata, or return `undefined` to skip
+	 * writing a checkpoint for that run.
+	 */
+	createCheckpoint?: (context: CoreCheckpointContext) =>
+		| Promise<
+				| {
+						ref: string;
+						createdAt: number;
+						runCount: number;
+						kind?: "stash" | "commit";
+				  }
+				| undefined
+		  >
+		| {
+				ref: string;
+				createdAt: number;
+				runCount: number;
+				kind?: "stash" | "commit";
+		  }
+		| undefined;
+}
+
 export interface CoreSessionConfig
 	extends CoreModelConfig,
 		CoreRuntimeFeatures,
@@ -124,6 +192,7 @@ export interface CoreSessionConfig
 	extensions?: AgentConfig["extensions"];
 	execution?: AgentConfig["execution"];
 	compaction?: CoreCompactionConfig;
+	checkpoint?: CoreCheckpointConfig;
 	onTeamEvent?: (event: TeamEvent) => void;
 	onConsecutiveMistakeLimitReached?: (
 		context: ConsecutiveMistakeLimitContext,