@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/terminal/service.js

@@ -0,0 +1,455 @@
+import { randomUUID } from 'node:crypto';
+import { startLocalBackend, startSshBackend, TerminalStartError, } from './backends.js';
+import { resolveSshCredentials, sshCredentialProblem, } from './config.js';
+import { createModuleCache } from './modules.js';
+import { TerminalTicketStore } from './tickets.js';
+export class TerminalRequestError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'TerminalRequestError';
+    }
+}
+export const TERMINAL_CLOSE_CODES = Object.freeze({
+    normal: 1000,
+    startFailed: 1011,
+    badRequest: 4400,
+    invalidTicket: 4401,
+    forbidden: 4403,
+    tooManySessions: 4429,
+});
+const MAX_DIMENSION = 1000;
+const MAX_TEXT_FRAME = 4096;
+const MAX_INPUT_FRAME = 1 << 20;
+/** Input queued while the session starts; frames beyond it are dropped. */
+const MAX_PENDING_INPUT = 1 << 20;
+// Output backpressure on the socket's send buffer.
+const PAUSE_BUFFERED = 256 * 1024;
+const RESUME_BUFFERED = 64 * 1024;
+const RESUME_POLL_MS = 25;
+/** Close code of a connection that dropped without a close frame. */
+const ABNORMAL_CLOSURE = 1006;
+/** Terminal tickets, targets and live sessions (ADR 0051). Transport-agnostic. */
+export class TerminalService {
+    #options;
+    #tickets;
+    #modules;
+    #sessions = new Map();
+    #env;
+    #now;
+    #closed = false;
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.now ?? Date.now;
+        this.#tickets = new TerminalTicketStore({ now: this.#now });
+        this.#modules = createModuleCache(options.modules);
+        this.#env = options.env ?? process.env;
+    }
+    get config() {
+        return this.#options.config;
+    }
+    /** Throws `TerminalRequestError(403)` unless the principal may use the terminal. */
+    async requireAuthorized(principal, ip) {
+        if (!principal) {
+            this.#audit({ action: 'terminal.denied', actor: 'anonymous', target: '', outcome: 'denied', ip, detail: { reason: 'unauthenticated' } });
+            throw new TerminalRequestError(401, 'unauthorized', '需要登录');
+        }
+        let allowed = false;
+        try {
+            allowed = (await this.#options.authorize(principal)) === true;
+        }
+        catch {
+            allowed = false;
+        }
+        if (!allowed) {
+            this.#audit({ action: 'terminal.denied', actor: principal.id, target: '', outcome: 'denied', ip, detail: { reason: 'forbidden' } });
+            throw new TerminalRequestError(403, 'forbidden', '需要 ops.terminal 权限');
+        }
+        return principal;
+    }
+    async listTargets() {
+        const pty = await this.#modules.pty();
+        const targets = [{
+                id: 'local',
+                kind: 'local',
+                label: '本机 Shell',
+                available: pty.ok,
+                ...(pty.ok ? {} : { reason: pty.reason }),
+            }];
+        if (this.config.ssh.length === 0)
+            return targets;
+        const ssh = await this.#modules.ssh();
+        for (const target of this.config.ssh) {
+            const problem = ssh.ok ? sshCredentialProblem(target, this.#env) : ssh.reason;
+            targets.push({
+                id: target.name,
+                kind: 'ssh',
+                label: `${target.label ?? sshLabel(target)}${target.insecureAcceptAnyHostKey ? '（不安全：未校验主机密钥）' : ''}`,
+                available: problem === undefined,
+                ...(problem === undefined ? {} : { reason: problem }),
+                ...(target.insecureAcceptAnyHostKey ? { insecureHostKey: true } : {}),
+            });
+        }
+        return targets;
+    }
+    async issueTicket(principal, body, ip) {
+        if (this.#closed)
+            throw new TerminalRequestError(404, 'not-found', '终端未启用');
+        const input = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+        const targetId = typeof input.target === 'string' ? input.target : '';
+        const size = parseSize(input.cols ?? 80, input.rows ?? 24);
+        if (!size)
+            throw new TerminalRequestError(400, 'bad-request', `cols / rows 必须是 1–${MAX_DIMENSION} 的整数`);
+        const target = (await this.listTargets()).find((entry) => entry.id === targetId);
+        if (!target)
+            throw new TerminalRequestError(404, 'unknown-target', '未知的终端目标');
+        if (!target.available)
+            throw new TerminalRequestError(409, 'unavailable', target.reason ?? '终端目标不可用');
+        if (this.#sessions.size >= this.config.maxSessions) {
+            throw new TerminalRequestError(429, 'too-many-sessions', `终端会话已达上限（${this.config.maxSessions}）`);
+        }
+        const issued = this.#tickets.issue({ principalId: principal.id, principal, target: target.id, ...size });
+        this.#audit({ action: 'terminal.ticket.issue', actor: principal.id, target: target.id, outcome: 'ok', ip, detail: {} });
+        return issued;
+    }
+    /**
+     * Handles one accepted WebSocket. `presentedPrincipal` is set when the upgrade
+     * also carried a bearer credential; it must then match the ticket's principal.
+     */
+    async handleConnection(socket, presentedPrincipal) {
+        const ip = socket.remoteAddress;
+        // Listen before any await: the peer may leave while authorization or startup is pending.
+        // Frames that arrive before the shell is up (ticket check, PTY / SSH start) are queued and
+        // replayed once it is ready: a client may type or paste right after the socket opens.
+        const connection = {
+            gone: false, pending: [], pendingBytes: 0,
+        };
+        const open = () => !connection.gone;
+        socket.onClose((code) => {
+            connection.gone = true;
+            connection.pending = [];
+            connection.session?.end(code === ABNORMAL_CLOSURE ? 'error' : 'disconnect');
+        });
+        socket.onMessage((data) => {
+            if (connection.session?.backend) {
+                this.#onMessage(connection.session, data, typeof data !== 'string');
+                return;
+            }
+            const bytes = typeof data === 'string' ? Buffer.byteLength(data) : data.byteLength;
+            // Bounded: a peer cannot grow memory before its session exists.
+            if (connection.pendingBytes + bytes > MAX_PENDING_INPUT)
+                return;
+            connection.pendingBytes += bytes;
+            connection.pending.push({ data, bytes });
+        });
+        const ticket = socket.url.searchParams.get('ticket');
+        const consumed = this.#tickets.consume(ticket, presentedPrincipal?.id);
+        if (!consumed.ok) {
+            this.#audit({ action: 'terminal.denied', actor: presentedPrincipal?.id ?? 'anonymous', target: '', outcome: 'denied', ip, detail: { reason: `ticket-${consumed.reason}` } });
+            reject(socket, TERMINAL_CLOSE_CODES.invalidTicket, 'invalid-ticket', '终端票据无效或已过期', open);
+            return;
+        }
+        const { principal, target: targetId, cols, rows } = consumed.grant;
+        try {
+            // Re-check: the principal may have been revoked since the ticket was issued.
+            await this.requireAuthorized(principal, ip);
+        }
+        catch {
+            reject(socket, TERMINAL_CLOSE_CODES.forbidden, 'forbidden', '需要 ops.terminal 权限', open);
+            return;
+        }
+        if (this.#closed) {
+            reject(socket, TERMINAL_CLOSE_CODES.forbidden, 'disabled', '终端未启用', open);
+            return;
+        }
+        if (connection.gone)
+            return;
+        if (this.#sessions.size >= this.config.maxSessions) {
+            this.#audit({ action: 'terminal.denied', actor: principal.id, target: targetId, outcome: 'denied', ip, detail: { reason: 'too-many-sessions' } });
+            reject(socket, TERMINAL_CLOSE_CODES.tooManySessions, 'too-many-sessions', `终端会话已达上限（${this.config.maxSessions}）`, open);
+            return;
+        }
+        const sshTarget = targetId === 'local' ? undefined : this.config.ssh.find((entry) => entry.name === targetId);
+        if (targetId !== 'local' && !sshTarget) {
+            reject(socket, TERMINAL_CLOSE_CODES.badRequest, 'unknown-target', '未知的终端目标', open);
+            return;
+        }
+        const kind = sshTarget ? 'ssh' : 'local';
+        const info = Object.freeze({
+            sessionId: randomUUID(),
+            principalId: principal.id,
+            target: targetId,
+            kind,
+            startedAt: this.#now(),
+        });
+        const live = this.#createSession(info, principal, socket, open, ip);
+        connection.session = live;
+        this.#sessions.set(info.sessionId, live);
+        let resumeTimer;
+        const resumeWhenDrained = () => {
+            if (live.ended || !open()) {
+                clearInterval(resumeTimer);
+                resumeTimer = undefined;
+                return;
+            }
+            if (socket.bufferedAmount > RESUME_BUFFERED)
+                return;
+            clearInterval(resumeTimer);
+            resumeTimer = undefined;
+            live.backend?.resume();
+        };
+        const events = {
+            onData: (chunk) => {
+                if (live.ended || !open())
+                    return;
+                // Output is always a binary frame; control messages are text.
+                socket.send(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+                if (!resumeTimer && socket.bufferedAmount >= PAUSE_BUFFERED) {
+                    live.backend?.pause();
+                    resumeTimer = setInterval(resumeWhenDrained, RESUME_POLL_MS);
+                    resumeTimer.unref?.();
+                }
+            },
+            onExit: (exit) => live.end('process-exit', exit),
+        };
+        let backend;
+        try {
+            backend = sshTarget
+                ? await this.#startSsh(sshTarget, { cols, rows }, events)
+                : await this.#startLocal({ cols, rows }, events);
+        }
+        catch (error) {
+            const code = error instanceof TerminalStartError ? error.code : 'start-failed';
+            // Only our own start errors are described to the client; others stay in the log.
+            const message = error instanceof TerminalStartError ? error.message : '终端启动失败';
+            this.#sessions.delete(info.sessionId);
+            live.ended = true;
+            this.#audit({ action: 'terminal.session.start', actor: principal.id, target: targetId, outcome: 'error', ip, detail: { sessionId: info.sessionId, kind, code } });
+            this.#options.logger?.warn?.(`terminal start failed | target=${targetId} | code=${code}`);
+            reject(socket, TERMINAL_CLOSE_CODES.startFailed, code, message, open);
+            return;
+        }
+        if (live.ended) {
+            // Disconnected (or revoked) while starting.
+            backend.kill();
+            return;
+        }
+        live.backend = backend;
+        this.#audit({ action: 'terminal.session.start', actor: principal.id, target: targetId, outcome: 'ok', ip, detail: { sessionId: info.sessionId, kind } });
+        sendControl(socket, { type: 'ready', sessionId: info.sessionId, target: targetId, kind, cols, rows }, open);
+        this.#resetIdle(live);
+        const queued = connection.pending;
+        connection.pending = [];
+        connection.pendingBytes = 0;
+        for (const frame of queued)
+            this.#onMessage(live, frame.data, typeof frame.data !== 'string');
+    }
+    /** Ends every session (and pending ticket) of a principal. Returns the number of sessions ended. */
+    terminatePrincipal(principalId, reason = 'revoked') {
+        this.#tickets.revokePrincipal(principalId);
+        let count = 0;
+        for (const session of [...this.#sessions.values()]) {
+            if (session.principal.id !== principalId)
+                continue;
+            session.end(reason);
+            count += 1;
+        }
+        return count;
+    }
+    /** Ends all sessions; with `final`, refuses further tickets and connections. */
+    closeAll(reason = 'disabled', final = false) {
+        if (final)
+            this.#closed = true;
+        this.#tickets.clear();
+        for (const session of [...this.#sessions.values()])
+            session.end(reason);
+    }
+    sessions() {
+        return [...this.#sessions.values()].map((session) => session.info);
+    }
+    #createSession(info, principal, socket, open, ip) {
+        const session = {
+            info,
+            principal,
+            socket,
+            open,
+            ...(ip ? { ip } : {}),
+            ended: false,
+            end: (reason, exit) => {
+                if (session.ended)
+                    return;
+                session.ended = true;
+                if (session.idleTimer)
+                    clearTimeout(session.idleTimer);
+                this.#sessions.delete(info.sessionId);
+                session.backend?.kill();
+                if (open()) {
+                    sendControl(socket, {
+                        type: 'exit',
+                        reason,
+                        code: exit?.code ?? null,
+                        ...(exit?.signal !== undefined ? { signal: exit.signal } : {}),
+                    }, open);
+                    try {
+                        socket.close(TERMINAL_CLOSE_CODES.normal, reason);
+                    }
+                    catch {
+                        /* already closing */
+                    }
+                }
+                if (!session.backend)
+                    return; // never started; start failure is audited separately
+                this.#audit({
+                    action: 'terminal.session.end',
+                    actor: principal.id,
+                    target: info.target,
+                    outcome: 'ok',
+                    ip,
+                    detail: {
+                        sessionId: info.sessionId,
+                        kind: info.kind,
+                        durationMs: Math.max(0, this.#now() - info.startedAt),
+                        exitCode: exit?.code ?? null,
+                        reason,
+                    },
+                });
+            },
+        };
+        return session;
+    }
+    #onMessage(session, data, isBinary) {
+        if (session.ended || !session.backend)
+            return;
+        const buffer = toBuffer(data);
+        if (!buffer)
+            return;
+        if (isBinary) {
+            if (buffer.length > MAX_INPUT_FRAME) {
+                sendControl(session.socket, { type: 'error', code: 'frame-too-large', message: '输入帧过大' }, session.open);
+                return;
+            }
+            this.#resetIdle(session);
+            session.backend.write(buffer);
+            return;
+        }
+        if (buffer.length > MAX_TEXT_FRAME) {
+            sendControl(session.socket, { type: 'error', code: 'bad-message', message: '控制消息过大' }, session.open);
+            return;
+        }
+        let message;
+        try {
+            const parsed = JSON.parse(buffer.toString('utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('not an object');
+            message = parsed;
+        }
+        catch {
+            sendControl(session.socket, { type: 'error', code: 'bad-message', message: '控制消息不是 JSON 对象' }, session.open);
+            return;
+        }
+        if (message.type === 'resize') {
+            const size = parseSize(message.cols, message.rows);
+            if (!size) {
+                sendControl(session.socket, { type: 'error', code: 'bad-message', message: `cols / rows 必须是 1–${MAX_DIMENSION} 的整数` }, session.open);
+                return;
+            }
+            session.backend.resize(size);
+            return;
+        }
+        if (message.type === 'ping') {
+            // Keep-alive only: does not reset the idle timer (idle means no input).
+            sendControl(session.socket, { type: 'pong' }, session.open);
+            return;
+        }
+        sendControl(session.socket, { type: 'error', code: 'bad-message', message: '未知的控制消息' }, session.open);
+    }
+    #resetIdle(session) {
+        const seconds = this.config.idleTimeout;
+        if (seconds <= 0)
+            return;
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        session.idleTimer = setTimeout(() => session.end('idle-timeout'), seconds * 1000);
+        session.idleTimer.unref?.();
+    }
+    async #startLocal(size, events) {
+        const pty = await this.#modules.pty();
+        if (!pty.ok)
+            throw new TerminalStartError('unavailable', pty.reason);
+        return startLocalBackend(pty.module, { shell: this.config.shell, cwd: this.config.cwd, env: this.#env }, size, events);
+    }
+    async #startSsh(target, size, events) {
+        const ssh = await this.#modules.ssh();
+        if (!ssh.ok)
+            throw new TerminalStartError('unavailable', ssh.reason);
+        let credentials;
+        try {
+            credentials = await resolveSshCredentials(target, {
+                env: this.#env,
+                projectRoot: this.#options.projectRoot,
+                ...(this.#options.readFile ? { readFile: this.#options.readFile } : {}),
+            });
+        }
+        catch (error) {
+            throw new TerminalStartError('credentials-unavailable', error instanceof Error ? error.message : String(error));
+        }
+        return startSshBackend(ssh.module, target, credentials, size, events, {
+            onHostKey: (fingerprint) => {
+                if (target.insecureAcceptAnyHostKey) {
+                    this.#options.logger?.warn?.(`terminal ssh ${target.name} host key ${fingerprint} accepted WITHOUT verification (insecureAcceptAnyHostKey); pin it with hostFingerprint`);
+                }
+            },
+        });
+    }
+    #audit(event) {
+        try {
+            const { ip, ...rest } = event;
+            this.#options.audit?.(Object.freeze(ip ? { ...rest, ip } : rest));
+        }
+        catch (error) {
+            this.#options.logger?.warn?.(`terminal audit failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+function sshLabel(target) {
+    return `${target.username}@${target.host}${target.port === 22 ? '' : `:${target.port}`}`;
+}
+function parseSize(cols, rows) {
+    const valid = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_DIMENSION;
+    return valid(cols) && valid(rows) ? { cols, rows } : undefined;
+}
+function toBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    if (ArrayBuffer.isView(data))
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    if (Array.isArray(data) && data.every((item) => Buffer.isBuffer(item)))
+        return Buffer.concat(data);
+    if (typeof data === 'string')
+        return Buffer.from(data, 'utf8');
+    return undefined;
+}
+function sendControl(socket, message, open) {
+    if (!open())
+        return;
+    try {
+        socket.send(JSON.stringify(message));
+    }
+    catch {
+        /* socket closing */
+    }
+}
+function reject(socket, code, errorCode, message, open) {
+    sendControl(socket, { type: 'error', code: errorCode, message }, open);
+    try {
+        socket.close(code, errorCode);
+    }
+    catch {
+        /* already closing */
+    }
+}

package/lib/terminal/tickets.d.ts

@@ -0,0 +1,46 @@
+export declare const TERMINAL_TICKET_TTL_MS = 30000;
+export interface TerminalTicketGrant {
+    readonly principalId: string;
+    /** The full principal the session will run as; `principal.id === principalId`. */
+    readonly principal: {
+        readonly id: string;
+        readonly kind?: string;
+    };
+    readonly target: string;
+    readonly cols: number;
+    readonly rows: number;
+}
+export interface IssuedTerminalTicket {
+    readonly ticket: string;
+    /** Unix epoch milliseconds. */
+    readonly expiresAt: number;
+}
+export type TicketConsumeResult = {
+    readonly ok: true;
+    readonly grant: TerminalTicketGrant;
+} | {
+    readonly ok: false;
+    readonly reason: 'invalid' | 'expired' | 'principal-mismatch';
+};
+/**
+ * One-time WebSocket tickets. Only the SHA-256 of a ticket is stored; lookup is a
+ * map access on that hash, so response timing does not depend on how much of a
+ * guessed ticket matches.
+ */
+export declare class TerminalTicketStore {
+    #private;
+    constructor(options?: {
+        now?: () => number;
+        ttlMs?: number;
+    });
+    issue(grant: TerminalTicketGrant): IssuedTerminalTicket;
+    /**
+     * Consumes a ticket. Any presented ticket is removed on first use, even when the
+     * caller's principal does not match, so a leaked ticket cannot be probed twice.
+     */
+    consume(ticket: string | null | undefined, expectedPrincipalId?: string): TicketConsumeResult;
+    revokePrincipal(principalId: string): number;
+    sweep(): void;
+    clear(): void;
+    get size(): number;
+}

package/lib/terminal/tickets.js

@@ -0,0 +1,76 @@
+import { createHash, randomBytes } from 'node:crypto';
+export const TERMINAL_TICKET_TTL_MS = 30_000;
+const MAX_PENDING_PER_PRINCIPAL = 16;
+/**
+ * One-time WebSocket tickets. Only the SHA-256 of a ticket is stored; lookup is a
+ * map access on that hash, so response timing does not depend on how much of a
+ * guessed ticket matches.
+ */
+export class TerminalTicketStore {
+    #tickets = new Map();
+    #now;
+    #ttlMs;
+    constructor(options = {}) {
+        this.#now = options.now ?? Date.now;
+        this.#ttlMs = options.ttlMs ?? TERMINAL_TICKET_TTL_MS;
+    }
+    issue(grant) {
+        this.sweep();
+        const pending = [...this.#tickets.entries()].filter(([, entry]) => entry.principalId === grant.principalId);
+        // Bound memory per principal: drop the oldest pending ticket.
+        if (pending.length >= MAX_PENDING_PER_PRINCIPAL) {
+            pending.sort((a, b) => a[1].expiresAt - b[1].expiresAt);
+            this.#tickets.delete(pending[0][0]);
+        }
+        const ticket = randomBytes(32).toString('base64url');
+        const expiresAt = this.#now() + this.#ttlMs;
+        this.#tickets.set(hashTicket(ticket), Object.freeze({ ...grant, expiresAt }));
+        return Object.freeze({ ticket, expiresAt });
+    }
+    /**
+     * Consumes a ticket. Any presented ticket is removed on first use, even when the
+     * caller's principal does not match, so a leaked ticket cannot be probed twice.
+     */
+    consume(ticket, expectedPrincipalId) {
+        if (!ticket || ticket.length > 128)
+            return { ok: false, reason: 'invalid' };
+        const key = hashTicket(ticket);
+        const entry = this.#tickets.get(key);
+        if (!entry)
+            return { ok: false, reason: 'invalid' };
+        this.#tickets.delete(key);
+        if (entry.expiresAt <= this.#now())
+            return { ok: false, reason: 'expired' };
+        if (expectedPrincipalId !== undefined && expectedPrincipalId !== entry.principalId) {
+            return { ok: false, reason: 'principal-mismatch' };
+        }
+        const { expiresAt: _expiresAt, ...grant } = entry;
+        return { ok: true, grant: Object.freeze(grant) };
+    }
+    revokePrincipal(principalId) {
+        let removed = 0;
+        for (const [key, entry] of this.#tickets) {
+            if (entry.principalId !== principalId)
+                continue;
+            this.#tickets.delete(key);
+            removed += 1;
+        }
+        return removed;
+    }
+    sweep() {
+        const now = this.#now();
+        for (const [key, entry] of this.#tickets) {
+            if (entry.expiresAt <= now)
+                this.#tickets.delete(key);
+        }
+    }
+    clear() {
+        this.#tickets.clear();
+    }
+    get size() {
+        return this.#tickets.size;
+    }
+}
+function hashTicket(ticket) {
+    return createHash('sha256').update(ticket).digest('hex');
+}

package/lib/terminal.d.ts

@@ -0,0 +1,3 @@
+/** `@zhin.js/gateway/terminal` — Console terminal (ADR 0051). */
+export * from './terminal/index.js';
+export * from './terminal/host.js';

package/lib/terminal.js

@@ -0,0 +1,3 @@
+/** `@zhin.js/gateway/terminal` — Console terminal (ADR 0051). */
+export * from './terminal/index.js';
+export * from './terminal/host.js';

package/lib/usage/aggregate.d.ts

@@ -0,0 +1,87 @@
+export declare const DAY_MS = 86400000;
+export declare const HOUR_MS = 3600000;
+export declare const FIXED_SEGMENTS: ReadonlySet<string>;
+export interface TraceScanOptions {
+    readonly since?: number;
+    readonly until?: number;
+    /** Substring, or `*` glob, matched against the session key. */
+    readonly session?: string;
+}
+export interface TraceScanResult {
+    /** `*.jsonl` files found in the directory. */
+    readonly files: number;
+    /** Files actually opened (not skipped by their date name). */
+    readonly filesRead: number;
+    readonly lines: number;
+    readonly malformed: number;
+}
+export declare function num(value: unknown): number | undefined;
+export declare function sessionMatcher(pattern: string | undefined): (key: string) => boolean;
+/**
+ * Streams every valid trace record in range to `visit`. A missing dir yields an
+ * empty scan. A record is valid with a numeric `started_at` and a string `session_key`.
+ */
+export declare function scanTraces(dir: string, options: TraceScanOptions, visit: (trace: any, startedAt: number) => void): Promise<TraceScanResult>;
+export type UsageBucket = 'hour' | 'day';
+export interface UsageStatsQuery {
+    readonly since: number;
+    readonly until: number;
+    readonly bucket: UsageBucket;
+    readonly session?: string;
+}
+export interface UsageStatsTokens {
+    readonly calls: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    /** cacheReadTokens / inputTokens, 0..1 (0 without input). */
+    readonly cacheShare: number;
+}
+export interface UsageStats {
+    readonly range: {
+        readonly since: number;
+        readonly until: number;
+        readonly bucket: UsageBucket;
+        readonly timeZone: string;
+    };
+    readonly totals: UsageStatsTokens & {
+        readonly turns: number;
+        readonly cacheShareByCall: {
+            readonly p50: number;
+            readonly p90: number;
+        };
+    };
+    readonly byModel: ReadonlyArray<UsageStatsTokens & {
+        readonly provider: string;
+        readonly model: string;
+    }>;
+    readonly bySession: ReadonlyArray<UsageStatsTokens & {
+        readonly sessionKey: string;
+        readonly platform?: string;
+        readonly scope?: string;
+        readonly sceneId?: string;
+        readonly turns: number;
+    }>;
+    readonly series: ReadonlyArray<UsageStatsTokens & {
+        readonly bucketStart: number;
+        readonly byModel: Readonly<Record<string, number>>;
+    }>;
+    readonly segments: {
+        readonly history: number;
+        readonly fixed: number;
+        readonly user: number;
+    };
+    readonly filesRead: number;
+    readonly malformedLines: number;
+}
+export declare const USAGE_STATS_SESSION_LIMIT = 50;
+/** Start of the local hour/day containing `ms`. */
+export declare function bucketStartOf(ms: number, bucket: UsageBucket): number;
+/** `platform:endpoint:scope:sceneId`; other shapes keep whatever parts they have. */
+export declare function parseSessionKey(key: string): {
+    platform?: string;
+    scope?: string;
+    sceneId?: string;
+};
+export declare function buildUsageStats(dir: string, query: UsageStatsQuery): Promise<UsageStats>;