feat(v2): check the extensible-union values you build

[benbrandt]

Found while adding experimental v2 support to claude-agent-acp.

Problem

Every extensible union ends in a catch-all variant whose tag is any string, e.g. { type: string; [key: string]: unknown }. Receivers need that, because they must accept future ACP variants. But it also means a value you build type-checks with a malformed known variant, at any depth, because it falls through to the catch-all:

// Both compiled before this change:
const update: SessionUpdate = { sessionUpdate: "usage_update", used: 1 }; // missing `size`
const chunk: SessionUpdate = {
  sessionUpdate: "agent_message_chunk", messageId: "m",
  content: { type: "text", txt: "hi" },                                  // `txt` is not a field
};

Change

In the v2 types, each catch-all is split in two:

• custom variants, whose tag starts with _, the protocol's prefix for implementation-specific values. Known tags never start with _.
• UnknownVariant<…>, with any string tag, branded with a symbol that only the types of received values carry. A value you build can't be one.

So:

• Values you build are checked against the known variants, nested ones included, with nothing to import or annotate. Both examples above are now compile errors.
• Custom variants still work, under a _ tag, with any payload: { sessionUpdate: "_acme/progress", percent: 40 }. An unknown tag without _, which the spec reserves for future versions, is rejected.
• Received values pass on unchanged, unknown variants included. That matters for every v2 agent, which must echo a prompt into a user_message: content: params.prompt compiles as-is. The same goes for relaying, or spreading a received value into a new message.

The brand exists only in the types:

• The zod validators are still generated from the unchanged schema, so runtime validation doesn't change.
• A small received() helper types parsed values at the parse boundary, with the reasoning documented once.
• Narrowing works as before: a member with a wide string tag blocks it in either form, which I checked. So the guards stay, and their custom-variant types now match the split.

v1 is unchanged.

How

The generator produces the v2 types from a copy of the schema whose catch-all tags are pinned to a marker. It then replaces each object type holding the marker with (custom | UnknownVariant<unknown>), using a small scanner that skips comments and strings, since the docs contain braces. A count check fails generation if the number of split members doesn't match the number marked.

This replaces the first version of this PR, which added opt-in Outgoing* aliases. Users had to discover them and import them, and they didn't help with nested values.

Testing

• New v2 tests:
  • a select option with an extra field, a usage_update missing size, and a nested text block with a misnamed field are all rejected;
  • _ extensions are accepted, top-level, in a config option, and in a nested block;
  • non-_ unknown tags and extensions missing the shared fields are rejected;
  • the untagged titled multi-select variant still works;
  • end to end: an agent echoes a prompt containing a block this SDK doesn't know, and the client receives it unchanged.
• The rest of the SDK, its existing tests, and the dual-version example compile unchanged.
• npm run check: generate check, lint, format, spellcheck, build, 976 tests, TypeDoc.