@clinebot/core 0.0.35 → 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/hooks/index.ts

@@ -1,10 +1,3 @@
-export {
-	createPersistentSubprocessHooks,
-	PersistentHookClient,
-	type PersistentHookClientOptions,
-	type PersistentSubprocessHookControl,
-	type PersistentSubprocessHooksOptions,
-} from "./persistent";
 export {
 	createSubprocessHooks,
 	type HookEventName,

package/src/hooks/subprocess-runner.ts

@@ -113,7 +113,7 @@ export async function runSubprocessEvent(
 ): Promise<RunSubprocessEventResult | undefined> {
 	const command = augmentNodeCommandForDebug(options.command, {
 		env: options.env,
-		debugRole: "hook-worker",
+		debugRole: "hook",
 	});
 	if (!Array.isArray(command) || command.length === 0) {
 		throw new Error("runSubprocessEvent requires a non-empty command");

package/src/hooks/subprocess.ts

@@ -26,6 +26,7 @@ import {
 	type ToolCallHookPayload,
 	type ToolResultHookPayload,
 	type UserPromptSubmitData,
+	type WorkspaceInfo,
 } from "@clinebot/shared";
 import { z } from "zod";
 import {
@@ -133,6 +134,13 @@ export async function runHook(
 export interface SubprocessHooksOptions {
 	command?: string[];
 	cwd?: string;
+	/**
+	 * Structured workspace and git metadata forwarded into every hook payload
+	 * as `workspaceInfo`. Obtained from `generateWorkspaceInfo` at session
+	 * startup and passed here so hook scripts can inspect branch, commit, and
+	 * remote without running their own `git` commands.
+	 */
+	workspaceInfo?: WorkspaceInfo;
 	env?: NodeJS.ProcessEnv;
 	timeoutMs?: number;
 	onDispatchError?: (error: Error, payload: HookEventPayload) => void;
@@ -240,6 +248,7 @@ function basePayload(
 			parentAgentId: ctx.parentAgentId,
 		}),
 		workspaceRoots: workspaceRoot ? [workspaceRoot] : [],
+		workspaceInfo: options.workspaceInfo,
 		userId,
 		agent_id: ctx.agentId,
 		parent_agent_id: ctx.parentAgentId,

package/src/hub/browser-websocket.ts

@@ -0,0 +1,159 @@
+import type {
+	HubClientRegistration,
+	HubEventEnvelope,
+	HubReplyEnvelope,
+	HubTransportFrame,
+} from "@clinebot/shared";
+import { safeJsonParse } from "@clinebot/shared";
+import type { HubCommandTransport } from "./transport";
+
+export interface BrowserHubSocketLike {
+	send(data: string): void;
+	addEventListener(
+		type: "message",
+		listener: (event: { data: string }) => void,
+	): void;
+	addEventListener(type: "close", listener: () => void): void;
+	removeEventListener(
+		type: "message",
+		listener: (event: { data: string }) => void,
+	): void;
+	removeEventListener(type: "close", listener: () => void): void;
+}
+
+export class BrowserWebSocketHubAdapter {
+	constructor(private readonly transport: HubCommandTransport) {}
+
+	attach(socket: BrowserHubSocketLike): () => void {
+		const subscriptions = new Map<string, () => void>();
+		const registeredClientIds = new Set<string>();
+		let closed = false;
+
+		const sendFrame = (frame: HubTransportFrame): void => {
+			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 => {
+			sendFrame({ kind: "event", envelope });
+		};
+
+		const onMessage = async (event: { data: string }): Promise<void> => {
+			try {
+				const frame = JSON.parse(event.data) as HubTransportFrame;
+				switch (frame.kind) {
+					case "command": {
+						const reply = await this.transport.command(frame.envelope);
+						if (frame.envelope.command === "client.register" && reply.ok) {
+							const registration = (frame.envelope.payload ??
+								{}) as unknown as HubClientRegistration;
+							const clientId =
+								registration.clientId?.trim() ||
+								frame.envelope.clientId?.trim();
+							if (clientId) {
+								registeredClientIds.add(clientId);
+							}
+						} else if (
+							frame.envelope.command === "client.unregister" &&
+							reply.ok
+						) {
+							const clientId = frame.envelope.clientId?.trim();
+							if (clientId) {
+								registeredClientIds.delete(clientId);
+							}
+						}
+						sendFrame({
+							kind: "reply",
+							envelope: reply satisfies HubReplyEnvelope,
+						});
+						break;
+					}
+					case "stream.subscribe": {
+						const key = `${frame.clientId}:${frame.sessionId ?? "*"}`;
+						if (subscriptions.has(key)) {
+							break;
+						}
+						const unsubscribe = await this.transport.subscribe(
+							frame.clientId,
+							onEvent,
+							{ sessionId: frame.sessionId },
+						);
+						subscriptions.set(key, unsubscribe);
+						break;
+					}
+					case "stream.unsubscribe": {
+						const key = `${frame.clientId}:${frame.sessionId ?? "*"}`;
+						subscriptions.get(key)?.();
+						subscriptions.delete(key);
+						break;
+					}
+					case "reply":
+					case "event":
+						break;
+				}
+			} catch (error) {
+				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: {
+						...parsed.envelope,
+						ok: false,
+						error: {
+							code: "command_failed",
+							message:
+								error instanceof Error ? error.message : "Unknown hub error",
+						},
+					} satisfies HubReplyEnvelope,
+				});
+			}
+		};
+
+		const onClose = (): void => {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			for (const unsubscribe of subscriptions.values()) {
+				unsubscribe();
+			}
+			subscriptions.clear();
+			for (const clientId of registeredClientIds) {
+				void this.transport.command({
+					version: "v1",
+					command: "client.unregister",
+					clientId,
+				});
+			}
+			registeredClientIds.clear();
+			socket.removeEventListener("message", onMessage);
+			socket.removeEventListener("close", onClose);
+		};
+
+		socket.addEventListener("message", onMessage);
+		socket.addEventListener("close", onClose);
+
+		return onClose;
+	}
+}