@nghyane/arcane 0.1.0

package/src/exa/websets.ts

@@ -0,0 +1,247 @@
+/**
+ * Exa Websets Tools
+ *
+ * CRUD operations for websets, items, searches, enrichments, and monitoring.
+ */
+import { type TObject, type TProperties, Type } from "@sinclair/typebox";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { callWebsetsTool, findApiKey } from "./mcp-client";
+import type { ExaRenderDetails } from "./types";
+
+/** Helper to create a websets tool with proper execute signature */
+function createWebsetTool(
+	name: string,
+	label: string,
+	description: string,
+	parameters: TObject<TProperties>,
+	mcpToolName: string,
+): CustomTool<any, ExaRenderDetails> {
+	return {
+		name,
+		label,
+		description,
+		parameters,
+		async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+			try {
+				const apiKey = await findApiKey();
+				if (!apiKey) {
+					return {
+						content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+						details: { error: "EXA_API_KEY not found", toolName: name },
+					};
+				}
+				const result = await callWebsetsTool(apiKey, mcpToolName, params as Record<string, unknown>);
+				return {
+					content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+					details: { raw: result, toolName: name },
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text" as const, text: `Error: ${message}` }],
+					details: { error: message, toolName: name },
+				};
+			}
+		},
+	};
+}
+
+// CRUD Operations
+const websetCreateTool = createWebsetTool(
+	"webset_create",
+	"Create Webset",
+	"Create a new webset collection for organizing web content.",
+	Type.Object({
+		name: Type.String({ description: "Name of the webset" }),
+		description: Type.Optional(Type.String({ description: "Optional description" })),
+	}),
+	"create_webset",
+);
+
+const websetListTool = createWebsetTool(
+	"webset_list",
+	"List Websets",
+	"List all websets in your account.",
+	Type.Object({}),
+	"list_websets",
+);
+
+const websetGetTool = createWebsetTool(
+	"webset_get",
+	"Get Webset",
+	"Get details of a specific webset by ID.",
+	Type.Object({
+		id: Type.String({ description: "Webset ID" }),
+	}),
+	"get_webset",
+);
+
+const websetUpdateTool = createWebsetTool(
+	"webset_update",
+	"Update Webset",
+	"Update a webset's name or description.",
+	Type.Object({
+		id: Type.String({ description: "Webset ID" }),
+		name: Type.Optional(Type.String({ description: "New name" })),
+		description: Type.Optional(Type.String({ description: "New description" })),
+	}),
+	"update_webset",
+);
+
+const websetDeleteTool = createWebsetTool(
+	"webset_delete",
+	"Delete Webset",
+	"Delete a webset and all its contents.",
+	Type.Object({
+		id: Type.String({ description: "Webset ID" }),
+	}),
+	"delete_webset",
+);
+
+// Item Management
+const websetItemsListTool = createWebsetTool(
+	"webset_items_list",
+	"List Webset Items",
+	"List items in a webset with optional pagination.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		limit: Type.Optional(Type.Number({ description: "Number of items to return" })),
+		offset: Type.Optional(Type.Number({ description: "Pagination offset" })),
+	}),
+	"list_webset_items",
+);
+
+const websetItemGetTool = createWebsetTool(
+	"webset_item_get",
+	"Get Webset Item",
+	"Get a specific item from a webset.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		item_id: Type.String({ description: "Item ID" }),
+	}),
+	"get_item",
+);
+
+// Search Operations
+const websetSearchCreateTool = createWebsetTool(
+	"webset_search_create",
+	"Create Webset Search",
+	"Create a new search within a webset.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		query: Type.String({ description: "Search query" }),
+	}),
+	"create_search",
+);
+
+const websetSearchGetTool = createWebsetTool(
+	"webset_search_get",
+	"Get Webset Search",
+	"Get the status and results of a webset search.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		search_id: Type.String({ description: "Search ID" }),
+	}),
+	"get_search",
+);
+
+const websetSearchCancelTool = createWebsetTool(
+	"webset_search_cancel",
+	"Cancel Webset Search",
+	"Cancel a running webset search.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		search_id: Type.String({ description: "Search ID" }),
+	}),
+	"cancel_search",
+);
+
+// Enrichment Operations
+const websetEnrichmentCreateTool = createWebsetTool(
+	"webset_enrichment_create",
+	"Create Enrichment",
+	"Create a new enrichment task for a webset.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		name: Type.String({ description: "Enrichment name" }),
+		prompt: Type.String({ description: "Enrichment prompt" }),
+	}),
+	"create_enrichment",
+);
+
+const websetEnrichmentGetTool = createWebsetTool(
+	"webset_enrichment_get",
+	"Get Enrichment",
+	"Get the status and results of an enrichment task.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		enrichment_id: Type.String({ description: "Enrichment ID" }),
+	}),
+	"get_enrichment",
+);
+
+const websetEnrichmentUpdateTool = createWebsetTool(
+	"webset_enrichment_update",
+	"Update Enrichment",
+	"Update an enrichment's name or prompt.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		enrichment_id: Type.String({ description: "Enrichment ID" }),
+		name: Type.Optional(Type.String({ description: "New name" })),
+		prompt: Type.Optional(Type.String({ description: "New prompt" })),
+	}),
+	"update_enrichment",
+);
+
+const websetEnrichmentDeleteTool = createWebsetTool(
+	"webset_enrichment_delete",
+	"Delete Enrichment",
+	"Delete an enrichment task.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		enrichment_id: Type.String({ description: "Enrichment ID" }),
+	}),
+	"delete_enrichment",
+);
+
+const websetEnrichmentCancelTool = createWebsetTool(
+	"webset_enrichment_cancel",
+	"Cancel Enrichment",
+	"Cancel a running enrichment task.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		enrichment_id: Type.String({ description: "Enrichment ID" }),
+	}),
+	"cancel_enrichment",
+);
+
+// Monitoring
+const websetMonitorCreateTool = createWebsetTool(
+	"webset_monitor_create",
+	"Create Monitor",
+	"Create a monitoring task for a webset with optional webhook notifications.",
+	Type.Object({
+		webset_id: Type.String({ description: "Webset ID" }),
+		webhook_url: Type.Optional(Type.String({ description: "Webhook URL for notifications" })),
+	}),
+	"create_monitor",
+);
+
+export const websetsTools: CustomTool<any, ExaRenderDetails>[] = [
+	websetCreateTool,
+	websetListTool,
+	websetGetTool,
+	websetUpdateTool,
+	websetDeleteTool,
+	websetItemsListTool,
+	websetItemGetTool,
+	websetSearchCreateTool,
+	websetSearchGetTool,
+	websetSearchCancelTool,
+	websetEnrichmentCreateTool,
+	websetEnrichmentGetTool,
+	websetEnrichmentUpdateTool,
+	websetEnrichmentDeleteTool,
+	websetEnrichmentCancelTool,
+	websetMonitorCreateTool,
+];

