@hansenexus/hud 0.3.0 → 0.4.0

package/dist/plugins/agent/server.js

@@ -0,0 +1,429 @@
+import { i as definePlugin } from "../../plugins-DVy_vaYr.js";
+//#region src/plugins/agent/prompt.ts
+/** The task text every provider receives: grab context first, then the instruction. */
+function dispatchPrompt({ note, payload, hints = [] }) {
+	const instruction = note.trim() || "Improve the grabbed element (see context).";
+	if (!payload) return [
+		`Instruction: ${instruction}`,
+		"",
+		"Task: apply the instruction and run the project's checks."
+	].join("\n");
+	const { component, anchor } = payload;
+	const lines = [
+		`HUD dispatch from ${payload.app}, page ${payload.url || payload.route}.`,
+		`Grabbed element: ${anchor.label}`,
+		`Selector (from <body>): ${anchor.selector}`
+	];
+	if (component) {
+		const owners = component.owners.length > 0 ? ` inside ${component.owners.join(" < ")}` : "";
+		lines.push(`React component: <${component.name}>${owners}`);
+		if (component.source) lines.push(`Source hint (from React; line approximate): ${component.source}`);
+	}
+	if (hints.length > 0) lines.push(`Component manifest matches (best effort, verify): ${hints.map((h) => h.path).join(", ")}`);
+	if (!component?.source && hints.length === 0) lines.push("No source hint: locate the component from the route and selector.");
+	lines.push(`Viewport: ${payload.viewport.width}×${payload.viewport.height}`, `Instruction: ${instruction}`, "", "Task: locate the element's source, apply the instruction, and run the project's checks.");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/plugins/agent/providers/claude-code.ts
+/** A transcript touched within this window counts as a running session. */
+const ACTIVE_MS = 12e4;
+/** Enough of a transcript to find its summary or first prompt without reading megabytes. */
+const HEAD_BYTES = 65536;
+const defaultArgs = (prompt) => [
+	"-p",
+	prompt,
+	"--permission-mode",
+	"acceptEdits"
+];
+/** Claude Code keeps transcripts in `~/.claude/projects/<cwd with every non-alphanumeric as ->`. */
+function projectDirName(cwd) {
+	return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/** Summary line, else first plain user prompt, from the head of a transcript. */
+function transcriptTitle(head) {
+	let prompt;
+	for (const line of head.split("\n")) {
+		let entry;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (entry.type === "summary" && typeof entry.summary === "string") return entry.summary;
+		if (prompt || entry.type !== "user") continue;
+		const content = entry.message?.content;
+		const text = typeof content === "string" ? content : Array.isArray(content) ? content.find((c) => c?.type === "text")?.text : void 0;
+		if (typeof text === "string" && text.trim() && !text.trimStart().startsWith("<")) prompt = text.trim().split("\n")[0];
+	}
+	return prompt?.slice(0, 120);
+}
+/**
+* Node built-ins, loaded on first use. A static import would make the whole
+* server entry unloadable wherever `node:` modules are missing (an edge
+* route, the playground's MSW worker), even for apps that only use `hermes()`.
+*/
+async function loadNode() {
+	const [childProcess, fs, fsp, os, path, proc] = await Promise.all([
+		import("node:child_process"),
+		import("node:fs"),
+		import("node:fs/promises"),
+		import("node:os"),
+		import("node:path"),
+		import("node:process")
+	]);
+	return {
+		childProcess,
+		fs,
+		fsp,
+		os,
+		path,
+		env: proc.env
+	};
+}
+async function readHead({ fsp }, path) {
+	const file = await fsp.open(path, "r");
+	try {
+		const buffer = new Uint8Array(HEAD_BYTES);
+		const { bytesRead } = await file.read(buffer, 0, HEAD_BYTES, 0);
+		return new TextDecoder().decode(buffer.subarray(0, bytesRead));
+	} finally {
+		await file.close();
+	}
+}
+/**
+* Dispatches to a local Claude Code: each run is `claude -p <prompt>` spawned
+* (argv, no shell) in `cwd`, detached so it outlives a dev-server reload, with
+* its output in a log file. Sessions are the runs started here plus the most
+* recent Claude Code transcripts of `cwd`.
+*/
+function claudeCode({ cwd: cwdOption, command = "claude", args = defaultArgs, label = "Claude Code (local)", logDir: logDirOption, transcripts = 8, home: homeOption, spawn: spawnOption } = {}) {
+	const runs = /* @__PURE__ */ new Map();
+	let node;
+	const nodeApi = () => {
+		node ??= loadNode();
+		return node;
+	};
+	const cwdOf = ({ path }) => cwdOption ?? path.resolve();
+	async function listTranscripts() {
+		const api = await nodeApi();
+		const { fsp, path } = api;
+		const home = homeOption ?? api.os.homedir();
+		const dir = path.join(home, ".claude", "projects", projectDirName(cwdOf(api)));
+		let names;
+		try {
+			names = (await fsp.readdir(dir)).filter((name) => name.endsWith(".jsonl"));
+		} catch {
+			return [];
+		}
+		const recent = (await Promise.all(names.map(async (name) => {
+			const file = path.join(dir, name);
+			return {
+				file,
+				mtime: (await fsp.stat(file)).mtimeMs
+			};
+		}))).sort((a, b) => b.mtime - a.mtime).slice(0, transcripts);
+		return Promise.all(recent.map(async ({ file, mtime }) => {
+			const id = path.basename(file, ".jsonl");
+			return {
+				provider: "claude-code",
+				id,
+				title: transcriptTitle(await readHead(api, file).catch(() => "")) ?? id.slice(0, 8),
+				status: Date.now() - mtime < ACTIVE_MS ? "running" : "idle",
+				updatedAt: new Date(mtime).toISOString()
+			};
+		}));
+	}
+	return {
+		id: "claude-code",
+		label,
+		description: cwdOption ? `claude -p in ${cwdOption}` : "claude -p in the dev server's directory",
+		async dispatch(order) {
+			const api = await nodeApi();
+			const { fs, path } = api;
+			const logDir = logDirOption ?? path.join(api.os.tmpdir(), "hud-agent");
+			const spawn = spawnOption ?? api.childProcess.spawn;
+			await api.fsp.mkdir(logDir, { recursive: true });
+			const id = `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+			const log = path.join(logDir, `${id}.log`);
+			const fd = fs.openSync(log, "a", 384);
+			let child;
+			try {
+				child = spawn(command, args(order.prompt), {
+					cwd: cwdOf(api),
+					detached: true,
+					stdio: [
+						"ignore",
+						fd,
+						fd
+					],
+					env: api.env
+				});
+				await new Promise((resolve, reject) => {
+					child.once("spawn", resolve);
+					child.once("error", reject);
+				});
+			} finally {
+				fs.closeSync(fd);
+			}
+			const run = {
+				id,
+				title: order.note.trim().split("\n")[0] || order.payload?.anchor.label || "dispatch",
+				status: "running",
+				startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				log
+			};
+			runs.set(id, run);
+			child.once("exit", (code) => {
+				run.status = code === 0 ? "done" : "failed";
+				run.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+			});
+			child.unref();
+			return {
+				runId: id,
+				detail: log
+			};
+		},
+		async sessions() {
+			return [...[...runs.values()].map((run) => ({
+				provider: "claude-code",
+				id: run.id,
+				title: run.title,
+				status: run.status,
+				startedAt: run.startedAt,
+				...run.updatedAt ? { updatedAt: run.updatedAt } : {},
+				detail: run.log
+			})).reverse(), ...await listTranscripts()];
+		}
+	};
+}
+//#endregion
+//#region src/plugins/agent/providers/hermes.ts
+const STATUS = {
+	queued: "queued",
+	running: "running",
+	succeeded: "done",
+	failed: "failed"
+};
+/**
+* Dispatches to a Hermes Agent API server: `POST /v1/runs` starts a
+* background run (202 `{ run_id }`), `GET /v1/jobs` lists runs for the
+* Sessions panel. The token never leaves the server.
+*/
+function hermes({ baseUrl, token, instructions, label = "Hermes", timeoutMs = 1e4, fetch: fetchImpl = globalThis.fetch }) {
+	const base = baseUrl.replace(/\/+$/, "");
+	const bearer = () => (typeof token === "function" ? token() : token)?.trim() || void 0;
+	async function call(path, init) {
+		const auth = bearer();
+		if (!auth) throw new Error("no Hermes token configured");
+		const res = await fetchImpl(`${base}${path}`, {
+			...init,
+			headers: {
+				Accept: "application/json",
+				Authorization: `Bearer ${auth}`,
+				...init?.body ? { "Content-Type": "application/json" } : {}
+			},
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		if (!res.ok) throw new Error(`Hermes answered ${res.status}`);
+		return res.json();
+	}
+	return {
+		id: "hermes",
+		label,
+		description: "Remote Hermes Agent run",
+		status: () => bearer() ? { available: true } : {
+			available: false,
+			reason: "no Hermes token configured"
+		},
+		async dispatch(order) {
+			const body = await call("/v1/runs", {
+				method: "POST",
+				body: JSON.stringify({
+					input: order.prompt,
+					...instructions ? { instructions } : {}
+				})
+			});
+			if (typeof body?.run_id !== "string" || !body.run_id) throw new Error("Hermes accepted the run but returned no run_id");
+			return { runId: body.run_id };
+		},
+		async sessions() {
+			const jobs = await call("/v1/jobs");
+			if (!Array.isArray(jobs)) throw new Error("Hermes /v1/jobs: expected an array");
+			return jobs.map((job) => {
+				const session = {
+					provider: "hermes",
+					id: job.id,
+					title: job.task?.split("\n")[0]?.slice(0, 120) || job.id,
+					status: STATUS[job.status] ?? "idle"
+				};
+				if (typeof job.createdAt === "number") {
+					session.startedAt = new Date(job.createdAt).toISOString();
+					if (typeof job.durationMs === "number") session.updatedAt = new Date(job.createdAt + job.durationMs).toISOString();
+				}
+				return session;
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/agent/server.ts
+function message(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* A dispatch spawns an agent, so a page on another origin must not be able to
+* trigger one through the developer's browser. A JSON content type forces a
+* CORS preflight that this route never answers, and `Sec-Fetch-Site` rejects
+* cross-site requests outright where the browser sends it.
+*/
+function refuseCrossSite(request) {
+	const site = request.headers.get("sec-fetch-site");
+	if (site && site !== "same-origin" && site !== "none") return Response.json({
+		ok: false,
+		error: "cross-site request refused"
+	}, { status: 403 });
+	if (!request.headers.get("content-type")?.toLowerCase().startsWith("application/json")) return Response.json({
+		ok: false,
+		error: "expected application/json"
+	}, { status: 415 });
+	return null;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Shape check, not a schema: enough that the prompt builder cannot throw on it. */
+function parseBody(value) {
+	if (!isRecord(value) || typeof value.target !== "string") return null;
+	const note = typeof value.note === "string" ? value.note : "";
+	const payload = value.payload;
+	const validPayload = isRecord(payload) && typeof payload.app === "string" && typeof payload.route === "string" && isRecord(payload.anchor) && typeof payload.anchor.label === "string" && typeof payload.anchor.selector === "string" && isRecord(payload.viewport) && typeof payload.viewport.width === "number" && typeof payload.viewport.height === "number" && (payload.component == null || isRecord(payload.component) && typeof payload.component.name === "string" && Array.isArray(payload.component.owners));
+	if (payload != null && !validPayload) return null;
+	const hints = Array.isArray(value.hints) ? value.hints.filter((h) => isRecord(h) && typeof h.name === "string" && typeof h.path === "string") : [];
+	return {
+		target: value.target,
+		note,
+		payload: validPayload ? payload : null,
+		hints
+	};
+}
+function checkUnique(providers) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const provider of providers) {
+		if (ids.has(provider.id)) throw new Error(`hud agent: duplicate provider id "${provider.id}"`);
+		ids.add(provider.id);
+	}
+}
+/**
+* Server half of `agentDispatch`: `GET /targets` lists the providers,
+* `POST /dispatch` hands a grab plus instruction to one of them.
+*/
+function agentDispatch({ providers }) {
+	checkUnique(providers);
+	const byId = new Map(providers.map((provider) => [provider.id, provider]));
+	return definePlugin({
+		id: "agent-dispatch",
+		routes: {
+			"/targets": { GET: async () => {
+				const targets = await Promise.all(providers.map(async (provider) => {
+					const info = {
+						id: provider.id,
+						label: provider.label,
+						available: true
+					};
+					if (provider.description) info.description = provider.description;
+					try {
+						const status = await provider.status?.() ?? { available: true };
+						if (!status.available) return {
+							...info,
+							available: false,
+							reason: status.reason
+						};
+					} catch (error) {
+						return {
+							...info,
+							available: false,
+							reason: message(error)
+						};
+					}
+					return info;
+				}));
+				return Response.json(targets);
+			} },
+			"/dispatch": { POST: async (request) => {
+				const refusal = refuseCrossSite(request);
+				if (refusal) return refusal;
+				const body = parseBody(await request.json().catch(() => null));
+				if (!body) return Response.json({
+					ok: false,
+					error: "invalid dispatch"
+				}, { status: 400 });
+				const fail = (status, error) => Response.json({
+					ok: false,
+					target: body.target,
+					error
+				}, { status });
+				if (!body.note.trim() && !body.payload) return fail(400, "nothing to dispatch");
+				const provider = byId.get(body.target);
+				if (!provider) return fail(404, `unknown target "${body.target}"`);
+				try {
+					const status = await provider.status?.() ?? { available: true };
+					if (!status.available) return fail(409, status.reason);
+					const hints = body.hints ?? [];
+					const prompt = dispatchPrompt({
+						note: body.note,
+						payload: body.payload,
+						hints
+					});
+					const run = await provider.dispatch({
+						note: body.note,
+						payload: body.payload,
+						hints,
+						prompt
+					});
+					const receipt = {
+						ok: true,
+						target: provider.id,
+						runId: run.runId
+					};
+					if (run.detail) receipt.detail = run.detail;
+					return Response.json(receipt);
+				} catch (error) {
+					return fail(502, message(error));
+				}
+			} }
+		}
+	});
+}
+/** Server half of `agentSessions`: `GET /sessions` merges every provider's sessions. */
+function agentSessions({ providers }) {
+	checkUnique(providers);
+	const listing = providers.filter((provider) => provider.sessions);
+	return definePlugin({
+		id: "agent-sessions",
+		routes: { "/sessions": { GET: async () => {
+			const results = await Promise.allSettled(listing.map(async (provider) => {
+				return (await provider.status?.() ?? { available: true }).available ? await provider.sessions?.() ?? [] : [];
+			}));
+			const response = {
+				sessions: [],
+				errors: []
+			};
+			for (const [i, result] of results.entries()) {
+				const provider = listing[i]?.id ?? "unknown";
+				if (result.status === "fulfilled") response.sessions.push(...result.value);
+				else response.errors.push({
+					provider,
+					error: message(result.reason)
+				});
+			}
+			response.sessions.sort((a, b) => sortKey(b).localeCompare(sortKey(a)));
+			return Response.json(response);
+		} } }
+	});
+}
+function sortKey(session) {
+	return session.updatedAt ?? session.startedAt ?? "";
+}
+//#endregion
+export { agentDispatch, agentSessions, claudeCode, dispatchPrompt, hermes };

package/dist/plugins/agent.d.ts

@@ -0,0 +1,37 @@
+import { r as GrabPayload, t as ComponentHint } from "../payload-CLKDVZWl.js";
+import { c as HudPluginProps, s as HudPluginContext } from "../plugins-CQ_0w1ot.js";
+import "../index-BYsdS-7d.js";
+import { a as DispatchTargetInfo, i as DispatchReceipt, n as AgentSessionStatus, o as SessionsResponse, r as DispatchBody, t as AgentSession } from "../types-DADBRiGk.js";
+//#region src/plugins/agent/index.d.ts
+export interface AgentDispatchOptions {
+  /**
+   * The app's component manifest. A grab is matched against it by route and
+   * label and the matches travel with the dispatch as extra source hints.
+   */
+  componentHints?: readonly ComponentHint[];
+  /** Open the Dispatch panel when a grab completes. Default true. */
+  openOnGrab?: boolean;
+}
+/**
+ * Dispatch panel: the last grab plus an instruction, sent to one of the
+ * server's providers (`hermes()`, `claudeCode()`). Mount the server half from
+ * `@hansenexus/hud/plugins/agent/server` in the catch-all route.
+ */
+export declare function agentDispatch({ componentHints, openOnGrab }?: AgentDispatchOptions): {
+  readonly id: "agent-dispatch";
+  readonly title: "Dispatch";
+  readonly panel: ({ ctx }: HudPluginProps) => import("react").JSX.Element;
+  readonly onGrab?: (_payload: GrabPayload, ctx: HudPluginContext) => void;
+};
+export interface AgentSessionsOptions {
+  /** Refresh interval while the panel is open and the tab visible. Default 10 s. */
+  intervalMs?: number;
+}
+/** Sessions panel: runs and sessions of every provider that lists them. */
+export declare function agentSessions({ intervalMs }?: AgentSessionsOptions): {
+  readonly id: "agent-sessions";
+  readonly title: "Sessions";
+  readonly panel: ({ ctx }: HudPluginProps) => import("react").JSX.Element;
+};
+//#endregion
+export type { AgentSession, AgentSessionStatus, DispatchBody, DispatchReceipt, DispatchTargetInfo, SessionsResponse };