@zhin.js/agent 1.1.39 → 1.1.41

package/lib/trace/turn-usage-log.js

@@ -0,0 +1,83 @@
+import { formatCompact } from '@zhin.js/logger';
+const FIELDS = {
+    input: 'prompt_tokens', output: 'completion_tokens', totalTokens: 'total_tokens',
+    cacheRead: 'cache_read_tokens', cacheWrite: 'cache_write_tokens', reasoning: 'reasoning_tokens',
+};
+// Metadata can contain controls too; preserve one physical line and field boundaries.
+function safe(value) {
+    return value.replace(/[\p{Cc}\u2028\u2029|]/gu, ch => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`).slice(0, 240);
+}
+function known(call, field) {
+    const value = call[FIELDS[field]];
+    if (value === undefined || !Number.isFinite(value) || value < 0)
+        return undefined;
+    // Old records lack availability. Positive usage is evidence; normalized zero isn't.
+    const reported = call.reported?.[field] ?? (field === 'cacheRead' || field === 'cacheWrite' || field === 'reasoning'
+        ? true : value > 0);
+    return reported ? value : undefined;
+}
+/** A partial sum is explicitly a lower bound, never an apparently complete zero. */
+function sum(calls, field) {
+    if (!calls.length)
+        return 0;
+    const values = calls.map(call => known(call, field));
+    const present = values.filter((v) => v !== undefined);
+    if (!present.length)
+        return '?';
+    const total = present.reduce((a, b) => a + b, 0);
+    return present.length === calls.length ? total : `>=${total}`;
+}
+function tree(trace) {
+    return [trace, ...trace.subagents.flatMap(tree)];
+}
+function tokens(calls) {
+    return { input: sum(calls, 'input'), output: sum(calls, 'output'),
+        cache_read: sum(calls, 'cacheRead'), cache_write: sum(calls, 'cacheWrite'), reasoning: sum(calls, 'reasoning') };
+}
+export function formatTurnUsageLogs(trace, context, includeDetails = true) {
+    const traces = tree(trace);
+    const calls = traces.flatMap(item => item.model_calls);
+    const identity = { trace: safe(context.traceId), turn: safe(trace.turn_id) };
+    const models = [...new Set(calls.map(call => `${call.provider ?? '?'}/${call.model ?? '?'}`))];
+    const summary = formatCompact({ op: 'turn', ...identity, scene: safe(context.scene),
+        status: context.status ?? trace.termination.status,
+        model: safe(models.join(',') || context.selectedModel || '?'),
+        calls: calls.length, ...tokens(calls),
+        ms: trace.duration_ms === undefined ? '?' : Math.round(trace.duration_ms),
+        ...(traces.length > 1 ? { subagent_calls: calls.length - trace.model_calls.length } : {}),
+        ...((context.status ?? trace.termination.status) !== 'completed'
+            || traces.some(item => item.dropped > 0 || item.termination.status !== 'completed')
+            ? { partial: true } : {}),
+    });
+    const details = includeDetails ? traces.flatMap(item => {
+        const ids = { trace: identity.trace, turn: safe(item.turn_id) };
+        const lines = item.model_calls.map(call => formatCompact({ op: 'call', ...ids, index: call.index,
+            model: safe(`${call.provider ?? '?'}/${call.model ?? '?'}`), status: safe(call.stop_reason ?? '?'),
+            ...tokens([call]), ms: call.duration_ms === undefined ? '?' : Math.round(call.duration_ms) }));
+        const budget = item.context_budget;
+        if (budget)
+            lines.push(formatCompact({ op: 'context', ...ids, request: 'first', unit: 'estimated_tokens',
+                total: budget.total_tokens, fixed: budget.fixed_tokens,
+                segments: Object.entries(budget.segments).map(([key, value]) => `${safe(key)}=${value}`).join(' '),
+                loaded_tools: budget.tools.loaded, deferred_tools: budget.tools.deferred }));
+        return lines;
+    }) : [];
+    return { summary, details };
+}
+/** Logging is a projection of the existing trace, never execution authority. */
+export function logTurnUsage(logger, trace, context) {
+    try {
+        if (!logger.isLevelEnabled('info'))
+            return;
+        const debug = logger.isLevelEnabled('debug');
+        const lines = formatTurnUsageLogs(trace, context, debug);
+        logger.info(lines.summary);
+        if (debug)
+            for (const line of lines.details)
+                logger.debug(line);
+    }
+    catch {
+        // A transport/formatter failure must not change the outcome or skip trace persistence.
+    }
+}
+//# sourceMappingURL=turn-usage-log.js.map

package/lib/trace/turn-usage-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-usage-log.js","sourceRoot":"","sources":["../../src/trace/turn-usage-log.ts"],"names":[],"mappings":"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","sourcesContent":["import { formatCompact, type Logger } from '@zhin.js/logger';\nimport type { TurnTrace, TurnTraceModelCall } from './turn-trace.js';\n\nexport interface UsageLogContext {\n  traceId: string;\n  scene: string;\n  selectedModel?: string;\n  status?: string;\n}\n\ntype Field = 'input' | 'output' | 'totalTokens' | 'cacheRead' | 'cacheWrite' | 'reasoning';\nconst FIELDS = {\n  input: 'prompt_tokens', output: 'completion_tokens', totalTokens: 'total_tokens',\n  cacheRead: 'cache_read_tokens', cacheWrite: 'cache_write_tokens', reasoning: 'reasoning_tokens',\n} as const;\n\n// Metadata can contain controls too; preserve one physical line and field boundaries.\nfunction safe(value: string): string {\n  return value.replace(/[\\p{Cc}\\u2028\\u2029|]/gu, ch => `\\\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`).slice(0, 240);\n}\n\nfunction known(call: TurnTraceModelCall, field: Field): number | undefined {\n  const value = call[FIELDS[field]];\n  if (value === undefined || !Number.isFinite(value) || value < 0) return undefined;\n  // Old records lack availability. Positive usage is evidence; normalized zero isn't.\n  const reported = call.reported?.[field] ?? (field === 'cacheRead' || field === 'cacheWrite' || field === 'reasoning'\n    ? true : value > 0);\n  return reported ? value : undefined;\n}\n\n/** A partial sum is explicitly a lower bound, never an apparently complete zero. */\nfunction sum(calls: readonly TurnTraceModelCall[], field: Field): number | string {\n  if (!calls.length) return 0;\n  const values = calls.map(call => known(call, field));\n  const present = values.filter((v): v is number => v !== undefined);\n  if (!present.length) return '?';\n  const total = present.reduce((a, b) => a + b, 0);\n  return present.length === calls.length ? total : `>=${total}`;\n}\n\nfunction tree(trace: TurnTrace): TurnTrace[] {\n  return [trace, ...trace.subagents.flatMap(tree)];\n}\n\nfunction tokens(calls: readonly TurnTraceModelCall[]) {\n  return { input: sum(calls, 'input'), output: sum(calls, 'output'),\n    cache_read: sum(calls, 'cacheRead'), cache_write: sum(calls, 'cacheWrite'), reasoning: sum(calls, 'reasoning') };\n}\n\nexport function formatTurnUsageLogs(trace: TurnTrace, context: UsageLogContext, includeDetails = true): { summary: string; details: string[] } {\n  const traces = tree(trace);\n  const calls = traces.flatMap(item => item.model_calls);\n  const identity = { trace: safe(context.traceId), turn: safe(trace.turn_id) };\n  const models = [...new Set(calls.map(call => `${call.provider ?? '?'}/${call.model ?? '?'}`))];\n  const summary = formatCompact({ op: 'turn', ...identity, scene: safe(context.scene),\n    status: context.status ?? trace.termination.status,\n    model: safe(models.join(',') || context.selectedModel || '?'),\n    calls: calls.length, ...tokens(calls),\n    ms: trace.duration_ms === undefined ? '?' : Math.round(trace.duration_ms),\n    ...(traces.length > 1 ? { subagent_calls: calls.length - trace.model_calls.length } : {}),\n    ...((context.status ?? trace.termination.status) !== 'completed'\n      || traces.some(item => item.dropped > 0 || item.termination.status !== 'completed')\n      ? { partial: true } : {}),\n  });\n  const details = includeDetails ? traces.flatMap(item => {\n    const ids = { trace: identity.trace, turn: safe(item.turn_id) };\n    const lines = item.model_calls.map(call => formatCompact({ op: 'call', ...ids, index: call.index,\n      model: safe(`${call.provider ?? '?'}/${call.model ?? '?'}`), status: safe(call.stop_reason ?? '?'),\n      ...tokens([call]), ms: call.duration_ms === undefined ? '?' : Math.round(call.duration_ms) }));\n    const budget = item.context_budget;\n    if (budget) lines.push(formatCompact({ op: 'context', ...ids, request: 'first', unit: 'estimated_tokens',\n      total: budget.total_tokens, fixed: budget.fixed_tokens,\n      segments: Object.entries(budget.segments).map(([key, value]) => `${safe(key)}=${value}`).join(' '),\n      loaded_tools: budget.tools.loaded, deferred_tools: budget.tools.deferred }));\n    return lines;\n  }) : [];\n  return { summary, details };\n}\n\n/** Logging is a projection of the existing trace, never execution authority. */\nexport function logTurnUsage(logger: Pick<Logger, 'info' | 'debug' | 'isLevelEnabled'>, trace: TurnTrace, context: UsageLogContext): void {\n  try {\n    if (!logger.isLevelEnabled('info')) return;\n    const debug = logger.isLevelEnabled('debug');\n    const lines = formatTurnUsageLogs(trace, context, debug);\n    logger.info(lines.summary);\n    if (debug) for (const line of lines.details) logger.debug(line);\n  } catch {\n    // A transport/formatter failure must not change the outcome or skip trace persistence.\n  }\n}\n"]}

package/lib/usage/usage-store.d.ts

@@ -0,0 +1,199 @@
+import { type DatabaseHost } from '@zhin.js/plugin-runtime';
+import type { TurnEvent } from '../event/turn-event.js';
+import type { TurnRequest } from '../turn/turn-ingress.js';
+export declare const AGENT_USAGE_TURN_MODEL: {
+    readonly id: {
+        readonly type: "text";
+        readonly length: 64;
+        readonly primary: true;
+    };
+    readonly fingerprint: {
+        readonly type: "text";
+        readonly length: 64;
+        readonly nullable: false;
+    };
+    readonly owner: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly trace_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly turn_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly session_key: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly principal_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly origin_kind: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly endpoint_adapter: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly endpoint_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly conversation_kind: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly conversation_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly parent_kind: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly parent_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly thread_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly source_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly selected_provider: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly selected_model: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly status: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly started_at: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly ended_at: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly duration_ms: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly call_count: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+};
+export declare const AGENT_USAGE_CALL_MODEL: {
+    readonly id: {
+        readonly type: "text";
+        readonly length: 64;
+        readonly primary: true;
+    };
+    readonly root_id: {
+        readonly type: "text";
+        readonly length: 64;
+        readonly nullable: false;
+    };
+    readonly turn_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly call_index: {
+        readonly type: "integer";
+        readonly nullable: false;
+    };
+    readonly provider: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly model: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly stop_reason: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly duration_ms: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly input_tokens: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly output_tokens: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly total_tokens: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly cache_read_tokens: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly cache_write_tokens: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly reasoning_tokens: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly ended_at: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+    readonly root_ended_at: {
+        readonly type: "bigint";
+        readonly nullable: true;
+    };
+};
+export type UsageRow = Record<string, string | number | null>;
+export interface AgentUsageRecord {
+    readonly turn: UsageRow;
+    readonly calls: readonly UsageRow[];
+}
+export interface AgentUsageStore {
+    save(record: AgentUsageRecord): Promise<void>;
+    prune(): Promise<void>;
+}
+export declare const agentUsageStoreToken: import("@zhin.js/plugin-runtime").Token<AgentUsageStore>;
+/** Minimal numeric facts, independent of log level and trace archive size limits. */
+export declare class AgentUsageCollector {
+    #private;
+    private readonly owner;
+    private readonly request;
+    private readonly selected;
+    constructor(owner: string, request: TurnRequest, selected: {
+        provider: string;
+        model: string;
+    });
+    record(event: TurnEvent): void;
+    finish(status: string): AgentUsageRecord;
+}
+/** Tables contain no payload JSON, chat content, prompt, tool arguments or error text. */
+export declare class DatabaseAgentUsageStore implements AgentUsageStore {
+    private readonly database;
+    readonly retentionDays: number;
+    private readonly now;
+    constructor(database: DatabaseHost, retentionDays?: number, now?: () => number);
+    save(record: AgentUsageRecord): Promise<void>;
+    prune(): Promise<void>;
+}

package/lib/usage/usage-store.js

@@ -0,0 +1,121 @@
+import { createRootPrivateToken, encodeStorageIdentity } from '@zhin.js/plugin-runtime';
+import { createHash } from 'node:crypto';
+import { traceScopeTurnId } from '../trace/turn-trace-registry.js';
+const text = { type: 'text', nullable: true };
+const count = { type: 'bigint', nullable: true };
+export const AGENT_USAGE_TURN_MODEL = {
+    id: { type: 'text', length: 64, primary: true }, fingerprint: { type: 'text', length: 64, nullable: false },
+    owner: text, trace_id: text, turn_id: text, session_key: text, principal_id: text,
+    origin_kind: text, endpoint_adapter: text, endpoint_id: text, conversation_kind: text, conversation_id: text,
+    parent_kind: text, parent_id: text, thread_id: text, source_id: text,
+    selected_provider: text, selected_model: text, status: text,
+    started_at: count, ended_at: count, duration_ms: count, call_count: count,
+};
+export const AGENT_USAGE_CALL_MODEL = {
+    id: { type: 'text', length: 64, primary: true }, root_id: { type: 'text', length: 64, nullable: false },
+    turn_id: text, call_index: { type: 'integer', nullable: false }, provider: text, model: text, stop_reason: text,
+    duration_ms: count, input_tokens: count, output_tokens: count, total_tokens: count,
+    cache_read_tokens: count, cache_write_tokens: count, reasoning_tokens: count, ended_at: count, root_ended_at: count,
+};
+export const agentUsageStoreToken = createRootPrivateToken('zhin.agent.usage-store', 'Generation-owned structured usage persistence');
+const tokenFields = {
+    input_tokens: ['promptTokens', 'input'], output_tokens: ['completionTokens', 'output'], total_tokens: ['totalTokens', 'totalTokens'],
+    cache_read_tokens: ['cacheReadTokens', 'cacheRead'], cache_write_tokens: ['cacheWriteTokens', 'cacheWrite'], reasoning_tokens: ['reasoningTokens', 'reasoning'],
+};
+function nonnegative(value) { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null; }
+const identity = (value) => value === undefined ? null : encodeStorageIdentity(value);
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+/** Minimal numeric facts, independent of log level and trace archive size limits. */
+export class AgentUsageCollector {
+    owner;
+    request;
+    selected;
+    #calls = [];
+    #indexes = new Map();
+    #startedAt = Date.now();
+    #id;
+    constructor(owner, request, selected) {
+        this.owner = owner;
+        this.request = request;
+        this.selected = selected;
+        this.#id = digest([owner, request.identity.turnId]);
+    }
+    record(event) {
+        if (event.type !== 'usage')
+            return;
+        const turnId = traceScopeTurnId(event) ?? this.request.identity.turnId;
+        const index = (this.#indexes.get(turnId) ?? 0) + 1;
+        this.#indexes.set(turnId, index);
+        const row = { id: digest([this.#id, turnId, index]), root_id: this.#id, turn_id: identity(turnId), call_index: index,
+            provider: event.provider ?? null, model: event.model ?? null, stop_reason: event.stopReason ?? null,
+            duration_ms: typeof event.durationMs === 'number' ? nonnegative(Math.round(event.durationMs)) : null, ended_at: Date.now() };
+        for (const [column, [source, availability]] of Object.entries(tokenFields)) {
+            const value = nonnegative(event.usage[source]);
+            const reported = event.usage.reported?.[availability]
+                ?? (availability === 'input' || availability === 'output' || availability === 'totalTokens' ? value !== null && value > 0 : value !== null);
+            row[column] = reported ? value : null;
+        }
+        this.#calls.push(row);
+    }
+    finish(status) {
+        const endedAt = Date.now(), origin = this.request.origin, im = origin.kind === 'im' ? origin : undefined;
+        const turn = { id: this.#id, owner: identity(this.owner), trace_id: identity(this.request.identity.traceId), turn_id: identity(this.request.identity.turnId),
+            session_key: identity(this.request.session.key), principal_id: identity(this.request.principal.subjectId),
+            origin_kind: origin.kind, endpoint_adapter: identity(im?.conversation?.endpoint.adapter ?? im?.platform), endpoint_id: identity(im?.conversation?.endpoint.id ?? im?.endpoint),
+            conversation_kind: im?.conversation?.kind ?? im?.scope ?? null, conversation_id: identity(im?.conversation?.id ?? im?.sceneId), parent_kind: im?.conversation?.parent?.kind ?? null,
+            parent_id: identity(im?.conversation?.parent?.id), thread_id: identity(im?.conversation?.threadId ?? im?.threadId),
+            source_id: identity(origin.kind === 'schedule' ? origin.jobId : origin.kind === 'a2a' ? origin.taskId : origin.kind === 'http' ? origin.sessionId : origin.kind === 'internal' ? origin.source : undefined),
+            selected_provider: this.selected.provider, selected_model: this.selected.model, status,
+            started_at: this.#startedAt, ended_at: endedAt, duration_ms: endedAt - this.#startedAt, call_count: this.#calls.length,
+        };
+        const calls = this.#calls.map(row => ({ ...row, root_ended_at: endedAt }));
+        turn.fingerprint = digest([turn, calls]);
+        return { turn, calls };
+    }
+}
+/** Tables contain no payload JSON, chat content, prompt, tool arguments or error text. */
+export class DatabaseAgentUsageStore {
+    database;
+    retentionDays;
+    now;
+    constructor(database, retentionDays = 30, now = Date.now) {
+        this.database = database;
+        this.retentionDays = retentionDays;
+        this.now = now;
+        if (!Number.isSafeInteger(retentionDays) || retentionDays <= 0)
+            throw new TypeError('ai.usage.retentionDays must be a positive integer');
+        if (!database.transaction)
+            throw new Error('Agent usage requires transactional database storage');
+    }
+    async save(record) {
+        try {
+            await this.database.transaction(async (transaction) => {
+                const turns = transaction.model('agent_usage_turns');
+                const existing = (await turns.select('fingerprint').where({ id: record.turn.id }))[0];
+                if (existing) {
+                    if (existing.fingerprint !== record.turn.fingerprint)
+                        throw new Error('Conflicting usage record for the same turn');
+                    return;
+                }
+                await turns.insert(record.turn);
+                for (const call of record.calls)
+                    await transaction.model('agent_usage_calls').insert(call);
+            });
+        }
+        catch (error) {
+            // A concurrent writer may have committed the same complete record.
+            const existing = (await this.database.models.get('agent_usage_turns').select('fingerprint').where({ id: record.turn.id }).limit(1))[0];
+            if (existing?.fingerprint === record.turn.fingerprint)
+                return;
+            throw error;
+        }
+    }
+    async prune() {
+        const cutoff = this.now() - this.retentionDays * 86_400_000;
+        await this.database.transaction(async (transaction) => {
+            await transaction.model('agent_usage_calls').delete().where({ root_ended_at: { $lt: cutoff } });
+            await transaction.model('agent_usage_turns').delete().where({ ended_at: { $lt: cutoff } });
+        });
+    }
+}
+//# sourceMappingURL=usage-store.js.map

package/lib/usage/usage-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-store.js","sourceRoot":"","sources":["../../src/usage/usage-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRootPrivateToken, encodeStorageIdentity, type DatabaseHost } from '@zhin.js/plugin-runtime';\nimport { createHash } from 'node:crypto';\nimport type { TurnEvent } from '../event/turn-event.js';\nimport type { TurnRequest } from '../turn/turn-ingress.js';\nimport { traceScopeTurnId } from '../trace/turn-trace-registry.js';\n\nconst text = { type: 'text', nullable: true } as const;\nconst count = { type: 'bigint', nullable: true } as const;\nexport const AGENT_USAGE_TURN_MODEL = {\n  id: { type: 'text', length: 64, primary: true }, fingerprint: { type: 'text', length: 64, nullable: false },\n  owner: text, trace_id: text, turn_id: text, session_key: text, principal_id: text,\n  origin_kind: text, endpoint_adapter: text, endpoint_id: text, conversation_kind: text, conversation_id: text,\n  parent_kind: text, parent_id: text, thread_id: text, source_id: text,\n  selected_provider: text, selected_model: text, status: text,\n  started_at: count, ended_at: count, duration_ms: count, call_count: count,\n} as const;\nexport const AGENT_USAGE_CALL_MODEL = {\n  id: { type: 'text', length: 64, primary: true }, root_id: { type: 'text', length: 64, nullable: false },\n  turn_id: text, call_index: { type: 'integer', nullable: false }, provider: text, model: text, stop_reason: text,\n  duration_ms: count, input_tokens: count, output_tokens: count, total_tokens: count,\n  cache_read_tokens: count, cache_write_tokens: count, reasoning_tokens: count, ended_at: count, root_ended_at: count,\n} as const;\nexport type UsageRow = Record<string, string | number | null>;\nexport interface AgentUsageRecord { readonly turn: UsageRow; readonly calls: readonly UsageRow[] }\nexport interface AgentUsageStore { save(record: AgentUsageRecord): Promise<void>; prune(): Promise<void> }\nexport const agentUsageStoreToken = createRootPrivateToken<AgentUsageStore>('zhin.agent.usage-store', 'Generation-owned structured usage persistence');\n\nconst tokenFields = {\n  input_tokens: ['promptTokens', 'input'], output_tokens: ['completionTokens', 'output'], total_tokens: ['totalTokens', 'totalTokens'],\n  cache_read_tokens: ['cacheReadTokens', 'cacheRead'], cache_write_tokens: ['cacheWriteTokens', 'cacheWrite'], reasoning_tokens: ['reasoningTokens', 'reasoning'],\n} as const;\nfunction nonnegative(value: unknown): number | null { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null; }\nconst identity = (value: string | undefined) => value === undefined ? null : encodeStorageIdentity(value);\nconst digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex');\n\n/** Minimal numeric facts, independent of log level and trace archive size limits. */\nexport class AgentUsageCollector {\n  readonly #calls: UsageRow[] = [];\n  readonly #indexes = new Map<string, number>();\n  readonly #startedAt = Date.now();\n  readonly #id: string;\n  constructor(private readonly owner: string, private readonly request: TurnRequest,\n    private readonly selected: { provider: string; model: string }) {\n    this.#id = digest([owner, request.identity.turnId]);\n  }\n  record(event: TurnEvent): void {\n    if (event.type !== 'usage') return;\n    const turnId = traceScopeTurnId(event) ?? this.request.identity.turnId;\n    const index = (this.#indexes.get(turnId) ?? 0) + 1;\n    this.#indexes.set(turnId, index);\n    const row: UsageRow = { id: digest([this.#id, turnId, index]), root_id: this.#id, turn_id: identity(turnId), call_index: index,\n      provider: event.provider ?? null, model: event.model ?? null, stop_reason: event.stopReason ?? null,\n      duration_ms: typeof event.durationMs === 'number' ? nonnegative(Math.round(event.durationMs)) : null, ended_at: Date.now() };\n    for (const [column, [source, availability]] of Object.entries(tokenFields)) {\n      const value = nonnegative(event.usage[source]);\n      const reported = event.usage.reported?.[availability]\n        ?? (availability === 'input' || availability === 'output' || availability === 'totalTokens' ? value !== null && value > 0 : value !== null);\n      row[column] = reported ? value : null;\n    }\n    this.#calls.push(row);\n  }\n  finish(status: string): AgentUsageRecord {\n    const endedAt = Date.now(), origin = this.request.origin, im = origin.kind === 'im' ? origin : undefined;\n    const turn: UsageRow = { id: this.#id, owner: identity(this.owner), trace_id: identity(this.request.identity.traceId), turn_id: identity(this.request.identity.turnId),\n      session_key: identity(this.request.session.key), principal_id: identity(this.request.principal.subjectId),\n      origin_kind: origin.kind, endpoint_adapter: identity(im?.conversation?.endpoint.adapter ?? im?.platform), endpoint_id: identity(im?.conversation?.endpoint.id ?? im?.endpoint),\n      conversation_kind: im?.conversation?.kind ?? im?.scope ?? null, conversation_id: identity(im?.conversation?.id ?? im?.sceneId), parent_kind: im?.conversation?.parent?.kind ?? null,\n      parent_id: identity(im?.conversation?.parent?.id), thread_id: identity(im?.conversation?.threadId ?? im?.threadId),\n      source_id: identity(origin.kind === 'schedule' ? origin.jobId : origin.kind === 'a2a' ? origin.taskId : origin.kind === 'http' ? origin.sessionId : origin.kind === 'internal' ? origin.source : undefined),\n      selected_provider: this.selected.provider, selected_model: this.selected.model, status,\n      started_at: this.#startedAt, ended_at: endedAt, duration_ms: endedAt - this.#startedAt, call_count: this.#calls.length,\n    };\n    const calls = this.#calls.map(row => ({ ...row, root_ended_at: endedAt }));\n    turn.fingerprint = digest([turn, calls]);\n    return { turn, calls };\n  }\n}\n\n/** Tables contain no payload JSON, chat content, prompt, tool arguments or error text. */\nexport class DatabaseAgentUsageStore implements AgentUsageStore {\n  constructor(private readonly database: DatabaseHost, readonly retentionDays = 30, private readonly now = Date.now) {\n    if (!Number.isSafeInteger(retentionDays) || retentionDays <= 0) throw new TypeError('ai.usage.retentionDays must be a positive integer');\n    if (!database.transaction) throw new Error('Agent usage requires transactional database storage');\n  }\n  async save(record: AgentUsageRecord): Promise<void> {\n    try {\n      await this.database.transaction!(async transaction => {\n        const turns = transaction.model('agent_usage_turns');\n        const existing = (await turns.select('fingerprint').where({ id: record.turn.id }))[0];\n        if (existing) {\n          if (existing.fingerprint !== record.turn.fingerprint) throw new Error('Conflicting usage record for the same turn');\n          return;\n        }\n        await turns.insert(record.turn);\n        for (const call of record.calls) await transaction.model('agent_usage_calls').insert(call);\n      });\n    } catch (error) {\n      // A concurrent writer may have committed the same complete record.\n      const existing = (await this.database.models.get('agent_usage_turns')!.select('fingerprint').where({ id: record.turn.id }).limit(1))[0];\n      if (existing?.fingerprint === record.turn.fingerprint) return;\n      throw error;\n    }\n  }\n  async prune(): Promise<void> {\n    const cutoff = this.now() - this.retentionDays * 86_400_000;\n    await this.database.transaction!(async transaction => {\n      await transaction.model('agent_usage_calls').delete().where({ root_ended_at: { $lt: cutoff } });\n      await transaction.model('agent_usage_turns').delete().where({ ended_at: { $lt: cutoff } });\n    });\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/agent",
-  "version": "1.1.39",
+  "version": "1.1.41",
   "description": "Zhin AI Agent — session, ZhinAgent, init; composes @zhin.js/core providers and tools",
   "type": "module",
   "main": "./lib/index.js",
@@ -90,19 +90,19 @@
     "ajv": "^8.18.0",
     "he": "^1.2.0",
     "js-yaml": "^5.2.2",
-    "@zhin.js/adapter": "1.1.21",
-    "@zhin.js/agent-feature": "1.1.8",
-    "@zhin.js/ai": "1.1.43",
-    "@zhin.js/core": "1.1.49",
-    "@zhin.js/im-contract": "1.1.5",
+    "@zhin.js/adapter": "1.1.22",
+    "@zhin.js/agent-feature": "1.1.9",
+    "@zhin.js/ai": "1.1.45",
+    "@zhin.js/core": "1.1.50",
+    "@zhin.js/im-contract": "1.1.6",
     "@zhin.js/kernel": "1.1.5",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/mcp-feature": "1.1.8",
-    "@zhin.js/permission": "1.1.7",
-    "@zhin.js/plugin-runtime": "1.1.15",
-    "@zhin.js/prompt-section": "1.1.7",
-    "@zhin.js/skill": "1.1.8",
-    "@zhin.js/tool": "1.1.8"
+    "@zhin.js/mcp-feature": "1.1.9",
+    "@zhin.js/permission": "1.1.8",
+    "@zhin.js/plugin-runtime": "1.1.16",
+    "@zhin.js/prompt-section": "1.1.8",
+    "@zhin.js/skill": "1.1.9",
+    "@zhin.js/tool": "1.1.9"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",