@danypops/jittor 0.6.0 → 0.7.0

package/src/service.ts

@@ -1,7 +1,10 @@
-import { COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES, CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS, CONTEXT_ASSESSMENT_QUERY_LIMIT, SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES } from "./constants.ts";
+import { errorResponse, healthResponse, readyResponse, requireBearerToken } from "@danypops/daemon-kit/http";
+import { COMPACTION_DURATION_ESTIMATE_MAX_SAMPLES, CONTEXT_ASSESSMENT_DEFAULT_WINDOW_MS, CONTEXT_ASSESSMENT_QUERY_LIMIT, MAX_USAGE_BUCKETS, PRUNE_MIN_AGE_MS, SERVICE_MAX_BODY_BYTES, SERVICE_MAX_RESPONSE_BYTES, TASK_COST_QUERY_LIMIT, USAGE_MAX_DISTINCT_SCOPES } from "./constants.ts";
 import { VERSION } from "./version.ts";
 import { validateMetricObservation, type MetricObservation, type MetricQuery, type StoredMetricObservation } from "./domain/metric.ts";
 import { assessContextTelemetry, estimateCompactionDuration, type CompactionDurationEstimate, type ContextAssessment } from "./domain/context-telemetry.ts";
+import { buildTaskCostSummary, type TaskCostSummary } from "./domain/task-cost.ts";
+import type { UsageAggregateRow } from "./domain/usage.ts";
 import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "./domain/benchmark.ts";
 import type { ModelRanker, ModelRecommendationInput } from "./domain/model-ranking-service.ts";
 import type { ModelRankingResult } from "./domain/model-ranking.ts";
