feat: v0.2.0 — telemetry + cost attribution parity with @sidclaw/sdk@0.1.11

Adds record_telemetry() on SidClaw/AsyncSidClaw, extends record_outcome
with 8 optional telemetry fields, and ships sidclaw.cost with MODEL_PRICING
+ estimate_cost for 13 models.

No breaking changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: VladUZH

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 (2026-04-17)
+
+Telemetry + cost attribution parity with `@sidclaw/sdk@0.1.11`.
+
+Added:
+- `record_telemetry(trace_id, params)` method on `SidClaw` and `AsyncSidClaw` — PATCH `/api/v1/traces/:id/telemetry`. Token usage and cost are accumulated server-side; outcome_summary and model are set-once (first write wins).
+- `RecordTelemetryParams` TypedDict with `tokens_in`, `tokens_out`, `tokens_cache_read`, `model`, `cost_estimate`, `outcome_summary` (all optional).
+- Extended `RecordOutcomeParams` with eight optional fields: `outcome_summary`, `error_classification`, `exit_code`, `tokens_in`, `tokens_out`, `tokens_cache_read`, `model`, `cost_estimate`.
+- `ErrorClassification` literal type: `'timeout' | 'permission' | 'not_found' | 'runtime'`.
+- New module `sidclaw.cost` — `MODEL_PRICING` table for 13 models (Claude 4.x, GPT-4o, Gemini), `estimate_cost(model, tokens_in, tokens_out, tokens_cache_read)`, `register_model_pricing(model, pricing)` for user overrides.
+
+No breaking changes — all new fields are optional.
+
 ## 0.1.0 (2026-03-23)
 
 - Initial release

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sidclaw"
-version = "0.1.2"
+version = "0.2.0"
 description = "Python SDK for SidClaw — governance for AI agents"
 readme = "README.md"
 license = "Apache-2.0"

src/sidclaw/__init__.py

@@ -16,13 +16,16 @@
     ApprovalStatus,
     ApprovalStatusResponse,
     DataClassification,
+    ErrorClassification,
     EvaluateParams,
     EvaluateResponse,
     PolicyEffect,
     RecordOutcomeParams,
+    RecordTelemetryParams,
     RiskClassification,
     WaitForApprovalOptions,
 )
+from .cost import MODEL_PRICING, ModelPricing, estimate_cost, register_model_pricing
 from .webhooks import verify_webhook_signature
 
 __all__ = [
@@ -31,12 +34,14 @@
     "EvaluateParams",
     "EvaluateResponse",
     "RecordOutcomeParams",
+    "RecordTelemetryParams",
     "ApprovalStatusResponse",
     "WaitForApprovalOptions",
     "DataClassification",
     "PolicyEffect",
     "ApprovalStatus",
     "RiskClassification",
+    "ErrorClassification",
     "SidClawError",
     "APIError",
     "ActionDeniedError",
@@ -46,5 +51,9 @@
     "AuthenticationError",
     "PlanLimitError",
     "verify_webhook_signature",
+    "MODEL_PRICING",
+    "ModelPricing",
+    "estimate_cost",
+    "register_model_pricing",
     "__version__",
 ]

src/sidclaw/_client.py

@@ -14,6 +14,7 @@
     EvaluateParams,
     EvaluateResponse,
     RecordOutcomeParams,
+    RecordTelemetryParams,
     WaitForApprovalOptions,
 )
 
@@ -114,6 +115,12 @@ def record_outcome(self, trace_id: str, params: RecordOutcomeParams) -> None:
         """Record the outcome of an action after execution."""
         self._request("POST", f"/api/v1/traces/{trace_id}/outcome", json=dict(params))
 
+    def record_telemetry(self, trace_id: str, params: RecordTelemetryParams) -> None:
+        """Attach token usage or cost data to a trace AFTER its outcome has been
+        recorded. Used for late-arriving LLM telemetry (e.g. from a Stop hook).
+        """
+        self._request("PATCH", f"/api/v1/traces/{trace_id}/telemetry", json=dict(params))
+
 
 class AsyncSidClaw(BaseClient):
     """Asynchronous SidClaw client."""