package/src/exec/bash-executor.ts

@@ -0,0 +1,184 @@
+/**
+ * Bash command execution with streaming support and cancellation.
+ *
+ * Uses brush-core via native bindings for shell execution.
+ */
+import { Shell } from "@nghyane/arcane-natives";
+import { Settings } from "../config/settings";
+import { OutputSink } from "../session/streaming-output";
+import { getOrCreateSnapshot } from "../utils/shell-snapshot";
+
+export interface BashExecutorOptions {
+	cwd?: string;
+	timeout?: number;
+	onChunk?: (chunk: string) => void;
+	signal?: AbortSignal;
+	/** Session key suffix to isolate shell sessions per agent */
+	sessionKey?: string;
+	/** Additional environment variables to inject */
+	env?: Record<string, string>;
+	/** Artifact path/id for full output storage */
+	artifactPath?: string;
+	artifactId?: string;
+}
+
+export interface BashResult {
+	output: string;
+	exitCode: number | undefined;
+	cancelled: boolean;
+	truncated: boolean;
+	totalLines: number;
+	totalBytes: number;
+	outputLines: number;
+	outputBytes: number;
+	artifactId?: string;
+}
+
+const HARD_TIMEOUT_GRACE_MS = 5_000;
+
+const shellSessions = new Map<string, Shell>();
+
+export async function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult> {
+	const settings = await Settings.init();
+	const { shell, env: shellEnv, prefix } = settings.getShellConfig();
+	const snapshotPath = shell.includes("bash") ? await getOrCreateSnapshot(shell, shellEnv) : null;
+
+	// Apply command prefix if configured
+	const prefixedCommand = prefix ? `${prefix} ${command}` : command;
+	const finalCommand = prefixedCommand;
+
+	// Create output sink for truncation and artifact handling
+	const sink = new OutputSink({
+		onChunk: options?.onChunk,
+		artifactPath: options?.artifactPath,
+		artifactId: options?.artifactId,
+	});
+
+	let pendingChunks = Promise.resolve();
+	const enqueueChunk = (chunk: string) => {
+		pendingChunks = pendingChunks.then(() => sink.push(chunk)).catch(() => {});
+	};
+
+	if (options?.signal?.aborted) {
+		return {
+			exitCode: undefined,
+			cancelled: true,
+			...(await sink.dump("Command cancelled")),
+		};
+	}
+
+	const sessionKey = buildSessionKey(shell, prefix, snapshotPath, shellEnv, options?.sessionKey);
+	let shellSession = shellSessions.get(sessionKey);
+	if (!shellSession) {
+		shellSession = new Shell({ sessionEnv: shellEnv, snapshotPath: snapshotPath ?? undefined });
+		shellSessions.set(sessionKey, shellSession);
+	}
+	const signal = options?.signal;
+	const abortHandler = () => {
+		shellSession.abort(signal?.reason instanceof Error ? signal.reason.message : undefined);
+	};
+	if (signal) {
+		signal.addEventListener("abort", abortHandler, { once: true });
+	}
+
+	let hardTimeoutTimer: NodeJS.Timeout | undefined;
+	const hardTimeoutDeferred = Promise.withResolvers<"hard-timeout">();
+	const baseTimeoutMs = Math.max(1_000, options?.timeout ?? 300_000);
+	const hardTimeoutMs = baseTimeoutMs + HARD_TIMEOUT_GRACE_MS;
+	hardTimeoutTimer = setTimeout(() => {
+		shellSession.abort(`Hard timeout after ${Math.round(hardTimeoutMs / 1000)}s`);
+		hardTimeoutDeferred.resolve("hard-timeout");
+	}, hardTimeoutMs);
+
+	let resetSession = false;
+
+	try {
+		const runPromise = shellSession.run(
+			{
+				command: finalCommand,
+				cwd: options?.cwd,
+				env: options?.env,
+				timeoutMs: options?.timeout,
+				signal,
+			},
+			(err, chunk) => {
+				if (!err) {
+					enqueueChunk(chunk);
+				}
+			},
+		);
+
+		const winner = await Promise.race([
+			runPromise.then(result => ({ kind: "result" as const, result })),
+			hardTimeoutDeferred.promise.then(() => ({ kind: "hard-timeout" as const })),
+		]);
+
+		await pendingChunks;
+
+		if (winner.kind === "hard-timeout") {
+			resetSession = true;
+			return {
+				exitCode: undefined,
+				cancelled: true,
+				...(await sink.dump(`Command exceeded hard timeout after ${Math.round(hardTimeoutMs / 1000)} seconds`)),
+			};
+		}
+
+		// Handle timeout
+		if (winner.result.timedOut) {
+			const annotation = options?.timeout
+				? `Command timed out after ${Math.round(options.timeout / 1000)} seconds`
+				: "Command timed out";
+			resetSession = true;
+			return {
+				exitCode: undefined,
+				cancelled: true,
+				...(await sink.dump(annotation)),
+			};
+		}
+
+		// Handle cancellation
+		if (winner.result.cancelled) {
+			resetSession = true;
+			return {
+				exitCode: undefined,
+				cancelled: true,
+				...(await sink.dump("Command cancelled")),
+			};
+		}
+
+		// Normal completion
+		return {
+			exitCode: winner.result.exitCode,
+			cancelled: false,
+			...(await sink.dump()),
+		};
+	} catch (err) {
+		resetSession = true;
+		throw err;
+	} finally {
+		if (hardTimeoutTimer) {
+			clearTimeout(hardTimeoutTimer);
+		}
+		if (signal) {
+			signal.removeEventListener("abort", abortHandler);
+		}
+		await pendingChunks;
+		if (resetSession) {
+			shellSessions.delete(sessionKey);
+		}
+	}
+}
+
+function buildSessionKey(
+	shell: string,
+	prefix: string | undefined,
+	snapshotPath: string | null,
+	env: Record<string, string>,
+	agentSessionKey?: string,
+): string {
+	const entries = Object.entries(env);
+	entries.sort(([a], [b]) => a.localeCompare(b));
+	const envSerialized = entries.map(([key, value]) => `${key}=${value}`).join("\n");
+	return [agentSessionKey ?? "", shell, prefix ?? "", snapshotPath ?? "", envSerialized].join("\n");
+}

