@ashlr/hub 2.2.0

package/dist/core/observability/forecast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forecast.js","sourceRoot":"","sources":["../../../src/core/observability/forecast.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE5E,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAE1C,8EAA8E;AAC9E,gFAAgF;AAChF,iFAAiF;AACjF,mFAAmF;AACnF,8EAA8E;AAC9E,8EAA8E;AAE9E,mFAAmF;AACnF,MAAM,kBAAkB,GAAI,GAAG,CAAC;AAChC,oFAAoF;AACpF,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC;;;;;;;;;GASG;AACH,SAAS,YAAY,CAAC,QAAgB,EAAE,SAAiB;IACvD,IAAI,QAAQ,IAAI,CAAC,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACvC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,kBAAkB;QACzC,CAAC,OAAO,GAAG,SAAS,CAAC,GAAG,mBAAmB,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAoB,EACpB,GAAgB;IAEhB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAExC,yDAAyD;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAEvD,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,mEAAmE;QACnE,IAAI,eAAe,GAAG,CAAC,CAAC;QACxB,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,IAAI,YAAY,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,eAAe,IAAI,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QACD,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;QAE/C,2EAA2E;QAC3E,mDAAmD;QACnD,iDAAiD;QACjD,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,uBAAuB;QAC3E,MAAM,SAAS,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,MAAM,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC,CAAC;QAExD,OAAO;YACL,MAAM;YACN,QAAQ;YACR,eAAe;YACf,mBAAmB;SACpB,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;QAC5D,OAAO;YACL,MAAM;YACN,QAAQ,EAAE,CAAC;YACX,eAAe,EAAE,CAAC;YAClB,mBAAmB,EAAE,CAAC;SACvB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/observability/governance.d.ts

@@ -0,0 +1,28 @@
+/**
+ * governance.ts — spend-governance evaluation for a configured budget window.
+ *
+ * M19: evalGovernance compares actual spend (from buildForecast/buildRollup)
+ * against the configured budget cap and returns an advisory GovernanceStatus.
+ *
+ * Design rules:
+ *  - ADVISORY ONLY: this function is pure-ish — it never blocks, throws, or
+ *    mutates any state. Callers decide how to act on the verdict.
+ *  - METADATA ONLY: no prompts, completions, tool args, file contents, or
+ *    secrets are ever read or emitted here.
+ *  - NEVER THROWS: all errors are caught; falls back to ok/null-cap verdict.
+ */
+import type { AshlrConfig, GovernanceStatus } from '../types.js';
+/**
+ * Evaluate the spend-governance verdict for the current budget window.
+ *
+ * - When no `cfg.telemetry.budgetUsd` is configured: returns level 'ok' with
+ *   capUsd null and a message indicating no cap is set.
+ * - When a cap is set: uses buildForecast (preferred, also uses buildRollup
+ *   internally) for '7d' and '30d' windows, and falls back to buildRollup
+ *   directly for the '1d' window (buildForecast does not support '1d').
+ * - Levels: 'over' when spentUsd >= cap, 'warn' when >= 80% of cap, else 'ok'.
+ *
+ * Pure-ish: reads local JSONL usage data but never modifies state, never
+ * throws, and never surfaces PAT or secret values.
+ */
+export declare function evalGovernance(cfg: AshlrConfig): GovernanceStatus;

package/dist/core/observability/governance.js