@@ -13,6 +16,9 @@ import type { PolicyDecision, Route } from "./policy.ts";
 export const EXPECTED_OPERATION_NAMES = [
 	"metrics.record",
 	"metrics.query",
+	"metrics.distinct_scopes",
+	"metrics.usage_series",
+	"metrics.cost_by_task",
 	"metrics.prune",
 	"benchmark.refresh",
 	"benchmark.status",
@@ -36,7 +42,10 @@ export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
 export interface OperationInputs {
 	"metrics.record": MetricObservation;
 	"metrics.query": MetricQuery;
-	"metrics.prune": { before: number };
+	"metrics.distinct_scopes": { source: string; since: number; until: number; limit?: number };
+	"metrics.usage_series": { source: string; since: number; until: number; bucketSizeMs: number; bucketCount: number; scopeLimit?: number };
+	"metrics.cost_by_task": { since: number; until: number };
+	"metrics.prune": { before: number; force?: boolean };
 	"benchmark.refresh": { force?: boolean };
 	"benchmark.status": Record<string, never>;
 	"benchmark.query": BenchmarkQuery;
@@ -57,6 +66,9 @@ export interface OperationInputs {
 export interface OperationOutputs {
 	"metrics.record": StoredMetricObservation;
 	"metrics.query": StoredMetricObservation[];
+	"metrics.distinct_scopes": string[];
+	"metrics.usage_series": { rows: UsageAggregateRow[]; truncated: boolean };
+	"metrics.cost_by_task": TaskCostSummary;
 	"metrics.prune": { deleted: number };
 	"benchmark.refresh": BenchmarkRefreshResult;
 	"benchmark.status": BenchmarkRefreshResult;
@@ -119,9 +131,61 @@ export class JittorService {
 		switch (operation) {
 			case "metrics.record": return this.metrics.record(validateMetricObservation(input));
 			case "metrics.query": return this.metrics.query(input as MetricQuery);
+			case "metrics.distinct_scopes": {
+				const source = input["source"];
+				const since = input["since"];
+				const until = input["until"];
+				if (typeof source !== "string" || source.length === 0) throw new Error("source is required");
+				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+					throw new Error("distinct scopes requires non-negative ordered integer bounds");
+				}
+				const requestedLimit = input["limit"];
+				const limit = Number.isFinite(requestedLimit) ? Math.max(1, Math.min(USAGE_MAX_DISTINCT_SCOPES, Math.floor(requestedLimit as number))) : USAGE_MAX_DISTINCT_SCOPES;
+				return this.metrics.distinctScopes({ source, since: since as number, until: until as number, limit });
+			}
+			case "metrics.usage_series": {
+				const source = input["source"];
+				const since = input["since"];
+				const until = input["until"];
+				const bucketSizeMs = input["bucketSizeMs"];
+				const bucketCount = input["bucketCount"];
+				if (typeof source !== "string" || source.length === 0) throw new Error("source is required");
+				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+					throw new Error("usage series requires non-negative ordered integer bounds");
+				}
+				if (typeof bucketSizeMs !== "number" || !Number.isFinite(bucketSizeMs) || bucketSizeMs <= 0) throw new Error("bucketSizeMs must be a positive number");
+				if (!Number.isInteger(bucketCount) || (bucketCount as number) <= 0 || (bucketCount as number) > MAX_USAGE_BUCKETS) {
+					throw new Error(`bucketCount must be a positive integer up to ${MAX_USAGE_BUCKETS}`);
+				}
+				const requestedScopeLimit = input["scopeLimit"];
+				const scopeLimit = Number.isFinite(requestedScopeLimit) ? Math.max(1, Math.min(USAGE_MAX_DISTINCT_SCOPES, Math.floor(requestedScopeLimit as number))) : USAGE_MAX_DISTINCT_SCOPES;
+				const scopes = this.metrics.distinctScopes({ source, since: since as number, until: until as number, limit: scopeLimit });
+				// More distinct scopes may exist beyond this bounded list -- that is the only remaining
+				// truncation risk once aggregation replaces a per-scope raw-row fetch (see aggregateUsage's
+				// own doc comment for the incident this was built to stop repeating).
+				const truncated = scopes.length >= scopeLimit;
+				const rows = scopes.length === 0 ? [] : this.metrics.aggregateUsage({
+					source, scopes, since: since as number, until: until as number, bucketSizeMs, bucketCount: bucketCount as number,
+				});
+				return { rows, truncated };
+			}
+			case "metrics.cost_by_task": {
+				const since = input["since"];
+				const until = input["until"];
+				if (!Number.isSafeInteger(since) || !Number.isSafeInteger(until) || (since as number) < 0 || (until as number) < (since as number)) {
+					throw new Error("cost by task requires non-negative ordered integer bounds");
+				}
+				const rows = this.metrics.query({ source: "pi", since: since as number, until: until as number, order: "desc", limit: TASK_COST_QUERY_LIMIT });
+				return buildTaskCostSummary(rows, { since: since as number, until: until as number, truncated: rows.length >= TASK_COST_QUERY_LIMIT });
+			}
 			case "metrics.prune": {
 				const before = input["before"];
 				if (typeof before !== "number") throw new Error("before is required");
+				const force = input["force"] === true;
+				const minCutoff = Date.now() - PRUNE_MIN_AGE_MS;
+				if (!force && before > minCutoff) {
+					throw new Error(`refusing to prune metrics newer than ${new Date(minCutoff).toISOString()} without force: true (this looked like it could delete recent or live data)`);
+				}
 				return { deleted: this.metrics.pruneBefore(before) };
 			}
 			case "benchmark.refresh": return this.benchmarks.refresh(input["force"] === true);
@@ -181,19 +245,16 @@ export interface JittorAppOptions {
 	maxBodyBytes?: number;
 }
 
-function authorized(request: Request, token: string): boolean {
-	return request.headers.get("authorization") === `Bearer ${token}`;
-}
-
+/**
+ * Bearer-check and the trivial health/ready/not-found responses now delegate to
+ * `@danypops/daemon-kit/http` (the same handful of lines every daemon's service.ts hand-rolled).
+ * The response-size guard below stays jittor-specific: daemon-kit's `jsonResponse` is intentionally
+ * unbounded (it has no operation dispatch of its own to guard), while jittor's `/api/v1/ops` can
+ * return arbitrarily large query results that must be capped (see SERVICE_MAX_RESPONSE_BYTES).
+ */
 function json(value: unknown, status = 200): Response {
 	const body = JSON.stringify(value);
-	if (new TextEncoder().encode(body).byteLength > SERVICE_MAX_RESPONSE_BYTES) {
-		const error = JSON.stringify({ error: "response too large" });
-		return new Response(error, {
-			status: 413,
-			headers: { "content-type": "application/json", "content-length": String(new TextEncoder().encode(error).byteLength) },
-		});
-	}
+	if (new TextEncoder().encode(body).byteLength > SERVICE_MAX_RESPONSE_BYTES) return errorResponse("response too large", 413);
 	return new Response(body, {
 		status,
 		headers: { "content-type": "application/json", "content-length": String(new TextEncoder().encode(body).byteLength) },
@@ -204,19 +265,16 @@ export function createApp(options: JittorAppOptions): { fetch(request: Request):
 	const maxBodyBytes = options.maxBodyBytes ?? SERVICE_MAX_BODY_BYTES;
 	return {
 		async fetch(request: Request): Promise<Response> {
-			if (!authorized(request, options.token)) return json({ error: "unauthorized" }, 401);
+			if (!requireBearerToken(request, options.token)) return errorResponse("unauthorized", 401);
 			const url = new URL(request.url);
-			if (request.method === "GET" && url.pathname === "/health") return json({ ok: true, version: VERSION });
-			if (request.method === "GET" && url.pathname === "/ready") {
-				const ready = options.service.ready();
-				return json({ ready }, ready ? 200 : 503);
-			}
+			if (request.method === "GET" && url.pathname === "/health") return healthResponse(VERSION);
+			if (request.method === "GET" && url.pathname === "/ready") return readyResponse(options.service.ready());
 			if (request.method === "GET" && url.pathname === "/api/v1/ops") return json({ operations: options.service.operationNames() });
-			if (request.method !== "POST" || url.pathname !== "/api/v1/ops") return json({ error: "not found" }, 404);
+			if (request.method !== "POST" || url.pathname !== "/api/v1/ops") return errorResponse("not found", 404);
 			const contentLength = Number(request.headers.get("content-length") ?? 0);
-			if (contentLength > maxBodyBytes) return json({ error: "payload too large" }, 413);
+			if (contentLength > maxBodyBytes) return errorResponse("payload too large", 413);
 			const text = await request.text();
-			if (new TextEncoder().encode(text).byteLength > maxBodyBytes) return json({ error: "payload too large" }, 413);
+			if (new TextEncoder().encode(text).byteLength > maxBodyBytes) return errorResponse("payload too large", 413);
 			try {
 				const body = JSON.parse(text) as { op?: unknown; input?: unknown };
 				if (typeof body.op !== "string") throw new Error("op is required");

package/src/state.ts

@@ -1,81 +1,55 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { randomBytes } from "node:crypto";
+/**
+ * Jittor's XDG paths/token/handle layout, now delegating to `@danypops/daemon-kit/paths` --
+ * the shared substrate factored out after jittor's own state.ts and web-spider-daemon's were
+ * found byte-identical (see daemon-kit's README). Kept as a thin jittor-named wrapper (same
+ * exported function names/signatures as before) so every existing call site (daemon.ts,
+ * client.ts, cli.ts, and their tests) is untouched by this migration.
+ */
+import {
+	ensureAuthToken as ensureDaemonKitAuthToken,
+	readDaemonHandle as readDaemonKitHandle,
+	removeDaemonHandle as removeDaemonKitHandle,
+	resolveDaemonPaths,
+	writeDaemonHandle as writeDaemonKitHandle,
+	type DaemonHandle,
+	type DaemonPaths,
+	type PathEnvironment,
+} from "@danypops/daemon-kit/paths";
 import {
 	DATABASE_FILENAME,
 	HANDLE_FILENAME,
 	JITTOR_STATE_DIRECTORY,
-	LOOPBACK_HOST,
 	SYSTEMD_UNIT_NAME,
 	TOKEN_FILENAME,
 } from "./constants.ts";
 
-export interface JittorPaths {
-	database: string;
-	token: string;
-	handle: string;
-	systemdUnit: string;
-}
+export type JittorPaths = DaemonPaths;
+export type { DaemonHandle, PathEnvironment };
 
-export interface DaemonHandle {
-	host: typeof LOOPBACK_HOST;
-	port: number;
-	pid: number;
-}
-
-export interface PathEnvironment {
-	env?: Record<string, string | undefined>;
-	home?: string;
-	uid?: number;
-}
+const JITTOR_PATH_NAMES = {
+	stateDirectoryName: JITTOR_STATE_DIRECTORY,
+	databaseFilename: DATABASE_FILENAME,
+	tokenFilename: TOKEN_FILENAME,
+	handleFilename: HANDLE_FILENAME,
+	systemdUnitName: SYSTEMD_UNIT_NAME,
+};
 
 export function resolveJittorPaths(options: PathEnvironment = {}): JittorPaths {
-	const env = options.env ?? process.env;
-	const home = options.home ?? homedir();
-	const uid = options.uid ?? process.getuid?.() ?? 0;
-	const dataHome = env["XDG_DATA_HOME"] ?? join(home, ".local", "share");
-	const stateHome = env["XDG_STATE_HOME"] ?? join(home, ".local", "state");
-	const runtimeHome = env["XDG_RUNTIME_DIR"] ?? join("/run", "user", String(uid));
-	const configHome = env["XDG_CONFIG_HOME"] ?? join(home, ".config");
-	return {
-		database: join(dataHome, JITTOR_STATE_DIRECTORY, DATABASE_FILENAME),
-		token: join(stateHome, JITTOR_STATE_DIRECTORY, TOKEN_FILENAME),
-		handle: join(runtimeHome, JITTOR_STATE_DIRECTORY, HANDLE_FILENAME),
-		systemdUnit: join(configHome, "systemd", "user", SYSTEMD_UNIT_NAME),
-	};
+	return resolveDaemonPaths(JITTOR_PATH_NAMES, options);
 }
 
 export function ensureAuthToken(paths: JittorPaths = resolveJittorPaths()): string {
-	mkdirSync(dirname(paths.token), { recursive: true, mode: 0o700 });
-	if (existsSync(paths.token)) {
-		chmodSync(paths.token, 0o600);
-		const token = readFileSync(paths.token, "utf8").trim();
-		if (!/^[a-f0-9]{64}$/.test(token)) throw new Error("invalid Jittor authentication token");
-		return token;
-	}
-	const token = randomBytes(32).toString("hex");
-	writeFileSync(paths.token, `${token}\n`, { mode: 0o600 });
-	return token;
+	return ensureDaemonKitAuthToken(paths.token, "Jittor");
 }
 
 export function writeDaemonHandle(paths: JittorPaths, handle: DaemonHandle): void {
-	mkdirSync(dirname(paths.handle), { recursive: true, mode: 0o700 });
-	const temporary = `${paths.handle}.${process.pid}.tmp`;
-	writeFileSync(temporary, `${JSON.stringify(handle)}\n`, { mode: 0o600 });
-	renameSync(temporary, paths.handle);
+	writeDaemonKitHandle(paths.handle, handle);
 }
 
 export function readDaemonHandle(paths: JittorPaths = resolveJittorPaths()): DaemonHandle | null {
-	try {
-		const value = JSON.parse(readFileSync(paths.handle, "utf8")) as Partial<DaemonHandle>;
-		if (value.host !== LOOPBACK_HOST || !Number.isInteger(value.port) || value.port! < 1 || value.port! > 65_535 || !Number.isInteger(value.pid)) return null;
-		return value as DaemonHandle;
-	} catch {
-		return null;
-	}
+	return readDaemonKitHandle(paths.handle);
 }
 
 export function removeDaemonHandle(paths: JittorPaths = resolveJittorPaths()): void {
-	rmSync(paths.handle, { force: true });
+	removeDaemonKitHandle(paths.handle);
 }

package/src/version.ts

@@ -1,16 +1,4 @@
-import { readFileSync } from "node:fs";
-
-function packageVersion(): string {
-	const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as unknown;
-	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
-		throw new Error("Jittor package manifest must be an object");
-	}
-	const version = (manifest as Record<string, unknown>)["version"];
-	if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
-		throw new Error("Jittor package manifest has an invalid version");
-	}
-	return version;
-}
+import { readPackageVersion } from "@danypops/daemon-kit/version";
 
 /** Runtime package version; package.json is the single release source of truth. */
-export const VERSION = packageVersion();
+export const VERSION = readPackageVersion(new URL("../package.json", import.meta.url), "Jittor");