@mc1global/opencode-jarvis 0.1.0

package/dist/application/rag/use-cases.js

@@ -0,0 +1,234 @@
+import { ok, fail } from "../../domain/shared/value-objects.js";
+import { EXTENSION_LANGUAGE_MAP, DEFAULT_CHUNK_CONFIGS, inferDomain, } from "../../domain/rag/value-objects.js";
+import { extractSnippet } from "../../domain/rag/services.js";
+import { extname } from "node:path";
+// ── Use Cases ─────────────────────────────────────────────────────────
+export class RagUseCases {
+    embedding;
+    vectors;
+    splitter;
+    files;
+    constructor(deps) {
+        this.embedding = deps.embeddingProvider;
+        this.vectors = deps.vectorRepository;
+        this.splitter = deps.textSplitter;
+        this.files = deps.fileDiscovery;
+    }
+    // ── Search ──────────────────────────────────────────────────────
+    async search(request) {
+        try {
+            const queryVector = await this.embedding.embed(request.query);
+            const results = await this.vectors.search(queryVector, {
+                topK: request.topK ?? 5,
+                workspace: request.workspace,
+                ...(request.domainFilter !== undefined
+                    ? { domainFilter: request.domainFilter }
+                    : {}),
+                ...(request.typeFilter !== undefined
+                    ? { typeFilter: request.typeFilter }
+                    : {}),
+            });
+            return ok({
+                results: results.map((r) => ({
+                    score: r.score,
+                    source: r.source,
+                    domain: r.domain,
+                    fileType: r.fileType,
+                    content: r.content,
+                })),
+                workspace: request.workspace,
+                query: request.query,
+            });
+        }
+        catch (error) {
+            return fail(`RAG search failed: ${String(error)}`);
+        }
+    }
+    // ── Index ───────────────────────────────────────────────────────
+    async index(request) {
+        try {
+            const workspace = request.workspace.toLowerCase();
+            // Discover files
+            const analysis = await this.files.discover(request.directory);
+            // Clear if requested
+            if (request.clear === true) {
+                await this.vectors.clearIndex(workspace);
+            }
+            // Ensure index exists
+            await this.vectors.ensureIndex(workspace);
+            // Create .ragignore if not present
+            await this.files.createRagignore(request.directory, analysis.projectType);
+            let totalChunks = 0;
+            // Process each file
+            for (const file of analysis.files) {
+                const content = await this.files.readFile(file.absolutePath);
+                if (content === null || content.trim().length === 0)
+                    continue;
+                const ext = extname(file.absolutePath).toLowerCase();
+                const language = EXTENSION_LANGUAGE_MAP.get(ext);
+                const config = DEFAULT_CHUNK_CONFIGS.get(language ?? "default") ??
+                    DEFAULT_CHUNK_CONFIGS.get("default");
+                const textChunks = await this.splitter.split(content, language, config);
+                if (textChunks.length === 0)
+                    continue;
+                // Generate embeddings in batch
+                const texts = textChunks.map((c) => c.content);
+                const vectors = await this.embedding.embedBatch(texts);
+                const domain = inferDomain(file.relativePath);
+                const fileType = ext.startsWith(".") ? ext.slice(1) : ext;
+                const chunks = textChunks.map((chunk, i) => ({
+                    vector: vectors[i],
+                    metadata: {
+                        source: file.absolutePath,
+                        workspace,
+                        domain,
+                        fileType,
+                        chunkIndex: chunk.index,
+                        totalChunks: textChunks.length,
+                        content: chunk.content,
+                    },
+                }));
+                await this.vectors.addChunks(workspace, chunks);
+                totalChunks += chunks.length;
+            }
+            return ok({
+                workspace,
+                projectType: analysis.projectType,
+                filesIndexed: analysis.files.length,
+                chunksCreated: totalChunks,
+                excludedFiles: analysis.excludedCount,
+                totalSizeMb: analysis.totalSizeMb,
+            });
+        }
+        catch (error) {
+            return fail(`RAG index failed: ${String(error)}`);
+        }
+    }
+    // ── Snippet ─────────────────────────────────────────────────────
+    async snippet(request) {
+        try {
+            const queryVector = await this.embedding.embed(request.query);
+            const results = await this.vectors.search(queryVector, {
+                topK: request.topK ?? 5,
+                workspace: request.workspace,
+            });
+            const contextLines = request.contextLines ?? 50;
+            const snippetResults = await Promise.all(results.map(async (r) => {
+                const fileContent = await this.files.readFile(r.source);
+                const snippet = fileContent !== null
+                    ? extractSnippet(fileContent, r.content, contextLines)
+                    : r.content;
+                return {
+                    score: r.score,
+                    source: r.source,
+                    snippet,
+                };
+            }));
+            return ok({
+                results: snippetResults,
+                workspace: request.workspace,
+            });
+        }
+        catch (error) {
+            return fail(`RAG snippet failed: ${String(error)}`);
+        }
+    }
+    // ── Update (re-index single file) ───────────────────────────────
+    async update(request) {
+        try {
+            const workspace = request.workspace.toLowerCase();
+            // Delete existing chunks for this file
+            await this.vectors.ensureIndex(workspace);
+            const removed = await this.vectors.deleteBySource(workspace, request.filePath);
+            // Read and re-index the file
+            const content = await this.files.readFile(request.filePath);
+            if (content === null || content.trim().length === 0) {
+                return ok({
+                    workspace,
+                    filePath: request.filePath,
+                    chunksRemoved: removed,
+                    chunksAdded: 0,
+                });
+            }
+            const ext = extname(request.filePath).toLowerCase();
+            const language = EXTENSION_LANGUAGE_MAP.get(ext);
+            const config = DEFAULT_CHUNK_CONFIGS.get(language ?? "default") ??
+                DEFAULT_CHUNK_CONFIGS.get("default");
+            const textChunks = await this.splitter.split(content, language, config);
+            if (textChunks.length === 0) {
+                return ok({
+                    workspace,
+                    filePath: request.filePath,
+                    chunksRemoved: removed,
+                    chunksAdded: 0,
+                });
+            }
+            const texts = textChunks.map((c) => c.content);
+            const vectors = await this.embedding.embedBatch(texts);
+            const domain = inferDomain(request.filePath);
+            const fileType = ext.startsWith(".") ? ext.slice(1) : ext;
+            const chunks = textChunks.map((chunk, i) => ({
+                vector: vectors[i],
+                metadata: {
+                    source: request.filePath,
+                    workspace,
+                    domain,
+                    fileType,
+                    chunkIndex: chunk.index,
+                    totalChunks: textChunks.length,
+                    content: chunk.content,
+                },
+            }));
+            await this.vectors.addChunks(workspace, chunks);
+            return ok({
+                workspace,
+                filePath: request.filePath,
+                chunksRemoved: removed,
+                chunksAdded: chunks.length,
+            });
+        }
+        catch (error) {
+            return fail(`RAG update failed: ${String(error)}`);
+        }
+    }
+    // ── Delete ──────────────────────────────────────────────────────
+    async delete(request) {
+        try {
+            const workspace = request.workspace.toLowerCase();
+            await this.vectors.ensureIndex(workspace);
+            const removed = await this.vectors.deleteBySource(workspace, request.filePath);
+            return ok({
+                workspace,
+                filePath: request.filePath,
+                chunksRemoved: removed,
+            });
+        }
+        catch (error) {
+            return fail(`RAG delete failed: ${String(error)}`);
+        }
+    }
+    // ── Status ──────────────────────────────────────────────────────
+    async status(request) {
+        try {
+            const stats = await this.vectors.getStats(request.workspace);
+            const response = {
+                workspace: stats.workspace,
+                documentCount: stats.documentCount,
+                embeddingModel: stats.embeddingModel,
+                storeType: stats.storeType,
+            };
+            if (request.includeOracle === true) {
+                const oracleStats = await this.vectors.getOracleStats();
+                return ok({
+                    ...response,
+                    oracleDocumentCount: oracleStats.documentCount,
+                });
+            }
+            return ok(response);
+        }
+        catch (error) {
+            return fail(`RAG status failed: ${String(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=use-cases.js.map

package/dist/application/rag/use-cases.js.map

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

package/dist/application/token-metrics/dtos.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Token Metrics DTOs (Data Transfer Objects)
+ *
+ * Plain objects for crossing layer boundaries in the token-metrics context.
+ * Tools/Hooks -> Use Cases (request DTOs), Use Cases -> Tools (response DTOs).
+ *
+ * SOLID: SRP - DTOs carry data, no logic
+ * DDD: Application layer boundary objects
+ */
+export interface RecordUsageRequest {
+    readonly workspace: string;
+    readonly toolName: string;
+    readonly agent: string;
+    readonly operation?: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly model: string;
+    readonly cardId?: string;
+    readonly sprintId?: string;
+    readonly sessionId?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export interface GetUsageHistoryRequest {
+    readonly workspace: string;
+    readonly agent?: string;
+    readonly cardId?: string;
+    readonly sprintId?: string;
+    readonly operation?: string;
+    readonly sessionId?: string;
+    readonly limit?: number;
+}
+export interface GetAgentReportRequest {
+    readonly workspace: string;
+    readonly agent?: string;
+}
+export interface GetCardReportRequest {
+    readonly workspace: string;
+    readonly cardId?: string;
+}
+export interface GetSprintReportRequest {
+    readonly workspace: string;
+    readonly sprintId?: string;
+}
+export interface GetWorkspaceSummaryRequest {
+    readonly workspace: string;
+}
+export interface EstimateCostRequest {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly model: string;
+}
+export interface TokenUsageResponse {
+    readonly id: string;
+    readonly workspace: string;
+    readonly toolName: string;
+    readonly agent: string;
+    readonly operation: string;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly model: string;
+    readonly costUsd: number;
+    readonly costTier: string;
+    readonly cardId: string | undefined;
+    readonly sprintId: string | undefined;
+    readonly sessionId: string | undefined;
+    readonly createdAt: string;
+}
+export interface AgentReportResponse {
+    readonly agent: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly totalCostUsd: number;
+    readonly recordCount: number;
+    readonly dominantOperation: string;
+}
+export interface CardReportResponse {
+    readonly cardId: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly totalCostUsd: number;
+    readonly recordCount: number;
+    readonly agentCount: number;
+}
+export interface SprintReportResponse {
+    readonly sprintId: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly totalCostUsd: number;
+    readonly recordCount: number;
+    readonly cardCount: number;
+    readonly agentCount: number;
+    readonly tokensPerCard: number;
+}
+export interface WorkspaceSummaryResponse {
+    readonly workspace: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly totalCostUsd: number;
+    readonly recordCount: number;
+    readonly byOperation: ReadonlyArray<{
+        readonly operation: string;
+        readonly totalTokens: number;
+        readonly totalCostUsd: number;
+        readonly count: number;
+    }>;
+    readonly topAgents: ReadonlyArray<{
+        readonly agent: string;
+        readonly totalTokens: number;
+        readonly totalCostUsd: number;
+    }>;
+    readonly recommendations: readonly string[];
+}
+export interface CostEstimateResponse {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly model: string;
+    readonly costUsd: number;
+    readonly costTier: string;
+}
+//# sourceMappingURL=dtos.d.ts.map

package/dist/application/token-metrics/dtos.d.ts.map

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

package/dist/application/token-metrics/dtos.js

@@ -0,0 +1,11 @@
+/**
+ * Token Metrics DTOs (Data Transfer Objects)
+ *
+ * Plain objects for crossing layer boundaries in the token-metrics context.
+ * Tools/Hooks -> Use Cases (request DTOs), Use Cases -> Tools (response DTOs).
+ *
+ * SOLID: SRP - DTOs carry data, no logic
+ * DDD: Application layer boundary objects
+ */
+export {};
+//# sourceMappingURL=dtos.js.map

package/dist/application/token-metrics/dtos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dtos.js","sourceRoot":"","sources":["../../../src/application/token-metrics/dtos.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/application/token-metrics/tracking-use-cases.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Token Metrics Use Cases
+ *
+ * Application layer orchestration for token usage tracking.
+ * Records usage, generates reports, estimates costs, and produces
+ * actionable recommendations based on spending patterns.
+ *
+ * SOLID: SRP - token metrics operations only
+ * SOLID: DIP - depends on repository interface, not implementation
+ * DDD: Application Service pattern
+ */
+import type { Result } from "../../domain/shared/value-objects.js";
+import type { TokenMetricsRepository } from "../../domain/token-metrics/repositories.js";
+import type { RecordUsageRequest, GetUsageHistoryRequest, GetAgentReportRequest, GetCardReportRequest, GetSprintReportRequest, GetWorkspaceSummaryRequest, EstimateCostRequest, TokenUsageResponse, AgentReportResponse, CardReportResponse, SprintReportResponse, WorkspaceSummaryResponse, CostEstimateResponse } from "./dtos.js";
+export declare class TokenMetricsUseCases {
+    private readonly repo;
+    constructor(repo: TokenMetricsRepository);
+    /** Record a token usage event. */
+    recordUsage(req: RecordUsageRequest): Promise<Result<TokenUsageResponse>>;
+    /** Get usage history with optional filters. */
+    getUsageHistory(req: GetUsageHistoryRequest): Promise<Result<readonly TokenUsageResponse[]>>;
+    /** Get aggregated report by agent. */
+    getAgentReport(req: GetAgentReportRequest): Promise<Result<readonly AgentReportResponse[]>>;
+    /** Get aggregated report by card. */
+    getCardReport(req: GetCardReportRequest): Promise<Result<readonly CardReportResponse[]>>;
+    /** Get aggregated report by sprint. */
+    getSprintReport(req: GetSprintReportRequest): Promise<Result<readonly SprintReportResponse[]>>;
+    /** Get workspace-wide summary with recommendations. */
+    getWorkspaceSummary(req: GetWorkspaceSummaryRequest): Promise<Result<WorkspaceSummaryResponse>>;
+    /** Estimate cost for a hypothetical token usage (no persistence). */
+    estimateCost(req: EstimateCostRequest): CostEstimateResponse;
+}
+//# sourceMappingURL=tracking-use-cases.d.ts.map

package/dist/application/token-metrics/tracking-use-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking-use-cases.d.ts","sourceRoot":"","sources":["../../../src/application/token-metrics/tracking-use-cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sCAAsC,CAAC;AASnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4CAA4C,CAAC;AACzF,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,WAAW,CAAC;AAwFnB,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,sBAAsB;IAEzD,kCAAkC;IAC5B,WAAW,CACf,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IA+BtC,+CAA+C;IACzC,eAAe,CACnB,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAC;IAmBjD,sCAAsC;IAChC,cAAc,CAClB,GAAG,EAAE,qBAAqB,GACzB,OAAO,CAAC,MAAM,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAAC;IAuBlD,qCAAqC;IAC/B,aAAa,CACjB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,MAAM,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAC;IAuBjD,uCAAuC;IACjC,eAAe,CACnB,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;IA0BnD,uDAAuD;IACjD,mBAAmB,CACvB,GAAG,EAAE,0BAA0B,GAC9B,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC;IAqC5C,qEAAqE;IACrE,YAAY,CAAC,GAAG,EAAE,mBAAmB,GAAG,oBAAoB;CAiB7D"}

package/dist/application/token-metrics/tracking-use-cases.js

@@ -0,0 +1,220 @@
+import { WorkspaceId, ok, fail } from "../../domain/shared/value-objects.js";
+import { TokenUsage } from "../../domain/token-metrics/entities.js";
+import { TokenUsageId, parseOperationType, calculateCost, getModelCostTier, } from "../../domain/token-metrics/value-objects.js";
+/** Map TokenUsage entity to response DTO. */
+function toUsageResponse(usage) {
+    return {
+        id: usage.id.value,
+        workspace: usage.workspace.value,
+        toolName: usage.toolName,
+        agent: usage.agent,
+        operation: usage.operation,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        totalTokens: usage.totalTokens,
+        model: usage.model,
+        costUsd: usage.costUsd,
+        costTier: usage.costTier,
+        cardId: usage.cardId,
+        sprintId: usage.sprintId,
+        sessionId: usage.sessionId,
+        createdAt: usage.createdAt.toISO(),
+    };
+}
+/**
+ * Generate recommendations based on workspace summary data.
+ * Flags anomalies and suggests optimizations.
+ */
+function generateRecommendations(totalCostUsd, recordCount, byOperation, topAgents) {
+    const recs = [];
+    // Cost threshold alert
+    if (totalCostUsd > 10) {
+        recs.push(`High cost alert: $${totalCostUsd.toFixed(2)} total. Consider routing more operations to local models.`);
+    }
+    else if (totalCostUsd > 1) {
+        recs.push(`Cost notice: $${totalCostUsd.toFixed(2)} total. Monitor for trends.`);
+    }
+    // Fix-heavy pattern detection
+    const fixOps = byOperation.find((o) => o.operation === "fix");
+    const implOps = byOperation.find((o) => o.operation === "implementation");
+    if (fixOps && implOps && fixOps.count > implOps.count * 0.5) {
+        recs.push("High fix-to-implementation ratio detected. Consider improving grooming/review processes.");
+    }
+    // Review overhead detection
+    const reviewOps = byOperation.find((o) => o.operation === "review");
+    if (reviewOps && recordCount > 0 && reviewOps.count / recordCount > 0.4) {
+        recs.push("Review operations exceed 40% of total. Consider streamlining review workflow.");
+    }
+    // Agent concentration
+    if (topAgents.length > 0) {
+        const totalAllAgents = topAgents.reduce((s, a) => s + a.totalTokens, 0);
+        const topAgent = topAgents[0];
+        if (totalAllAgents > 0 && topAgent.totalTokens / totalAllAgents > 0.7) {
+            recs.push(`Agent "${topAgent.agent}" consumes ${Math.round((topAgent.totalTokens / totalAllAgents) * 100)}% of tokens. Consider distributing work.`);
+        }
+    }
+    if (recs.length === 0) {
+        recs.push("Token usage within normal parameters.");
+    }
+    return recs;
+}
+export class TokenMetricsUseCases {
+    repo;
+    constructor(repo) {
+        this.repo = repo;
+    }
+    /** Record a token usage event. */
+    async recordUsage(req) {
+        try {
+            const workspace = WorkspaceId.create(req.workspace);
+            const sequence = await this.repo.nextSequence(workspace);
+            const id = TokenUsageId.create(sequence);
+            const operation = req.operation
+                ? parseOperationType(req.operation)
+                : undefined;
+            const usage = TokenUsage.create({
+                id,
+                workspace,
+                toolName: req.toolName,
+                agent: req.agent,
+                inputTokens: req.inputTokens,
+                outputTokens: req.outputTokens,
+                model: req.model,
+                ...(operation !== undefined ? { operation } : {}),
+                ...(req.cardId !== undefined ? { cardId: req.cardId } : {}),
+                ...(req.sprintId !== undefined ? { sprintId: req.sprintId } : {}),
+                ...(req.sessionId !== undefined ? { sessionId: req.sessionId } : {}),
+                ...(req.metadata !== undefined ? { metadata: req.metadata } : {}),
+            });
+            await this.repo.save(usage);
+            return ok(toUsageResponse(usage));
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Get usage history with optional filters. */
+    async getUsageHistory(req) {
+        try {
+            const workspace = WorkspaceId.create(req.workspace);
+            const records = await this.repo.findByWorkspace(workspace, {
+                ...(req.agent !== undefined ? { agent: req.agent } : {}),
+                ...(req.cardId !== undefined ? { cardId: req.cardId } : {}),
+                ...(req.sprintId !== undefined ? { sprintId: req.sprintId } : {}),
+                ...(req.operation !== undefined
+                    ? { operation: parseOperationType(req.operation) }
+                    : {}),
+                ...(req.sessionId !== undefined ? { sessionId: req.sessionId } : {}),
+                ...(req.limit !== undefined ? { limit: req.limit } : {}),
+            });
+            return ok(records.map(toUsageResponse));
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Get aggregated report by agent. */
+    async getAgentReport(req) {
+        try {
+            const workspace = WorkspaceId.create(req.workspace);
+            const metrics = await this.repo.getMetricsByAgent(workspace, req.agent);
+            return ok(metrics.map((m) => ({
+                agent: m.agent,
+                totalInputTokens: m.totalInputTokens,
+                totalOutputTokens: m.totalOutputTokens,
+                totalTokens: m.totalTokens,
+                totalCostUsd: m.totalCostUsd,
+                recordCount: m.recordCount,
+                dominantOperation: m.dominantOperation,
+            })));
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Get aggregated report by card. */
+    async getCardReport(req) {
+        try {
+            const workspace = WorkspaceId.create(req.workspace);
+            const metrics = await this.repo.getMetricsByCard(workspace, req.cardId);
+            return ok(metrics.map((m) => ({
+                cardId: m.cardId,
+                totalInputTokens: m.totalInputTokens,
+                totalOutputTokens: m.totalOutputTokens,
+                totalTokens: m.totalTokens,
+                totalCostUsd: m.totalCostUsd,
+                recordCount: m.recordCount,
+                agentCount: m.agentCount,
+            })));
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Get aggregated report by sprint. */
+    async getSprintReport(req) {
+        try {
+            const workspace = WorkspaceId.create(req.workspace);
+            const metrics = await this.repo.getMetricsBySprint(workspace, req.sprintId);
+            return ok(metrics.map((m) => ({
+                sprintId: m.sprintId,
+                totalInputTokens: m.totalInputTokens,
+                totalOutputTokens: m.totalOutputTokens,
+                totalTokens: m.totalTokens,
+                totalCostUsd: m.totalCostUsd,
+                recordCount: m.recordCount,
+                cardCount: m.cardCount,
+                agentCount: m.agentCount,
+                tokensPerCard: m.cardCount > 0 ? Math.round(m.totalTokens / m.cardCount) : 0,
+            })));
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Get workspace-wide summary with recommendations. */
+    async getWorkspaceSummary(req) {
+        try {
+            const workspace = WorkspaceId.create(req.workspace);
+            const summary = await this.repo.getWorkspaceSummary(workspace);
+            const recommendations = generateRecommendations(summary.totalCostUsd, summary.recordCount, summary.byOperation, summary.topAgents);
+            return ok({
+                workspace: req.workspace,
+                totalInputTokens: summary.totalInputTokens,
+                totalOutputTokens: summary.totalOutputTokens,
+                totalTokens: summary.totalTokens,
+                totalCostUsd: summary.totalCostUsd,
+                recordCount: summary.recordCount,
+                byOperation: summary.byOperation.map((o) => ({
+                    operation: o.operation,
+                    totalTokens: o.totalTokens,
+                    totalCostUsd: o.totalCostUsd,
+                    count: o.count,
+                })),
+                topAgents: summary.topAgents.map((a) => ({
+                    agent: a.agent,
+                    totalTokens: a.totalTokens,
+                    totalCostUsd: a.totalCostUsd,
+                })),
+                recommendations,
+            });
+        }
+        catch (e) {
+            return fail(e instanceof Error ? e.message : String(e));
+        }
+    }
+    /** Estimate cost for a hypothetical token usage (no persistence). */
+    estimateCost(req) {
+        const cost = calculateCost(req.inputTokens, req.outputTokens, req.model);
+        const tier = getModelCostTier(req.model);
+        return {
+            inputTokens: req.inputTokens,
+            outputTokens: req.outputTokens,
+            totalTokens: req.inputTokens + req.outputTokens,
+            model: req.model,
+            costUsd: cost,
+            costTier: tier,
+        };
+    }
+}
+//# sourceMappingURL=tracking-use-cases.js.map