@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/dist/sdk/usage/analytics.d.ts

@@ -0,0 +1,20 @@
+import { type PriceRates } from "../sessions/pricing.js";
+import type { UsageFilter, UsagePeriod, UsageSummary } from "./types.js";
+/** A price lookup, injected so tests never load Pi's catalogue. */
+export type RatesLookup = (provider: string, model: string) => Promise<PriceRates | null>;
+/** The local-day boundaries `period` covers, expressed as UTC instants. */
+export declare function periodRange(period: UsagePeriod, offsetMinutes: number, now?: Date): {
+    from: string | null;
+    to: string;
+};
+export interface SummaryInput {
+    root: string;
+    filter: UsageFilter;
+    period: UsagePeriod;
+    timezoneOffsetMinutes: number;
+    /** Model labels are `provider/model`; only accounts need a lookup. */
+    accountLabel?: (accountId: string) => string;
+    rates?: RatesLookup;
+    now?: Date;
+}
+export declare function summarize(input: SummaryInput): Promise<UsageSummary>;

package/dist/sdk/usage/analytics.js

@@ -0,0 +1,151 @@
+import { all, withIndex } from "../core/index.js";
+import { costAt } from "../sessions/pricing.js";
+import { lastIndexedAt } from "./ledger.js";
+const ROW_LIMIT = 10;
+const DAY_LIMIT = 400;
+const UNPRICED_LIMIT = 40;
+const zero = (value) => value ?? 0;
+const round = (value, places = 6) => Math.round(value * 10 ** places) / 10 ** places;
+function totals(row, estimated = 0) {
+    const input = zero(row?.input);
+    const cacheRead = zero(row?.cacheRead);
+    const cacheWrite = zero(row?.cacheWrite);
+    const cost = row?.cost == null && !estimated ? null : round(zero(row?.cost) + estimated);
+    const cached = cacheRead + input + cacheWrite;
+    return {
+        requests: zero(row?.requests),
+        inputTokens: input,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+        outputTokens: zero(row?.output),
+        reasoningTokens: zero(row?.reasoning),
+        costUsd: cost,
+        estimatedCostUsd: estimated ? round(estimated) : 0,
+        unpricedRequests: zero(row?.unpriced),
+        avgTtftMs: row?.ttft == null ? null : Math.round(row.ttft),
+        avgDurationMs: row?.duration == null ? null : Math.round(row.duration),
+        cacheHitPercent: cached ? Math.round((cacheRead / cached) * 1000) / 10 : null
+    };
+}
+/** The local-day boundaries `period` covers, expressed as UTC instants. */
+export function periodRange(period, offsetMinutes, now = new Date()) {
+    const to = now.toISOString();
+    if (period === 'all')
+        return { from: null, to };
+    const shifted = new Date(now.getTime() + offsetMinutes * 60_000);
+    const midnight = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate());
+    const days = period === 'today' ? 0 : period === '7d' ? 6 : 29;
+    return { from: new Date(midnight - days * 86_400_000 - offsetMinutes * 60_000).toISOString(), to };
+}
+function where(filter, from, to) {
+    const clauses = ['at < ?'];
+    const params = [to];
+    if (from) {
+        clauses.push('at >= ?');
+        params.push(from);
+    }
+    if (filter.session) {
+        clauses.push('session_id = ?');
+        params.push(filter.session);
+    }
+    if (filter.account) {
+        clauses.push('account_id = ?');
+        params.push(filter.account);
+    }
+    if (filter.project) {
+        clauses.push('project_id = ?');
+        params.push(filter.project);
+    }
+    return { sql: clauses.join(' AND '), params };
+}
+const SUM = `COUNT(*) AS requests, SUM(input_tokens) AS input, SUM(cache_read_tokens) AS cacheRead,
+  SUM(cache_write_tokens) AS cacheWrite, SUM(output_tokens) AS output, SUM(reasoning_tokens) AS reasoning,
+  SUM(cost_usd) AS cost, SUM(CASE WHEN cost_usd IS NULL THEN 1 ELSE 0 END) AS unpriced,
+  AVG(ttft_ms) AS ttft, AVG(duration_ms) AS duration`;
+function grouped(database, column, clause, params, limit) {
+    return all(database, `SELECT ${column} AS key, ${SUM} FROM usage_requests WHERE ${clause}
+     GROUP BY ${column} ORDER BY SUM(COALESCE(input_tokens,0)+COALESCE(cache_read_tokens,0)+COALESCE(cache_write_tokens,0)+COALESCE(output_tokens,0)) DESC
+     LIMIT ${limit}`, ...params).map((row) => ({ key: row.key ?? '', values: row }));
+}
+function modelKey(provider, model) {
+    return `${provider ?? 'unknown'}/${model ?? 'unknown'}`;
+}
+/** Estimates the cost of the requests a provider did not price, grouped by model. */
+async function estimate(database, clause, params, rates) {
+    const rows = all(database, `SELECT provider, model, ${SUM} FROM usage_requests
+     WHERE ${clause} AND cost_usd IS NULL GROUP BY provider, model LIMIT ${UNPRICED_LIMIT}`, ...params);
+    const estimates = new Map();
+    for (const row of rows) {
+        if (!row.model)
+            continue;
+        const table = await rates(row.provider ?? '', row.model).catch(() => null);
+        if (!table)
+            continue;
+        const cost = costAt(table, {
+            inputTokens: zero(row.input),
+            outputTokens: zero(row.output),
+            cacheReadTokens: zero(row.cacheRead),
+            cacheWriteTokens: zero(row.cacheWrite)
+        });
+        const key = modelKey(row.provider, row.model);
+        const previous = estimates.get(key) ?? { cost: 0, requests: 0 };
+        estimates.set(key, { cost: previous.cost + cost, requests: previous.requests + zero(row.requests) });
+    }
+    return estimates;
+}
+export async function summarize(input) {
+    const offset = Number.isFinite(input.timezoneOffsetMinutes) ? Math.max(-840, Math.min(840, Math.trunc(input.timezoneOffsetMinutes))) : 0;
+    const { from, to } = periodRange(input.period, offset, input.now ?? new Date());
+    const { sql: clause, params } = where(input.filter, from, to);
+    const shift = `${offset >= 0 ? '+' : ''}${offset} minutes`;
+    const label = input.accountLabel ?? ((id) => id.slice(0, 8));
+    const summary = withIndex(input.root, (database) => {
+        const total = all(database, `SELECT ${SUM} FROM usage_requests WHERE ${clause}`, ...params)[0];
+        const days = all(database, `SELECT date(at, ?) AS day, ${SUM} FROM usage_requests WHERE ${clause}
+       GROUP BY day ORDER BY day DESC LIMIT ${DAY_LIMIT}`, shift, ...params);
+        return {
+            total,
+            days: days.reverse(),
+            byModel: grouped(database, "COALESCE(provider,'unknown') || '/' || COALESCE(model,'unknown')", clause, params, ROW_LIMIT + 1),
+            byProvider: grouped(database, "COALESCE(provider,'unknown')", clause, params, ROW_LIMIT + 1),
+            byAccount: grouped(database, "COALESCE(account_id,'')", clause, params, ROW_LIMIT + 1),
+            bySession: grouped(database, 'session_id', clause, params, ROW_LIMIT + 1)
+        };
+    });
+    const estimates = input.rates && zero(summary.total?.unpriced)
+        ? await withIndex(input.root, (database) => estimate(database, clause, params, input.rates))
+        : new Map();
+    const estimated = [...estimates.values()].reduce((sum, entry) => sum + entry.cost, 0);
+    const row = (key, values, labelText, detail) => {
+        const estimateEntry = estimates.get(key);
+        return { key, label: labelText, detail, ...totals(values, estimateEntry?.cost ?? 0) };
+    };
+    const modelRows = summary.byModel.map((entry) => row(entry.key, entry.values, entry.key, null));
+    const truncate = (entries) => entries.length > ROW_LIMIT;
+    const accountRows = summary.byAccount.slice(0, ROW_LIMIT).map((entry) => row(entry.key, entry.values, entry.key ? label(entry.key) : 'No account', null));
+    const sessionRows = summary.bySession.slice(0, ROW_LIMIT).map((entry) => row(entry.key, entry.values, entry.key.slice(0, 12), null));
+    const days = summary.days.map((entry) => ({
+        day: entry.day,
+        requests: zero(entry.requests),
+        inputTokens: zero(entry.input),
+        cacheReadTokens: zero(entry.cacheRead),
+        outputTokens: zero(entry.output),
+        costUsd: entry.cost == null ? null : round(entry.cost)
+    }));
+    return {
+        scope: input.filter.session ? 'session' : input.filter.project ? 'project' : input.filter.account ? 'account' : 'all',
+        period: input.period,
+        from,
+        to,
+        timezoneOffsetMinutes: offset,
+        generatedAt: new Date().toISOString(),
+        totals: totals(summary.total, estimated),
+        byDay: days,
+        byModel: modelRows.slice(0, ROW_LIMIT),
+        byProvider: summary.byProvider.slice(0, ROW_LIMIT).map((entry) => row(entry.key, entry.values, entry.key, null)),
+        byAccount: accountRows,
+        bySession: sessionRows,
+        truncated: truncate(summary.byModel) || truncate(summary.byProvider) || truncate(summary.byAccount) || truncate(summary.bySession),
+        lastIndexedAt: lastIndexedAt(input.root)
+    };
+}

