---
title: '組み込み/ネットワーク対応Worker Runtime crateを作る'
state: 'planning'
created_at: '2026-06-25T12:17:05Z'
updated_at: '2026-06-25T13:43:31Z'
assignee: null
---

## 背景

Yoi は現在、Worker 的な実行単位を主に `yoi pod` process / Unix socket / pod metadata / session jsonl として扱っている。一方で今後は、Companion や routing-only Orchestrator を Backend process 内に組み込んだ Runtime 上の Worker として動かし、Coder / Reviewer などは local / remote host 上の Runtime process で動かしたい。

このため、Backend が持つ `RuntimeRegistry` や Workspace API の都合ではなく、**Worker を動かす環境そのものとしての Runtime** を独立した crate / library API として定義する必要がある。`RuntimeRegistry` は Backend が embedded Runtime と remote Runtime をまとめて同じようにアクセスするための集約境界であり、Runtime 自体の実装主体ではない。

この Ticket では、まず要件だけを整理する。実装前に、現在の `pod`、`llm-worker`、Panel / Workspace backend における Pod / Worker 扱いを調査し、既存構造から Runtime crate へ移すべき責務と adapter として残すべき責務を把握する。

## 要件

### Runtime crate の位置付け

- `crates/worker-runtime` を Worker を動かす実行環境の正体として設計する。
- `worker-runtime/lib.rs` は Backend などに組み込める embeddable Runtime API を公開する。
- `worker-runtime/main.rs` は同じ Runtime を network API で公開する Runtime process を起動する。
- Runtime process と embedded Runtime は Worker semantics を二重実装しない。
  - Worker lifecycle / input / output / event / transcript projection は lib 側を正とする。
  - main binary は config / API server / transport / shutdown wrapper に留める。

### Runtime / Worker model

- Runtime は Worker を動かす環境であり、trait object ではなく domain entity / concrete runtime implementation として扱う。
- Runtime は複数 Worker を保持・起動・停止・操作できる。
- Worker identity は Runtime scoped とする。
  - `runtime_id`
  - `worker_id`
  - UI 用 `display_name` / `display_ref`
- Browser / API / Backend は `runtime_id + worker_id` を authority とし、`pod_name` / socket path / session path を authority にしない。
- Runtime は capability / status / diagnostics を返す。
  - backend internal
  - local process capable
  - future remote host capable
  - filesystem / shell / git / worktree capability
  - tools availability

### Embeddable Runtime API

- Backend は `Runtime` を process 内に直接組み込める。
- Embedded Runtime は tools なし Companion のような Worker を local process / socket なしで動かせる。
- API は少なくとも以下の操作を表現できる。
  - runtime summary / status
  - worker list / detail
  - create worker
  - send input
  - stop / cancel worker
  - bounded transcript projection
  - event subscription または event cursor
  - usage / overview projection
- v0 は single-flight / busy reject でよい。
- raw provider trace / raw session full log を Backend durable authority にしない。

### Networked Runtime process API

- `worker-runtime/main.rs` は Runtime を network API として公開する。
- 将来、別ホストの Runtime process に Backend が接続し、remote Worker を local / internal Worker と同じ概念で扱えるようにする。
- Network API は command と observation を分ける。
  - command: create / input / stop / cancel
  - observation: worker status / transcript projection / events
- v0 transport は実装時に選ぶが、HTTP command + SSE/WebSocket event stream を想定可能な shape にする。
- Browser が remote Runtime へ直接 authority-bearing request を送るのではなく、Backend registry / policy 経由にする。

### Backend RuntimeRegistry との関係

- Workspace backend の `RuntimeRegistry` は、embedded Runtime と remote Runtime client をまとめる集約境界とする。
- Registry は Worker を実行しない。
- Registry は runtime lookup / policy / visibility / API projection / current workspace filtering を担う。
- Backend internal Companion は embedded Runtime に載る Worker として扱う。
- Existing local Pod / process-based Worker は Runtime の adapter または移行対象として扱う。

