ticket: add plugin host api followups

2026-06-19 16:54:40 +09:00 · 2026-06-19 16:54:40 +09:00 · f1876321c5
commit f1876321c5
parent 8940262618
15 changed files with 533 additions and 2 deletions
--- a/.yoi/tickets/00001KVDJCVWZ/item.md
+++ b/.yoi/tickets/00001KVDJCVWZ/item.md
@ -1,8 +1,8 @@
 ---
 title: 'Orchestrator Ticket event Companion notify の peer registration / diagnostics を修正する'
-state: 'done'
+state: 'closed'
 created_at: '2026-06-18T14:33:09Z'
-updated_at: '2026-06-18T14:33:50Z'
+updated_at: '2026-06-19T07:52:14Z'
 assignee: null
 readiness: 'implementation_ready'
 risk_flags: ['orchestrator', 'companion', 'peer-notify', 'ticket-event', 'auto-run-false', 'diagnostics']
--- a/.yoi/tickets/00001KVDJCVWZ/resolution.md
+++ b/.yoi/tickets/00001KVDJCVWZ/resolution.md
@ -0,0 +1,3 @@
+Ticket `00001KVDJCVWZ` (`Orchestrator Ticket event Companion notify の peer registration / diagnostics を修正する`) はすでに `state: done` に到達していたため、workspace Panel から close しました。
+
+この Close action によって、実装作業、state 変更、Orchestrator/Companion launch、worker invocation は開始されていません。
--- a/.yoi/tickets/00001KVDJCVWZ/thread.md
+++ b/.yoi/tickets/00001KVDJCVWZ/thread.md
@ -4,4 +4,24 @@

 LocalTicketBackend によって作成されました。

+---
+
+<!-- event: state_changed author: hare at: 2026-06-19T07:52:14Z from: done to: closed reason: closed field: state -->
+
+## State changed
+
+Ticket を closed にしました。
+
+
+---
+
+<!-- event: close author: hare at: 2026-06-19T07:52:14Z status: closed -->
+
+## 完了
+
+Ticket `00001KVDJCVWZ` (`Orchestrator Ticket event Companion notify の peer registration / diagnostics を修正する`) はすでに `state: done` に到達していたため、workspace Panel から close しました。
+
+この Close action によって、実装作業、state 変更、Orchestrator/Companion launch、worker invocation は開始されていません。
+
+
 ---