@@ -0,0 +1,101 @@
+/**
+ * governance.ts — spend-governance evaluation for a configured budget window.
+ *
+ * M19: evalGovernance compares actual spend (from buildForecast/buildRollup)
+ * against the configured budget cap and returns an advisory GovernanceStatus.
+ *
+ * Design rules:
+ *  - ADVISORY ONLY: this function is pure-ish — it never blocks, throws, or
+ *    mutates any state. Callers decide how to act on the verdict.
+ *  - METADATA ONLY: no prompts, completions, tool args, file contents, or
+ *    secrets are ever read or emitted here.
+ *  - NEVER THROWS: all errors are caught; falls back to ok/null-cap verdict.
+ */
+import { buildForecast } from './forecast.js';
+import { buildRollup } from './rollup.js';
+// ---------------------------------------------------------------------------
+// Governance thresholds
+// ---------------------------------------------------------------------------
+/** Fraction of cap at which the level escalates from 'ok' to 'warn'. */
+const WARN_THRESHOLD = 0.8;
+// ---------------------------------------------------------------------------
+// evalGovernance
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate the spend-governance verdict for the current budget window.
+ *
+ * - When no `cfg.telemetry.budgetUsd` is configured: returns level 'ok' with
+ *   capUsd null and a message indicating no cap is set.
+ * - When a cap is set: uses buildForecast (preferred, also uses buildRollup
+ *   internally) for '7d' and '30d' windows, and falls back to buildRollup
+ *   directly for the '1d' window (buildForecast does not support '1d').
+ * - Levels: 'over' when spentUsd >= cap, 'warn' when >= 80% of cap, else 'ok'.
+ *
+ * Pure-ish: reads local JSONL usage data but never modifies state, never
+ * throws, and never surfaces PAT or secret values.
+ */
+export function evalGovernance(cfg) {
+    try {
+        const cap = cfg.telemetry?.budgetUsd;
+        // No cap configured — governance has nothing to enforce.
+        if (cap === undefined || cap === null) {
+            return {
+                level: 'ok',
+                spentUsd: 0,
+                capUsd: null,
+                window: cfg.telemetry?.budgetWindow ?? '7d',
+                message: 'No spend cap set.',
+            };
+        }
+        const rawWindow = cfg.telemetry?.budgetWindow ?? '7d';
+        // Obtain actual spend for the window. buildForecast supports '7d'|'30d';
+        // for '1d' we fall back to buildRollup directly (same underlying source).
+        let spentUsd = 0;
+        if (rawWindow === '1d') {
+            const rollup = buildRollup('1d', cfg);
+            spentUsd = Math.max(0, rollup.totals.estCostUsd);
+        }
+        else {
+            // rawWindow is now '7d' | '30d' — safe cast (type guard above handles '1d').
+            const forecastWindow = rawWindow;
+            const forecast = buildForecast(forecastWindow, cfg);
+            spentUsd = Math.max(0, forecast.spentUsd);
+        }
+        const capUsd = Math.max(0, cap);
+        const ratio = capUsd > 0 ? spentUsd / capUsd : (spentUsd > 0 ? Infinity : 0);
+        let level;
+        let message;
+        if (ratio >= 1) {
+            level = 'over';
+            message =
+                `Spend $${spentUsd.toFixed(4)} has exceeded the ${rawWindow} cap ` +
+                    `of $${capUsd.toFixed(2)}. Use --over-budget to proceed when govAction is 'block'.`;
+        }
+        else if (ratio >= WARN_THRESHOLD) {
+            level = 'warn';
+            const pct = (ratio * 100).toFixed(1);
+            message =
+                `Spend $${spentUsd.toFixed(4)} is at ${pct}% of the ${rawWindow} cap ` +
+                    `of $${capUsd.toFixed(2)}.`;
+        }
+        else {
+            level = 'ok';
+            const pct = capUsd > 0 ? (ratio * 100).toFixed(1) : '0.0';
+            message =
+                `Spend $${spentUsd.toFixed(4)} is within the ${rawWindow} cap ` +
+                    `of $${capUsd.toFixed(2)} (${pct}% used).`;
+        }
+        return { level, spentUsd, capUsd, window: rawWindow, message };
+    }
+    catch {
+        // Best-effort fallback — governance must never throw or block a run.
+        return {
+            level: 'ok',
+            spentUsd: 0,
+            capUsd: null,
+            window: cfg.telemetry?.budgetWindow ?? '7d',
+            message: 'Governance evaluation unavailable (internal error).',
+        };
+    }
+}
+//# sourceMappingURL=governance.js.map

package/dist/core/observability/governance.js.map

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

package/dist/core/observability/otlp.d.ts