### Existing Worker / LLM engine migration boundary

- `llm-worker` は先に `llm-engine` へ改名し、LLM turn engine と実行単位としての Worker を名前上分離する。
- 既存 `pod` crate は先に `worker` crate へ rename し、single Worker host として扱う。
- 既存 `yoi pod` process は当面 compatibility / process-backed Worker adapter として扱えるようにする。
- 最終的には process boundary を Worker ではなく Runtime に寄せる。
  - Runtime process が複数 Worker を保持できる。
  - Worker ごとに subprocess を持つかどうかは Runtime implementation detail とする。
- `llm-engine` の provider streaming / tool execution / history integration のうち、Runtime crate に移すべきものと Worker-specific に残すものを調査して整理する。
- `worker` crate の Unix socket protocol / metadata / session persistence / TUI attach semantics は、Runtime API との対応を調査してから移行方針を決める。

### Pod-named store / registry migration boundary

- `pod-store` / `pod-registry` は standalone crate として rename せず、`worker-runtime` 作成時に Runtime 内部 module へ直接統合する。
- `pod-store` 相当は Runtime 内部の Worker metadata / transcript projection / config snapshot persistence module とする。
- `pod-registry` 相当は Backend RuntimeRegistry ではなく、Runtime 内部の live Worker allocation / scope conflict / stale reclaim module とする。
- Backend `RuntimeRegistry` は embedded / remote Runtime を束ねる集約境界であり、Worker store / live allocation authority を直接持たない。
- 後方互換 alias / standalone `worker-store` / standalone `worker-registry` / old crate compatibility / old on-disk migration は設けない。

### Safety / authority

- Runtime API は raw socket path / session path / local metadata path を公開 API authority にしない。
- Worker tool authority は Runtime / Worker config / explicit grant で決める。
- Backend internal Companion v0 は filesystem / shell / git / Ticket mutation tools を持たない。
- Remote Runtime との接続では将来 auth / permission / network safety を挟める境界を残す。

## 調査事項

実装前に以下を調査する。

- `crates/pod` が現在担っている責務。
  - process entrypoint
  - socket protocol
  - session persistence
  - metadata / runtime dir
  - in-flight snapshot / attach behavior
  - tool registry / workflow / profile integration
- `crates/llm-worker` が現在担っている責務。
  - provider request / streaming
  - history / callback / tool-call loop
  - reasoning / usage / continuation / retry
  - Worker として再利用できる boundary
- Panel / TUI / Workspace backend が現在 Pod をどう扱っているか。
  - Companion send path
  - Worker/host list API
  - Pod metadata reader
  - spawn / stop / attach / event handling
- Existing `client` crate の process spawn / PodClient / socket protocol を Runtime adapter でどう扱うか。

## Non-goals

- Backend internal Companion Web Console の完成。
- Remote Runtime protocol の完成。
- Existing Pod process model の即時削除。
- Full session storage migration。
- Full tool authority redesign。
- Multi-user auth / permission model の完成。

## 受け入れ条件

この Ticket は要件整理と現状把握から開始する。ready に進める前に以下を満たす。

- `worker-runtime/lib.rs` と `worker-runtime/main.rs` の責務境界が整理されている。
- Runtime / Worker / RuntimeRegistry / Backend service の責務境界が整理されている。
- Runtime は Worker を動かす環境、Registry は Backend の集約境界であることが明確になっている。
- Embedded Runtime と networked Runtime process が同じ Runtime API に基づく方針が整理されている。
- Existing `worker` / `llm-engine` / Panel / Workspace backend の Worker 扱いの調査結果が記録されている。
- `pod-store` / `pod-registry` は standalone rename を挟まず、`worker-runtime` 内部 module へ直接統合する方針が整理されている。
- Backend `RuntimeRegistry` と Runtime internal store / allocation registry の責務境界が整理されている。
- 既存 Worker process model から Runtime model へ移行するための初期 implementation split が提案されている。