hyperclaw 4.0.2 → 5.0.1

package/dist/oauth-flow-CeaaGAz0.js

@@ -0,0 +1,150 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const path = require_chunk.__toESM(require("path"));
+const os = require_chunk.__toESM(require("os"));
+const crypto = require_chunk.__toESM(require("crypto"));
+const http = require_chunk.__toESM(require("http"));
+
+//#region src/services/oauth-flow.ts
+const HC_DIR = path.default.join(os.default.homedir(), ".hyperclaw");
+const REDIRECT_PORT = 38789;
+const REDIRECT_PATH = "/oauth/callback";
+const PROVIDERS = {
+	google: {
+		authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+		token_url: "https://oauth2.googleapis.com/token",
+		scopes: [
+			"openid",
+			"email",
+			"profile",
+			"https://www.googleapis.com/auth/aiplatform"
+		],
+		client_id: process.env.GOOGLE_OAUTH_CLIENT_ID || "",
+		client_secret: process.env.GOOGLE_OAUTH_CLIENT_SECRET
+	},
+	"google-gmail": {
+		authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+		token_url: "https://oauth2.googleapis.com/token",
+		scopes: [
+			"openid",
+			"email",
+			"profile",
+			"https://www.googleapis.com/auth/gmail.modify",
+			"https://mail.google.com/"
+		],
+		client_id: process.env.GOOGLE_OAUTH_CLIENT_ID || "",
+		client_secret: process.env.GOOGLE_OAUTH_CLIENT_SECRET
+	},
+	microsoft: {
+		authorize_url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+		token_url: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+		scopes: [
+			"openid",
+			"profile",
+			"offline_access",
+			"https://cognitiveservices.azure.com/.default"
+		],
+		client_id: process.env.AZURE_OAUTH_CLIENT_ID || process.env.MICROSOFT_OAUTH_CLIENT_ID || "",
+		client_secret: process.env.AZURE_OAUTH_CLIENT_SECRET || process.env.MICROSOFT_OAUTH_CLIENT_SECRET
+	}
+};
+async function runOAuthFlow(providerId, opts) {
+	const cfg = PROVIDERS[providerId];
+	if (!cfg) throw new Error(`OAuth provider "${providerId}" not configured. Supported: google, google-gmail (Gmail Pub/Sub), microsoft. Anthropic/OpenAI: use "hyperclaw auth add" (API keys) or "hyperclaw auth setup-token anthropic" for Claude Pro/Max.`);
+	const clientId = opts?.clientId || cfg.client_id || process.env.OAUTH_CLIENT_ID;
+	const clientSecret = opts?.clientSecret || cfg.client_secret || process.env.OAUTH_CLIENT_SECRET;
+	const scopes = opts?.scopes || cfg.scopes;
+	if (!clientId) {
+		const hint = providerId === "google" ? "Set GOOGLE_OAUTH_CLIENT_ID or OAUTH_CLIENT_ID. Create at: https://console.cloud.google.com/apis/credentials" : providerId === "microsoft" ? "Set AZURE_OAUTH_CLIENT_ID. Create at: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade" : "Set OAUTH_CLIENT_ID or pass --client-id";
+		throw new Error(`OAuth client_id required. ${hint}`);
+	}
+	const codeVerifier = crypto.default.randomBytes(32).toString("base64url");
+	const codeChallenge = crypto.default.createHash("sha256").update(codeVerifier).digest("base64url");
+	const authParams = new URLSearchParams({
+		client_id: clientId,
+		redirect_uri: `http://127.0.0.1:${REDIRECT_PORT}${REDIRECT_PATH}`,
+		response_type: "code",
+		scope: scopes.join(" "),
+		code_challenge: codeChallenge,
+		code_challenge_method: "S256",
+		access_type: "offline",
+		prompt: "consent"
+	});
+	const authUrl = `${cfg.authorize_url}?${authParams}`;
+	return new Promise((resolve, reject) => {
+		const server = http.default.createServer(async (req, res) => {
+			const url = new URL(req.url || "/", `http://127.0.0.1`);
+			if (url.pathname !== REDIRECT_PATH) {
+				res.writeHead(404);
+				res.end("Not found");
+				return;
+			}
+			const code = url.searchParams.get("code");
+			const error = url.searchParams.get("error");
+			res.setHeader("Content-Type", "text/html; charset=utf-8");
+			if (error) {
+				res.writeHead(400);
+				res.end(`<h1>OAuth error</h1><p>${error}</p><p>You can close this tab.</p>`);
+				server.close();
+				reject(new Error(`OAuth error: ${error}`));
+				return;
+			}
+			if (!code) {
+				res.writeHead(400);
+				res.end("<h1>No code received</h1><p>You can close this tab.</p>");
+				server.close();
+				reject(new Error("No authorization code received"));
+				return;
+			}
+			const body = new URLSearchParams({
+				grant_type: "authorization_code",
+				code,
+				redirect_uri: `http://127.0.0.1:${REDIRECT_PORT}${REDIRECT_PATH}`,
+				code_verifier: codeVerifier
+			});
+			if (clientSecret) body.set("client_secret", clientSecret);
+			body.set("client_id", clientId);
+			try {
+				const tokenRes = await fetch(cfg.token_url, {
+					method: "POST",
+					headers: { "Content-Type": "application/x-www-form-urlencoded" },
+					body: body.toString()
+				});
+				const tokenData = await tokenRes.json();
+				if (tokenData.error) {
+					res.writeHead(400);
+					res.end(`<h1>Token error</h1><p>${tokenData.error}</p><p>You can close this tab.</p>`);
+					server.close();
+					reject(new Error(tokenData.error_description || tokenData.error));
+					return;
+				}
+				res.writeHead(200);
+				res.end("<h1>Success!</h1><p>HyperClaw has received your tokens. You can close this tab and return to the terminal.</p>");
+				server.close();
+				resolve({
+					access_token: tokenData.access_token,
+					refresh_token: tokenData.refresh_token,
+					expires_in: tokenData.expires_in
+				});
+			} catch (e) {
+				res.writeHead(500);
+				res.end(`<h1>Error</h1><p>${e.message}</p><p>You can close this tab.</p>`);
+				server.close();
+				reject(e);
+			}
+		});
+		server.listen(REDIRECT_PORT, "127.0.0.1", () => {
+			try {
+				const { exec } = require("child_process");
+				const opener = process.platform === "win32" ? `start "" "${authUrl}"` : (process.platform === "darwin" ? "open" : "xdg-open") + ` "${authUrl}"`;
+				exec(opener);
+			} catch {}
+		});
+		server.on("error", (err) => {
+			server.close();
+			reject(err);
+		});
+	});
+}
+
+//#endregion
+exports.runOAuthFlow = runOAuthFlow;

