From 752cce3ffd349c04c98f0a3f6a559dc2cc3f549c Mon Sep 17 00:00:00 2001 From: Hare Date: Mon, 15 Jun 2026 02:24:23 +0900 Subject: [PATCH] ticket: refine plugin surface model --- .yoi/tickets/00001KSXRQ4G8/item.md | 252 +++++++++++++++++++++++---- .yoi/tickets/00001KSXRQ4G8/thread.md | 42 +++++ 2 files changed, 259 insertions(+), 35 deletions(-) diff --git a/.yoi/tickets/00001KSXRQ4G8/item.md b/.yoi/tickets/00001KSXRQ4G8/item.md index e6aeb79f..25ffa005 100644 --- a/.yoi/tickets/00001KSXRQ4G8/item.md +++ b/.yoi/tickets/00001KSXRQ4G8/item.md @@ -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. diff --git a/.yoi/tickets/00001KSXRQ4G8/thread.md b/.yoi/tickets/00001KSXRQ4G8/thread.md index 5ceec833..ea7fd491 100644 --- a/.yoi/tickets/00001KSXRQ4G8/thread.md +++ b/.yoi/tickets/00001KSXRQ4G8/thread.md @@ -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 から分離する。 +--- + + + +## 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 にする。 + + +--- + + + +## 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 は必要性が具体化した時点で追加設計する。 + + +--- + + + +## 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 にはしない。 + + ---