Mmsp Dev

---
name: mmsp-dev
description: Fixed workflow for developing MMSP itself — adding or updating model support, and changing its pages. Use when asked to support a new model or protocol version in this repository, sync llmsdk_docs, implement a provider client, or change the playground, the tracer or the site. Covers doc syncing, live API capture, paired Python/TypeScript implementation, model-scoped e2e testing, and the UI rules for the three pages.
---

# MMSP Development Workflow

Adding or updating model support follows the stages below, in order. Where a stage says **stop and ask**, pause and ask the user; do not continue until the issue is resolved, and never fill the gap yourself.

## Directory map

```
llmsdk_docs/<model_version>/      Official docs snapshot, one folder per model generation (README.md + docs/)
api_captures/<protocol>/          Git-ignored raw API captures: request payloads + stream events
src_py/mmsp/<client_type>/        Python client, one folder per client type: <vendor>_official/ or <protocol>/
src_py/mmsp/auto_client.py        Creates the client a client_type names; a model id's family names its official client
src_ts/src/<client_type>/         TypeScript client, mirrors the Python folder
src_ts/src/autoClient.ts          TypeScript routing, mirrors auto_client.py
src_py/tests/test_client.py       Parameterized e2e tests (env-gated AVAILABLE_MODELS)
src_ts/tests/client.test.ts       Same for TypeScript
changelog/unreleased/             Where unshipped changes go; renamed to the version at release
changelog/<version>/              Release summary (README.md) plus one detail file per entry
changelog/README.md               The entry format: metadata block, body rules, bilingual pairing
CHANGELOG.md                      One brief line per release linking into changelog/
src_py/mmsp/integration/          The playground and the tracer pages, mirrored in src_ts/src/integration/
site/                             The Astro site at mmsp.penguin.ooo
.agents/skills/mmsp-dev/kill-ai-slop/   Vendored AI-slop guide and scanner for the UI work below
<name>.zh.md                      Chinese counterpart, required for every file in changelog/
```

## Stage 1 — Sync official docs into `llmsdk_docs/`

- Sources must be the model vendor's official documentation site (e.g. docs.anthropic.com, platform.openai.com, ai.google.dev). Never use third-party mirrors, blog posts, or model memory.
- Save the snapshot under `llmsdk_docs/<model_version>/` following the existing folder conventions, and list the folder in `llmsdk_docs/README.md`. Running this workflow is the explicit request that the repository rule against editing `llmsdk_docs/` asks for.
- When the fetched docs differ from an existing snapshot, the new official docs win: update the old files in place.
- The snapshot must be complete enough to implement from: request/response schemas, streaming event sequence, thinking output, tool calling, usage fields, and error responses.
- **Stop and ask** if the official URL is uncertain or a page cannot be fetched. The user can paste the content manually.

## Stage 2 — Capture a live API exchange into `api_captures/`

- Gate: the provider's API key environment variable must be set and usable. Use the same environment variables and base URLs as `src_py/tests/test_client.py` (`AVAILABLE_MODELS` gating and `_create_client`). **Stop and ask** the user to supply the key if it is missing; the workflow must not continue without it.
- Using the provider's official SDK, or raw HTTP exactly as documented, run one streaming tool-call request with thinking enabled, then send the tool result back so the capture also shows how assistant turns are re-sent.
- Save the complete exchange unmodified under `api_captures/<protocol>/` (git-ignored), e.g. `round1.request.json` plus `round1.stream.jsonl` with every raw stream event in order. Never save credentials.
- When something in the exchange will not serialize to JSON (binary payloads, SDK objects holding non-JSON values), save its `str()` form and analyze from that. Keep the container parseable: wrap the text in a JSON object so the `.jsonl` stays one JSON value per line (`{"unserializable_str": "<str(event)>"}`, keeping the event in stream order), or put the whole exchange in a sibling `.txt` when nothing about it serializes. A `str()` capture is still the authoritative record of what the API returned. Never drop the event, hand-edit it into valid JSON, or fall back to the docs because serialization failed.
- **Stop and ask** on any API error (invalid key, insufficient quota, rate limit). Do not mock the response or continue from docs alone.
- The capture is the primary implementation reference and outranks the docs: where they disagree, implement what the API actually returned.
- Then probe the replay, because the capture only shows what the API *sends*, not what it *needs back*. Re-send the assistant turn repeatedly, each time with one candidate field removed — the reasoning item's id, its content, the whole reasoning item, each field you were tempted to keep — and record which removals the API still accepts with the model's behavior intact. That result, not the shape of the response, decides what Stage 3 stores. Save the probe outcomes next to the capture.