@@ -210,3 +217,9 @@ async def wait_for_approval(
     async def record_outcome(self, trace_id: str, params: RecordOutcomeParams) -> None:
         """Record the outcome of an action after execution."""
         await self._request("POST", f"/api/v1/traces/{trace_id}/outcome", json=dict(params))
+
+    async def record_telemetry(self, trace_id: str, params: RecordTelemetryParams) -> None:
+        """Attach token usage or cost data to a trace AFTER its outcome has been
+        recorded. Used for late-arriving LLM telemetry (e.g. from a Stop hook).
+        """
+        await self._request("PATCH", f"/api/v1/traces/{trace_id}/telemetry", json=dict(params))

src/sidclaw/_constants.py

@@ -1,4 +1,4 @@
-SDK_VERSION = "0.1.0"
+SDK_VERSION = "0.2.0"
 DEFAULT_BASE_URL = "https://api.sidclaw.com"
 DEFAULT_MAX_RETRIES = 3
 DEFAULT_TIMEOUT = 30.0

src/sidclaw/_types.py

@@ -24,9 +24,32 @@ class EvaluateParams(TypedDict, total=False):
     context: dict[str, Any]  # optional
 
 
+ErrorClassification = Literal["timeout", "permission", "not_found", "runtime"]
+
+
 class RecordOutcomeParams(TypedDict, total=False):
     status: Literal["success", "error"]  # required
     metadata: dict[str, Any]  # optional
+    # Added 2026-04-16 — hooks + cost-attribution telemetry. All optional.
+    outcome_summary: str
+    error_classification: ErrorClassification
+    exit_code: int
+    tokens_in: int
+    tokens_out: int
+    tokens_cache_read: int
+    model: str
+    cost_estimate: float
+
+
+class RecordTelemetryParams(TypedDict, total=False):
+    """Late-arriving LLM telemetry attached to a trace after its outcome."""
+
+    tokens_in: int
+    tokens_out: int
+    tokens_cache_read: int
+    model: str
+    cost_estimate: float
+    outcome_summary: str
 
 
 class ApprovalDecisionParams(TypedDict):

src/sidclaw/cost.py

@@ -0,0 +1,79 @@
+"""Per-1M-token pricing for common LLM models.
+
+Keep this table up to date — stale pricing produces bad cost estimates.
+Prices are in USD per 1,000,000 tokens.
+
+Used by :func:`estimate_cost` and consumed by the Claude Code Stop hook.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ModelPricing(TypedDict, total=False):
+    input: float  # required
+    output: float  # required
+    cache_read: float
+    cache_write: float
+
+
+MODEL_PRICING: dict[str, ModelPricing] = {
+    # Anthropic Claude 4.x
+    "claude-opus-4-7": {"input": 15.0, "output": 75.0, "cache_read": 1.5},
+    "claude-opus-4-6": {"input": 15.0, "output": 75.0, "cache_read": 1.5},
+    "claude-sonnet-4-6": {"input": 3.0, "output": 15.0, "cache_read": 0.3},
+    "claude-sonnet-4-5": {"input": 3.0, "output": 15.0, "cache_read": 0.3},
+    "claude-haiku-4-5": {"input": 0.8, "output": 4.0, "cache_read": 0.08},
+    # OpenAI
+    "gpt-4o": {"input": 2.5, "output": 10.0, "cache_read": 1.25},
+    "gpt-4o-mini": {"input": 0.15, "output": 0.6, "cache_read": 0.075},
+    "gpt-4-turbo": {"input": 10.0, "output": 30.0},
+    "o1-preview": {"input": 15.0, "output": 60.0},
+    "o1-mini": {"input": 3.0, "output": 12.0},
+    # Google Gemini
+    "gemini-2.0-flash": {"input": 0.1, "output": 0.4},
+    "gemini-1.5-pro": {"input": 1.25, "output": 5.0},
+    "gemini-1.5-flash": {"input": 0.075, "output": 0.3},
+}
+
+
+def estimate_cost(
+    model: str,
+    tokens_in: int,
+    tokens_out: int,
+    tokens_cache_read: int = 0,
+    tokens_cache_write: int = 0,
+) -> float:
+    """Compute a USD cost estimate for a model call.
+
+    Returns 0 if the model is not in the pricing table — prefer emitting 0
+    over a wildly wrong estimate.
+    """
+    pricing = MODEL_PRICING.get(model) or MODEL_PRICING.get(model.lower())
+    if not pricing:
+        return 0.0
+
+    input_price = pricing.get("input", 0.0)
+    output_price = pricing.get("output", 0.0)
+    cache_read_price = pricing.get("cache_read", 0.0)
+    cache_write_price = pricing.get("cache_write", input_price)
+
+    cost = (
+        tokens_in * input_price
+        + tokens_out * output_price
+        + tokens_cache_read * cache_read_price
+        + tokens_cache_write * cache_write_price
+    )
+
+    return cost / 1_000_000
+
+
+def register_model_pricing(model: str, pricing: ModelPricing) -> None:
+    """Register or override pricing for a model — useful for fine-tuned variants
+    or self-hosted models where you know the unit cost.
+    """
+    MODEL_PRICING[model] = pricing
+
+
+__all__ = ["MODEL_PRICING", "ModelPricing", "estimate_cost", "register_model_pricing"]

tests/test_client.py

@@ -233,6 +233,73 @@ def test_record_outcome_error(self, client, mock_api):
         mock_api.post("/api/v1/traces/trace-1/outcome").mock(return_value=httpx.Response(200, json={}))
         client.record_outcome("trace-1", {"status": "error", "metadata": {"error": "Something failed"}})
 
+    def test_record_outcome_with_extended_telemetry_fields(self, client, mock_api):
+        route = mock_api.post("/api/v1/traces/trace-1/outcome").mock(
+            return_value=httpx.Response(200, json={})
+        )
+        client.record_outcome(
+            "trace-1",
+            {
+                "status": "success",
+                "outcome_summary": "Created 2 files, ran 12 tests",
+                "error_classification": "runtime",
+                "exit_code": 0,
+                "tokens_in": 1000,
+                "tokens_out": 500,
+                "tokens_cache_read": 200,
+                "model": "claude-opus-4-7",
+                "cost_estimate": 0.045,
+            },
+        )
+        import json as _json
+
+        body = _json.loads(route.calls[0].request.content)
+        assert body["status"] == "success"
+        assert body["outcome_summary"] == "Created 2 files, ran 12 tests"
+        assert body["error_classification"] == "runtime"
+        assert body["exit_code"] == 0
+        assert body["tokens_in"] == 1000
+        assert body["tokens_out"] == 500
+        assert body["tokens_cache_read"] == 200
+        assert body["model"] == "claude-opus-4-7"
+        assert body["cost_estimate"] == 0.045
+
+
+class TestRecordTelemetry:
+    def test_record_telemetry_sends_patch(self, client, mock_api):
+        route = mock_api.patch("/api/v1/traces/trace-1/telemetry").mock(
+            return_value=httpx.Response(200, json={})
+        )
+        client.record_telemetry(
+            "trace-1",
+            {
+                "tokens_in": 2000,
+                "tokens_out": 800,
+                "tokens_cache_read": 400,
+                "model": "claude-sonnet-4-6",
+                "cost_estimate": 0.018,
+                "outcome_summary": "Refactored auth module",
+            },
+        )
+        assert route.call_count == 1
+        import json as _json
+
+        body = _json.loads(route.calls[0].request.content)
+        assert body["tokens_in"] == 2000
+        assert body["model"] == "claude-sonnet-4-6"
+        assert body["outcome_summary"] == "Refactored auth module"
+
+    def test_record_telemetry_accepts_partial_payload(self, client, mock_api):
+        route = mock_api.patch("/api/v1/traces/trace-1/telemetry").mock(
+            return_value=httpx.Response(200, json={})
+        )
+        client.record_telemetry("trace-1", {"cost_estimate": 0.01})
+        assert route.call_count == 1
+        import json as _json
+
+        body = _json.loads(route.calls[0].request.content)
+        assert body == {"cost_estimate": 0.01}
+
 
 class TestWaitForApproval:
     def test_wait_for_approval_approved(self, client, mock_api):

tests/test_cost.py

@@ -0,0 +1,31 @@
+from sidclaw.cost import MODEL_PRICING, estimate_cost, register_model_pricing
+
+
+class TestEstimateCost:
+    def test_computes_opus_4_7_cost(self):
+        cost = estimate_cost(
+            model="claude-opus-4-7",
+            tokens_in=1_000_000,
+            tokens_out=500_000,
+        )
+        # 1M * $15 + 0.5M * $75 = $15 + $37.5 = $52.5
+        assert cost == 52.5
+
+    def test_handles_cache_read_discount(self):
+        cost = estimate_cost(
+            model="claude-sonnet-4-6",
+            tokens_in=1_000_000,
+            tokens_out=100_000,
+            tokens_cache_read=2_000_000,
+        )
+        # 1M * $3 + 0.1M * $15 + 2M * $0.3 = 3 + 1.5 + 0.6 = $5.1
+        assert abs(cost - 5.1) < 1e-5
+
+    def test_returns_zero_for_unknown_models(self):
+        assert estimate_cost(model="unknown-model", tokens_in=1000, tokens_out=1000) == 0
+
+    def test_register_model_pricing_overrides_table(self):
+        register_model_pricing("custom-model", {"input": 10, "output": 20})
+        assert MODEL_PRICING["custom-model"] == {"input": 10, "output": 20}
+        cost = estimate_cost(model="custom-model", tokens_in=1_000_000, tokens_out=1_000_000)
+        assert abs(cost - 30) < 1e-5