design(local-capability): define external Adapter Protocol for participant-local capabilities

[madawei2699]

Status

FRESH-AGENT AUTHORING PROOF COMPLETE — PR #519 merged; next gate is local source-built Runtime registration against the real CUPS Adapter, then release and Room acceptance.

Related:

• Core direction — temporary capability access and collaboration fabric #51 — Core direction / temporary capability boundary
• experiment(runtime-capability): prove Room-scoped Runtime Host capability RPC #512 — Room-scoped Runtime Host capability RPC
• Lab fix(agent): patch Runtime dependency vulnerabilities #215 — participant-local / physical capability product proof
• Lab docs: activate browser-optional Agent Rooms #214 / chore: activate agent Runtime v0.5.15 #218 — completed App-owned semantic capability proof

Decision to freeze

Free4Chat Runtime should not become a hardware integration host.

Canonical boundary:

Room
  ↓
Free4Chat Core / Runtime
  ↓
Local Capability Adapter Protocol
  ↓
Adapter
  ↓
vendor API / Home Assistant / IPP / BLE / serial / USB / LAN / SDK / whatever

The key rule is:

Runtime knows capabilities, not integrations.

More explicitly:

Runtime owns capability transport, authority, bounds and lifecycle. Adapter owns integration, vendor protocol, local configuration and credentials.

A Xiaomi token, Home Assistant token, printer password, BLE pairing key, MQTT credential, serial configuration or vendor account must not become a Free4Chat Runtime credential/configuration type merely because an Adapter needs it.

Why this is needed

#512 proves a bounded semantic capability can be projected from a participant-local Runtime into a Room:

Human deterministic invocation
        ┐
        ├→ daemon-owned semantic controller → local fixture
Agent   ┘

The current fixture-specific HTTP adapter was intentionally useful for the proof. It must not become the long-term extension model.

Without a strict external Adapter boundary, normal product evolution would pull integrations into Runtime:

Runtime
├─ Xiaomi / MiOT
├─ Home Assistant
├─ Epson / IPP / CUPS
├─ BLE
├─ MQTT
├─ serial / USB
├─ vendor SDKs
└─ vendor-specific credential/config lifecycle

That is explicitly rejected.

Product model

Runtime responsibilities

Runtime may own only the generic machinery necessary to safely project local semantic capabilities into a Room:

• Adapter registration / deregistration;
• bounded descriptor validation;
• list / describe / observe / invoke dispatch;
• Room authorization;
• request correlation / timeout / cancellation;
• process/local-IPC lifecycle if Runtime supervises an Adapter;
• health / unavailable state;
• Room / Runtime teardown cleanup;
• protection against endpoint/config/credential leakage into Room/Harness surfaces.

Runtime does not understand the underlying device/service.

Adapter responsibilities

An Adapter owns everything integration-specific:

• device/service discovery;
• vendor protocol;
• vendor OAuth/login;
• vendor tokens / passwords / API keys;
• local endpoint / LAN address;
• BLE / serial / USB / IPP / MQTT / HTTP / SDK use;
• vendor-specific retries and connection behavior;
• conversion from messy local integration state into the bounded semantic capability contract.

Credentials stay in Adapter-owned/local-system storage, for example:

• macOS Keychain;
• Home Assistant's own credential/config store;
• Adapter-local config;
• environment variables;
• an already-authenticated vendor CLI/session;
• another local secret mechanism selected by that integration.

Free4Chat does not define a universal vendor credential schema or credential vault.

Agent role

Agents are first-class Adapter authors/operators.

A setup Agent may, subject to existing local Harness/operator approval policy:

inspect local environment
→ research an existing integration/protocol
→ search for an official/community Free4Chat-compatible Adapter
→ install/use that Adapter
OR
→ generate a small Adapter locally
→ configure vendor login locally
→ test describe/observe/invoke
→ ask Human to approve registration/publication

The Runtime must not require Free4Chat to know the vendor or device model.

An Agent-generated Adapter is allowed to solve an integration Free4Chat has never heard of.

Room messages themselves never grant the Agent new local filesystem/network/USB/secret authority.

Adapter sources are intentionally open

Free4Chat should define the protocol, not a closed integration catalogue.

A compatible Adapter may be:

• generated on demand by an Agent;
• maintained by the user;
• published by the Free4Chat project as a reference/curated Adapter;
• published by a device vendor;
• found in an open-source repository;
• provided by the community;
• a thin wrapper over an existing local system such as Home Assistant or CUPS.

No central Adapter marketplace/registry is required for this issue.

