ticket: refine plugin surface model
This commit is contained in:
parent
4be6c9662d
commit
752cce3ffd
|
|
@ -1,18 +1,24 @@
|
|||
---
|
||||
title: 'Plugin: define extension surface for hooks and tools'
|
||||
title: 'Plugin: define runtime, surface, and minimal host API model'
|
||||
state: 'planning'
|
||||
created_at: '2026-05-31T01:00:05Z'
|
||||
updated_at: '2026-06-13T15:29:21Z'
|
||||
updated_at: '2026-06-14T17:22:23Z'
|
||||
assignee: null
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Design Yoi's Plugin surface as the user-facing package/config/runtime layer built on top of `pod::feature`.
|
||||
Design Yoi's Plugin model as a user-facing package/config/runtime layer built on top of `pod::feature` and a deliberately small host API.
|
||||
|
||||
`pod::feature` is the internal API substrate for contribution registration: Tools, Hooks, BackgroundTasks, Services, diagnostics, and lifecycle integration. Plugin is the layer that makes that substrate usable by users and workspaces through package metadata, enablement config, runtime choices, provenance, and Plugin-layer permissions.
|
||||
Use three stable terms:
|
||||
|
||||
MCP is not the Plugin model and should not be treated as a Plugin permission backend. MCP is a separate protocol-backed integration layer that also uses the feature API and owns its own MCP-specific enablement/trust policy.
|
||||
- **Plugin runtime**: how Plugin code/config is executed.
|
||||
- **Plugin surface**: what the Plugin adds to Yoi.
|
||||
- **Plugin host API**: what Yoi-provided capabilities a Plugin runtime may call while implementing a surface.
|
||||
|
||||
`pod::feature` remains the internal substrate for contribution registration, lifecycle diagnostics, and Worker/ToolRegistry/HookRegistry integration. Plugin owns package identity, enablement, runtime selection, Plugin-layer permissions, trust policy, and host API grants.
|
||||
|
||||
MCP is not the Plugin model and should not be treated as a Plugin permission backend. MCP is a separate protocol-backed integration layer that also uses `pod::feature` and owns MCP-specific enablement/trust policy.
|
||||
|
||||
## Background
|
||||
|
||||
|
|
@ -23,66 +29,242 @@ Yoi already has internal extension-like surfaces:
|
|||
- Feature contribution declarations in `pod::feature`
|
||||
- Built-in features such as task and ticket tools
|
||||
|
||||
The Plugin surface should expose extension points without letting external packages bypass Worker history, prompt/context invariants, scoped tool permissions, or role/profile configuration.
|
||||
Plugin design must not let external packages bypass Worker history, prompt/context invariants, scoped tool permissions, restore snapshot authority, or launch-policy authority.
|
||||
|
||||
Prior Hook hardening work constrains model-visible context mutation so Plugin exposure can stay safe. Plugin design should reuse those safe surfaces rather than creating a parallel tool/hook runtime.
|
||||
Prior Hook hardening work constrains model-visible context mutation so Plugin exposure can stay safe. Plugin design should reuse those safe surfaces rather than creating parallel prompt/history/tool paths.
|
||||
|
||||
A concrete future use case is a chat bridge such as Slack/Discord. The preferred architecture is not that Yoi starts or bundles a full Slack/Discord SDK process. An externally managed bridge service, such as a `discord.js` service, may expose a small HTTPS API; a Yoi Plugin can call that API using configured URL/auth data. A Plugin may also run a Pod-lifetime service loop and submit external events through a host-mediated Ingress surface, but those semantics must stay concrete and bounded.
|
||||
|
||||
## Plugin runtime
|
||||
|
||||
Runtime answers: **how is Plugin code/config executed?**
|
||||
|
||||
Supported design vocabulary:
|
||||
|
||||
- `declarative`: config-only Plugin behavior, no arbitrary code execution.
|
||||
- `wasm`: sandboxed WASM Plugin module with explicit host APIs.
|
||||
- `external_process`: future/optional runtime. Do not assume it for the initial Plugin model.
|
||||
|
||||
The initial runtime direction is:
|
||||
|
||||
```text
|
||||
runtime: declarative and/or wasm
|
||||
host APIs: https + fs, plus surface-intrinsic ingress/diagnostics where required
|
||||
surfaces: Tool + Hook + Service + Ingress
|
||||
```
|
||||
|
||||
## Plugin surface
|
||||
|
||||
Surface answers: **what does the Plugin add to Yoi?**
|
||||
|
||||
The Plugin surfaces are:
|
||||
|
||||
- `Tool`
|
||||
- `Hook`
|
||||
- `Service`
|
||||
- `Ingress`
|
||||
|
||||
Do not use `Outbound` as a separate surface. External writes are represented as Tool surface entries with side-effect metadata.
|
||||
|
||||
### Tool surface
|
||||
|
||||
A Tool surface adds model/workflow-callable operations through ordinary Yoi ToolRegistry paths.
|
||||
|
||||
External side effects such as chat sends are Tools:
|
||||
|
||||
```text
|
||||
discord_send_message
|
||||
slack_reply_thread
|
||||
github_create_issue_comment
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- registers through ordinary ToolRegistry / `pod::feature` paths
|
||||
- uses normal model-visible schema exposure
|
||||
- passes normal PreToolCall permission policy
|
||||
- commits tool call/result through normal history plumbing
|
||||
- uses bounded result serialization
|
||||
- declares side-effect metadata such as `effect = "external_write"` where applicable
|
||||
- validates configured destination allowlists before executing external writes
|
||||
|
||||
### Hook surface
|
||||
|
||||
A Hook surface reacts to supported Yoi lifecycle events using the hardened public Hook API.
|
||||
|
||||
Requirements:
|
||||
|
||||
- no raw hidden `Item` injection
|
||||
- no prompt/context mutation outside durable history-aware paths
|
||||
- explicit supported `HookAction` subset only
|
||||
- Hook-triggered external writes must still go through Tool or another explicit host-approved path, not hidden side effects
|
||||
|
||||
### Service surface
|
||||
|
||||
A Service surface is Pod-lifetime Plugin work managed by Yoi's Plugin runtime.
|
||||
|
||||
The initial Service contract is concrete and limited:
|
||||
|
||||
- Services start during Pod startup after explicit Plugin enablement is resolved.
|
||||
- Services stop when the Pod stops or when the Plugin instance is replaced during restore/relaunch.
|
||||
- Services report lifecycle state: `starting`, `ready`, `degraded`, `failed`, `stopping`, `stopped`.
|
||||
- Services may use only granted Plugin host APIs, initially `https` and `fs`, plus surface-intrinsic diagnostics and ingress submission where granted.
|
||||
- Services must be cancellable and must not block Pod shutdown indefinitely.
|
||||
- Service diagnostics must be bounded and must redact secrets.
|
||||
|
||||
For chat bridge Plugins, Service is the WASM-side client loop that communicates with an externally managed bridge service over HTTPS polling or other explicitly designed future event mechanisms. WebSocket/SSE are not implied by the word Service; they require separate host API design.
|
||||
|
||||
### Ingress surface
|
||||
|
||||
Ingress is the host-mediated surface for external events entering Yoi.
|
||||
|
||||
Plugins do **not** directly choose `Notify`, `Run`, target Pod, or hidden context insertion. A Plugin submits a typed external event to the host:
|
||||
|
||||
```text
|
||||
host.ingress.submit(event)
|
||||
```
|
||||
|
||||
Then host routing policy decides delivery:
|
||||
|
||||
```text
|
||||
submit external event -> route/dedup/bounds/policy -> notify | run | drop | diagnostic
|
||||
```
|
||||
|
||||
Initial typed event target for chat bridges:
|
||||
|
||||
```text
|
||||
ExternalMessageEvent {
|
||||
source_plugin,
|
||||
provider,
|
||||
external_workspace_id/team_id/guild_id,
|
||||
channel_id,
|
||||
thread_id?,
|
||||
message_id,
|
||||
actor_id,
|
||||
actor_display_name?,
|
||||
text,
|
||||
attachments[],
|
||||
timestamp,
|
||||
permalink?,
|
||||
dedup_key,
|
||||
}
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- external content is untrusted
|
||||
- event size is bounded before entering Yoi history/model-visible context
|
||||
- host performs deduplication and loop prevention
|
||||
- host routing config decides target Pod and delivery mode
|
||||
- accepted events are appended through durable history/notification paths before they can affect model context
|
||||
- rejected/dropped events produce bounded diagnostics without unnecessarily storing message content
|
||||
|
||||
## Plugin host APIs
|
||||
|
||||
Host API answers: **what Yoi-provided capabilities can a Plugin runtime call while implementing a surface?**
|
||||
|
||||
Host APIs are runtime capabilities controlled by Plugin-layer grants. Keep this set narrow. Do not add a broad API to avoid deciding concrete semantics.
|
||||
|
||||
The initial general-purpose host API set is:
|
||||
|
||||
- `https`: bounded HTTPS client only.
|
||||
- `fs`: scoped filesystem read/write under explicit Plugin grants.
|
||||
|
||||
Surface-intrinsic host calls also exist where required:
|
||||
|
||||
- `ingress.submit`: available only to Plugins granted the Ingress surface.
|
||||
- `diagnostics`: bounded lifecycle/error/health reporting for Plugin runtime and Service surface.
|
||||
|
||||
Use `https`, not `web`, for the initial network API. The first network host API should not imply arbitrary browser-like web capabilities, raw TCP, local network access, HTTP without TLS, WebSocket, SSE, DNS policy, or remote fetching semantics beyond the explicitly designed HTTPS client.
|
||||
|
||||
### `https` host API
|
||||
|
||||
Initial requirements:
|
||||
|
||||
- HTTPS only
|
||||
- explicit allowlist of origins or exact endpoints
|
||||
- bounded request/response size
|
||||
- timeout/cancellation
|
||||
- configured headers/auth data only through Plugin enablement policy
|
||||
- no implicit access to ambient environment variables or host credentials
|
||||
- diagnostics must redact credentials and sensitive headers
|
||||
|
||||
WebSocket, SSE, long polling helpers, and inbound server/webhook APIs are out of the initial host API unless a later Ticket designs them explicitly.
|
||||
|
||||
### `fs` host API
|
||||
|
||||
Initial requirements:
|
||||
|
||||
- scoped paths explicitly granted by Plugin-layer policy
|
||||
- no automatic inheritance from Pod workspace scope
|
||||
- bounded read/write operations
|
||||
- path traversal protection
|
||||
- diagnostics that identify denied paths without leaking file contents
|
||||
|
||||
## Requirements
|
||||
|
||||
- Define Plugin as a user-facing layer over `pod::feature`, not as the feature API itself.
|
||||
- Plugin package/config/runtime code eventually contributes through `pod::feature`.
|
||||
- `pod::feature` remains responsible for contribution declarations, lifecycle, diagnostics, and registration plumbing.
|
||||
- Plugin remains responsible for package enablement, provenance, runtime selection, and Plugin-layer permission/trust policy.
|
||||
- Define supported contribution categories.
|
||||
- Tools
|
||||
- Hooks
|
||||
- Background tasks / services, if included in the initial model
|
||||
- Future extensions must remain explicit contribution categories, not arbitrary host access.
|
||||
- Plugin remains responsible for package enablement, provenance, runtime selection, host API grants, and Plugin-layer permission/trust policy.
|
||||
- Use the terms `Plugin runtime`, `Plugin surface`, and `Plugin host API`; avoid durable/user-facing use of `contribution category`.
|
||||
- Plugin surfaces are Tool / Hook / Service / Ingress.
|
||||
- Service has a Pod-lifetime lifecycle contract; it does not imply WebSocket/SSE/raw network support.
|
||||
- Ingress is `host.ingress.submit(typed external event)`; host routing decides notify/run/drop/diagnostic.
|
||||
- External outbound side effects are Tool surface entries with external-write metadata, not a separate Outbound surface.
|
||||
- Initial general-purpose Plugin host APIs are only `https` and `fs`.
|
||||
- `ingress.submit` and `diagnostics` are surface-intrinsic host calls, not broad ambient capabilities.
|
||||
- Do not expose a generic `web` API in the initial Plugin model.
|
||||
- Define Plugin-layer permission and trust model separately from `pod::feature`.
|
||||
- Do not rely on feature-level `HostAuthority` / authority grants for Plugin permissions.
|
||||
- Plugin grants should be tied to package identity/runtime/user or workspace config, not to feature install reports.
|
||||
- Plugin policy must decide which contribution categories and host APIs a Plugin runtime can use.
|
||||
- Plugin grants are tied to package identity/runtime/user or workspace config, not feature install reports.
|
||||
- Plugin policy decides which surfaces and host APIs a Plugin runtime can use.
|
||||
- Define runtime families separately.
|
||||
- Declarative/config-only Plugins
|
||||
- WASM or another sandboxed runtime, if/when selected
|
||||
- External process/plugin bridge, if/when selected
|
||||
- WASM Plugins
|
||||
- External process Plugins only as an explicit future/optional runtime
|
||||
- MCP remains a separate feature-backed protocol integration, not the Plugin permission model.
|
||||
- Hook Plugins must use the hardened public Hook surface.
|
||||
- no raw hidden `Item` injection
|
||||
- no prompt/context mutation outside durable history-aware paths
|
||||
- explicit supported `HookAction` subset only
|
||||
- Tool Plugins must register ordinary Yoi tools.
|
||||
- normal tool schema exposure
|
||||
- normal PreToolCall permission path
|
||||
- normal tool-result history path
|
||||
- bounded result serialization
|
||||
- Plugin metadata and package content are untrusted input.
|
||||
- Plugin metadata, config, external data, and package content are untrusted input.
|
||||
- Plugin enablement must be explicit.
|
||||
- package presence/discovery alone cannot enable or execute Plugin code
|
||||
- workspace/user config must opt in to package/runtime/contribution activation
|
||||
- workspace/user config must opt in to package/runtime/surface activation and host API grants
|
||||
- The design must document the boundary among Plugin, MCP, and built-in Features.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- A design note or Ticket plan defines Plugin as a user-facing layer over `pod::feature`.
|
||||
- The plan uses `runtime`, `surface`, and `host API` terminology and avoids relying on `contribution category` as the durable term.
|
||||
- The plan states that Plugin surfaces are Tool / Hook / Service / Ingress.
|
||||
- The plan states that Service has concrete Pod-lifetime lifecycle semantics and does not imply unspecified network/event APIs.
|
||||
- The plan states that Ingress is typed external-event submission to the host, not direct Notify/Run/context injection.
|
||||
- The plan states that external outbound side effects are Tool surface entries with external-write metadata.
|
||||
- The plan states that initial general-purpose Plugin host APIs are `https` and `fs` only.
|
||||
- The plan states that `https` is HTTPS-only and does not imply generic `web`/browser/raw-network capabilities.
|
||||
- The plan states that filesystem access is a Plugin host API controlled by Plugin-layer grants and does not inherit Pod workspace scope automatically.
|
||||
- The plan states that Plugin permissions are Plugin-layer policy and are not implemented by `pod::feature` `HostAuthority` grants.
|
||||
- The plan states that MCP is a separate feature-backed integration with MCP-specific enablement/trust policy.
|
||||
- Contribution categories and runtime families are named with explicit in/out of scope decisions for the first implementation slice.
|
||||
- The public Hook safety invariants from `00001KT6Q08R8` remain intact.
|
||||
- Tool Plugins are required to use ordinary ToolRegistry / permission / history / bounded-result paths.
|
||||
- No design path allows Plugin package presence alone to execute code or mutate context.
|
||||
- The design identifies which follow-up Tickets own package format, runtime implementation, and Plugin permission details.
|
||||
- The design identifies which follow-up Tickets own package format, runtime implementation, host APIs, and Plugin permission details.
|
||||
|
||||
## Suggested decomposition
|
||||
|
||||
1. Public Hook surface hardening. Completed by `00001KT6Q08R8`.
|
||||
2. Feature contribution API substrate. Completed initial slice by `00001KT6Q08R9`; dynamic provider work continues in `00001KTR81P9X`.
|
||||
2. Feature contribution API substrate. Completed by `00001KT6Q08R9` and `00001KTR81P9X`.
|
||||
3. Plugin package/discovery format. Tracked by `00001KT0Z4BK8`.
|
||||
4. Plugin permission/runtime policy Ticket. Create or refine after runtime family is selected; do not put this policy into `pod::feature`.
|
||||
5. MCP local stdio integration. Tracked separately by `00001KTR82RB7`; it uses feature API but is not Plugin permission work.
|
||||
4. Plugin enablement plan + metadata snapshot restore integration.
|
||||
5. WASM/declarative runtime slice with Tool and Hook surfaces.
|
||||
6. Plugin host API slice for `https` and `fs` only.
|
||||
7. Service lifecycle surface.
|
||||
8. Ingress external-message submission and routing policy.
|
||||
9. Tool external-write metadata and destination allowlist enforcement.
|
||||
10. Future Ticket: streaming event APIs such as SSE/WebSocket/long polling, if HTTPS polling is insufficient.
|
||||
11. MCP local stdio integration remains tracked separately by `00001KTR82RB7`.
|
||||
|
||||
## Notes
|
||||
|
||||
- This Ticket is a design coordination Ticket; implementation should be split into concrete Tickets rather than landing a broad Plugin platform in one change.
|
||||
- Keep Plugin permission terms distinct from `HostAuthority`. If `HostAuthority` remains in code, it is not the Plugin policy surface.
|
||||
- Avoid adding support for arbitrary scripting languages until package identity, runtime sandbox/trust, and permission policy are explicit.
|
||||
- Keep Plugin permission terms distinct from removed feature-layer `HostAuthority` terminology.
|
||||
- Avoid requiring Yoi to manage arbitrary external SDK processes for chat bridge support.
|
||||
- Avoid broad host APIs. Add host APIs only when a concrete Plugin surface and use case require them.
|
||||
|
|
|
|||
|
|
@ -57,4 +57,46 @@ This preserves the desired detachable shape: feature state remains in the featur
|
|||
- `00001KSXRQ4G8` と `00001KT0Z4BK8` は Plugin permission を Plugin layer として扱い、MCP を初期 Plugin packaging/runtime から分離する。
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-06-14T16:53:27Z -->
|
||||
|
||||
## Decision
|
||||
|
||||
決定:
|
||||
- Durable terminology は `Plugin runtime` / `Plugin surface` / `Plugin host API` にする。`contribution category` は分かりづらいため設計語彙として使わない。
|
||||
- Plugin surface は Tool / Hook / Service / Ingress の4つに整理する。
|
||||
- Outbound は独立 surface にしない。Slack/Discord 送信など外部副作用は `external_write` metadata を持つ Tool として扱う。
|
||||
- Ingress は Plugin が Notify/Run を直接呼ぶ API ではなく、typed external event を host に submit する API とする。host routing policy が notify/run/drop を決める。
|
||||
- Web/FS/Secret/State/Timer/Diagnostics は Plugin surface ではなく Plugin host API。WASM などの runtime が surface を実装するために、Plugin-layer grant で明示的に許可された範囲だけ使える。
|
||||
- Chat bridge target は、Yoi が discord.js/Slack SDK process を起動する前提にしない。外部管理の bridge service に WASM Plugin が configured URL + SecretRef で接続する設計を first-class にする。
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-06-14T17:19:59Z -->
|
||||
|
||||
## Decision
|
||||
|
||||
決定:
|
||||
- Initial Plugin surface は Tool / Hook を主軸にする。
|
||||
- Service / Ingress は将来候補として残すが、Submit/Notify/Run や lifecycle semantics を具体化する別 Ticket まで初期 contract には入れない。
|
||||
- Outbound は独立 surface にしない。外部副作用は `external_write` metadata を持つ Tool として扱う。
|
||||
- Plugin host API は初期は `https` と `fs` に絞る。`web` という広い API 名は使わず、HTTPS-only の bounded client と scoped FS として設計する。
|
||||
- WebSocket/SSE/long polling、timer、state、secret plaintext access、Ingress submit API は必要性が具体化した時点で追加設計する。
|
||||
|
||||
|
||||
---
|
||||
|
||||
<!-- event: decision author: hare at: 2026-06-14T17:22:23Z -->
|
||||
|
||||
## Decision
|
||||
|
||||
決定:
|
||||
- Service / Ingress は Plugin surface として必要なので初期設計対象に戻す。
|
||||
- Service は Pod-lifetime の Plugin work として具体化する。ただし Service という語は WebSocket/SSE/raw network support を含意しない。初期の外部通信は `https` host API の範囲に限定し、streaming API は別途設計する。
|
||||
- Ingress は `host.ingress.submit(typed external event)` として具体化する。Plugin が Notify/Run/context injection を直接選ばず、host routing policy が notify/run/drop/diagnostic を決める。
|
||||
- General-purpose host API は引き続き `https` と `fs` に絞る。`ingress.submit` と `diagnostics` は surface-intrinsic host calls として扱い、広い ambient capability にはしない。
|
||||
|
||||
|
||||
---
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user