@nextclaw/service 0.1.1

package/dist/cli/commands/skills/skills-query.service.d.ts

@@ -0,0 +1,141 @@
+import { LocalizedTextMap } from "./marketplace.metadata.js";
+import { SkillScope } from "@nextclaw/core";
+
+//#region src/cli/commands/skills/skills-query.service.d.ts
+type MarketplaceSkillSort = "relevance" | "updated";
+type MarketplaceSkillInstallKind = "builtin" | "marketplace";
+type MarketplaceInstallSpec = {
+  kind: MarketplaceSkillInstallKind;
+  spec: string;
+  command: string;
+};
+type MarketplaceSkillItemSummary = {
+  id: string;
+  slug: string;
+  type: "skill";
+  name: string;
+  summary: string;
+  summaryI18n: LocalizedTextMap;
+  tags: string[];
+  author: string;
+  install: MarketplaceInstallSpec;
+  updatedAt: string;
+};
+type MarketplaceSkillItemView = MarketplaceSkillItemSummary & {
+  description?: string;
+  descriptionI18n?: LocalizedTextMap;
+  sourceRepo?: string;
+  homepage?: string;
+  publishedAt: string;
+};
+type MarketplaceSkillContentView = {
+  type: "skill";
+  slug: string;
+  name: string;
+  install: MarketplaceInstallSpec;
+  source: "builtin" | "marketplace" | "remote";
+  raw: string;
+  metadataRaw?: string;
+  bodyRaw: string;
+  sourceUrl?: string;
+};
+type MarketplaceSkillListView = {
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+  sort: MarketplaceSkillSort;
+  query?: string;
+  items: MarketplaceSkillItemSummary[];
+};
+type MarketplaceSkillRecommendationView = {
+  type: "skill";
+  sceneId: string;
+  title: string;
+  description?: string;
+  total: number;
+  items: MarketplaceSkillItemSummary[];
+};
+type InstalledSkillSummaryView = {
+  ref: string;
+  name: string;
+  path: string;
+  relativePath: string | null;
+  scope: SkillScope;
+  source: SkillScope;
+  summary: string | null;
+  summaryI18n: LocalizedTextMap | null;
+  description: string | null;
+  descriptionI18n: LocalizedTextMap | null;
+  author: string | null;
+  tags: string[];
+  always: boolean;
+};
+type InstalledSkillDetailView = InstalledSkillSummaryView & {
+  metadata: Record<string, string> | null;
+  raw: string;
+  bodyRaw: string;
+};
+type InstalledSkillsListView = {
+  workspace: string;
+  total: number;
+  skills: InstalledSkillSummaryView[];
+};
+type MarketplaceSkillsSearchView = MarketplaceSkillListView & {
+  apiBaseUrl: string;
+};
+type MarketplaceSkillInfoView = {
+  apiBaseUrl: string;
+  item: MarketplaceSkillItemView;
+  content: MarketplaceSkillContentView | null;
+  contentUnavailableReason: string | null;
+};
+type MarketplaceSkillsRecommendationResultView = MarketplaceSkillRecommendationView & {
+  apiBaseUrl: string;
+};
+declare class SkillsQueryService {
+  listInstalled: (params: {
+    workdir: string;
+    query?: string;
+    scope?: string;
+  }) => InstalledSkillsListView;
+  getInstalledInfo: (params: {
+    workdir: string;
+    selector: string;
+  }) => InstalledSkillDetailView;
+  searchMarketplaceSkills: (params: {
+    apiBaseUrl?: string;
+    query?: string;
+    tag?: string;
+    sort?: string;
+    page?: string | number;
+    pageSize?: string | number;
+  }) => Promise<MarketplaceSkillsSearchView>;
+  getMarketplaceSkillInfo: (params: {
+    apiBaseUrl?: string;
+    slug: string;
+  }) => Promise<MarketplaceSkillInfoView>;
+  recommendMarketplaceSkills: (params: {
+    apiBaseUrl?: string;
+    scene?: string;
+    limit?: string | number;
+  }) => Promise<MarketplaceSkillsRecommendationResultView>;
+  private buildInstalledSkillSummary;
+  private buildInstalledSkillDetail;
+  private matchesInstalledSkillQuery;
+  private stripFrontmatter;
+  private readAlwaysFlag;
+  private buildRelativePath;
+  private normalizeMarketplaceSummary;
+  private normalizeMarketplaceItem;
+  private normalizeMarketplaceContent;
+  private normalizeMarketplaceInstallSpec;
+  private normalizeInstalledScope;
+  private normalizeMarketplaceSort;
+  private normalizePositiveInteger;
+  private normalizeRequiredString;
+  private normalizeOptionalString;
+  private fetchMarketplaceView;
+}
+//#endregion
+export { InstalledSkillDetailView, InstalledSkillSummaryView, InstalledSkillsListView, MarketplaceSkillInfoView, MarketplaceSkillsRecommendationResultView, MarketplaceSkillsSearchView, SkillsQueryService };

