@alashi/cli 0.9.0 → 0.10.0

package/dist/{store-Cxxnjq70.mjs → store-VoJe_U1Q.mjs}

@@ -2,8 +2,8 @@ import { APP_NAME_PATTERN, AppSdkError, ConfigError, JsonFileStore, SDK_VERSION,
 import semver from "semver";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, symlink, writeFile } from "node:fs/promises";
-import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { cp, lstat, mkdir, readFile, readdir, readlink, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { z } from "zod";
@@ -11,6 +11,208 @@ import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { Cron } from "croner";
 import { homedir } from "node:os";
+//#region src/usage.ts
+/** Days of history kept in usage.json; older days are dropped on write. */
+const USAGE_RETENTION_DAYS = 90;
+/** Cents-of-a-millicent precision — enough for per-turn costs, short enough to keep JSON tidy. */
+const COST_PRECISION = 6;
+const DAY_MS = 864e5;
+/** The UTC calendar day (`YYYY-MM-DD`) a timestamp falls in. */
+function utcDay(at = /* @__PURE__ */ new Date()) {
+	return at.toISOString().slice(0, 10);
+}
+function round(value) {
+	return Number(value.toFixed(COST_PRECISION));
+}
+/** Money for humans: sub-dollar spend needs the extra digits, larger sums don't. */
+function formatUsd(value) {
+	return `$${value.toFixed(value >= 1 ? 2 : 4)}`;
+}
+/**
+* Per-app, per-UTC-day AI spend, persisted as OS bookkeeping in the app
+* container (`apps/<name>/usage.json`, next to jobs.json and chat.json).
+*
+* Cost arrives from the `result` event's `costUsd`, which the SDK contract
+* marks optional: engines that do not report cost simply contribute nothing.
+* Writes are serialized per app so concurrent turns cannot lose an update,
+* and each app has its own queue so a slow write for one app never delays
+* another.
+*/
+var UsageRecorder = class {
+	store;
+	retentionDays;
+	/** Serializes usage.json read-modify-write per app. */
+	queues = /* @__PURE__ */ new Map();
+	constructor(store, retentionDays = 90) {
+		this.store = store;
+		this.retentionDays = retentionDays;
+	}
+	/**
+	* Adds one turn's cost to the app's total for the UTC day of `at`.
+	* A missing, non-finite, or negative `costUsd` is ignored (no turn counted,
+	* no file written) so a provider that omits cost cannot corrupt the totals.
+	*/
+	record(appName, costUsd, at = /* @__PURE__ */ new Date()) {
+		if (typeof costUsd !== "number" || !Number.isFinite(costUsd) || costUsd < 0) return Promise.resolve();
+		return this.enqueue(appName, async () => {
+			const state = await this.store.readUsageState(appName);
+			const date = utcDay(at);
+			const day = state.days.find((entry) => entry.date === date);
+			if (day) {
+				day.costUsd = round(day.costUsd + costUsd);
+				day.turns += 1;
+			} else state.days.push({
+				date,
+				costUsd: round(costUsd),
+				turns: 1
+			});
+			await this.store.writeUsageState(appName, this.prune(state, at));
+		});
+	}
+	/** The app's recorded days, oldest first, with expired days filtered out. */
+	async read(appName, at = /* @__PURE__ */ new Date()) {
+		return this.prune(await this.store.readUsageState(appName), at);
+	}
+	/** Today's spend plus the daily series, for the dashboard and the usage endpoint. */
+	async summary(appName, at = /* @__PURE__ */ new Date()) {
+		const { days } = await this.read(appName, at);
+		const date = utcDay(at);
+		const today = days.find((entry) => entry.date === date);
+		return {
+			date,
+			todayCostUsd: today?.costUsd ?? 0,
+			todayTurns: today?.turns ?? 0,
+			totalCostUsd: round(days.reduce((sum, entry) => sum + entry.costUsd, 0)),
+			retentionDays: this.retentionDays,
+			days
+		};
+	}
+	/** Drops days outside the retention window and normalizes ordering/values. */
+	prune(state, at) {
+		const cutoff = utcDay(/* @__PURE__ */ new Date(at.getTime() - (this.retentionDays - 1) * DAY_MS));
+		return { days: state.days.filter((entry) => typeof entry?.date === "string" && entry.date >= cutoff && Number.isFinite(entry.costUsd) && entry.costUsd >= 0).map((entry) => ({
+			date: entry.date,
+			costUsd: round(entry.costUsd),
+			turns: Number.isFinite(entry.turns) ? entry.turns : 0
+		})).sort((a, b) => a.date.localeCompare(b.date)) };
+	}
+	enqueue(appName, work) {
+		const next = (this.queues.get(appName) ?? Promise.resolve()).then(work);
+		const settled = next.catch(() => void 0);
+		this.queues.set(appName, settled);
+		settled.then(() => {
+			if (this.queues.get(appName) === settled) this.queues.delete(appName);
+		});
+		return next;
+	}
+};
+//#endregion
+//#region src/budget.ts
+/**
+* Stable discriminator on the thrown error. Apps see the host's error object
+* across a package boundary (and, once `AppContext` becomes RPC, across a
+* process boundary), so the reliable check is this code — not `instanceof`.
+*/
+const BUDGET_EXCEEDED_CODE = "budget_exceeded";
+/**
+* Refusal from the `createSession` budget gate.
+*
+* Extends the SDK's `AppSdkError` so it stays inside the taxonomy apps already
+* catch, and carries a `code` plus the numbers behind the decision so an app
+* can degrade gracefully (queue the work, skip the run, tell the user) instead
+* of treating a spend cap as a crash. The message is written to stand alone:
+* it is often the only text a human sees, rendered somewhere far from the host.
+*/
+var BudgetExceededError = class extends AppSdkError {
+	code = BUDGET_EXCEEDED_CODE;
+	appName;
+	/** UTC day the cap applies to. */
+	date;
+	/** The configured cap in USD. */
+	limitUsd;
+	/** Spend already recorded for `date`. */
+	spentUsd;
+	constructor(appName, params) {
+		super(`Daily AI spend cap reached: app "${appName}" has spent ${formatUsd(params.spentUsd)} of its ${formatUsd(params.limitUsd)} cap for ${params.date} (UTC). New sessions are refused until the cap resets at 00:00 UTC, or until it is raised in the app's alashi settings.`);
+		this.name = "BudgetExceededError";
+		this.appName = appName;
+		this.date = params.date;
+		this.limitUsd = params.limitUsd;
+		this.spentUsd = params.spentUsd;
+	}
+	/** Duck-typed check that survives duplicate copies of this module. */
+	static is(err) {
+		return err instanceof Error && err.code === "budget_exceeded";
+	}
+};
+/**
+* The cap the *host* has set for an app, or undefined when there is none.
+*
+* Read only from `GlobalConfig.budgets`, which is deliberately not part of the
+* config layers merged into `ctx.config`: an app must not be able to raise its
+* own ceiling through its manifest defaults or `apps/<name>/config.json`.
+*
+* A hand-edited cap that is not a finite number >= 0 is ignored rather than
+* treated as zero — a typo in config.json should not brick an app, and the
+* dashboard/settings write path validates before it ever gets stored.
+*/
+function appBudget(config, name) {
+	const dailyUsd = config.budgets?.[name]?.dailyUsd;
+	if (typeof dailyUsd !== "number" || !Number.isFinite(dailyUsd) || dailyUsd < 0) return void 0;
+	return dailyUsd;
+}
+/** Whether `spentUsd` has reached `dailyUsd`; the cap itself is inclusive. */
+function isOver(spentUsd, dailyUsd) {
+	return dailyUsd !== void 0 && spentUsd >= dailyUsd;
+}
+/** Combines an already-read usage summary with a cap; no I/O. */
+function budgetStatusFor(summary, dailyUsd) {
+	return {
+		date: summary.date,
+		spentUsd: summary.todayCostUsd,
+		...dailyUsd !== void 0 && {
+			dailyUsd,
+			remainingUsd: Math.max(0, Number((dailyUsd - summary.todayCostUsd).toFixed(6)))
+		},
+		overBudget: isOver(summary.todayCostUsd, dailyUsd)
+	};
+}
+/** Today's spend against the app's cap, for the gate, the dashboard, and settings. */
+async function budgetStatus(store, usage, name, at = /* @__PURE__ */ new Date()) {
+	const [config, summary] = await Promise.all([store.readGlobalConfig(), usage.summary(name, at)]);
+	return budgetStatusFor(summary, appBudget(config, name));
+}
+/**
+* Fail-closed gate: throws `BudgetExceededError` when the app has already
+* spent its daily cap. Evaluated fresh on every call, so a cap edit or a
+* mid-day overspend takes effect without restarting the app.
+*/
+async function assertWithinBudget(store, usage, name, at = /* @__PURE__ */ new Date()) {
+	const status = await budgetStatus(store, usage, name, at);
+	if (!status.overBudget || status.dailyUsd === void 0) return;
+	throw new BudgetExceededError(name, {
+		date: status.date,
+		limitUsd: status.dailyUsd,
+		spentUsd: status.spentUsd
+	});
+}
+/**
+* Sets (or, with `undefined`, clears) an app's daily cap in the host config.
+* Rejects anything that is not a finite, non-negative dollar amount; `0` is a
+* legitimate value meaning "no AI spend at all for this app".
+*/
+async function setAppBudget(store, name, dailyUsd) {
+	if (dailyUsd !== void 0 && (!Number.isFinite(dailyUsd) || dailyUsd < 0)) throw new AppSdkError(`Invalid daily spend cap: ${JSON.stringify(dailyUsd)}`);
+	const config = await store.readGlobalConfig();
+	const budgets = { ...config.budgets };
+	if (dailyUsd === void 0) delete budgets[name];
+	else budgets[name] = { dailyUsd };
+	const next = { ...config };
+	if (Object.keys(budgets).length === 0) delete next.budgets;
+	else next.budgets = budgets;
+	await store.writeGlobalConfig(next);
+}
+//#endregion
 //#region src/compat.ts
 /**
 * Enforces the manifest's declared `sdkVersion` range against the SDK
@@ -60,6 +262,11 @@ async function loadApp(repoDir) {
 	}
 	const definition = mod.default;
 	if (typeof definition !== "object" || definition === null || !("manifest" in definition)) throw new AppSdkError("App entry must default-export an app definition (use defineApp() from @alashi/apps-sdk)");
+	const raw = definition.manifest;
+	if (typeof raw.sdkVersion === "string") checkSdkCompatibility({
+		name: typeof raw.name === "string" ? raw.name : entry,
+		sdkVersion: raw.sdkVersion
+	});
 	return {
 		definition,
 		manifest: parseManifest(definition.manifest),
@@ -68,7 +275,7 @@ async function loadApp(repoDir) {
 }
 //#endregion
 //#region src/sources.ts
-const execFileAsync$1 = promisify(execFile);
+const execFileAsync$2 = promisify(execFile);
 function parseSourceArg(arg) {
 	if (arg.startsWith(".") || isAbsolute(arg)) return {
 		type: "local",
@@ -89,7 +296,7 @@ function parseSourceArg(arg) {
 }
 async function git(args, cwd) {
 	try {
-		const { stdout } = await execFileAsync$1("git", args, cwd ? { cwd } : {});
+		const { stdout } = await execFileAsync$2("git", args, cwd ? { cwd } : {});
 		return stdout.trim();
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -220,7 +427,7 @@ async function resolveApp(store, appName) {
 }
 //#endregion
 //#region src/installer.ts
-const execFileAsync = promisify(execFile);
+const execFileAsync$1 = promisify(execFile);
 async function hasDependencies(dir) {
 	try {
 		const pkg = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
@@ -233,7 +440,7 @@ async function hasDependencies(dir) {
 async function installDependencies(dir) {
 	if (!await hasDependencies(dir)) return;
 	try {
-		await execFileAsync("npm", [
+		await execFileAsync$1("npm", [
 			"install",
 			"--ignore-scripts",
 			"--omit=dev",
@@ -275,7 +482,6 @@ async function installApp(store, source, options = {}) {
 	}
 	try {
 		const { manifest } = await loadApp(inspectDir);
-		checkSdkCompatibility(manifest);
 		if (expectName && manifest.name !== expectName) throw new AppSdkError(`App manifest name "${manifest.name}" does not match requested "${expectName}"`);
 		if (await store.readAppRecord(manifest.name)) throw new AppSdkError(`App "${manifest.name}" is already installed (use: alashi update ${manifest.name})`);
 		const repoDir = store.appRepoDir(manifest.name);
@@ -310,7 +516,6 @@ async function updateApp(store, name) {
 	await updateSource(record.source, repoDir);
 	await installDependencies(repoDir);
 	const { manifest } = await loadApp(repoDir);
-	checkSdkCompatibility(manifest);
 	if (manifest.name !== name) throw new AppSdkError(`App renamed itself to "${manifest.name}"; refusing update`);
 	const updated = {
 		...record,
@@ -337,6 +542,276 @@ async function removeApp(store, name, options = {}) {
 	await rm(store.appRecordPath(name), { force: true });
 }
 //#endregion
+//#region src/portability.ts
+const execFileAsync = promisify(execFile);
+/**
+* Container portability. An app is only half-portable on its own: the
+* container holds sessionId pointers, but the conversation transcripts live
+* with the engine (keyed by the app's data dir as cwd). An export therefore
+* snapshots the container *plus* the transcripts, engine-neutrally, and the
+* import re-keys them to this machine's data dir.
+*
+* Archive layout (tar.gz):
+*   alashi-export.json          { formatVersion, exportedAt, app, transcripts }
+*   container/                  the contents of $ALASHI_HOME/apps/<name>/
+*   transcripts/<sessionId>.jsonl
+*/
+const EXPORT_FORMAT_VERSION = 1;
+const METADATA_FILE = "alashi-export.json";
+const CONTAINER_DIR = "container";
+const TRANSCRIPTS_DIR = "transcripts";
+const TRANSCRIPT_EXT = ".jsonl";
+/** Re-derivable from the source, and by far the biggest thing in a container. */
+const CONTAINER_EXCLUDES = [join("repo", "node_modules"), join("repo", ".git")];
+/** Session ids become file names, so they must not be able to escape the dir. */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Shelling out to tar matches how git and npm are already invoked. */
+async function tar(args) {
+	try {
+		const { stdout } = await execFileAsync("tar", args);
+		return stdout;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new AppSdkError(`tar ${args[0]} failed: ${message}`, { cause: err });
+	}
+}
+async function exists(path) {
+	try {
+		await lstat(path);
+		return true;
+	} catch (err) {
+		if (err.code === "ENOENT") return false;
+		throw err;
+	}
+}
+async function isDirectory(path) {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function containerFilter(appDir) {
+	return (src) => {
+		const rel = relative(appDir, src);
+		if (rel === "") return true;
+		return !CONTAINER_EXCLUDES.some((excluded) => rel === excluded || rel.startsWith(excluded + sep));
+	};
+}
+/**
+* Packs apps/<name>/ plus the transcripts of every conversation that ever had
+* a turn into a single self-contained tar.gz.
+*/
+async function exportApp(store, provider, name, options = {}) {
+	const record = await store.readAppRecord(name);
+	if (!record) throw new AppSdkError(`App "${name}" is not installed`);
+	const archivePath = resolve(process.cwd(), options.out ?? `${record.name}-${record.version}.tar.gz`);
+	if (await exists(archivePath)) throw new AppSdkError(`Refusing to overwrite existing file: ${archivePath}`);
+	const warnings = [];
+	const appDir = store.appDir(name);
+	const stage = join(store.stagingDir, randomUUID());
+	try {
+		await mkdir(stage, { recursive: true });
+		await cp(appDir, join(stage, CONTAINER_DIR), {
+			recursive: true,
+			dereference: true,
+			filter: containerFilter(appDir)
+		});
+		const { conversations } = await store.readChatState(name);
+		const sessionIds = [...new Set(conversations.map((conversation) => conversation.sessionId).filter((sessionId) => !!sessionId))];
+		let transcripts = [];
+		if (!provider.exportTranscripts) {
+			if (sessionIds.length > 0) warnings.push(`Provider "${provider.name}" cannot export transcripts; the archive holds the container only`);
+		} else if (sessionIds.length > 0) transcripts = await provider.exportTranscripts(sessionIds);
+		await mkdir(join(stage, TRANSCRIPTS_DIR), { recursive: true });
+		const written = [];
+		for (const transcript of transcripts) {
+			if (!SESSION_ID_PATTERN.test(transcript.sessionId)) {
+				warnings.push(`Skipped transcript with unusable session id ${JSON.stringify(transcript.sessionId)}`);
+				continue;
+			}
+			await writeFile(join(stage, TRANSCRIPTS_DIR, `${transcript.sessionId}${TRANSCRIPT_EXT}`), transcript.content, "utf8");
+			written.push(transcript.sessionId);
+		}
+		if (provider.exportTranscripts && written.length < sessionIds.length) warnings.push(`${sessionIds.length - written.length} of ${sessionIds.length} conversations had no transcript in "${provider.name}" storage`);
+		const metadata = {
+			formatVersion: 1,
+			exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			app: record,
+			transcripts: written
+		};
+		await writeFile(join(stage, METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+		await mkdir(dirname(archivePath), { recursive: true });
+		await tar([
+			"-czf",
+			archivePath,
+			"-C",
+			stage,
+			"."
+		]);
+		return {
+			archivePath,
+			record,
+			transcriptCount: written.length,
+			warnings
+		};
+	} finally {
+		await rm(stage, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** An archive is untrusted input: no absolute members, no ".." traversal. */
+async function assertSafeMembers(archive) {
+	const listing = await tar(["-tzf", archive]);
+	for (const line of listing.split("\n")) {
+		const member = line.trim();
+		if (member === "") continue;
+		const segments = member.split(/[\\/]/);
+		if (isAbsolute(member) || member.startsWith("/") || segments.includes("..")) throw new AppSdkError(`Refusing to import ${archive}: it contains an unsafe path ${JSON.stringify(member)}`);
+	}
+}
+/** Second belt: a symlink inside the archive must not point out of the stage. */
+async function assertNothingEscaped(stage) {
+	const root = resolve(stage);
+	const walk = async (dir) => {
+		for (const entry of await readdir(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isSymbolicLink()) {
+				const target = resolve(dir, await readlink(path));
+				const rel = relative(root, target);
+				if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) throw new AppSdkError(`Refusing to import: ${relative(root, path)} links outside the archive (${target})`);
+				continue;
+			}
+			if (entry.isDirectory()) await walk(path);
+		}
+	};
+	await walk(root);
+}
+async function readMetadata(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (err) {
+		throw new AppSdkError(`Not an alashi export archive: ${METADATA_FILE} is missing`, { cause: err });
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new AppSdkError(`Corrupt ${METADATA_FILE} in archive`, { cause: err });
+	}
+	const metadata = parsed;
+	if (metadata?.formatVersion !== 1) throw new AppSdkError(`Unsupported export formatVersion ${JSON.stringify(metadata?.formatVersion)}; this alashi reads formatVersion 1`);
+	return metadata;
+}
+async function readInstallRecord(path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(path, "utf8"));
+	} catch (err) {
+		throw new AppSdkError(`Archive has no readable ${CONTAINER_DIR}/app.json`, { cause: err });
+	}
+	const record = parsed;
+	if (!record || typeof record.name !== "string" || typeof record.version !== "string") throw new AppSdkError(`Archive ${CONTAINER_DIR}/app.json is not an install record`);
+	if (!APP_NAME_PATTERN.test(record.name)) throw new AppSdkError(`Archive carries an invalid app name: ${JSON.stringify(record.name)}`);
+	return record;
+}
+async function readTranscripts(dir) {
+	let entries;
+	try {
+		entries = await readdir(dir);
+	} catch (err) {
+		if (err.code === "ENOENT") return [];
+		throw err;
+	}
+	const transcripts = [];
+	for (const entry of entries.sort()) {
+		if (!entry.endsWith(TRANSCRIPT_EXT)) continue;
+		const sessionId = entry.slice(0, -6);
+		if (!SESSION_ID_PATTERN.test(sessionId)) continue;
+		transcripts.push({
+			sessionId,
+			content: await readFile(join(dir, entry), "utf8")
+		});
+	}
+	return transcripts;
+}
+/** Staging and apps/ are both under $ALASHI_HOME, so rename is the fast path. */
+async function moveDir(from, to) {
+	try {
+		await rename(from, to);
+	} catch (err) {
+		if (err.code !== "EXDEV") throw err;
+		await cp(from, to, { recursive: true });
+		await rm(from, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Restores a container exported by {@link exportApp}, plus its transcripts. */
+async function importApp(store, provider, archivePath) {
+	const archive = resolve(process.cwd(), archivePath);
+	if (!await exists(archive)) throw new AppSdkError(`Archive not found: ${archive}`);
+	await assertSafeMembers(archive);
+	const warnings = [];
+	const stage = join(store.stagingDir, randomUUID());
+	try {
+		await mkdir(stage, { recursive: true });
+		await tar([
+			"-xzf",
+			archive,
+			"-C",
+			stage,
+			"--no-same-owner"
+		]);
+		await assertNothingEscaped(stage);
+		await readMetadata(join(stage, METADATA_FILE));
+		const containerDir = join(stage, CONTAINER_DIR);
+		if (!await isDirectory(containerDir)) throw new AppSdkError(`Archive has no ${CONTAINER_DIR}/ directory: ${archive}`);
+		const record = await readInstallRecord(join(containerDir, "app.json"));
+		const name = record.name;
+		if (await store.readAppRecord(name)) throw new AppSdkError(`App "${name}" is already installed (use: alashi remove ${name})`);
+		const appDir = store.appDir(name);
+		if (await exists(appDir)) throw new AppSdkError(`${appDir} already exists (leftover data from a previous install); delete it before importing`);
+		await mkdir(store.appsDir, { recursive: true });
+		await moveDir(containerDir, appDir);
+		try {
+			await mkdir(store.appDataDir(name), { recursive: true });
+			await installDependencies(store.appRepoDir(name));
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new AppSdkError(`Restored ${name} to ${appDir}, but reinstalling its dependencies failed: ${message}. Run "alashi update ${name}" before using it.`, { cause: err });
+		}
+		const transcripts = await readTranscripts(join(stage, TRANSCRIPTS_DIR));
+		let restored = 0;
+		if (transcripts.length > 0) {
+			if (!provider.importTranscripts) warnings.push(`Provider "${provider.name}" cannot import transcripts; ${transcripts.length} conversation transcripts were not restored`);
+			else {
+				try {
+					await provider.importTranscripts(transcripts, { cwd: store.appDataDir(name) });
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					throw new AppSdkError(`Restored ${name} to ${appDir}, but restoring its transcripts failed: ${message}. The app works; its chat history does not.`, { cause: err });
+				}
+				restored = transcripts.length;
+			}
+		}
+		return {
+			record,
+			transcriptCount: restored,
+			warnings
+		};
+	} finally {
+		await rm(stage, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
 //#region src/runtime.ts
 function createLogger(prefix) {
 	const log = (level, message, data) => {
@@ -352,6 +827,30 @@ function createLogger(prefix) {
 	};
 }
 /**
+* Wraps a session so every `result` event's cost is accounted for before the
+* event reaches the caller. This sits under *every* session an app opens —
+* chat turns, cron job handlers, and app routes alike — so spend is recorded
+* no matter who opened the session.
+*/
+function meterSession(session, recordCost) {
+	return {
+		get id() {
+			return session.id;
+		},
+		send(input) {
+			const events = session.send(input);
+			return (async function* metered() {
+				for await (const event of events) {
+					if (event.type === "result") await recordCost(event.costUsd);
+					yield event;
+				}
+			})();
+		},
+		interrupt: () => session.interrupt(),
+		close: () => session.close()
+	};
+}
+/**
 * Wraps the host provider so every session an app opens automatically gets
 * its manifest-declared MCP servers, tool allowlist, agents, skills,
 * instructions, and data-dir cwd. Per-call options still win where they
@@ -362,6 +861,7 @@ function scopeProvider(provider, defaults) {
 		name: provider.name,
 		async createSession(options = {}) {
 			if (defaults.unreadyError !== void 0) throw new ConfigError(defaults.unreadyError);
+			await defaults.checkBudget?.();
 			const mcpServers = {
 				...defaults.mcpServers,
 				...options.mcpServers
@@ -372,7 +872,7 @@ function scopeProvider(provider, defaults) {
 				...options.agents
 			};
 			const skillDirs = [.../* @__PURE__ */ new Set([...defaults.skillDirs, ...options.skillDirs ?? []])];
-			return provider.createSession({
+			const session = await provider.createSession({
 				cwd: defaults.cwd,
 				...defaults.instructions !== void 0 && { systemPrompt: defaults.instructions },
 				...options,
@@ -381,6 +881,7 @@ function scopeProvider(provider, defaults) {
 				...Object.keys(agents).length > 0 && { agents },
 				...skillDirs.length > 0 && { skillDirs }
 			});
+			return defaults.recordCost ? meterSession(session, defaults.recordCost) : session;
 		}
 	};
 }
@@ -420,8 +921,12 @@ async function resolveAppConfig(store, manifest) {
 * Setup state shapes the session defaults: unconfigured MCP servers are
 * dropped (with their tools) so interpolation never hits a missing key, and
 * while required keys are missing the scoped provider fails closed.
+*
+* When a `usage` recorder is supplied, every session opened through the
+* returned context reports its per-turn cost to it, and the app's host-set
+* daily spend cap (if any) is enforced on every createSession.
 */
-async function buildAppContext(store, manifest, provider) {
+async function buildAppContext(store, manifest, provider, usage) {
 	const name = manifest.name;
 	const dataDir = store.appDataDir(name);
 	const repoDir = store.appRepoDir(name);
@@ -437,11 +942,19 @@ async function buildAppContext(store, manifest, provider) {
 	const excluded = status.integrations.filter((i) => !i.configured).map((i) => i.name);
 	const mcpServers = interpolate(Object.fromEntries(Object.entries(manifest.mcpServers).filter(([server]) => !excluded.includes(server)).map(([server, { optional: _optional, ...decl }]) => [server, decl])));
 	const allowedTools = manifest.permissions.allowedTools.filter((tool) => !excluded.some((server) => tool.startsWith(`mcp__${server}__`)));
+	const logger = createLogger(name);
+	const recordCost = usage ? async (costUsd) => {
+		try {
+			await usage.record(name, costUsd);
+		} catch (err) {
+			logger.warn("Failed to record AI spend", { error: String(err) });
+		}
+	} : void 0;
 	return {
 		appName: name,
 		dataDir,
 		config,
-		logger: createLogger(name),
+		logger,
 		state: new JsonFileStore(join(dataDir, "state.json")),
 		ai: scopeProvider(provider, {
 			mcpServers,
@@ -450,6 +963,8 @@ async function buildAppContext(store, manifest, provider) {
 			skillDirs: manifest.skills.map((dir) => resolve(repoDir, dir)),
 			...instructions !== void 0 && { instructions },
 			cwd: dataDir,
+			...recordCost !== void 0 && { recordCost },
+			...usage !== void 0 && { checkBudget: () => assertWithinBudget(store, usage, name) },
 			...!status.ready && { unreadyError: `App "${name}" is not configured: missing ${status.missing.join(", ")}. Set the missing keys in the dashboard settings or ${store.appConfigPath(name)}.` }
 		})
 	};
@@ -616,12 +1131,15 @@ function settingsPage(name) {
   .ro-item { margin-bottom: 12px; }
   .ro-item:last-child { margin-bottom: 0; }
   details summary { cursor: pointer; }
+  #budget-card input { max-width: 180px; }
+  #budget-status { margin-left: 12px; color: var(--muted); }
 </style>
 </head>
 <body>
 <header class="topbar"><a href="/">alashi</a> <span>/</span> <strong id="title"></strong> <span>settings</span></header>
 <main class="narrow">
   <div id="banner" class="banner" hidden></div>
+  <div id="budget-card"></div>
   <div id="cards"></div>
   <button id="save" class="primary">Save changes</button><span id="status"></span>
   <div id="manifest-cards"></div>
@@ -754,6 +1272,78 @@ function render(data) {
   }
 }
 
+function usd(value) {
+  return '$' + value.toFixed(value >= 1 ? 2 : 4);
+}
+
+/**
+ * Daily spend cap. A host setting, not an app config key: it lives in the
+ * host's own config.json and is enforced in createSession, so an app cannot
+ * raise its own ceiling through its manifest defaults or its config layer.
+ */
+function renderBudget(b, message) {
+  const root = document.getElementById('budget-card');
+  root.replaceChildren();
+  const capped = typeof b.dailyUsd === 'number';
+
+  const input = el('input', {
+    type: 'number', min: '0', step: '0.01', placeholder: 'no cap',
+    value: capped ? String(b.dailyUsd) : '',
+  });
+  const status = el('span', { id: 'budget-status', text: message || '' });
+
+  const save = el('button', {
+    class: 'primary',
+    text: 'Save cap',
+    onclick: async () => {
+      const raw = input.value.trim();
+      const dailyUsd = raw === '' ? null : Number(raw);
+      if (dailyUsd !== null && !(dailyUsd >= 0)) {
+        status.textContent = 'Enter a dollar amount, or leave empty for no cap.';
+        return;
+      }
+      status.textContent = 'Saving…';
+      const res = await fetch('/api/apps/' + APP + '/budget', {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ dailyUsd }),
+      });
+      if (!res.ok) {
+        status.textContent = 'Save failed (' + res.status + ')';
+        return;
+      }
+      renderBudget(await res.json(), dailyUsd === null ? 'Cap removed.' : 'Cap saved.');
+    },
+  });
+
+  const spent = 'Spent today (' + b.date + ', UTC): ' + usd(b.spentUsd);
+  const body = [
+    el('div', { class: 'desc', text:
+      'Enforced by the host: once the spend for the UTC day reaches the cap, new AI sessions for '
+      + 'this app are refused, and the counter resets at 00:00 UTC. This is a host setting — the '
+      + 'app cannot read or raise it through its own config.' }),
+    el('div', { class: 'field' }, [
+      el('label', { text: 'Daily spend cap (USD)' }),
+      input,
+    ]),
+    el('div', { class: 'desc', text: capped
+      ? spent + ' — ' + usd(b.remainingUsd) + ' left of ' + usd(b.dailyUsd)
+      : spent + ' — no cap set, spend is unlimited' }),
+    el('div', { style: 'margin-top:12px' }, [save, status]),
+  ];
+  if (b.overBudget) {
+    body.unshift(el('div', { class: 'banner warn', text:
+      'Over budget — new AI sessions are refused. ' + usd(b.spentUsd) + ' spent of the '
+      + usd(b.dailyUsd) + ' daily cap for ' + b.date + ' (UTC). Raise or clear the cap below, '
+      + 'or wait for the reset at 00:00 UTC.' }));
+  }
+
+  root.append(el('div', { class: 'card' }, [
+    el('h2', { text: 'Spend cap' }),
+    el('div', { class: 'body' }, body),
+  ]));
+}
+
 function roCard(title, children) {
   return el('div', { class: 'card' }, [
     el('h2', { text: title }),
@@ -827,10 +1417,13 @@ function renderManifest(m) {
 }
 
 async function load() {
-  const [res, manRes] = await Promise.all([
+  const [res, manRes, budgetRes] = await Promise.all([
     fetch('/api/apps/' + APP + '/config'),
     fetch('/api/apps/' + APP + '/manifest'),
+    fetch('/api/apps/' + APP + '/budget'),
   ]);
+  // Host bookkeeping: the cap renders even when the app itself fails to load.
+  if (budgetRes.ok) renderBudget(await budgetRes.json());
   if (!res.ok) {
     document.getElementById('banner').hidden = false;
     document.getElementById('banner').className = 'banner warn';
@@ -882,14 +1475,44 @@ const CONTENT_TYPES = {
 function escapeHtml(value) {
 	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
 }
+/** Host-rendered failure page — apps never need to ship their own error UI. */
+function appErrorPage(name, err) {
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(name)} — failed to load</title>
+<link rel="stylesheet" href="/assets/v1/system.css">
+</head>
+<body>
+<header class="topbar"><strong>alashi</strong></header>
+<main class="narrow">
+<h1>${escapeHtml(name)} failed to load</h1>
+<div class="panel">
+<p>${escapeHtml(String(err))}</p>
+<p class="muted"><a href="/">Back to apps</a></p>
+</div>
+</main>
+</body>
+</html>
+`;
+}
 /**
 * The host HTTP surface:
 *   GET  /                      dashboard of installed apps
 *   GET  /settings/:name        per-app settings page (config form)
-*   GET  /api/apps              installed apps as JSON
+*   GET  /api/apps              installed apps as JSON, each with todayCostUsd
+*                               and its daily spend cap / over-budget state
+*   GET  /api/apps/:name/usage  recorded AI spend: today's total, a daily series,
+*                               and the budget status
+*   GET  /api/apps/:name/budget today's spend against the app's daily cap
+*   PUT  /api/apps/:name/budget { dailyUsd: number | null } -> set or clear the cap
+*                               (a host setting; apps cannot set their own)
 *   POST /api/apps/:name/chat   { message, conversationId? } -> SSE stream of AgentEvents
 *                               (omit conversationId to start a new conversation; the
-*                                id is echoed in the x-conversation-id response header)
+*                                id is echoed in the x-conversation-id response header;
+*                                402 when the app is over its daily spend cap)
 *   GET  /api/apps/:name/chat/conversations          conversations, most recent first
 *   POST /api/apps/:name/chat/conversations  { sessionId?, title? } -> create a conversation,
 *                               optionally adopting an existing provider session (e.g. an
@@ -912,9 +1535,10 @@ function escapeHtml(value) {
 function createServer(store, provider) {
 	const apps = /* @__PURE__ */ new Map();
 	const sessions = /* @__PURE__ */ new Map();
+	const usage = new UsageRecorder(store);
 	async function startApp(name) {
 		const { definition, manifest } = await loadApp(store.appRepoDir(name));
-		const ctx = await buildAppContext(store, manifest, provider);
+		const ctx = await buildAppContext(store, manifest, provider, usage);
 		return {
 			manifest,
 			ctx,
@@ -1021,35 +1645,46 @@ function createServer(store, provider) {
 			return c.json({ error: "Not found" }, 404);
 		}
 	});
-	/** Readiness for the dashboard badge; undefined when the app fails to load. */
+	/** Readiness for the dashboard badge; loadError carries the failure reason. */
 	async function readiness(name) {
 		try {
 			const running = await getApp(name);
 			if (!running) return void 0;
 			return (await resolveAppConfig(store, running.manifest)).status;
-		} catch {
-			return;
+		} catch (err) {
+			return { loadError: String(err) };
 		}
 	}
 	app.get("/", async (c) => {
 		const records = await store.listInstalled();
-		const rows = (await Promise.all(records.map(async (r) => {
+		const cells = await Promise.all(records.map(async (r) => {
 			const name = escapeHtml(r.name);
 			const status = await readiness(r.name);
-			const badge = !status ? "<span class=\"badge err\">failed to load</span>" : status.ready ? "<span class=\"badge ok\">ready</span>" : `<a href="/settings/${name}"><span class="badge err">needs setup</span></a>`;
-			return `<tr>
+			const badge = !status ? "<span class=\"badge err\">failed to load</span>" : "loadError" in status ? `<span class="badge err" title="${escapeHtml(status.loadError)}">failed to load</span>` : status.ready ? "<span class=\"badge ok\">ready</span>" : `<a href="/settings/${name}"><span class="badge err">needs setup</span></a>`;
+			const budget = await budgetStatus(store, usage, r.name);
+			const todayCostUsd = budget.spentUsd;
+			const overBadge = budget.overBudget ? ` <a href="/settings/${name}" title="Daily AI spend cap reached — new sessions are refused until 00:00 UTC"><span class="badge err">over budget</span></a>` : "";
+			const cap = budget.dailyUsd === void 0 ? "" : ` <span class="muted" title="Daily spend cap">/ ${formatUsd(budget.dailyUsd)}</span>`;
+			return {
+				row: `<tr>
   <td><a href="/app/${name}/">${name}</a></td>
   <td class="muted">v${escapeHtml(r.version)}</td>
   <td class="muted">${escapeHtml(r.source.type)}</td>
-  <td>${badge}</td>
+  <td>${badge}${overBadge}</td>
+  <td class="muted" style="text-align:right">${formatUsd(todayCostUsd)}${cap}</td>
   <td style="text-align:right"><a href="/settings/${name}">settings</a></td>
-</tr>`;
-		}))).join("\n");
+</tr>`,
+				todayCostUsd
+			};
+		}));
+		const rows = cells.map((cell) => cell.row).join("\n");
+		const totalToday = cells.reduce((sum, cell) => sum + cell.todayCostUsd, 0);
 		const body = records.length === 0 ? "<div class=\"empty\">No apps installed. Run <code>alashi install &lt;name&gt;</code>.</div>" : `<table>
-<thead><tr><th>App</th><th>Version</th><th>Source</th><th>Status</th><th></th></tr></thead>
+<thead><tr><th>App</th><th>Version</th><th>Source</th><th>Status</th><th style="text-align:right" title="AI spend today (UTC)">Today</th><th></th></tr></thead>
 <tbody>
 ${rows}
 </tbody>
+<tfoot><tr><td colspan="4" class="muted">AI spend today (UTC)</td><td class="muted" style="text-align:right">${formatUsd(totalToday)}</td><td></td></tr></tfoot>
 </table>`;
 		return c.html(`<!doctype html>
 <html lang="en">
@@ -1072,7 +1707,58 @@ ${body}
 </html>
 `);
 	});
-	app.get("/api/apps", async (c) => c.json({ apps: await store.listInstalled() }));
+	app.get("/api/apps", async (c) => {
+		const records = await store.listInstalled();
+		const apps = await Promise.all(records.map(async (record) => {
+			const budget = await budgetStatus(store, usage, record.name);
+			return {
+				...record,
+				todayCostUsd: budget.spentUsd,
+				overBudget: budget.overBudget,
+				...budget.dailyUsd !== void 0 && { dailyBudgetUsd: budget.dailyUsd }
+			};
+		}));
+		return c.json({ apps });
+	});
+	/** Spend and budget are host bookkeeping: readable even when the app fails to load. */
+	async function installedApp(name) {
+		return APP_NAME_PATTERN.test(name) && await store.readAppRecord(name) !== void 0;
+	}
+	app.get("/api/apps/:name/usage", async (c) => {
+		const name = c.req.param("name");
+		if (!await installedApp(name)) return c.json({ error: `App "${name}" is not installed` }, 404);
+		const [summary, config] = await Promise.all([usage.summary(name), store.readGlobalConfig()]);
+		return c.json({
+			...summary,
+			budget: budgetStatusFor(summary, appBudget(config, name))
+		});
+	});
+	app.get("/api/apps/:name/budget", async (c) => {
+		const name = c.req.param("name");
+		if (!await installedApp(name)) return c.json({ error: `App "${name}" is not installed` }, 404);
+		return c.json(await budgetStatus(store, usage, name));
+	});
+	/**
+	* Sets the app's daily spend cap. A host setting, not an app config key: it
+	* never touches `apps/<name>/config.json`, so the app cannot raise it via
+	* PUT /api/apps/:name/config or by shipping a manifest default.
+	*/
+	app.put("/api/apps/:name/budget", async (c) => {
+		const name = c.req.param("name");
+		if (!await installedApp(name)) return c.json({ error: `App "${name}" is not installed` }, 404);
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "Body must be JSON" }, 400);
+		}
+		if (typeof body !== "object" || body === null || Array.isArray(body)) return c.json({ error: "Body must be { \"dailyUsd\": number | null }" }, 400);
+		const { dailyUsd } = body;
+		if (dailyUsd !== null && (typeof dailyUsd !== "number" || !Number.isFinite(dailyUsd))) return c.json({ error: "\"dailyUsd\" must be a number, or null to remove the cap" }, 400);
+		if (typeof dailyUsd === "number" && dailyUsd < 0) return c.json({ error: "\"dailyUsd\" must not be negative" }, 400);
+		await setAppBudget(store, name, dailyUsd === null ? void 0 : dailyUsd);
+		return c.json(await budgetStatus(store, usage, name));
+	});
 	app.get("/settings/:name", async (c) => {
 		const name = c.req.param("name");
 		if (!APP_NAME_PATTERN.test(name) || !await store.readAppRecord(name)) return c.json({ error: `App "${name}" is not installed` }, 404);
@@ -1241,6 +1927,12 @@ ${body}
 		}
 		if (typeof message !== "string" || message.length === 0) return c.json({ error: "Body must be { \"message\": string }" }, 400);
 		if (conversationId !== void 0 && typeof conversationId !== "string") return c.json({ error: "\"conversationId\" must be a string" }, 400);
+		try {
+			await assertWithinBudget(store, usage, name);
+		} catch (err) {
+			if (BudgetExceededError.is(err)) return c.json({ error: err.message }, 402);
+			throw err;
+		}
 		const state = await getChatState(name);
 		let convo;
 		if (conversationId !== void 0) {
@@ -1298,7 +1990,13 @@ ${body}
 	app.get("/app/:name", (c) => c.redirect(`/app/${c.req.param("name")}/`));
 	app.all("/app/:name/*", async (c) => {
 		const name = c.req.param("name");
-		const running = await getApp(name);
+		let running;
+		try {
+			running = await getApp(name);
+		} catch (err) {
+			if (c.req.method === "GET" && (c.req.header("accept") ?? "").includes("text/html")) return c.html(appErrorPage(name, err), 500);
+			throw err;
+		}
 		if (!running) return c.json({ error: `App "${name}" is not installed` }, 404);
 		if (c.req.method === "GET" || c.req.method === "HEAD") {
 			const file = await serveStatic(name, running.manifest, c.req.path);
@@ -1383,6 +2081,9 @@ var Store = class {
 	appJobStatePath(name) {
 		return join(this.appDir(name), "jobs.json");
 	}
+	appUsagePath(name) {
+		return join(this.appDir(name), "usage.json");
+	}
 	registryCachePath(name) {
 		if (!APP_NAME_PATTERN.test(name)) throw new AppSdkError(`Invalid registry name: ${JSON.stringify(name)}`);
 		return join(this.registriesDir, `${name}.json`);
@@ -1421,6 +2122,12 @@ var Store = class {
 	async writeJobState(name, state) {
 		await writeJson(this.appJobStatePath(name), state);
 	}
+	async readUsageState(name) {
+		return { days: (await readJson(this.appUsagePath(name)))?.days ?? [] };
+	}
+	async writeUsageState(name, state) {
+		await writeJson(this.appUsagePath(name), state);
+	}
 	async listInstalled() {
 		let entries;
 		try {
@@ -1439,6 +2146,6 @@ var Store = class {
 	}
 };
 //#endregion
-export { checkSdkCompatibility as _, installApp as a, addRegistry as c, removeRegistry as d, resolveApp as f, loadApp as g, updateSource as h, resolveAppConfig as i, readCachedIndex as l, parseSourceArg as m, createServer as n, removeApp as o, fetchSource as p, buildAppContext as r, updateApp as s, Store as t, refreshRegistry as u };
+export { UsageRecorder as A, BudgetExceededError as C, budgetStatusFor as D, budgetStatus as E, utcDay as M, setAppBudget as O, BUDGET_EXCEEDED_CODE as S, assertWithinBudget as T, fetchSource as _, EXPORT_FORMAT_VERSION as a, loadApp as b, installApp as c, updateApp as d, addRegistry as f, resolveApp as g, removeRegistry as h, resolveAppConfig as i, formatUsd as j, USAGE_RETENTION_DAYS as k, installDependencies as l, refreshRegistry as m, createServer as n, exportApp as o, readCachedIndex as p, buildAppContext as r, importApp as s, Store as t, removeApp as u, parseSourceArg as v, appBudget as w, checkSdkCompatibility as x, updateSource as y };
 
-//# sourceMappingURL=store-Cxxnjq70.mjs.map
+//# sourceMappingURL=store-VoJe_U1Q.mjs.map