The Agent may discover compatible Adapters using ordinary local/web research and then validate them against the protocol.

Protocol surface

Keep the first external contract extremely small.

Conceptually:

list?       // optional if one process exposes several capabilities
describe
observe
invoke
health

The semantic Room-facing model remains bounded:

capabilityId
title
version
observe availability
closed typed actions
bounded result

Do not put integration concepts into the protocol:

• URL / HTTP path;
• MQTT topic;
• serial port;
• BLE characteristic;
• vendor token;
• Home Assistant entity internals;
• printer model;
• device driver type.

Transport

Prefer the simplest local process/IPC transport that allows an Agent to implement an Adapter in any common language.

Candidate V1:

Runtime
↕ stdio JSON messages / JSON-RPC-like request-response
Adapter process

This is a candidate, not a reason to invent a large SDK.

Evaluate stdio against a Unix-socket/local-IPC alternative and choose the smallest contract with:

• request correlation;
• bounded frames;
• timeout/cancellation;
• no network listener required;
• easy Python/Node/Go implementation;
• explicit process lifecycle;
• deterministic tests.

Avoid making generic loopback HTTP proxying the canonical Runtime abstraction.

Trust / approval split

Two separate approvals must remain distinguishable:

1. Local Adapter execution

Human/operator approves running/installing Adapter code

This is local-code authority governed by normal Harness/OS/operator policy.

2. Room capability publication/control

Human explicitly enables the Adapter's bounded capability for this Room

Running an Adapter does not automatically publish it to Rooms.

Publishing a capability does not authorize arbitrary Adapter code or local network access.

For Agent-generated temporary Adapters, prefer Room/session-bounded lifecycle where practical:

Agent generates Adapter
→ Human approves local execution
→ Runtime validates descriptor
→ Human approves Room projection
→ Room / registration ends
→ ephemeral Adapter can be stopped/removed

Do not require ephemeral lifecycle for every user-installed Adapter; long-lived local Adapter processes are also valid.

Secret boundary

Normal Runtime / Room / Harness-visible surfaces must never contain Adapter integration secrets.

Explicitly keep outside Free4Chat capability projection:

• vendor credentials;
• OAuth refresh/access tokens;
• local endpoint URLs/IP addresses unless independently required for local debugging;
• device pairing keys;
• Adapter internal config;
• arbitrary environment values;
• vendor request/response auth material.

Runtime may know how to launch/connect to an Adapter process, but should not parse, own or persist the Adapter's vendor credentials.

Avoid putting secret values in argv.

Official support policy

Free4Chat Core should provide:

1. the Adapter Protocol specification;
2. a tiny validator/test harness for Adapter authors/Agents;
3. Runtime registration/lifecycle support;
4. at most a small number of reference Adapters/examples when useful.

Reference Adapters must remain outside the Runtime core dependency graph.

A future Home Assistant or CUPS example may be valuable because it demonstrates broad reuse, but it is not part of defining this protocol.

Phase 0 / V1 proof

Phase 0 result: PR #516 merged at 520e3f379f0373b1ca3890b16f1e824f7e1a6259. The retained baseline is supervised stdio NDJSON, protocolVersion 1, list / describe / observe / invoke, an external Python reference Adapter, and a conformance validator. Production Runtime migration remains the next step.

Do not start with Xiaomi-specific code.

First prove the boundary by extracting/replacing the current fixture-specific Runtime integration with one external Adapter process implementing the protocol.

Suggested proof:

existing localhost fixture
        ↑
Agent/user-written external Adapter
        ↑
generic Adapter Protocol
        ↑
Runtime
        ↑
Room #512 capability RPC

Acceptance should prove that the Runtime does not change when the Adapter implementation is replaced.

Then Lab #215 can use the same protocol for one real device/service.

Acceptance

Protocol

• one small versioned external Adapter protocol is documented;
• a Python/Node/Go Adapter can implement it without Free4Chat SDK dependencies;
• descriptor / request / result frames are bounded and validated;
• Adapter process failure becomes bounded unavailable;
• unsupported actions fail explicitly;
• protocol contains no vendor/device transport concepts.

Runtime boundary

• Runtime no longer needs fixture/vendor-specific HTTP routes to project the proof capability;
• adding/replacing an Adapter requires no Room/Core protocol change;
• Runtime does not own vendor credentials/configuration;
• Runtime does not become a generic HTTP/TCP/reverse proxy;
• Adapter disappearance removes/unavailable capability cleanly.

Agent authoring

