From 4a3f605aee5cdb3e0cfdcba94e39ca89ffce939c Mon Sep 17 00:00:00 2001 From: xj Date: Sun, 22 Feb 2026 02:14:57 -0800 Subject: [PATCH] docs(plugin): document plugin model and phased roadmap --- README.md | 1 + docs/design/plugin-system-roadmap.md | 92 ++++++++++++++++++++++++++++ docs/hooks-plugin-examples.md | 43 +++++++++++++ 3 files changed, 136 insertions(+) create mode 100644 docs/design/plugin-system-roadmap.md diff --git a/README.md b/README.md index af1d9f793..ec70a52c5 100644 --- a/README.md +++ b/README.md @@ -1012,6 +1012,7 @@ PicoClaw provides typed lifecycle hooks for observability, outbound filtering, a - If hooks are not set, default behavior is unchanged. See runnable examples: [docs/hooks-plugin-examples.md](docs/hooks-plugin-examples.md) +Roadmap for plugin system evolution: [docs/design/plugin-system-roadmap.md](docs/design/plugin-system-roadmap.md)
Zhipu diff --git a/docs/design/plugin-system-roadmap.md b/docs/design/plugin-system-roadmap.md new file mode 100644 index 000000000..8a8d38ad8 --- /dev/null +++ b/docs/design/plugin-system-roadmap.md @@ -0,0 +1,92 @@ +# Plugin System Roadmap + +This document defines how PicoClaw evolves from hook-based extension points to a fuller plugin system in low-risk phases. + +## Current Status (Phase 0: Foundation) + +Implemented in current hooks MR: + +- Typed lifecycle hooks (`pkg/hooks`) +- Priority-based handler ordering +- Cancellation support for modifying hooks +- Panic recovery and error isolation +- Agent-loop integration via `agentLoop.SetHooks(...)` + +Compatibility: + +- If no hooks are registered, runtime behavior is unchanged. +- No config migration is required. + +## Non-Goals in Phase 0 + +- No dynamic runtime plugin loading +- No remote plugin marketplace/distribution +- No plugin sandboxing model +- No stable external plugin ABI yet + +## Phase Plan + +## Phase 1: Static Plugin Contract (Compile-time) + +Goal: define a minimal public plugin contract for Go modules. + +Proposed: + +- Add `pkg/plugin` with a small interface: + - `Name() string` + - `Register(*hooks.HookRegistry) error` +- Register plugins at startup in code. +- Add compatibility metadata (`PluginAPIVersion`) for forward checks. + +Exit criteria: + +- Example plugin module builds against the contract. +- Startup validation logs loaded plugins and registration errors clearly. + +## Phase 2: Config-driven Enable/Disable + +Goal: operational control without code changes. + +Proposed: + +- Add plugin list/config in `config.json`: + - enabled/disabled flags + - optional plugin-specific settings +- Deterministic load order and conflict resolution rules. + +Exit criteria: + +- Users can toggle plugins without rebuilding. +- Clear startup diagnostics for invalid plugin config. + +## Phase 3: Developer Experience + +Goal: make third-party plugin development straightforward. + +Proposed: + +- Provide `examples/plugins/*` reference implementations. +- Publish plugin authoring guide (lifecycle map, best practices, safety constraints). +- Add plugin-focused test harness pattern for hook behavior verification. + +Exit criteria: + +- New plugin can be built from template with minimal boilerplate. +- CI examples demonstrate expected behavior and regression checks. + +## Phase 4: Optional Dynamic Loading (Separate RFC) + +Goal: support runtime-loaded plugins only if security and operability are acceptable. + +Preconditions: + +- Threat model approved +- Signature/trust model defined +- Sandboxing and permission boundaries defined +- Rollback and safe-disable behavior validated + +Until then, compile-time registration remains the recommended model. + +## Maintainer Review Notes + +The current hooks MR should be reviewed as Phase 0 only. It intentionally establishes extension points while avoiding high-risk runtime plugin mechanics. diff --git a/docs/hooks-plugin-examples.md b/docs/hooks-plugin-examples.md index d243e424d..230fb8a93 100644 --- a/docs/hooks-plugin-examples.md +++ b/docs/hooks-plugin-examples.md @@ -2,11 +2,54 @@ This guide shows how to extend PicoClaw behavior with `pkg/hooks` without modifying core agent logic. +For future direction (beyond current hooks foundation), see [Plugin System Roadmap](design/plugin-system-roadmap.md). + Current model: - "Plugin-style" means registering Go handlers at startup. - Hooks are in-process (no dynamic `.so` loading). - If no hooks are registered, the runtime follows the normal zero-cost path. +## How Plugin Works + +PicoClaw's plugin model is a startup-time hook registry: + +1. Build a registry (`hooks.NewHookRegistry()`). +2. Register one or more handlers per lifecycle hook with priority. +3. Attach once with `agentLoop.SetHooks(registry)` before `agentLoop.Run(...)`. +4. Agent loop triggers hook handlers at specific lifecycle points. + +Execution semantics: + +- Observe-only hooks (`message_received`, `after_tool_call`, `llm_input`, `llm_output`, `session_start`, `session_end`) + - run concurrently + - cannot block core behavior +- Modifying hooks (`message_sending`, `before_tool_call`) + - run sequentially by priority (lower number first) + - may mutate event data + - may cancel operation via `Cancel=true` + +Safety model: + +- Panic in one handler is recovered and logged. +- Handler errors are logged; pipeline continues unless canceled by event flag. +- With no registered hooks, agent loop behavior is unchanged. + +Lifecycle map: + +```text +Inbound message + -> message_received + -> session_start + -> llm_input + -> llm_output + -> before_tool_call (cancelable) + -> tool execute + -> after_tool_call + -> message_sending (cancelable) + -> outbound publish + -> session_end +``` + ## Available Hooks | Hook | Type | Typical use |