package/dist/oauth-flow-DQPvMHRH.js

@@ -0,0 +1,150 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const path = require_chunk.__toESM(require("path"));
+const os = require_chunk.__toESM(require("os"));
+const crypto = require_chunk.__toESM(require("crypto"));
+const http = require_chunk.__toESM(require("http"));
+
+//#region src/services/oauth-flow.ts
+const HC_DIR = path.default.join(os.default.homedir(), ".hyperclaw");
+const REDIRECT_PORT = 38789;
+const REDIRECT_PATH = "/oauth/callback";
+const PROVIDERS = {
+	google: {
+		authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+		token_url: "https://oauth2.googleapis.com/token",
+		scopes: [
+			"openid",
+			"email",
+			"profile",
+			"https://www.googleapis.com/auth/aiplatform"
+		],
+		client_id: process.env.GOOGLE_OAUTH_CLIENT_ID || "",
+		client_secret: process.env.GOOGLE_OAUTH_CLIENT_SECRET
+	},
+	"google-gmail": {
+		authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+		token_url: "https://oauth2.googleapis.com/token",
+		scopes: [
+			"openid",
+			"email",
+			"profile",
+			"https://www.googleapis.com/auth/gmail.modify",
+			"https://mail.google.com/"
+		],
+		client_id: process.env.GOOGLE_OAUTH_CLIENT_ID || "",
+		client_secret: process.env.GOOGLE_OAUTH_CLIENT_SECRET
+	},
+	microsoft: {
+		authorize_url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+		token_url: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+		scopes: [
+			"openid",
+			"profile",
+			"offline_access",
+			"https://cognitiveservices.azure.com/.default"
+		],
+		client_id: process.env.AZURE_OAUTH_CLIENT_ID || process.env.MICROSOFT_OAUTH_CLIENT_ID || "",
+		client_secret: process.env.AZURE_OAUTH_CLIENT_SECRET || process.env.MICROSOFT_OAUTH_CLIENT_SECRET
+	}
+};
+async function runOAuthFlow(providerId, opts) {
+	const cfg = PROVIDERS[providerId];
+	if (!cfg) throw new Error(`OAuth provider "${providerId}" not configured. Supported: google, google-gmail (Gmail Pub/Sub), microsoft. Anthropic/OpenAI: use "hyperclaw auth add" (API keys) or "hyperclaw auth setup-token anthropic" for Claude Pro/Max.`);
+	const clientId = opts?.clientId || cfg.client_id || process.env.OAUTH_CLIENT_ID;
+	const clientSecret = opts?.clientSecret || cfg.client_secret || process.env.OAUTH_CLIENT_SECRET;
+	const scopes = opts?.scopes || cfg.scopes;
+	if (!clientId) {
+		const hint = providerId === "google" ? "Set GOOGLE_OAUTH_CLIENT_ID or OAUTH_CLIENT_ID. Create at: https://console.cloud.google.com/apis/credentials" : providerId === "microsoft" ? "Set AZURE_OAUTH_CLIENT_ID. Create at: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade" : "Set OAUTH_CLIENT_ID or pass --client-id";
+		throw new Error(`OAuth client_id required. ${hint}`);
+	}
+	const codeVerifier = crypto.default.randomBytes(32).toString("base64url");
+	const codeChallenge = crypto.default.createHash("sha256").update(codeVerifier).digest("base64url");
+	const authParams = new URLSearchParams({
+		client_id: clientId,
+		redirect_uri: `http://127.0.0.1:${REDIRECT_PORT}${REDIRECT_PATH}`,
+		response_type: "code",
+		scope: scopes.join(" "),
+		code_challenge: codeChallenge,
+		code_challenge_method: "S256",
+		access_type: "offline",
+		prompt: "consent"
+	});
+	const authUrl = `${cfg.authorize_url}?${authParams}`;
+	return new Promise((resolve, reject) => {
+		const server = http.default.createServer(async (req, res) => {
+			const url = new URL(req.url || "/", `http://127.0.0.1`);
+			if (url.pathname !== REDIRECT_PATH) {
+				res.writeHead(404);
+				res.end("Not found");
+				return;
+			}
+			const code = url.searchParams.get("code");
+			const error = url.searchParams.get("error");
+			res.setHeader("Content-Type", "text/html; charset=utf-8");
+			if (error) {
+				res.writeHead(400);
+				res.end(`<h1>OAuth error</h1><p>${error}</p><p>You can close this tab.</p>`);
+				server.close();
+				reject(new Error(`OAuth error: ${error}`));
+				return;
+			}
+			if (!code) {
+				res.writeHead(400);
+				res.end("<h1>No code received</h1><p>You can close this tab.</p>");
+				server.close();
+				reject(new Error("No authorization code received"));
+				return;
+			}
+			const body = new URLSearchParams({
+				grant_type: "authorization_code",
+				code,
+				redirect_uri: `http://127.0.0.1:${REDIRECT_PORT}${REDIRECT_PATH}`,
+				code_verifier: codeVerifier
+			});
+			if (clientSecret) body.set("client_secret", clientSecret);
+			body.set("client_id", clientId);
+			try {
+				const tokenRes = await fetch(cfg.token_url, {
+					method: "POST",
+					headers: { "Content-Type": "application/x-www-form-urlencoded" },
+					body: body.toString()
+				});
+				const tokenData = await tokenRes.json();
+				if (tokenData.error) {
+					res.writeHead(400);
+					res.end(`<h1>Token error</h1><p>${tokenData.error}</p><p>You can close this tab.</p>`);
+					server.close();
+					reject(new Error(tokenData.error_description || tokenData.error));
+					return;
+				}
+				res.writeHead(200);
+				res.end("<h1>Success!</h1><p>HyperClaw has received your tokens. You can close this tab and return to the terminal.</p>");
+				server.close();
+				resolve({
+					access_token: tokenData.access_token,
+					refresh_token: tokenData.refresh_token,
+					expires_in: tokenData.expires_in
+				});
+			} catch (e) {
+				res.writeHead(500);
+				res.end(`<h1>Error</h1><p>${e.message}</p><p>You can close this tab.</p>`);
+				server.close();
+				reject(e);
+			}
+		});
+		server.listen(REDIRECT_PORT, "127.0.0.1", () => {
+			try {
+				const { exec } = require("child_process");
+				const opener = process.platform === "win32" ? `start "" "${authUrl}"` : (process.platform === "darwin" ? "open" : "xdg-open") + ` "${authUrl}"`;
+				exec(opener);
+			} catch {}
+		});
+		server.on("error", (err) => {
+			server.close();
+			reject(err);
+		});
+	});
+}
+
+//#endregion
+exports.runOAuthFlow = runOAuthFlow;

