@clinebot/core 0.0.28 → 0.0.29

package/src/runtime/checkpoint-hooks.ts

@@ -0,0 +1,186 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import type { AgentHooks, BasicLogger } from "@clinebot/shared";
+
+const execFile = promisify(execFileCallback);
+
+export interface CheckpointEntry {
+	ref: string;
+	createdAt: number;
+	runCount: number;
+	kind?: "stash" | "commit";
+}
+
+export interface CheckpointMetadata {
+	latest: CheckpointEntry;
+	history: CheckpointEntry[];
+}
+
+type CreateCheckpointHooksOptions = {
+	cwd: string;
+	sessionId: string;
+	logger?: BasicLogger;
+	readSessionMetadata: () => Promise<Record<string, unknown> | undefined>;
+	writeSessionMetadata: (
+		metadata: Record<string, unknown>,
+	) => Promise<void> | void;
+};
+
+function warn(logger: BasicLogger | undefined, message: string): void {
+	logger?.log(message, { severity: "warn" });
+}
+
+function readCheckpointMetadata(
+	metadata: Record<string, unknown> | undefined,
+): CheckpointMetadata | undefined {
+	const candidate = metadata?.checkpoint;
+	if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+		return undefined;
+	}
+	const record = candidate as Partial<CheckpointMetadata>;
+	if (!record.latest || !Array.isArray(record.history)) {
+		return undefined;
+	}
+	const latest = record.latest as Partial<CheckpointEntry>;
+	const history = record.history.filter(
+		(entry): entry is CheckpointEntry =>
+			!!entry &&
+			typeof entry === "object" &&
+			typeof (entry as Partial<CheckpointEntry>).ref === "string" &&
+			typeof (entry as Partial<CheckpointEntry>).createdAt === "number" &&
+			typeof (entry as Partial<CheckpointEntry>).runCount === "number",
+	);
+	if (
+		typeof latest.ref !== "string" ||
+		typeof latest.createdAt !== "number" ||
+		typeof latest.runCount !== "number"
+	) {
+		return undefined;
+	}
+	return {
+		latest: latest as CheckpointEntry,
+		history,
+	};
+}
+
+async function runGit(
+	cwd: string,
+	args: string[],
+): Promise<{ stdout: string; stderr: string }> {
+	const result = await execFile("git", ["-C", cwd, ...args], {
+		windowsHide: true,
+	});
+	return {
+		stdout: result.stdout.trim(),
+		stderr: result.stderr.trim(),
+	};
+}
+
+export function createCheckpointHooks(
+	options: CreateCheckpointHooksOptions,
+): AgentHooks {
+	let runCount = 0;
+	let repoSupported: boolean | undefined;
+
+	const ensureGitRepository = async (): Promise<boolean> => {
+		if (repoSupported !== undefined) {
+			return repoSupported;
+		}
+		try {
+			const result = await runGit(options.cwd, [
+				"rev-parse",
+				"--is-inside-work-tree",
+			]);
+			repoSupported = result.stdout === "true";
+		} catch {
+			repoSupported = false;
+		}
+		return repoSupported;
+	};
+
+	const createCheckpoint = async (): Promise<CheckpointEntry | undefined> => {
+		if (!(await ensureGitRepository())) {
+			return undefined;
+		}
+
+		const message = `cline checkpoint session=${options.sessionId} run=${runCount}`;
+		let ref = "";
+		try {
+			const result = await runGit(options.cwd, ["stash", "create", message]);
+			ref = result.stdout.trim();
+		} catch (error) {
+			warn(
+				options.logger,
+				`Checkpoint snapshot failed: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			return undefined;
+		}
+		if (!ref) {
+			try {
+				const result = await runGit(options.cwd, ["rev-parse", "HEAD"]);
+				ref = result.stdout.trim();
+			} catch (error) {
+				warn(
+					options.logger,
+					`Checkpoint HEAD fallback failed: ${error instanceof Error ? error.message : String(error)}`,
+				);
+				return undefined;
+			}
+			if (!ref) {
+				return undefined;
+			}
+			return {
+				ref,
+				createdAt: Date.now(),
+				runCount,
+				kind: "commit",
+			};
+		}
+
+		try {
+			await runGit(options.cwd, ["stash", "store", "-m", message, ref]);
+		} catch (error) {
+			warn(
+				options.logger,
+				`Checkpoint store failed: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			return undefined;
+		}
+
+		return {
+			ref,
+			createdAt: Date.now(),
+			runCount,
+			kind: "stash",
+		};
+	};
+
+	return {
+		onRunStart: async ({ parentAgentId }) => {
+			if (parentAgentId === null) {
+				runCount += 1;
+			}
+			return undefined;
+		},
+		onBeforeAgentStart: async ({ parentAgentId, iteration }) => {
+			if (parentAgentId !== null || iteration !== 1 || runCount < 1) {
+				return undefined;
+			}
+			const entry = await createCheckpoint();
+			if (!entry) {
+				return undefined;
+			}
+			const metadata = await options.readSessionMetadata();
+			const existing = readCheckpointMetadata(metadata);
+			const history = [...(existing?.history ?? []), entry];
+			await options.writeSessionMetadata({
+				...(metadata ?? {}),
+				checkpoint: {
+					latest: entry,
+					history,
+				} satisfies CheckpointMetadata,
+			});
+			return undefined;
+		},
+	};
+}

package/src/runtime/hook-file-hooks.test.ts

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { createHookConfigFileHooks } from "./hook-file-hooks";
+import { createHookConfigFileHooks, mergeAgentHooks } from "./hook-file-hooks";
 
 async function waitForFile(
 	filePath: string,
@@ -234,4 +234,43 @@ describe("createHookConfigFileHooks", () => {
 			await rm(workspace, { recursive: true, force: true });
 		}
 	});
+
+	it("merges before-agent-start controls across hook layers", async () => {
+		const hooks = mergeAgentHooks([
+			{
+				onBeforeAgentStart: async () => ({
+					systemPrompt: "system-a",
+				}),
+			},
+			{
+				onBeforeAgentStart: async () => ({
+					appendMessages: [
+						{
+							role: "user",
+							content: [{ type: "text", text: "ctx-a" }],
+						},
+					],
+				}),
+			},
+		]);
+
+		const control = await hooks?.onBeforeAgentStart?.({
+			agentId: "agent_1",
+			conversationId: "conv_1",
+			parentAgentId: null,
+			iteration: 1,
+			systemPrompt: "base",
+			messages: [],
+		});
+
+		expect(control).toMatchObject({
+			systemPrompt: "system-a",
+			appendMessages: [
+				{
+					role: "user",
+					content: [{ type: "text", text: "ctx-a" }],
+				},
+			],
+		});
+	});
 });