• a fresh Agent can inspect the protocol/examples and implement a disposable Adapter;
• Agent can test it locally with a small protocol validator;
• Adapter can be registered without adding vendor-specific Runtime code;
• local-code approval remains separate from Room capability authorization.

Reuse proof

After V1, Lab #215 should be able to choose any convenient real target — for example Home Assistant→Xiaomi light or IPP/CUPS→printer — by changing only the Adapter side.

Non-goals

• Xiaomi / MiOT integration in Runtime;
• Home Assistant client in Runtime;
• Epson / CUPS / IPP integration in Runtime;
• BLE/MQTT/serial/USB stacks in Runtime;
• vendor credential manager;
• universal secret vault;
• device driver catalogue;
• global Adapter registry;
• marketplace;
• package manager;
• automatic installation of untrusted Adapter code;
• arbitrary local network proxy;
• Generated Task App unrestricted LAN access;
• permanent device cloud;
• broad plugin SDK beyond the minimum protocol.

Design test

For every proposed Runtime addition ask:

Is this required to securely project a bounded local semantic capability into a Room, or is this integration logic that belongs in the Adapter?

If the latter, keep it outside Runtime.

[madawei2699]

Canonical boundary is now synchronized into Core #51, Lab roadmap #212, and Lab experiment #215.

Execution order:

1. Finish experiment(runtime-capability): prove Room-scoped Runtime Host capability RPC #512 release/official-binary acceptance.
2. design(local-capability): define external Adapter Protocol for participant-local capabilities #514 design/spike may proceed now, but do not mix its Runtime implementation into the experiment(runtime-capability): prove Room-scoped Runtime Host capability RPC #512 release.
3. V1 should extract the current fixture-specific integration behind one external Adapter Protocol and prove an Agent can implement/test a compatible Adapter without vendor-specific Runtime changes.
4. Only then should Lab fix(agent): patch Runtime dependency vulnerabilities #215 choose a real target such as Home Assistant→Xiaomi light or IPP/CUPS→printer.

The success criterion is not “Free4Chat supports Xiaomi/Epson.” It is:

A new integration can be found, installed, configured, or generated by an Agent/community author and brought into a Room without adding vendor code or vendor credentials to Runtime.

[madawei2699]

Phase 0 design/spike is ready in draft PR #516: #516

Transport: supervised child process over newline-delimited JSON stdio. Each envelope carries protocolVersion 1; operations are list, describe, observe, and invoke. No initialization or health method is needed; timeout kills/reaps the process, and EOF/crash/malformed/oversized/duplicate responses fail closed.

Bounds and shape: 65,536-byte frames; up to eight bounded descriptors using the existing Runtime Host semantic projection shape; 1,024-byte args; 4,096-byte results; one request in flight per process; 1.5-second reference deadline. Errors use a closed category set. Stdout is protocol-only and logs go to stderr.

Fixture audit: RuntimeCapabilityProjection, Room authorization/semantic dispatch, and generic bounds remain Runtime responsibilities. fixture_http.go (/state, /actions/set-led, color mapping, loopback HTTP) moves behind the protocol in a later migration. config.go/local-capability.json, daemon capability-configure/FixtureEndpoint, and CLI --fixture-endpoint are fixture-specific and should be removed after that migration. Generic semantic list/describe/observe/invoke CLI/controller surfaces remain. The Go fixture tests become obsolete after migration. No production migration is in this PR.

Evidence: an external standard-library Python Adapter uses an Adapter-owned config file to call the deterministic localhost fixture; its descriptor and protocol contain no endpoint and it imports no Free4Chat package. validate.py can check a supplied Adapter's list/describe/observe/invoke and unsupported-action response. Ran the reference validator; it passed malformed, oversized, duplicate, and missing-response failure probes plus valid invocation.

Unresolved before production V1: #513 currently limits a Runtime Host projection to one capability while this protocol allows up to eight; decide the generic ceiling. Decide daemon-owned versus resident-owned process registration. Keep the reference deadline bounded/configurable. Local Adapter execution approval and Room publication/control approval remain separate.

Recommendation: retain the protocol and spike from #516 as Phase 0, then implement the generic process-registration/lifecycle seam in a separate V1 change; do not add vendor integrations to Runtime.

[madawei2699]

Release sequencing gate: #515 has merged at 87077771658e2c575c7a15d2c30e9ec4a419a1f5. Keep #516 Draft until agent-v0.5.46 is tagged/published from that release baseline, because #516 adds experimental agent/** files and must not enter the v0.5.46 release tag.

[madawei2699]

