F39: Vercel AI SDK integration

[peterkacerik]

Summary

• Adds createAISDKOnFinish() callback factory for automatic usage tracking from Vercel AI SDK's generateText(), streamText(), and generateObject()
• Adds createVercelAIUsageEvent() pure helper for manual event construction
• Privacy-safe: only reads result.usage and result.response metadata — never accesses text, toolCalls, toolResults, object, or rawResponse

Task

Task file: aispendguard-tasks/active/features/F39-vercel-ai-sdk-integration.md

Changes

File	Change
src/types.ts	Added VercelAIOnFinishResult and VercelAIConfig types
src/vercel-ai.ts	New — callback factory + event helper + provider detection
src/index.ts	Added exports for new functions and types
tests/vercel-ai.test.mjs	New — 14 tests: provider detection, privacy traps, latency edge cases, fire-and-forget

Implementation Coverage

• Step 1 (Add Vercel AI types): src/types.ts — VercelAIOnFinishResult, VercelAIConfig
• Step 2 (Implement callback factory): src/vercel-ai.ts — createVercelAIUsageEvent(), createAISDKOnFinish(), detectProvider()
• Step 3 (Add exports): src/index.ts — function and type exports
• Step 4 (Write tests): tests/vercel-ai.test.mjs — 14 test cases
• Step 5 (Documentation): Post-merge — will update docs page in aispendguard-app and aispendguard-docs/sdk/

Testing

• npx tsc --noEmit passes
• npm run build passes
• Existing tests pass (58/58, 1 skipped live test)
• New tests added for: provider detection (5 tests), event creation (4 tests), latency edge cases (2 tests), config override (1 test), fire-and-forget (1 test), privacy invariant (2 tests with property traps)

Documentation

• Docs page update (aispendguard-app/app/(docs)/docs/page.tsx) and SDK docs (aispendguard-docs/sdk/) to be done post-merge per plan Step 5 (RECOMMENDED, not blocking)

[peterkacerik]

Sentinel Code Review — ✅ APPROVED

Mandatory Scans

• Conflict markers: none ✅
• Dangerous patterns: none ✅
• Merge state: CLEAN ✅

Implementation Completeness (4/4 critical steps)

1. src/types.ts — VercelAIOnFinishResult + VercelAIConfig types, privacy-sensitive fields commented out ✅
2. src/vercel-ai.ts — createAISDKOnFinish factory + createVercelAIUsageEvent helper + detectProvider ✅
3. src/index.ts — exports added ✅
4. tests/vercel-ai.test.mjs — 14 tests (provider detection, privacy traps, fire-and-forget, config override) ✅
5. Documentation — marked as post-merge follow-up (acceptable) ✅

Security Checklist

• Privacy invariant preserved — only reads usage + response metadata. NEVER reads text/toolCalls/toolResults/object/rawResponse. Privacy getter-trap tests verify this.
• Fire-and-forget — try/catch wrapper ensures tracking failures never break user code
• No injection vectors — tags are merged from config, not user input
• No new dependencies — uses only existing SDK internals
• Latency clamped — Math.max(0, ...) prevents negative values from future timestamps

Quality

• 58/58 tests passing (14 new for Vercel AI, all existing pass)
• TypeScript clean
• Pure function separation (createVercelAIUsageEvent vs createAISDKOnFinish) — testable
• Default tags follow existing pattern (task_type: "chat", feature: "default", route: "default")
• Provider detection covers OpenAI, Anthropic, Google, Cohere, Mistral with "unknown" fallback

Findings

No blocking findings. Clean implementation.

NOTE: This is an SDK change — requires publish task for The King (npm release). Sandra should create this after QA.

Merge blocked by B30 (Vercel ERROR on aispendguard-app). SDK PR itself is mergeable but per sequential gate, will merge after B30 resolution.

[peterkacerik]

Code Review — APPROVED (Sentinel)

PR #8 — F39: Vercel AI SDK integration

Mandatory Scans: CLEAN

Security: CLEAN

• No secrets. No HTTP endpoints. Pure event mapper.
• Privacy: STRONG — only accesses usage tokens + response metadata. Privacy-trap tests enforce no content access.

Non-blocking

1. [MEDIUM] usage tokens — add ?? 0 fallback for runtime safety
2. [LOW] response field optionality — align type with defensive ?. access
3. [LOW] Default task_type:'chat' — consider 'inference'
4. [INFO] Verify rebase on current main

Tests: 14 tests including privacy traps. PASS.

Merge blocked by B30.