Awesome Reviewers

Treat every field added to a shared interface (SDK types, request/response payloads, hook options, headers) as a long-term API commitment, and design it deliberately:

• Prefer a descriptive string-literal union over a boolean when the field models more than a true/false fact. Booleans often hide states that aren’t really the negation of each other, and they tend to proliferate into combinations that are invalid and hard to test. Favor entry?: "run" | "continue" over isContinuation?: boolean, and resumed?: "resumed" | "started" over resumed?: boolean — the enum documents the “false” case positively instead of through negation.
• Keep contracts symmetric: if a field can be set on input, make sure every code path that produces the corresponding output also forwards it. A field that goes in but never comes back out (e.g. displayPrompt accepted but dropped by an event projector) is a trap for the next integrator even if no current caller depends on it.
• Never silently repurpose an existing field or header’s meaning. If X-Task-ID used to carry the task id and now needs to carry a ulid, rename it (X-Task-ULID) or add a new field/header instead of changing what the existing name means underneath callers.
• Don’t duplicate a fact that’s already derivable elsewhere in the contract (e.g. a providerConfigured flag duplicating a provider catalog’s own configured/apiKeyOptional metadata). Expose the single source of truth and let consumers read from it, avoiding extra synchronization burden.
• Before shipping a new option/flag on a public surface, check whether it can be collapsed into existing, always-on behavior; it’s far cheaper to simplify the surface before it’s published than after.

Applying these checks during review prevents ambiguous, inconsistent, or redundant contracts from leaking into the public API surface.

This site is open source. Improve this page.