package/dist/cli/commands/skills/skills-query.service.js

@@ -0,0 +1,212 @@
+import { parseSkillFrontmatter } from "./marketplace.metadata.js";
+import { runWithMarketplaceNetworkRetry } from "./marketplace-network-retry.js";
+import { readMarketplaceEnvelope, resolveMarketplaceApiBase } from "./marketplace-client.js";
+import { relative, resolve } from "node:path";
+import { SkillsLoader } from "@nextclaw/core";
+import { readFileSync } from "node:fs";
+//#region src/cli/commands/skills/skills-query.service.ts
+var SkillsQueryService = class {
+	listInstalled = (params) => {
+		const workspace = resolve(params.workdir);
+		const loader = new SkillsLoader(workspace);
+		const scope = this.normalizeInstalledScope(params.scope);
+		const normalizedQuery = this.normalizeOptionalString(params.query)?.toLowerCase() ?? null;
+		const skills = loader.listSkills(false).map((skill) => this.buildInstalledSkillSummary(skill, loader, workspace)).filter((skill) => scope === "all" || skill.scope === scope).filter((skill) => this.matchesInstalledSkillQuery(skill, normalizedQuery));
+		return {
+			workspace,
+			total: skills.length,
+			skills
+		};
+	};
+	getInstalledInfo = (params) => {
+		const workspace = resolve(params.workdir);
+		const loader = new SkillsLoader(workspace);
+		const skill = loader.getSkillInfo(params.selector);
+		if (!skill) throw new Error(`Installed skill not found: ${params.selector}`);
+		return this.buildInstalledSkillDetail(skill, loader, workspace);
+	};
+	searchMarketplaceSkills = async (params) => {
+		const apiBaseUrl = resolveMarketplaceApiBase(params.apiBaseUrl);
+		const result = await this.fetchMarketplaceView({
+			apiBaseUrl,
+			path: "/api/v1/skills/items",
+			query: {
+				q: this.normalizeOptionalString(params.query) ?? void 0,
+				tag: this.normalizeOptionalString(params.tag) ?? void 0,
+				sort: this.normalizeMarketplaceSort(params.sort),
+				page: this.normalizePositiveInteger(params.page),
+				pageSize: this.normalizePositiveInteger(params.pageSize)
+			}
+		});
+		return {
+			apiBaseUrl,
+			...result,
+			items: result.items.map((item) => this.normalizeMarketplaceSummary(item))
+		};
+	};
+	getMarketplaceSkillInfo = async (params) => {
+		const slug = this.normalizeRequiredString(params.slug, "skill slug");
+		const apiBaseUrl = resolveMarketplaceApiBase(params.apiBaseUrl);
+		const encodedSlug = encodeURIComponent(slug);
+		const item = await this.fetchMarketplaceView({
+			apiBaseUrl,
+			path: `/api/v1/skills/items/${encodedSlug}`
+		});
+		let content = null;
+		let contentUnavailableReason = null;
+		try {
+			content = this.normalizeMarketplaceContent(await this.fetchMarketplaceView({
+				apiBaseUrl,
+				path: `/api/v1/skills/items/${encodedSlug}/content`
+			}));
+		} catch (error) {
+			contentUnavailableReason = error instanceof Error ? error.message : String(error);
+		}
+		return {
+			apiBaseUrl,
+			item: this.normalizeMarketplaceItem(item),
+			content,
+			contentUnavailableReason
+		};
+	};
+	recommendMarketplaceSkills = async (params) => {
+		const apiBaseUrl = resolveMarketplaceApiBase(params.apiBaseUrl);
+		const result = await this.fetchMarketplaceView({
+			apiBaseUrl,
+			path: "/api/v1/skills/recommendations",
+			query: {
+				scene: this.normalizeOptionalString(params.scene) ?? void 0,
+				limit: this.normalizePositiveInteger(params.limit)
+			}
+		});
+		return {
+			apiBaseUrl,
+			...result,
+			items: result.items.map((item) => this.normalizeMarketplaceSummary(item))
+		};
+	};
+	buildInstalledSkillSummary = (skill, loader, workspace) => {
+		const raw = readFileSync(skill.path, "utf8");
+		const metadata = loader.getSkillMetadata(skill);
+		const frontmatter = parseSkillFrontmatter(raw);
+		return {
+			ref: skill.ref,
+			name: skill.name,
+			path: skill.path,
+			relativePath: this.buildRelativePath(workspace, skill.path),
+			scope: skill.scope,
+			source: skill.source,
+			summary: frontmatter.summary ?? null,
+			summaryI18n: frontmatter.summaryI18n ?? null,
+			description: frontmatter.description ?? metadata?.description ?? null,
+			descriptionI18n: frontmatter.descriptionI18n ?? null,
+			author: frontmatter.author ?? null,
+			tags: frontmatter.tags ?? [],
+			always: this.readAlwaysFlag(metadata)
+		};
+	};
+	buildInstalledSkillDetail = (skill, loader, workspace) => {
+		const summary = this.buildInstalledSkillSummary(skill, loader, workspace);
+		const raw = readFileSync(skill.path, "utf8");
+		return {
+			...summary,
+			metadata: loader.getSkillMetadata(skill),
+			raw,
+			bodyRaw: this.stripFrontmatter(raw)
+		};
+	};
+	matchesInstalledSkillQuery = (skill, query) => {
+		if (!query) return true;
+		return [
+			skill.ref,
+			skill.name,
+			skill.path,
+			skill.relativePath ?? "",
+			skill.scope,
+			skill.source,
+			skill.summary ?? "",
+			skill.description ?? "",
+			skill.author ?? "",
+			...skill.tags,
+			...Object.values(skill.summaryI18n ?? {}),
+			...Object.values(skill.descriptionI18n ?? {})
+		].some((value) => value.toLowerCase().includes(query));
+	};
+	stripFrontmatter = (raw) => {
+		const normalized = raw.replace(/\r\n/g, "\n");
+		const match = normalized.match(/^---\n[\s\S]*?\n---\n?/);
+		if (!match) return normalized.trim();
+		return normalized.slice(match[0].length).trim();
+	};
+	readAlwaysFlag = (metadata) => {
+		if (metadata?.always === "true") return true;
+		const raw = metadata?.metadata;
+		if (!raw) return false;
+		try {
+			return JSON.parse(raw).nextclaw?.always === true;
+		} catch {
+			return false;
+		}
+	};
+	buildRelativePath = (workspace, absolutePath) => {
+		const relativePath = relative(workspace, absolutePath).replace(/\\/g, "/");
+		return relativePath.startsWith("..") ? null : relativePath;
+	};
+	normalizeMarketplaceSummary = (item) => ({
+		...item,
+		install: this.normalizeMarketplaceInstallSpec(item.install, item.slug)
+	});
+	normalizeMarketplaceItem = (item) => ({
+		...item,
+		install: this.normalizeMarketplaceInstallSpec(item.install, item.slug)
+	});
+	normalizeMarketplaceContent = (content) => ({
+		...content,
+		install: this.normalizeMarketplaceInstallSpec(content.install, content.slug)
+	});
+	normalizeMarketplaceInstallSpec = (install, slug) => ({
+		...install,
+		command: `nextclaw marketplace skills install ${slug}`
+	});
+	normalizeInstalledScope = (value) => {
+		const normalized = this.normalizeOptionalString(value);
+		if (!normalized || normalized === "all") return "all";
+		if (normalized === "builtin" || normalized === "project" || normalized === "workspace") return normalized;
+		throw new Error(`Invalid skill scope: ${value}. Expected all, builtin, project, or workspace.`);
+	};
+	normalizeMarketplaceSort = (value) => {
+		const normalized = this.normalizeOptionalString(value);
+		if (!normalized) return;
+		if (normalized === "relevance" || normalized === "updated") return normalized;
+		throw new Error(`Invalid marketplace sort: ${value}. Expected relevance or updated.`);
+	};
+	normalizePositiveInteger = (value) => {
+		if (value === void 0) return;
+		const parsed = Number(value);
+		if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Expected a positive integer, received: ${String(value)}`);
+		return String(Math.floor(parsed));
+	};
+	normalizeRequiredString = (value, label) => {
+		const normalized = this.normalizeOptionalString(value);
+		if (!normalized) throw new Error(`Missing ${label}`);
+		return normalized;
+	};
+	normalizeOptionalString = (value) => {
+		if (typeof value !== "string") return null;
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	};
+	fetchMarketplaceView = async (params) => {
+		const url = new URL(params.path, `${params.apiBaseUrl}/`);
+		for (const [key, value] of Object.entries(params.query ?? {})) if (typeof value === "string" && value.length > 0) url.searchParams.set(key, value);
+		const response = await runWithMarketplaceNetworkRetry(async () => await fetch(url.toString(), { headers: { Accept: "application/json" } }));
+		const payload = await readMarketplaceEnvelope(response);
+		if (!payload.ok || !payload.data) {
+			const message = payload.error?.message || `marketplace request failed: ${response.status}`;
+			throw new Error(message);
+		}
+		return payload.data;
+	};
+};
+//#endregion
+export { SkillsQueryService };

package/dist/cli/commands/start/index.d.ts

@@ -0,0 +1,18 @@
+import { StartCommandOptions } from "../../../shared/types/cli.types.js";
+import { RuntimeCommandService } from "../../../shared/services/runtime/runtime-command.service.js";
+
+//#region src/cli/commands/start/index.d.ts
+declare class StartCommands {
+  private readonly deps;
+  constructor(deps: {
+    runtimeCommandService: RuntimeCommandService;
+    forcedPublicHost: string;
+    init: (params: {
+      source: string;
+      auto: boolean;
+    }) => Promise<void>;
+  });
+  run: (opts: StartCommandOptions) => Promise<void>;
+}
+//#endregion
+export { StartCommands };

package/dist/cli/commands/start/index.js

@@ -0,0 +1,25 @@
+import { parseStartTimeoutMs, resolveManagedServiceUiOverrides } from "../../../shared/utils/runtime-helpers.js";
+//#region src/cli/commands/start/index.ts
+var StartCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async (opts) => {
+		const startupTimeoutMs = parseStartTimeoutMs(opts.startTimeout);
+		await this.deps.init({
+			source: "start",
+			auto: true
+		});
+		const uiOverrides = resolveManagedServiceUiOverrides({
+			uiPort: opts.uiPort,
+			forcedPublicHost: this.deps.forcedPublicHost
+		});
+		await this.deps.runtimeCommandService.startService({
+			uiOverrides,
+			open: Boolean(opts.open),
+			startupTimeoutMs
+		});
+	};
+};
+//#endregion
+export { StartCommands };

package/dist/cli/commands/stop/index.d.ts

@@ -0,0 +1,12 @@
+import { RuntimeCommandService } from "../../../shared/services/runtime/runtime-command.service.js";
+
+//#region src/cli/commands/stop/index.d.ts
+declare class StopCommands {
+  private readonly deps;
+  constructor(deps: {
+    runtimeCommandService: RuntimeCommandService;
+  });
+  run: () => Promise<void>;
+}
+//#endregion
+export { StopCommands };

package/dist/cli/commands/stop/index.js

@@ -0,0 +1,11 @@
+//#region src/cli/commands/stop/index.ts
+var StopCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async () => {
+		await this.deps.runtimeCommandService.stopService();
+	};
+};
+//#endregion
+export { StopCommands };

package/dist/cli/commands/ui/index.d.ts

@@ -0,0 +1,14 @@
+import { UiCommandOptions } from "../../../shared/types/cli.types.js";
+import { RuntimeCommandService } from "../../../shared/services/runtime/runtime-command.service.js";
+
+//#region src/cli/commands/ui/index.d.ts
+declare class UiCommands {
+  private readonly deps;
+  constructor(deps: {
+    runtimeCommandService: RuntimeCommandService;
+    forcedPublicHost: string;
+  });
+  run: (opts: UiCommandOptions) => Promise<void>;
+}
+//#endregion
+export { UiCommands };

package/dist/cli/commands/ui/index.js

@@ -0,0 +1,17 @@
+//#region src/cli/commands/ui/index.ts
+var UiCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async (opts) => {
+		const uiOverrides = {
+			enabled: true,
+			host: this.deps.forcedPublicHost,
+			open: Boolean(opts.open)
+		};
+		if (opts.port) uiOverrides.port = Number(opts.port);
+		await this.deps.runtimeCommandService.startGateway({ uiOverrides });
+	};
+};
+//#endregion
+export { UiCommands };

package/dist/cli/commands/usage/index.d.ts

@@ -0,0 +1,2 @@
+import { LlmUsageCommandService } from "./services/llm-usage-command.service.js";
+export { LlmUsageCommandService };

package/dist/cli/commands/usage/index.js

@@ -0,0 +1,2 @@
+import { LlmUsageCommandService } from "./services/llm-usage-command.service.js";
+export { LlmUsageCommandService };

package/dist/cli/commands/usage/services/llm-usage-command.service.d.ts

@@ -0,0 +1,22 @@
+import { UsageCommandOptions } from "../../../../shared/types/cli.types.js";
+import { LlmUsageQueryService } from "./llm-usage-query.service.js";
+
+//#region src/cli/commands/usage/services/llm-usage-command.service.d.ts
+declare class LlmUsageCommandService {
+  private readonly deps;
+  constructor(deps?: {
+    queryService?: LlmUsageQueryService;
+  });
+  readonly show: (opts?: UsageCommandOptions) => Promise<void>;
+  private get queryService();
+  private readonly showSnapshot;
+  private readonly showHistory;
+  private readonly showStats;
+  private readonly renderSnapshot;
+  private readonly renderHistory;
+  private readonly renderStats;
+  private readonly resolveLimit;
+  private readonly toPercent;
+}
+//#endregion
+export { LlmUsageCommandService };

package/dist/cli/commands/usage/services/llm-usage-command.service.js

@@ -0,0 +1,160 @@
+import { llmUsageQueryService } from "./llm-usage-query.service.js";
+//#region src/cli/commands/usage/services/llm-usage-command.service.ts
+var LlmUsageCommandService = class {
+	constructor(deps = {}) {
+		this.deps = deps;
+	}
+	show = async (opts = {}) => {
+		if (opts.history && opts.stats) {
+			console.error("Choose only one usage mode: `--history` or `--stats`.");
+			process.exitCode = 1;
+			return;
+		}
+		if (opts.history) {
+			this.showHistory(opts);
+			return;
+		}
+		if (opts.stats) {
+			this.showStats(opts);
+			return;
+		}
+		this.showSnapshot(opts);
+	};
+	get queryService() {
+		return this.deps.queryService ?? llmUsageQueryService;
+	}
+	showSnapshot = (opts) => {
+		const snapshot = this.queryService.getSnapshot();
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: Boolean(snapshot),
+				mode: "snapshot",
+				path: this.queryService.snapshotPath,
+				snapshot
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (!snapshot) {
+			console.log([
+				"No LLM usage snapshot recorded yet.",
+				`Snapshot path: ${this.queryService.snapshotPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderSnapshot(snapshot));
+		process.exitCode = 0;
+	};
+	showHistory = (opts) => {
+		const records = this.queryService.getHistory(opts.limit);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: records.length > 0,
+				mode: "history",
+				path: this.queryService.historyPath,
+				limit: this.resolveLimit(opts.limit),
+				records
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (records.length === 0) {
+			console.log([
+				"No LLM usage history recorded yet.",
+				`History path: ${this.queryService.historyPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage --history`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderHistory(records));
+		process.exitCode = 0;
+	};
+	showStats = (opts) => {
+		const stats = this.queryService.getStats();
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: stats.totalRecords > 0,
+				mode: "stats",
+				path: this.queryService.historyPath,
+				stats
+			}, null, 2));
+			process.exitCode = 0;
+			return;
+		}
+		if (stats.totalRecords === 0) {
+			console.log([
+				"No LLM usage history recorded yet.",
+				`History path: ${this.queryService.historyPath}`,
+				"Run `nextclaw agent -m \"ping\"` or use the local UI once, then retry `nextclaw usage --stats`."
+			].join("\n"));
+			process.exitCode = 0;
+			return;
+		}
+		console.log(this.renderStats(stats));
+		process.exitCode = 0;
+	};
+	renderSnapshot = (snapshot) => {
+		const lines = [
+			"Latest LLM usage snapshot",
+			`Observed at: ${snapshot.observedAt}`,
+			`Source: ${snapshot.source}`,
+			`Model: ${snapshot.model ?? "unknown"}`,
+			`Prompt tokens: ${snapshot.summary.promptTokens}`,
+			`Completion tokens: ${snapshot.summary.completionTokens}`,
+			`Total tokens: ${snapshot.summary.totalTokens}`,
+			`Cached tokens: ${snapshot.summary.cachedTokens}`,
+			`Cache hit: ${snapshot.summary.cacheHit ? "yes" : "no"}`,
+			`Snapshot path: ${this.queryService.snapshotPath}`
+		];
+		if (snapshot.summary.cacheMetricKeys.length > 0) lines.push(`Cache metric keys: ${snapshot.summary.cacheMetricKeys.join(", ")}`);
+		if (Object.keys(snapshot.usage).length > 0) lines.push("", "Raw usage:", JSON.stringify(snapshot.usage, null, 2));
+		return lines.join("\n");
+	};
+	renderHistory = (records) => {
+		const lines = [
+			"Recent LLM usage history",
+			`History path: ${this.queryService.historyPath}`,
+			`Showing: ${records.length} record(s)`,
+			""
+		];
+		for (const [index, record] of records.entries()) lines.push(`${index + 1}. ${record.observedAt} | source=${record.source} | model=${record.model ?? "unknown"} | total=${record.summary.totalTokens} | cached=${record.summary.cachedTokens} | cache-hit=${record.summary.cacheHit ? "yes" : "no"}`);
+		return lines.join("\n");
+	};
+	renderStats = (stats) => {
+		const lines = [
+			"LLM usage history stats",
+			`History path: ${this.queryService.historyPath}`,
+			`Records: ${stats.totalRecords}`,
+			`Usage records: ${stats.usageRecordCount}`,
+			`Empty usage records: ${stats.emptyUsageRecordCount}`,
+			`Prompt-bearing records: ${stats.promptTokenRecordCount}`,
+			`Oldest observed at: ${stats.oldestObservedAt ?? "n/a"}`,
+			`Latest observed at: ${stats.latestObservedAt ?? "n/a"}`,
+			`Prompt tokens: ${stats.totalPromptTokens}`,
+			`Completion tokens: ${stats.totalCompletionTokens}`,
+			`Total tokens: ${stats.totalTokens}`,
+			`Cached tokens: ${stats.totalCachedTokens}`,
+			`Cache hit records: ${stats.cacheHitRecords}/${stats.promptTokenRecordCount} (${this.toPercent(stats.cacheHitRate)})`,
+			`Cache token rate: ${this.toPercent(stats.tokenCacheRate)}`
+		];
+		if (stats.sources.length > 0) lines.push(`Sources: ${stats.sources.map((item) => `${item.value}=${item.count}`).join(", ")}`);
+		if (stats.models.length > 0) lines.push(`Models: ${stats.models.map((item) => `${item.value}=${item.count}`).join(", ")}`);
+		return lines.join("\n");
+	};
+	resolveLimit = (value) => {
+		if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+		if (typeof value === "string" && value.trim().length > 0) {
+			const parsed = Number(value);
+			if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+		}
+		return 10;
+	};
+	toPercent = (value) => {
+		return `${(value * 100).toFixed(1)}%`;
+	};
+};
+//#endregion
+export { LlmUsageCommandService };

