AI Output Envelope

CaseSolo AI routes must return generated work in a shared ai envelope while preserving legacy top-level fields until UI consumers migrate.

Contract

Use buildAIOutputEnvelope() from src/lib/ai/output-envelope.ts.

Every generated AI payload should include:

answer: the route-specific result, such as an analysis object, briefing, chat response, or draft.
citations: route-safe citation references derived from sourceSpans.
sourceSpans: original retrieved source spans when RAG is used.
confidence: unknown, low, medium, or high; inferred from source similarity unless overridden.
model: model ID plus provider.
toolCalls: normalized tool execution records.
permissions: firm, user, case, role, scopes, and tenant-scope status.
approvals: whether human review is required and the checkpoint name.
cost: input/output/total tokens, credits, and optional USD estimate.
latency: start, completion, and duration.
audit: activity/run/request IDs, prompt ID, cache key, and cache status.

Keep existing response fields during migration, but add ai beside them.
Use real audit IDs when available. If no persisted audit exists, set auditId to untracked or a deterministic cache marker; do not fabricate database IDs.
Legal drafts, medical analysis, demand generation, outbound communications, and record-mutating AI actions should set approvals.required = true.
Advisory outputs like chat, briefing, and what-if scenarios may set approvals.required = false, but should still include a checkpoint or reason when useful.
RAG-backed routes must attach sourceSpans; the helper converts them into citations.
New AI routes should not invent custom model, tokens, confidence, or audit shapes.

executeAgent() returns AgentResult.envelope.
POST /api/agents/invoke returns ai for synchronous agent runs.
POST /api/ai/analyze returns ai for cached and live analysis.
GET /api/ai/briefing returns and caches ai.
Case-level generated-output routes now include ai for chat, drafts, scenarios, and medical-record analysis.