@@ -0,0 +1,88 @@
+/**
+ * core/observability/otlp.ts — M19 OTLP/HTTP-JSON trace builder.
+ *
+ * Pure, dependency-free helpers that turn a completed run/swarm into:
+ *   - GenAiSpan[]  (spansFromRun / spansFromSwarm) — METADATA ONLY
+ *   - an OTLP/HTTP-JSON trace payload (buildGenAiTrace) following the
+ *     resourceSpans -> scopeSpans -> spans nesting, with GenAI
+ *     semantic-convention attributes.
+ *
+ * PRIVACY INVARIANT (enforced here, asserted by m19.otlp.test.ts):
+ *   Span attributes carry ONLY metadata — model id, token counts, cost, ids,
+ *   provider, tier, status, duration. NEVER prompt/response text, sub-goal
+ *   text, tool args, file contents, project paths, or secrets. The span
+ *   `name` is the task id (a stable metadata identifier), never the goal.
+ *
+ * This module is imported statically by telemetry-sink.ts (buildGenAiTrace)
+ * and dynamically by orchestrator.ts / swarm/runner.ts (spansFromRun /
+ * spansFromSwarm). It must stay free of side effects and runtime deps.
+ */
+import type { GenAiSpan, RunState, SwarmRun } from '../types.js';
+type OtlpValue = {
+    stringValue: string;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+};
+interface OtlpAttribute {
+    key: string;
+    value: OtlpValue;
+}
+interface OtlpSpan {
+    /** 32 lowercase hex chars (16 random bytes). Required by the OTLP data model. */
+    traceId: string;
+    /** 16 lowercase hex chars (8 random bytes). Required by the OTLP data model. */
+    spanId: string;
+    /** OTLP span kind. 1=INTERNAL — GenAI calls are internal work units. */
+    kind: number;
+    name: string;
+    /** Decimal string of unix-nanoseconds. */
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    /** OTLP status object. code 0=unset, 1=ok(unused), 2=error. */
+    status: {
+        code: number;
+    };
+    attributes: OtlpAttribute[];
+}
+interface OtlpScopeSpans {
+    scope: {
+        name: string;
+        version: string;
+    };
+    spans: OtlpSpan[];
+}
+interface OtlpResourceSpans {
+    resource: {
+        attributes: OtlpAttribute[];
+    };
+    scopeSpans: OtlpScopeSpans[];
+}
+export interface OtlpTrace {
+    resourceSpans: OtlpResourceSpans[];
+}
+/**
+ * Build a valid OTLP/HTTP-JSON trace from GenAiSpan metadata.
+ *
+ * Shape: { resourceSpans: [ { resource, scopeSpans: [ { scope, spans } ] } ] }.
+ * Every span carries GenAI semantic-convention attributes plus ashlr.* ids.
+ * Handles an empty `spans` array gracefully (one resourceSpans entry with an
+ * empty spans list). METADATA ONLY — never content.
+ */
+export declare function buildGenAiTrace(spans: GenAiSpan[]): OtlpTrace;
+/**
+ * Derive one GenAiSpan per RunTask that has usage. Pure — does not mutate the
+ * run. Span name is the task id (metadata), NEVER the sub-goal text. No
+ * result/goal text is read into the span. Timestamps fall back to the run's
+ * createdAt/updatedAt window (per-task timestamps are not tracked).
+ */
+export declare function spansFromRun(run: RunState): GenAiSpan[];
+/**
+ * Derive one GenAiSpan per SwarmTaskRun that has usage. Pure — does not mutate
+ * the swarm. Span name is the task id (metadata), NEVER goal/result/project
+ * text. SwarmRun has no per-run provider, so provider/model/tier use neutral
+ * metadata defaults. Timestamps fall back to the swarm's createdAt/updatedAt.
+ */
+export declare function spansFromSwarm(swarm: SwarmRun): GenAiSpan[];
+export {};

package/dist/core/observability/otlp.js

