glirastes 0.4.0 → 0.5.0

package/dist/cjs/runtime/local-signer.d.ts

@@ -0,0 +1,17 @@
+import type { RevisionSignature } from '../contracts/revisions.js';
+import { type RuntimePublicJwk } from '../sync/signature-verifier.js';
+export interface LocalRevisionSigner {
+    readonly keyId: string;
+    readonly publicKeyJwk: RuntimePublicJwk;
+    sign<T extends object>(unsigned: T): T & {
+        signature: RevisionSignature;
+    };
+}
+/**
+ * Standalone mode has no control plane and therefore no platform signing
+ * key. It still never lets unsigned data into the runtime: every locally
+ * materialized revision is signed with an ephemeral Ed25519 key generated
+ * at boot, and verifies through the exact same verifier chain managed
+ * revisions use. The key never leaves the process and dies with it.
+ */
+export declare function createEphemeralLocalSigner(): LocalRevisionSigner;

package/dist/cjs/runtime/local-signer.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEphemeralLocalSigner = createEphemeralLocalSigner;
+const node_crypto_1 = require("node:crypto");
+const signature_verifier_js_1 = require("../sync/signature-verifier.js");
+/**
+ * Standalone mode has no control plane and therefore no platform signing
+ * key. It still never lets unsigned data into the runtime: every locally
+ * materialized revision is signed with an ephemeral Ed25519 key generated
+ * at boot, and verifies through the exact same verifier chain managed
+ * revisions use. The key never leaves the process and dies with it.
+ */
+function createEphemeralLocalSigner() {
+    const { publicKey, privateKey } = (0, node_crypto_1.generateKeyPairSync)('ed25519');
+    const keyId = (0, node_crypto_1.createHash)('sha256')
+        .update(publicKey.export({ type: 'spki', format: 'der' }))
+        .digest('hex')
+        .slice(0, 16);
+    const publicKeyJwk = {
+        ...publicKey.export({ format: 'jwk' }),
+        kid: keyId,
+    };
+    return {
+        keyId,
+        publicKeyJwk,
+        sign(unsigned) {
+            const value = (0, node_crypto_1.sign)(null, Buffer.from((0, signature_verifier_js_1.canonicalRuntimeJson)(unsigned)), privateKey).toString('base64url');
+            return {
+                ...unsigned,
+                signature: { algorithm: 'Ed25519', keyId, value },
+            };
+        },
+    };
+}

package/dist/cjs/runtime/local-tool-bindings.d.ts

@@ -0,0 +1,57 @@
+import type { ManifestTool } from '../contracts/revisions.js';
+import type { EndpointMethod, SchemaLike, Tool, ToolRegistry } from '../types.js';
+import type { TurnSnapshot } from './turn-snapshot.js';
+export declare function createLocalSchemaDigest(schema: SchemaLike | undefined): string;
+interface LocalToolBindingBase {
+    /** Stable UUID assigned by the control plane and synced into the target app. */
+    toolId: string;
+    /** Fingerprint derived locally from the bound source route. */
+    sourceFingerprint: string;
+    inputSchemaDigest: string;
+    outputSchemaDigest: string;
+    /** Local schema and executor; never transmitted to the control plane. */
+    tool: Tool;
+}
+export interface LocalEndpointToolBinding extends LocalToolBindingBase {
+    executionKind: 'endpoint';
+    method: EndpointMethod;
+    path: string;
+}
+export interface LocalUiToolBinding extends LocalToolBindingBase {
+    executionKind: 'ui';
+    actionBindingRef: string;
+}
+export type LocalToolBinding = LocalEndpointToolBinding | LocalUiToolBinding;
+/**
+ * Names of the technical facts on which a local binding disagrees with its
+ * signed manifest entry. Names only, never values or content.
+ */
+export declare function localToolBindingMismatches(binding: LocalToolBinding, manifestTool: ManifestTool): string[];
+export declare function assertLocalToolBindingMatches(binding: LocalToolBinding, manifestTool: ManifestTool): void;
+/**
+ * Tool names are either dotted definitionIds with camelCase segments
+ * (`ui.navigate`, `tasks.bulkUpdateStatus`) — the managed manifest's name
+ * domain — or historical snake_case names.
+ */
+export declare const TOOL_NAME_PATTERN: RegExp;
+/**
+ * Model providers reject '.' in function names (^[a-zA-Z0-9_-]+$). The signed
+ * manifest name stays the identity; this is only its deterministic model-safe
+ * encoding. Collisions after encoding fail closed at materialization.
+ */
+export declare function modelFacingToolName(manifestName: string): string;
+export type ToolRegistryDiagnosticReason = 'local-binding-missing' | 'local-binding-mismatch' | 'runtime-policy-missing' | 'runtime-policy-risk-below-manifest';
+export interface ToolRegistryDiagnostic {
+    code: 'E-BINDING-010' | 'E-BINDING-011' | 'E-POLICY-010' | 'E-POLICY-011';
+    reason: ToolRegistryDiagnosticReason;
+    toolId: string;
+    /** Names of mismatched technical facts; never values or content. */
+    mismatches?: string[];
+}
+export declare function materializeManifestToolRegistry(options: {
+    snapshot: TurnSnapshot;
+    bindings: ReadonlyArray<LocalToolBinding>;
+    /** Receives one content-free diagnostic per tool that stays unavailable. */
+    onToolUnavailable?: (diagnostic: ToolRegistryDiagnostic) => void;
+}): ToolRegistry;
+export {};

