contribute-api

Contribute A New API Surface

Companion Guidance

Use karpathy-guidelines alongside this skill for implementation or review work. Keep changes scoped, surface assumptions, and define focused validation before editing.

Use this skill when contributing a public API addition or behavior change to the runtime or bindings.

Default Guidance

• Start from the shared Rust core behavior first
• Decide whether the CLI, PyO3 binding, Python SDK, type stubs, schemas, or the Python and TypeScript adapter-contract bindings must expose the new surface
• Keep every affected public surface in parity
• RunRequest.relay_session_root is forwarded as the typed AgentRunRequest.relay_session_root field. Keep Rust, Python, TypeScript, and schema representations in parity. Context keys do not control Relay propagation; preserve the adapter fallback for unusable UUIDs.
• Update docs and examples in the same branch

Minimum Acceptance

• Public behavior is clearly described
• Every affected public surface is covered
• The validation matrix matches the changed surfaces
• PR notes explain the user-facing change

References

• validate-change
• review-doc-style
• docs/python-sdk-contract.md
• schemas/SCHEMA.md
• justfile