Skip to content

Commit 22f4e58

Browse files
thymikeeclaude
andcommitted
docs(plugins): document the single cleanup owner and daemon.json states
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent de0d7ae commit 22f4e58

2 files changed

Lines changed: 10 additions & 0 deletions

File tree

‎docs/adr/0034-provider-plugin-registry.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ Status: accepted. Umbrella #3747; contract and registry #3755.
1616
- A plugin that fails to enumerate, load, validate or set up is recorded and skipped. The daemon
1717
starts with the rest. The inventory lists every plugin as `active` or `failed`, with a typed
1818
`error.reason`, and is published in `daemon.json` and by `agent-device daemon status`.
19+
- `registry.close()` is the single, idempotent cleanup owner. It shuts down each runtime, then calls
20+
its `dispose`, and returns an outcome per plugin and step. Runtimes are never wrapped.
21+
Composition is transactional: when a later step fails, it closes the registry before it throws.
22+
- The registry receives candidates. Composition chooses the sources.
23+
- `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`; only `absent`
24+
reads as a stopped daemon.
1925
- The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon.
2026
- v1 plugins (`agentDevicePlugin.apiVersion: 1`) without a `./agent-device` export are dispatched by
2127
their manifest before any code runs and load through an adapter until 0.22 removes them (#3759).

‎website/docs/docs/plugins.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ A failed install keeps the previous selection. A running daemon keeps the plugin
3434

3535
`source` is `builtin`, `store`, or `embedder`. A plugin that cannot register has `state: "failed"` and an `error` with `code`, `message`, and a `reason` such as `invalid_plugin`, `incompatible_plugin`, or `duplicate_provider`. The daemon starts without it and keeps every other provider. Fix or remove the package, then stop the daemon so the next command starts a new one.
3636

37+
When a daemon's `daemon.json` cannot be used, `daemon status` says so instead of reporting a stopped daemon: `unreadable` means the file exists but could not be read, and `invalid` means it was read but is not a daemon record. Only an absent file means `stopped`.
38+
39+
When the daemon stops, it closes every plugin once: each runtime shuts down, then its `dispose` runs. A step that fails is logged as `provider_plugin_cleanup_failed` with the provider and step, and the other plugins still close.
40+
3741
`plugins list --json` works without a daemon. It lists your installed plugins with their provider and whether their factory loads and validates; whether `setup` succeeds shows only in a running daemon's inventory. When a daemon is running for the same `--state-dir`, it also reports that daemon's inventory under `daemon`.
3842

3943
When two plugins claim the same provider, the first one wins: bundled providers, then installed plugins in package-name order, then plugins a JavaScript host passes itself. The others are `failed` with `duplicate_provider`. The first claim holds even when that plugin then fails to set up, so a later plugin for the same provider doesn't take over. `cloud` and `proxy` are reserved and can't be claimed.

0 commit comments

Comments
 (0)