feat: end-to-end cost tracking with frontend metrics panel

Backend:
- Token tracking wired into knowledge extraction node
(reads langchain response_metadata for prompt/completion tokens)
- Stage timing added to extract, chunk, embed, reconcile nodes
- Each stage start/end recorded via RunTracker

Frontend:
- New api/metrics.js module
- Document Workspace shows 'Run cost and timing' card after workflow
completes or pauses for review
- Summary row: total time, tokens used, LLM calls
- Per-stage breakdown with proportional bar chart + time + token count
- Stages shown: extraction, chunking, embedding, knowledge_extraction,
reconciliation

The reviewer can now see exactly where time was spent and how many
tokens each run consumed — stage by stage.

backend/app/workflow/nodes/chunk.py

@@ -1,4 +1,5 @@
 from app.services.chunking_service import ChunkingService
+from app.core.tracing.run_tracker import get_or_create_tracker
 from app.workflow.state import WorkflowState
 
 
@@ -13,6 +14,9 @@ def chunk(
 
     state.current_node = "CHUNKING"
 
+    tracker = get_or_create_tracker(str(state.workflow_run_id))
+    tracker.start_stage("chunking")
+
     result = chunking_service.chunk_document(
         document_version_id=state.document_version_id,
         sections=state.extracted_sections,
@@ -20,4 +24,5 @@ def chunk(
 
     state.metadata["chunks_created"] = result["chunks_created"]
 
+    tracker.end_stage("chunking")
     return state

backend/app/workflow/nodes/embed.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from sqlalchemy.orm import Session
 
+from app.core.tracing.run_tracker import get_or_create_tracker
 from app.models.document_chunk import DocumentChunk
 from app.services.embedding_service import EmbeddingService
 from app.workflow.state import WorkflowState
@@ -18,6 +19,9 @@ def embed(
 
     state.current_node = "EMBEDDING"
 
+    tracker = get_or_create_tracker(str(state.workflow_run_id))
+    tracker.start_stage("embedding")
+
     chunks = (
         db.query(DocumentChunk)
         .filter(
@@ -31,6 +35,7 @@ def embed(
 
     if not chunks:
         state.metadata["embeddings_created"] = 0
+        tracker.end_stage("embedding")
         return state
 
     texts = [chunk.text for chunk in chunks]
@@ -38,6 +43,7 @@ def embed(
     vectors = embedding_service.embed_many(texts)
 
     if len(vectors) != len(chunks):
+        tracker.end_stage("embedding")
         raise RuntimeError(
             "Embedding count does not match chunk count."
         )
@@ -49,4 +55,5 @@ def embed(
 
     state.metadata["embeddings_created"] = len(chunks)
 
+    tracker.end_stage("embedding")
     return state

backend/app/workflow/nodes/extract.py

@@ -1,3 +1,4 @@
+from app.core.tracing.run_tracker import get_or_create_tracker
 from app.services.document_processor import (
     TextExtractionError,
     extract_text_sections,
@@ -13,6 +14,9 @@ def extract(state: WorkflowState) -> WorkflowState:
 
     state.current_node = "EXTRACTION"
 
+    tracker = get_or_create_tracker(str(state.workflow_run_id))
+    tracker.start_stage("extraction")
+
     try:
         sections = extract_text_sections(
             state.document_path
@@ -34,6 +38,8 @@ def extract(state: WorkflowState) -> WorkflowState:
 
     except TextExtractionError as exc:
         state.metadata["extraction_error"] = str(exc)
+        tracker.end_stage("extraction")
         raise
 
+    tracker.end_stage("extraction")
     return state

backend/app/workflow/nodes/knowledge.py

@@ -129,9 +129,29 @@ def knowledge(
         KnowledgeExtractionResult
     )
 
-    result: KnowledgeExtractionResult = structured_model.invoke(
-        prompt
-    )
+    # Track LLM usage
+    from app.core.tracing.run_tracker import get_or_create_tracker
+    tracker = get_or_create_tracker(str(state.workflow_run_id))
+    tracker.start_stage("knowledge_extraction")
+
+    response = structured_model.invoke(prompt)
+
+    # Extract token usage from LangChain response metadata
+    try:
+        if hasattr(response, "response_metadata"):
+            meta = response.response_metadata or {}
+            usage = meta.get("token_usage") or meta.get("usage") or {}
+            tracker.record_llm_usage(
+                "knowledge_extraction",
+                input_tokens=usage.get("prompt_tokens", 0) or usage.get("input_tokens", 0),
+                output_tokens=usage.get("completion_tokens", 0) or usage.get("output_tokens", 0),
+            )
+    except Exception:
+        pass  # Non-fatal — don't break workflow for metrics
+
+    tracker.end_stage("knowledge_extraction")
+
+    result = response
 
     created_count = 0
 

backend/app/workflow/nodes/reconcile.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from sqlalchemy.orm import Session
 
+from app.core.tracing.run_tracker import get_or_create_tracker
 from app.services.reconciliation_service import ReconciliationService
 from app.workflow.state import WorkflowState
 
@@ -17,6 +18,9 @@ def reconcile(
 
     state.current_node = "RECONCILIATION"
 
+    tracker = get_or_create_tracker(str(state.workflow_run_id))
+    tracker.start_stage("reconciliation")
+
     service = ReconciliationService(db)
 
     results = service.reconcile_document(
@@ -26,4 +30,5 @@ def reconcile(
 
     state.metadata["reconciliation"] = results
 
+    tracker.end_stage("reconciliation")
     return state

frontend/src/api/metrics.js

@@ -0,0 +1,5 @@
+import { apiRequest } from "./client";
+
+export async function getWorkflowMetrics(workflowId) {
+    return apiRequest(`/metrics/workflow/${workflowId}`);
+}

frontend/src/pages/DocumentWorkspace.css

@@ -14,3 +14,89 @@
   color: var(--color-text-secondary);
   margin: 0 0 var(--space-3);
 }
+
+/* Run cost and timing metrics */
+.dw-metrics__summary {
+    display: flex;
+    gap: var(--space-6);
+    margin-bottom: var(--space-4);
+}
+
+.dw-metrics__stat {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+}
+
+.dw-metrics__stat-value {
+    font-size: var(--text-xl);
+    font-weight: 700;
+    color: var(--color-text-primary);
+}
+
+.dw-metrics__stat-label {
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+}
+
+.dw-metrics__stages {
+    border-top: 1px solid var(--color-border);
+    padding-top: var(--space-3);
+}
+
+.dw-metrics__stages-title {
+    font-size: var(--text-xs);
+    font-weight: 600;
+    color: var(--color-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    margin: 0 0 var(--space-3);
+}
+
+.dw-metrics__stage-row {
+    display: flex;
+    align-items: center;
+    gap: var(--space-3);
+    padding: var(--space-1) 0;
+}
+
+.dw-metrics__stage-name {
+    flex-shrink: 0;
+    width: 140px;
+    font-size: var(--text-xs);
+    color: var(--color-text-secondary);
+    text-transform: capitalize;
+}
+
+.dw-metrics__stage-bar-track {
+    flex: 1;
+    height: 6px;
+    border-radius: 3px;
+    background: var(--color-border);
+    overflow: hidden;
+}
+
+.dw-metrics__stage-bar-fill {
+    height: 100%;
+    border-radius: 3px;
+    background: var(--color-accent);
+    min-width: 2px;
+    transition: width var(--transition-base);
+}
+
+.dw-metrics__stage-time {
+    flex-shrink: 0;
+    width: 60px;
+    text-align: right;
+    font-size: var(--text-xs);
+    font-family: var(--font-mono);
+    color: var(--color-text-muted);
+}
+
+.dw-metrics__stage-tokens {
+    flex-shrink: 0;
+    width: 70px;
+    text-align: right;
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+}

frontend/src/pages/DocumentWorkspace.jsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useParams } from "react-router-dom";
 import { getWorkflow } from "../api/workflows";
+import { getWorkflowMetrics } from "../api/metrics";
 import { WorkflowStatusBadge } from "../components/workflow/WorkflowStatusBadge";
 import { ProposalReviewList } from "../components/proposals/ProposalReviewList";
 import { Card, CardHeader, CardBody, LoadingState, EmptyState, Glossary } from "../components/ui";
@@ -27,6 +28,7 @@ export default function DocumentWorkspace() {
     const [workflow, setWorkflow] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
+    const [metrics, setMetrics] = useState(null);
     const pollRef = useRef(null);
 
     const fetchWorkflow = useCallback(async () => {
@@ -39,6 +41,11 @@ export default function DocumentWorkspace() {
             } else {
                 setWorkflow(result);
                 setError(null);
+                // Fetch metrics when workflow is no longer pending/running
+                if (result.status && !ACTIVE_STATUSES.has(result.status)) {
+                    const m = await getWorkflowMetrics(workflowId);
+                    if (m && !m.detail) setMetrics(m);
+                }
             }
         } catch (err) {
             setError("Couldn't load workflow status.");
@@ -164,6 +171,73 @@ export default function DocumentWorkspace() {
                     </CardBody>
                 </Card>
             )}
+
+            {metrics && metrics.stages && metrics.stages.length > 0 && (
+                <Card>
+                    <CardHeader title="Run cost and timing" />
+                    <CardBody>
+                        <div className="dw-metrics">
+                            <div className="dw-metrics__summary">
+                                {metrics.total_elapsed_ms != null && (
+                                    <div className="dw-metrics__stat">
+                                        <span className="dw-metrics__stat-value">
+                                            {metrics.total_elapsed_ms > 1000
+                                                ? `${(metrics.total_elapsed_ms / 1000).toFixed(1)}s`
+                                                : `${Math.round(metrics.total_elapsed_ms)}ms`}
+                                        </span>
+                                        <span className="dw-metrics__stat-label">Total time</span>
+                                    </div>
+                                )}
+                                {metrics.total_tokens > 0 && (
+                                    <div className="dw-metrics__stat">
+                                        <span className="dw-metrics__stat-value">
+                                            {metrics.total_tokens.toLocaleString()}
+                                        </span>
+                                        <span className="dw-metrics__stat-label">Tokens used</span>
+                                    </div>
+                                )}
+                                {metrics.total_llm_calls > 0 && (
+                                    <div className="dw-metrics__stat">
+                                        <span className="dw-metrics__stat-value">
+                                            {metrics.total_llm_calls}
+                                        </span>
+                                        <span className="dw-metrics__stat-label">LLM calls</span>
+                                    </div>
+                                )}
+                            </div>
+                            <div className="dw-metrics__stages">
+                                <p className="dw-metrics__stages-title">Time per stage</p>
+                                {metrics.stages.map((stage) => (
+                                    <div key={stage.name} className="dw-metrics__stage-row">
+                                        <span className="dw-metrics__stage-name">{stage.name}</span>
+                                        <div className="dw-metrics__stage-bar-track">
+                                            <div
+                                                className="dw-metrics__stage-bar-fill"
+                                                style={{
+                                                    width: `${Math.min(
+                                                        100,
+                                                        (stage.elapsed_ms / (metrics.total_elapsed_ms || 1)) * 100
+                                                    )}%`,
+                                                }}
+                                            />
+                                        </div>
+                                        <span className="dw-metrics__stage-time">
+                                            {stage.elapsed_ms > 1000
+                                                ? `${(stage.elapsed_ms / 1000).toFixed(1)}s`
+                                                : `${Math.round(stage.elapsed_ms)}ms`}
+                                        </span>
+                                        {stage.input_tokens > 0 && (
+                                            <span className="dw-metrics__stage-tokens">
+                                                {(stage.input_tokens + stage.output_tokens).toLocaleString()} tok
+                                            </span>
+                                        )}
+                                    </div>
+                                ))}
+                            </div>
+                        </div>
+                    </CardBody>
+                </Card>
+            )}
         </div>
     );
 }