chore: sync OpenAPI contract

[JasonLovesDoggo]

Automated sync of `contract/openapi.yaml` from the monorepo.

Source commit: trylitmus/litmus@472e2bf1b2ee3469407923dd498a51b08312638b

Review the diff, then merge. If the SDK has codegen (e.g. `pnpm generate`),
run it after merging to update generated types.

[greptile-apps]

Greptile Summary

This automated sync adds a new $sessionend event type (with an explanatory note distinguishing it from $abandon) and eight new optional LLM-metrics fields — model, provider, input_tokens, output_tokens, total_tokens, duration_ms, ttft_ms, and cost — to the Event schema. All changes are additive and backwards-compatible; no existing fields or endpoints are modified.

Confidence Score: 5/5

Safe to merge — all changes are additive and backwards-compatible with no breaking modifications.

The only finding is a P2 design note about total_tokens lacking an enforcement constraint, which is inherent to OpenAPI 3.0 and does not block merge. No P0/P1 issues were found.

No files require special attention.

Important Files Changed

Filename	Overview
contract/openapi.yaml	Adds $sessionend event type with clarifying docs, and 8 new optional LLM-metrics fields (model, provider, input/output/total tokens, duration_ms, ttft_ms, cost) to the Event schema. All additions are backwards-compatible. Minor concern: total_tokens is an independent field with no schema-level constraint enforcing it equals input_tokens + output_tokens.

Entity Relationship Diagram

%%{init: {'theme': 'neutral'}}%%
erDiagram
    Event {
        string id PK
        string session_id
        string type
        string project_id
        string prompt_id
        string prompt_version
        string generation_id
        string user_id
        string model "NEW"
        string provider "NEW"
        integer input_tokens "NEW"
        integer output_tokens "NEW"
        integer total_tokens "NEW"
        integer duration_ms "NEW"
        integer ttft_ms "NEW"
        number cost "NEW"
        object metadata
        string timestamp
    }

    EventType {
        string value
    }

    Event ||--|| EventType : "type references"

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: contract/openapi.yaml
Line: 153-155

Comment:
**`total_tokens` has no consistency constraint**

`total_tokens` is described as "input + output" but is an independent field — OpenAPI 3.0 has no mechanism to enforce the arithmetic. A caller can supply mismatched values (e.g., 100 input, 200 output, 999 total) and the contract accepts the payload without complaint. If the server stores all three independently, this can silently produce inconsistent analytics. Consider either computing `total_tokens` server-side and removing it from the schema, or documenting that the server ignores it when both `input_tokens` and `output_tokens` are provided.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "chore: sync OpenAPI contract from monore..." | Re-trigger Greptile}

[greptile-apps]

total_tokens has no consistency constraint

total_tokens is described as "input + output" but is an independent field — OpenAPI 3.0 has no mechanism to enforce the arithmetic. A caller can supply mismatched values (e.g., 100 input, 200 output, 999 total) and the contract accepts the payload without complaint. If the server stores all three independently, this can silently produce inconsistent analytics. Consider either computing total_tokens server-side and removing it from the schema, or documenting that the server ignores it when both input_tokens and output_tokens are provided.

Prompt To Fix With AI

This is a comment left during a code review.
Path: contract/openapi.yaml
Line: 153-155

Comment:
**`total_tokens` has no consistency constraint**

`total_tokens` is described as "input + output" but is an independent field — OpenAPI 3.0 has no mechanism to enforce the arithmetic. A caller can supply mismatched values (e.g., 100 input, 200 output, 999 total) and the contract accepts the payload without complaint. If the server stores all three independently, this can silently produce inconsistent analytics. Consider either computing `total_tokens` server-side and removing it from the schema, or documenting that the server ignores it when both `input_tokens` and `output_tokens` are provided.

How can I resolve this? If you propose a fix, please make it concise.