SDK foundation: stable schema, compatibility policy, and transport

[SarthakWade]

Problem

The npm package installs and launches Headless but is not a client SDK. Internal Swift and Rust protocol code does not provide a stable contract for products embedding Headless. Handwritten SDKs would drift from CLI validation and response types.

Proposed contract

Define one machine-readable command and response schema from the existing protocol validators. Generated or schema-validated clients should provide lifecycle management, sessions, typed commands and errors, capability negotiation, timeouts, cancellation, and compatibility checks.

SDKs should launch or connect through the existing local CLI, stdio, or private Unix-socket architecture. They must not introduce TCP, remote control, arbitrary JavaScript, or a second independently evolving protocol.

Security requirements

Page-derived data remains marked untrusted. Unknown fields fail closed. Sensitive diagnostics retain both gates. Credential APIs accept aliases or challenge references, never raw password fields. Transport ownership and socket permissions remain host enforced.

Acceptance criteria

• An architecture decision defines schema ownership, generation strategy, supported transports, and semantic-version policy.
• Compatibility behavior is specified for older client, older host, missing capability, and protocol mismatch.
• Golden fixtures verify parity among CLI parsing, protocol validation, MCP, and generated types.
• Cancellation and timeout behavior cannot leave orphaned hosts or half-completed state.
• Release, deprecation, support-window, provenance, and security-reporting policies are documented.

[yashranaway]

Do not start until #169 and #170 merge. Those add protocol commands the schema would have to describe.

Keep the existing local transport. No TCP. Generated from the Swift validators, not a second handwritten protocol. Credential APIs if they exist later are aliases and challenge IDs only. #164 and #165 stay blocked on this.