package/dist/oauth-provider-B4dzn56l.js

@@ -0,0 +1,110 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const fs_extra = require_chunk.__toESM(require("fs-extra"));
+const path = require_chunk.__toESM(require("path"));
+const os = require_chunk.__toESM(require("os"));
+const https = require_chunk.__toESM(require("https"));
+
+//#region src/services/oauth-provider.ts
+function defaultTokenPath(providerId) {
+	return path.default.join(HC_DIR, `oauth-${providerId}.json`);
+}
+async function getProviderCredentialAsync(cfg) {
+	if (!cfg?.provider) return "";
+	const authType = cfg.provider.authType ?? "api_key";
+	if (authType === "api_key") {
+		const key = cfg.provider.apiKey;
+		if (key) return key;
+		const pid = cfg.provider.providerId || "openrouter";
+		switch (pid) {
+			case "openrouter": return process.env.OPENROUTER_API_KEY || "";
+			case "anthropic": return process.env.ANTHROPIC_API_KEY || "";
+			case "openai": return process.env.OPENAI_API_KEY || "";
+			case "xai": return process.env.XAI_API_KEY || "";
+			case "google": return process.env.GOOGLE_AI_API_KEY || "";
+			default: return process.env.OPENROUTER_API_KEY || process.env.ANTHROPIC_API_KEY || "";
+		}
+	}
+	const tokenPath = cfg.provider.oauthTokenPath || defaultTokenPath(cfg.provider.providerId || "default");
+	if (!await fs_extra.default.pathExists(tokenPath)) return "";
+	let data;
+	try {
+		data = await fs_extra.default.readJson(tokenPath);
+	} catch {
+		return "";
+	}
+	if (!data.access_token) return "";
+	const now = Math.floor(Date.now() / 1e3);
+	const expiresAt = data.expires_at ?? 0;
+	if (expiresAt > 0 && now < expiresAt - 60) return data.access_token;
+	if (!data.refresh_token) return data.access_token;
+	const tokenUrl = data.token_url || DEFAULT_REFRESH_URLS[cfg.provider.providerId || ""] || "";
+	if (!tokenUrl) return data.access_token;
+	const refreshed = await refreshAccessToken({
+		token_url: tokenUrl,
+		refresh_token: data.refresh_token,
+		client_id: data.client_id || process.env.OAUTH_CLIENT_ID,
+		client_secret: data.client_secret || process.env.OAUTH_CLIENT_SECRET
+	});
+	if (refreshed.access_token) {
+		data.access_token = refreshed.access_token;
+		if (refreshed.expires_in) data.expires_at = now + refreshed.expires_in;
+		await fs_extra.default.writeJson(tokenPath, data, { spaces: 2 });
+		return data.access_token;
+	}
+	return data.access_token;
+}
+async function refreshAccessToken(opts) {
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		refresh_token: opts.refresh_token
+	});
+	if (opts.client_id) body.set("client_id", opts.client_id);
+	if (opts.client_secret) body.set("client_secret", opts.client_secret);
+	const u = new URL(opts.token_url);
+	return new Promise((resolve) => {
+		const req = https.default.request({
+			hostname: u.hostname,
+			port: 443,
+			path: u.pathname + u.search,
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" }
+		}, (res) => {
+			let data = "";
+			res.on("data", (c) => data += c);
+			res.on("end", () => {
+				try {
+					const j = JSON.parse(data);
+					resolve({
+						access_token: j.access_token,
+						expires_in: j.expires_in
+					});
+				} catch {
+					resolve({});
+				}
+			});
+		});
+		req.on("error", () => resolve({}));
+		req.write(body.toString());
+		req.end();
+	});
+}
+/** Write token file (e.g. after OAuth callback or manual paste). */
+async function writeOAuthToken(providerId, token, customPath) {
+	const p = customPath || defaultTokenPath(providerId);
+	await fs_extra.default.ensureDir(path.default.dirname(p));
+	await fs_extra.default.writeJson(p, token, { spaces: 2 });
+}
+var HC_DIR, DEFAULT_REFRESH_URLS;
+var init_oauth_provider = require_chunk.__esm({ "src/services/oauth-provider.ts"() {
+	HC_DIR = path.default.join(os.default.homedir(), ".hyperclaw");
+	DEFAULT_REFRESH_URLS = {
+		google: "https://oauth2.googleapis.com/token",
+		openai: "https://api.openai.com/v1/auth/refresh",
+		anthropic: ""
+	};
+} });
+
+//#endregion
+init_oauth_provider();
+exports.getProviderCredentialAsync = getProviderCredentialAsync;
+exports.writeOAuthToken = writeOAuthToken;