package/src/exec/exec.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared command execution utilities for hooks and custom tools.
+ */
+import { ptree } from "@nghyane/arcane-utils";
+
+/**
+ * Options for executing shell commands.
+ */
+export interface ExecOptions {
+	/** AbortSignal to cancel the command */
+	signal?: AbortSignal;
+	/** Timeout in milliseconds */
+	timeout?: number;
+	/** Working directory */
+	cwd?: string;
+}
+
+/**
+ * Result of executing a shell command.
+ */
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+	killed: boolean;
+}
+
+/**
+ * Execute a shell command and return stdout/stderr/code.
+ * Supports timeout and abort signal.
+ */
+export async function execCommand(
+	command: string,
+	args: string[],
+	cwd: string,
+	options?: ExecOptions,
+): Promise<ExecResult> {
+	const result = await ptree.exec([command, ...args], {
+		cwd,
+		signal: options?.signal,
+		timeout: options?.timeout,
+		allowNonZero: true,
+		allowAbort: true,
+		stderr: "full",
+	});
+
+	return {
+		stdout: result.stdout,
+		stderr: result.stderr,
+		code: result.exitCode ?? 0,
+		killed: Boolean(result.exitError?.aborted),
+	};
+}

package/src/export/custom-share.ts

@@ -0,0 +1,65 @@
+/**
+ * Custom share script loader.
+ *
+ * Allows users to define a custom share handler at ~/.arcane/agent/share.ts
+ * that will be used instead of the default GitHub Gist sharing.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@nghyane/arcane-utils/dirs";
+
+export interface CustomShareResult {
+	/** URL to display/open (optional - script may handle everything itself) */
+	url?: string;
+	/** Additional message to show the user */
+	message?: string;
+}
+
+export type CustomShareFn = (htmlPath: string) => Promise<CustomShareResult | string | undefined>;
+
+interface LoadedCustomShare {
+	path: string;
+	fn: CustomShareFn;
+}
+
+const SHARE_SCRIPT_CANDIDATES = ["share.ts", "share.js", "share.mjs"];
+
+/**
+ * Get the path to the custom share script if it exists.
+ */
+export function getCustomSharePath(): string | null {
+	const agentDir = getAgentDir();
+
+	for (const candidate of SHARE_SCRIPT_CANDIDATES) {
+		const scriptPath = path.join(agentDir, candidate);
+		if (fs.existsSync(scriptPath)) {
+			return scriptPath;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Load the custom share script if it exists.
+ */
+export async function loadCustomShare(): Promise<LoadedCustomShare | null> {
+	const scriptPath = getCustomSharePath();
+	if (!scriptPath) {
+		return null;
+	}
+
+	try {
+		const module = await import(scriptPath);
+		const fn = module.default;
+
+		if (typeof fn !== "function") {
+			throw new Error("share script must export a default function");
+		}
+
+		return { path: scriptPath, fn };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to load share script: ${message}`);
+	}
+}

package/src/export/html/index.ts

@@ -0,0 +1,162 @@
+import * as path from "node:path";
+import type { AgentState } from "@nghyane/arcane-agent";
+import { isEnoent } from "@nghyane/arcane-utils";
+import { APP_NAME } from "@nghyane/arcane-utils/dirs";
+import { getResolvedThemeColors, getThemeExportColors } from "../../modes/theme/theme";
+import { type SessionEntry, type SessionHeader, SessionManager } from "../../session/session-manager";
+// Pre-generated template (created by scripts/generate-template.ts at publish time)
+import { TEMPLATE } from "./template.generated";
+
+export interface ExportOptions {
+	outputPath?: string;
+	themeName?: string;
+}
+
+/** Parse a color string to RGB values. */
+function parseColor(color: string): { r: number; g: number; b: number } | undefined {
+	const hexMatch = color.match(/^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/);
+	if (hexMatch) {
+		return {
+			r: Number.parseInt(hexMatch[1], 16),
+			g: Number.parseInt(hexMatch[2], 16),
+			b: Number.parseInt(hexMatch[3], 16),
+		};
+	}
+	const rgbMatch = color.match(/^rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+	if (rgbMatch) {
+		return {
+			r: Number.parseInt(rgbMatch[1], 10),
+			g: Number.parseInt(rgbMatch[2], 10),
+			b: Number.parseInt(rgbMatch[3], 10),
+		};
+	}
+	return undefined;
+}
+
+/** Calculate relative luminance of a color (0-1, higher = lighter). */
+function getLuminance(r: number, g: number, b: number): number {
+	const toLinear = (c: number) => {
+		const s = c / 255;
+		return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+	};
+	return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** Adjust color brightness. */
+function adjustBrightness(color: string, factor: number): string {
+	const parsed = parseColor(color);
+	if (!parsed) return color;
+	const adjust = (c: number) => Math.min(255, Math.max(0, Math.round(c * factor)));
+	return `rgb(${adjust(parsed.r)}, ${adjust(parsed.g)}, ${adjust(parsed.b)})`;
+}
+
+/** Derive export background colors from a base color. */
+function deriveExportColors(baseColor: string): { pageBg: string; cardBg: string; infoBg: string } {
+	const parsed = parseColor(baseColor);
+	if (!parsed) {
+		return { pageBg: "rgb(24, 24, 30)", cardBg: "rgb(30, 30, 36)", infoBg: "rgb(60, 55, 40)" };
+	}
+
+	const luminance = getLuminance(parsed.r, parsed.g, parsed.b);
+	if (luminance > 0.5) {
+		return {
+			pageBg: adjustBrightness(baseColor, 0.96),
+			cardBg: baseColor,
+			infoBg: `rgb(${Math.min(255, parsed.r + 10)}, ${Math.min(255, parsed.g + 5)}, ${Math.max(0, parsed.b - 20)})`,
+		};
+	}
+	return {
+		pageBg: adjustBrightness(baseColor, 0.7),
+		cardBg: adjustBrightness(baseColor, 0.85),
+		infoBg: `rgb(${Math.min(255, parsed.r + 20)}, ${Math.min(255, parsed.g + 15)}, ${parsed.b})`,
+	};
+}
+
+/** Generate CSS custom properties for theme. */
+async function generateThemeVars(themeName?: string): Promise<string> {
+	const colors = await getResolvedThemeColors(themeName);
+	const lines: string[] = [];
+	for (const [key, value] of Object.entries(colors)) {
+		lines.push(`--${key}: ${value};`);
+	}
+
+	const themeExport = await getThemeExportColors(themeName);
+	const userMessageBg = colors.userMessageBg || "#343541";
+	const derived = deriveExportColors(userMessageBg);
+
+	lines.push(`--body-bg: ${themeExport.pageBg ?? derived.pageBg};`);
+	lines.push(`--container-bg: ${themeExport.cardBg ?? derived.cardBg};`);
+	lines.push(`--info-bg: ${themeExport.infoBg ?? derived.infoBg};`);
+
+	return lines.join(" ");
+}
+
+interface SessionData {
+	header: SessionHeader | null;
+	entries: SessionEntry[];
+	leafId: string | null;
+	systemPrompt?: string;
+	tools?: { name: string; description: string }[];
+}
+
+/** Generate HTML from bundled template with runtime substitutions. */
+async function generateHtml(sessionData: SessionData, themeName?: string): Promise<string> {
+	const themeVars = await generateThemeVars(themeName);
+	const sessionDataBase64 = Buffer.from(JSON.stringify(sessionData)).toBase64();
+
+	return TEMPLATE.replace("<theme-vars/>", `<style>:root { ${themeVars} }</style>`).replace(
+		"{{SESSION_DATA}}",
+		sessionDataBase64,
+	);
+}
+
+/** Export session to HTML using SessionManager and AgentState. */
+export async function exportSessionToHtml(
+	sm: SessionManager,
+	state?: AgentState,
+	options?: ExportOptions | string,
+): Promise<string> {
+	const opts: ExportOptions = typeof options === "string" ? { outputPath: options } : options || {};
+
+	const sessionFile = sm.getSessionFile();
+	if (!sessionFile) throw new Error("Cannot export in-memory session to HTML");
+
+	const sessionData: SessionData = {
+		header: sm.getHeader(),
+		entries: sm.getEntries(),
+		leafId: sm.getLeafId(),
+		systemPrompt: state?.systemPrompt,
+		tools: state?.tools?.map(t => ({ name: t.name, description: t.description })),
+	};
+
+	const html = await generateHtml(sessionData, opts.themeName);
+	const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(sessionFile, ".jsonl")}.html`;
+
+	await Bun.write(outputPath, html);
+	return outputPath;
+}
+
+/** Export session file to HTML (standalone). */
+export async function exportFromFile(inputPath: string, options?: ExportOptions | string): Promise<string> {
+	const opts: ExportOptions = typeof options === "string" ? { outputPath: options } : options || {};
+
+	let sm: SessionManager;
+	try {
+		sm = await SessionManager.open(inputPath);
+	} catch (err) {
+		if (isEnoent(err)) throw new Error(`File not found: ${inputPath}`);
+		throw err;
+	}
+
+	const sessionData: SessionData = {
+		header: sm.getHeader(),
+		entries: sm.getEntries(),
+		leafId: sm.getLeafId(),
+	};
+
+	const html = await generateHtml(sessionData, opts.themeName);
+	const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(inputPath, ".jsonl")}.html`;
+
+	await Bun.write(outputPath, html);
+	return outputPath;
+}