Phase 0 is now complete: PR #516 merged as 520e3f379f0373b1ca3890b16f1e824f7e1a6259.

Next work is V1 production integration only:

• Runtime supervises an approved external Adapter process;
• stdio NDJSON protocol from [codex] design local capability Adapter protocol #516;
• reuse existing semantic capability projection and experiment(runtime-capability): prove Room-scoped Runtime Host capability RPC #512 Room RPC;
• move fixture-specific HTTP/configuration out of production Runtime;
• keep vendor credentials/configuration entirely Adapter-owned;
• no Xiaomi/Home Assistant/Epson code in Runtime.

The deferred #512 production Room acceptance remains separate and does not block this work.

[madawei2699]

Production V1 Adapter integration is ready for review in Draft PR #518: #518

Production boundary: the daemon launches one approved external executable directly (no shell) and speaks bounded protocolVersion 1 newline-delimited JSON over stdin/stdout. Runtime owns process registration/lifecycle, semantic descriptor/action validation, timeout and request correlation, one-capability projection, and refresh on availability changes. The Adapter owns endpoint/configuration, credentials, and all integration HTTP/device behavior. No vendor credential store, generic proxy, or device integration was added.

Removed fixture-specific Runtime code: deleted agent/internal/capability/fixture_http.go, its loopback endpoint persistence, daemon fixture configure/FixtureEndpoint IPC, and capability configure --fixture-endpoint. The generic semantic list / describe / observe / invoke interface remains. The deterministic HTTP fixture is called only by the external Python reference Adapter.

Lifecycle and safety: registration persists only executable plus bounded argv in private local config. The daemon supervises one long-lived Adapter, replaces/removes and reaps the old child, clears projection after child exit, and shuts it down with the daemon. Frames, args, results, stderr capture, and deadlines are bounded; stderr and unrelated ambient environment values are not exposed to the Room/Harness. Room/session-owned temporary Adapter expiry remains deferred; V1 registrations are daemon-owned and persistent.

Evidence: full Go tests, go vet, build/gofmt, Python reference validator, installer/bootstrap/cleanup scripts passed. Relevant App matrix passed (25 tests) and yarn type-check passed. Dogfood starts the deterministic fixture and registers adapter.py through the production daemon; Human semantic observe/invoke and Agent Room capability RPC route through the same Adapter process. The fixture records GET /state and POST /actions/set-led, proving those HTTP calls stay inside Python. Tests also cover replacement, crash-triggered projection removal, and daemon shutdown cleanup.

Remaining #514 acceptance: review/merge this Draft PR; exercise a fresh Agent authoring or selecting an Adapter with the reference validator; and use Lab #215 to choose a real local target and prove it needs only Adapter-side work. Multi-capability support and temporary Room/session-owned process expiry require later evidence. The deferred #512 production Room acceptance remains independent and is not included here. No new Runtime release was created.

[madawei2699]

V1 PR #518 final review passes. The Runtime/Adapter boundary is now implementation-complete enough to move to reuse evidence after merge.

Important credential rule for the next real-device proof: Adapter registration persists only executable + bounded argv. Treat argv strictly as non-secret launcher metadata. Vendor tokens/passwords/endpoints remain Adapter-owned (local config/Keychain/existing login state) and must not be passed through Runtime registration.

[madawei2699]

PR #518 merged as dd01a6dd97c09684d90e438493afccfe1a76dc33.

#514 now moves from implementation to reuse/authoring acceptance. Do not add more Runtime abstraction yet.

Next gate:

1. give a fresh coding Agent only the public design/spec + validator + ordinary local environment;
2. do not explain the internal Go implementation;
3. ask it to either find an existing compatible Adapter or write one for a new local target;
4. it must keep vendor credentials/config Adapter-owned;
5. Runtime source must remain unchanged;
6. validator + semantic list/describe/observe/invoke must pass.

Only after that should Lab #215 use a real household device/service.

[madawei2699]

Fresh-Agent authoring proof succeeded with PR #519.

Without changing Runtime/Core production code, a fresh Codex session used the public Adapter Protocol to implement a real read-only CUPS Adapter for an existing Epson queue. The Adapter validated and observed {"state":"idle","acceptingJobs":true}; queue/device connection details remained Adapter-local. A separately authorized CUPS smoke print also physically produced a page, confirming the local printer path itself works.

This satisfies the authoring/reuse design half of #514.

Remaining #514 gate is now narrow: publish a Runtime containing merged #518, register this exact Adapter with the official binary, then prove semantic list / describe / observe (and Room path if convenient) without Runtime changes.