Made of little things.

# AI request diagnostics and model discovery

> Legacy bridge reference. The active UI uses [shell LLM or paid CVM](llm-value-reference.md); the provider-key editor and raw diagnostics described below are no longer active.

Feature brief, 2026-10-26: make failed reports inspectable without accepting
invalid output as an assessment. Preserve the white/off-black/orange interface;
use a collapsible diagnostic panel within the existing review, with bounded,
copyable text areas and explicit status/error labels at narrow and touch sizes.

The existing encrypted CVM bridge reads upstream SSE and exposes bounded progress
through actor-owned job polling. No browser network, new NAP domain or relay
escape hatch. Show timing/stages, HTTP status, provider response ID, finish reason,
usage where supplied, schema field failures, raw assistant output and any
provider-exposed reasoning output. Never invent a thinking stream or imply that
all vendors expose one. Partial/unvalidated text stays separate from the report.
Credentials are redacted before leaving the bridge and again at the client;
headers and request bodies are excluded. Diagnostics stay in memory, expire with
bridge jobs, clear with the case and are not autosaved or logged.

Model discovery uses GET /models via the trusted bridge and the connection's key;
no case or inference request. The editor offers returned IDs plus manual entry,
preserves the chosen ID even when absent, rejects stale results after edits and
keeps discovery distinct from text/vision verification. Explicit refresh plus
loading saved trusted connections is authorized; no model lookup on keystrokes.
Hard/optional domains and host boundaries are unchanged.


## Provider references

