@qilin-agent/cli 0.0.0-stage → 3.1.4

package/lib/types/usage-ledger.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The deployment's per-account token ledger.
+ *
+ * One runtime serves one account and reports each completed Turn of that
+ * account's sessions; the hub appends every report to that account's own file.
+ * A report is one Turn's increment, identified by its session and turn number,
+ * so a repeated report never double counts and a session that spans a month
+ * boundary lands in each month it actually spent in. Files are plain JSON lines
+ * the operator can read.
+ * @module @qilin-agent/cli/usage-ledger
+ */
+/** One account's reported spend for one completed Turn. */
+export interface UsageReport {
+    /** Session the Turn belongs to. */
+    readonly sessionId: string;
+    /** Turn number inside that session; session plus turn identifies the record. */
+    readonly turn: number;
+    /** Prompt tokens billed as uncached input. */
+    readonly inputTokens: number;
+    /** Completion tokens billed for the Turn. */
+    readonly outputTokens: number;
+    /** Prompt tokens the provider served from its cache, when every attempt reported them. */
+    readonly cacheReadTokens?: number;
+    /** Prompt tokens written to that cache, when every attempt reported them. */
+    readonly cacheWriteTokens?: number;
+    /** When the runtime reported it, in epoch milliseconds. */
+    readonly at: number;
+}
+/** A window of report times; an absent bound is unbounded on that side. */
+export interface UsageWindow {
+    /** Earliest report time to include, inclusive. */
+    readonly from?: number | undefined;
+    /** Latest report time to include, inclusive. */
+    readonly to?: number | undefined;
+}
+/** What one account spent across the records inside a window. */
+export interface UsageTotal {
+    /** Sessions with at least one record in the window. */
+    readonly sessions: number;
+    /** Turns recorded in the window. */
+    readonly turns: number;
+    /** Uncached prompt tokens across those Turns. */
+    readonly inputTokens: number;
+    /** Completion tokens across those Turns. */
+    readonly outputTokens: number;
+    /** Prompt tokens served from the provider cache, summed over the Turns that reported them. */
+    readonly cacheReadTokens: number;
+    /** Prompt tokens written to that cache, likewise. */
+    readonly cacheWriteTokens: number;
+    /** Share of prompt tokens that came from cache, in [0, 1]; 0 when the window never read cache. */
+    readonly cacheHitRate: number;
+    /** The most recent report time in the window. */
+    readonly at: number;
+}
+/** Directory of the ledger inside one deployment home. */
+/** The browser-facing read the hub answers from its own ledger. */
+export declare const USAGE_BROWSER_READ_PATH = "/api/usage/me";
+export declare function usageDirectory(home: string): string;
+/** Absolute path of one account's ledger file. */
+export declare function usageFilePath(home: string, accountId: string): string;
+/**
+ * Append one report to an account's ledger, creating the directory on first use.
+ * @param home - deployment home.
+ * @param accountId - the account the reporting runtime serves.
+ * @param report - the values it reported.
+ */
+export declare function appendUsage(home: string, accountId: string, report: UsageReport): Promise<void>;
+/**
+ * Read one account's records, latest line per Turn, oldest first.
+ *
+ * A Turn reported twice keeps the later line and an out-of-order earlier line
+ * never replaces it; a line that is not a report is skipped rather than failing
+ * the read, because runtimes append to this file while the hub reads it.
+ * @param home - deployment home.
+ * @param accountId - the account whose ledger to read.
+ * @param window - report times to include.
+ * @returns the records inside the window, sorted by report time.
+ */
+export declare function readUsageRecords(home: string, accountId: string, window?: UsageWindow): Promise<UsageReport[]>;
+/**
+ * Total the records of one account's ledger inside a window.
+ * @param home - deployment home.
+ * @param accountId - the account whose ledger to total.
+ * @param window - report times to include.
+ * @returns the total, zeroes when nothing was reported in the window.
+ */
+export declare function readUsageTotal(home: string, accountId: string, window?: UsageWindow): Promise<UsageTotal>;
+/**
+ * The report-time window one read asks for.
+ * @param params - query parameters of the read.
+ * @returns the window, or undefined when a bound is not a whole non-negative
+ * number of epoch milliseconds or the bounds are inverted.
+ */
+export declare function readUsageWindow(params: URLSearchParams): UsageWindow | undefined;
+/**
+ * The newest records one answer carries, and whether older ones were left out.
+ *
+ * Records are sorted by report time, so a chart drawn from the newest slice is
+ * missing its oldest days rather than scattered holes; the flag says so.
+ * @param records - records in report-time order.
+ * @param cap - most records one answer may carry.
+ * @returns the records to send and whether the cap dropped any.
+ */
+export declare function capUsageRecords<T>(records: readonly T[], cap: number): {
+    records: T[];
+    truncated: boolean;
+};
+/**
+ * Sum one account's records into a total.
+ * @param records - records already deduplicated per Turn.
+ * @returns the total they add up to.
+ */
+export declare function totalUsage(records: readonly UsageReport[]): UsageTotal;
+/**
+ * Total every account's ledger inside a window.
+ * @param home - deployment home.
+ * @param window - report times to include.
+ * @returns one total per account that reported in the window.
+ */
+export declare function readUsageTotals(home: string, window?: UsageWindow): Promise<Record<string, UsageTotal>>;
+/**
+ * Sum every account's total into the deployment's own.
+ *
+ * The session and turn counts add up rather than deduplicating, because one
+ * session belongs to one account: two accounts reporting a session each
+ * reported two.
+ * @param totals - totals keyed by account identity.
+ * @returns the summed total, zeroes when no account has reported.
+ */
+export declare function sumUsageTotals(totals: Readonly<Record<string, UsageTotal>>): UsageTotal;
+/**
+ * Read one ledger line as a report.
+ * @param line - one line of an account's ledger.
+ * @returns the report, or undefined when the line is empty, torn, or not a report.
+ */
+export declare function parseUsageReport(line: string): UsageReport | undefined;
+/**
+ * Whether a parsed value carries the report fields with usable values.
+ * @param value - the parsed line.
+ * @returns true when it is one report.
+ */
+export declare function isUsageReport(value: unknown): value is UsageReport;
+//# sourceMappingURL=usage-ledger.d.ts.map