package/dist/sdk/usage/ledger.d.ts

@@ -0,0 +1,38 @@
+import { type RunEvent, type RunRecord } from "../sessions/contracts.js";
+export interface UsageRow {
+    runId: string;
+    sequence: number;
+    requestIndex: number;
+    at: string;
+    day: string;
+    accountId: string | null;
+    projectId: string | null;
+    sessionId: string;
+    agentId: string | null;
+    mode: string;
+    trigger: string | null;
+    provider: string | null;
+    model: string | null;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    costUsd: number | null;
+    costSource: string | null;
+    contextTokens: number | null;
+    contextWindow: number | null;
+    durationMs: number | null;
+    ttftMs: number | null;
+    requests: number;
+}
+/** One row per request: the event's own `request`, or the run's totals when a provider reported only those. */
+export declare function usageRowsFor(run: RunRecord, events: readonly RunEvent[]): UsageRow[];
+/** Indexes one run's usage. Idempotent, and safe to call when the index is unavailable. */
+export declare function indexRunUsage(root: string, runId: string): boolean;
+/** Indexes every run the ledger has not seen yet. Returns how many runs it added. */
+export declare function syncUsage(root: string): number;
+/** The ledger's last write, or null when it holds nothing. */
+export declare function lastIndexedAt(root: string): string | null;
+/** Run ids the ledger knows, for diagnostics and tests. */
+export declare function indexedRuns(root: string): string[];

