docs(schema): decompose tool call payload union

[somus]

Pull Request

Summary

• Decompose tool_call.payload from 32 full payload branches into allOf of tool discriminator, common fields, and truncation state.
• Keep validation closure with unevaluatedProperties: false so unknown top-level tool payload fields remain invalid.
• Add pinned json-schema-to-typescript@15.0.4 generation guard and TypeScript smoke contracts.

Related Issue

• None.

Public Impact

• No public contract change
• Spec or schema change
• Public package API change
• CLI behavior change
• Public URL or docs behavior change

Impact description:

• Release schema composition changes preserve validation semantics while avoiding generator-hostile exponential oneOf expansion.

Verification

• mise run check:typescript-generation passed. Generation completed in ~178ms locally.
• mise run check:schema passed.
• Old/new schema comparison: schema validity unchanged for 459 fixture records.
• Targeted schema samples passed for truncation, missing file_read.args.path, unknown tool payload field rejection, capability JSON values, and vendor metadata JSON values.
• mise run check passed.
• cmp -s schema/draft.json schema/v0.1.0.json passed.

Reviewer Notes

• PR is intentionally waiting for review. It should not be merged directly.
• TypeScript smoke checks allow schema validation to own unknown top-level payload field rejection; generated TS may still allow extras because of allOf composition.

---

[coderabbitai]

Warning

Review limit reached

@somus, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 16 minutes and 59 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 7dc719b2-70a1-42e2-889d-0efc90b31ed0

📥 Commits

Reviewing files that changed from the base of the PR and between 2202d30 and 55ebf63.

📒 Files selected for processing (4)

• mise.toml
• schema/draft.json
• schema/v0.1.0.json
• scripts/check-typescript-generation.mjs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch somus/schema-ts-generator-check

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[stage-review]

Ready to review this PR? Stage has broken it down into 5 individual chapters for you:

	Title
1	Add TypeScript generation and smoke test dependencies
2	Decompose tool call payload union in draft schema
3	Apply tool call decomposition to release schema
4	Implement TypeScript generation smoke checks
5	Wire TypeScript generation check into task runner

_{Chapters generated by Stage for commit 55ebf63 on Jun 13, 2026 11:12am UTC.}

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Schema as JSON Schema (draft/2020-12)
    participant Validator as AJV Validator
    participant Gen as json-schema-to-typescript
    participant TSC as TypeScript Compiler
    participant Tools as Tool Definitions ($defs)

    Note over Schema,Tools: CHANGED: tool_call.payload decomposed from oneOf of 32 branches to allOf composition

    Schema->>Schema: Define tool discriminator schema (tool const per tool kind)
    Schema->>Schema: Define common fields schema (usage, truncated, args_size, overflow_ref)
    Schema->>Schema: Define truncation state schemas (truncated: true vs false)
    Schema->>Tools: Reference tool-specific args $ref (toolCallFileReadArgs, etc.)

    Note over Schema: NEW: allOf combines discriminator + common fields + truncation state

    Schema->>Schema: Apply unevaluatedProperties: false at payload top level

    Validator->>Schema: Load schema
    Validator->>Schema: Validate tool_call payload against allOf composition

    alt Valid tool_call payload
        Validator->>Validator: Discriminator matches one tool const
        Validator->>Validator: Common fields present
        Validator->>Validator: Truncation state consistent (args_size required when truncated=true)
        Validator-->>Validator: Pass
    else Unknown top-level field (e.g., "future_field")
        Validator->>Schema: unevaluatedProperties: false rejects extra field
        Validator-->>Validator: Fail (validation error)
    end

    Note over Gen,TSC: NEW: Pinned json-schema-to-typescript@15.0.4 generation guard

    Gen->>Schema: Compile schema/v0.1.0.json to TypeScript types
    Gen-->>Gen: Generate AgentTrailV010 type with allOf composition (not oneOf expansion)

    TSC->>Gen: Run check-typescript-generation.mjs script
    Gen->>Gen: Fork child process to load json-schema-to-typescript
    Gen-->>TSC: Generated TypeScript source (~178ms)

    TSC->>TSC: Compile smoke contracts (validShellTruncated, invalidShellMissingArgsSize, etc.)
    alt Valid smoke contracts
        TSC-->>TSC: @ts-expect-error annotations pass for invalid cases
        TSC-->>TSC: Valid cases compile without error
    else Smoke contract failure
        TSC-->>TSC: Compilation error (test fails)
    end

    TSC->>Validator: Run assertSchemaRejectsUnknownToolPayloadField via AJV
    Validator->>Schema: Validate sample with unknown top-level field
    alt Schema rejects unknown field
        Validator-->>TSC: exit code 1 (expected)
        TSC-->>TSC: Pass
    else Schema allows unknown field
        Validator-->>TSC: exit code 0 (unexpected)
        TSC-->>TSC: Fail with error
    end

    Note over Schema,Tools: Validation semantics preserved (459 fixture records unchanged)

Loading

<sub>Shadow auto-approve: would require human review. Schema refactor replacing 32 oneOf branches with allOf composition alters the generated TypeScript types and validation behavior. Though tests pass, composition changes in a JSON schema can have subtle downstream effects on type generation and strictness that warrant human review.
Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>