feat(F69): Mastra agent framework integration

[peterkacerik]

Summary

• Adds createMastraExporter() helper for Mastra's native OTEL telemetry
• Thin config helper (~75 lines) — no new runtime dependencies
• Maps Mastra's GenAI OTEL traces to AISpendGuard events via existing OTLP endpoint
• 3-line user setup: telemetry: createMastraExporter({ apiKey: "asg_..." })

Changes

File	What
src/mastra.ts	OTEL exporter config builder with API key validation, default tags, source auto-set
src/index.ts	Re-export createMastraExporter and MastraExporterConfig
package.json	./mastra export map entry, @mastra/core optional peer dep, "mastra" keyword
tests/mastra.test.mjs	14 tests: valid config, API key validation, default tags, source override, service name, return shape, no forbidden keys

Cross-repo docs

• aispendguard-docs/sdk/mastra.md — full integration guide (committed to docs repo)
• aispendguard-app/app/(docs)/docs/page.tsx — Mastra section (pending, requires app repo branch)

Test plan

• All 60 SDK tests pass (59 pass, 1 skipped live test)
• TypeScript compiles clean
• E2E: Mastra agent -> OTLP endpoint -> UsageEvent (follow-up in aispendguard-testing)

🤖 Generated with Claude Code

[peterkacerik]

Code Review — Sentinel (2026-04-10)

Verdict: APPROVED

SDK PR #9 diff reviewed (4 files, +199 new lines). Adds Mastra agent framework OTEL exporter config helper.

Mandatory Scans

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

Security

• API key validation: apiKey.startsWith("asg_") — prevents misconfigured keys
• Privacy invariant: 14 tests, including forbidden key check verifying no prompt/completion/messages/content in config
• source tag auto-set to "mastra" — correct source tracking
• Tags prefixed with aispendguard.tag.* for OTEL resource attributes — proper namespace isolation
• Config builder only — no network calls, no SSRF risk
• Optional peer dependency on @mastra/core — no forced install

Quality

• 14 comprehensive tests covering: valid config, invalid API key (3 cases), default tags, source tag auto-set/override, service name, return shape, forbidden keys
• Export map with ./mastra sub-path — clean tree-shaking
• Re-exported in src/index.ts — discoverable
• SDK docs created at aispendguard-docs/sdk/mastra.md

Documentation

SDK docs created. App docs page Mastra section pending (requires F54 branch merge first) — acceptable, follow-up tracked.

Regression Check

Patterns #1-#11: all clear.

Merge blocked by B30 (Vercel ERROR state — app repo). SDK can be merged independently if desired.

[peterkacerik]

Rebase Required

PR has merge conflicts (mergeStateStatus: DIRTY). Please rebase onto main and resolve conflicts before I can proceed with merge.

— Sentinel

[peterkacerik]

Sentinel Post-Rebase Review: APPROVED

Rebase conflict in src/index.ts resolved cleanly — Vercel AI SDK exports from main + Mastra exports from branch both preserved. No functional changes from previously approved code.

Mandatory scans: No conflict markers ✅, no dangerous patterns ✅.

Diff confirmed:

• src/mastra.ts (75 lines) — OTEL exporter config helper unchanged ✅
• package.json — export map + optional peer dep ✅
• src/index.ts — clean re-exports ✅
• tests/mastra.test.mjs (14 tests) — comprehensive coverage ✅

Merging now.