@clinebot/agents 0.0.0

package/src/hooks/lifecycle.ts

@@ -0,0 +1,239 @@
+import type {
+	AgentConfig,
+	AgentExtension,
+	AgentExtensionHookStage,
+	AgentHookControl,
+} from "../types.js";
+import type { HookEngine, HookHandler } from "./engine.js";
+
+type LifecycleConfig = Pick<AgentConfig, "hooks" | "extensions">;
+
+type ExtensionStageHandlerSpec = {
+	handler: (
+		extension: AgentExtension,
+		event: { payload: unknown },
+	) => Promise<AgentHookControl | undefined> | AgentHookControl | undefined;
+	name: string;
+};
+
+const EXTENSION_STAGE_HANDLERS: Record<
+	AgentExtensionHookStage,
+	ExtensionStageHandlerSpec
+> = {
+	input: {
+		name: "onInput",
+		handler: (extension, event) =>
+			extension.onInput?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	session_start: {
+		name: "onSessionStart",
+		handler: (extension, event) =>
+			extension.onSessionStart?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	run_start: {
+		name: "onRunStart",
+		handler: (extension, event) =>
+			extension.onRunStart?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	iteration_start: {
+		name: "onIterationStart",
+		handler: (extension, event) =>
+			extension.onIterationStart?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	turn_start: {
+		name: "onTurnStart",
+		handler: (extension, event) =>
+			extension.onTurnStart?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	before_agent_start: {
+		name: "onBeforeAgentStart",
+		handler: (extension, event) =>
+			extension.onBeforeAgentStart?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	tool_call_before: {
+		name: "onToolCall",
+		handler: (extension, event) =>
+			extension.onToolCall?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	tool_call_after: {
+		name: "onToolResult",
+		handler: (extension, event) =>
+			extension.onToolResult?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	turn_end: {
+		name: "onAgentEnd",
+		handler: (extension, event) =>
+			extension.onAgentEnd?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	iteration_end: {
+		name: "onIterationEnd",
+		handler: async (extension, event) => {
+			await extension.onIterationEnd?.(event.payload as never);
+			return undefined;
+		},
+	},
+	run_end: {
+		name: "onRunEnd",
+		handler: async (extension, event) => {
+			await extension.onRunEnd?.(event.payload as never);
+			return undefined;
+		},
+	},
+	session_shutdown: {
+		name: "onSessionShutdown",
+		handler: (extension, event) =>
+			extension.onSessionShutdown?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	error: {
+		name: "onError",
+		handler: async (extension, event) => {
+			await extension.onError?.(event.payload as never);
+			return undefined;
+		},
+	},
+	runtime_event: {
+		name: "onRuntimeEvent",
+		handler: async (extension, event) => {
+			await extension.onRuntimeEvent?.(event.payload as never);
+			return undefined;
+		},
+	},
+};
+
+export function registerLifecycleHandlers(
+	hookEngine: HookEngine,
+	config: LifecycleConfig,
+): void {
+	const register = (handler: HookHandler): void => {
+		hookEngine.register(handler);
+	};
+	const hooks = config.hooks;
+
+	if (hooks?.onSessionStart) {
+		register({
+			name: "hooks.onSessionStart",
+			stage: "session_start",
+			handle: (event) => hooks.onSessionStart?.(event.payload as never),
+		});
+	}
+	if (hooks?.onRunStart) {
+		register({
+			name: "hooks.onRunStart",
+			stage: "run_start",
+			handle: (event) => hooks.onRunStart?.(event.payload as never),
+		});
+	}
+	if (hooks?.onRunEnd) {
+		register({
+			name: "hooks.onRunEnd",
+			stage: "run_end",
+			handle: async (event) => {
+				await hooks.onRunEnd?.(event.payload as never);
+				return undefined;
+			},
+		});
+	}
+	if (hooks?.onIterationStart) {
+		register({
+			name: "hooks.onIterationStart",
+			stage: "iteration_start",
+			handle: (event) => hooks.onIterationStart?.(event.payload as never),
+		});
+	}
+	if (hooks?.onIterationEnd) {
+		register({
+			name: "hooks.onIterationEnd",
+			stage: "iteration_end",
+			handle: async (event) => {
+				await hooks.onIterationEnd?.(event.payload as never);
+				return undefined;
+			},
+		});
+	}
+	if (hooks?.onTurnStart) {
+		register({
+			name: "hooks.onTurnStart",
+			stage: "turn_start",
+			handle: (event) => hooks.onTurnStart?.(event.payload as never),
+		});
+	}
+	if (hooks?.onTurnEnd) {
+		register({
+			name: "hooks.onTurnEnd",
+			stage: "turn_end",
+			handle: (event) => hooks.onTurnEnd?.(event.payload as never),
+		});
+	}
+	if (hooks?.onToolCallStart) {
+		register({
+			name: "hooks.onToolCallStart",
+			stage: "tool_call_before",
+			handle: (event) => hooks.onToolCallStart?.(event.payload as never),
+		});
+	}
+	if (hooks?.onToolCallEnd) {
+		register({
+			name: "hooks.onToolCallEnd",
+			stage: "tool_call_after",
+			handle: (event) => hooks.onToolCallEnd?.(event.payload as never),
+		});
+	}
+	if (hooks?.onSessionShutdown) {
+		register({
+			name: "hooks.onSessionShutdown",
+			stage: "session_shutdown",
+			handle: (event) => hooks.onSessionShutdown?.(event.payload as never),
+		});
+	}
+	if (hooks?.onError) {
+		register({
+			name: "hooks.onError",
+			stage: "error",
+			handle: async (event) => {
+				await hooks.onError?.(event.payload as never);
+				return undefined;
+			},
+		});
+	}
+
+	for (const [index, extension] of (config.extensions ?? []).entries()) {
+		if (!extension.manifest.capabilities.includes("hooks")) {
+			continue;
+		}
+		const order = String(index).padStart(4, "0");
+		const extensionName = extension.name || `extension_${order}`;
+		const base = `${order}:${extensionName}`;
+		const subscribedStages = new Set(extension.manifest.hookStages ?? []);
+		for (const stage of subscribedStages) {
+			const stageHandler = EXTENSION_STAGE_HANDLERS[stage];
+			if (!stageHandler) {
+				continue;
+			}
+			register({
+				name: `${base}.${stageHandler.name}`,
+				stage,
+				handle: (event) => stageHandler.handler(extension, event),
+			});
+		}
+	}
+}

package/src/hooks/node.ts

@@ -0,0 +1,18 @@
+export {
+	createSubprocessHooks,
+	type HookEventName,
+	HookEventNameSchema,
+	type HookEventPayload,
+	HookEventPayloadSchema,
+	parseHookEventPayload,
+	type RunHookOptions,
+	type RunHookResult,
+	runHook,
+	type SubprocessHookControl,
+	type SubprocessHooksOptions,
+} from "./subprocess.js";
+export {
+	type RunSubprocessEventOptions,
+	type RunSubprocessEventResult,
+	runSubprocessEvent,
+} from "./subprocess-runner.js";

package/src/hooks/subprocess-runner.ts

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+
+export interface RunSubprocessEventOptions {
+	command: string[];
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	detached?: boolean;
+	timeoutMs?: number;
+}
+
+export interface RunSubprocessEventResult {
+	exitCode: number | null;
+	stdout: string;
+	stderr: string;
+	parsedJson?: unknown;
+	parseError?: string;
+	timedOut?: boolean;
+}
+
+function parseStdout(stdout: string): {
+	parsedJson?: unknown;
+	parseError?: string;
+} {
+	const trimmed = stdout.trim();
+	if (!trimmed) {
+		return {};
+	}
+
+	const lines = trimmed
+		.split("\n")
+		.map((line) => line.trim())
+		.filter(Boolean);
+	const prefixed = lines
+		.filter((line) => line.startsWith("HOOK_CONTROL\t"))
+		.map((line) => line.slice("HOOK_CONTROL\t".length));
+
+	const candidate =
+		prefixed.length > 0 ? prefixed[prefixed.length - 1] : trimmed;
+	try {
+		return { parsedJson: JSON.parse(candidate) };
+	} catch (error) {
+		return {
+			parseError:
+				error instanceof Error
+					? error.message
+					: "Failed to parse subprocess stdout JSON",
+		};
+	}
+}
+
+function formatSpawnError(error: unknown, command: string[]): Error {
+	const err = error instanceof Error ? error : new Error(String(error));
+	const withCode = err as Error & { code?: string };
+	const commandLabel = command.join(" ");
+	if (withCode.code === "EACCES") {
+		return new Error(
+			`Failed to execute hook command "${commandLabel}" (EACCES). Configure hooks with an explicit interpreter/command array (for example: ["bash", "/path/to/script"]) or make the script executable with a valid shebang.`,
+		);
+	}
+	return new Error(
+		`Failed to execute hook command "${commandLabel}": ${err.message}`,
+	);
+}
+
+export async function runSubprocessEvent(
+	payload: unknown,
+	options: RunSubprocessEventOptions,
+): Promise<RunSubprocessEventResult | undefined> {
+	const command = options.command;
+	if (!Array.isArray(command) || command.length === 0) {
+		throw new Error("runSubprocessEvent requires a non-empty command");
+	}
+
+	const detached = !!options.detached;
+	const child = spawn(command[0], command.slice(1), {
+		cwd: options.cwd,
+		env: options.env,
+		stdio: detached ? ["pipe", "ignore", "ignore"] : ["pipe", "pipe", "pipe"],
+		detached,
+	});
+
+	if (!child.stdin) {
+		throw new Error("runSubprocessEvent failed to create stdin pipe");
+	}
+	child.stdin.write(JSON.stringify(payload));
+	child.stdin.end();
+
+	if (detached) {
+		await new Promise<void>((resolve, reject) => {
+			child.once("error", (error) => {
+				reject(formatSpawnError(error, command));
+			});
+			child.once("spawn", () => resolve());
+		});
+		child.unref();
+		return;
+	}
+
+	if (!child.stdout || !child.stderr) {
+		throw new Error("runSubprocessEvent failed to create stdout/stderr pipes");
+	}
+
+	let stdout = "";
+	let stderr = "";
+	let timedOut = false;
+	let timeoutId: NodeJS.Timeout | undefined;
+
+	child.stdout.on("data", (chunk: Buffer | string) => {
+		stdout += chunk.toString();
+	});
+	child.stderr.on("data", (chunk: Buffer | string) => {
+		stderr += chunk.toString();
+	});
+
+	return await new Promise<RunSubprocessEventResult>((resolve, reject) => {
+		child.once("error", (error) => {
+			reject(formatSpawnError(error, command));
+		});
+		if ((options.timeoutMs ?? 0) > 0) {
+			timeoutId = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGKILL");
+			}, options.timeoutMs);
+		}
+		child.once("close", (exitCode) => {
+			if (timeoutId) {
+				clearTimeout(timeoutId);
+			}
+			const { parsedJson, parseError } = parseStdout(stdout);
+			resolve({
+				exitCode,
+				stdout,
+				stderr,
+				parsedJson,
+				parseError,
+				timedOut,
+			});
+		});
+	});
+}

package/src/hooks/subprocess.test.ts

@@ -0,0 +1,180 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createSubprocessHooks, runHook } from "./subprocess.js";
+
+const tmpPaths: string[] = [];
+
+afterEach(async () => {
+	for (const path of tmpPaths) {
+		await rm(path, { recursive: true, force: true });
+	}
+	tmpPaths.length = 0;
+});
+
+describe("hooks", () => {
+	it("runHook pipes payload to command and parses JSON stdout", async () => {
+		const result = await runHook(
+			{
+				clineVersion: "",
+				hookName: "tool_call",
+				timestamp: new Date().toISOString(),
+				taskId: "conv-1",
+				workspaceRoots: [],
+				userId: "agent-1",
+				agent_id: "agent-1",
+				parent_agent_id: null,
+				iteration: 1,
+				tool_call: {
+					id: "call-1",
+					name: "read_file",
+					input: { path: "README.md" },
+				},
+			},
+			{
+				command: [
+					process.execPath,
+					"-e",
+					"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const p=JSON.parse(d);process.stdout.write(JSON.stringify({cancel:p.hookName==='tool_call',context:'ok'}));});",
+				],
+			},
+		);
+
+		expect(result?.exitCode).toBe(0);
+		expect(result?.parsedJson).toEqual({ cancel: true, context: "ok" });
+	});
+
+	it("createSubprocessHooks maps lifecycle payloads and returns hook controls", async () => {
+		const dir = await mkdtemp(join(tmpdir(), "agents-hooks-"));
+		tmpPaths.push(dir);
+		const output = join(dir, "events.log");
+
+		const script =
+			"const fs=require('node:fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const p=JSON.parse(d);fs.appendFileSync(process.argv[1],JSON.stringify(p)+'\\n');if(p.hookName==='tool_call'){process.stdout.write(JSON.stringify({cancel:true,context:'stop-now',overrideInput:{safe:true}}));}});";
+
+		const hookControl = createSubprocessHooks({
+			command: [process.execPath, "-e", script, output],
+		});
+
+		const control = await hookControl.hooks.onToolCallStart?.({
+			agentId: "agent-main",
+			conversationId: "conv-main",
+			parentAgentId: null,
+			iteration: 2,
+			call: {
+				id: "c-1",
+				name: "bash",
+				input: { command: "ls" },
+			},
+		});
+		expect(control).toEqual({
+			cancel: true,
+			context: "stop-now",
+			overrideInput: { safe: true },
+		});
+
+		await expect(
+			hookControl.hooks.onToolCallEnd?.({
+				agentId: "agent-main",
+				conversationId: "conv-main",
+				parentAgentId: null,
+				iteration: 2,
+				record: {
+					id: "c-1",
+					name: "bash",
+					input: { command: "ls" },
+					output: "ok",
+					durationMs: 1,
+					startedAt: new Date(),
+					endedAt: new Date(),
+				},
+			}),
+		).resolves.toBeUndefined();
+		await expect(
+			hookControl.hooks.onTurnEnd?.({
+				agentId: "agent-main",
+				conversationId: "conv-main",
+				parentAgentId: null,
+				iteration: 2,
+				turn: {
+					text: "done",
+					toolCalls: [],
+					usage: { inputTokens: 1, outputTokens: 1 },
+					truncated: false,
+				},
+			}),
+		).resolves.toBeUndefined();
+		await expect(
+			hookControl.shutdown({
+				agentId: "agent-main",
+				conversationId: "conv-main",
+				parentAgentId: null,
+				reason: "test",
+			}),
+		).resolves.toBeUndefined();
+
+		await new Promise((resolve) => setTimeout(resolve, 80));
+		const lines = (await readFile(output, "utf8"))
+			.trim()
+			.split("\n")
+			.map((line) => JSON.parse(line));
+
+		expect(lines.some((e) => e.hookName === "tool_call")).toBe(true);
+	});
+
+	it("reports dispatch errors without throwing", async () => {
+		const onDispatchError = vi
+			.fn<(error: Error) => void>()
+			.mockImplementation(() => undefined);
+
+		const hookControl = createSubprocessHooks({
+			command: ["/path/does/not/exist"],
+			onDispatchError: (error) => onDispatchError(error),
+		});
+
+		await expect(
+			hookControl.hooks.onToolCallEnd?.({
+				agentId: "agent-main",
+				conversationId: "conv-main",
+				parentAgentId: null,
+				iteration: 2,
+				record: {
+					id: "c-1",
+					name: "bash",
+					input: { command: "ls" },
+					output: "ok",
+					durationMs: 1,
+					startedAt: new Date(),
+					endedAt: new Date(),
+				},
+			}),
+		).resolves.toBeUndefined();
+
+		await new Promise((resolve) => setTimeout(resolve, 30));
+		expect(onDispatchError).toHaveBeenCalled();
+	});
+
+	it("treats invalid tool_call stdout as dispatch error", async () => {
+		const onDispatchError = vi.fn<(error: Error) => void>();
+		const hookControl = createSubprocessHooks({
+			command: [process.execPath, "-e", "process.stdout.write('not-json')"],
+			onDispatchError: (error) => onDispatchError(error),
+		});
+
+		const result = await hookControl.hooks.onToolCallStart?.({
+			agentId: "agent-main",
+			conversationId: "conv-main",
+			parentAgentId: null,
+			iteration: 1,
+			call: {
+				id: "c-1",
+				name: "bash",
+				input: { command: "ls" },
+			},
+		});
+
+		expect(result).toBeUndefined();
+		expect(onDispatchError).toHaveBeenCalledTimes(1);
+	});
+});