package/dist/cjs/runtime/local-tool-bindings.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_NAME_PATTERN = void 0;
+exports.createLocalSchemaDigest = createLocalSchemaDigest;
+exports.localToolBindingMismatches = localToolBindingMismatches;
+exports.assertLocalToolBindingMatches = assertLocalToolBindingMatches;
+exports.modelFacingToolName = modelFacingToolName;
+exports.materializeManifestToolRegistry = materializeManifestToolRegistry;
+const node_crypto_1 = require("node:crypto");
+const tool_policy_js_1 = require("../contracts/tool-policy.js");
+function canonicalSchemaValue(value, ancestors = []) {
+    if (value === null
+        || typeof value === 'string'
+        || typeof value === 'number'
+        || typeof value === 'boolean') {
+        return value;
+    }
+    if (value === undefined)
+        return { type: 'undefined' };
+    if (typeof value === 'bigint')
+        return { bigint: value.toString() };
+    if (typeof value === 'function')
+        return { function: true };
+    if (typeof value !== 'object')
+        return { type: typeof value };
+    if (value instanceof Date)
+        return { date: value.toISOString() };
+    if (value instanceof RegExp)
+        return { regexp: value.toString() };
+    if (ancestors.includes(value))
+        return { circular: true };
+    const nextAncestors = [...ancestors, value];
+    const schemaDefinition = value._zod?.def ?? value._def;
+    if (schemaDefinition) {
+        return {
+            schema: canonicalSchemaValue(schemaDefinition, nextAncestors),
+        };
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => canonicalSchemaValue(entry, nextAncestors));
+    }
+    if (value instanceof Map) {
+        return [...value.entries()]
+            .map(([key, entry]) => [
+            canonicalSchemaValue(key, nextAncestors),
+            canonicalSchemaValue(entry, nextAncestors),
+        ])
+            .sort(([left], [right]) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    }
+    if (value instanceof Set) {
+        return [...value]
+            .map((entry) => canonicalSchemaValue(entry, nextAncestors))
+            .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    }
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => {
+        const child = value[key];
+        const canonicalChild = ((key === 'shape' || key === 'getter')
+            && typeof child === 'function')
+            ? canonicalSchemaValue(child(), nextAncestors)
+            : canonicalSchemaValue(child, nextAncestors);
+        return [key, canonicalChild];
+    }));
+}
+function createLocalSchemaDescriptor(schema) {
+    return JSON.stringify(canonicalSchemaValue(schema));
+}
+function createLocalSchemaDigest(schema) {
+    const canonical = createLocalSchemaDescriptor(schema);
+    return `sha256:${(0, node_crypto_1.createHash)('sha256')
+        .update(canonical)
+        .digest('base64url')}`;
+}
+/**
+ * Names of the technical facts on which a local binding disagrees with its
+ * signed manifest entry. Names only, never values or content.
+ */
+function localToolBindingMismatches(binding, manifestTool) {
+    const mismatches = [];
+    if (binding.executionKind !== manifestTool.executionKind) {
+        mismatches.push('execution kind');
+    }
+    if (binding.sourceFingerprint !== manifestTool.sourceFingerprint) {
+        mismatches.push('source fingerprint');
+    }
+    if (binding.inputSchemaDigest !== manifestTool.inputSchemaDigest) {
+        mismatches.push('input schema digest');
+    }
+    if (binding.outputSchemaDigest !== manifestTool.outputSchemaDigest) {
+        mismatches.push('output schema digest');
+    }
+    if (binding.executionKind === 'endpoint'
+        && manifestTool.executionKind === 'endpoint') {
+        if (binding.method !== manifestTool.method)
+            mismatches.push('method');
+        if (binding.path !== manifestTool.path)
+            mismatches.push('path');
+    }
+    if (binding.executionKind === 'ui'
+        && manifestTool.executionKind === 'ui'
+        && binding.actionBindingRef !== manifestTool.actionBindingRef) {
+        mismatches.push('action binding');
+    }
+    return mismatches;
+}
+function assertLocalToolBindingMatches(binding, manifestTool) {
+    const mismatches = localToolBindingMismatches(binding, manifestTool);
+    if (mismatches.length > 0) {
+        throw new Error(`Local tool binding mismatch (${manifestTool.toolId}): `
+            + mismatches.join(', '));
+    }
+}
+/**
+ * Tool names are either dotted definitionIds with camelCase segments
+ * (`ui.navigate`, `tasks.bulkUpdateStatus`) — the managed manifest's name
+ * domain — or historical snake_case names.
+ */
+exports.TOOL_NAME_PATTERN = /^[a-z][a-zA-Z0-9_]*(?:\.[a-zA-Z][a-zA-Z0-9_]*)*$/;
+/**
+ * Model providers reject '.' in function names (^[a-zA-Z0-9_-]+$). The signed
+ * manifest name stays the identity; this is only its deterministic model-safe
+ * encoding. Collisions after encoding fail closed at materialization.
+ */
+function modelFacingToolName(manifestName) {
+    return manifestName.replace(/\./g, '_');
+}
+function reportUnavailableTool(diagnostic) {
+    console.warn('[glirastes] tool disabled for this turn', diagnostic);
+}
+function materializeManifestToolRegistry(options) {
+    const report = options.onToolUnavailable ?? reportUnavailableTool;
+    const bindingsByToolId = new Map();
+    for (const binding of options.bindings) {
+        if (bindingsByToolId.has(binding.toolId)) {
+            throw new Error(`Duplicate local tool binding: ${binding.toolId}`);
+        }
+        bindingsByToolId.set(binding.toolId, binding);
+    }
+    const policiesByToolId = new Map(options.snapshot.policyRevision.toolPolicies.map((policy) => [policy.toolId, policy]));
+    const allowedToolIds = new Set(options.snapshot.agentRevision.toolAllowlist);
+    const registry = {};
+    for (const manifestTool of options.snapshot.manifestRevision.tools) {
+        if (!manifestTool.enabled
+            || manifestTool.tombstone
+            || !allowedToolIds.has(manifestTool.toolId)) {
+            continue;
+        }
+        const toolId = manifestTool.toolId;
+        // Each failure below disables only this tool; the rest keep working.
+        const policy = policiesByToolId.get(toolId);
+        if (!policy) {
+            report({ code: 'E-POLICY-010', reason: 'runtime-policy-missing', toolId });
+            continue;
+        }
+        if (!policy.enabled)
+            continue;
+        // A policy may raise the manifest risk (overlay), never lower it.
+        if ((0, tool_policy_js_1.riskTier)(policy.riskClass) < (0, tool_policy_js_1.riskTier)(manifestTool.riskClass)) {
+            report({
+                code: 'E-POLICY-011',
+                reason: 'runtime-policy-risk-below-manifest',
+                toolId,
+            });
+            continue;
+        }
+        const binding = bindingsByToolId.get(toolId);
+        if (!binding) {
+            report({ code: 'E-BINDING-010', reason: 'local-binding-missing', toolId });
+            continue;
+        }
+        const mismatches = localToolBindingMismatches(binding, manifestTool);
+        if (mismatches.length > 0) {
+            report({
+                code: 'E-BINDING-011',
+                reason: 'local-binding-mismatch',
+                toolId,
+                mismatches,
+            });
+            continue;
+        }
+        const modelName = modelFacingToolName(manifestTool.name);
+        if (registry[modelName]) {
+            throw new Error(`Manifest tool names collide after model-safe encoding: ${modelName}`);
+        }
+        registry[modelName] = {
+            ...binding.tool,
+            id: toolId,
+            description: manifestTool.description,
+            method: manifestTool.executionKind === 'endpoint'
+                ? manifestTool.method
+                : undefined,
+            needsApproval: (0, tool_policy_js_1.confirmationFloor)(policy.riskClass, policy.requiresApproval),
+        };
+    }
+    return registry;
+}

