@amalgm/chat 0.1.0

package/dist/usage/normalize.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Usage normalization — engine `chat-core/usage.js:65-116,204-206`, ported
+ * byte-exact. Every provider-flavored usage payload (Claude SDK snake_case,
+ * OpenAI camelCase, codex cumulative meters, opencode step records) funnels
+ * through `normalizeUsage` into one canonical `NormalizedUsage` shape.
+ */
+import { type TokenList } from './tokens.js';
+/**
+ * Engine `positiveOrNull()`: the numeric value when finite and > 0, else
+ * null.
+ */
+export declare function positiveOrNull(value: unknown): number | null;
+/**
+ * Loose input accepted by `normalizeUsage` — the union of every key
+ * spelling the engine recognizes across providers.
+ */
+export interface UsageInput {
+    tokenList?: unknown;
+    cumulativeTokenList?: unknown;
+    previousCumulativeTokenList?: unknown;
+    /** Non-cached input tokens — unless `inputTokensAreTotal` is set. */
+    inputTokens?: unknown;
+    input_tokens?: unknown;
+    nonCachedInputTokens?: unknown;
+    /** Total input including cache buckets; decomposed into non-cached input. */
+    totalInputTokens?: unknown;
+    promptTokens?: unknown;
+    /** When truthy, `inputTokens` is treated as a total-input figure. */
+    inputTokensAreTotal?: unknown;
+    outputTokens?: unknown;
+    completionTokens?: unknown;
+    output_tokens?: unknown;
+    cacheReadTokens?: unknown;
+    cachedInputTokens?: unknown;
+    cache_read_input_tokens?: unknown;
+    cacheWriteTokens?: unknown;
+    cacheCreationInputTokens?: unknown;
+    cache_creation_input_tokens?: unknown;
+    thoughtTokens?: unknown;
+    reasoningTokens?: unknown;
+    inputContextSize?: unknown;
+    input_context_size?: unknown;
+    contextUsedTokens?: unknown;
+    usedTokens?: unknown;
+    lastUsedTokens?: unknown;
+    contextLimit?: unknown;
+    maxTokens?: unknown;
+    modelContextWindow?: unknown;
+    totalProcessedTokens?: unknown;
+    costUsd?: unknown;
+    costUSD?: unknown;
+    cost?: unknown;
+    marketCostUsd?: unknown;
+    operation?: unknown;
+    usageOperation?: unknown;
+    billable?: unknown;
+    source?: unknown;
+    exact?: unknown;
+}
+/**
+ * The canonical usage record. Laws:
+ * - `costUsd`/`marketCostUsd` are null when unknown — never zero. Zero
+ *   means "measured as free"; null means "not measured".
+ * - `inputTokens` always means non-cached input; total-input figures are
+ *   decomposed by subtracting the cache buckets (clamped at 0).
+ * - `inputContextSize` is the next-turn context footprint (defaults to the
+ *   tokenList total).
+ * - `source` is a free-form provenance string (engine default `'runtime'`);
+ *   well-known values include `'claude_agent_sdk_model_usage'`,
+ *   `'codex_app_server_turn_delta'`, `'codex_app_server_step_sum'`,
+ *   `'pi_rpc_step_sum'`, `'turn_sum'`, `'native_chat_turn'`.
+ */
+export interface NormalizedUsage {
+    tokenList: TokenList;
+    cumulativeTokenList: TokenList | null;
+    previousCumulativeTokenList: TokenList | null;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    thoughtTokens: number;
+    inputContextSize: number;
+    contextUsedTokens: number | null;
+    contextLimit: number | null;
+    usedTokens: number | null;
+    lastUsedTokens: number | null;
+    maxTokens: number | null;
+    totalProcessedTokens: number | null;
+    costUsd: number | null;
+    marketCostUsd: number | null;
+    operation: string;
+    billable: boolean;
+    source: string;
+    exact: boolean;
+}
+/** Engine `normalizeUsage()`, byte-exact including every fallback chain. */
+export declare function normalizeUsage(input?: UsageInput): NormalizedUsage;
+/**
+ * Engine `providerFromModel()`: the provider prefix of a slash-qualified
+ * model id (`'anthropic/claude-sonnet-4.6'` → `'anthropic'`), else null.
+ */
+export declare function providerFromModel(modelId: unknown): string | null;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/usage/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/usage/normalize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAEvF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,SAAS,CAAC;IACrB,mBAAmB,EAAE,SAAS,GAAG,IAAI,CAAC;IACtC,2BAA2B,EAAE,SAAS,GAAG,IAAI,CAAC;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,GAAE,UAAe,GAAG,eAAe,CA8CtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEjE"}

