@clinebot/core 0.0.30 → 0.0.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/dist/index.d.ts +1 -1
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +24 -24
  4. package/dist/runtime/checkpoint-hooks.d.ts +10 -0
  5. package/dist/runtime/checkpoint-hooks.d.ts.map +1 -1
  6. package/dist/session/default-session-manager.d.ts.map +1 -1
  7. package/dist/types/config.d.ts +61 -0
  8. package/dist/types/config.d.ts.map +1 -1
  9. package/package.json +4 -4
  10. package/src/index.ts +2 -0
  11. package/src/runtime/checkpoint-hooks.ts +26 -1
  12. package/src/session/default-session-manager.test.ts +7 -9
  13. package/src/session/default-session-manager.ts +2 -6
  14. package/src/session/persistence-service.test.ts +8 -17
  15. package/src/types/config.ts +69 -0
package/dist/runtime/checkpoint-hooks.d.ts CHANGED
@@ -15,6 +15,16 @@ type CreateCheckpointHooksOptions = {
15
15
  logger?: BasicLogger;
16
16
  readSessionMetadata: () => Promise<Record<string, unknown> | undefined>;
17
17
  writeSessionMetadata: (metadata: Record<string, unknown>) => Promise<void> | void;
18
+ /**
19
+ * Optional custom checkpoint implementation. When provided, the built-in
20
+ * git stash/ref logic is skipped entirely and this function is called
21
+ * instead. Return `undefined` to skip writing a checkpoint for that run.
22
+ */
23
+ createCheckpoint?: (context: {
24
+ cwd: string;
25
+ sessionId: string;
26
+ runCount: number;
27
+ }) => Promise<CheckpointEntry | undefined> | CheckpointEntry | undefined;
18
28
  };
19
29
  export declare function createCheckpointHooks(options: CreateCheckpointHooksOptions): AgentHooks;
20
30
  export {};
