Developer Preview 0.3.0.dev2: This page documents the unchanged SDK 0.2.0 base contract. For the unified adapter, optional simulated motion and current installation commands, use the current quickstart and bundled docs. No real hardware or production integration is enabled.

Public contract 1.0

SDK 0.2.0 preserves wire version 1.0. Manifest.parse, negotiate_version, validate_request, validate_response, parse_wire, CapabilityInterface, CertificationTestSuite (legacy local-only name) and PrecertificationSuite are the public entrypoints. Runtime package: aicontinue_capabilities. Schema: aicontinue_capabilities/schemas.json.

Three adapter kinds

• software: local_app and/or manufacturer_cloud route, never a device route. An installed manufacturer app is an explicit dependency if used.
• device: device routes only; an explicitly described direct device protocol is required for any future real target. No manufacturer app is implied.
• hybrid: at least one device route and one local_app or manufacturer_cloud route. Each recipient/capability/transport is authorized separately. Local permission never grants cloud permission.

All declared routes carry trust: untrusted; all manifests require synthetic_only: true. These are declarations, not authenticated identity, attestation, credentials or security proof. Manufacturer/product/runtime refs are bounded labels, never URLs or private owner identifiers. Every declared capability must be represented by a route, and a route cannot add undeclared capabilities. Sensors requires declared sensor_types. A host chooses the route; adapters must reject undeclared routes and must not silently fall back.

Envelopes

Request fields are exactly version, invocation_ref, capability, operation, payload, route_id. Response fields are exactly version, invocation_ref, status, payload, error. invocation_ref must match. Both use version 1.0. Maximum canonical wire size is 32,768 UTF-8 bytes. Unknown fields and operations are rejected. parse_wire rejects duplicate JSON keys, invalid UTF-8, invalid JSON, non-finite numbers and over-limit input. Apply it at the transport boundary before schema validation. Do not accept raw parser defaults that silently overwrite duplicate keys.

For success, status=ok and error=none; payload matches the selected capability.operation schema. For failure, status=error, payload={} and error is one of unsupported, unavailable, cancelled, timeout, invalid_request. No stack traces, driver messages, paths, keys or extra metadata may cross the wire.

Media bounds

MicrophoneAudioInput.sample returns exactly 80 samples (160 bytes) per frames unit, 1–4 units, pcm16 mono at 16000, 24000 or 48000 Hz. The sample rate must equal the request. A unit is a fixed sample block, not a millisecond promise; duration = 80 × frames / sample_rate seconds. The synthetic reference example emits zero-valued PCM samples. Before real audio interoperability, document agreed PCM byte order in the hardware acceptance packet; the existing wire identifier does not express endianness and real conversion is unverified.

SpeakerAudioOutput.play accepts nonempty even-length PCM bytes up to 8192, base64-encoded, same rate set, channels=1, codec=pcm16. A success is a simulated acceptance, not proof of audible playback. Camera.snapshot is gray8, width/height 1–64, decoded byte count exactly width×height and returned dimensions/format equal request. Images are synthetic. No streaming camera or continuous audio transport is added.

Display.present is bounded text (1–1024 characters), never executable content. UserControls.poll returns a bounded event enum; it grants no action authority. Sensors.read supports only temperature_celsius, battery_percent, acceleration_mps2; values are bounded -100..100, battery 0..100, scalar or three-axis shape as appropriate. Recording start/stop/status is a state acknowledgement only; retained_bytes must be zero. Recording start retention_seconds is 1–300 but real storage/retention is not implemented. BasicDeviceStatus and ConnectivityEvents are declarative status/poll operations, not remote management or arbitrary commands.

Lifecycles

Timeout/cancel/disconnect after dispatch may leave remote completion unknown. Never infer success, automatically replay or restore late results. A reconnect needs a fresh connection epoch and new authorized operation refs. A real integration must renegotiate the audio format or reconnect when the audio sample rate changes. The public adapter has no Core or session authority. Host-specific lifecycle/permission tests remain private and production integration is pending.

Schemas document exact shapes; a general JSON Schema validator alone does not perform cross-message correlations, invocation binding, manifest route checks or authorization. Python runtime checks are required. No generic shell, URL fetch, filesystem operation, extensible RPC, remote management, motion, location, robotics or vehicle capability is introduced.