Repository navigation
feat(host): startAgentDevice() for embedder-owned daemons #3757
Copy link
Copy link
Open
Labels
enhancementNew feature or requestNew feature or requestin-progressWork is actively in progressWork is actively in progressready-for-agent
Description
Part of #3747. Prerequisites have merged: #3806 (recorded ownership safety) and #3797 (authenticated, instance-fenced hosted shutdown). Implementation: #3843.
Purpose
Let a driver process own an agent-device runtime in-process and pass plugin objects it imports as ordinary dependencies. Other processes may attach to that exact instance.
import { startAgentDevice } from 'agent-device';
import testmu from '@agent-device/testmu';
const host = await startAgentDevice({ stateDir, host: optionalHostEnvironment, plugins: [testmu({ credentials })] });
host.client; // AgentDeviceClient
host.clientConfig; // serializable AgentDeviceClientConfig: attach-only, pinned to this instance
const report = await host.close(); // the runtime's ShutdownReportContract
- Entry:
startAgentDeviceand its two public types (StartAgentDeviceOptions,AgentDeviceHost) come from the mainagent-deviceentry. There is noagent-device/hostsubpath. The function loads the daemon runtime lazily, so a plainimport 'agent-device'costs nothing extra; ADR 0027 keeps the eager closure unchanged. - Runtime: it reuses the daemon runtime and serves the existing authenticated protocol on loopback. Built-in providers come first, then the supplied plugins, through the existing registry. The registry's validator reports malformed or incompatible plugins in the published inventory. The plugin store is not read. Automatic idle reap is off. Registration records
ownership: 'embedded'. A refused registration propagatesdaemon_registration_refused. - Host environment:
hostdefaults to one captured copy of the process env and cwd. The runtime never changes the process env or cwd, installs process handlers, or exits the process. - Attach: a client created from
clientConfiggoes through the one normal attach flow: it observes the daemon, requires areusecompatibility decision, then checks the pin (token, PID, start time from the runtime's published identity) as a predicate. A missing, unreadable or replaced instance fails withdaemon-binding-mismatch. A version or code-origin mismatch fails withdaemon-incompatible. It never starts, replaces or redirects a daemon. - Close:
close()is idempotent and returns the runtime's existing shutdown report. Runtime startup owns rollback. The CLI never signals or replaces an embedded runtime (fix(daemon): preserve recorded ownership through stop and cleanup #3806); an externaldaemon stopuses the authenticated hosted shutdown (fix(daemon): finalize every host-owned close through registration #3797).
Dropped from the earlier contract
These were dropped in #3843 to keep the design minimal. The previous body is in the issue edit history.
- The
agent-device/hostsubpath: one entry,agent-device, and a lazy load. - The separate bound-attach path and the token override: one attach flow with the pin as a predicate.
- The
logoption andLogEntry: runtime console output is silent; artifact diagnostics remain. Symbol.asyncDispose: useclose().host.pluginsand the inventory copy:daemon.json/daemon statusown the inventory.- Extra root re-exports (
HostClientConfig,HostEnvironment,ShutdownReport):AgentDeviceClientConfigalready describes the config. - The host-specific reasons
state-dir-in-use,state-dir-ownership-unproven,state_dir_requiredandinvalid_embedder_plugin, plus the separate embedder plugin check: they duplicated existing registration and registry reasons.
Done when
- feat(sdk): start an embedded runtime from the main entry #3843 merges with lifecycle tests and a live run of the built package (
import { startAgentDevice } from 'agent-device', list devices, snapshot, close). - ADR 0034 states the simplified ownership rule.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or requestin-progressWork is actively in progressWork is actively in progressready-for-agent
Activity
thymikee commentedon Oct 19, 2026
Decision: publication layers: The maintainer approved three functional PRs for this work. This supersedes the body’s “At most two PRs” note.
agent-device/hostentry and binding in the later feat(host): startAgentDevice() for embedder-owned daemons #3757 PR.The combined first two layers contain 4,186 gross lines. Each layer fits the repository’s 2,500-line limit. Required ownership and lifecycle tests remain. One registration owner and one shutdown file replace the request ledger and release facade. The split does not change the host API contract or the 0.21 compatibility rule.
thymikee commentedon Oct 19, 2026
Current state: 2026-10-19.
Both approved prerequisite layers have merged: #3806 at
4645ddd75fand #3797 atb5f47e7542. They add recorded ownership safety and authenticated/direct close completion. The dead-owner managed-startup regression is fixed. Final independent code and sentence reviews passed; the exact local receipts and review dispositions remain in the PRs.No PR remains open from this coordinator. The later public host entry and binding work remains in this issue. The accepted three-PR plan still applies. This coordinator thread is closing at the maintainer's request.