package/dist/runtime/checkpoint-hooks.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"checkpoint-hooks.d.ts","sourceRoot":"","sources":["../../src/runtime/checkpoint-hooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIhE,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,KAAK,4BAA4B,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mBAAmB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IACxE,oBAAoB,EAAE,CACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1B,CAAC;AAoDF,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GACnC,UAAU,CAyGZ"}
1
+ {"version":3,"file":"checkpoint-hooks.d.ts","sourceRoot":"","sources":["../../src/runtime/checkpoint-hooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIhE,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,KAAK,4BAA4B,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mBAAmB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IACxE,oBAAoB,EAAE,CACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC5B,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;KACjB,KAAK,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,GAAG,eAAe,GAAG,SAAS,CAAC;CACzE,CAAC;AAoDF,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,4BAA4B,GACnC,UAAU,CAwHZ"}
package/dist/session/default-session-manager.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"default-session-manager.d.ts","sourceRoot":"","sources":["../../src/session/default-session-manager.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"default-session-manager.d.ts","sourceRoot":"","sources":["../../src/session/default-session-manager.ts"],"names":[],"mappings":"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"}
package/dist/types/config.d.ts CHANGED
@@ -66,6 +66,66 @@ export interface CoreCompactionConfig {
66
66
  summarizer?: CoreCompactionSummarizerConfig;
67
67
  compact?: (context: CoreCompactionContext) => Promise<CoreCompactionResult | undefined> | CoreCompactionResult | undefined;
68
68
  }
69
+ /**
70
+ * Context passed to a custom `createCheckpoint` implementation.
71
+ */
72
+ export interface CoreCheckpointContext {
73
+ /** Absolute path to the working directory of the session. */
74
+ cwd: string;
75
+ /** The session identifier. */
76
+ sessionId: string;
77
+ /** Monotonically increasing run counter for this session (starts at 1). */
78
+ runCount: number;
79
+ }
80
+ /**
81
+ * Configuration for the built-in git-based checkpoint feature.
82
+ *
83
+ * Checkpoints capture a restorable snapshot of the workspace at the start of
84
+ * each root-agent run so that changes made during a session can be rolled back.
85
+ *
86
+ * @example Disable checkpoints entirely:
87
+ * ```ts
88
+ * checkpoint: { enabled: false }
89
+ * ```
90
+ *
91
+ * @example Bring your own checkpoint implementation:
92
+ * ```ts
93
+ * checkpoint: {
94
+ * createCheckpoint: async ({ cwd, sessionId, runCount }) => {
95
+ * const ref = await mySnapshotFn(cwd);
96
+ * return { ref, createdAt: Date.now(), runCount };
97
+ * },
98
+ * }
99
+ * ```
100
+ */
101
+ export interface CoreCheckpointConfig {
102
+ /**
103
+ * Whether to create checkpoints on each root-agent run start.
104
+ * Defaults to `false` — checkpoints are **opt-in**. Set to `true` to
105
+ * enable the built-in git stash/ref checkpoint behaviour for this session.
106
+ */
107
+ enabled?: boolean;
108
+ /**
109
+ * Replace the built-in git stash/ref checkpoint logic with a custom
110
+ * implementation. Called once at the start of each root-agent run (before
111
+ * the first agent iteration).
112
+ *
113
+ * Return an object with at least `ref`, `createdAt`, and `runCount` to have
114
+ * the entry recorded in session metadata, or return `undefined` to skip
115
+ * writing a checkpoint for that run.
116
+ */
117
+ createCheckpoint?: (context: CoreCheckpointContext) => Promise<{
118
+ ref: string;
119
+ createdAt: number;
120
+ runCount: number;
121
+ kind?: "stash" | "commit";
122
+ } | undefined> | {
123
+ ref: string;
124
+ createdAt: number;
125
+ runCount: number;
126
+ kind?: "stash" | "commit";
127
+ } | undefined;
128
+ }
69
129
  export interface CoreSessionConfig extends CoreModelConfig, CoreRuntimeFeatures, Omit<SessionWorkspaceConfig, "workspaceRoot">, Omit<SessionPromptConfig, "systemPrompt">, Omit<SessionExecutionConfig, "enableTools" | "teamName" | "missionLogIntervalSteps" | "missionLogIntervalMs" | "maxConsecutiveMistakes"> {
70
130
  sessionId?: string;
71
131
  workspaceRoot?: string;
@@ -83,6 +143,7 @@ export interface CoreSessionConfig extends CoreModelConfig, CoreRuntimeFeatures,
83
143
  extensions?: AgentConfig["extensions"];
84
144
  execution?: AgentConfig["execution"];
85
145
  compaction?: CoreCompactionConfig;
146
+ checkpoint?: CoreCheckpointConfig;
86
147
  onTeamEvent?: (event: TeamEvent) => void;
87
148
  onConsecutiveMistakeLimitReached?: (context: ConsecutiveMistakeLimitContext) => Promise<ConsecutiveMistakeLimitDecision> | ConsecutiveMistakeLimitDecision;
88
149
  toolRoutingRules?: ToolRoutingRule[];
package/dist/types/config.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,aAAa,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EACX,WAAW,EACX,UAAU,EACV,SAAS,EACT,WAAW,EACX,8BAA8B,EAC9B,+BAA+B,EAC/B,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,IAAI,EACJ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEnE,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtD;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,mBAAmB;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,KAAK,EAAE;QACN,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC;KAC/B,CAAC;IACF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,8BAA8B;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACtD,cAAc,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,8BAA8B,CAAC;IAC5C,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,qBAAqB,KAE5B,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,GACzC,oBAAoB,GACpB,SAAS,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAC/C,OAAO,CACL;QACA,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;KACzB,GACD,SAAS,CACV,GACD;QACA,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;KACzB,GACD,SAAS,CAAC;CACb;AAED,MAAM,WAAW,iBAChB,SAAQ,eAAe,EACtB,mBAAmB,EACnB,IAAI,CAAC,sBAAsB,EAAE,eAAe,CAAC,EAC7C,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,EACzC,IAAI,CACH,sBAAsB,EACpB,aAAa,GACb,UAAU,GACV,yBAAyB,GACzB,sBAAsB,GACtB,wBAAwB,CAC1B;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,UAAU,CAAC,EAAE,IAAI,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACvC,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAClC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,gCAAgC,CAAC,EAAE,CAClC,OAAO,EAAE,8BAA8B,KAErC,OAAO,CAAC,+BAA+B,CAAC,GACxC,+BAA+B,CAAC;IACnC,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B"}
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@clinebot/core",
3
3
  "description": "Cline Core SDK for Node Runtime",
4
- "version": "0.0.30",
4
+ "version": "0.0.32",
5
5
  "type": "module",
6
6
  "types": "./dist/index.d.ts",
7
7
  "main": "./dist/index.js",
@@ -36,8 +36,8 @@
36
36
  "test:watch": "vitest --config vitest.config.ts"
37
37
  },
38
38
  "dependencies": {
39
- "@clinebot/agents": "0.0.30",
40
- "@clinebot/llms": "0.0.30",
39
+ "@clinebot/agents": "0.0.32",
40
+ "@clinebot/llms": "0.0.32",
41
41
  "@opentelemetry/api": "^1.9.0",
42
42
  "@opentelemetry/api-logs": "^0.214.0",
43
43
  "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
@@ -58,7 +58,7 @@
58
58
  },
59
59
  "devDependencies": {
60
60
  "@clinebot/rpc": "0.0.28",
61
- "@clinebot/shared": "0.0.30"
61
+ "@clinebot/shared": "0.0.32"
62
62
  },
63
63
  "engines": {
64
64
  "node": ">=22"
package/src/index.ts CHANGED
@@ -535,6 +535,8 @@ export type { SessionStatus } from "./types/common";
535
535
  export { SESSION_STATUSES, SessionSource } from "./types/common";
536
536
  export type {
537
537
  CoreAgentMode,
538
+ CoreCheckpointConfig,
539
+ CoreCheckpointContext,
538
540
  CoreCompactionConfig,
539
541
  CoreCompactionContext,
540
542
  CoreCompactionResult,
package/src/runtime/checkpoint-hooks.ts CHANGED
@@ -24,6 +24,16 @@ type CreateCheckpointHooksOptions = {
24
24
  writeSessionMetadata: (
25
25
  metadata: Record<string, unknown>,
26
26
  ) => Promise<void> | void;
27
+ /**
28
+ * Optional custom checkpoint implementation. When provided, the built-in
29
+ * git stash/ref logic is skipped entirely and this function is called
30
+ * instead. Return `undefined` to skip writing a checkpoint for that run.
31
+ */
32
+ createCheckpoint?: (context: {
33
+ cwd: string;
34
+ sessionId: string;
35
+ runCount: number;
36
+ }) => Promise<CheckpointEntry | undefined> | CheckpointEntry | undefined;
27
37
  };
28
38
 
29
39
  function warn(logger: BasicLogger | undefined, message: string): void {
@@ -99,6 +109,14 @@ export function createCheckpointHooks(
99
109
  };
100
110
 
101
111
  const createCheckpoint = async (): Promise<CheckpointEntry | undefined> => {
112
+ if (options.createCheckpoint) {
113
+ return await options.createCheckpoint({
114
+ cwd: options.cwd,
115
+ sessionId: options.sessionId,
116
+ runCount,
117
+ });
118
+ }
119
+
102
120
  if (!(await ensureGitRepository())) {
103
121
  return undefined;
104
122
  }
@@ -137,8 +155,15 @@ export function createCheckpointHooks(
137
155
  };
138
156
  }
139
157
 
158
+ // Store the stash commit under a private ref namespace so it is
159
+ // invisible to the user's normal `git stash list` workflow.
160
+ // `refs/stash` is what populates that list; writing to any other
161
+ // ref path keeps the object reachable (GC-safe) without surfacing
162
+ // it to the user. The raw SHA already works with `git stash apply`
163
+ // on the restore path, so no restore-side changes are needed.
164
+ const privateRef = `refs/cline/checkpoints/${options.sessionId}/${runCount}`;
140
165
  try {
141
- await runGit(options.cwd, ["stash", "store", "-m", message, ref]);
166
+ await runGit(options.cwd, ["update-ref", privateRef, ref]);
142
167
  } catch (error) {
143
168
  warn(
144
169
  options.logger,
package/src/session/default-session-manager.test.ts CHANGED
@@ -150,7 +150,6 @@ describe("DefaultSessionManager", () => {
150
150
  const envSnapshot = {
151
151
  HOME: process.env.HOME,
152
152
  CLINE_DIR: process.env.CLINE_DIR,
153
- CLINE_CHECKPOINT: process.env.CLINE_CHECKPOINT,
154
153
  };
155
154
  let isolatedHomeDir = "";
156
155
 
@@ -158,7 +157,6 @@ describe("DefaultSessionManager", () => {
158
157
  isolatedHomeDir = mkdtempSync(join(tmpdir(), "core-session-home-"));
159
158
  process.env.HOME = isolatedHomeDir;
160
159
  process.env.CLINE_DIR = join(isolatedHomeDir, ".cline");
161
- delete process.env.CLINE_CHECKPOINT;
162
160
  setHomeDir(isolatedHomeDir);
163
161
  setClineDir(process.env.CLINE_DIR);
164
162
  });
@@ -166,7 +164,6 @@ describe("DefaultSessionManager", () => {
166
164
  afterEach(() => {
167
165
  process.env.HOME = envSnapshot.HOME;
168
166
  process.env.CLINE_DIR = envSnapshot.CLINE_DIR;
169
- process.env.CLINE_CHECKPOINT = envSnapshot.CLINE_CHECKPOINT;
170
167
  setHomeDir(envSnapshot.HOME ?? "~");
171
168
  setClineDir(envSnapshot.CLINE_DIR ?? join("~", ".cline"));
172
169
  rmSync(isolatedHomeDir, { recursive: true, force: true });
@@ -652,7 +649,7 @@ describe("DefaultSessionManager", () => {
652
649
  );
653
650
  });
654
651
 
655
- it("does not install checkpoint hooks unless CLINE_CHECKPOINT=true", async () => {
652
+ it("does not install checkpoint hooks when checkpoint.enabled is not set in config", async () => {
656
653
  const sessionId = "sess-checkpoint-default-off";
657
654
  const manifest = createManifest(sessionId);
658
655
  const updateSession = vi.fn().mockResolvedValue({ updated: true });
@@ -737,10 +734,8 @@ describe("DefaultSessionManager", () => {
737
734
  });
738
735
  });
739
736
 
740
- it("installs checkpoint hooks when CLINE_CHECKPOINT=true", async () => {
741
- process.env.CLINE_CHECKPOINT = "true";
742
-
743
- const sessionId = "sess-checkpoint-env-on";
737
+ it("installs checkpoint hooks when checkpoint.enabled=true in config", async () => {
738
+ const sessionId = "sess-checkpoint-config-on";
744
739
  const repoCwd = mkdtempSync(join(isolatedHomeDir, "checkpoint-repo-"));
745
740
  createGitRepo(repoCwd);
746
741
  const manifest = createManifest(sessionId);
@@ -813,7 +808,10 @@ describe("DefaultSessionManager", () => {
813
808
  });
814
809
 
815
810
  await manager.start({
816
- config: createConfig({ sessionId, cwd: repoCwd }),
811
+ config: {
812
+ ...createConfig({ sessionId, cwd: repoCwd }),
813
+ checkpoint: { enabled: true },
814
+ },
817
815
  prompt: "hello",
818
816
  interactive: false,
819
817
  });
package/src/session/default-session-manager.ts CHANGED
@@ -115,11 +115,6 @@ type SessionBackend =
115
115
  const MAX_SCAN_LIMIT = 5000;
116
116
  const MAX_USER_FILE_BYTES = 20 * 1_000 * 1_024;
117
117
 
118
- // NOTE: Temporarily disabled until checkpoint is ready for production.
119
- function isCheckpointFeatureEnabled(): boolean {
120
- return process?.env?.CLINE_CHECKPOINT === "true";
121
- }
122
-
123
118
  async function loadUserFileContent(path: string): Promise<string> {
124
119
  const fileStat = await stat(path);
125
120
  if (!fileStat.isFile()) {
@@ -277,11 +272,12 @@ export class DefaultSessionManager implements SessionManager {
277
272
  };
278
273
  configWithProvider.hooks = mergeAgentHooks([
279
274
  effectiveConfig.hooks,
280
- isCheckpointFeatureEnabled()
275
+ effectiveConfig.checkpoint?.enabled === true
281
276
  ? createCheckpointHooks({
282
277
  cwd: configWithProvider.cwd,
283
278
  sessionId,
284
279
  logger: configWithProvider.logger,
280
+ createCheckpoint: effectiveConfig.checkpoint?.createCheckpoint,
285
281
  readSessionMetadata: async () =>
286
282
  (await this.get(sessionId))?.metadata as
287
283
  | Record<string, unknown>
package/src/session/persistence-service.test.ts CHANGED
@@ -160,13 +160,11 @@ describe("UnifiedSessionPersistenceService", () => {
160
160
  row.sessionId.includes("__teamtask__java-haiku-agent__"),
161
161
  )?.sessionId;
162
162
  expect(teammateSessionId).toBeTruthy();
163
- const path = join(
164
- sessionsDir,
165
- rootSessionId,
166
- "java-haiku-agent__" +
167
- teammateSessionId?.slice(teammateSessionId?.lastIndexOf("__") + 2) +
168
- ".messages.json",
163
+ const row = childSessions.find(
164
+ (item) => item.sessionId === teammateSessionId,
169
165
  );
166
+ expect(row?.messagesPath).toBeTruthy();
167
+ const path = row?.messagesPath as string;
170
168
  const payload = JSON.parse(readFileSync(path, "utf8")) as {
171
169
  agent?: string;
172
170
  sessionId?: string;
@@ -195,18 +193,11 @@ describe("UnifiedSessionPersistenceService", () => {
195
193
  cacheWriteTokens: 0,
196
194
  cost: 0.123,
197
195
  });
198
- const row = childSessions.find(
199
- (item) => item.sessionId === teammateSessionId,
200
- );
201
196
  expect(row?.messagesPath).toBe(path);
202
- expect(row?.transcriptPath).toBe(
203
- join(
204
- sessionsDir,
205
- rootSessionId,
206
- "java-haiku-agent__" +
207
- teammateSessionId?.slice(teammateSessionId?.lastIndexOf("__") + 2) +
208
- ".log",
209
- ),
197
+ expect(row?.transcriptPath).toBeTruthy();
198
+ expect(row?.transcriptPath).toContain(
199
+ join(sessionsDir, rootSessionId, "java-haiku-agent__"),
210
200
  );
201
+ expect(row?.transcriptPath).toMatch(/\.log$/);
211
202
  });
212
203
  });
package/src/types/config.ts CHANGED
@@ -95,6 +95,74 @@ export interface CoreCompactionConfig {
95
95
  | undefined;
96
96
  }
97
97
 
98
+ /**
99
+ * Context passed to a custom `createCheckpoint` implementation.
100
+ */
101
+ export interface CoreCheckpointContext {
102
+ /** Absolute path to the working directory of the session. */
103
+ cwd: string;
104
+ /** The session identifier. */
105
+ sessionId: string;
106
+ /** Monotonically increasing run counter for this session (starts at 1). */
107
+ runCount: number;
108
+ }
109
+
110
+ /**
111
+ * Configuration for the built-in git-based checkpoint feature.
112
+ *
113
+ * Checkpoints capture a restorable snapshot of the workspace at the start of
114
+ * each root-agent run so that changes made during a session can be rolled back.
115
+ *
116
+ * @example Disable checkpoints entirely:
117
+ * ```ts
118
+ * checkpoint: { enabled: false }
119
+ * ```
120
+ *
121
+ * @example Bring your own checkpoint implementation:
122
+ * ```ts
123
+ * checkpoint: {
124
+ * createCheckpoint: async ({ cwd, sessionId, runCount }) => {
125
+ * const ref = await mySnapshotFn(cwd);
126
+ * return { ref, createdAt: Date.now(), runCount };
127
+ * },
128
+ * }
129
+ * ```
130
+ */
131
+ export interface CoreCheckpointConfig {
132
+ /**
133
+ * Whether to create checkpoints on each root-agent run start.
134
+ * Defaults to `false` — checkpoints are **opt-in**. Set to `true` to
135
+ * enable the built-in git stash/ref checkpoint behaviour for this session.
136
+ */
137
+ enabled?: boolean;
138
+ /**
139
+ * Replace the built-in git stash/ref checkpoint logic with a custom
140
+ * implementation. Called once at the start of each root-agent run (before
141
+ * the first agent iteration).
142
+ *
143
+ * Return an object with at least `ref`, `createdAt`, and `runCount` to have
144
+ * the entry recorded in session metadata, or return `undefined` to skip
145
+ * writing a checkpoint for that run.
146
+ */
147
+ createCheckpoint?: (context: CoreCheckpointContext) =>
148
+ | Promise<
149
+ | {
150
+ ref: string;
151
+ createdAt: number;
152
+ runCount: number;
153
+ kind?: "stash" | "commit";
154
+ }
155
+ | undefined
156
+ >
157
+ | {
158
+ ref: string;
159
+ createdAt: number;
160
+ runCount: number;
161
+ kind?: "stash" | "commit";
162
+ }
163
+ | undefined;
164
+ }
165
+
98
166
  export interface CoreSessionConfig
99
167
  extends CoreModelConfig,
100
168
  CoreRuntimeFeatures,
@@ -124,6 +192,7 @@ export interface CoreSessionConfig
124
192
  extensions?: AgentConfig["extensions"];
125
193
  execution?: AgentConfig["execution"];
126
194
  compaction?: CoreCompactionConfig;
195
+ checkpoint?: CoreCheckpointConfig;
127
196
  onTeamEvent?: (event: TeamEvent) => void;
128
197
  onConsecutiveMistakeLimitReached?: (
129
198
  context: ConsecutiveMistakeLimitContext,