package/lib/types/web-entry.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The deployment entry: one public address, one supervisor, and one runtime per
+ * account.
+ *
+ * Every profile that serves a browser address is a deployment: `qilin web` and
+ * the product surface `qilin` both come here. This process binds the address a
+ * browser reaches, terminates TLS when the invocation carries a certificate and
+ * key, and starts one child runtime per account on demand. A child boots the same
+ * profile with {@link TENANT_VARIABLE} set, so the application is what a runtime
+ * process runs and the supervisor is what the deployment runs.
+ *
+ * Runtimes stay on loopback: the public address is the supervisor's. That is
+ * why this entry serves every account through its own origin rather than
+ * redirecting a browser to a runtime port — a redirect target a client cannot
+ * reach is not a deployment.
+ *
+ * The entry reads the deployment's own flags and hands every other argument to
+ * each runtime's command line, so an application flag reaches the process that
+ * implements it instead of being dropped here. `--patch` is the exception it
+ * forwards as a launcher flag, because an overlay applies to the composition
+ * each runtime boots.
+ *
+ * The desktop shell boots the product profile in-process through
+ * `profile-boot`, so it never reaches this module and keeps serving one
+ * account directly.
+ * @module @qilin-agent/cli/web-entry
+ */
+/** The profiles whose boot is a deployment of the product surface. */
+export declare const ENTRY_PROFILES: readonly string[];
+/** Certificate chain and private key the deployment address serves with. */
+export interface DeploymentTls {
+    /** PEM certificate chain file. */
+    readonly certFile: string;
+    /** Unencrypted PEM private key file. */
+    readonly keyFile: string;
+}
+/** What one deployment invocation asks the entry to serve. */
+export interface DeploymentOptions {
+    /** Interface the public address binds. */
+    readonly host: string;
+    /** Port the public address binds; 0 lets the OS pick one. */
+    readonly port: number;
+    /** Profile each account's runtime boots. */
+    readonly tenantProfile: string;
+    /** Idle window after which an account's runtime is reclaimed. */
+    readonly idleMilliseconds: number;
+    /** Most account runtimes alive at once; 0 keeps every one. */
+    readonly maxTenants: number;
+    /** First wait before retrying a runtime that failed to start. */
+    readonly restartBackoffMilliseconds: number;
+    /** Serve every account through the public address instead of per-account origins. */
+    readonly singleOrigin: boolean;
+    /** Interface each account's runtime binds; loopback serves one public address. */
+    readonly tenantHost: string | undefined;
+    /** Who may create accounts on this deployment. */
+    readonly registration: 'open' | 'closed';
+    /** TLS the public address terminates with, when the invocation named a key pair. */
+    readonly tls: DeploymentTls | undefined;
+    /** Whether the invocation asked for help instead of serving. */
+    readonly help: boolean;
+    /** Overlay files the deployment arguments name, as absolute paths, in argv order. */
+    readonly patches: readonly string[];
+    /** Arguments belonging to the served application, in argv order. */
+    readonly appArguments: readonly string[];
+}
+/** What the launcher resolved for one deployment boot. */
+export interface WebEntryInvocation {
+    /** Arguments for the served application, after the launcher's own flags. */
+    readonly args: readonly string[];
+    /** Profile this deployment serves. */
+    readonly profile: string;
+    /** Overlay files applied to every runtime's composition, in argv order. */
+    readonly patches: readonly string[];
+    /** Shipped template named by `--from-default-profile`, which this entry refuses. */
+    readonly fromDefaultProfile?: string | undefined;
+}
+/**
+ * Read one deployment invocation.
+ * @param args - the arguments after the launcher's own flags.
+ * @param servedProfile - profile this deployment serves when the invocation names none.
+ * @returns what the entry should serve.
+ * @throws Error when a named flag cannot be honoured.
+ */
+export declare function deploymentOptions(args: readonly string[], servedProfile: string): DeploymentOptions;
+/**
+ * Whether this process is the deployment entry rather than one account's runtime.
+ * @returns true when no tenant marker is present.
+ */
+export declare function isWebEntry(): boolean;
+/**
+ * Serve the deployment: the public address, and one runtime per account.
+ * @param invocation - the served profile, its overlays, and the app's arguments.
+ * @returns the process exit code.
+ * @throws Error when the invocation names a flag the deployment cannot honour.
+ */
+export declare function runWebEntry(invocation: WebEntryInvocation): Promise<number>;
+//# sourceMappingURL=web-entry.d.ts.map