## Observability

This project uses Sprint Vibe for agent observability.
API endpoint: https://sprintvibe.app/api/v1/ingest
API key: sv_live_YOUR_KEY_HERE

Report activity by POSTing JSON to the endpoint with header:
  Authorization: Bearer sv_live_YOUR_KEY_HERE

Required fields:
  - session_id: your session/thread ID
  - event_type: session_start | tool_call | tool_result | error | session_end

Optional fields:
  - agent_name, model, tool_name, tool_input, payload

#!/usr/bin/env bash
INPUT=$(cat)

curl -s -X POST "https://sprintvibe.app/api/v1/ingest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "$INPUT" \
  --connect-timeout 3 \
  --max-time 5 \
  > /dev/null 2>&1 &

exit 0

chmod +x .claude/hooks/sprint-vibe-hook.sh

{
  "hooks": {
    "SessionStart": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "SessionEnd": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "UserPromptSubmit": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "PreToolUse": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "PostToolUse": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "PostToolUseFailure": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "PermissionRequest": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "Stop": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "SubagentStart": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "SubagentStop": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "TeammateIdle": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "TaskCompleted": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "Notification": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ],
    "PreCompact": [
      { "matcher": "", "hooks": [{ "type": "command", "command": ".claude/hooks/sprint-vibe-hook.sh" }] }
    ]
  }
}

notify = ["bash", "-c", "curl -s -X POST https://sprintvibe.app/api/v1/ingest -H 'Content-Type: application/json' -H 'Authorization: Bearer YOUR_API_KEY' -d \"$1\" &", "--"]

[otel]
environment = "production"

[otel.exporter.otlp-http]
endpoint = "https://sprintvibe.app/api/v1/otel"
headers = { "Authorization" = "Bearer YOUR_API_KEY" }

const SV_URL = "https://sprintvibe.app/api/v1/ingest"
const SV_KEY = "YOUR_API_KEY"

async function track(sessionId: string, eventType: string, data: Record<string, unknown> = {}) {
  fetch(SV_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${SV_KEY}` },
    body: JSON.stringify({ session_id: sessionId, event_type: eventType, platform: "codex", ...data }),
  }).catch(() => {})
}

// Track session lifecycle
const threadId = process.env.CODEX_THREAD_ID || crypto.randomUUID()
await track(threadId, "session_start", { agent_name: "codex", model: "codex" })

// Track tool calls
await track(threadId, "tool_call", { tool_name: "code_edit", tool_input: { file: "app.ts" } })
await track(threadId, "tool_result", { tool_name: "code_edit", payload: { success: true } })

// Track completion
await track(threadId, "session_end")

import WebSocket from "ws"

const SV_URL = "https://sprintvibe.app/api/v1/ingest"
const SV_KEY = "YOUR_API_KEY"
const OC_URL = "ws://127.0.0.1:18789"
const OC_TOKEN = "your-gateway-token"

const ws = new WebSocket(OC_URL)

ws.on("open", () => {
  // Handshake
  ws.send(JSON.stringify({
    type: "req", id: "1", method: "connect",
    params: {
      minProtocol: 1, maxProtocol: 1,
      client: { id: "sprintvibe", displayName: "Sprint Vibe", version: "1.0.0", platform: "node", mode: "remote" },
      auth: { token: OC_TOKEN }
    }
  }))
})

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString())

  if (msg.type === "event") {
    fetch(SV_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${SV_KEY}` },
      body: JSON.stringify({
        session_id: msg.payload?.sessionKey || msg.payload?.runId || "openclaw-main",
        event_type: msg.event === "agent" ? "tool_call" : "status_update",
        platform: "openclaw",
        agent_name: msg.payload?.agentName || "openclaw",
        channel: msg.payload?.channel,
        payload: msg.payload,
      }),
    }).catch(() => {})
  }
})

{
  "hooks": {
    "enabled": true,
    "token": "your-shared-secret",
    "mappings": {
      "sprintvibe": {
        "action": "agent",
        "transform": { "module": "sprintvibe-bridge" }
      }
    },
    "transformsDir": "./transforms"
  }
}

const SV_URL = "https://sprintvibe.app/api/v1/ingest"
const SV_KEY = "YOUR_API_KEY"