## Stage 3 — Implement the Python and TypeScript clients

- One folder per client type, named after it: an **official client** per vendor (`openai_official/`, `anthropic_official/`, `gemini_official/`, `zai_official/`, `moonshot_official/`, `deepseek_official/`, `minimax_official/`) speaks the vendor's own API, knows every generation of the vendor's models, and reads the vendor's key from the environment; a **compatible client** per wire protocol (`openai_responses/`, `openai_chat/`, `openai_chat_vllm_adapter/`, `openai_embedding/`, `ant_messages/`, `google_genai/`) speaks that protocol for any endpoint. The class is named after the folder (`OpenAIOfficialClient`, `OpenaiChatClient`), and the client type is the folder name with hyphens (`openai-official`, `openai-chat`).
  - A new generation of a vendor's models goes into the vendor's official client. Diff the new protocol (capture + docs) against what the client sends today; where a generation differs, even by a single key name, tell the generations apart inside the client by explicit version (`"4-6" in self._model`, `"gpt-6" in self._model`), never by a bare substring like `"claude" in model`, and keep the older generations working. Never drop a generation unless the user explicitly instructs it.
  - A new vendor gets a new official client folder, a new `<vendor>-official` client type in `auto_client.py` / `autoClient.ts`, and a new row in the model family table there: the family is the prefix every id of the vendor's models begins with (`glm-`, `kimi-`), matched case-insensitively.
  - A new wire protocol that several vendors serve gets a compatible client folder and client type; a compatible client carries no vendor's quirks.
