diff --git a/work-items/open/20260603-122317-plugin-feature-contribution-registry/artifacts/pod-api-design-delegation.md b/work-items/open/20260603-122317-plugin-feature-contribution-registry/artifacts/pod-api-design-delegation.md new file mode 100644 index 00000000..1b47bcad --- /dev/null +++ b/work-items/open/20260603-122317-plugin-feature-contribution-registry/artifacts/pod-api-design-delegation.md @@ -0,0 +1,106 @@ +# Delegation intent: Plugin base Pod API design + +## Intent + +Design the public Pod-side API that will serve as the base for Plugin / Feature contributions. The result should make Plugin-provided or built-in extension modules easy to register cleanly without adding ad hoc Pod processing paths. + +This is a design task, not an implementation task. The output should be a concise but concrete design document suitable for turning into implementation tickets or acceptance criteria for `plugin-feature-contribution-registry` and `hook-public-surface-hardening`. + +## Background + +The current direction is that feature state remains owned by the feature/extension module, while interaction with Pod happens through existing durable host surfaces: + +- Tools +- Hooks +- notifications / events / durable history append paths + +The concern is that adding WorkItem, MCP, memory, plugin, and other capabilities without a common registry will create many unrelated Pod-specific insertion points. The Plugin system should establish a common contribution and authority boundary, even for built-in features. + +`hook-public-surface-hardening` is being implemented separately to make public Hook actions safe before plugin exposure. + +## Design question + +What should the clean public API look like for a feature/plugin module that wants to contribute capabilities to a Pod? + +The design should answer: + +- What API types should extension modules use to declare/register capabilities? +- What belongs in a pure descriptor vs a runtime install callback? +- How should Tools, Hooks, and notifications be represented in the same public surface? +- How should capability request / host grant / diagnostics be expressed? +- What state should the feature keep itself, and what state may Pod keep? +- What must be impossible through this API? +- Where should the API live initially, and what parts should be movable to a future `plugin`/`extension` crate? + +## Required constraints + +- Public API must not let features/plugins mutate prompt context or session history invisibly. +- Model-visible additions must go through durable host paths: tool result, committed history append, explicit notification/history append, or user-visible event path. +- Public Hook contribution must depend on the safe Hook surface after `hook-public-surface-hardening`. +- Tool contributions must use the normal ToolRegistry / PreToolCall permission / history result path. +- Feature registry must install into existing Pod/Worker surfaces; it must not create a parallel Pod runtime path. +- Capability grant is host-controlled. A feature may request capabilities but must not assume them. +- Built-in features and future external plugins should fit the same shape. +- Avoid designing package distribution, WASM execution, or MCP implementation details beyond the minimal runtime-kind placeholders needed for the API. +- Avoid broad refactors of Pod/Worker crate boundaries unless needed to explain a clean API boundary. + +## Files / records to read + +Tickets: + +- `/home/hare/Projects/yoi/work-items/open/20260603-122317-plugin-feature-contribution-registry/item.md` +- `/home/hare/Projects/yoi/work-items/open/20260603-122317-hook-public-surface-hardening/item.md` +- `/home/hare/Projects/yoi/work-items/open/20260531-010005-plugin-extension-surface/item.md` +- `/home/hare/Projects/yoi/work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md` + +Code: + +- `crates/pod/src/hook.rs` +- `crates/pod/src/ipc/interceptor.rs` +- `crates/pod/src/controller.rs` +- `crates/pod/src/pod.rs` +- `crates/pod/src/permission.rs` +- `crates/llm-worker/src/tool.rs` +- `crates/llm-worker/src/interceptor.rs` +- `crates/tools/src/lib.rs` +- `crates/pod/src/workflow/mod.rs` + +## Expected output + +Write a design document to: + +`/home/hare/Projects/yoi/work-items/open/20260603-122317-plugin-feature-contribution-registry/artifacts/pod-api-design.md` + +Use this structure: + +1. Summary recommendation +2. Current relevant Pod/Worker surfaces +3. Proposed public API shape + - types/modules + - example registration snippet + - Tool contribution + - Hook contribution + - notification/event contribution + - capability request/grant/diagnostics +4. State ownership model +5. Safety invariants / forbidden operations +6. Placement and crate-boundary recommendation +7. Migration path from current built-in registrations +8. Impact on WorkItem / MCP / plugin distribution follow-ups +9. Open questions / risks + +## Non-goals + +- Do not edit source code. +- Do not implement tests. +- Do not create a worktree. +- Do not close or modify tickets except writing the requested design artifact. + +## Completion report + +Report: + +- whether the artifact was written +- the recommended API placement +- the highest-risk API decision +- any blockers that require parent/user decision diff --git a/work-items/open/20260603-122317-plugin-feature-contribution-registry/item.md b/work-items/open/20260603-122317-plugin-feature-contribution-registry/item.md index 254fa72c..b9f74eb5 100644 --- a/work-items/open/20260603-122317-plugin-feature-contribution-registry/item.md +++ b/work-items/open/20260603-122317-plugin-feature-contribution-registry/item.md @@ -7,7 +7,7 @@ kind: feature priority: P1 labels: [plugin, registry, tools, hooks, orchestration] created_at: 2026-06-03T12:23:17Z -updated_at: 2026-06-03T12:23:17Z +updated_at: 2026-06-03T16:38:46Z assignee: null legacy_ticket: null --- diff --git a/work-items/open/20260603-122317-plugin-feature-contribution-registry/thread.md b/work-items/open/20260603-122317-plugin-feature-contribution-registry/thread.md index 963ee2d7..7769dba3 100644 --- a/work-items/open/20260603-122317-plugin-feature-contribution-registry/thread.md +++ b/work-items/open/20260603-122317-plugin-feature-contribution-registry/thread.md @@ -4,4 +4,118 @@ Created by tickets.sh create. +--- + + + +## Plan + +# Delegation intent: Plugin base Pod API design + +## Intent + +Design the public Pod-side API that will serve as the base for Plugin / Feature contributions. The result should make Plugin-provided or built-in extension modules easy to register cleanly without adding ad hoc Pod processing paths. + +This is a design task, not an implementation task. The output should be a concise but concrete design document suitable for turning into implementation tickets or acceptance criteria for `plugin-feature-contribution-registry` and `hook-public-surface-hardening`. + +## Background + +The current direction is that feature state remains owned by the feature/extension module, while interaction with Pod happens through existing durable host surfaces: + +- Tools +- Hooks +- notifications / events / durable history append paths + +The concern is that adding WorkItem, MCP, memory, plugin, and other capabilities without a common registry will create many unrelated Pod-specific insertion points. The Plugin system should establish a common contribution and authority boundary, even for built-in features. + +`hook-public-surface-hardening` is being implemented separately to make public Hook actions safe before plugin exposure. + +## Design question + +What should the clean public API look like for a feature/plugin module that wants to contribute capabilities to a Pod? + +The design should answer: + +- What API types should extension modules use to declare/register capabilities? +- What belongs in a pure descriptor vs a runtime install callback? +- How should Tools, Hooks, and notifications be represented in the same public surface? +- How should capability request / host grant / diagnostics be expressed? +- What state should the feature keep itself, and what state may Pod keep? +- What must be impossible through this API? +- Where should the API live initially, and what parts should be movable to a future `plugin`/`extension` crate? + +## Required constraints + +- Public API must not let features/plugins mutate prompt context or session history invisibly. +- Model-visible additions must go through durable host paths: tool result, committed history append, explicit notification/history append, or user-visible event path. +- Public Hook contribution must depend on the safe Hook surface after `hook-public-surface-hardening`. +- Tool contributions must use the normal ToolRegistry / PreToolCall permission / history result path. +- Feature registry must install into existing Pod/Worker surfaces; it must not create a parallel Pod runtime path. +- Capability grant is host-controlled. A feature may request capabilities but must not assume them. +- Built-in features and future external plugins should fit the same shape. +- Avoid designing package distribution, WASM execution, or MCP implementation details beyond the minimal runtime-kind placeholders needed for the API. +- Avoid broad refactors of Pod/Worker crate boundaries unless needed to explain a clean API boundary. + +## Files / records to read + +Tickets: + +- `/home/hare/Projects/yoi/work-items/open/20260603-122317-plugin-feature-contribution-registry/item.md` +- `/home/hare/Projects/yoi/work-items/open/20260603-122317-hook-public-surface-hardening/item.md` +- `/home/hare/Projects/yoi/work-items/open/20260531-010005-plugin-extension-surface/item.md` +- `/home/hare/Projects/yoi/work-items/open/20260601-031252-builtin-work-item-intake-routing/item.md` + +Code: + +- `crates/pod/src/hook.rs` +- `crates/pod/src/ipc/interceptor.rs` +- `crates/pod/src/controller.rs` +- `crates/pod/src/pod.rs` +- `crates/pod/src/permission.rs` +- `crates/llm-worker/src/tool.rs` +- `crates/llm-worker/src/interceptor.rs` +- `crates/tools/src/lib.rs` +- `crates/pod/src/workflow/mod.rs` + +## Expected output + +Write a design document to: + +`/home/hare/Projects/yoi/work-items/open/20260603-122317-plugin-feature-contribution-registry/artifacts/pod-api-design.md` + +Use this structure: + +1. Summary recommendation +2. Current relevant Pod/Worker surfaces +3. Proposed public API shape + - types/modules + - example registration snippet + - Tool contribution + - Hook contribution + - notification/event contribution + - capability request/grant/diagnostics +4. State ownership model +5. Safety invariants / forbidden operations +6. Placement and crate-boundary recommendation +7. Migration path from current built-in registrations +8. Impact on WorkItem / MCP / plugin distribution follow-ups +9. Open questions / risks + +## Non-goals + +- Do not edit source code. +- Do not implement tests. +- Do not create a worktree. +- Do not close or modify tickets except writing the requested design artifact. + +## Completion report + +Report: + +- whether the artifact was written +- the recommended API placement +- the highest-risk API decision +- any blockers that require parent/user decision + + ---