Add built-in plugin system for namespaced target-scoped integrations#28
Open
burczu wants to merge 8 commits into
Open
Add built-in plugin system for namespaced target-scoped integrations#28burczu wants to merge 8 commits into
burczu wants to merge 8 commits into
Conversation
- Extend IpcCommand union with generic plugin-command envelope - Approve esbuild, simple-git-hooks, unrs-resolver build scripts in pnpm-workspace.yaml - Add .idea to .gitignore
Add plugin.ts with the full TypeScript interface for the built-in plugin system: AgentPluginState, AgentPluginTargetSession, AgentPluginCommandContext, AgentPluginTargetContext, AgentPluginDetachContext, AgentPluginCommand, and AgentPlugin with daemon/target lifecycle hooks.
Orchestrator validates unique plugin/command ids at construction, wraps RuntimeSession into AgentPluginTargetSession, sequences lifecycle hooks across all plugins, and dispatches plugin-command IPC with state enforcement before calling execute(). 19 tests covering all paths.
Replace the standalone AgentRuntimeBridge class with AgentRuntimeBridgePlugin implementing the AgentPlugin interface. The plugin checks supportsTarget in lifecycle hooks, manages its own state (idle/ready/unsupported-target), and routes SDK measurement commands through an injected CoreCommandRelay instead of holding a direct dispatcher reference. Old bridge file removed in Phase 5.
Replace hardwired AgentRuntimeBridge with PluginOrchestrator backed by AgentRuntimeBridgePlugin. Daemon intercepts plugin-command IPC before the dispatcher, sequences orchestrator lifecycle hooks alongside core attachments, and calls orchestrator.start/stop around the daemon lifetime. Delete the now-unused bridge/runtime-bridge.ts.
Define AgentPluginRegistration in cli/program.ts and extend createProgram with a plugins parameter that calls registerCliCommands for each plugin after core commands. Assemble BUILT_IN_PLUGINS in cli/index.ts with the runtime-bridge registration. Bridge registerCliCommands is a no-op for now.
Add a Built-in plugin system section to README with an overview of the protocol envelope, AgentPlugin interface, PluginOrchestrator, CLI registration, and a 4-step guide for adding a new plugin. Update AGENTS.md command family lookup with plugin system files and add guidance on plugin routing and the plugin authoring workflow.
V3RON
reviewed
May 20, 2026
V3RON
reviewed
May 20, 2026
- Fix stray 'oh ' prefix on AGENTS.md heading - Extract built-in plugin system docs to docs/PLUGINS.md - Replace verbose README section with a one-line reference
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #26.
This PR adds a built-in plugin system that lets target-scoped integrations (e.g. Rozenite) be added without leaking runtime-specific behavior into the core daemon, dispatcher, CLI, or protocol types.
plugin-commandIPC envelope added toIpcCommand; the union never needs to widen for a new pluginAgentPlugininterface (src/plugin.ts) — plugins declare a unique id, static commands, asupportsTarget()predicate, a state machine (idle / ready / unsupported-target / waiting-for-runtime / error), and optional daemon/target lifecycle hooksPluginOrchestrator(src/plugin-orchestrator.ts) — validates unique plugin/command ids at construction, wrapsRuntimeSessioninto a narrowAgentPluginTargetSession, fans out lifecycle events, and dispatchesplugin-commandIPC with state enforcement before callingexecute()AgentRuntimeBridge→ plugin — migrated tosrc/plugins/runtime-bridge/index.tsimplementingAgentPlugin; uses an injectedCoreCommandRelayinstead of holding the dispatcher directly; checkssupportsTargetin lifecycle hooks (RN-only)plugin-commandbefore the dispatcher; sequences orchestrator lifecycle alongside core attachments via existing callbacks; callsorchestrator.start/stoparound daemon lifetimecreateProgramgains aplugins: AgentPluginRegistration[]parameter;BUILT_IN_PLUGINSassembled incli/index.ts; bridgeregisterCliCommandsis a no-op placeholder for future subcommandsBackward compatibility
All existing commands, flags, outputs, and daemon behavior are unchanged. The
plugin-commandIPC type is additive. The runtime bridge behavior is identical — it now runs through the plugin seam transparently.Risks
CoreCommandRelayis a closure overthis.commandDispatcherconstructed before the dispatcher is assigned. This is safe because the relay is only called at runtime, never during construction — same pattern as the original bridge.onTargetDisconnectedis declared in the interface but not yet wired. No existing behavior changes.beforeClearTargetfires orchestrator cleanup as fire-and-forget (void). PluginonTargetClearedimplementations that do meaningful async work should be aware of this for the shutdown path.Manual testing
Requires a React Native app with
@agent-cdp/sdkinstalled (e.g. theplaygroundapp in this repo).Expected: all existing workflows unchanged; unknown plugin command returns
{"ok":false,"error":"Unknown plugin 'nope'"}.