--- a/.yoi/tickets/00001KVFD3YSV/artifacts/.gitkeep
+++ b/.yoi/tickets/00001KVFD3YSV/artifacts/.gitkeep
--- a/.yoi/tickets/00001KVFD3YSV/artifacts/relations.json
+++ b/.yoi/tickets/00001KVFD3YSV/artifacts/relations.json
@ -0,0 +1,45 @@
+{
+  "version": 1,
+  "relations": [
+    {
+      "ticket_id": "00001KVFD3YSV",
+      "kind": "depends_on",
+      "target": "00001KV5R5V2S",
+      "note": "CLI inspection consumes Plugin package discovery and enablement resolver output.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:40:41Z"
+    },
+    {
+      "ticket_id": "00001KVFD3YSV",
+      "kind": "depends_on",
+      "target": "00001KV5W3PJ3",
+      "note": "CLI inspection should expose permission/grant diagnostics from the implemented grant model.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:40:41Z"
+    },
+    {
+      "ticket_id": "00001KVFD3YSV",
+      "kind": "related",
+      "target": "00001KSXRQ4G8",
+      "note": "Uses established Plugin runtime/surface/host API terminology.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:40:41Z"
+    },
+    {
+      "ticket_id": "00001KVFD3YSV",
+      "kind": "related",
+      "target": "00001KV5W3PHA",
+      "note": "Tool surface registration status should be visible in inspection output.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:40:41Z"
+    },
+    {
+      "ticket_id": "00001KVFD3YSV",
+      "kind": "related",
+      "target": "00001KV5W3PHW",
+      "note": "Runtime config/status should be shown without executing Plugin code.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:40:41Z"
+    }
+  ]
+}
--- a/.yoi/tickets/00001KVFD3YSV/item.md
+++ b/.yoi/tickets/00001KVFD3YSV/item.md
@ -0,0 +1,184 @@
+---
+title: 'Plugin: add read-only CLI inspection list/show'
+state: 'ready'
+created_at: '2026-06-19T07:39:23Z'
+updated_at: '2026-06-19T07:40:41Z'
+assignee: null
+readiness: 'implementation_ready'
+risk_flags: ['plugin', 'cli', 'diagnostics', 'read-only', 'json-output', 'no-execution']
+---
+
+## Background
+
+Plugin package discovery / explicit enablement / Tool registration / WASM Tool runtime / permission grants まで実装されたため、次に必要なのは「なぜ Plugin が見えない / 有効化されない / 実行できないのか」を headless に確認できる read-only inspection surface である。
+
+Panel や TUI diagnostic に出す前に、CLI で deterministic に確認できる `yoi plugin list` / `yoi plugin show <ref>` を追加する。この CLI は Plugin code を実行せず、package discovery、manifest parse、enablement resolution、grant validation、static diagnostics を表示するだけにする。
+
+目的は、Plugin の多段 failure point を human / JSON の両方で確認できるようにすること。
+
+```text
+package discovered?
+manifest valid?
+api version compatible?
+explicitly enabled?
+digest/version/source match?
+requested permission granted?
+tool schema valid?
+runtime config present?
+```
+
+## Requirements
+
+- Top-level product CLI に read-only Plugin inspection command を追加する。
+  - `yoi plugin list`
+  - `yoi plugin show <ref>`
+- `--json` output を最初から提供する。
+  - `yoi plugin list --json`
+  - `yoi plugin show <ref> --json`
+- Human-readable output は JSON 用 typed report の thin formatting にする。
+- Workspace / Profile resolution は通常起動に近い意味にする。
+  - default は current workspace。
+  - 既存 CLI 方針に合わせて `--workspace <path>` を扱う。
+  - Profile 指定が必要なら既存 Profile selector と整合する option を使う。
+- Plugin code を実行しない。
+  - WASM module を実行しない。
+  - Tool call を発生させない。
+  - Hook / Service / Ingress を起動しない。
+- Read-only とする。
+  - install / update / enable / disable / trust / sign / run は non-goal。
+  - Plugin package / config / Ticket / memory / Pod state を変更しない。
+- Inspection report は typed data として実装する。
+  - future Panel diagnostic / tests / agent-readable output で再利用できる形にする。
+- `list` は package/ref 単位の overview を出す。
+  - ref
+  - source
+  - package path (human output では必要に応じて短縮)
+  - version
+  - api version
+  - digest
+  - status
+  - enabled surfaces
+  - diagnostic count / summary
+- `show <ref>` は詳細を出す。
+  - manifest metadata
+  - source-qualified identity
+  - package path
+  - digest
+  - version / api version
+  - runtime kind/config summary
+  - enabled surfaces
+  - Tool definitions and registration eligibility
+  - requested permissions
+  - granted permissions
+  - effective grants / denied grants
+  - diagnostics
+- Status vocabulary を明確にする。
+  - `active`: enabled and statically valid for at least one surface/tool.
+  - `disabled`: discovered but not explicitly enabled.
+  - `missing`: enablement refers to a package that is not discovered.
+  - `rejected`: invalid manifest / incompatible api / digest mismatch / grant mismatch / invalid schema etc.
+  - `partial`: package is usable but some surfaces/tools are rejected.
+- Diagnostics は bounded / safe にする。
+  - secret-like values / auth / file contents を出さない。
+  - path は必要最小限。JSON では absolute path が必要なら workspace/user store source と一緒に出す。
+  - denial / parse / digest / grant mismatch reasons を区別できる。
+- Ambiguous unqualified ref は fail closed し、`show` で diagnostic を返す。
+- JSON schema は stable typed structure として test で固定する。
+
+## Example human output
+
+`yoi plugin list`:
+
+```text
+REF                    SOURCE   VERSION  STATUS    SURFACES  DIGEST
+project:example.echo   project  0.1.0    active    tool      sha256:...
+project:broken         project  -        rejected  -         -
+user:fetch             user     0.2.1    disabled  tool      sha256:...
+```
+
+`yoi plugin show project:example.echo`:
+
+```text
+Plugin: project:example.echo
+Source: project
+Package: .yoi/plugins/example.echo.yoi-plugin
+Version: 0.1.0
+API: yoi-plugin-1
+Digest: sha256:...
+Status: active
+
+Enabled surfaces:
+- tool
+
+Tools:
+- example_echo
+  status: registered
+  schema: valid
+  external_write: false
+
+Permissions:
+Requested:
+- surfaces.tool
+- tool:example_echo
+
+Granted:
+- surfaces.tool
+- tool:example_echo
+
+Diagnostics:
+- none
+```
+
+## Acceptance criteria
+
+- `yoi plugin list` prints a bounded human-readable overview without executing Plugin code.
+- `yoi plugin show <ref>` prints detailed static inspection for a Plugin ref without executing Plugin code.
+- `--json` output is available for both commands and uses a stable typed structure.
+- Valid enabled Plugin appears as `active`.
+- Discovered but not enabled Plugin appears as `disabled`.
+- Enabled but missing package appears as `missing`.
+- Invalid manifest / incompatible api version appears as `rejected` with diagnostic.
+- Digest / version / source mismatch appears as diagnostic.
+- Grant denial / missing requested permission appears as diagnostic.
+- Partial tool/surface rejection can be represented without marking the whole package as fully active.
+- Ambiguous unqualified id fails closed with diagnostic.
+- Plugin code / WASM / Tool execution is not triggered by list/show.
+- Tests cover:
+  - list human output for active / disabled / rejected / missing packages
+  - show human output for active package with Tool surface and grants
+  - JSON list structure
+  - JSON show structure
+  - invalid manifest diagnostic
+  - digest mismatch diagnostic
+  - missing grant diagnostic
+  - ambiguous ref diagnostic
+  - no runtime execution from inspection path
+- Validation: focused CLI/plugin inspection tests, relevant `cargo check` / `cargo test`, `cargo fmt --check`, `git diff --check`, and `nix build .#yoi` because product CLI / packaging surface changes.
+
+## Non-goals
+
+- Plugin install / update / remove.
+- Enable / disable mutation.
+- Trust / signature / registry implementation.
+- Plugin code execution.
+- WASM validation beyond static runtime config/manifest inspection.
+- `https` host API implementation.
+- `fs` host API implementation.
+- Service / Ingress startup.
+- Panel/TUI Plugin diagnostics UI.
+
+## Implementation notes
+
+- Product CLI ownership stays in the `yoi` crate.
+- Avoid embedding resolver logic directly in display formatting; build a typed inspection report first.
+- Reuse existing Plugin resolver / diagnostics where possible.
+- Keep CLI output deterministic and suitable for tests.
+- Do not introduce user-facing terminology `contribution category`; use Plugin runtime / surface / host API / grants.
+
+## Related work
+
+- `00001KV5R5V2S` — Plugin package discovery and explicit enablement resolver.
+- `00001KV5W3PHA` — Plugin Tool surface registration.
+- `00001KV5W3PHW` — Plugin Tool execution with minimal WASM runtime.
+- `00001KV5W3PJ3` — Plugin permission grant enforcement.
+- `00001KSXRQ4G8` — Plugin runtime / surface / minimal host API model design.
--- a/.yoi/tickets/00001KVFD3YSV/thread.md
+++ b/.yoi/tickets/00001KVFD3YSV/thread.md
@ -0,0 +1,7 @@
+<!-- event: create author: "yoi ticket" at: 2026-06-19T07:39:23Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---
--- a/.yoi/tickets/00001KVFDX9AF/artifacts/.gitkeep
+++ b/.yoi/tickets/00001KVFDX9AF/artifacts/.gitkeep
--- a/.yoi/tickets/00001KVFDX9AF/artifacts/relations.json
+++ b/.yoi/tickets/00001KVFDX9AF/artifacts/relations.json
@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "relations": [
+    {
+      "ticket_id": "00001KVFDX9AF",
+      "kind": "depends_on",
+      "target": "00001KV5W3PHW",
+      "note": "https host API is implemented inside the WASM Plugin Tool runtime.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    },
+    {
+      "ticket_id": "00001KVFDX9AF",
+      "kind": "depends_on",
+      "target": "00001KV5W3PJ3",
+      "note": "https host API must be guarded by Plugin permission grants.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    },
+    {
+      "ticket_id": "00001KVFDX9AF",
+      "kind": "related",
+      "target": "00001KSXRQ4G8",
+      "note": "Uses established Plugin host API terminology.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    },
+    {
+      "ticket_id": "00001KVFDX9AF",
+      "kind": "related",
+      "target": "00001KVFD3YSV",
+      "note": "Inspection CLI should expose https host API grants/diagnostics.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    }
+  ]
+}
--- a/.yoi/tickets/00001KVFDX9AF/item.md
+++ b/.yoi/tickets/00001KVFDX9AF/item.md
@ -0,0 +1,96 @@
+---
+title: 'Plugin: implement https host API for Tool runtime'
+state: 'ready'
+created_at: '2026-06-19T07:53:13Z'
+updated_at: '2026-06-19T07:54:32Z'
+assignee: null
+readiness: 'implementation_ready'
+risk_flags: ['plugin', 'https', 'host-api', 'network', 'sandbox', 'secrets', 'permission-grants']
+---
+
+## Background
+
+Plugin Tool runtime は minimal WASM execution と permission grants まで実装済みだが、外部 HTTPS API を呼ぶ host API はまだ未実装である。
+
+この Ticket では、WASM Plugin Tool から明示 grant された outbound HTTPS request だけを実行できる `https` host API を追加する。これは Discord webhook / REST API など outbound integration の前提になる。ただし Service / Ingress / WebSocket / inbound HTTP はこの Ticket の対象外。
+
+用語は `web` ではなく `https` とする。
+
+## Requirements
+
+- WASM Plugin Tool runtime に `https` host API import を追加する。
+  - API 名・ABI は既存 `yoi-plugin-wasm-1` / host import 設計と整合させる。
+  - Plugin は ambient network access を持たず、host API 経由のみで HTTPS request できる。
+- HTTPS only とする。
+  - `http://` は reject。
+  - localhost / private / link-local / unix socket / file URL 等は reject。
+- Permission grants と統合する。
+  - manifest requested permissions の `host_api.https` を読む。
+  - config granted permissions と照合する。
+  - grant がない場合は fail closed。
+  - host / method / optional path prefix などの allowlist を表現できるようにする。
+- Request を bounded にする。
+  - method allowlist。
+  - request body size bound。
+  - header count / size bound。
+  - response body size bound。
+  - timeout。
+  - redirect policy。
+- Credentials は ambient env から読まない。
+  - header / auth は explicit config / secret ref 経由だけにする。
+  - diagnostics に secret-like header / token / body content を漏らさない。
+- Response は Tool result に安全に戻せる bounded structure にする。
+  - status code
+  - bounded headers if needed
+  - bounded body text / bytes policy
+  - truncated flag
+- Failure は structured Tool error にする。
+  - grant denied
+  - URL rejected
+  - private/local host rejected
+  - timeout
+  - response too large
+  - network error
+  - unsupported method
+- Plugin code / history / model context に hidden context injection しない。
+  - HTTPS response は Tool result として通常の tool history 経路に残す。
+
+## Acceptance criteria
+
+- Granted Plugin Tool can perform an allowed HTTPS request through host API.
+- Request without `host_api.https` grant fails closed before network access.
+- Disallowed host / method / URL scheme fails closed.
+- `http://`, localhost, private IP, link-local, and local/private host targets are rejected.
+- Timeout and response size bounds are enforced.
+- Request / response diagnostics are bounded and redact secret-like values.
+- No ambient env credentials or ambient network APIs are exposed to WASM.
+- Tool result path remains ordinary Tool result/history path.
+- Tests cover:
+  - allowed HTTPS request with grant
+  - missing grant denied
+  - disallowed host denied
+  - method denied
+  - http scheme denied
+  - private/local host denied
+  - timeout
+  - response truncation / size bound
+  - secret header redaction
+  - no network access without host API import/grant
+- Validation: focused plugin https tests, relevant cargo check/test, `cargo fmt --check`, `git diff --check`, and `nix build .#yoi` because dependency/package/network code may change.
+
+## Non-goals
+
+- `fs` host API implementation.
+- WebSocket / SSE / timer host APIs.
+- Service surface lifecycle.
+- Ingress surface.
+- Discord Gateway bridge.
+- Inbound HTTP server.
+- Plugin package manager / install/update.
+
+## Related work
+
+- `00001KV5W3PHW` — Plugin Tool execution with minimal WASM runtime.
+- `00001KV5W3PJ3` — Plugin permission grant enforcement.
+- `00001KVFD3YSV` — Plugin read-only CLI inspection list/show.
+- `00001KSXRQ4G8` — Plugin runtime / surface / minimal host API model design.
--- a/.yoi/tickets/00001KVFDX9AF/thread.md
+++ b/.yoi/tickets/00001KVFDX9AF/thread.md
@ -0,0 +1,7 @@
+<!-- event: create author: "yoi ticket" at: 2026-06-19T07:53:13Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---
--- a/.yoi/tickets/00001KVFDX9AY/artifacts/.gitkeep
+++ b/.yoi/tickets/00001KVFDX9AY/artifacts/.gitkeep
--- a/.yoi/tickets/00001KVFDX9AY/artifacts/relations.json
+++ b/.yoi/tickets/00001KVFDX9AY/artifacts/relations.json
@ -0,0 +1,37 @@
+{
+  "version": 1,
+  "relations": [
+    {
+      "ticket_id": "00001KVFDX9AY",
+      "kind": "depends_on",
+      "target": "00001KV5W3PHW",
+      "note": "fs host API is implemented inside the WASM Plugin Tool runtime.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    },
+    {
+      "ticket_id": "00001KVFDX9AY",
+      "kind": "depends_on",
+      "target": "00001KV5W3PJ3",
+      "note": "fs host API must be guarded by Plugin permission grants.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    },
+    {
+      "ticket_id": "00001KVFDX9AY",
+      "kind": "related",
+      "target": "00001KSXRQ4G8",
+      "note": "Uses established Plugin host API terminology.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    },
+    {
+      "ticket_id": "00001KVFDX9AY",
+      "kind": "related",
+      "target": "00001KVFD3YSV",
+      "note": "Inspection CLI should expose fs host API grants/diagnostics.",
+      "author": "yoi ticket",
+      "at": "2026-06-19T07:54:32Z"
+    }
+  ]
+}
--- a/.yoi/tickets/00001KVFDX9AY/item.md
+++ b/.yoi/tickets/00001KVFDX9AY/item.md
@ -0,0 +1,88 @@
+---
+title: 'Plugin: implement fs host API for Tool runtime'
+state: 'ready'
+created_at: '2026-06-19T07:53:13Z'
+updated_at: '2026-06-19T07:54:32Z'
+assignee: null
+readiness: 'implementation_ready'
+risk_flags: ['plugin', 'fs', 'host-api', 'sandbox', 'path-safety', 'permission-grants', 'file-mutation']
+---
+
+## Background
+
+Plugin Tool runtime は minimal WASM execution と permission grants まで実装済みだが、Plugin-layer scoped filesystem access はまだ未実装である。
+
+この Ticket では、WASM Plugin Tool から明示 grant された scoped paths のみを read/list/write できる `fs` host API を追加する。Plugin は Pod / workspace の filesystem authority を自動継承しない。Plugin-specific grant だけが有効な authority になる。
+
+## Requirements
+
+- WASM Plugin Tool runtime に `fs` host API import を追加する。
+  - API 名・ABI は既存 `yoi-plugin-wasm-1` / host import 設計と整合させる。
+  - Plugin は ambient filesystem access を持たず、host API 経由のみで fs operation できる。
+- Plugin-layer scoped paths を grant で表現する。
+  - read
+  - list
+  - write の初期 subset
+  - optional path root / glob / prefix policy は implementation-time に最小安全形を選ぶ。
+- Workspace filesystem scope を自動継承しない。
+  - Pod が workspace write authority を持っていても Plugin は grant なしでは読めない/書けない。
+- Path safety を徹底する。
+  - normalization
+  - `..` traversal reject
+  - symlink/root escape reject
+  - absolute/relative path policy を明確化
+  - allowed root 外は fail closed
+- Bounds を設ける。
+  - read size bound
+  - write size bound
+  - directory entry count bound
+  - path length bound
+  - diagnostic size bound
+- Writes は既存 file mutation safety と整合させる。
+  - normalized target file ごとの serialization / atomic-ish behavior を検討する。
+  - broad Worker scheduler は追加しない。
+- Diagnostics は safe にする。
+  - file content を error/log に漏らさない。
+  - rejected path は必要最小限にする。
+- Tool result path は通常 Tool result/history 経路を使う。
+  - hidden context injection しない。
+
+## Acceptance criteria
+
+- Granted Plugin Tool can read an allowed file through `fs` host API.
+- Granted Plugin Tool can list an allowed directory within bounds.
+- Granted Plugin Tool can write an allowed file within bounds.
+- Plugin without matching `host_api.fs` grant cannot read/list/write.
+- Workspace write authority is not inherited by Plugin without Plugin grant.
+- `../` traversal, symlink escape, and allowed-root escape are rejected.
+- Oversize read/write/list results fail closed or truncate according to explicit policy.
+- File mutation safety does not race unsafely with existing Write/Edit semantics.
+- Diagnostics do not include file content or secret-like data.
+- Tests cover:
+  - allowed read
+  - allowed list
+  - allowed write
+  - missing grant denied
+  - workspace authority not inherited
+  - path traversal rejected
+  - symlink/root escape rejected
+  - read/write/list bounds
+  - diagnostics redaction
+  - write serialization or safe conflict behavior
+- Validation: focused plugin fs tests, relevant cargo check/test, `cargo fmt --check`, `git diff --check`, and `nix build .#yoi` because host API / packaging behavior may change.
+
+## Non-goals
+
+- `https` host API implementation.
+- General workspace Read/Write tool delegation.
+- Service / Ingress surface.
+- File watcher / background sync.
+- Broad WASI filesystem exposure.
+- Plugin package manager / install/update.
+
+## Related work
+
+- `00001KV5W3PHW` — Plugin Tool execution with minimal WASM runtime.
+- `00001KV5W3PJ3` — Plugin permission grant enforcement.
+- `00001KVFD3YSV` — Plugin read-only CLI inspection list/show.
+- `00001KSXRQ4G8` — Plugin runtime / surface / minimal host API model design.
--- a/.yoi/tickets/00001KVFDX9AY/thread.md
+++ b/.yoi/tickets/00001KVFDX9AY/thread.md
@ -0,0 +1,7 @@
+<!-- event: create author: "yoi ticket" at: 2026-06-19T07:53:13Z -->
+
+## 作成
+
+LocalTicketBackend によって作成されました。
+
+---