Skip to content

feat(sdk): establish the canonical local protocol contract - #180

Merged
yashranaway merged 5 commits into
mainfrom
feat/sdk-foundation-163
Sep 13, 2026
Merged

feat(sdk): establish the canonical local protocol contract#180
yashranaway merged 5 commits into
mainfrom
feat/sdk-foundation-163

Conversation

@SarthakWade

@SarthakWade SarthakWade commented Sep 12, 2026

Copy link
Copy Markdown
Collaborator

What this changes

Adds a deterministic Swift-owned SDK contract exposed by headless schema, with typed command parameters, result metadata, command scope, transport timeout policy, local lifecycle errors, trust markings, compatibility policy, support policy, and checked-in golden schema and conformance fixtures.

Adds supervised host ownership for SDK-launched processes. The canonical default is platform-neutral headless start --supervised; macOS presentation is included only when callers explicitly request foreground or background behavior.

Closes #163

Security and lifecycle

  • Uses only the existing private same-user Unix socket.
  • Adds no TCP listener, debug port, arbitrary JavaScript, remote control, or direct credential values.
  • Keeps page-derived data marked untrusted and sensitive diagnostics double-gated.
  • Rejects unknown request fields and unsupported capabilities.
  • Refuses existing shared hosts during supervised launch and grants ownership only after startup and socket PIDs match.
  • Stops and reaps only the launcher and host owned by the SDK.
  • Preserves the platform default when presentation is omitted, allowing Linux launch without a macOS-only option.

Verification

  • pnpm test: 65/65 protocol tests, secure terminal tests, and MCP integration
  • pnpm test:runtime
  • pnpm test:npm
  • Web lint and production build
  • macOS build and protocol suite
  • Linux Docker E2E
  • macOS WKWebView E2E
  • Linux amd64 and arm64 release artifacts
  • macOS and multi-platform container release artifacts

Stack

This is the base of the SDK stack. #181 depends on this PR, and #182 depends on #181.

@SarthakWade SarthakWade added the macos-e2e Run the macOS WKWebView E2E suite label Sep 12, 2026
@SarthakWade
SarthakWade added this pull request to stack #183 September 12, 2026 21:31

@yashranaway yashranaway left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Swift-owned schema, golden fixtures, and supervised start path match ADR 28 and the host hard rules.

headless schema stays a local CLI command. start --supervised refuses an already-running host, grants ownership only when the ping PID matches the child, and shuts the host down when the owner pipe closes. Transport is still the same-user Unix socket. Auth parameters are challenge/account only. Unknown request fields stay rejected.

Required CI is green, including Linux E2E and macOS E2E.

@yashranaway
yashranaway merged commit 2bf77e3 into main Sep 13, 2026
16 checks passed
@yashranaway
yashranaway deleted the feat/sdk-foundation-163 branch September 13, 2026 04:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

macos-e2e Run the macOS WKWebView E2E suite

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SDK foundation: stable schema, compatibility policy, and transport

2 participants