async function track(sessionId: string, eventType: string, data: Record<string, unknown> = {}) {
  fetch(SV_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${SV_KEY}` },
    body: JSON.stringify({ session_id: sessionId, event_type: eventType, platform: "gemini", ...data }),
  }).catch(() => {})
}

// Session start
await track("gemini-001", "session_start", {
  agent_name: "antigravity-planner",
  model: "gemini-2.5-pro",
})

// Tool calls
await track("gemini-001", "tool_call", {
  agent_name: "antigravity-planner",
  tool_name: "web_search",
  tool_input: { query: "latest API docs" },
})

await track("gemini-001", "tool_result", {
  tool_name: "web_search",
  payload: { results_count: 10, top_result: "developers.google.com/..." },
})

// Session end
await track("gemini-001", "session_end")

import httpx

SV_URL = "https://sprintvibe.app/api/v1/ingest"
SV_KEY = "YOUR_API_KEY"

def track(session_id: str, event_type: str, **kwargs):
    httpx.post(SV_URL, headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {SV_KEY}",
    }, json={
        "session_id": session_id,
        "event_type": event_type,
        "platform": "gemini",
        **kwargs,
    }, timeout=5)

# Usage
track("gemini-001", "session_start", agent_name="planner", model="gemini-2.5-pro")
track("gemini-001", "tool_call", tool_name="code_gen", tool_input={"prompt": "build a form"})
track("gemini-001", "session_end")

import httpx
from uuid import uuid4

class SprintVibe:
    def __init__(self, api_key: str, url: str = "https://sprintvibe.app"):
        self.url = f"{url}/api/v1/ingest"
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}",
        }

    def event(self, session_id: str, event_type: str, **kwargs):
        httpx.post(self.url, headers=self.headers, json={
            "session_id": session_id,
            "event_type": event_type,
            **kwargs,
        }, timeout=5)

    def session(self, agent_name: str = None, model: str = None, **kwargs):
        """Start a tracked session. Returns a session helper."""
        sid = str(uuid4())
        self.event(sid, "session_start", agent_name=agent_name, model=model, **kwargs)
        return SprintVibeSession(self, sid)

class SprintVibeSession:
    def __init__(self, sv: SprintVibe, session_id: str):
        self.sv = sv
        self.session_id = session_id

    def tool_call(self, tool_name: str, tool_input: dict = None, **kwargs):
        self.sv.event(self.session_id, "tool_call", tool_name=tool_name, tool_input=tool_input, **kwargs)

    def tool_result(self, tool_name: str, payload: dict = None, **kwargs):
        self.sv.event(self.session_id, "tool_result", tool_name=tool_name, payload=payload, **kwargs)

    def error(self, tool_name: str, message: str, **kwargs):
        self.sv.event(self.session_id, "tool_error", tool_name=tool_name, payload={"error": message}, **kwargs)

    def end(self):
        self.sv.event(self.session_id, "session_end")

# ── Usage with LangChain ──
sv = SprintVibe("sv_live_...")
session = sv.session(agent_name="langchain-agent", model="gpt-4", team_name="research")

session.tool_call("web_search", {"query": "quantum computing papers 2026"})
session.tool_result("web_search", {"results": 15})
session.tool_call("summarize", {"text": "..."})
session.tool_result("summarize", {"summary": "Key findings..."})
session.end()

class SprintVibe {
  private url: string
  private headers: Record<string, string>

  constructor(apiKey: string, url = "https://sprintvibe.app") {
    this.url = `${url}/api/v1/ingest`
    this.headers = { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` }
  }

  async event(sessionId: string, eventType: string, data: Record<string, unknown> = {}) {
    fetch(this.url, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({ session_id: sessionId, event_type: eventType, ...data }),
    }).catch(() => {})
  }

  session(opts: { agentName?: string; model?: string; teamName?: string } = {}) {
    const sid = crypto.randomUUID()
    this.event(sid, "session_start", {
      agent_name: opts.agentName, model: opts.model, team_name: opts.teamName,
    })
    return {
      toolCall: (toolName: string, toolInput?: object) =>
        this.event(sid, "tool_call", { tool_name: toolName, tool_input: toolInput }),
      toolResult: (toolName: string, payload?: object) =>
        this.event(sid, "tool_result", { tool_name: toolName, payload }),
      error: (toolName: string, message: string) =>
        this.event(sid, "tool_error", { tool_name: toolName, payload: { error: message } }),
      end: () => this.event(sid, "session_end"),
      id: sid,
    }
  }
}

// ── Usage ──
const sv = new SprintVibe("sv_live_...")
const session = sv.session({ agentName: "my-agent", model: "llama-3.2", teamName: "backend" })

await session.toolCall("code_edit", { file: "app.ts", action: "add_function" })
await session.toolResult("code_edit", { success: true, lines_changed: 15 })
await session.end()

curl -X POST https://sprintvibe.app/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -d '{
    "session_id": "my-session-001",
    "event_type": "tool_call",
    "platform": "custom",
    "agent_name": "my-agent",
    "model": "llama-3.2",
    "tool_name": "web_search",
    "tool_input": {"query": "hello world"},
    "team_name": "research"
  }'

## Sprint Vibe
Quest: "Implement user settings page"
Quest ID: quest-settings-page
Branch: feature/settings-v1   # (or v2, v3 in other branches)
API Key: sv_live_YOUR_KEY