package/dist/cjs/runtime/managed-turn.d.ts

@@ -0,0 +1,29 @@
+import type { Principal, SecurityRevocation } from '../contracts/index.js';
+import type { AiSdkToolCall, AiSdkToolFailure, AiSdkToolSuccess } from './ai-sdk/engine.js';
+import { ExecutionBudgetTracker, type BudgetEvaluation, type ExecutionUsage } from './budget.js';
+import { type TurnSnapshot } from './turn-snapshot.js';
+export interface ManagedTurnBudgetSignal {
+    evaluation: BudgetEvaluation;
+    usage: ExecutionUsage;
+}
+export interface ManagedTurnGuardOptions {
+    snapshot: TurnSnapshot;
+    resolvePrincipal: () => Principal | undefined | Promise<Principal | undefined>;
+    loadRevocations?: (snapshot: TurnSnapshot) => ReadonlyArray<SecurityRevocation> | Promise<ReadonlyArray<SecurityRevocation>>;
+    onBudgetSignal?: (signal: ManagedTurnBudgetSignal) => void | Promise<void>;
+}
+export interface ManagedTurnGuard {
+    readonly snapshot: TurnSnapshot;
+    readonly tracker: ExecutionBudgetTracker;
+    readonly toolTimeoutMs: number;
+    beforeToolCall(call: AiSdkToolCall): Promise<void>;
+    afterModelStep(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        estimatedCostUsd?: number;
+    }): Promise<void>;
+    afterToolCall(call: AiSdkToolSuccess): Promise<void>;
+    onToolError(call: AiSdkToolFailure): Promise<void>;
+    resolveApproval(call: AiSdkToolCall): Promise<boolean>;
+}
+export declare function createManagedTurnGuard(options: ManagedTurnGuardOptions): ManagedTurnGuard;

