Implement accepted Issue #75 - #513

Implements the exact accepted scope for Issue #75.

Owner build authorization: #75 (comment)

Summary

Expose optional provider-neutral TypeScript response metadata with reported token totals across repair and retained filtering details on success and failure; add offline regression coverage and documentation crediting intuity-hans and unmerged PR 80.

Agreed work

Accepted work

Approved by the project owner, robgruen, for issue #75.

Goal

Let TypeScript applications inspect service-reported token usage and available content-filtering information alongside TypeChat responses, including reported totals across repair and retained information on failure, without changing validated application data or requiring a particular provider.

Scope

• Add optional provider-neutral metadata to TypeScript model and translation response envelopes on both success and failure, preserving existing text and application data types.
• Extract supported usage and available filtering details from the existing OpenAI Chat Completions, OpenAI Responses, and Azure OpenAI client paths.
• Retain each provider response's available metadata and aggregate reported token counts across initial and repair responses, preserving missing and partial reporting distinctions.
• Add deterministic offline mocked regression coverage and TypeScript documentation, preserving credit for intuity-hans and the closed, unmerged work in PR 80.

Non-goals

• Do not add metadata to model-generated or validated application data, weaken validation, or change repair limits and existing failure semantics.
• Do not add providers, vendor-bound core types, new moderation calls, or complete raw provider-response bodies to metadata.
• Do not estimate missing token counts, calculate prices, or claim reported-only totals account for usage the service did not report.
• Do not change Python APIs or perform unrelated refactoring.

Acceptance criteria

• Public TypeScript model and translation results expose optional provider-neutral metadata on both success and failure. Successful model data remains text, successful translation data remains the validated application object, and metadata is never inserted into that object or its schema.
• Mocked responses from the existing OpenAI Chat Completions, OpenAI Responses, and Azure OpenAI client paths expose their supported reported usage and available filtering details through the optional metadata. Missing filtering details remain optional. Metadata does not contain complete provider response bodies, and extraction makes no additional service or moderation requests.
• For an initial response reporting input 13, output 7, and total 20 tokens, followed by a repair reporting input 5, output 3, and total 8, translation exposes two ordered response records and reported totals of input 18, output 10, and total 28. Each response contributes exactly once, and separate translations do not share accumulated metadata.
• Fixtures distinguish unavailable counts from reported zero counts. Mixed reported and absent usage produces reported-only totals with partial reporting distinguishable from complete reporting. An aggregate with no reported count remains absent, and missing total counts are not inferred from other fields.
• Failure fixtures cover non-JSON text, JSON parse errors, schema and custom validation rejection, content-filtered responses, initial model failure, and failed repair. Each final failure retains all available metadata and reported usage while preserving existing message, rejected data, and responseText behavior. A later model failure does not erase metadata from an earlier response.
• Existing validation and additional instance validation still determine success. Disabling repair makes one model call, the default permits at most one repair call, and getData still returns application data on success and throws on failure. Metadata never converts a rejected or filtered result into success.
• A custom model whose complete method returns the existing promise of a text result without metadata still type-checks and translates valid output unchanged. Providers with no usage or filtering metadata remain usable without fabricated fields or a provider-specific dependency in the core result types.
• Deterministic offline mocked tests cover the supported client formats, full and partial usage, absent metadata, reported zeros, successful repair, final failures, compatibility, and isolation between translations. The tests require no credentials or live provider access.
• TypeScript documentation shows optional metadata on success and failure, lists supported token mappings and filtering fields for each existing API format, and explains per-response records, repair totals, partial reporting, and unreported usage. It credits intuity-hans for PR 80 without presenting that unmerged work as an available feature.

Existing contributions

• #80 at 4f3e378

Proposal run | Approved scope policy

This accepts the scope above. It does not start or authorize an automated implementation run, increase any budget, or approve merging. Material scope changes require a new proposal and owner decision.

Verified execution

