F42: Add session_id support for agent/session cost tracking

[peterkacerik]

Summary

• Add session_id to AllowedTagKey and ALLOWED_TAGS for first-class session tracking support
• Extend SessionBudget with optional sessionId config that auto-injects session_id tag into all tracked events
• Add createSession() factory that generates sess_<random> IDs using crypto.randomBytes (Node 18 compatible)
• Include session_id in enforcement events when configured

Task

Task file: aispendguard-tasks/active/features/F42-agent-session-cost-tracking.md

Changes

File	Change
src/types.ts	Added session_id to AllowedTagKey, added CreateSessionConfig type
src/validate.ts	Added session_id to ALLOWED_TAGS set
src/session-budget.ts	Added sessionId config, auto-tag injection in trackUsage(), session_id in enforcement events
src/index.ts	Added createSession() factory export, CreateSessionConfig type export
tests/session-budget.test.mjs	7 new tests for session_id features

Implementation Coverage

• Step 1 (types + validation): src/types.ts AllowedTagKey + CreateSessionConfig, src/validate.ts ALLOWED_TAGS
• Step 2 (SessionBudget extension): src/session-budget.ts sessionId field, auto-injection, enforcement events
• Step 3 (createSession factory): src/index.ts createSession() + exports
• Step 7 (tests): tests/session-budget.test.mjs — 7 new test cases

Testing

• npm run build passes
• All 52 tests pass (1 skipped for env)
• New tests added for: sessionId auto-tagging, override behavior, no-sessionId passthrough, createSession factory (auto + explicit ID), enforcement event session_id

Sentinel Findings Addressed

• N2: Using crypto.randomBytes(6).toString('hex') instead of crypto.randomUUID() for Node 18 compat

🤖 Generated with Claude Code

[peterkacerik]

Sentinel Code Review — APPROVED

All planned SDK changes implemented correctly:

• session_id added to AllowedTagKey union and ALLOWED_TAGS set
• SessionBudget extended with sessionId auto-tag injection
• createSession() factory with randomBytes (Node 18 compat)
• 6 new test scenarios covering auto-tagging, override, factory, enforcement events

Security: Tag validation preserved, privacy invariant maintained, no injection vectors. CI green on Node 18/20/22.

No blocking findings. Ready to merge.

[peterkacerik]

Code Review — APPROVED (Sentinel)

PR #7 — F42: session_id support in SDK

Mandatory Scans

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

Security: CLEAN

• session_id goes through normalizeTags() validation (max 120 chars)
• FORBIDDEN_KEYS guard unchanged — privacy invariant maintained
• Auto-generated IDs via crypto.randomBytes(6) — sufficient entropy

Non-blocking Findings

1. [MEDIUM] Redundant sessionId on SessionBudgetConfig and CreateSessionConfig
2. [LOW] No early validation at construction time (deferred to trackUsage)
3. [LOW] Config sessionId silently overrides user tag — tested but undocumented

Tests: 7 new test cases. PASS.

Merge blocked by B30.