package/dist/cli/commands/usage/services/llm-usage-query.service.d.ts

@@ -0,0 +1,43 @@
+import { LlmUsageRecord, LlmUsageStore } from "@nextclaw/kernel";
+
+//#region src/cli/commands/usage/services/llm-usage-query.service.d.ts
+type LlmUsageStats = {
+  totalRecords: number;
+  usageRecordCount: number;
+  emptyUsageRecordCount: number;
+  promptTokenRecordCount: number;
+  oldestObservedAt: string | null;
+  latestObservedAt: string | null;
+  totalPromptTokens: number;
+  totalCompletionTokens: number;
+  totalTokens: number;
+  totalCachedTokens: number;
+  cacheHitRecords: number;
+  cacheHitRate: number;
+  tokenCacheRate: number;
+  sources: Array<{
+    value: string;
+    count: number;
+  }>;
+  models: Array<{
+    value: string;
+    count: number;
+  }>;
+};
+declare class LlmUsageQueryService {
+  private readonly store;
+  constructor(deps?: {
+    store?: LlmUsageStore;
+  });
+  get snapshotPath(): string;
+  get historyPath(): string;
+  readonly getSnapshot: () => LlmUsageRecord | null;
+  readonly getHistory: (limit?: string | number) => LlmUsageRecord[];
+  readonly getStats: () => LlmUsageStats;
+  private readonly resolveLimit;
+  private readonly bumpCounter;
+  private readonly toSortedCounts;
+}
+declare const llmUsageQueryService: LlmUsageQueryService;
+//#endregion
+export { LlmUsageQueryService, LlmUsageStats, llmUsageQueryService };