Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity
3c2fd5d760
yoi/.yoi/tickets/00001KVTNAY20/item.md

9.7 KiB
Raw Blame History

title state created_at updated_at assignee
Abstract Workspace Worker runtime spawn operations planning 2026-06-23T16:34:39Z 2026-06-23T16:50:00Z null

背景

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 が通る。