• Fixed base: fd25d4412ac6232b183e17a97433ca7f7221b806
• Context SHA-256: 4253443df11e4d70a5f5ab1592259934e9579d559a25d49c3f608ba9329b3728
• Candidate SHA-256: 931d0c7d8a82aa677597a020537160c284b2c66ac4da08a3bd6aaa833bd0786a
• Full patch SHA-256: e9c53b6e63dac9bbc334696b0879168fbcb427f21363f16d678803d45452dd97
• Passed: git diff --check
• Passed: typescript: npm run build
• Passed: typescript: npm run build-all
• Passed: typescript: npm test
• Main inference: 124.05274 / 1000 AI credits
• Detection: 16.76878 / 400 AI credits
• Execution and usage records

Owner-authorized follow-up

The workflow published original commit adcfc9323fc2b5afa1130ed6a121c78a5d02a0a8. The owner separately approved:

• 58ee0f8c285227e4096194a95f25e9f9d38f24a2: run the metadata suite in ordinary npm test and update its documented command.
• fa9d14c7f6786b9ad22de42f4effc67339ae94bb: report filtered/refused replies with a concise error instead of dumping the provider body into the message; preserve original records and application results while explicitly marking omitted, unrepresentable token totals as overflow.
• 1c1abe6f9566ecd7d691596344911ce1f30f83bd: include the metadata guide in npm packaging and link it from the published README; extend the existing package-consumer test to verify the exact packed guide and complete guide URL. The README uses an absolute GitHub link so npm rendering does not depend on repository-subdirectory rebasing.

The original context/candidate/patch hashes and isolated-check/scan evidence above remain tied to the original automated commit. They have not been rewritten to claim coverage of these owner-approved follow-ups. The documentation-packaging/discovery finding was initially deferred and is now addressed by the documentation-only follow-up.

Verification before the documentation-only follow-up

• Default npm test passes all 241 tests with no failures or skips. The 21 metadata tests cover filtered error privacy, exact safe-integer boundaries, unaffected counts, overflow during HTTP retries, and repair success/failure retention.
• All 12 current-head CI checks pass, including Node 22.23.4, 24.22.1, and 26.12.1 plus aggregate CodeQL. Copilot reports no active review issues and recommends approval; human review and merge remain separate decisions.
• Earlier local live checks passed six success/repair/failure scenarios across two configured Azure Chat Completions routes, using eight requests.
• Additional local validation on the latest commit succeeded through a derived Azure v1 Responses route using the configured deployment as the model. Its real usage was 119 input, 35 output, and 154 total tokens.
• Non-directed profanity quotations were allowed and returned unchanged by both Responses and Chat Completions, each with HTTP 200. These are observations of allowed behavior, not evidence of a genuine blocked response. The three additional requests reported 383 total tokens.
• Configured endpoint addresses, access tokens, and raw diagnostic records remain local and are not included in this public summary.

Limitations

• Genuine blocked/refusal behavior remains covered by deterministic mocked tests, not a live filter-triggering request. The profanity probes did not trigger blocking.
• The live Responses check covers one configured resource/deployment, not every endpoint in the configuration.
• No second coding/detection workflow was run for the owner-authorized follow-ups. Their verification is local testing and fresh ordinary PR CI, not the original full-patch scan.
• No automatic approval, merge, issue closure, release, or scope expansion is authorized.

Documentation-only follow-up verification

• The focused package-consumer regression passes on pinned Node 24.22.1 at 1c1abe6f9566ecd7d691596344911ce1f30f83bd. It builds the root and workspaces, creates and extracts the real npm tarball, verifies the guide matches the source and the packaged README links to its exact GitHub URL, and validates the package in a clean TypeScript 7 consumer. No live provider calls were made.
• All 12 CI checks pass at 1c1abe6f9566ecd7d691596344911ce1f30f83bd, including the Node 22.23.4 / 24.22.1 / 26.12.1 builds, Python Pyright matrix, CodeQL, and CLA check. Human review and merge remain separate decisions.