package/dist/cjs/runtime/managed-turn.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createManagedTurnGuard = createManagedTurnGuard;
+const authorization_js_1 = require("./authorization.js");
+const local_tool_bindings_js_1 = require("./local-tool-bindings.js");
+const budget_js_1 = require("./budget.js");
+const fingerprint_js_1 = require("./fingerprint.js");
+const turn_snapshot_js_1 = require("./turn-snapshot.js");
+function errorResult(result) {
+    return typeof result === 'object'
+        && result !== null
+        && 'error' in result
+        && typeof result.error === 'string';
+}
+function createManagedTurnGuard(options) {
+    const tracker = new budget_js_1.ExecutionBudgetTracker(options.snapshot.budget);
+    const resolveManifestTool = (toolName) => {
+        // Calls arrive under the model-safe encoding of the signed manifest name.
+        const tool = options.snapshot.manifestRevision.tools.find((candidate) => (0, local_tool_bindings_js_1.modelFacingToolName)(candidate.name) === toolName);
+        if (!tool) {
+            throw new Error(`Tool execution denied: manifest_tool_unavailable (${toolName})`);
+        }
+        return tool;
+    };
+    const authorize = async (call) => {
+        const manifestTool = resolveManifestTool(call.toolName);
+        const principal = await options.resolvePrincipal();
+        const authorization = (0, authorization_js_1.authorizeToolCall)({
+            principal,
+            agentRevision: options.snapshot.agentRevision,
+            manifestRevision: options.snapshot.manifestRevision,
+            policyRevision: options.snapshot.policyRevision,
+            toolId: manifestTool.toolId,
+        });
+        if (!authorization.allowed) {
+            throw new Error(`Tool execution denied: ${authorization.reason} (${call.toolName})`);
+        }
+        const revocations = await options.loadRevocations?.(options.snapshot) ?? [];
+        if ((0, turn_snapshot_js_1.isToolRevoked)(options.snapshot, manifestTool.toolId, revocations)) {
+            throw new Error(`Tool execution denied: revoked (${call.toolName})`);
+        }
+        return { authorization, manifestTool };
+    };
+    const emitBudgetSignal = async () => {
+        const evaluation = tracker.evaluate();
+        if (evaluation.state !== 'within-budget') {
+            await options.onBudgetSignal?.({
+                evaluation,
+                usage: tracker.usage,
+            });
+        }
+        return evaluation;
+    };
+    return {
+        snapshot: options.snapshot,
+        tracker,
+        toolTimeoutMs: options.snapshot.budget.toolTimeoutMs,
+        async beforeToolCall(call) {
+            const currentBudget = await emitBudgetSignal();
+            if (currentBudget.state === 'hard-limit') {
+                throw new Error(`Tool execution denied: budget_exhausted (${currentBudget.reasons.join(',')})`);
+            }
+            await authorize(call);
+            tracker.recordToolCall();
+            await emitBudgetSignal();
+        },
+        async afterModelStep(usage) {
+            tracker.recordModelStep();
+            tracker.recordTokens(usage.inputTokens, usage.outputTokens);
+            if (usage.estimatedCostUsd !== undefined) {
+                tracker.recordEstimatedCost(usage.estimatedCostUsd);
+            }
+            await emitBudgetSignal();
+        },
+        async afterToolCall(call) {
+            const { manifestTool } = await authorize(call);
+            tracker.recordFingerprint((0, fingerprint_js_1.createExecutionFingerprint)({
+                toolId: manifestTool.toolId,
+                arguments: call.input,
+                result: call.result,
+            }));
+            if (errorResult(call.result)) {
+                tracker.recordError();
+            }
+            else {
+                tracker.recordSuccess();
+            }
+            await emitBudgetSignal();
+        },
+        async onToolError() {
+            tracker.recordError();
+            await emitBudgetSignal();
+        },
+        async resolveApproval(call) {
+            const { authorization } = await authorize(call);
+            return authorization.requiresApproval;
+        },
+    };
+}

