159 lines
9.8 KiB
Markdown
159 lines
9.8 KiB
Markdown
---
|
|
title: 'Abstract Workspace Worker runtime spawn operations'
|
|
state: 'inprogress'
|
|
created_at: '2026-06-23T16:34:39Z'
|
|
updated_at: '2026-06-23T19:31:58Z'
|
|
assignee: null
|
|
queued_by: 'workspace-panel'
|
|
queued_at: '2026-06-23T19:25:09Z'
|
|
---
|
|
|
|
## 背景
|
|
|
|
Workspace web / Workspace backend から Worker を起動・停止・操作する UI/API を作るには、現在 read-only live view として実装されている runtime bridge を、Worker 操作も扱える backend abstraction に拡張する必要がある。
|
|
|
|
現状:
|
|
|
|
- `crates/workspace-server/src/hosts.rs` の `LocalRuntimeBridge` は local runtime metadata を読んで `HostSummary` / `WorkerSummary` を返す read-only bridge である。
|
|
- `/api/hosts`、`/api/workers`、`/api/hosts/{host_id}/workers` はこの bridge を直接使っている。
|
|
- Worker 起動の最終境界は `yoi pod [POD_OPTIONS]` process launch である。
|
|
- 既存の `client::spawn::SpawnConfig` は `yoi pod` 起動 options の typed 表現に近いが、`ticket_role` のような Ticket/Orchestration domain の情報も混ざっている。
|
|
- Workspace backend には Worker spawn / stop / protocol proxy の抽象境界がまだない。
|
|
- Worker 起動を web backend から実装する際、workspace root / cwd / pod name / profile / role-session claim の経路が TUI とズレると、Panel 表示や workspace 所属判定が壊れる。
|
|
|
|
この Ticket では、Workspace backend から Worker spawn 操作を実装する前段として、**Pod process 起動境界**と**Ticket / Orchestration intent 境界**を分離して整理する。低レベル起動は Ticket system を知らず、Ticket/Orchestration 情報は上位 resolver / launch policy が低レベル config へ落とす。
|
|
|
|
## 要件
|
|
|
|
### Layering / responsibility split
|
|
|
|
起動系は少なくとも以下の層に分ける。
|
|
|
|
1. **Pod process launch layer**
|
|
- `yoi pod [POD_OPTIONS]` を起動する唯一の低レベル境界。
|
|
- Ticket / Orchestration / Role / TicketId を直接知らない。
|
|
- `workspace_root`、`pod_name`、`profile`、`manifest`、`project`、`store`、`cwd`、`initial_input`、`workflow`、`require_pod_state` のような process 起動 options だけを扱う。
|
|
2. **Worker runtime layer**
|
|
- Workspace backend / API から見える Worker 操作境界。
|
|
- hosts/workers live view、worker lookup、spawn/stop/protocol proxy の entrypoint を持つ。
|
|
- API intent を低レベル Pod process launch config へ解決する。
|
|
3. **Ticket / Orchestration resolver layer**
|
|
- Ticket ID、Ticket role、Orchestrator/Coder/Reviewer といった workflow domain を扱う。
|
|
- Role/Profile/Workflow/Ticket context を解決し、低レベル Pod process launch config と必要な launch policy / prompt input を作る。
|
|
- Ticket/Orchestration 情報を低レベル launcher に直接漏らさない。
|
|
|
|
### Pod process launch abstraction
|
|
|
|
- `SpawnConfig` をそのまま Workspace backend API の入力として扱わない。
|
|
- 低レベルの起動 config は Ticket/Orchestration domain を持たない形に整理する。
|
|
- 既存 `SpawnConfig` を改名/分割するか、別の `PodProcessLaunchConfig` / `PodLaunchOptions` を導入する。
|
|
- `ticket_role` は低レベル process config から分離する。
|
|
- 必要なら `PodLaunchPolicy` / `ProfileLaunchPolicy` のような別引数/別 layer に移す。
|
|
- `--ticket-role` は現状 hidden CLI marker として存在してよいが、汎用 `yoi pod` 起動 config の概念には含めない。
|
|
- 低レベル launcher は `Command::new("yoi")` 相当の process 起動と acceptance evidence 取得に責務を限定する。
|
|
- TUI/Panel、SpawnPod tool、Workspace backend はこの低レベル launcher を共有できるようにする。
|
|
|
|
### Worker runtime abstraction
|
|
|
|
- `LocalRuntimeBridge` 相当の read-only live view を、Worker 操作用の抽象境界へ整理する。
|
|
- trait 名は実装時に決めてよいが、概念としては `WorkerRuntime` / `WorkspaceWorkerRuntime` / `HostRuntime` のような境界を作る。
|
|
- 最低限、以下の責務を同じ abstraction から扱えるようにする。
|
|
- hosts list
|
|
- workers list
|
|
- worker detail / lookup
|
|
- worker spawn request
|
|
- worker stop request
|
|
- 将来の protocol method proxy / event stream の接続点
|
|
- v0 では local implementation のみでよい。
|
|
- 例: `LocalPodRuntime` / `LocalWorkspaceRuntime`。
|
|
- 将来 Host protocol / remote worker backend を差し替えられるよう、Workspace API handler が concrete local implementation に密結合しすぎない形にする。
|
|
|
|
### Spawn operation abstraction
|
|
|
|
- Backend API から Worker を起動するための typed request / result を設計する。
|
|
- Browser から `workspace_root` / `cwd` / executable path / raw profile selector を自由入力させない。
|
|
- Frontend/API request は intent を中心にする。
|
|
- 例: generic worker profile launch、orchestrator start、ticket coder/reviewer start。
|
|
- ticket_id が必要な operation は path または typed field から受ける。
|
|
- Backend / resolver が以下を解決する。
|
|
- canonical workspace root
|
|
- process cwd
|
|
- pod name
|
|
- profile / manifest / project
|
|
- initial input / workflow
|
|
- optional launch policy
|
|
- role-session claim
|
|
- Orchestrator の dedicated worktree 起動では、runtime workspace identity と cwd を混同しない。
|
|
- `workspace_root` は original/main workspace
|
|
- `cwd` は orchestration worktree
|
|
- Coder / Reviewer / Orchestrator の Ticket-specific 起動経路は、低レベル Pod process launch config を生成する上位 resolver として扱う。
|
|
- Workspace backend が独自に `Command::new("yoi")` を組み立てて挙動を分岐させない。
|
|
|
|
### Ticket / Orchestration information boundary
|
|
|
|
- Ticket ID、Ticket role、Orchestration role は低レベル `PodProcessLaunchConfig` に入れない。
|
|
- Ticket/Orchestration resolver は以下を出力する。
|
|
- low-level Pod process launch config
|
|
- optional profile/launch policy
|
|
- role-session claim metadata
|
|
- model-visible initial input / workflow selection
|
|
- Role は Profile と同一視しない。
|
|
- Role は workflow 上の責務。
|
|
- Profile は Pod recipe。
|
|
- Role/Profile/Ticket の対応は上位 resolver の責務であり、低レベル launcher の責務ではない。
|
|
- Role を使わない generic Worker 起動では Ticket/Orchestration 情報を一切要求しない。
|
|
|
|
### API surface planning
|
|
|
|
- 実装する API はこの Ticket で確定しなくてもよいが、初期案として以下を検討する。
|
|
- generic: `POST /api/workers/spawn`
|
|
- operation: `POST /api/workers/{worker_id}/stop`
|
|
- orchestration: `POST /api/orchestrator/start`
|
|
- ticket-specific: `POST /api/tickets/{ticket_id}/workers`
|
|
- 起動 operation は HTTP command として扱う。
|
|
- 状態観測 / stream / transcript は後続 Ticket で SSE/WebSocket を検討する。
|
|
- spawn success は process start だけでなく、socket/connect/snapshot 等の acceptance evidence を持つこと。
|
|
|
|
### Role-session / Panel integration
|
|
|
|
- Backend spawn でも Panel が Worker を見つけられるようにする。
|
|
- 起動成功後に必要な local role-session claim を作る、または既存 helper を共有する。
|
|
- Runtime registry、Pod metadata、role-session registry のどれを authority / hint として扱うかを明確にする。
|
|
- stale/missing/already-running の扱いを typed error として返す。
|
|
|
|
### Safety / authority boundary
|
|
|
|
- Browser は local Unix socket path や runtime registry path を直接知らない。
|
|
- Backend が worker identity を解決し、対象 Worker が current Workspace から見えることを確認する。
|
|
- user permission model はこの Ticket の scope 外だが、将来挟める場所を backend abstraction に残す。
|
|
- Raw Pod protocol を browser から受ける場合でも、backend が最低限の method allow/block を挟める構造にする。
|
|
|
|
## Non-goals
|
|
|
|
- Worker operation UI の完成。
|
|
- WebSocket/SSE event stream の完成。
|
|
- Full permission / user auth model の設計。
|
|
- Remote Host protocol implementation。
|
|
- Pod protocol TypeScript 型生成の実装。
|
|
- Workspace identity `.yoi/workspace.toml` 実装。
|
|
- StopPod / registry locking の追加修正。
|
|
- Ticket/Orchestration domain を廃止すること。
|
|
- `--ticket-role` hidden CLI marker の即時削除。
|
|
|
|
## 受け入れ条件
|
|
|
|
この Ticket は planning から開始する。ready に進める前に以下を満たす。
|
|
|
|
- Workspace backend runtime abstraction の責務境界が明文化されている。
|
|
- `yoi pod [POD_OPTIONS]` process launch 境界と Ticket/Orchestration resolver 境界が分離されている。
|
|
- 低レベル Pod process launch config が Ticket ID / Ticket role / Orchestration role を直接持たない方針が明記されている。
|
|
- 既存 `SpawnConfig` の `ticket_role` をどう分離するかが決まっている。
|
|
- 現在の `LocalRuntimeBridge` をどう trait / service に置き換えるかが決まっている。
|
|
- Worker spawn request / result の typed shape が設計されている。
|
|
- Orchestrator / Coder / Reviewer の起動時に `workspace_root` と `cwd` をどう決めるかが明記されている。
|
|
- TUI/Panel、SpawnPod tool、Workspace backend が低レベル Pod process launcher を共有する方針が明記されている。
|
|
- Ticket/Orchestration resolver が低レベル launch config・launch policy・role-session claim を生成する方針が明記されている。
|
|
- Backend API endpoint の初期案が整理されている。
|
|
- role-session claim / Pod metadata / runtime registry との連携方針が明記されている。
|
|
- 実装まで含める場合は `cargo test -p yoi-workspace-server`、`cargo check -p yoi`、`cd web/workspace && deno task check && deno task build`、`git diff --check`、`nix build .#yoi --no-link` が通る。
|