package/dist/sdk/usage/ledger.js

@@ -0,0 +1,142 @@
+import { all, run as execute, transaction, withIndex } from "../core/index.js";
+import { now } from "../core/fs.js";
+import { readAllRuns } from "../sessions/runIndex.js";
+import { findRun, readEvents } from "../sessions/runStore.js";
+import { usagePayloadSchema } from "../sessions/contracts.js";
+const number = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const optionalNumber = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
+const text = (value) => (typeof value === 'string' && value ? value : null);
+/** One row per request: the event's own `request`, or the run's totals when a provider reported only those. */
+export function usageRowsFor(run, events) {
+    const rows = [];
+    let lastTotals = null;
+    let lastTotalsAt = null;
+    for (const event of events) {
+        if (event.type !== 'usage.updated')
+            continue;
+        const parsed = usagePayloadSchema.safeParse(event.payload);
+        if (!parsed.success)
+            continue;
+        const payload = parsed.data;
+        lastTotals = payload;
+        lastTotalsAt = event.timestamp;
+        const request = payload.request;
+        // Without a per-request update the event's fields are cumulative; only the last one may count.
+        if (!request)
+            continue;
+        rows.push({
+            runId: run.id,
+            sequence: event.sequence,
+            requestIndex: request?.index ?? payload.requests ?? rows.length + 1,
+            at: event.timestamp,
+            day: event.timestamp.slice(0, 10),
+            accountId: run.accountId ?? null,
+            projectId: run.projectId ?? null,
+            sessionId: run.sessionId,
+            agentId: run.agentId ?? null,
+            mode: run.mode ?? 'chat',
+            trigger: run.trigger ?? null,
+            provider: request?.provider ?? payload.provider ?? null,
+            model: request?.model ?? payload.model ?? null,
+            inputTokens: number(request?.inputTokens ?? payload.inputTokens),
+            cacheReadTokens: number(request?.cacheReadTokens ?? payload.cacheReadTokens),
+            cacheWriteTokens: number(request?.cacheWriteTokens ?? payload.cacheWriteTokens),
+            outputTokens: number(request?.outputTokens ?? payload.outputTokens),
+            reasoningTokens: number(request?.reasoningTokens ?? payload.reasoningTokens),
+            costUsd: optionalNumber(request?.costUsd ?? payload.costUsd),
+            costSource: text(request?.costSource ?? payload.costSource),
+            contextTokens: optionalNumber(payload.contextTokens),
+            contextWindow: optionalNumber(payload.contextWindow),
+            durationMs: optionalNumber(request?.durationMs),
+            ttftMs: optionalNumber(request?.ttftMs),
+            requests: number(payload.requests)
+        });
+    }
+    // A run whose provider reported totals but no per-request update (an older record) still counts once.
+    if (!rows.length && lastTotals) {
+        rows.push({
+            runId: run.id, sequence: 0, requestIndex: lastTotals.requests ?? 1,
+            at: lastTotalsAt ?? run.endedAt ?? run.startedAt, day: (lastTotalsAt ?? run.endedAt ?? run.startedAt).slice(0, 10),
+            accountId: run.accountId ?? null, projectId: run.projectId ?? null, sessionId: run.sessionId,
+            agentId: run.agentId ?? null, mode: run.mode ?? 'chat', trigger: run.trigger ?? null,
+            provider: lastTotals.provider ?? null, model: lastTotals.model ?? null,
+            inputTokens: number(lastTotals.inputTokens), cacheReadTokens: number(lastTotals.cacheReadTokens),
+            cacheWriteTokens: number(lastTotals.cacheWriteTokens), outputTokens: number(lastTotals.outputTokens),
+            reasoningTokens: number(lastTotals.reasoningTokens), costUsd: optionalNumber(lastTotals.costUsd),
+            costSource: text(lastTotals.costSource), contextTokens: optionalNumber(lastTotals.contextTokens),
+            contextWindow: optionalNumber(lastTotals.contextWindow), durationMs: null, ttftMs: null,
+            requests: number(lastTotals.requests)
+        });
+    }
+    return rows;
+}
+function write(database, run, rows) {
+    execute(database, 'DELETE FROM usage_requests WHERE run_id = ?', run.id);
+    for (const row of rows) {
+        execute(database, `INSERT INTO usage_requests (run_id, sequence, request_index, at, day, account_id, project_id, session_id, agent_id, mode, trigger,
+         provider, model, input_tokens, cache_read_tokens, cache_write_tokens, output_tokens, reasoning_tokens,
+         cost_usd, cost_source, context_tokens, context_window, duration_ms, ttft_ms, requests)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, row.runId, row.sequence, row.requestIndex, row.at, row.day, row.accountId, row.projectId, row.sessionId, row.agentId, row.mode, row.trigger, row.provider, row.model, row.inputTokens, row.cacheReadTokens, row.cacheWriteTokens, row.outputTokens, row.reasoningTokens, row.costUsd, row.costSource, row.contextTokens, row.contextWindow, row.durationMs, row.ttftMs, row.requests);
+    }
+    execute(database, 'INSERT OR REPLACE INTO usage_indexed (run_id, indexed_at, rows) VALUES (?, ?, ?)', run.id, now(), rows.length);
+}
+/** Indexes one run's usage. Idempotent, and safe to call when the index is unavailable. */
+export function indexRunUsage(root, runId) {
+    const run = findRun(root, runId);
+    if (!run)
+        return false;
+    let events;
+    try {
+        events = readEvents(root, runId);
+    }
+    catch {
+        return false;
+    }
+    const rows = usageRowsFor(run, events);
+    try {
+        withIndex(root, (database) => transaction(database, () => write(database, run, rows)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Indexes every run the ledger has not seen yet. Returns how many runs it added. */
+export function syncUsage(root) {
+    const indexed = new Set();
+    try {
+        withIndex(root, (database) => {
+            for (const row of all(database, 'SELECT run_id FROM usage_indexed'))
+                indexed.add(row.run_id);
+        });
+    }
+    catch {
+        return 0;
+    }
+    let added = 0;
+    for (const record of readAllRuns(root)) {
+        if (indexed.has(record.id))
+            continue;
+        if (indexRunUsage(root, record.id))
+            added += 1;
+    }
+    return added;
+}
+/** The ledger's last write, or null when it holds nothing. */
+export function lastIndexedAt(root) {
+    try {
+        return withIndex(root, (database) => all(database, 'SELECT MAX(indexed_at) AS at FROM usage_indexed')[0]?.at ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+/** Run ids the ledger knows, for diagnostics and tests. */
+export function indexedRuns(root) {
+    try {
+        return withIndex(root, (database) => all(database, 'SELECT run_id FROM usage_indexed').map((row) => row.run_id));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/sdk/usage/limits/adapters.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderLimitAdapter } from "./types.js";
+export declare const OPENROUTER_ADAPTER: ProviderLimitAdapter;
+export declare const DEEPSEEK_ADAPTER: ProviderLimitAdapter;
+export declare const ANTHROPIC_ADMIN_ADAPTER: ProviderLimitAdapter;
+/** ChatGPT/Codex plan windows and credits, from the account's own usage endpoint. */
+export declare const CODEX_ADAPTER: ProviderLimitAdapter;
+/** OpenCode Go's 5-hour, weekly and monthly subscription windows. */
+export declare const OPENCODE_GO_ADAPTER: ProviderLimitAdapter;
+/** The documented adapter for a provider, when one exists. Headers remain the other source. */
+export declare function adapterFor(provider: string): ProviderLimitAdapter | null;
+export declare const DOCUMENTED_ADAPTERS: readonly ProviderLimitAdapter[];