curl -X POST https://sprintvibe.app/api/v1/artifacts \
  -H "Authorization: Bearer sv_live_YOUR_KEY" \
  -F "type=screenshot" \
  -F "session_id=abc-123" \
  -F "quest_id=quest-456" \
  -F "route=/dashboard" \
  -F "viewport=1280x720" \
  -F "file=@screenshot.png"

{
  "spec": "Build a user settings page with: profile editing (name, avatar, bio), notification preferences (email, push, SMS toggles), connected accounts (GitHub, Google OAuth), danger zone (delete account with confirmation). Must be responsive and match the existing dashboard theme.",
  "context": {
    "tech_stack": "Next.js 16, Tailwind, Supabase",
    "existing_patterns": "Server components for data, client components for interactivity"
  }
}

// Response:
{
  "quests": [
    {
      "type": "main", "title": "User Settings Page",
      "sub_quests": [
        { "type": "sub", "title": "Profile editing section", "parallel_group": 1, "estimated_files": ["app/settings/page.tsx", "components/profile-form.tsx"] },
        { "type": "sub", "title": "Notification preferences", "parallel_group": 1, "estimated_files": ["components/notification-prefs.tsx", "lib/notifications.ts"] },
        { "type": "sub", "title": "Connected accounts", "parallel_group": 1, "estimated_files": ["components/connected-accounts.tsx", "app/api/oauth/route.ts"] },
        { "type": "sub", "title": "Danger zone (delete account)", "parallel_group": 2, "depends_on": ["Profile editing section"], "estimated_files": ["components/danger-zone.tsx", "app/api/account/delete/route.ts"] }
      ]
    }
  ],
  "conflicts": ["Profile editing and Connected accounts both likely touch app/settings/page.tsx"],
  "estimated_total_cost": "$8.50 with Opus, $2.10 with Sonnet"
}

{
  "period": "2026-02-07",
  "total_spend": "$34.20",
  "effective_spend": "$28.50",
  "waste_breakdown": {
    "redundant_reads": "$2.10 (43 occurrences)",
    "duplicate_searches": "$0.80 (12 occurrences)",
    "failed_attempts": "$2.40 (3 quests retried from scratch)",
    "over_qualified_model": "$0.40 (Opus used for 2 trivial test-writing quests)"
  },
  "recommendations": [
    "Route test-writing quests to Sonnet (saves ~$0.20/quest)",
    "Add offset/limit to file reads in components/ (agents read full files 67% of the time)",
    "Session 'abc-123' read lib/utils.ts 7 times — consider pinning to context"
  ]
}

{
  "gates": [
    { "type": "tests_pass", "command": "npm test", "required": true },
    { "type": "build_succeeds", "command": "npm run build", "required": true },
    { "type": "type_check", "command": "npx tsc --noEmit", "required": true },
    { "type": "lint_clean", "command": "npm run lint", "required": false },
    { "type": "visual_regression", "max_diff_score": 0.05, "required": false },
    { "type": "acceptance_criteria", "method": "llm_judge", "required": true },
    { "type": "no_secret_leak", "patterns": ["API_KEY", "SECRET", "PASSWORD", "sv_live_"], "required": true }
  ],
  "trigger": "attempt_complete"
}

POST https://sprintvibe.app/api/v1/ingest
Authorization: Bearer sv_live_...
Content-Type: application/json

{
  // ── Required ──
  "session_id": "string",         // Unique session/thread identifier
  "event_type": "string",         // See event types table above

  // ── Identity ──
  "platform": "string",           // claude_code | codex | openclaw | gemini | custom
  "agent_name": "string",         // Human-readable agent name
  "agent_role": "string",         // lead | teammate | subagent
  "team_name": "string",          // Group agents into teams
  "model": "string",              // Model name (claude-opus-4-6, gpt-4, etc.)

  // ── Tool data ──
  "tool_name": "string",          // Name of tool being called
  "tool_input": {},               // Tool parameters (any JSON object)

  // ── Context ──
  "channel": "string",            // whatsapp | telegram | slack | discord | web
  "parent_session_id": "string",  // Links subagent to parent session
  "cwd": "string",                // Working directory
  "permission_mode": "string",    // default | plan | dontAsk | bypassPermissions

  // ── Payload ──
  "payload": {},                  // Any additional data (tool output, errors, etc.)
  "metadata": {},                 // Arbitrary metadata tags

  // ── Claude Code auto-detection ──
  // When hook_event_name is present, platform is auto-set to "claude_code"
  // and event_type is auto-mapped from the hook event name.
  "hook_event_name": "string"     // SessionStart | PreToolUse | PostToolUse | etc.
}

{
  "success": true,
  "event_id": "uuid"
}

// 401 - Missing or invalid API key
{ "error": "Missing API key" }
{ "error": "Invalid API key" }

// 500 - Server error
{ "error": "Failed to store event" }

{ "status": "ok" }