feat(tools): expose servedModel / costUsd disclosure on execution results (SAP-2764)

[gwitwer]

Summary

SDK half of a corrected server-side contract (internal tracker): expose the server's serving disclosure — the billing class + lane the request resolved to, in the SKU vocabulary the platform bills in. Never a model or provider id, never a provider price (an earlier draft's servedModel/provider costUsd are gone per the corrected contract, shipped as a server-side companion change).

What changed

• models.run — ModelRunOutcome.servedClass + lane (wire served_class/lane): the billing class (size) the run's label resolved to and the lane it executed in; modelUsed keeps meaning the requested label. costUsd is deprecated and now number | null: servers report null (the customer dollar amount is the metering pipeline's, summed on run views); older servers' numbers still map through.
• models.coding.run — CodingRunOutcome.servedClass/lane/deprecated costUsd (all null from coding servers today; null = unknown, never fabricated).
• llm.run / llm.redeem / llm.callSession — LlmDisclosure now describes served_class/lane (injected top-level into raw /v2 non-streaming bodies; streams carry the same data as x-sapiom-served-class/x-sapiom-lane headers); readDisclosure() returns the camelCase LlmDisclosureResult { servedClass, lane }. The response model field keeps echoing the label.
• Reserved degradation (typed unknown) unchanged.
• Minor changeset rewritten, calling out the costUsd number → number | null widening.

Compatibility

• All new fields optional/nullable → existing consumers compile/run unchanged; old servers map missing fields to null — covered on both mappers + readDisclosure.

Testing

• packages/tools: jest green (mapping incl. class/lane, old-server absent-fields, null-from-coding-servers, readDisclosure happy/absent/malformed); pnpm build clean; provider-neutral copy check passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SZmJ79CfTQ4M1EeY5RD9s9

[gwitwer]

Reworked in ca7c37b to the corrected disclosure contract (see the server-side discussion): the disclosure vocabulary is now billing class × lane — servedClass/lane replace servedModel everywhere, and costUsd is deprecated + nullable (servers report null; the metering pipeline owns customer dollars). LlmDisclosureResult is now { servedClass, lane }. This also fully retires the round-1 confidentiality concern class: no field can carry a provider identifier anymore, by construction. PR body updated; changeset rewritten with the number → number | null widening called out.

[gwitwer]

Closing — the disclosure contract changed: customer results carry served class + lane + token usage, never the provider model or provider-priced cost (per the platform's SKU contract). These servedModel/costUsd types would expose a contract the server no longer serves. Reissue as servedClass/lane/usage result types as part of the upcoming SDK ergonomics PR (the platform's corrected model-execution contract, internal, is authoritative on the shape).

[gwitwer]

Addressed in 7c4ef1c — point-by-point:

🔒 Vendor/codename in shipped JSDoc — Fixed. The JSDoc example is gone (field described by its semantics: "server-assigned identifier of the deployment"), and all spec fixtures use the opaque deployment-a. node scripts/provider-neutral-copy-check.mjs passes. (Note: some pre-existing internal label strings in submit.spec.ts predate this PR and are untouched — flagging separately if you want them swept.)

🔒 Private-repo pointer / internal-tracker link — Fixed. The contract path and ticket ids are out of the published JSDoc (fields are documented by their wire semantics instead), and the PR body no longer carries the internal tracker link or the private companion-branch description.

Missing changeset — Fixed. Added a minor changeset for @sapiom/tools that explicitly calls out the changed documented meaning of the existing ModelRunOutcome.costUsd (server-reported cost, served-priced when disclosed) alongside the new fields.

Cut degradation — Respectfully keeping it: reserving the optional degradation field in these exact result shapes is an explicit Must of the driving requirement ("Reserve the optional degradation field in the same result shape, populated by a follow-up"), so removing it would un-ship a requirement. To blunt the narrowing concern, it's documented as "server-defined shape" — consumers are told the shape isn't theirs to depend on, and Record<string, unknown> only permits reads of unknown, so a later concrete type narrows what they can assume, not what compiles.

JSDoc asserts backend behavior — Fixed. All disclosure docs now state what the wire field is and attribute interpretation to the server ("as reported by the server", "server-assigned identifier"), with no client-side guarantee implied, and no internal ticket ids in published docs.

LlmDisclosure snake_case / unnameable return type — Fixed the second half: readDisclosure now returns the named, exported camelCase LlmDisclosureResult. Keeping LlmDisclosure exported in wire shape deliberately: unlike the rest of the package, llm.run/redeem/callSession return raw provider bodies (generic T, snake_case throughout), so the type consumers intersect with those bodies (llm.run<Message & LlmDisclosure>) must match the wire casing — a camelCase version would describe fields that don't exist on the object. Its docstring now says exactly that.

Old-server path untested — Fixed. run-launch.spec gains an absent-fields case for mapModelResult, and a new coding-result.spec.ts covers coding's mapper for all three cases (null fields as today's servers emit, absent fields as older servers emit, values passed through).

[gwitwer]

Round 2 addressed in f316c8a:

degradation reservation — Keeping the field, hardening the type. Reserving degradation in these exact result shapes is an explicit Must of the driving ticket, so cutting it would un-ship a requirement — but your substantive concern (narrowing an untyped bag later breaks anyone who indexed into it) is real, so it's now typed unknown on all three public types (and the wire interfaces). Nothing can index into unknown without narrowing first, which makes the future concrete type purely additive — the breaking-change vector you flagged no longer exists. The changeset states the shape is server-defined and not yet stable.

Changeset precision — Fixed: it now says exactly which fields map to null on old servers (servedModel/costUsd via the mappers and readDisclosure) vs stay absent (degradation, raw body fields).

Checker gap — Added the deployment vendor's name from the round-1 finding to the provider-neutral copy checker's forbidden list, so that leak class can't regress silently; check passes on the tree.

Test execution — For the record since the sandbox blocked jest for you: npx jest --maxWorkers=1 on the three touched spec files → 13 passed; full packages/tools suite was green before round 2 (567 tests) and pnpm build is clean after it.