package/dist/usage/normalize.js

@@ -0,0 +1,71 @@
+/**
+ * Usage normalization — engine `chat-core/usage.js:65-116,204-206`, ported
+ * byte-exact. Every provider-flavored usage payload (Claude SDK snake_case,
+ * OpenAI camelCase, codex cumulative meters, opencode step records) funnels
+ * through `normalizeUsage` into one canonical `NormalizedUsage` shape.
+ */
+import { n, nonNegativeOrNull, normalizeTokenList } from './tokens.js';
+/**
+ * Engine `positiveOrNull()`: the numeric value when finite and > 0, else
+ * null.
+ */
+export function positiveOrNull(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+/** Engine `normalizeUsage()`, byte-exact including every fallback chain. */
+export function normalizeUsage(input = {}) {
+    const cacheRead = n(input.cacheReadTokens ?? input.cachedInputTokens ?? input.cache_read_input_tokens);
+    const cacheWrite = n(input.cacheWriteTokens ?? input.cacheCreationInputTokens ?? input.cache_creation_input_tokens);
+    const output = n(input.outputTokens ?? input.completionTokens ?? input.output_tokens);
+    const thought = n(input.thoughtTokens ?? input.reasoningTokens);
+    const totalInput = input.totalInputTokens ?? input.promptTokens ?? (input.inputTokensAreTotal ? input.inputTokens : null);
+    const nonCachedInput = totalInput == null
+        ? n(input.inputTokens ?? input.input_tokens ?? input.nonCachedInputTokens)
+        : Math.max(0, n(totalInput) - cacheRead - cacheWrite);
+    const tokenList = normalizeTokenList({
+        tokenList: input.tokenList,
+        inputTokens: nonCachedInput,
+        outputTokens: output,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+        thoughtTokens: thought,
+    });
+    const inputContextSize = nonNegativeOrNull(input.inputContextSize ?? input.input_context_size)
+        ?? tokenList.total;
+    return {
+        tokenList,
+        cumulativeTokenList: input.cumulativeTokenList && typeof input.cumulativeTokenList === 'object'
+            ? normalizeTokenList({ tokenList: input.cumulativeTokenList })
+            : null,
+        previousCumulativeTokenList: input.previousCumulativeTokenList && typeof input.previousCumulativeTokenList === 'object'
+            ? normalizeTokenList({ tokenList: input.previousCumulativeTokenList })
+            : null,
+        inputTokens: nonCachedInput,
+        outputTokens: output,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+        thoughtTokens: thought,
+        inputContextSize,
+        contextUsedTokens: positiveOrNull(input.contextUsedTokens ?? input.usedTokens ?? inputContextSize),
+        contextLimit: positiveOrNull(input.contextLimit ?? input.maxTokens ?? input.modelContextWindow),
+        usedTokens: positiveOrNull(input.usedTokens ?? input.contextUsedTokens ?? inputContextSize),
+        lastUsedTokens: positiveOrNull(input.lastUsedTokens ?? input.contextUsedTokens ?? input.usedTokens ?? inputContextSize),
+        maxTokens: positiveOrNull(input.maxTokens ?? input.contextLimit ?? input.modelContextWindow),
+        totalProcessedTokens: positiveOrNull(input.totalProcessedTokens),
+        costUsd: (input.costUsd ?? input.costUSD ?? input.cost ?? null),
+        marketCostUsd: (input.marketCostUsd ?? null),
+        operation: String(input.operation || input.usageOperation || 'chat_step'),
+        billable: input.billable !== false,
+        source: (input.source || 'runtime'),
+        exact: input.exact === true,
+    };
+}
+/**
+ * Engine `providerFromModel()`: the provider prefix of a slash-qualified
+ * model id (`'anthropic/claude-sonnet-4.6'` → `'anthropic'`), else null.
+ */
+export function providerFromModel(modelId) {
+    return typeof modelId === 'string' && modelId.includes('/') ? modelId.split('/')[0] ?? null : null;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/usage/normalize.js.map

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

package/dist/usage/ports.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Usage host boundary — the ownership DECISIONS from engine
+ * `chat-core/usage.js` (`beginProxyTurn` :145-148,:159-173 and
+ * `logTurnUsage` :325-351) ported as pure functions, plus the port
+ * interfaces the host implements for the side effects (the proxy
+ * turn-start POST and the usage_logs db write) and the exact
+ * `usage_logs` row shape from engine `chat-server/db.js
+ * buildUsageLogRow` (:507).
+ *
+ * Ownership law: when `authMethod === 'amalgm'` the platform proxy meters
+ * and persists usage itself — the runtime must NOT double-log. Every other
+ * auth method is user-owned: the runtime finalizes the turn locally and
+ * writes one usage row, pricing it from the local catalog when the
+ * provider gave no cost.
+ */
+import { type TurnUsageRecord, type UsageContract } from './finalize.js';
+import type { NormalizedUsage } from './normalize.js';
+export type { UsageContract } from './finalize.js';
+/** Body POSTed to the proxy's `/internal/turn-start` (engine :159-173). */
+export interface BeginProxyTurnBody {
+    sessionId: string | undefined;
+    messageId: string | undefined;
+    agentId: string | undefined;
+    harnessId: string | undefined;
+    authMethod: string | undefined;
+    usageOwner: string;
+    modelId: string | undefined;
+    internalModelId: string | undefined;
+    cliModel: string | undefined;
+    contextWindow: number | null;
+    maxTokens: number | null;
+    cwd: string | undefined;
+    mcpServers: unknown;
+}
+export type BeginProxyTurnDecision = {
+    skipped: true;
+    reason: 'not_amalgm';
+} | {
+    skipped: false;
+    body: BeginProxyTurnBody;
+};
+/**
+ * The pure fork of engine `beginProxyTurn()`: non-amalgm auth skips the
+ * proxy entirely (`'not_amalgm'`); amalgm auth yields the exact
+ * turn-start body for the host's `BillingPort.beginTurn`. Token refresh,
+ * the POST, the 401 retry, and error mapping are host concerns.
+ */
+export declare function decideBeginProxyTurn(contract: UsageContract): BeginProxyTurnDecision;
+/**
+ * Host port for the proxy turn-start POST. The host owns base URL, token
+ * freshness (refresh + 401 retry-once), and mapping non-OK responses to
+ * coded errors (`AMALGM_PROXY_NOT_CONFIGURED`, `AMALGM_TURN_START_FAILED`,
+ * `balanceUsd` passthrough).
+ */
+export interface BillingPort {
+    beginTurn(body: BeginProxyTurnBody): Promise<unknown>;
+}
+/** Camel-case payload the engine hands to `db.logUsage` (:339-349). */
+export interface UsageLogPayload {
+    userId: string | undefined;
+    sessionId: string | undefined;
+    messageId: string | undefined;
+    agentId: string | undefined;
+    harnessId: string | undefined;
+    authMethod: string | undefined;
+    modelId: string | undefined;
+    usage: NormalizedUsage;
+    marketCostUsd: number | null;
+}
+/**
+ * The exact `usage_logs` row from engine `chat-server/db.js
+ * buildUsageLogRow` (:507). Note the boundary law: `NormalizedUsage`
+ * keeps unknown cost as null, but the persisted row coerces
+ * `cost_usd`/`market_cost_usd` to 0 (engine `?? 0`).
+ */
+export interface UsageLogRow {
+    user_id: string | undefined;
+    session_id: string | null;
+    message_id: string | null;
+    agent_id: string | null;
+    harness_id: string | null;
+    auth_method: string | null;
+    provider: string | null;
+    model: string | null;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    cost_usd: number;
+    market_cost_usd: number;
+    container_id: string | null;
+}
+/**
+ * Engine `buildUsageLogRow()`, byte-exact — except the engine's
+ * `process.env.AMALGM_CONTAINER_ID` read becomes the documented
+ * `options.containerId` parameter (falsy → null, matching the engine's
+ * `|| null`).
+ */
+export declare function buildUsageLogRow({ userId, sessionId, messageId, agentId, harnessId, authMethod, modelId, usage, marketCostUsd }: UsageLogPayload, options?: {
+    containerId?: string | null | undefined;
+}): UsageLogRow;
+/** Host port for the usage_logs write (engine `db.logUsage`). */
+export interface UsageLogPort {
+    logUsage(row: UsageLogRow): Promise<void>;
+}
+export type TurnUsageLogDecision = {
+    skipped: true;
+    source: 'proxy_owned_provider_usage';
+    reason: 'proxy_persists_usage_immediately';
+} | {
+    skipped: true;
+    reason: 'no_turn_usage';
+} | {
+    skipped: false;
+    source: 'local_turn_exact';
+    count: 1;
+    log: UsageLogPayload;
+};
+export interface DecideTurnUsageLogArgs {
+    contract: UsageContract;
+    messageId?: string | undefined;
+    usage?: NormalizedUsage | null | undefined;
+    usageRecords?: readonly TurnUsageRecord[] | null | undefined;
+}
+/**
+ * The pure decision of engine `logTurnUsage()` (:325-351):
+ *
+ * - amalgm auth → skip `{ skipped: true, source:
+ *   'proxy_owned_provider_usage', reason: 'proxy_persists_usage_immediately' }`
+ *   (the proxy already persisted usage; logging here would double-bill).
+ * - no finalizable turn usage → skip `{ skipped: true, reason:
+ *   'no_turn_usage' }`.
+ * - otherwise → `{ skipped: false, source: 'local_turn_exact', count: 1 }`
+ *   with the exact `db.logUsage` payload; `marketCostUsd` falls back to the
+ *   local catalog (`calculateCost`) when the finalized usage carries none.
+ *
+ * The host performs the write:
+ * `usageLogPort.logUsage(buildUsageLogRow(decision.log, { containerId }))`.
+ */
+export declare function decideTurnUsageLog({ contract, messageId, usage, usageRecords }: DecideTurnUsageLogArgs): TurnUsageLogDecision;
+//# sourceMappingURL=ports.d.ts.map

package/dist/usage/ports.d.ts.map

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

package/dist/usage/ports.js

@@ -0,0 +1,113 @@
+/**
+ * Usage host boundary — the ownership DECISIONS from engine
+ * `chat-core/usage.js` (`beginProxyTurn` :145-148,:159-173 and
+ * `logTurnUsage` :325-351) ported as pure functions, plus the port
+ * interfaces the host implements for the side effects (the proxy
+ * turn-start POST and the usage_logs db write) and the exact
+ * `usage_logs` row shape from engine `chat-server/db.js
+ * buildUsageLogRow` (:507).
+ *
+ * Ownership law: when `authMethod === 'amalgm'` the platform proxy meters
+ * and persists usage itself — the runtime must NOT double-log. Every other
+ * auth method is user-owned: the runtime finalizes the turn locally and
+ * writes one usage row, pricing it from the local catalog when the
+ * provider gave no cost.
+ */
+import { finalizeTurnUsage } from './finalize.js';
+import { calculateCost } from './model-catalog.js';
+/**
+ * The pure fork of engine `beginProxyTurn()`: non-amalgm auth skips the
+ * proxy entirely (`'not_amalgm'`); amalgm auth yields the exact
+ * turn-start body for the host's `BillingPort.beginTurn`. Token refresh,
+ * the POST, the 401 retry, and error mapping are host concerns.
+ */
+export function decideBeginProxyTurn(contract) {
+    if (contract.authMethod !== 'amalgm') {
+        return { skipped: true, reason: 'not_amalgm' };
+    }
+    return {
+        skipped: false,
+        body: {
+            sessionId: contract.sessionId,
+            messageId: contract.assistantMessageId,
+            agentId: contract.agentId,
+            harnessId: contract.harness,
+            authMethod: contract.authMethod,
+            usageOwner: contract.usageOwner || 'platform_proxy',
+            modelId: contract.usageModelId || contract.modelId,
+            internalModelId: contract.modelId,
+            cliModel: contract.cliModel,
+            contextWindow: contract.contextWindow ?? null,
+            maxTokens: contract.maxTokens ?? null,
+            cwd: contract.cwd,
+            mcpServers: contract.mcpServers,
+        },
+    };
+}
+/**
+ * Engine `buildUsageLogRow()`, byte-exact — except the engine's
+ * `process.env.AMALGM_CONTAINER_ID` read becomes the documented
+ * `options.containerId` parameter (falsy → null, matching the engine's
+ * `|| null`).
+ */
+export function buildUsageLogRow({ userId, sessionId, messageId, agentId, harnessId, authMethod, modelId, usage, marketCostUsd }, options = {}) {
+    const provider = modelId?.split('/')[0] || null;
+    return {
+        user_id: userId,
+        session_id: sessionId || null,
+        message_id: messageId || null,
+        agent_id: agentId || null,
+        harness_id: harnessId || null,
+        auth_method: authMethod || null,
+        provider,
+        model: modelId || null,
+        input_tokens: usage.inputTokens || 0,
+        output_tokens: usage.outputTokens || 0,
+        cache_read_tokens: usage.cacheReadTokens || 0,
+        cache_write_tokens: usage.cacheWriteTokens || 0,
+        cost_usd: usage.costUsd ?? 0,
+        market_cost_usd: marketCostUsd ?? usage.costUsd ?? 0,
+        container_id: options.containerId || null,
+    };
+}
+/**
+ * The pure decision of engine `logTurnUsage()` (:325-351):
+ *
+ * - amalgm auth → skip `{ skipped: true, source:
+ *   'proxy_owned_provider_usage', reason: 'proxy_persists_usage_immediately' }`
+ *   (the proxy already persisted usage; logging here would double-bill).
+ * - no finalizable turn usage → skip `{ skipped: true, reason:
+ *   'no_turn_usage' }`.
+ * - otherwise → `{ skipped: false, source: 'local_turn_exact', count: 1 }`
+ *   with the exact `db.logUsage` payload; `marketCostUsd` falls back to the
+ *   local catalog (`calculateCost`) when the finalized usage carries none.
+ *
+ * The host performs the write:
+ * `usageLogPort.logUsage(buildUsageLogRow(decision.log, { containerId }))`.
+ */
+export function decideTurnUsageLog({ contract, messageId, usage, usageRecords }) {
+    if (contract.authMethod === 'amalgm') {
+        return { skipped: true, source: 'proxy_owned_provider_usage', reason: 'proxy_persists_usage_immediately' };
+    }
+    const turnUsage = finalizeTurnUsage({ contract, usage, usageRecords });
+    if (!turnUsage)
+        return { skipped: true, reason: 'no_turn_usage' };
+    const marketCostUsd = turnUsage.marketCostUsd ?? calculateCost(contract.usageModelId || contract.modelId, turnUsage.inputTokens, turnUsage.outputTokens, turnUsage.cacheReadTokens, turnUsage.cacheWriteTokens);
+    return {
+        skipped: false,
+        source: 'local_turn_exact',
+        count: 1,
+        log: {
+            userId: contract.userId,
+            sessionId: contract.sessionId,
+            messageId,
+            agentId: contract.agentId,
+            harnessId: contract.harness,
+            authMethod: contract.authMethod,
+            modelId: contract.usageModelId || contract.modelId,
+            usage: turnUsage,
+            marketCostUsd,
+        },
+    };
+}
+//# sourceMappingURL=ports.js.map

package/dist/usage/ports.js.map

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

package/dist/usage/tokens.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Token counting primitives — engine `chat-core/usage.js:11-63,118-127`,
+ * ported byte-exact. Owned by the usage module; the wire module imports
+ * `totalUsageTokens` for PromptUsage projection.
+ */
+/** Engine `n()`: coerce to a finite number, else 0. */
+export declare function n(value: unknown): number;
+/**
+ * Engine `nonNegativeOrNull()`: the numeric value when finite and >= 0,
+ * else null. Note `Number(null)` is 0, so null coerces to 0 here — callers
+ * relying on "absent" must pass `undefined`.
+ */
+export declare function nonNegativeOrNull(value: unknown): number | null;
+/** The six-bucket token list every normalized usage record carries. */
+export interface TokenList {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    thought: number;
+    total: number;
+}
+/**
+ * Loose input accepted by `normalizeTokenList`: either a nested
+ * `tokenList` (short or long key names) or flat `*Tokens` fields.
+ */
+export interface TokenListInput {
+    tokenList?: unknown;
+    inputTokens?: unknown;
+    outputTokens?: unknown;
+    cacheReadTokens?: unknown;
+    cacheWriteTokens?: unknown;
+    thoughtTokens?: unknown;
+    totalTokens?: unknown;
+}
+/**
+ * Engine `normalizeTokenList()`: coerce any of the accepted key spellings
+ * into the canonical six-bucket list. `total` prefers an explicit
+ * non-negative total (nested or flat), else the computed sum of the four
+ * context buckets — `thought` is informational and never counted into the
+ * computed total.
+ */
+export declare function normalizeTokenList(input?: TokenListInput): TokenList;
+/**
+ * Engine `hasTokenListBuckets()`: true when any bucket coerces to a finite
+ * number. Mirrors the engine's `Number()` coercion exactly — `null`
+ * coerces to 0 (finite → true), `undefined` to NaN (→ false).
+ */
+export declare function hasTokenListBuckets(tokenList?: Partial<Record<keyof TokenList, unknown>>): boolean;
+/** Engine `zeroTokenList()`: a fresh all-zero list. */
+export declare function zeroTokenList(): TokenList;
+/**
+ * Engine `addTokenLists()`: bucket-wise sum, re-normalized (so `total` is
+ * recomputed from the four context buckets, never carried over).
+ */
+export declare function addTokenLists(a?: Partial<TokenList>, b?: Partial<TokenList>): TokenList;
+/**
+ * Engine `subtractTokenLists()`: bucket-wise `after - before`, clamped at
+ * 0 per bucket — a cumulative meter that reset (e.g. across compaction)
+ * can never produce a negative delta.
+ */
+export declare function subtractTokenLists(after?: Partial<TokenList>, before?: Partial<TokenList>): TokenList;
+export interface UsageLike {
+    tokenList?: {
+        total?: unknown;
+    } | undefined;
+    inputContextSize?: unknown;
+    inputTokens?: unknown;
+    outputTokens?: unknown;
+    cacheReadTokens?: unknown;
+    cacheWriteTokens?: unknown;
+}
+/**
+ * Total tokens for a usage record: tokenList total, else context size, else
+ * the sum of the four buckets. Precedence uses `||`, exactly as the engine —
+ * a zero total falls through to the next source.
+ */
+export declare function totalUsageTokens(usage?: UsageLike): number;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/usage/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/usage/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uDAAuD;AACvD,wBAAgB,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,cAAmB,GAAG,SAAS,CAoBxE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,OAAO,CAAC,MAAM,CAAC,MAAM,SAAS,EAAE,OAAO,CAAC,CAAM,GAAG,OAAO,CAGtG;AAED,uDAAuD;AACvD,wBAAgB,aAAa,IAAI,SAAS,CAEzC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAE,OAAO,CAAC,SAAS,CAAM,EAAE,CAAC,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAQ/F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,OAAO,CAAC,SAAS,CAAM,EAAE,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAQ7G;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAC;IAC5C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,SAAc,GAAG,MAAM,CAM9D"}

package/dist/usage/tokens.js

@@ -0,0 +1,98 @@
+/**
+ * Token counting primitives — engine `chat-core/usage.js:11-63,118-127`,
+ * ported byte-exact. Owned by the usage module; the wire module imports
+ * `totalUsageTokens` for PromptUsage projection.
+ */
+/** Engine `n()`: coerce to a finite number, else 0. */
+export function n(value) {
+    const parsed = Number(value || 0);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/**
+ * Engine `nonNegativeOrNull()`: the numeric value when finite and >= 0,
+ * else null. Note `Number(null)` is 0, so null coerces to 0 here — callers
+ * relying on "absent" must pass `undefined`.
+ */
+export function nonNegativeOrNull(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+/**
+ * Engine `normalizeTokenList()`: coerce any of the accepted key spellings
+ * into the canonical six-bucket list. `total` prefers an explicit
+ * non-negative total (nested or flat), else the computed sum of the four
+ * context buckets — `thought` is informational and never counted into the
+ * computed total.
+ */
+export function normalizeTokenList(input = {}) {
+    const tokenList = (input.tokenList && typeof input.tokenList === 'object'
+        ? input.tokenList
+        : {});
+    const inputTokens = n(tokenList['input'] ?? tokenList['inputTokens'] ?? input.inputTokens);
+    const outputTokens = n(tokenList['output'] ?? tokenList['outputTokens'] ?? input.outputTokens);
+    const cacheReadTokens = n(tokenList['cacheRead'] ?? tokenList['cacheReadTokens'] ?? input.cacheReadTokens);
+    const cacheWriteTokens = n(tokenList['cacheWrite'] ?? tokenList['cacheWriteTokens'] ?? input.cacheWriteTokens);
+    const thoughtTokens = n(tokenList['thought'] ?? tokenList['thoughtTokens'] ?? input.thoughtTokens);
+    const computedTotal = inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens;
+    const total = nonNegativeOrNull(tokenList['total'] ?? tokenList['totalTokens'] ?? input.totalTokens)
+        ?? computedTotal;
+    return {
+        input: inputTokens,
+        output: outputTokens,
+        cacheRead: cacheReadTokens,
+        cacheWrite: cacheWriteTokens,
+        thought: thoughtTokens,
+        total,
+    };
+}
+/**
+ * Engine `hasTokenListBuckets()`: true when any bucket coerces to a finite
+ * number. Mirrors the engine's `Number()` coercion exactly — `null`
+ * coerces to 0 (finite → true), `undefined` to NaN (→ false).
+ */
+export function hasTokenListBuckets(tokenList = {}) {
+    return ['input', 'output', 'cacheRead', 'cacheWrite', 'thought', 'total']
+        .some((key) => Number.isFinite(Number(tokenList[key])));
+}
+/** Engine `zeroTokenList()`: a fresh all-zero list. */
+export function zeroTokenList() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, thought: 0, total: 0 };
+}
+/**
+ * Engine `addTokenLists()`: bucket-wise sum, re-normalized (so `total` is
+ * recomputed from the four context buckets, never carried over).
+ */
+export function addTokenLists(a = {}, b = {}) {
+    return normalizeTokenList({
+        inputTokens: n(a.input) + n(b.input),
+        outputTokens: n(a.output) + n(b.output),
+        cacheReadTokens: n(a.cacheRead) + n(b.cacheRead),
+        cacheWriteTokens: n(a.cacheWrite) + n(b.cacheWrite),
+        thoughtTokens: n(a.thought) + n(b.thought),
+    });
+}
+/**
+ * Engine `subtractTokenLists()`: bucket-wise `after - before`, clamped at
+ * 0 per bucket — a cumulative meter that reset (e.g. across compaction)
+ * can never produce a negative delta.
+ */
+export function subtractTokenLists(after = {}, before = {}) {
+    return normalizeTokenList({
+        inputTokens: Math.max(0, n(after.input) - n(before.input)),
+        outputTokens: Math.max(0, n(after.output) - n(before.output)),
+        cacheReadTokens: Math.max(0, n(after.cacheRead) - n(before.cacheRead)),
+        cacheWriteTokens: Math.max(0, n(after.cacheWrite) - n(before.cacheWrite)),
+        thoughtTokens: Math.max(0, n(after.thought) - n(before.thought)),
+    });
+}
+/**
+ * Total tokens for a usage record: tokenList total, else context size, else
+ * the sum of the four buckets. Precedence uses `||`, exactly as the engine —
+ * a zero total falls through to the next source.
+ */
+export function totalUsageTokens(usage = {}) {
+    return (n(usage.tokenList?.total) ||
+        n(usage.inputContextSize) ||
+        n(usage.inputTokens) + n(usage.outputTokens) + n(usage.cacheReadTokens) + n(usage.cacheWriteTokens));
+}
+//# sourceMappingURL=tokens.js.map

package/dist/usage/tokens.js.map

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