@@ -0,0 +1,217 @@
+/**
+ * core/observability/otlp.ts — M19 OTLP/HTTP-JSON trace builder.
+ *
+ * Pure, dependency-free helpers that turn a completed run/swarm into:
+ *   - GenAiSpan[]  (spansFromRun / spansFromSwarm) — METADATA ONLY
+ *   - an OTLP/HTTP-JSON trace payload (buildGenAiTrace) following the
+ *     resourceSpans -> scopeSpans -> spans nesting, with GenAI
+ *     semantic-convention attributes.
+ *
+ * PRIVACY INVARIANT (enforced here, asserted by m19.otlp.test.ts):
+ *   Span attributes carry ONLY metadata — model id, token counts, cost, ids,
+ *   provider, tier, status, duration. NEVER prompt/response text, sub-goal
+ *   text, tool args, file contents, project paths, or secrets. The span
+ *   `name` is the task id (a stable metadata identifier), never the goal.
+ *
+ * This module is imported statically by telemetry-sink.ts (buildGenAiTrace)
+ * and dynamically by orchestrator.ts / swarm/runner.ts (spansFromRun /
+ * spansFromSwarm). It must stay free of side effects and runtime deps.
+ */
+import { randomBytes } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Instrumentation scope advertised in scopeSpans[].scope. */
+const SCOPE_NAME = 'ashlr-hub';
+const SCOPE_VERSION = '0.1.0';
+/** Nanoseconds per millisecond (OTLP timestamps are unix-nanoseconds). */
+const NS_PER_MS = 1000000n;
+// ---------------------------------------------------------------------------
+// Internal attribute helpers
+// ---------------------------------------------------------------------------
+function strAttr(key, value) {
+    return { key, value: { stringValue: value } };
+}
+/** Integer attribute — OTLP intValue is a decimal string per the JSON mapping. */
+function intAttr(key, value) {
+    const n = Number.isFinite(value) ? Math.trunc(value) : 0;
+    return { key, value: { intValue: String(n) } };
+}
+function doubleAttr(key, value) {
+    return { key, value: { doubleValue: Number.isFinite(value) ? value : 0 } };
+}
+/**
+ * Convert an ISO timestamp to a unix-nanosecond decimal string. Invalid or
+ * missing timestamps fall back to 0 so the builder never throws.
+ */
+function isoToUnixNano(iso) {
+    const ms = Date.parse(iso);
+    if (Number.isNaN(ms))
+        return '0';
+    return (BigInt(ms) * NS_PER_MS).toString();
+}
+/** Map a terminal status string to an OTLP status code (2=error else unset). */
+function statusCode(status) {
+    return status === 'failed' || status === 'aborted' ? 2 : 0;
+}
+/** OTLP SpanKind.INTERNAL — these are internal work units, not RPC client spans. */
+const SPAN_KIND_INTERNAL = 1;
+/** Random 16-byte trace id as 32 lowercase hex chars (OTLP-required identifier). */
+function newTraceId() {
+    return randomBytes(16).toString('hex');
+}
+/** Random 8-byte span id as 16 lowercase hex chars (OTLP-required identifier). */
+function newSpanId() {
+    return randomBytes(8).toString('hex');
+}
+// ---------------------------------------------------------------------------
+// Public: buildGenAiTrace
+// ---------------------------------------------------------------------------
+/**
+ * Build a valid OTLP/HTTP-JSON trace from GenAiSpan metadata.
+ *
+ * Shape: { resourceSpans: [ { resource, scopeSpans: [ { scope, spans } ] } ] }.
+ * Every span carries GenAI semantic-convention attributes plus ashlr.* ids.
+ * Handles an empty `spans` array gracefully (one resourceSpans entry with an
+ * empty spans list). METADATA ONLY — never content.
+ */
+export function buildGenAiTrace(spans) {
+    // One trace id per emitted batch; per-span ids below. Random bytes carry no
+    // content — still METADATA ONLY. Required by the OTLP data model and by
+    // backends (Tempo/Jaeger/Honeycomb) that drop zero/empty-id spans.
+    const traceId = newTraceId();
+    const otlpSpans = spans.map((s) => {
+        const start = isoToUnixNano(s.startTs);
+        let end = isoToUnixNano(s.endTs);
+        // Guarantee end >= start even if timestamps are equal/inverted.
+        if (BigInt(end) < BigInt(start))
+            end = start;
+        return {
+            traceId,
+            spanId: newSpanId(),
+            kind: SPAN_KIND_INTERNAL,
+            // name is the task id (metadata identifier) — never goal/result text.
+            name: s.name,
+            startTimeUnixNano: start,
+            endTimeUnixNano: end,
+            status: { code: statusCode(s.status) },
+            attributes: [
+                strAttr('gen_ai.system', s.provider),
+                strAttr('gen_ai.request.model', s.model),
+                intAttr('gen_ai.usage.input_tokens', s.tokensIn),
+                intAttr('gen_ai.usage.output_tokens', s.tokensOut),
+                doubleAttr('gen_ai.usage.cost_usd', s.estCostUsd),
+                strAttr('ashlr.run.id', s.runId),
+                strAttr('ashlr.provider', s.provider),
+                strAttr('ashlr.tier', s.tier),
+                strAttr('ashlr.status', s.status),
+            ],
+        };
+    });
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        strAttr('service.name', SCOPE_NAME),
+                        strAttr('telemetry.sdk.name', SCOPE_NAME),
+                        strAttr('telemetry.sdk.language', 'nodejs'),
+                    ],
+                },
+                scopeSpans: [
+                    {
+                        scope: { name: SCOPE_NAME, version: SCOPE_VERSION },
+                        spans: otlpSpans,
+                    },
+                ],
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Provider/model/tier derivation (metadata only)
+// ---------------------------------------------------------------------------
+const CLOUD_PROVIDERS = new Set(['anthropic', 'openai', 'google', 'bedrock', 'azure']);
+/** Cloud vs local tier, inferred from the provider id (metadata only). */
+function tierForProvider(provider) {
+    return CLOUD_PROVIDERS.has(provider.toLowerCase()) ? 'cloud' : 'local';
+}
+/**
+ * A coarse model label derived from the provider — we never expose the actual
+ * routed model name when it isn't tracked per-task, only a metadata stand-in.
+ * The provider itself is metadata and safe to surface.
+ */
+function modelForProvider(provider) {
+    return provider || 'unknown';
+}
+// ---------------------------------------------------------------------------
+// Public: spansFromRun
+// ---------------------------------------------------------------------------
+/**
+ * Derive one GenAiSpan per RunTask that has usage. Pure — does not mutate the
+ * run. Span name is the task id (metadata), NEVER the sub-goal text. No
+ * result/goal text is read into the span. Timestamps fall back to the run's
+ * createdAt/updatedAt window (per-task timestamps are not tracked).
+ */
+export function spansFromRun(run) {
+    const provider = run.provider || 'unknown';
+    const model = modelForProvider(provider);
+    const tier = tierForProvider(provider);
+    const startTs = run.createdAt;
+    const endTs = run.updatedAt;
+    const spans = [];
+    for (const task of run.tasks) {
+        if (!task.usage)
+            continue;
+        spans.push({
+            name: task.id, // metadata id, NOT task.goal
+            runId: run.id,
+            model,
+            provider,
+            tier,
+            tokensIn: task.usage.tokensIn,
+            tokensOut: task.usage.tokensOut,
+            estCostUsd: task.usage.estCostUsd,
+            status: task.status,
+            startTs,
+            endTs,
+        });
+    }
+    return spans;
+}
+// ---------------------------------------------------------------------------
+// Public: spansFromSwarm
+// ---------------------------------------------------------------------------
+/**
+ * Derive one GenAiSpan per SwarmTaskRun that has usage. Pure — does not mutate
+ * the swarm. Span name is the task id (metadata), NEVER goal/result/project
+ * text. SwarmRun has no per-run provider, so provider/model/tier use neutral
+ * metadata defaults. Timestamps fall back to the swarm's createdAt/updatedAt.
+ */
+export function spansFromSwarm(swarm) {
+    const provider = 'ashlr-swarm';
+    const model = 'swarm';
+    const tier = 'local';
+    const startTs = swarm.createdAt;
+    const endTs = swarm.updatedAt;
+    const spans = [];
+    for (const task of swarm.tasks) {
+        if (!task.usage)
+            continue;
+        spans.push({
+            name: task.id, // metadata id, NOT goal/result/project
+            runId: swarm.id,
+            model,
+            provider,
+            tier,
+            tokensIn: task.usage.tokensIn,
+            tokensOut: task.usage.tokensOut,
+            estCostUsd: task.usage.estCostUsd,
+            status: task.status,
+            startTs,
+            endTs,
+        });
+    }
+    return spans;
+}
+//# sourceMappingURL=otlp.js.map