Checked 26 October 2026 against the published provider interfaces:
- [DeepSeek model listing](https://api-docs.deepseek.com/api/list-models/) and
  [chat streaming](https://api-docs.deepseek.com/api/create-chat-completion/).
- [Kimi model listing](https://platform.kimi.ai/docs/api/list-models) and
  [chat streaming / reasoning_content](https://platform.kimi.ai/docs/api/chat).
- [OpenAI model listing](https://developers.openai.com/api/reference/resources/models/methods/list)
  and [Chat Completions streaming](https://developers.openai.com/api/docs/guides/streaming-responses).

The existing Chat Completions route does not expose reasoning text for every
provider/model. The UI says when no reasoning text was returned; it does not
attempt to recover hidden internal reasoning or add another model request.
Protocol 4 requires an updated bridge. Earlier failed responses were discarded
and cannot be recovered by this upgrade; a new explicit request is needed.

## Response formatting correction — 27 October 2026

The supplied Kimi response finished normally but omitted the closing brace of
`evidence` before `assessments`. HTTP 200 and `finish_reason: stop` establish a
completed request, not valid assistant JSON. Previously the report prompt alone
specified the format; the API request did not constrain it.

Analysis now requests strict JSON Schema output from OpenAI and Kimi, and JSON
object mode from DeepSeek. Connection checks also request JSON object mode.
The schema constrains fields and nesting; the existing app validation still
checks limits, observation IDs and whether patient-photo evidence was supplied.
Provider references: [Kimi Structured Output](https://platform.kimi.ai/docs/guide/response_format),
[OpenAI Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs),
and [DeepSeek JSON mode](https://api-docs.deepseek.com/guides/json_mode/).
Models must support the requested format; unsupported request options surface
the provider error and never trigger a silent extra inference request.

For a completed response with exactly one missing child-object closing brace,
the bridge tries bounded insertion positions before recognized report fields.
It accepts only a single unambiguous result that passes the full detailed-report
validator without changing or dropping any fields or values. Duplicate keys,
extra fields, missing final root braces, multiple missing braces, malformed
strings, incomplete streams and invalid reports remain rejected. Ordinary
semantic checks still run after recovery. No text is invented, and no repair
request is sent to a model.

Diagnostics retain the original output and show a **JSON formatting recovered**
notice when used. Unrecoverable syntax failures include the parser's error and
position where available, with the existing key redaction. Diagnostics remain
session-only. Restart `pnpm ai:bridge` to use this correction; protocol stays at
4. The change does not retroactively rerun a failed request in an open page.

### No-photo disclaimer correction

A subsequent valid JSON report put "No patient photographs were attached or
reviewed" and a body-map limitation in `evidence.visual`. The blanket nonempty
array check misidentified that disclosure as a claim of photo findings.

Each request now derives the photo count from the actual attached image payload,
never case metadata. Without patient photos, the provider schema sets
`evidence.visual.maxItems` to zero; all providers receive an explicit instruction
to return `[]` there and put absence disclosures in `limitations` or
`evidence.missing`. Photo-bearing requests keep the normal visual-evidence list.
Schemas are copied per request to avoid leaking this constraint across requests.

The response check recognizes only a narrow English source-absence grammar,
including the reported body-map-only caveat with location/layer/pose labels.
When every entry is such a disclaimer, the photo-findings list becomes empty
and diagnostics explain the omission while retaining the exact original output.
All other report fields remain unchanged. Any finding, mixed list, appended
claim, unrecognized phrase or ambiguous wording still fails; a no-photo prefix
alone is not sufficient. This is source categorization, not medical validation
or a general natural-language classifier. No extra inference request is made.

The existing diagnostic panel displays a **Photo evidence note** with unchanged
layout, palette and host boundaries. Protocol remains 4; restart the bridge to
apply the new request constraints and response handling.

## Verification

Verified 26 October 2026:

- `pnpm verify`: 90 tests passed, including guidance, malformed JSON/schema,
  interrupted streams, split UTF-8/CRLF, bounded output, secret redaction,
  diagnostic pagination and model discovery. Type checking and build passed.
- `pnpm test:conformance`: 5 passed, 0 failed, 5 skipped. Manifest, wire and
  lifecycle evidence remains unmeasured by this reference harness.
- `pnpm test:ai:transport`: encrypted ContextVM handshake and actor isolation,
  paged diagnostics, model listing, idempotent starts and two-phase connection
  verification passed through a loopback relay with synthetic provider replies.
- `pnpm test:diagnostics:ui http://127.0.0.1:4173/`: real soyLI iframe/storage
  with the actual bridge behind a test CVM adapter. Confirmed reasoning before
  completion, retained invalid output, escaping/redaction, no accepted invalid
  report, no saved diagnostics, model selection/manual IDs, failed lookup
  fallback and stale lookup rejection. Required 200×160, 320×560, 900×600 and
  1600×1000 frames, host light/dark and touch 390×844 / 844×390 passed.
- `pnpm test:ai:ui`: existing connection, photo review, persistence, stop,
  report, missing-storage and no-WebGL flows passed with synthetic providers.
- `soyli check`: checked under `space-playback-6`, Chromium 153.0.8010.12;
  preview HTML 131,758 bytes, source 36,017,874 bytes. Artifact hash:
  `b0efcac24df6e8869d0161672e1bdff4f31a74f354d46e7e6857506e5bf9dfa3`.

Browser captures are under the ignored `.napplet-space/diagnostic-checks/`.
No real provider requests or charges were made during verification. Browser
contexts and test bridges were closed. The pre-existing user-owned preview at
port 4173 was reused and left running; no new preview process was started.

Verified the formatting correction on 27 October 2026:

- Replayed the entire supplied 13,592-character response through the provider
  adapter with a synthetic transport. Inserting the single missing brace was
  sufficient; all three assessments passed validation and every field/value
  matched the corrected JSON. The original raw output was retained unchanged.
- `pnpm verify`: 94 tests passed, type check and build passed. New regressions
  cover provider format options, recovery in streaming/nonstreaming replies,
  rejection of unsafe repairs, original-output retention and syntax positions.
- `pnpm test:ai:transport` and `pnpm test:ai:ui` passed with synthetic replies,
  including connection verification, stop/error handling and persistence.
- `pnpm test:diagnostics:ui http://127.0.0.1:4173/` passed with no browser errors.
  The actual bridge accepted the missing-brace fixture, displayed the recovery
  notice and retained the malformed original without another provider request.
  The four required frame sizes, both host themes and touch portrait/landscape
  passed; inspected the narrow and 900-pixel recovery-panel captures.
- `pnpm test:conformance`: 5 passed, 0 failed, 5 skipped, with the same unmeasured
  manifest, wire and lifecycle checks as above. `soyli check` passed under
  `space-playback-6`, Chromium 153.0.8010.12. Artifact hash:
  `38dc3fcc98d8a40af85cee480590ddd97b1c2cca497b6fe769a5dc5aa77183c7`.

No live provider call was made, so live enforcement of the schema by each vendor
remains untested. No production bridge was restarted. All test contexts/bridges
closed, and the pre-existing user-owned soyLI preview remained running.

Verified the no-photo correction later on 27 October 2026:

- Replayed the full supplied 16,886-character response through `callProvider`.
  It is accepted with `evidence.visual: []`; all other fields are unchanged,
  and diagnostics retain the original output and explain the omission.
- `pnpm verify`: 98 tests passed, type check and build passed. Regressions cover
  actual photo counts, body maps versus photos, metadata that claims photos were
  sent, per-request schema isolation, streaming and nonstreaming disclaimers,
  mixed/appended/unrecognized photo claims and preservation of real-photo output.
- `pnpm test:diagnostics:ui http://127.0.0.1:4173/`: passed with no browser errors,
  including combined brace recovery/disclaimer normalization, visible notes,
  original output retention and no extra inference. Four frame sizes, both host
  themes and touch portrait/landscape passed; inspected the 320-pixel notice.
- `pnpm test:conformance`: 5 passed, 0 failed, 5 skipped (manifest/wire/lifecycle
  evidence still unmeasured). `soyli check` passed under `space-playback-6`,
  Chromium 153.0.8010.12, artifact hash
  `f3d52f0258f2e8819bcc588c883c4f16e567fe51e6bfd56928aeb47469dff2cb`.

Only synthetic transport replies were used. No real inference calls or production
bridge restarts; the existing user-owned preview was reused and left running.
Test browser contexts and the test bridge were closed.