actoviq-agent-sdk 0.4.21 → 0.4.22

package/dist/src/usage/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../src/usage/contracts.ts"],"names":[],"mappings":"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"}

package/dist/src/usage/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/src/usage/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/usage/contracts.ts"],"names":[],"mappings":""}

package/dist/src/usage/index.d.ts

@@ -0,0 +1,7 @@
+export { UsageBudgetService, formatBudgetNotification } from './budgetService.js';
+export type { BudgetNotification, BudgetPreflightResult, BudgetStorePort, BudgetTransactionPort, } from './budgetService.js';
+export type { BudgetContext, BudgetAction, BudgetDecision, BudgetMetric, BudgetPeriod, BudgetPolicy, BudgetReservation, BudgetReservationOutcome, BudgetScope, UsageCounters, UsageAccuracy, UsageEventV2, UsageFilter, UsageImportResult, UsagePage, UsageRouteAttempt, UsageSource, UsageStatus, UsageSummary, } from './contracts.js';
+export { UsageLedger } from './usageLedger.js';
+export type { UsageLedgerOptions } from './usageLedger.js';
+export { UsageQueryService, legacyCostLedgerPath, usageDatabasePath } from './usageQueryService.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/usage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/usage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAClF,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,wBAAwB,EACxB,WAAW,EACX,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/src/usage/index.js

@@ -0,0 +1,4 @@
+export { UsageBudgetService, formatBudgetNotification } from './budgetService.js';
+export { UsageLedger } from './usageLedger.js';
+export { UsageQueryService, legacyCostLedgerPath, usageDatabasePath } from './usageQueryService.js';
+//# sourceMappingURL=index.js.map

package/dist/src/usage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/usage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AA4BlF,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/src/usage/usageLedger.d.ts

@@ -0,0 +1,19 @@
+import { type SqliteDriverFactory } from '../storage-v2/sqliteDriver.js';
+import type { UsageEventV2, UsageFilter, UsageImportResult, UsagePage, UsageSummary } from './contracts.js';
+export interface UsageLedgerOptions {
+    filename: string;
+    driverFactory?: SqliteDriverFactory;
+}
+export declare class UsageLedger {
+    private readonly driver;
+    private constructor();
+    static open(options: UsageLedgerOptions): Promise<UsageLedger>;
+    append(event: UsageEventV2): boolean;
+    query(page?: UsagePage): UsageEventV2[];
+    summarize(filter?: UsageFilter): UsageSummary;
+    importLegacyJsonl(filename: string): Promise<UsageImportResult>;
+    exportJsonl(filename: string, filter?: UsageFilter): Promise<number>;
+    deleteBefore(timestamp: string): number;
+    close(): void;
+}
+//# sourceMappingURL=usageLedger.d.ts.map

package/dist/src/usage/usageLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageLedger.d.ts","sourceRoot":"","sources":["../../../src/usage/usageLedger.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,YAAY,EACb,MAAM,gBAAgB,CAAC;AAiBxB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,qBAAa,WAAW;IACF,OAAO,CAAC,QAAQ,CAAC,MAAM;IAA3C,OAAO;WAIM,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAcpE,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IA4CpC,KAAK,CAAC,IAAI,GAAE,SAAc,GAAG,YAAY,EAAE;IAU3C,SAAS,CAAC,MAAM,GAAE,WAAgB,GAAG,YAAY;IAuC3C,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqD/D,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAY9E,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAKvC,KAAK,IAAI,IAAI;CAGd"}

package/dist/src/usage/usageLedger.js