package/dist/core/observability/otlp.js.map

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

package/dist/core/observability/rollup.d.ts

@@ -0,0 +1,35 @@
+/**
+ * rollup.ts — build ActivityRollup from local usage events + git commit counts.
+ *
+ * Privacy: delegates to collectUsageEvents which reads METADATA ONLY.
+ * Performance: skips files outside the window (mtime filtering in usage-source),
+ *   git log --since is bounded per-repo, never throws globally.
+ */
+import type { AshlrConfig, ActivityRollup } from '../types.js';
+/**
+ * Convert a window label to milliseconds.
+ * Unknown labels fall back to 7d.
+ */
+export declare function windowToMs(window: string): number;
+/**
+ * Derive a provider key from a model id so estCostUsd() can match it.
+ *
+ * Examples:
+ *   'claude-3-5-sonnet-20241022' -> 'claude'
+ *   'gpt-4o'                     -> 'gpt'
+ *   'gemini-1.5-pro'             -> 'gemini'
+ *   'ollama/llama3'              -> 'ollama'
+ *   unknown                      -> model id as-is (budget fallback applies)
+ */
+export declare function modelToProviderKey(model: string): string;
+/**
+ * Local (zero-cost) provider keys. A model whose `modelToProviderKey` lands in
+ * this set is served by a LOCAL backend and costs $0. Shared with forecast.ts so
+ * the local/cloud split stays consistent across rollup and savings computation.
+ */
+export declare const LOCAL_PROVIDER_KEYS: ReadonlySet<string>;
+/** True when `model` is served by a local provider (cost $0). */
+export declare function isLocalProviderModel(model: string): boolean;
+export declare function buildRollup(window: '1d' | '7d' | '30d', cfg: AshlrConfig, opts?: {
+    project?: string;
+}): ActivityRollup;