package/dist/oauth-provider-Uo4Nib_c.js

@@ -0,0 +1,110 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const fs_extra = require_chunk.__toESM(require("fs-extra"));
+const path = require_chunk.__toESM(require("path"));
+const os = require_chunk.__toESM(require("os"));
+const https = require_chunk.__toESM(require("https"));
+
+//#region src/services/oauth-provider.ts
+function defaultTokenPath(providerId) {
+	return path.default.join(HC_DIR, `oauth-${providerId}.json`);
+}
+async function getProviderCredentialAsync(cfg) {
+	if (!cfg?.provider) return "";
+	const authType = cfg.provider.authType ?? "api_key";
+	if (authType === "api_key") {
+		const key = cfg.provider.apiKey;
+		if (key) return key;
+		const pid = cfg.provider.providerId || "openrouter";
+		switch (pid) {
+			case "openrouter": return process.env.OPENROUTER_API_KEY || "";
+			case "anthropic": return process.env.ANTHROPIC_API_KEY || "";
+			case "openai": return process.env.OPENAI_API_KEY || "";
+			case "xai": return process.env.XAI_API_KEY || "";
+			case "google": return process.env.GOOGLE_AI_API_KEY || "";
+			default: return process.env.OPENROUTER_API_KEY || process.env.ANTHROPIC_API_KEY || "";
+		}
+	}
+	const tokenPath = cfg.provider.oauthTokenPath || defaultTokenPath(cfg.provider.providerId || "default");
+	if (!await fs_extra.default.pathExists(tokenPath)) return "";
+	let data;
+	try {
+		data = await fs_extra.default.readJson(tokenPath);
+	} catch {
+		return "";
+	}
+	if (!data.access_token) return "";
+	const now = Math.floor(Date.now() / 1e3);
+	const expiresAt = data.expires_at ?? 0;
+	if (expiresAt > 0 && now < expiresAt - 60) return data.access_token;
+	if (!data.refresh_token) return data.access_token;
+	const tokenUrl = data.token_url || DEFAULT_REFRESH_URLS[cfg.provider.providerId || ""] || "";
+	if (!tokenUrl) return data.access_token;
+	const refreshed = await refreshAccessToken({
+		token_url: tokenUrl,
+		refresh_token: data.refresh_token,
+		client_id: data.client_id || process.env.OAUTH_CLIENT_ID,
+		client_secret: data.client_secret || process.env.OAUTH_CLIENT_SECRET
+	});
+	if (refreshed.access_token) {
+		data.access_token = refreshed.access_token;
+		if (refreshed.expires_in) data.expires_at = now + refreshed.expires_in;
+		await fs_extra.default.writeJson(tokenPath, data, { spaces: 2 });
+		return data.access_token;
+	}
+	return data.access_token;
+}
+async function refreshAccessToken(opts) {
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		refresh_token: opts.refresh_token
+	});
+	if (opts.client_id) body.set("client_id", opts.client_id);
+	if (opts.client_secret) body.set("client_secret", opts.client_secret);
+	const u = new URL(opts.token_url);
+	return new Promise((resolve) => {
+		const req = https.default.request({
+			hostname: u.hostname,
+			port: 443,
+			path: u.pathname + u.search,
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" }
+		}, (res) => {
+			let data = "";
+			res.on("data", (c) => data += c);
+			res.on("end", () => {
+				try {
+					const j = JSON.parse(data);
+					resolve({
+						access_token: j.access_token,
+						expires_in: j.expires_in
+					});
+				} catch {
+					resolve({});
+				}
+			});
+		});
+		req.on("error", () => resolve({}));
+		req.write(body.toString());
+		req.end();
+	});
+}
+/** Write token file (e.g. after OAuth callback or manual paste). */
+async function writeOAuthToken(providerId, token, customPath) {
+	const p = customPath || defaultTokenPath(providerId);
+	await fs_extra.default.ensureDir(path.default.dirname(p));
+	await fs_extra.default.writeJson(p, token, { spaces: 2 });
+}
+var HC_DIR, DEFAULT_REFRESH_URLS;
+var init_oauth_provider = require_chunk.__esm({ "src/services/oauth-provider.ts"() {
+	HC_DIR = path.default.join(os.default.homedir(), ".hyperclaw");
+	DEFAULT_REFRESH_URLS = {
+		google: "https://oauth2.googleapis.com/token",
+		openai: "https://api.openai.com/v1/auth/refresh",
+		anthropic: ""
+	};
+} });
+
+//#endregion
+init_oauth_provider();
+exports.getProviderCredentialAsync = getProviderCredentialAsync;
+exports.writeOAuthToken = writeOAuthToken;