@@ -0,0 +1,389 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { nodeSqliteDriverFactory, } from '../storage-v2/sqliteDriver.js';
+const SCHEMA_VERSION = 1;
+const FILTER_COLUMNS = {
+    source: 'source',
+    status: 'status',
+    model: 'requested_model',
+    providerId: 'provider_id',
+    credentialId: 'credential_id',
+    routeId: 'route_id',
+    configurationId: 'configuration_id',
+    projectId: 'project_id',
+    agentId: 'agent_id',
+    sessionId: 'session_id',
+    runId: 'run_id',
+};
+export class UsageLedger {
+    driver;
+    constructor(driver) {
+        this.driver = driver;
+        initializeSchema(driver);
+    }
+    static async open(options) {
+        if (!options.filename.trim())
+            throw new TypeError('filename must not be empty');
+        if (options.filename !== ':memory:') {
+            await mkdir(path.dirname(path.resolve(options.filename)), { recursive: true });
+        }
+        const driver = await (options.driverFactory ?? nodeSqliteDriverFactory).open(options.filename);
+        try {
+            return new UsageLedger(driver);
+        }
+        catch (error) {
+            driver.close();
+            throw error;
+        }
+    }
+    append(event) {
+        assertUsageEvent(event);
+        const result = this.driver.prepare(`
+      INSERT OR IGNORE INTO usage_events (
+        event_id, request_id, correlation_id, timestamp, source, status,
+        requested_model, resolved_model, operation,
+        provider_id, credential_id, route_id, configuration_id, project_id, agent_id,
+        session_id, run_id, input_tokens, output_tokens, cache_read_tokens,
+        cache_write_tokens, reasoning_tokens, audio_input_tokens, audio_output_tokens,
+        requests, usage_accuracy, cost_usd, event_json
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(event.eventId, event.requestId, event.correlationId, event.timestamp, event.source, event.status, event.requestedModel, event.resolvedModel ?? null, event.operation, event.providerId ?? null, event.credentialId ?? null, event.routeId ?? null, event.configurationId ?? null, event.projectId ?? null, event.agentId ?? null, event.sessionId ?? null, event.runId ?? null, event.usage.inputTokens, event.usage.outputTokens, event.usage.cacheReadTokens, event.usage.cacheWriteTokens, event.usage.reasoningTokens, event.usage.audioInputTokens, event.usage.audioOutputTokens, event.usage.requests, event.usage.accuracy, event.usage.costUsd ?? 0, JSON.stringify(event));
+        return result.changes > 0;
+    }
+    query(page = {}) {
+        const { sql, parameters } = filterSql(page);
+        const limit = clampInteger(page.limit, 100, 1, 1000);
+        const offset = clampInteger(page.offset, 0, 0, Number.MAX_SAFE_INTEGER);
+        return this.driver.prepare(`
+      SELECT event_json FROM usage_events${sql}
+      ORDER BY timestamp DESC, event_id DESC LIMIT ? OFFSET ?
+    `).all(...parameters, limit, offset).map(row => parseStoredEvent(row.event_json));
+    }
+    summarize(filter = {}) {
+        const { sql, parameters } = filterSql(filter);
+        const row = this.driver.prepare(`
+      SELECT
+        COUNT(*) AS entries,
+        COALESCE(SUM(input_tokens), 0) AS input_tokens,
+        COALESCE(SUM(output_tokens), 0) AS output_tokens,
+        COALESCE(SUM(cache_read_tokens), 0) AS cache_read_tokens,
+        COALESCE(SUM(cache_write_tokens), 0) AS cache_write_tokens,
+        COALESCE(SUM(input_tokens + output_tokens), 0) AS total_tokens,
+        COALESCE(SUM(reasoning_tokens), 0) AS reasoning_tokens,
+        COALESCE(SUM(audio_input_tokens), 0) AS audio_input_tokens,
+        COALESCE(SUM(audio_output_tokens), 0) AS audio_output_tokens,
+        COALESCE(SUM(requests), 0) AS requests,
+        COALESCE(SUM(cost_usd), 0) AS cost_usd,
+        SUM(CASE WHEN usage_accuracy = 'unknown' THEN 1 ELSE 0 END) AS unknown_entries,
+        SUM(CASE WHEN usage_accuracy = 'estimated' THEN 1 ELSE 0 END) AS estimated_entries
+      FROM usage_events${sql}
+    `).get(...parameters);
+        return {
+            entries: numeric(row?.entries),
+            inputTokens: numeric(row?.input_tokens),
+            outputTokens: numeric(row?.output_tokens),
+            cacheReadTokens: numeric(row?.cache_read_tokens),
+            cacheWriteTokens: numeric(row?.cache_write_tokens),
+            totalTokens: numeric(row?.total_tokens),
+            reasoningTokens: numeric(row?.reasoning_tokens),
+            audioInputTokens: numeric(row?.audio_input_tokens),
+            audioOutputTokens: numeric(row?.audio_output_tokens),
+            requests: numeric(row?.requests),
+            costUsd: numeric(row?.cost_usd),
+            accuracy: numeric(row?.unknown_entries) > 0
+                ? 'unknown'
+                : numeric(row?.estimated_entries) > 0
+                    ? 'estimated'
+                    : 'actual',
+        };
+    }
+    async importLegacyJsonl(filename) {
+        let buffer;
+        try {
+            buffer = await readFile(filename);
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return { imported: 0, skipped: 0, malformed: 0 };
+            throw error;
+        }
+        const sourceKey = path.resolve(filename);
+        const checkpoint = this.driver.prepare(`
+      SELECT byte_offset FROM usage_import_sources WHERE source_key = ?
+    `).get(sourceKey);
+        const previousOffset = numeric(checkpoint?.byte_offset);
+        const startOffset = previousOffset <= buffer.length ? previousOffset : 0;
+        if (startOffset === buffer.length)
+            return { imported: 0, skipped: 0, malformed: 0 };
+        return this.driver.transaction(() => {
+            let imported = 0;
+            let skipped = 0;
+            let malformed = 0;
+            let offset = startOffset;
+            for (let cursor = startOffset; cursor <= buffer.length; cursor += 1) {
+                if (cursor < buffer.length && buffer[cursor] !== 0x0a)
+                    continue;
+                const raw = buffer.subarray(offset, cursor).toString('utf8').replace(/\r$/u, '');
+                const lineOffset = offset;
+                offset = cursor + 1;
+                if (!raw.trim())
+                    continue;
+                let value;
+                try {
+                    value = JSON.parse(raw);
+                }
+                catch {
+                    malformed += 1;
+                    continue;
+                }
+                const event = legacyEvent(value, raw, lineOffset);
+                if (!event) {
+                    malformed += 1;
+                }
+                else if (this.append(event)) {
+                    imported += 1;
+                }
+                else {
+                    skipped += 1;
+                }
+            }
+            this.driver.prepare(`
+        INSERT INTO usage_import_sources (source_key, byte_offset, updated_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(source_key) DO UPDATE SET
+          byte_offset = excluded.byte_offset,
+          updated_at = excluded.updated_at
+      `).run(sourceKey, buffer.length, new Date().toISOString());
+            return { imported, skipped, malformed };
+        });
+    }
+    async exportJsonl(filename, filter = {}) {
+        await mkdir(path.dirname(path.resolve(filename)), { recursive: true });
+        const events = [];
+        for (let offset = 0;; offset += 1000) {
+            const page = this.query({ ...filter, limit: 1000, offset });
+            events.push(...page);
+            if (page.length < 1000)
+                break;
+        }
+        await writeFile(filename, events.map(event => JSON.stringify(event)).join('\n') + (events.length ? '\n' : ''), 'utf8');
+        return events.length;
+    }
+    deleteBefore(timestamp) {
+        assertTimestamp(timestamp, 'timestamp');
+        return this.driver.prepare('DELETE FROM usage_events WHERE timestamp < ?').run(timestamp).changes;
+    }
+    close() {
+        this.driver.close();
+    }
+}
+function initializeSchema(driver) {
+    driver.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA foreign_keys = ON;
+    PRAGMA busy_timeout = 5000;
+    CREATE TABLE IF NOT EXISTS usage_schema (version INTEGER NOT NULL);
+    INSERT INTO usage_schema(version)
+      SELECT ${SCHEMA_VERSION} WHERE NOT EXISTS (SELECT 1 FROM usage_schema);
+    CREATE TABLE IF NOT EXISTS usage_events (
+      event_id TEXT PRIMARY KEY,
+      request_id TEXT NOT NULL,
+      correlation_id TEXT NOT NULL,
+      timestamp TEXT NOT NULL,
+      source TEXT NOT NULL,
+      status TEXT NOT NULL,
+      requested_model TEXT NOT NULL,
+      resolved_model TEXT,
+      operation TEXT NOT NULL,
+      provider_id TEXT,
+      credential_id TEXT,
+      route_id TEXT,
+      configuration_id TEXT,
+      project_id TEXT,
+      agent_id TEXT,
+      session_id TEXT,
+      run_id TEXT,
+      input_tokens INTEGER NOT NULL,
+      output_tokens INTEGER NOT NULL,
+      cache_read_tokens INTEGER NOT NULL,
+      cache_write_tokens INTEGER NOT NULL,
+      reasoning_tokens INTEGER NOT NULL,
+      audio_input_tokens INTEGER NOT NULL,
+      audio_output_tokens INTEGER NOT NULL,
+      requests INTEGER NOT NULL,
+      usage_accuracy TEXT NOT NULL,
+      cost_usd REAL NOT NULL,
+      event_json TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS usage_events_timestamp ON usage_events(timestamp);
+    CREATE INDEX IF NOT EXISTS usage_events_model ON usage_events(requested_model, timestamp);
+    CREATE INDEX IF NOT EXISTS usage_events_provider ON usage_events(provider_id, timestamp);
+    CREATE INDEX IF NOT EXISTS usage_events_route ON usage_events(route_id, timestamp);
+    CREATE INDEX IF NOT EXISTS usage_events_configuration ON usage_events(configuration_id, timestamp);
+    CREATE INDEX IF NOT EXISTS usage_events_project ON usage_events(project_id, timestamp);
+    CREATE INDEX IF NOT EXISTS usage_events_agent ON usage_events(agent_id, timestamp);
+    CREATE TABLE IF NOT EXISTS usage_import_sources (
+      source_key TEXT PRIMARY KEY,
+      byte_offset INTEGER NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+  `);
+    const row = driver.prepare('SELECT version FROM usage_schema LIMIT 1').get();
+    if (numeric(row?.version) !== SCHEMA_VERSION) {
+        throw new Error(`Unsupported usage ledger schema version: ${String(row?.version)}`);
+    }
+}
+function filterSql(filter) {
+    const clauses = [];
+    const parameters = [];
+    if (filter.from) {
+        assertTimestamp(filter.from, 'from');
+        clauses.push('timestamp >= ?');
+        parameters.push(filter.from);
+    }
+    if (filter.to) {
+        assertTimestamp(filter.to, 'to');
+        clauses.push('timestamp < ?');
+        parameters.push(filter.to);
+    }
+    for (const [key, column] of Object.entries(FILTER_COLUMNS)) {
+        const value = filter[key];
+        if (value === undefined)
+            continue;
+        clauses.push(`${column} = ?`);
+        parameters.push(value);
+    }
+    return { sql: clauses.length ? ` WHERE ${clauses.join(' AND ')}` : '', parameters };
+}
+function legacyEvent(value, raw, offset) {
+    if (!isRecord(value))
+        return undefined;
+    if (value.version === 2 && typeof value.eventId === 'string') {
+        try {
+            const event = value;
+            assertUsageEvent(event);
+            return event;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // Legacy `/cost` included timestamp-less valid records in the all-time total.
+    // Anchor them outside normal retention windows without pretending they are current usage.
+    const timestamp = typeof value.ts === 'string' && Number.isFinite(Date.parse(value.ts))
+        ? value.ts
+        : '1970-01-01T00:00:00.000Z';
+    const eventId = typeof value.eventId === 'string' && value.eventId
+        ? value.eventId
+        : `legacy:${createHash('sha256').update(raw).digest('hex')}:${offset}`;
+    const costUsd = count(value.costUsd);
+    return {
+        version: 2,
+        eventId,
+        requestId: optionalString(value.requestId) ?? optionalString(value.runId) ?? eventId,
+        correlationId: optionalString(value.correlationId) ?? optionalString(value.sessionId) ?? eventId,
+        timestamp,
+        source: usageSource(value.source) ?? 'import',
+        status: 'succeeded',
+        requestedModel: typeof value.model === 'string' && value.model ? value.model : 'unknown',
+        operation: 'generate',
+        ...(optionalString(value.providerId) ? { providerId: optionalString(value.providerId) } : {}),
+        ...(optionalString(value.credentialId) ? { credentialId: optionalString(value.credentialId) } : {}),
+        ...(optionalString(value.routeId) ? { routeId: optionalString(value.routeId) } : {}),
+        ...(optionalString(value.configurationId) ? { configurationId: optionalString(value.configurationId) } : {}),
+        ...(optionalString(value.projectId) ? { projectId: optionalString(value.projectId) } : {}),
+        ...(optionalString(value.agentId) ? { agentId: optionalString(value.agentId) } : {}),
+        ...(optionalString(value.sessionId) ? { sessionId: optionalString(value.sessionId) } : {}),
+        ...(optionalString(value.runId) ? { runId: optionalString(value.runId) } : {}),
+        usage: {
+            requests: 1,
+            inputTokens: count(value.inputTokens),
+            outputTokens: count(value.outputTokens),
+            totalTokens: count(value.inputTokens) + count(value.outputTokens),
+            cacheReadTokens: count(value.cacheReadTokens),
+            cacheWriteTokens: count(value.cacheWriteTokens),
+            reasoningTokens: count(value.reasoningTokens),
+            audioInputTokens: count(value.audioInputTokens),
+            audioOutputTokens: count(value.audioOutputTokens),
+            ...(costUsd > 0 ? { costUsd } : {}),
+            accuracy: costUsd > 0 ? 'actual' : 'unknown',
+        },
+        attempts: [],
+        durationMs: 0,
+        streaming: false,
+    };
+}
+function assertUsageEvent(event) {
+    if (event.version !== 2)
+        throw new TypeError('usage event version must be 2');
+    if (!event.eventId.trim())
+        throw new TypeError('usage event id must not be empty');
+    if (!event.requestId.trim())
+        throw new TypeError('usage event request id must not be empty');
+    if (!event.correlationId.trim())
+        throw new TypeError('usage event correlation id must not be empty');
+    if (!event.requestedModel.trim())
+        throw new TypeError('usage event model must not be empty');
+    assertTimestamp(event.timestamp, 'usage event timestamp');
+    for (const [name, value] of Object.entries({
+        requests: event.usage.requests,
+        inputTokens: event.usage.inputTokens,
+        outputTokens: event.usage.outputTokens,
+        totalTokens: event.usage.totalTokens,
+        cacheReadTokens: event.usage.cacheReadTokens,
+        cacheWriteTokens: event.usage.cacheWriteTokens,
+        reasoningTokens: event.usage.reasoningTokens,
+        audioInputTokens: event.usage.audioInputTokens,
+        audioOutputTokens: event.usage.audioOutputTokens,
+        costUsd: event.usage.costUsd ?? 0,
+        durationMs: event.durationMs,
+    })) {
+        if (!Number.isFinite(value) || value < 0)
+            throw new TypeError(`${name} must be a finite non-negative number`);
+    }
+}
+function parseStoredEvent(value) {
+    if (typeof value !== 'string')
+        throw new TypeError('usage event payload must be a string');
+    const event = JSON.parse(value);
+    assertUsageEvent(event);
+    return event;
+}
+function assertTimestamp(value, name) {
+    if (!Number.isFinite(Date.parse(value)))
+        throw new TypeError(`${name} must be an ISO timestamp`);
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function numeric(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+function usageSource(value) {
+    return value === 'hadamard' || value === 'bridge' || value === 'keyway'
+        || value === 'native-cli' || value === 'import'
+        ? value
+        : value === 'hadamard-sdk'
+            ? 'hadamard'
+            : value === 'bridge-sdk'
+                ? 'bridge'
+                : value === 'keyway-gateway'
+                    ? 'keyway'
+                    : undefined;
+}
+function clampInteger(value, fallback, minimum, maximum) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(maximum, Math.max(minimum, Math.floor(value)));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isMissingFile(error) {
+    return isRecord(error) && error.code === 'ENOENT';
+}
+//# sourceMappingURL=usageLedger.js.map

package/dist/src/usage/usageLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageLedger.js","sourceRoot":"","sources":["../../../src/usage/usageLedger.ts"],"names":[],"mappings":"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"}

package/dist/src/usage/usageQueryService.d.ts

@@ -0,0 +1,12 @@
+import type { UsageFilter, UsagePage, UsageSummary } from './contracts.js';
+export declare function usageDatabasePath(homeDir: string): string;
+export declare function legacyCostLedgerPath(homeDir: string): string;
+export declare class UsageQueryService {
+    private readonly ledger;
+    private constructor();
+    static open(homeDir: string): Promise<UsageQueryService>;
+    summary(filter?: UsageFilter): UsageSummary;
+    events(page?: UsagePage): import("./contracts.js").UsageEventV2[];
+    close(): void;
+}
+//# sourceMappingURL=usageQueryService.d.ts.map

package/dist/src/usage/usageQueryService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageQueryService.d.ts","sourceRoot":"","sources":["../../../src/usage/usageQueryService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG3E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,qBAAa,iBAAiB;IACR,OAAO,CAAC,QAAQ,CAAC,MAAM;IAA3C,OAAO;WAEM,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAM9D,OAAO,CAAC,MAAM,GAAE,WAAgB,GAAG,YAAY;IAI/C,MAAM,CAAC,IAAI,GAAE,SAAc;IAI3B,KAAK,IAAI,IAAI;CAGd"}

package/dist/src/usage/usageQueryService.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { UsageLedger } from './usageLedger.js';
+export function usageDatabasePath(homeDir) {
+    return path.join(homeDir, 'usage', 'usage-v2.sqlite');
+}
+export function legacyCostLedgerPath(homeDir) {
+    return path.join(homeDir, 'usage', 'cost-ledger.jsonl');
+}
+export class UsageQueryService {
+    ledger;
+    constructor(ledger) {
+        this.ledger = ledger;
+    }
+    static async open(homeDir) {
+        const ledger = await UsageLedger.open({ filename: usageDatabasePath(homeDir) });
+        await ledger.importLegacyJsonl(legacyCostLedgerPath(homeDir));
+        return new UsageQueryService(ledger);
+    }
+    summary(filter = {}) {
+        return this.ledger.summarize(filter);
+    }
+    events(page = {}) {
+        return this.ledger.query(page);
+    }
+    close() {
+        this.ledger.close();
+    }
+}
+//# sourceMappingURL=usageQueryService.js.map

package/dist/src/usage/usageQueryService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usageQueryService.js","sourceRoot":"","sources":["../../../src/usage/usageQueryService.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,OAAO,iBAAiB;IACS;IAArC,YAAqC,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAE5D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAe;QAC/B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAChF,MAAM,MAAM,CAAC,iBAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;QAC9D,OAAO,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,SAAsB,EAAE;QAC9B,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,CAAC,OAAkB,EAAE;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actoviq-agent-sdk",
-  "version": "0.4.21",
+  "version": "0.4.22",
   "description": "Agent team platform — multi-agent, multi-runtime, model team collaboration with TUI, GUI, and MCP.",
   "repository": {
     "type": "git",
@@ -55,7 +55,7 @@
       "target": [
         "nsis"
       ],
-      "signAndEditExecutable": false,
+      "icon": "assets/hadamard-icon.ico",
       "forceCodeSigning": false
     },
     "nsis": {
@@ -164,6 +164,7 @@
     "README-zh.md",
     "CHANGELOG.md",
     "SECURITY.md",
+    "scripts/prepare-gui-launcher.mjs",
     "vendor/hadamard-runtime/cli.js"
   ],
   "engines": {
@@ -213,6 +214,7 @@
     "bench:memory": "tsx bench/memory/run.ts",
     "bench:goal": "tsx bench/goal/run.ts",
     "smoke": "npm run build && tsx scripts/integration-smoke.ts",
+    "smoke:keyway:native": "tsx scripts/keyway-native-auth-live-smoke.ts",
     "example:hadamard-quickstart": "npm run build && tsx examples/hadamard-quickstart.ts",
     "example:hadamard-session": "npm run build && tsx examples/hadamard-session.ts",
     "example:hadamard-stream-loop": "npm run build && tsx examples/hadamard-stream-loop.ts",
@@ -260,6 +262,16 @@
     "ws": "^8.21.3",
     "zod": "^4.1.12"
   },
+  "peerDependencies": {
+    "@keyway-router/core": "0.1.0",
+    "@keyway-router/gateway": "0.1.0",
+    "@keyway-router/node": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@keyway-router/core": { "optional": true },
+    "@keyway-router/gateway": { "optional": true },
+    "@keyway-router/node": { "optional": true }
+  },
   "optionalDependencies": {
     "@e2b/desktop": "^2.3.1",
     "@xterm/addon-fit": "^0.11.0",

package/scripts/prepare-gui-launcher.mjs

@@ -0,0 +1,62 @@
+// Windows dev launcher: copy electron.exe beside Electron's dist resources
+// (icudtl.dat, resources/, …) and embed assets/hadamard-icon.ico. The icon
+// fingerprint in the filename gives Explorer a fresh cache key after a brand
+// icon update; Windows taskbar icons are otherwise sticky by executable path.
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+if (process.platform !== 'win32') {
+  process.exit(0);
+}
+
+const electronExe = require('electron');
+const distDir = dirname(electronExe);
+const iconIco = join(root, 'assets', 'hadamard-icon.ico');
+
+if (!existsSync(iconIco)) {
+  process.stderr.write('prepare-gui-launcher: missing assets/hadamard-icon.ico — run npm run generate:icon\n');
+  process.exit(1);
+}
+
+const iconFingerprint = createHash('sha256').update(readFileSync(iconIco)).digest('hex').slice(0, 12);
+const launcherName = `Hadamard-${iconFingerprint}.exe`;
+const launcher = join(distDir, launcherName);
+
+const sources = [electronExe, iconIco];
+const stale = !existsSync(launcher)
+  || sources.some((src) => statSync(src).mtimeMs > statSync(launcher).mtimeMs);
+
+if (!stale) {
+  process.stdout.write(`prepare-gui-launcher: up to date (${launcher})\n`);
+  process.exit(0);
+}
+
+copyFileSync(electronExe, launcher);
+
+let rcedit;
+try {
+  rcedit = require('rcedit');
+} catch {
+  process.stderr.write('prepare-gui-launcher: install rcedit (npm install -D rcedit)\n');
+  process.exit(1);
+}
+
+await rcedit(launcher, {
+  icon: iconIco,
+  'product-version': '1.0.0',
+  'version-string': {
+    FileDescription: 'Hadamard',
+    ProductName: 'Hadamard',
+    CompanyName: 'Hadamard',
+    OriginalFilename: launcherName,
+    InternalName: 'Hadamard',
+  },
+});
+
+process.stdout.write(`prepare-gui-launcher: wrote ${launcher}\n`);