package/dist/cjs/runtime/metrics/cost.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import { type RuntimeTurnCost } from '../../contracts/index.js';
+/**
+ * Prices for models whose provider reports no cost. A provider-reported cost
+ * always wins; the table only fills gaps and every estimate names its
+ * `version`. Glirastes ships no default table: prices change, and a stale
+ * table would be wrong without anyone noticing.
+ */
+export declare const RuntimePriceTableSchema: z.ZodObject<{
+    version: z.ZodString;
+    models: z.ZodRecord<z.ZodString, z.ZodObject<{
+        inputUsdPerMillion: z.ZodNumber;
+        outputUsdPerMillion: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RuntimePriceTable = z.infer<typeof RuntimePriceTableSchema>;
+export declare const UNKNOWN_TURN_COST: RuntimeTurnCost;
+export interface StepCostInput {
+    model: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    /** AI SDK `providerMetadata` of the step. */
+    providerMetadata?: unknown;
+    /** AI SDK `usage.raw` of the step (the provider's own usage object). */
+    usageRaw?: unknown;
+    /**
+     * Cost found in the step's raw stream chunks (`rawChunkCostUsd`). The
+     * OpenAI-compatible provider strips OpenRouter's `usage.cost` from
+     * `usage.raw`; only the raw chunk keeps it.
+     */
+    rawChunkCostUsd?: number | null;
+}
+/**
+ * The cost an OpenRouter stream chunk carries (`usage.cost` of the final
+ * chunk), as delivered by `streamText({ includeRawChunks: true })`.
+ */
+export declare function rawChunkCostUsd(rawValue: unknown): number | null;
+/**
+ * The cost the provider reported for one model step, in USD. Three locations
+ * are read in this order, and they are not equally verified:
+ *
+ * - `providerMetadata.openrouter.usage.cost`, where OpenRouter's official
+ *   provider is documented to put it. Modelled, not measured:
+ *   `@openrouter/ai-sdk-provider` is not a dependency of this package and
+ *   no test runs against it, only hand-written metadata objects.
+ * - `usage.raw.cost`, for a provider that keeps unknown usage fields. Also
+ *   modelled. The OpenAI-compatible provider is not such a provider.
+ * - the raw stream chunk (`rawChunkCostUsd`), the path
+ *   `createOpenAI({ baseURL: 'https://openrouter.ai/api/v1' })` needs.
+ *   Measured in the source of `@ai-sdk/openai` 3.0.53, whose chunk schema
+ *   strips `cost` from `usage.raw`. Whether a live OpenRouter response sends
+ *   `usage.cost` in the final chunk is not verified here.
+ */
+export declare function providerReportedCostUsd(input: {
+    providerMetadata?: unknown;
+    usageRaw?: unknown;
+    rawChunkCostUsd?: number | null;
+}): number | null;
+export declare function resolveStepCost(input: StepCostInput, priceTable?: RuntimePriceTable): RuntimeTurnCost;
+/**
+ * A turn's cost is known only when every model step's cost is known. Any
+ * estimated step makes the whole turn a price-table cost.
+ */
+export declare function combineTurnCost(steps: ReadonlyArray<RuntimeTurnCost>): RuntimeTurnCost;

package/dist/cjs/runtime/metrics/cost.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_TURN_COST = exports.RuntimePriceTableSchema = void 0;
+exports.rawChunkCostUsd = rawChunkCostUsd;
+exports.providerReportedCostUsd = providerReportedCostUsd;
+exports.resolveStepCost = resolveStepCost;
+exports.combineTurnCost = combineTurnCost;
+const zod_1 = require("zod");
+const index_js_1 = require("../../contracts/index.js");
+const usdPerMillion = zod_1.z.number().finite().nonnegative().max(10_000);
+/**
+ * Prices for models whose provider reports no cost. A provider-reported cost
+ * always wins; the table only fills gaps and every estimate names its
+ * `version`. Glirastes ships no default table: prices change, and a stale
+ * table would be wrong without anyone noticing.
+ */
+exports.RuntimePriceTableSchema = zod_1.z.object({
+    version: zod_1.z.string().regex(index_js_1.RUNTIME_PRICING_VERSION_PATTERN),
+    models: zod_1.z.record(zod_1.z.string().regex(index_js_1.RUNTIME_METRIC_LABEL_PATTERN), zod_1.z.object({
+        inputUsdPerMillion: usdPerMillion,
+        outputUsdPerMillion: usdPerMillion,
+    }).strict()),
+}).strict();
+exports.UNKNOWN_TURN_COST = Object.freeze({
+    usd: null,
+    source: null,
+    pricingVersion: null,
+});
+function child(value, key) {
+    return value !== null && typeof value === 'object'
+        ? value[key]
+        : undefined;
+}
+function usableAmount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : null;
+}
+/**
+ * The cost an OpenRouter stream chunk carries (`usage.cost` of the final
+ * chunk), as delivered by `streamText({ includeRawChunks: true })`.
+ */
+function rawChunkCostUsd(rawValue) {
+    return usableAmount(child(child(rawValue, 'usage'), 'cost'));
+}
+/**
+ * The cost the provider reported for one model step, in USD. Three locations
+ * are read in this order, and they are not equally verified:
+ *
+ * - `providerMetadata.openrouter.usage.cost`, where OpenRouter's official
+ *   provider is documented to put it. Modelled, not measured:
+ *   `@openrouter/ai-sdk-provider` is not a dependency of this package and
+ *   no test runs against it, only hand-written metadata objects.
+ * - `usage.raw.cost`, for a provider that keeps unknown usage fields. Also
+ *   modelled. The OpenAI-compatible provider is not such a provider.
+ * - the raw stream chunk (`rawChunkCostUsd`), the path
+ *   `createOpenAI({ baseURL: 'https://openrouter.ai/api/v1' })` needs.
+ *   Measured in the source of `@ai-sdk/openai` 3.0.53, whose chunk schema
+ *   strips `cost` from `usage.raw`. Whether a live OpenRouter response sends
+ *   `usage.cost` in the final chunk is not verified here.
+ */
+function providerReportedCostUsd(input) {
+    return usableAmount(child(child(child(input.providerMetadata, 'openrouter'), 'usage'), 'cost'))
+        ?? usableAmount(child(input.usageRaw, 'cost'))
+        ?? usableAmount(input.rawChunkCostUsd);
+}
+function resolveStepCost(input, priceTable) {
+    const reported = providerReportedCostUsd(input);
+    if (reported !== null) {
+        return { usd: reported, source: 'provider-reported', pricingVersion: null };
+    }
+    const price = input.model && priceTable
+        && Object.hasOwn(priceTable.models, input.model)
+        ? priceTable.models[input.model]
+        : undefined;
+    if (!price || !priceTable)
+        return exports.UNKNOWN_TURN_COST;
+    return {
+        usd: (input.inputTokens * price.inputUsdPerMillion
+            + input.outputTokens * price.outputUsdPerMillion) / 1_000_000,
+        source: 'price-table',
+        pricingVersion: priceTable.version,
+    };
+}
+/**
+ * A turn's cost is known only when every model step's cost is known. Any
+ * estimated step makes the whole turn a price-table cost.
+ */
+function combineTurnCost(steps) {
+    if (steps.length === 0 || steps.some((step) => step.usd === null)) {
+        return exports.UNKNOWN_TURN_COST;
+    }
+    const usd = steps.reduce((sum, step) => sum + (step.usd ?? 0), 0);
+    const estimated = steps.find((step) => step.source === 'price-table');
+    return estimated
+        ? { usd, source: 'price-table', pricingVersion: estimated.pricingVersion }
+        : { usd, source: 'provider-reported', pricingVersion: null };
+}

package/dist/cjs/runtime/metrics/sink.d.ts

@@ -0,0 +1,56 @@
+import type { RuntimeMetricsSink } from './turn-recorder.js';
+export type RuntimeMetricsDropReason = 'invalid' | 'queue-full' | 'send-failed' | 'closed';
+export interface RuntimeMetricsSinkOptions {
+    /** Control-plane base URL (HTTPS, or loopback HTTP for local tests). */
+    controlPlaneUrl: string;
+    /** The app-bound runtime key; sent only in the Authorization header. */
+    apiKey: string;
+    appId: string;
+    environmentId: string;
+    /** Build identifier of the deployed code, e.g. a commit; null if unknown. */
+    buildId?: string | null;
+    /** This process; defaults to a random id per sink. */
+    instanceId?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Events per request, 1–50 (default 50). */
+    maxBatchSize?: number;
+    /** Events waiting for delivery before new ones are dropped (default 1,000). */
+    maxQueueSize?: number;
+    /** Delivery interval (default 5 s). */
+    flushIntervalMs?: number;
+    /** Per-request timeout; a slower Platform loses the batch (default 5 s). */
+    requestTimeoutMs?: number;
+    /** Content-free notice about dropped events, e.g. for local logging. */
+    onDrop?: (drop: {
+        reason: RuntimeMetricsDropReason;
+        count: number;
+    }) => void;
+}
+export interface BatchingRuntimeMetricsSink extends RuntimeMetricsSink {
+    /** Events waiting for delivery. */
+    readonly pending: number;
+}
+/**
+ * Batches turn events and delivers them to the Platform off the turn path.
+ * `record` validates and queues synchronously and never throws; delivery
+ * runs on an unref'd interval or when a batch is full. A failed, rejected or
+ * timed-out request drops its batch: metrics never retry, never block a turn
+ * and never hold the process open.
+ */
+export declare function createRuntimeMetricsSink(options: RuntimeMetricsSinkOptions): BatchingRuntimeMetricsSink;
+/**
+ * The sink of a connected app, or undefined. The key (and the optional
+ * self-hosting URL) come from the environment; the app and environment come
+ * from the connection the runtime looked up (`lookupRuntimeConnection`), so
+ * the sink exists only once that lookup resolved. Standalone apps (no
+ * `GLIRASTES_API_KEY`) get no sink and stay network-silent; an invalid
+ * connection also yields none, because metrics must never stop a chat from
+ * starting. `GLIRASTES_BUILD_ID` (optional) names the deployed build.
+ */
+export declare function createRuntimeMetricsSinkFromEnv(env?: Record<string, string | undefined>, options?: Omit<RuntimeMetricsSinkOptions, 'controlPlaneUrl' | 'apiKey' | 'appId' | 'environmentId' | 'buildId'> & {
+    /** The resolved connection; without it the sink stays absent. */
+    connection?: {
+        appId: string;
+        environmentId: string;
+    };
+}): BatchingRuntimeMetricsSink | undefined;