package/src/runtime/hook-file-hooks.ts

@@ -1,13 +1,15 @@
 import { spawn } from "node:child_process";
 import { appendFileSync, readFileSync } from "node:fs";
-import type {
-	AgentHooks,
-	HookEventName,
-	HookEventPayload,
-} from "@clinebot/agents";
-import type { BasicLogger, HookSessionContext } from "@clinebot/shared";
+import type { AgentHooks } from "@clinebot/agents";
+import {
+	augmentNodeCommandForDebug,
+	type BasicLogger,
+	type HookSessionContext,
+	withResolvedClineBuildEnv,
+} from "@clinebot/shared";
 import { ensureParentDir } from "@clinebot/shared/storage";
-import { listHookConfigFiles } from "../agents/hooks-config-loader";
+import { listHookConfigFiles } from "../extensions/config/hooks-config-loader";
+import type { HookEventName, HookEventPayload } from "../hooks";
 
 type HookContextBase = {
 	agentId: string;
@@ -64,8 +66,15 @@ function logHookError(
 ): void {
 	const detail = error instanceof Error ? `: ${error.message}` : "";
 	const text = `${message}${detail}`;
-	if (logger?.warn) {
-		logger.warn(text);
+	if (logger) {
+		try {
+			logger.log(text, {
+				severity: "warn",
+				...(error !== undefined ? { error } : {}),
+			});
+		} catch {
+			// Logging failures must not break hook execution.
+		}
 		return;
 	}
 	console.warn(text);
@@ -264,9 +273,13 @@ async function runHookCommand(
 	if (options.command.length === 0) {
 		throw new Error("runHookCommand requires non-empty command");
 	}
-	const child = spawn(options.command[0], options.command.slice(1), {
-		cwd: options.cwd,
+	const command = augmentNodeCommandForDebug(options.command, {
 		env: options.env,
+		debugRole: "hook-worker",
+	});
+	const child = spawn(command[0], command.slice(1), {
+		cwd: options.cwd,
+		env: withResolvedClineBuildEnv(options.env),
 		stdio: options.detached
 			? ["pipe", "ignore", "ignore"]
 			: ["pipe", "pipe", "pipe"],
@@ -386,7 +399,9 @@ function inferHookCommand(path: string): string[] {
 		lowered.endsWith(".mjs") ||
 		lowered.endsWith(".cjs")
 	) {
-		return ["node", path];
+		return augmentNodeCommandForDebug(["node", path], {
+			debugRole: "hook-worker",
+		});
 	}
 	if (
 		lowered.endsWith(".ts") ||
@@ -415,9 +430,10 @@ function createHookCommandMap(workspacePath: string): HookCommandMap {
 		if (!file.hookEventName) {
 			continue;
 		}
-		const existing = map[file.hookEventName] ?? [];
+		const hookEventName = file.hookEventName;
+		const existing = map[hookEventName] ?? [];
 		existing.push(inferHookCommand(file.path));
-		map[file.hookEventName] = existing;
+		map[hookEventName] = existing;
 	}
 	return map;
 }
@@ -436,7 +452,7 @@ async function runBlockingHookCommands(options: {
 			const result = await runHookCommand(options.payload, {
 				command,
 				cwd: options.cwd,
-				env: process.env,
+				env: withResolvedClineBuildEnv(process.env),
 				detached: false,
 				timeoutMs: options.timeoutMs,
 			});
@@ -474,7 +490,7 @@ function runAsyncHookCommands(options: {
 		void runHookCommand(options.payload, {
 			command,
 			cwd: options.cwd,
-			env: process.env,
+			env: withResolvedClineBuildEnv(process.env),
 			detached: true,
 		}).catch((error) => {
 			logHookError(
@@ -845,12 +861,15 @@ export function mergeAgentHooks(
 	}
 
 	return {
+		onSessionStart: mergeHookFunction(activeLayers, "onSessionStart"),
 		onRunStart: mergeHookFunction(activeLayers, "onRunStart"),
 		onRunEnd: mergeHookFunction(activeLayers, "onRunEnd"),
 		onIterationStart: mergeHookFunction(activeLayers, "onIterationStart"),
 		onIterationEnd: mergeHookFunction(activeLayers, "onIterationEnd"),
 		onTurnStart: mergeHookFunction(activeLayers, "onTurnStart"),
+		onBeforeAgentStart: mergeHookFunction(activeLayers, "onBeforeAgentStart"),
 		onTurnEnd: mergeHookFunction(activeLayers, "onTurnEnd"),
+		onStopError: mergeHookFunction(activeLayers, "onStopError"),
 		onToolCallStart: mergeHookFunction(activeLayers, "onToolCallStart"),
 		onToolCallEnd: mergeHookFunction(activeLayers, "onToolCallEnd"),
 		onSessionShutdown: mergeHookFunction(activeLayers, "onSessionShutdown"),

package/src/runtime/index.ts

@@ -1,8 +1,3 @@
-export {
-	type AvailableRuntimeCommand,
-	listAvailableRuntimeCommandsFromWatcher,
-	resolveRuntimeSlashCommandFromWatcher,
-} from "./commands";
 export {
 	formatRulesForSystemPrompt,
 	isRuleEnabled,
@@ -10,11 +5,6 @@ export {
 	loadRulesForSystemPromptFromWatcher,
 } from "./rules";
 export { createTeamName, DefaultRuntimeBuilder } from "./runtime-builder";
-export {
-	type SandboxCallOptions,
-	SubprocessSandbox,
-	type SubprocessSandboxOptions,
-} from "./sandbox/subprocess-sandbox";
 export type {
 	BuiltRuntime,
 	RuntimeBuilder,
@@ -22,16 +12,11 @@ export type {
 	SessionRuntime,
 } from "./session-runtime";
 export {
-	type AvailableSkill,
-	listAvailableSkillsFromWatcher,
-	resolveSkillsSlashCommandFromWatcher,
-} from "./skills";
+	type SandboxCallOptions,
+	SubprocessSandbox,
+	type SubprocessSandboxOptions,
+} from "./subprocess-sandbox";
 export {
 	type DesktopToolApprovalOptions,
 	requestDesktopToolApproval,
 } from "./tool-approval";
-export {
-	type AvailableWorkflow,
-	listAvailableWorkflowsFromWatcher,
-	resolveWorkflowSlashCommandFromWatcher,
-} from "./workflows";

package/src/runtime/rules.ts

@@ -1,4 +1,7 @@
-import type { RuleConfig, UserInstructionConfigWatcher } from "../agents";
+import type {
+	RuleConfig,
+	UserInstructionConfigWatcher,
+} from "../extensions/config";
 
 export function isRuleEnabled(rule: RuleConfig): boolean {
 	return rule.disabled !== true;

package/src/runtime/runtime-builder.team-persistence.test.ts

@@ -35,7 +35,7 @@ class MockAgentTeamsRuntime {
 	shutdownTeammate = vi.fn();
 }
 
-vi.mock("@clinebot/agents", () => ({
+vi.mock("../team", () => ({
 	AgentTeamsRuntime: MockAgentTeamsRuntime,
 	bootstrapAgentTeams: bootstrapAgentTeamsMock,
 	createDelegatedAgentConfigProvider: (config: Record<string, unknown>) => {
@@ -109,7 +109,7 @@ describe("DefaultRuntimeBuilder team persistence boundary", () => {
 		const { DefaultRuntimeBuilder } = await import("./runtime-builder");
 		const onTeamRestored = vi.fn();
 
-		new DefaultRuntimeBuilder().build({
+		await new DefaultRuntimeBuilder().build({
 			config: {
 				providerId: "anthropic",
 				modelId: "claude-sonnet-4-6",
@@ -194,7 +194,7 @@ describe("DefaultRuntimeBuilder team persistence boundary", () => {
 		const { DefaultRuntimeBuilder } = await import("./runtime-builder");
 		bootstrapAgentTeamsMock.mockClear();
 
-		new DefaultRuntimeBuilder().build({
+		await new DefaultRuntimeBuilder().build({
 			config: {
 				providerId: "cline",
 				modelId: "anthropic/claude-sonnet-4.6",
@@ -236,9 +236,6 @@ describe("DefaultRuntimeBuilder team persistence boundary", () => {
 			expect.objectContaining({
 				providerId: "cline",
 				cwd: "/repo/demo",
-				clineWorkspaceMetadata: expect.stringContaining(
-					"# Workspace Configuration",
-				),
 			}),
 		);
 	});