- `auto_client.py` / `autoClient.ts` create the client a `client_type` names, from the one table of client types. Without a `client_type`, the family a model id begins with names its official client; an id of no known family raises and asks for one. The routing has no other rule: no substring matching on model ids, no version matching outside the official clients.
- **A credential goes only where it was given for.** This is the security model, and every client constructor follows it. A key passed as `api_key` is used as it is. A client that reads the environment's generic key (`OPENAI_API_KEY` for `openai_official` and the OpenAI-protocol compatible clients, `ANTHROPIC_API_KEY` for `anthropic_official` and `ant_messages`, `GEMINI_API_KEY` for `google_genai`) reads it only when the endpoint comes from the environment too (`OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` / `GEMINI_BASE_URL`, or the provider's own default): given a `base_url` and no `api_key`, it raises at construction instead of sending that key to another endpoint. That is `resolve_credentials` / `resolveCredentials` in `utils`; call it, do not reimplement it. Any other official client (`deepseek_official`, `zai_official`, `moonshot_official`, `minimax_official`, `gemini_official`) reads its own variable (`DEEPSEEK_API_KEY`, `ZAI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_API_KEY`, `GEMINI_API_KEY`) whatever base URL it is given, and never the generic one; without either it raises `<VAR> is required for <Client>.`. Hand every credential to the vendor SDK explicitly, including "none" (`authToken: null` in TypeScript, a cleared `auth_token` in Python), because the SDKs fill whatever they are not handed from their own environment variables. The offline tests in `tests/env-credentials.test.ts` / `tests/test_env_credentials.py` build every client under a controlled environment and read the credential the SDK instance holds; add a new client to them.
- Replay must be **minimal, not exhaustive**. A replayed assistant turn has to be accepted by the API with the model's behavior intact; it does not have to reproduce the wire item field for field. `fidelity` is an exception channel, not a mirror of the payload: a field earns a place there only when the Stage 2 probe shows the request fails or the model degrades without it. Provider-generated ids the API regenerates or ignores — a reasoning item id, an output-item id — stay out. Fields the API demands go in: GPT-5.5's `phase`, Claude's thinking `signature`, the exact reasoning field name a strict upstream requires.
- Never copy into `fidelity` what a universal field already carries — the thinking text, a tool call's name or parsed arguments. Rebuild the wire item from the universal fields instead.
- `tool_call_id` is not optional: always capture the provider's call id and replay it. Where the wire format carries both an item id and a call id, the call id is the one that correlates a result to its call.
- **Follow the reference client; do not redesign.** `openai_official/` is the shape for Responses-style protocols, `openai_chat/` for Chat Completions: same method order, same control flow, same names. A new client should read as a diff against its reference, because that is how it will be reviewed.
- **Keep it readable top to bottom.** A reader should follow one request or response straight through the file without jumping between definitions, so inlining is the default: read the SDK's attributes directly (`model_output.delta`, `model_output.item.call_id`) and keep field access, usage arithmetic, and error text where they are used. Extract a helper only for a genuinely large, self-contained block — the kind that would bury the main flow if inlined, such as fetching and decoding an image — never for a few lines. Mirror the reference client's own private methods (`_convert_thinking_level_*`, `_convert_tool_choice`) instead of inventing a layer beside them; a shim that accepts both dicts and SDK objects is never one of them, because the events are typed with the SDK's own types.
- **Clients yield deltas only; the base class closes the items.** `transform_model_output_to_uni_event` / `transformModelOutputToUniEvent` turns one wire event into one `UniEvent` whose `content_items` are the `.delta` items that event carries, in wire order, and never a `.done` item. `_streaming_response_internal` / `_streamingResponseInternal` builds the request, opens the stream, and yields one event per wire event: a plain loop, with no item bookkeeping, no accumulator, no argument parsing, no usage merging, and no synthesized stop. `usage_metadata` / `finish_reason` ride on `stop` events wherever the wire reports them — Anthropic `message_start` and `message_delta`, the Chat Completions finish and usage chunks, `response.completed` — merged field by field by the base; a client's `stop` event never ends the public stream. A wire event with nothing universal is the empty delta event: no items, null usage and finish reason. The base class hands every delta to `StreamItems` (`stream_items.py` / `streamItems.ts`), which sends it out as it arrives and closes each item with its `.done` item when the next item begins or the client's stream ends; the base then emits the one stop event or raises `EmptyResponseError`. Events that break the protocol raise `StreamProtocolError` in every mode, and the shared e2e tests check every client's stream with `assert_stream_grammar` / `assertStreamGrammar`.
- **The deltas of one item are contiguous and share one `fidelity.item_id`.** Model output is serial, so one item streams at a time and the provider's end-of-item events (`content_block_stop`, `response.output_item.done`, `step.stop`) are listed as no-ops: a gateway that closes its items late or out of order changes nothing. Pass the provider's own id, stringified, as `fidelity.item_id`: the Anthropic block `index`, the Responses event `item_id` or `item.id or item.call_id` (`None` / `undefined` where a gateway sends none), the Interactions step `index`, the Chat Completions wire field (`reasoning_content`, `reasoning`, `content`, `tool_calls`), the generateContent part kind (`function_call`, `thought`, `inline_thinking`, `inline_data`, `text`); embedding vectors carry none. `StreamItems` strips it, so it never reaches consumers, traces or histories.
- **`StreamItems` decides where an item ends; clients never do.** A delta belongs to the next item when it carries another `item_id`, is of another kind (an Interactions thought step going text, image, text is three items under one index), or begins an item by itself: a `tool_call.delta` carrying a name (every provider sends it once, on the call's first delta, so Chat Completions calls need no ids of their own), an image (`inline_thinking`, or `inline_data` with an `image/*` MIME type, while audio streams in chunks of one item), an embedding vector. Otherwise it continues the item streaming now: a delta without an id does, and so do a call's arguments whatever id a gateway puts on them. Fidelity sent alone under the item's id is that item's, whatever kind carries it (an Interactions `thought_signature` after an image thought). The per-kind table in that file — the growing field, the header fields of the first delta, how the chunks join — is the only per-kind code in the stream: the done item is the item's first delta with the growing field replaced by the join of every delta's (tool call arguments parsed) plus the item's fidelity.
- **Fidelity goes out once, when it is complete.** Attach it to the delta at which the client knows it whole: Anthropic's signature on its `signature_delta`, as a `thinking.delta` with empty `thinking`; the Responses reasoning `channel` / `encrypted_content` on an empty `thinking.delta` yielded at `response.output_item.done`, the last delta of that item; GPT's `phase` on an empty `text.delta` at `response.output_item.added`. `StreamItems` copies it onto the `.done` item. An identical fidelity repeated on later deltas of the same item goes out once (Chat Completions tags every reasoning delta with `reasoning_field`); a different one is a `StreamProtocolError`.
- **Stream on deltas; never re-read the completed item.** A tool call opens with a `tool_call.delta` carrying the name and call id on the item-added event and continues with argument fragments; the completion event yields nothing but the fidelity unknown until then. Never read content back from a completed item or cross-check it against what the deltas produced; `response.function_call_arguments.done` returns the empty delta event. Leave provider error events (`response.failed`, `response.error`, `error`) to the unknown-event guard rather than translating them into MMSP errors, except on Gemini Interactions: neither of its SDKs raises on the SSE `error` event that arrives inside an open stream, so the guard would drop the provider's failure and the stream would end as one without usage, and `gemini_official` raises on an `error` event carrying an error object instead, with the provider's code and message. `minimax_official` is the deliberate exception: it ignores the argument deltas and reads each call from `response.output_item.done`, yielding one `tool_call.delta` with the name, call id, and whole arguments. A client streams a call on deltas or delivers the completed item, never both, so the fragments and the complete call can never disagree.
- **The message transform switches on `.done` types.** `transform_uni_message_to_model_input` matches `text.done`, `thinking.done`, `tool_call.done`, `tool_result.done`, and the rest; a message never carries a `.delta` item, and legacy item types are converted before a client sees the messages.
- **The message transform keeps the order of the content items.** Whatever a turn produced — thinking, then text, then a tool call — has to leave the transform in that order. Where a protocol makes an item its own entry (a Responses `reasoning` / `function_call`, say) and the message text is collected separately, flush the collected text before appending the entry; a message appended after the items it preceded is what DeepSeek answers with "No tool output found for tool call". Anthropic Messages and Gemini keep one ordered block list per message, so appending in item order is enough; Chat Completions splits content and `tool_calls` into fields of one message and carries no interleaving at all.
- `UniConfig` keys rarely map one-to-one onto provider config keys. **Stop and ask**: list every non-obvious mapping and confirm it with the user before coding. Never decide silently.
- Every `ThinkingLevel` must stay usable on every client — never raise for a thinking level. Map each level to the closest level the model supports and degrade silently when a level has no exact equivalent (e.g. `gemini_official` maps `NONE` to `MINIMAL`, or to `low` on the models that reject `minimal`; `moonshot_official` maps `NONE` to `low` because K3 cannot disable reasoning).
- `temperature` and `tool_choice` (and other unsupported parameter values, e.g. `prompt_caching`) may reject with an exception, but must raise the MMSP-specific `UnsupportedParameterError` from `errors.py` / `errors.ts`, never a bare `ValueError`/`Error`. Keep the message wording consistent with existing clients (containing "not support").
- Implement Python and TypeScript together with identical behavior.

## Stage 4 — Verify

- Register the model in the env-gated `AVAILABLE_MODELS` lists of both test files with correct capability flags. Do not add model-specific test functions or files.
- That `AVAILABLE_MODELS` entry is the **only** test change a new model is entitled to. `src_py/tests/test_client.py` and `src_ts/tests/client.test.ts` are shared contracts every client must already satisfy: never rewrite their bodies, assertions, prompts, or helpers to accommodate one model, and never branch inside them on a model name. A failing shared test means the client is wrong until proven otherwise. **Stop and ask** for explicit approval before any broader test edit, and get it per change — approval for one edit is not approval for the next.
- `AVAILABLE_MODELS` keeps only the newest version of each model family per provider block (e.g. gemini-3.6-flash, not gemini-3.5-flash or 3.5-flash-lite as well). When a newer generation lands, replace the older entry — the old client folder stays supported and routed (see Stage 3) but is no longer e2e-tested.
- Static checks: `make lint` in `src_py/`; `npm run lint` and `npm run build` in `src_ts/`.
- Run only the new model's e2e tests; the full suites are slow and spend real API quota:
  - `cd src_py && uv run pytest -vvv tests/test_client.py -k "<model-name>"`
  - `cd src_ts && npm run test -- -t "<model-name>"`
- Leave unrelated tests to CI.

## Supported-model registry

- `src_py/mmsp/registry.py` / `src_ts/src/registry.ts` list the supported models as entries of (model, base_url, client) plus input/output modalities, context window, and USD-stored pricing keyed by MMSP's usage buckets. Keep both languages identical; the registry unit test constructs every entry through `AutoLLMClient`.
- For OpenRouter-hosted entries, pull authoritative data from the live models API `GET https://openrouter.ai/api/v1/models` (docs: https://openrouter.ai/docs/api/api-reference/models/list-all-models-and-their-properties): `pricing.prompt`/`completion` are USD per token (multiply by 1e6), plus `context_length` and `architecture.input_modalities`/`output_modalities`. The API lists chat models only — embedding models are absent and must be checked via their model pages.
- SiliconFlow publishes no pricing API; declare official CNY list prices with the `cny()` initializer (converted to USD storage at 7 CNY/USD).

## Record and ship

- Unreleased changes all land in `changelog/unreleased/`, named for its state rather than a number because the version is not decided until release. Never create a numbered folder for unshipped work and never invent the next version number; release preparation renames `unreleased/` to the decided version.
- Write `changelog/unreleased/YYYY-MM-DD-<slug>.md` in the format `changelog/README.md` specifies: the metadata block (`Date`, `Type`, `Scope`, `PR`, `Issue`, `Breaking`) directly under the title, then `## What changed` recording what the change did, plus the factual detail it introduced (config mappings, registry metadata, protocol differences) and `## Compatibility` when it breaks something.
- The entry records what was done, never the reasoning behind it and never the state of the codebase. `## Why`, `## Problem`, `## Decision`, `## Alternatives considered`, `## Verification`, `## Risks` do not belong on disk, and neither do claims like "`X` is not exported from `Y`": they read as fact, go stale as the code moves, and every later reader pays to re-check them.
- The reasoning is still required — it goes where it stays tied to its moment. Report it in the conversation as the work happens (what the probes returned, which alternatives you weighed and why the others lost, what the verification actually covered, what you are unsure of), and write it into the PR description. Anyone who needs it later pulls the PR description, `git log`, or `git blame`.
- Link the PR and any issue the change closes as full URLs (`https://github.com/Prism-Shadow/model-message-stream-protocol/pull/N`), in the metadata block and in the release-README line. A bare `#N` is not a link in a Markdown file. The PR number only exists once the PR is open, so open it first, then add both links in a follow-up commit on the same branch.
- Write the Chinese counterpart `changelog/<version>/YYYY-MM-DD-<slug>.zh.md` in the same PR, mirroring the English file section for section. The metadata block stays English verbatim (only the `Breaking` reason is prose to translate), as do code identifiers, model ids, and links; `changelog/README.md` lists the standard heading renderings. An entry without its counterpart is unfinished.
- Add one line at the top of that version's `changelog/<version>/README.md` and the matching line in `README.zh.md`, whose `[详情]` link points at the `.zh.md` entry; the root `CHANGELOG.md` and `CHANGELOG.zh.md` keep one line per release, added at release preparation.
- Commit on a feature branch and open a PR with `gh pr create --base dev`; direct pushes to `dev` are rejected.

## UI work — the playground, the tracer and the site

The three pages share one look, and every change to them goes through two references before it ships:

- `kill-ai-slop/GUIDE.md`, the field guide to the machine-default tics of generated interfaces, with its scanner: `node .agents/skills/mmsp-dev/kill-ai-slop/scripts/scan.mjs <dir>`. Follow its order — scan, triage each hit as slop or intended, report, then fix — and read `references/taxonomy.md` and `references/fixes.md` for what each tell is and what replaces it. The playground and tracer pages live inside Python and TypeScript strings, so scan an extracted copy of the HTML.
- https://www.beautifului.dev/, the reference for AI-native components: the loading line with a shimmer and the elapsed time, the collapsible "Thought for N s" trace, tool-call chips, the composer with a round send button, segmented controls with a gliding thumb.

The system they share:

- Neutral tokens (`--bg`, `--surface`, `--raised`, `--text`, `--muted`, `--subtle`, `--ring`) with one accent; color carries meaning only (a stop reason, an item's kind). Light and dark follow the system through `prefers-color-scheme` and a `data-theme` override; the playground and the tracer share the `mmsp.playground.theme` key, the site uses `mmsp-site.theme`.
- Inter for the interface, JetBrains Mono only for ids, JSON, paths of data and token counts. Depth from 1px rings, not large shadows. Motion 150–250 ms on `cubic-bezier(0.23, 1, 0.32, 1)`, only where something changes, and off under `prefers-reduced-motion`.
- One mark everywhere: the four-tile MMSP logo of `site/src/components/Logo.astro` (two `#477dfb` tiles and two dark ones, white letters), also the favicon of all three pages. The site's brand scale in `site/src/styles/global.css` is built around `#477dfb`, a pure blue at the hue of fennel flower `#7aa2f7`, as `brand-500`: images and the mark use `#477dfb`, text on white uses `brand-600` or darker, and text in the dark theme uses `brand-400`, which is `#7aa2f7` itself. The language and theme controls of the top bar are buttons that cycle on click (the other language; system, light, dark), not menus. The home page fits one desktop window, footer included: the player zooms to at most 85%, then its two stream panes are capped and follow their newest line. The README and social images are rendered from `site/artwork/` with `render.sh`. Before committing an image, shrink it: PNGs to at most 1760 px wide (twice the README column) and a 256-colour palette (`imagequant`, then `pyoxipng`), GIFs with `gifsicle -O3 --lossy=15`, dropping every other motion frame first. The README images together stay under 1 MB. Each tile of the mark is its own shape (the dark ones reach half a unit under the blue ones at the seams): one dark square under the blue tiles shows as a grey rim on white. The logo files for others to use are `.github/images/mmsp-logo.svg` and `mmsp-logo-dark.svg` (outlined letters) with 512 px PNGs of each, built by `site/artwork/logo.py <NotoSans-Bold.ttf> .github/images` with the PNGs rendered from the SVGs in Chrome. Every image has one copy in the repository: the site serves `.github/images/social-preview.png` through `site/src/pages/social-preview.png.ts` rather than a second file in `site/public/`.

What the owner has asked for, and keeps asking for:

- As few words as possible; logos and icons over sentences. The site home page is modeled on https://penguin.ooo/: the mark, the fixed slogan with its turning verb, the second line, two buttons, the vendor logos, and the recorded streams beside them, visible without scrolling. The top bar ends with language, theme and GitHub.
- A list is carried by alignment, spacing and hierarchy: no tinted boxes, no colored left bars, no pills for words that are not a status. Roles read as uppercase words.
- Side panels float and take no width, so a page's column sits in the same place whatever else is open. Navigation in the tracer reads like a file explorer: back, forward and up, then the address.

How the pages are built and checked:

- The playground page is one HTML document embedded as `CHAT_TEMPLATE` in both servers. Python serves it through Jinja, so it may hold no `{{`, `{%` or `{#`, and every backslash is doubled; TypeScript holds it in a template literal, so backticks and `${` are escaped too. Edit it once and regenerate both embeddings; keep the element ids and function names the page tests assert.
- The tracer shares `_TRACER_HEAD`, `_TRACER_SCRIPT` and `_ICONS` (`TRACER_HEAD`, `TRACER_SCRIPT`, `ICONS`) and a `_page` shell between `tracer.py` (Jinja page bodies) and `tracer.ts` (the same markup built in code). A tracer test asserts a trace page never contains `0.6`, its sign of a leaked sixth embedding value, so no CSS number or SVG path there may contain it.
- CI runs the model tests (`jest.yml`, `pytest.yml`) only for changes outside `site/`; a site-only change runs the site build alone.
- Verify in headless Chrome against both servers (and `npm run build` plus `astro preview` for the site): light and dark, desktop and a 390 px phone, no console errors, no horizontal scroll. A passing scan is not a better page; look at the screenshots.
- Scanner hits accepted on purpose: the shimmer on loading text, the round send and remove buttons, Lucide-derived icons, Inter, mono for data, and the owner's slogan as a sentence-long headline.