package/dist/observability-BV-Yx0V9.js

@@ -0,0 +1,89 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/observability.ts
+/** Rough cost per 1M tokens (Claude Sonnet ballpark). */
+const COST_PER_1M_INPUT = 3;
+const COST_PER_1M_OUTPUT = 15;
+function estimateCost(usage) {
+	if (!usage) return 0;
+	const inp = (usage.input || 0) + (usage.cacheRead || 0);
+	return inp / 1e6 * COST_PER_1M_INPUT + (usage.output || 0) / 1e6 * COST_PER_1M_OUTPUT;
+}
+function createRunTracer(sessionId, source) {
+	const startTime = (/* @__PURE__ */ new Date()).toISOString();
+	const toolCalls = [];
+	const pending = [];
+	const trace = {
+		sessionId,
+		source,
+		startTime,
+		toolCalls
+	};
+	return {
+		trace,
+		onToolCall(name, input) {
+			pending.push({
+				name,
+				input
+			});
+		},
+		onToolResult(name, result) {
+			const head = pending.shift();
+			toolCalls.push({
+				name: name || head?.name || "unknown",
+				input: head?.input ?? {},
+				result: result.slice(0, 500),
+				at: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		},
+		onRunEnd(usage, error) {
+			trace.endTime = (/* @__PURE__ */ new Date()).toISOString();
+			trace.usage = usage;
+			trace.costUsd = estimateCost(usage);
+			trace.error = error;
+		}
+	};
+}
+/** List trace files (for querying). */
+async function listTraces(baseDir, limit = 50) {
+	try {
+		const fs = await import("fs-extra");
+		const path = await import("path");
+		const dir = path.join(baseDir, "traces");
+		if (!await fs.pathExists(dir)) return [];
+		const files = (await fs.readdir(dir)).filter((f) => f.endsWith(".json")).map((f) => path.join(dir, f));
+		const stats = await Promise.all(files.map(async (fp) => ({
+			fp,
+			mtime: (await fs.stat(fp)).mtime.getTime()
+		})));
+		stats.sort((a, b) => b.mtime - a.mtime);
+		const out = [];
+		for (const { fp } of stats.slice(0, limit)) try {
+			out.push(await fs.readJson(fp));
+		} catch {}
+		return out;
+	} catch {
+		return [];
+	}
+}
+/** Write trace to file (e.g. ~/.hyperclaw/traces/). */
+async function writeTraceToFile(baseDir, trace) {
+	try {
+		const fs = await import("fs-extra");
+		const path = await import("path");
+		const dir = path.join(baseDir, "traces");
+		await fs.ensureDir(dir);
+		const name = `run-${trace.startTime.replace(/[:.]/g, "-")}.json`;
+		const fp = path.join(dir, name);
+		await fs.writeJson(fp, trace, { spaces: 0 });
+		return fp;
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+exports.createRunTracer = createRunTracer;
+exports.estimateCost = estimateCost;
+exports.listTraces = listTraces;
+exports.writeTraceToFile = writeTraceToFile;