@clinebot/core 0.0.36 → 0.0.37

package/src/hooks/hook-registry.ts

@@ -0,0 +1,257 @@
+/**
+ * Lifecycle-hook registration wiring for the legacy `AgentHooks` and
+ * `AgentExtension` surfaces onto a `HookEngine`.
+ *
+ * @see PLAN.md §3.1 — moved from `packages/agents/src/runtime/hook-registry.ts`.
+ * @see PLAN.md §3.3.3 — OLD `config.hooks.*` → NEW placement.
+ *
+ * Verbatim port: pure wiring with no state. After the migration this is
+ * invoked by `HookBridge` and the legacy-agent facade's `addTools`
+ * pathway. Lives under `packages/core/src/hooks/` per §3.1.
+ */
+
+import type {
+	AgentConfig,
+	AgentExtension,
+	AgentExtensionHookStage,
+	AgentHookControl,
+	HookEngine,
+	HookHandler,
+} from "@clinebot/shared";
+
+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: "onTurnEnd",
+		handler: (extension, event) =>
+			extension.onTurnEnd?.(event.payload as never) as
+				| AgentHookControl
+				| undefined,
+	},
+	stop_error: {
+		name: "onAgentError",
+		handler: (extension, event) =>
+			extension.onAgentError?.(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?.onBeforeAgentStart) {
+		register({
+			name: "hooks.onBeforeAgentStart",
+			stage: "before_agent_start",
+			handle: (event) => hooks.onBeforeAgentStart?.(event.payload as never),
+		});
+	}
+	if (hooks?.onTurnEnd) {
+		register({
+			name: "hooks.onTurnEnd",
+			stage: "turn_end",
+			handle: (event) => hooks.onTurnEnd?.(event.payload as never),
+		});
+	}
+	if (hooks?.onStopError)
+		register({
+			name: "hooks.onStopError",
+			stage: "stop_error",
+			handle: (event) => hooks.onStopError?.(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.disabled) continue;
+		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/hub/browser-websocket.ts

@@ -4,6 +4,7 @@ import type {
 	HubReplyEnvelope,
 	HubTransportFrame,
 } from "@clinebot/shared";
+import { safeJsonParse } from "@clinebot/shared";
 import type { HubCommandTransport } from "./transport";
 
 export interface BrowserHubSocketLike {
@@ -29,7 +30,17 @@ export class BrowserWebSocketHubAdapter {
 		let closed = false;
 
 		const sendFrame = (frame: HubTransportFrame): void => {
-			socket.send(JSON.stringify(frame));
+			try {
+				socket.send(JSON.stringify(frame));
+			} catch (error) {
+				console.error(
+					`[hub] failed to send websocket frame: ${
+						error instanceof Error
+							? error.stack || error.message
+							: String(error)
+					}`,
+				);
+			}
 		};
 
 		const onEvent = (envelope: HubEventEnvelope): void => {
@@ -37,8 +48,8 @@ export class BrowserWebSocketHubAdapter {
 		};
 
 		const onMessage = async (event: { data: string }): Promise<void> => {
-			const frame = JSON.parse(event.data) as HubTransportFrame;
 			try {
+				const frame = JSON.parse(event.data) as HubTransportFrame;
 				switch (frame.kind) {
 					case "command": {
 						const reply = await this.transport.command(frame.envelope);
@@ -90,13 +101,24 @@ export class BrowserWebSocketHubAdapter {
 						break;
 				}
 			} catch (error) {
-				if (frame.kind !== "command") {
+				const parsed =
+					typeof event.data === "string"
+						? safeJsonParse<HubTransportFrame>(event.data)
+						: undefined;
+				if (!parsed || parsed.kind !== "command") {
+					console.error(
+						`[hub] rejected malformed websocket frame: ${
+							error instanceof Error
+								? error.stack || error.message
+								: String(error)
+						}`,
+					);
 					return;
 				}
 				sendFrame({
 					kind: "reply",
 					envelope: {
-						...frame.envelope,
+						...parsed.envelope,
 						ok: false,
 						error: {
 							code: "command_failed",

package/src/hub/client.ts

@@ -152,6 +152,7 @@ export class NodeHubClient {
 	private readonly listeners = new Set<SubscriptionEntry>();
 	private readonly subscriptionCounts = new Map<string, number>();
 	private lastCloseMessage = "Hub connection closed";
+	private registered = false;
 
 	constructor(private readonly options: HubClientOptions) {
 		this.clientId =
@@ -253,6 +254,7 @@ export class NodeHubClient {
 				cwd: this.options.cwd,
 			},
 		} satisfies HubClientRegistration);
+		this.registered = true;
 		for (const key of this.subscriptionCounts.keys()) {
 			this.sendSubscriptionFrame(
 				"stream.subscribe",
@@ -281,27 +283,36 @@ export class NodeHubClient {
 		command: HubCommandEnvelope["command"],
 		payload?: Record<string, unknown>,
 		sessionId?: string,
+		options?: { timeoutMs?: number | null },
 	): Promise<HubReplyEnvelope> {
 		await this.connect();
 		const requestId = createSessionId("hubreq_");
 		const reply = new Promise<HubReplyEnvelope>((resolve, reject) => {
-			const timeout = setTimeout(() => {
-				if (!this.pendingReplies.delete(requestId)) {
-					return;
-				}
-				reject(
-					new Error(
-						`Hub command ${command} timed out after ${HUB_COMMAND_TIMEOUT_MS}ms`,
-					),
-				);
-			}, HUB_COMMAND_TIMEOUT_MS);
+			const timeoutMs = options?.timeoutMs;
+			const timeout =
+				timeoutMs === null
+					? undefined
+					: setTimeout(() => {
+							if (!this.pendingReplies.delete(requestId)) {
+								return;
+							}
+							reject(
+								new Error(
+									`Hub command ${command} timed out after ${timeoutMs ?? HUB_COMMAND_TIMEOUT_MS}ms`,
+								),
+							);
+						}, timeoutMs ?? HUB_COMMAND_TIMEOUT_MS);
 			this.pendingReplies.set(requestId, {
 				resolve: (value) => {
-					clearTimeout(timeout);
+					if (timeout) {
+						clearTimeout(timeout);
+					}
 					resolve(value);
 				},
 				reject: (error) => {
-					clearTimeout(timeout);
+					if (timeout) {
+						clearTimeout(timeout);
+					}
 					reject(error);
 				},
 			});
@@ -328,6 +339,7 @@ export class NodeHubClient {
 
 	close(): void {
 		const socket = this.socket;
+		this.registered = false;
 		if (!socket) {
 			return;
 		}
@@ -345,6 +357,21 @@ export class NodeHubClient {
 		}
 	}
 
+	async dispose(): Promise<void> {
+		const socket = this.socket;
+		if (socket?.readyState === 1 && this.registered) {
+			try {
+				await this.command("client.unregister", undefined, undefined, {
+					timeoutMs: 2_000,
+				});
+			} catch {
+				// Best-effort unregister during shutdown. The websocket adapter also
+				// unregisters clients on close, so failure here should not block teardown.
+			}
+		}
+		this.close();
+	}
+
 	private sendFrame(frame: HubTransportFrame): void {
 		if (!this.socket || this.socket.readyState !== 1) {
 			throw new Error(
@@ -486,7 +513,8 @@ async function probeCompatibleHubUrl(
 		};
 	}
 	const buildId = resolveHubBuildId();
-	if (record.buildId?.trim() && record.buildId !== buildId) {
+	const recordBuildId = record.buildId?.trim();
+	if (!recordBuildId || recordBuildId !== buildId) {
 		return {
 			status: "build_mismatch",
 			url: normalized,
@@ -572,3 +600,34 @@ export async function ensureCompatibleLocalHubUrl(
 	spawnDetachedHubServer(options.workspaceRoot ?? process.cwd());
 	return await waitForCompatibleHubUrl(owner);
 }
+
+export async function requestHubShutdown(url: string): Promise<boolean> {
+	const parsed = new URL(url);
+	if (parsed.protocol === "ws:") {
+		parsed.protocol = "http:";
+	} else if (parsed.protocol === "wss:") {
+		parsed.protocol = "https:";
+	}
+	parsed.pathname = "/shutdown";
+	parsed.search = "";
+	parsed.hash = "";
+	const response = await fetch(parsed, { method: "POST" });
+	return response.ok;
+}
+
+export async function stopLocalHubServerGracefully(): Promise<boolean> {
+	const owner = resolveSharedHubOwnerContext();
+	const discovery = await readHubDiscovery(owner.discoveryPath);
+	if (!discovery?.url) {
+		return false;
+	}
+	try {
+		const stopped = await requestHubShutdown(discovery.url);
+		if (stopped) {
+			return true;
+		}
+	} catch {
+		// Fall through so callers can apply a stronger fallback.
+	}
+	return false;
+}

package/src/hub/daemon-entry.ts

@@ -1,8 +1,11 @@
+import { initVcr } from "@clinebot/shared";
 import { resolveHubEndpointOptions } from "./defaults";
 import { createLocalHubScheduleRuntimeHandlers } from "./runtime-handlers";
 import { startHubWebSocketServer } from "./server";
 import { resolveSharedHubOwnerContext } from "./workspace";
 
+initVcr(process.env.CLINE_VCR);
+
 function parseArgs(argv: string[]): {
 	cwd: string;
 	host?: string;
@@ -60,6 +63,7 @@ async function main(): Promise<void> {
 		pathname: endpoint.pathname,
 		owner: resolveSharedHubOwnerContext(),
 		runtimeHandlers: createLocalHubScheduleRuntimeHandlers(),
+		cronOptions: { workspaceRoot: options.cwd },
 	});
 
 	const shutdown = async (): Promise<void> => {
@@ -67,12 +71,43 @@ async function main(): Promise<void> {
 		process.exit(0);
 	};
 
+	let fatalShutdownStarted = false;
+	const shutdownFatal = (label: string, error: unknown): void => {
+		if (fatalShutdownStarted) {
+			return;
+		}
+		fatalShutdownStarted = true;
+		const message =
+			error instanceof Error ? error.stack || error.message : String(error);
+		process.stderr.write(`[hub-daemon] ${label}: ${message}\n`);
+		void server
+			.close()
+			.catch((closeError) => {
+				const closeMessage =
+					closeError instanceof Error
+						? closeError.stack || closeError.message
+						: String(closeError);
+				process.stderr.write(
+					`[hub-daemon] shutdown after ${label} failed: ${closeMessage}\n`,
+				);
+			})
+			.finally(() => {
+				process.exit(1);
+			});
+	};
+
 	process.on("SIGINT", () => {
 		void shutdown();
 	});
 	process.on("SIGTERM", () => {
 		void shutdown();
 	});
+	process.on("uncaughtException", (error) => {
+		shutdownFatal("uncaughtException", error);
+	});
+	process.on("unhandledRejection", (reason) => {
+		shutdownFatal("unhandledRejection", reason);
+	});
 
 	await new Promise<void>(() => {
 		// keep daemon process alive