path: root/doc/Specifications.md

# AI Agent Sandbox MCP Server — 仕様書

**文書名:** `Specifications.md`  
**版:** 0.2 Audit Revision
**対象OS:** Windows 11 x64  
**主実装:** C# / .NET 10 LTS  
**目的:** 実装前に、外部から観測可能な性質・制約・安全条件を一意に定義する。

---

## 1. 文書の位置付け

### 1.1 仕様と設計の分離

本書は「システムが何を満たすか」を定義する。実現手段、モジュール構成、Win32 APIの使い方などは `Design.md` に定義する。
IPA「厳密な仕様記述入門」の考え方に従い、課題・仕様・設計を分離し、仕様は設計より上位の性質として扱う。

| 文書 | 責務 | 主な読者 |
| --- | --- | --- |
| Specifications.md | 外部性質、機能、状態、制約、非機能、安全条件を定義 | 利用者、レビュー担当、実装担当 |
| Design.md | 仕様を満たすための構造、データ、アルゴリズム、Windows強制方式を定義 | 実装担当、Codex、保守担当 |

### 1.2 記述規則

- **MUST / 必須**: 実装が必ず満たす。
- **MUST NOT / 禁止**: 実装が行ってはならない。
- **SHOULD / 推奨**: 原則として満たす。逸脱時は根拠を記録する。
- **MAY / 任意**: 実装上の選択肢である。
- 同一概念には必ず同一の用語を使用する。類義語を新しい概念として導入しない。

### 1.3 仕様品質の観点

本書は、完全性、一貫性、検証容易性、修正容易性、追跡性を重視する。妥当性確認は「この仕様がAIエージェントの安全な作業実行という目的に適合するか」、正当性検証は「設計・実装が本仕様を満たすか」と定義する。

---

## 2. 目的・課題・範囲

### 2.1 解くべき課題

外部AIエージェントから自然言語で作業依頼を受け、ローカルLLMで計画・判断し、Windows上で許可された操作だけを実行し、結果をテキストで返す。LLMの判断をセキュリティ境界として信用せず、OSとアプリケーションのポリシーで能力を制限する。

### 2.2 システム境界

| 境界内 | 境界外 |
| --- | --- |
| MCP Server、Agent Runtime、Ollama制御、Planner、Session、Skill、Policy Engine、Sandbox Broker、監査 | Ollamaサーバ本体、MCP Client、利用対象リポジトリ、外部ネットワーク |
| Windows上の一時ACL/WFP/Job/AppContainer利用 | OS自体の完全仮想化、Hyper-V、WSL、Docker |

### 2.3 v1の非対象

- Legacy HTTP+SSE transportの後方互換対応。
- WebSocketや独自TCP等の独自MCP transport。
- 外部ネットワークからのStreamable HTTP接続。
- Streamable HTTPのアプリ内TLS終端・HTTP認証。
- SandboxPolicyのMCP経由での変更。
- 固定System PromptのMCP/CLI/設定からの置換。
- Hot Reload。
- 永続Sessionデータベース。
- WSL、Docker、VMを安全境界として利用すること。
- Credential Manager、SSH key、API token等のSandboxへの継承。

---

## 3. 用語

| 用語 | 定義 |
| --- | --- |
| MCP Client | 本システムをMCP Serverとして呼び出す外部AIエージェントまたはホスト。 |
| MCP Tool | MCP Clientに公開する `agent_run` と `agent_status`。 |
| Agent | Ollama、Planner、Internal Toolを用いてTaskを遂行する内部実行主体。 |
| Agent Runtime | Agent Loop、Session、Ollama呼出し、Internal Tool調停を行う中核。 |
| Internal Tool | Ollamaのnative tool callingにだけ公開され、MCP Clientには公開されない内部操作。 |
| Task | 依頼を分割した意味的な作業単位。 |
| TaskGraph | Taskとdependencyから成る有向非巡回グラフ。 |
| Token PERT | TaskのLLM消費量をO/M/Pのtoken値で推定するPERT派生モデル。 |
| Token CPM | TaskGraph上でexpected token costを重みとしてcritical pathを求めるモデル。 |
| Token Budget Class | 1K～128KのTask単位token予算階級。Ollama `num_ctx`とは別概念。 |
| Session | 会話、TaskGraph、Execution Resultをメモリ上に保持する論理単位。 |
| User Sandbox Configuration | Workspace、Mount、Execution、Network、Resourceを利用者の意図で表すsemantic設定。 |
| Sandbox Environment Resolution | Logical Path、Executable Alias、Runtime等をHost上のResolved Pathへ解決する処理。 |
| Effective Sandbox Policy | ResolutionとExecutable Approvalの結果から生成され、Policy Engineが使用する解決済みホワイトリスト。従来のSandboxPolicyはこの意味でのみ使用する。 |
| Sandbox | Effective Sandbox PolicyをWindows機構で強制したExecution Environment。 |
| Sandbox Broker | プロセス起動・許可判定・Windows強制機構の調停を担当する信頼境界。 |
| Application Profile | アプリケーション固定のLess Privileged AppContainer (LPAC) profile。Taskごとには作成・削除しない。 |
| Task Resource | Task中だけ存在するACL、WFP filter、Job Object、一時ファイル等。 |
| Executable | Windows上でProcessとして起動可能な実行対象。Internal Toolとは区別する。 |
| Executable Alias | 利用者がHost Executableを指定する人間向け名称。Alias解決だけではApprovalにならない。 |
| Approved Entry Executable | BrokerがEntry Processとして直接起動できる、Executable Approval済みHost Executable。 |
| Executable Approval | Entry ExecutableのResolved PathとSHA-256を人間が信頼対象として登録する操作。 |
| Runtime / Runtime Root / Runtime Component | Entry Executableの動作に必要な実行環境、そのFilesystem root、その配下のExecutable/resource。 |
| Workspace Artifact | development Workspace内で生成または配置され、Host Executable ApprovalなしでSandbox Entry Processとして起動できる実行物。 |
| Shell | command interpreterとして動作するExecutable category。 |
| Sandbox Process Tree | Brokerが起動したEntry Processと、同じconfinementを継承する全Descendant Process。 |
| Logical Path / Resolved Path | 利用者が指定したpathと、reparse resolution後にPolicy評価へ使用する実体path。 |
| Fixed System Prompt | 実行ファイルに組み込まれ、利用者が変更できない最上位指示。 |
| User System Prompt | 設定で指定可能だがFixed System Promptを上書きできない追加指示。 |
| Skill | LLMへの補助指示を記述したMarkdown。実行権限そのものを与えない。 |
| Locale | BCP 47形式を推奨する言語識別子。標準は `en` と `ja`。 |
| Audit Log | セキュリティに関係する操作を通常ログと分離して記録する監査記録。 |
| Recovery Journal | Task Resourceの適用・解除を復旧可能にする永続的な最小ジャーナル。 |

---

## 4. 利用者と主要利用シナリオ

| ID | 主体 | シナリオ | 成功条件 |
| --- | --- | --- | --- |
| UC-01 | MCP Client | 自然言語の依頼を送信する | Task IDとSession IDを受領する |
| UC-02 | MCP Client | Task状態を照会する | 状態と、完了時には最終回答をテキストで得る |
| UC-03 | 利用者 | 画像付き依頼を送信する | Vision対応modelなら処理される |
| UC-04 | 利用者 | 言語を指定して起動する | CLI/診断/MCP応答/LLM最終回答が指定言語になる |
| UC-05 | 利用者 | User Sandbox Configurationを適用する | YAML全体の解決・Executable identity・権限差分を一度確認し、原子的に適用できる |
| UC-06 | 利用者 | 適用状態を確認する | YAML、Resolved Path、Executable hash、Effective Sandbox Policy、Platform状態を一つの表で確認できる |
| UC-07 | Agent | 計画を作成・更新する | TaskGraphがDAGを維持しToken CPMを再計算する |
| UC-08 | Agent | Internal Toolを呼ぶ | Policy検査後にのみ副作用が発生する |
| UC-09 | システム | 異常終了から復旧する | 残留Task Resourceを除去してから受付開始する |

---

## 5. 外部インターフェース仕様

### 5.1 MCP Transport

| ID | Transport | 要件 |
| --- | --- | --- |
| MCP-TR-01 | stdio | MUST対応。既定transportとする。 |
| MCP-TR-02 | Streamable HTTP | MUST対応。loopbackのみlisten可能とする。 |
| MCP-TR-03 | Legacy HTTP+SSE | MUST NOT対応。後方互換fallbackも実装しない。 |
| MCP-TR-04 | Streamable HTTP SSE stream | v1では提供しない。GETによるevent streamは提供しない。 |
| MCP-TR-05 | 独自transport | MUST NOT実装。 |

### 5.2 MCP Tool

| Tool | 用途 | 処理モデル | 返却 |
| --- | --- | --- | --- |
| agent_run | 新規または既存Sessionに依頼を登録 | 非同期 | Task ID、Session IDを含むテキスト |
| agent_status | Task状態を取得 | 同期照会 | 状態、進捗要約、完了時最終回答を含むテキスト |

### 5.3 agent_run入力要件

| ID | 項目 | 必須 | 要件 |
| --- | --- | --- | --- |
| MCP-RUN-01 | request | Yes | 空でないUTF-8テキスト。主I/F。 |
| MCP-RUN-02 | session_id | No | 指定時は存在するSessionへ継続。未指定時は新規Session。 |
| MCP-RUN-03 | temperature | No | 当該TaskのOllama呼出しにのみ適用する一時override。設定を書き換えない。 |
| MCP-RUN-04 | images | No | 画像0件以上。Vision対応model利用時のみ処理。 |
| MCP-RUN-05 | その他LLM設定 | No | model、system prompt、context等をMCPから変更してはならない。 |

### 5.4 agent_status入力要件

| ID | 項目 | 必須 | 要件 |
| --- | --- | --- | --- |
| MCP-STS-01 | task_id | Yes | agent_runが返したTask ID。 |
| MCP-STS-02 | session_id | No | 指定時はTaskとの整合を検査する。 |

`agent_status` のtext resultは既存のTask/Session ID、状態、進捗、token実績、最終結果に加え、実行iteration数、再計画回数、最後のerror codeと選択localeのerror messageを返す。内部Tool名、Sandbox実装詳細、chain-of-thoughtは返してはならない。

### 5.5 Task状態

| 状態 | 意味 | 遷移先 |
| --- | --- | --- |
| queued | 受付済み、未開始 | planning / cancelled / failed |
| planning | TaskGraph作成・更新中 | running / failed |
| running | Internal ToolまたはLLM処理中 | planning / completed / failed / cancelled |
| completed | TaskGraph全ノード完了 | 終端 |
| failed | 回復不能な失敗 | 終端 |
| cancelled | 安全停止完了 | 終端 |

### 5.5.1 v1実行並列性

- 複数Taskを `queued` として同時に受け付けることができる。
- アプリケーション全体で `planning` または `running` になれるTaskは最大1件とする。
- Task Resourceを適用できるTaskも同時に最大1件とする。
- `agent_run` の非同期受付は維持し、実行待ちTaskは受付順の単一キューで処理する。

### 5.6 CLI

schema version 2のCLI surfaceは次に限定する。

```text
agent-mcp [<config-path>]
agent-mcp apply [<config-path>] [--yes]
agent-mcp show [<config-path>]
```

command省略時はYAMLの`mcp.transport`と`application.language`を使用してMCP Serverを起動する。config path省略時は実行ファイルと同じdirectoryの`agent.yaml`を使用する。CLIからYAML値を上書きしてはならない。

`apply`はbase/local merge後のYAML全体、Workspace、Mount、Execution Entry、Network、Resourceを解決し、ExecutableのResolved PathとSHA-256を含む権限差分を一度だけ表示する。全検証成功後、利用者が承認した場合だけconfig別Applied Configuration Storeをatomic replaceする。途中失敗時は以前の適用状態を維持する。`--yes`は非対話適用だけに使用でき、Auditへ記録する。

`show`はread-onlyとし、desired/resolved/applied/effectiveの状態とFilesystem/Execution/Network/Resource権限マトリックスを一つのtext表示で返す。WFP filter追加削除を伴う完全なPlatform preflightは起動時に必ず実施する。MCP ClientおよびLLMから`apply`を呼び出せない。

旧`serve`、`check`、`executable *`、`sandbox *`、`--config`、`--lang`、`--transport`、`--path`、`--runtime-root`、`--no-runtime`、`--format`は受け付けず、schema version 2の移行診断を返す。

### 5.7 MCP 2026-07-28とTasks Extension

| ID | 要件 |
| --- | --- |
| MCP-2026-01 | HTTPの主経路はMCP `2026-07-28`とし、`server/discover`およびrequest単位の必須`_meta`を処理する。 |
| MCP-2026-02 | HTTPはstatelessとし、`Mcp-Session-Id`を発行・要求しない。既存`session_id`はAgent会話IDでありtransport sessionではない。 |
| MCP-2026-03 | 旧initialize clientは公式SDKのdual-era fallbackで受け付けるが、Legacy HTTP+SSE endpointは提供しない。 |
| MCP-2026-04 | `io.modelcontextprotocol/tasks`を公式Extensionとして宣言する。対応clientの`agent_run`はTask result、非対応clientは従来のqueued textを受け取る。 |
| MCP-2026-05 | MCP Task IDとAgent Task IDは同一UUIDで相関し、`tasks/get`と`agent_status`のどちらからも同じ作業を追跡可能にする。 |
| MCP-2026-06 | Agentの`queued/planning/running`はMCP `working`へ、terminal状態は対応するTask terminal状態へ写像する。 |
| MCP-2026-07 | MCP Taskは設定可能なTTL/poll intervalを持ち、process restart後の未完了Taskは`failed/server_restarted`へ確定する。実行は再開しない。 |

### 5.8 起動・HTTP観測性

- command省略のServer起動はbind前に管理者権限、BFE、WFP transaction、filter add/deleteを検査し、不足時は具体的なerrorと対処をstderrへ出してexit code 2で終了しなければならない。
- ready messageは実際のtransport開始後だけ出力し、HTTPではendpoint/protocol/stateless/PID/log path、stdioではprotocol/PID/log pathを含める。
- HTTP request logは実socketのremote/local endpoint、method、path、status、duration、標準MCP routing headerを記録可能とする。
- `Authorization`、`Cookie`、query、body、prompt、画像、Base64をrequest logへ記録してはならず、`X-Forwarded-For`を接続元として信用してはならない。

---

## 6. Ollama機能仕様

| ID | 対象 | 仕様 |
| --- | --- | --- |
| OLL-01 | Backend | LLM backendはOllamaのみに限定する。 |
| OLL-02 | API | 会話とtool callingはOllama Chat APIを使用可能とする。 |
| OLL-03 | Options | Ollamaが提供する生成optionを設定ファイルから変更可能にする。 |
| OLL-04 | Typed Options | 既知optionは型付きで検証する。 |
| OLL-05 | Extra Options | 将来追加optionのため `extra_options` を許可する。既知optionとの競合は既知optionを優先する。 |
| OLL-06 | Temperature | 設定値を既定とし、agent_runのoptional値だけTask scopeで上書き可能。 |
| OLL-07 | Model | MCPから変更不可。 |
| OLL-08 | System Prompt | MCPから変更不可。Fixed System Promptは設定からも変更不可。 |
| OLL-09 | Vision | MCPから画像をoptional入力可能。非対応modelではlocalized error。 |
| OLL-10 | Tool Calling | Internal ToolにOllama native tool callingを使用する。 |
| OLL-11 | Tool Guard | 実行が必要なTaskでtool callが行われない場合、未実行を検出して再試行する。 |
| OLL-12 | Retry | Ollama通信失敗は既定3回まで再試行する。 |
| OLL-13 | Usage | `prompt_eval_count` と `eval_count` をTask実測tokenとして記録する。 |
| OLL-14 | Thinking | `think`はOllama native Chat APIのbooleanまたは対応levelを使用する。推論過程と最終回答を分離し、推論本文を利用者向け結果・Conversation・Execution Result・Logへ出力しない。tool call継続に必要なassistant message内でのみOllamaへ返送する。 |

Vision入力は設定可能な画像数、1画像あたりのsize、request合計sizeの上限を持ち、上限超過をOllama呼出し前に拒否しなければならない。具体的な既定値は設計および設定schemaで定義する。

---

## 7. Agent Runtime仕様

### 7.1 Agent Loop

| ID | 要件 |
| --- | --- |
| AGT-01 | 正常終了条件はTaskGraphの全Taskがcompletedであること。 |
| AGT-02 | 既定 `max_iterations` は128。超過時はfailed。 |
| AGT-03 | 同一原因と判定した失敗が5回連続した場合はfailed。 |
| AGT-04 | Taskが外部操作を必要とする場合、LLMの文章上の「実施した」という主張だけを完了根拠にしない。 |
| AGT-05 | 副作用はInternal Tool経由でのみ実行する。 |
| AGT-06 | Internal ToolはMCP Clientに列挙・公開しない。 |

### 7.2 Tool未使用検出

AgentはTaskの期待副作用と観測結果を比較し、実行が必要なのにtool callが0件の場合はTaskをcompletedにしない。再試行はAgent Loopの失敗回数へ算入する。純粋な説明・分析Taskにはtool callを強制しない。Sandbox Policyによる未許可操作は同一Tool呼出しへ再投入しない。許可済み能力だけで代替できる可能性がある場合に限り再計画でき、同一denyの再発、計画未変更、実行可能Taskなし、再計画失敗、または既定最大3回への到達でTaskをfailedにしてcleanupする。

Internal Toolが返す読取・検索・tail結果は設定可能な上限を持ち、contextを無制限に消費してはならない。上限値は設計および設定schemaで定義する。

---

## 8. Planner仕様

### 8.1 TaskGraph

| ID | 要件 |
| --- | --- |
| PLN-01 | TaskGraphはDAGでなければならない。cycleを検出した更新は拒否する。 |
| PLN-02 | 既定 `max_tasks` は32。 |
| PLN-03 | completed Taskはimmutable。 |
| PLN-04 | 未完了Taskの追加とdependency追加を許可する。 |
| PLN-05 | TaskGraph変更後はToken CPMを再計算する。 |
| PLN-06 | Taskは意味的作業単位とし、Token Budget Classとは分離する。 |

### 8.2 Token Budget Class

| Class | Token上限 |
| --- | --- |
| 1K | 1,024 |
| 2K | 2,048 |
| 4K | 4,096 |
| 8K | 8,192 |
| 16K | 16,384 |
| 32K | 32,768 |
| 64K | 65,536 |
| 128K | 131,072 |

Token Budget ClassはTask全体に許されるLLM token消費の計画値であり、単一Ollama callのcontext window (`num_ctx`) ではない。複数callの合計がTask実績となる。

### 8.3 Token PERT

- 各Taskは `optimistic_tokens (O)`、`most_likely_tokens (M)`、`pessimistic_tokens (P)` を持つ。
- 不変条件は `0 < O <= M <= P <= token_budget` とする。
- 期待token costは `E = (O + 4M + P) / 6` とする。
- Critical Pathは依存経路上の `E` の合計が最大の経路とする。
- Token CPMは実行時間を予測しない。依存連鎖のLLMコストと優先度を可視化するために使用する。
- 全Taskの総token予算はCritical Pathとは別に合計して管理する。

### 8.4 実測

Task実績はOllama応答の `prompt_eval_count` をinput token、`eval_count` をoutput tokenとして累積し、`actual_total_tokens = input + output` を保持する。v1では実績による自動学習補正は行わず、将来の推定改善に利用可能な記録だけを残す。

---

## 9. Session・Context仕様

| ID | 要件 |
| --- | --- |
| SES-01 | Sessionを持つ。完全statelessにはしない。 |
| SES-02 | Session IDをMCP I/Fへ公開する。 |
| SES-03 | Sessionはプロセスメモリにのみ保持し、アプリ終了時に消失してよい。 |
| SES-04 | Sessionはconversation、TaskGraph、Execution Resultを保持する。 |
| SES-05 | context上限接近時は古い情報を単純削除せず要約する。 |
| SES-06 | 要約後も未完了Task、security decision、重要なexecution result、利用者制約を保持する。 |

Context要約を開始する利用率閾値は設定可能でなければならない。具体値は設計および設定schemaで定義する。

---

## 10. Skill・Prompt仕様

### 10.1 Prompt優先順位

優先順位は `Fixed System Prompt > User System Prompt > Runtime Context > Conversation` とする。下位層は上位層の禁止事項・安全条件を上書きできない。

| 層 | 変更主体 | 内容 |
| --- | --- | --- |
| Fixed System Prompt | アプリケーションのみ | 安全不変条件、tool利用規則、完了判定 |
| User System Prompt | 設定所有者 | プロジェクト固有の追加指示 |
| Runtime Context | Agent Runtime | locale、選択Skill、Sandbox capability、TaskGraph |
| Conversation | MCP Client/Agent | 依頼と対話履歴 |

### 10.2 Skill

- Agent Skills open standard (agentskills.io) に準拠する。
- Skill directory構造は `<skill-name>/SKILL.md` のみを扱う。legacy単一Markdown形式は廃止する。
- `SKILL.md` はYAML frontmatter + Markdown bodyで構成し、`name` (1-64文字、lowercase英数字+hyphen、親directory名と一致) と `description` (1-1024文字) を必須とする。
- frontmatterなしのSkillは推測せずrejectする。malformed YAML、duplicate skill nameは起動/check時fatalとする。
- Progressive Disclosure: Stage 1 Discovery (name + descriptionのみ) → Stage 2 Selection (LLM) → Stage 3 Instructions Load (選択SKILL.md本文) → Stage 4 Resources (scripts/references/assets)。
- Skill選択はLLMにより行う。選択可能集合は設定されたSkill directoryに限定する。Runtimeは選択結果を検証し、unknown Skill名を読み込まない。
- Skillロードはcapability付与を意味しない。`allowed-tools` metadataはSandbox Capabilityとして解釈しない。
- Skillに `scripts/` が含まれていても自動実行許可しない。Entry起動には通常どおりEffective Sandbox Policy上のFilesystem execute capability、Entry Process分類、必要なExecutable Approval、Sandbox Brokerを必須とする。
- Skill directory内resourceについてcanonicalization、reparse point検査、Skill root外へのescape禁止を行う。
- Skill選択・本文ロードはInternal Toolとして公開せず、Agent Runtime / Prompt Context Managementの責務として実装する。
- Internal Toolの具体的なcatalogとschemaは設計事項とする。MCP Clientへ公開せず、Internal Toolによる副作用は必ずPolicy検査を通過しなければならない。

---

## 11. User Sandbox Configuration・Effective Sandbox Policy仕様

### 11.1 基本原則

- User Sandbox Configurationは`readonly`または`development` Profile、Workspace、Mount、Execution、Network、Resourceを表す。
- Sandbox Environment ResolutionとExecutable Approval Resolutionの成功後だけEffective Sandbox Policyを生成する。
- Effective Sandbox PolicyはResolved Filesystem Rootのcapabilityと由来、Approved Entry Executable、Runtime Root、Artifact Root、Network endpoint、Resource limit、固定baseline capabilityを利用者が確認可能な形で保持する。
- **ホワイトリスト方式**を採用し、未指定能力はdenyする。
- Descendant ProcessはEntry Processと同じLPAC、Filesystem、Network、Job confinementを継承し、親より強いcapabilityを取得できない。
- LLMとMCP ClientはUser Sandbox Configuration、Resolution Result、Executable Approval、Effective Sandbox Policyを変更できない。
- User Sandbox Configuration変更はconfig別Resolution Resultの再確認とアプリ再起動を必要とする。
- v1で開放可能なのはFilesystem、Process、Network、Resourceとする。その他能力はdenyとする。

### 11.2 Filesystem Policy

| 権限 | 意味 |
| --- | --- |
| read | ファイル内容読取、directory列挙。 |
| write | create、overwrite、renameを含む。deleteは含まない。 |
| execute | 対象fileをExecutable imageとして利用できる。Entry Processの分類に応じてExecutable Approvalも必要。 |
| delete | ファイルまたはdirectoryを削除できる。 |

| ID | 要件 |
| --- | --- |
| FS-01 | Workspace Root、Mount Root、Runtime Root、Artifact Root、個別Executable fileをFilesystem Rootへ変換する。 |
| FS-02 | Logical Pathはreparse chainとcycleを検査してResolved Pathへ変換した後にPolicy評価する。 |
| FS-03 | 未確認または確認後に解決先が変化したLogical Pathを使用せず、許可範囲外への脱出を禁止する。 |
| FS-04 | write権限だけではdeleteできない。 |
| FS-05 | ACLとAppContainerの両方で強制可能な形にする。 |
| FS-06 | ディレクトリ作成 (mkdir) はwrite権限で許可する。ディレクトリ削除 (rmdir) はdelete権限で許可するが、空ディレクトリのみとする。ディレクトリ列挙 (list) はread権限で許可する。 |
| FS-07 | renameはsource/destination双方にwrite権限を要求する。destination既存時は拒否する。cross-volume renameは不支持とする。 |
| FS-08 | readonly ProfileのWorkspaceはreadのみ、development ProfileのWorkspaceはread/write/deleteおよびWorkspace Artifact実行を許可する。 |
| FS-09 | Mount accessはread_only、read_write、read_write_deleteのいずれかとし、MountからのExecutable起動を許可しない。 |
| FS-10 | read Filesystem CapabilityをWindows ACL execute permissionへ暗黙変換しない。 |

### 11.3 Process Policy

| ID | 要件 |
| --- | --- |
| PRC-01 | Approved Entry ExecutableとApproved Shell ExecutableはAlias、Resolved Path、SHA-256がExecutable Approvalと一致しなければならない。 |
| PRC-02 | Entry Executable更新でhashが変化した場合は自動許可せず再承認を要求する。pathまたはreparse解決先変更も同様とする。 |
| PRC-03 | 確認済みRuntime Root内のRuntime Componentは個別hashなしでEntry Processとして起動可能とする。 |
| PRC-04 | development Workspace内のWorkspace ArtifactはHost Executable ApprovalなしでEntry Processとして起動可能とする。 |
| PRC-05 | External Unknown ExecutableをBrokerからEntry Processとして直接起動してはならない。 |
| PRC-06 | cmd.exe、powershell.exe、pwsh.exeをShellとして分類し、直接起動にはExecutable Approvalを要求する。Shellの許可は追加capabilityを付与しない。 |
| PRC-07 | Descendant Processは個別Executable Approvalを要求せず許可するが、同じLPAC token、ACL、WFP、Job Objectを継承しなければならない。 |
| PRC-08 | 全DescendantをJob chain内へ閉じ込め、breakawayを許可しない。 |
| PRC-09 | Entry Processの分類とApproval判定はSandbox Brokerが実行前に行う。 |

### 11.4 Network Policy

- Network Access Modeは `none`、`local`、`restricted` の3値とする。
- `none` はLoopbackを含む全通信を拒否する。
- `local` は列挙portに対するIPv4/IPv6 Loopbackだけを許可し、LANを含めない。
- `restricted` は列挙host/portに一致するoutboundだけを許可する。
- endpointが空またはmodeと矛盾する設定は拒否し、全開放を意味するfallbackを持たない。
- host名はhostsファイルに近い単純な列挙思想で扱い、汎用Firewall言語は実装しない。

### 11.5 Resource Policy

| 資源 | 要件 |
| --- | --- |
| process count | 上限を設定可能。Job配下全体に適用。 |
| memory | 上限を設定可能。 |
| wall-clock timeout | TaskまたはProcessの停止条件として設定可能。 |
| child process | 親と同等以下の制約下でのみ許可。 |

Resource Profileは`constrained = 1024 MiB/4 Process/300秒`、`normal = 4096 MiB/16 Process/1800秒`、`extended = 8192 MiB/32 Process/3600秒`とし、各正数値を個別override可能とする。

### 11.6 v1で明示denyする能力

- Registry write
- 任意COM/Automation
- Device直接アクセス
- Camera/Microphone
- Credential Manager
- SSH keyの自動継承
- API token/secretの自動継承
- Sandbox外のNamed Pipe/IPC

---

## 12. File Editing仕様

- overwrite、patch、atomic replaceを併用できる。
- 通常は変更前内容をメモリに保持し、編集後検証に失敗した場合にrollbackする。
- 設定されたmemory backup閾値を超える大容量ファイルでは、Sandbox管理下の一時backupを使用できる。
- memory backup閾値は設定可能でなければならない。
- 利用者向け恒久 `.bak` ファイルは既定で作成しない。
- atomic replaceが適用可能な操作では、部分書込み状態を利用者から観測させないことを優先する。

---

## 13. Application Profile・Task Resource仕様

- Application Profileはapplication固定のLPACとし、`ALL APPLICATION PACKAGES`由来の既定accessを除外する。
- 全Profileの固定baselineとしてRegistry readとSandbox Process Tree自身のinstrumentation registrationを許可し、Registry writeとCOM capabilityはdenyする。
- Resolved `%SystemRoot%/System32`をOS Runtime RootとしてSandbox Process Treeへread/execute公開する。Brokerからの直接Entry起動は別途Executable Approvalを要求する。
- Task終了時にApplication Profileを削除しない。
- Task固有ACL、WFP filter、Job Object、一時ファイル等はTask Resourceとして管理する。
- Task Resourceは正常終了・失敗・cancelのいずれでも残留させない。
- crashで残留可能性がある変更はRecovery Journalにより次回起動時に回収する。
- MCP受付開始前にRecoveryを完了し、clean stateを確認しなければならない。

---

## 14. 国際化仕様

| ID | 要件 |
| --- | --- |
| I18N-01 | アプリケーション管理メッセージをソースコードへハードコードしない。 |
| I18N-02 | 標準localeとして `locales/en.json` と `locales/ja.json` を配布する。 |
| I18N-03 | ユーザーは `zh-CN.json` 等を追加し、アプリ変更なしでlocaleを追加できる。 |
| I18N-04 | locale識別子はBCP 47形式を推奨する。 |
| I18N-05 | 起動時のlocaleは`application.language`で選択する。 |
| I18N-06 | 優先順位はconfig > built-in default(en)とし、CLI overrideを持たない。 |
| I18N-07 | 選択言語はCLI、診断、MCPテキスト応答、LLM最終回答へ適用する。 |
| I18N-08 | 入力言語の自動検出による切替は行わない。 |
| I18N-09 | placeholderは `{task}` のようなnamed placeholderを使う。 |
| I18N-10 | missing keyは 選択locale → en → key文字列 の順にfallbackする。 |
| I18N-11 | 壊れたJSONまたは未知keyを含むlocale fileはfatal errorとする。 |

---

## 15. Configuration仕様

- 主設定形式はYAML。
- `schema_version: 2` を必須とする。version 1の`execution.executables`／`execution.shells`と、それ以前の`filesystem`／`process.approvals`形式は破壊的に廃止し、移行方法付きで拒否する。
- 設定変更の反映には再起動を必須とする。
- Hot Reloadは明示的に非対応。
- config pathはCLIの任意の位置引数で選択可能とし、optionによる設定上書きを持たない。
- base設定と同じdirectoryに `agent.local.yaml` が存在する場合は任意overrideとして読み込む。mapは再帰mergeし、scalarと配列はlocal側で置換する。merge後の設定全体をvalidationし、相対pathはbase設定directoryを基準に解決する。
- Release Bundleは既定設定だけを配布し、利用者のlocal設定、User System Prompt、Skillをpublishで上書きしてはならない。
- `sandbox.execution.entries`はAlias、Executable Logical Path、optional Runtime Rootを一つのrecordとして持つ。Shell分類はResolved file nameから内部で決定する。
- 起動時にschema、Applied Configuration、locale、Effective Sandbox Policyのvalidationを行う。
- Workspace/Mount ResolutionとExecutable identity/Approvalを分離保存せず、config別Applied Configuration Storeへ一つのsnapshotとして保存する。StoreはWindows user単位のuser-only領域に置き、Release Bundleへ含めない。
- YAML fingerprint、Resolved Path、Executable SHA-256、Runtime Rootのいずれかが適用済みsnapshotと異なる場合、起動はfail-closedにして`agent-mcp apply`を案内する。

---

## 16. Logging・Audit仕様

| 種別 | 要件 |
| --- | --- |
| Application Log | stderrに出力可能。stdio時stdoutへログを出してはならない。ファイルにも保存する。 |
| LLM Log | promptとresponseを記録する。call、Session、Task、Planner Task、phase、iteration、replan、model、token usageを相関できなければならない。secretを継承しない前提でも、ログ出力先は保護する。 |
| Audit Log | 通常ログと分離する。Task lifecycle、Internal Tool Call、Sandbox Process、秘密情報を除いたargument metadata、exit code、file write、delete、denied access、network rule、recoveryをSession/Taskと相関して記録する。argument本文、画像、Base64、credentialは記録しない。 |
| Token Metrics | Task/Call単位のinput/output/total tokenを記録する。 |

---

## 17. Recovery・異常系仕様

| ID | 異常 | 要求動作 |
| --- | --- | --- |
| REC-01 | Ollama unavailable | 既定3回retry後、Taskをfailed。 |
| REC-02 | Process hang | timeout後、安全にJob配下を停止。 |
| REC-03 | Application終了 | Job Object配下を必ずkillする。 |
| REC-04 | stdio EOF/Client消失 | 当該Client所有のTaskを安全停止する。 |
| REC-05 | Streamable HTTP server停止／明示cancel | 対象Taskを安全停止する。stateless HTTPのrequest完了やsocket切断はAgent Session終了とみなさない。 |
| REC-06 | crash後起動 | Recovery Journalに基づき残留Task Resourceをcleanにしてからserveする。 |
| REC-07 | cleanup失敗 | serveを開始せずfatal errorとする。 |

---

## 18. セキュリティ不変条件

| ID | 不変条件 |
| --- | --- |
| SEC-INV-01 | LLMの出力だけでは権限を増加できない。 |
| SEC-INV-02 | MCP ClientはUser Sandbox Configuration、Resolution Result、Executable Approval、Effective Sandbox Policyを変更できない。 |
| SEC-INV-03 | descendant processは親より強い権限を持てない。 |
| SEC-INV-04 | 未許可Filesystem pathへR/W/E/Deleteできない。 |
| SEC-INV-05 | 承認hashと一致しないHost ExecutableをBrokerからEntry Processとして直接起動できない。 |
| SEC-INV-06 | Network noneではLoopbackを含め通信できない。 |
| SEC-INV-07 | Network local/restrictedでもEffective Network Policy外のaddress/portへ通信できない。 |
| SEC-INV-08 | CredentialをSandboxへ暗黙継承しない。 |
| SEC-INV-09 | Fixed System Promptは利用者入力で置換できない。 |
| SEC-INV-10 | Task終了後にTask Resourceを残さない。 |
| SEC-INV-11 | Recovery未完了状態でMCP受付を開始しない。 |
| SEC-INV-12 | stdio stdoutにはMCP protocol以外を書かない。 |
| SEC-INV-13 | Sandbox Process TreeのどのProcessもEffective Sandbox Policy外のresourceまたはcapabilityを取得できない。 |

---

## 19. 非機能要求

| ID | 品質 | 要求 |
| --- | --- | --- |
| NFR-01 | Security | default deny、least privilege、explicit approvalを優先する。 |
| NFR-02 | Determinism | Policy評価、TaskGraph検証、PERT/CPM計算はLLMに依存せず決定的に実行する。 |
| NFR-03 | Recoverability | crash後にclean stateへ復帰できる。 |
| NFR-04 | Maintainability | 外部MCP Toolを2個に固定し、内部責務を分離する。 |
| NFR-05 | Dependency Control | 標準ライブラリで実現可能な機能に新規依存を追加しない。 |
| NFR-06 | Portability | v1はWindows 11 x64専用。Windows機構を抽象化し過ぎない。 |
| NFR-07 | Observability | Task、Internal Tool Call、Sandbox Process、Token、Effective Sandbox Policy denialを追跡可能にする。 |
| NFR-08 | Localization | 英語・日本語を標準提供し、追加localeをコード変更なしで導入可能。 |
| NFR-09 | Readability | 設定、ログ、仕様語彙を一貫させる。 |

---

## 20. 受入基準

| ID | 検証条件 |
| --- | --- |
| AT-01 | stdioでinitialize→agent_run→agent_statusが成立する。 |
| AT-02 | Streamable HTTPを127.0.0.1/::1で利用でき、非loopback bindは拒否される。 |
| AT-03 | Legacy HTTP+SSE endpointを提供しない。 |
| AT-04 | agent_runがTask ID/Session IDを返し、完了前にblockingし続けない。 |
| AT-05 | MCP temperature overrideがTask scopeのみで有効。 |
| AT-06 | 非Vision modelへ画像指定時、選択localeのerrorが返る。 |
| AT-07 | 未許可file read/write/deleteがOSまたはBrokerで拒否されAuditに残る。 |
| AT-08 | reparse解決結果が未確認または変更されたLogical Pathは拒否される。 |
| AT-09 | Approved Entry Executableのhash変更後の直接起動が拒否される。 |
| AT-10 | Network noneでLoopbackを含む通信が拒否される。 |
| AT-11 | local/restrictedのEffective Network Policy外address/portへの通信が拒否される。 |
| AT-12 | Entry/Descendant ProcessがLPACとJob confinementを継承し、breakawayまたはPolicy外resource accessができない。 |
| AT-21 | Approved Python、Approved PowerShell、Approved .NETから通常のDescendant Processを生成できる。 |
| AT-22 | development Workspace ArtifactはApprovalなしでEntry起動でき、External Unknown Executableの直接Entry起動は拒否される。 |
| AT-13 | Task crash後、次回起動RecoveryでTask Resourceが除去される。 |
| AT-14 | TaskGraph cycle追加が拒否される。 |
| AT-15 | completed Taskが変更されない。 |
| AT-16 | O/M/Pからexpected tokenが決定的に計算される。 |
| AT-17 | Ollama実測token数がTask実績へ累積される。 |
| AT-18 | ja/en切替がCLI、MCP応答、LLM回答へ反映される。 |
| AT-19 | 追加localeがコード変更なしでロードされる。 |
| AT-20 | 未知locale keyまたは壊れたJSONで起動/checkが失敗する。 |

### 20.1 Operational E2E

| ID | 検証条件 |
| --- | --- |
| E2E-01 | ソースツリー外へ展開したRelease Bundle、Python 3.14 Approval、配布既定model、stdio MCP Clientを使い、複雑なPython programとsubprocessを含むtestの作成・実行、日本語応答、Audit追跡、Task Resource cleanupまで完走する。 |
| E2E-02 | E2E-01と同等の作業をloopback限定Streamable HTTPのIPv4/IPv6で完走する。 |

v1の完了には、win-x64向けself-contained Release Bundleが単独でEnvironment Resolutionを実行でき、確認済みOperational配置でE2E-01とE2E-02が`deepseek-v4-flash:cloud`を使ってPASSすることを必須とする。rate limit、接続失敗、model unavailableをPASSへ読み替えない。

---

## 21. 要求トレーサビリティ

| 仕様領域 | 主要Requirement | Design.md対応章 |
| --- | --- | --- |
| MCP | MCP-TR / MCP-RUN / MCP-STS | 5章 |
| Ollama | OLL-* | 6章 |
| Agent | AGT-* | 7章 |
| Planner | PLN-* | 8章 |
| Session | SES-* | 9章 |
| Sandbox | FS-* / PRC-* / SEC-INV-* | 10〜13章 |
| i18n | I18N-* | 14章 |
| Recovery | REC-* | 16章 |
| NFR | NFR-* | 全章横断 |

---

## 22. 参考資料

- IPA/SEC「実務家のための形式手法 厳密な仕様記述を志すための形式手法入門 厳密な仕様記述入門」2013年。仕様と設計の分離、構造・機能・振る舞い・非機能、Validation/Verification、完全性・一貫性等の記述原則を参考にした。
- Model Context Protocol Specification: standard transportsとしてstdioとStreamable HTTPを参照し、旧HTTP+SSE transportは非対応とした。
- Ollama API Reference: Chat APIのtools/images/optionsおよび `prompt_eval_count` / `eval_count` を参照した。

---

## 23. 変更管理

- 本仕様の変更は `schema_version`、MCP Tool schema、Effective Sandbox Policy、安全不変条件への影響を必ず確認する。
- Design.mdが本仕様と矛盾した場合は本仕様を優先し、Design.mdを修正する。
- 実装都合で仕様を暗黙変更してはならない。必要な場合は先に仕様を変更する。

---

## 24. Requirement ID索引

- `MCP-TR-*`: MCP transport
- `MCP-RUN-*`: agent_run
- `MCP-STS-*`: agent_status
- `OLL-*`: Ollama
- `AGT-*`: Agent Loop
- `PLN-*`: Planner
- `SES-*`: Session
- `FS-*`: Filesystem
- `PRC-*`: Process
- `I18N-*`: Localization
- `REC-*`: Recovery
- `SEC-INV-*`: Security invariant
- `NFR-*`: Non-functional
- `AT-*`: Acceptance

## 25. 仕様上の禁止事項一覧

- MCP ClientへInternal Toolを公開すること。
- MCP requestでSystem Prompt、model、SandboxPolicyを変更すること。
- `temperature` overrideを永続設定へ書き戻すこと。
- Legacy HTTP+SSEを互換目的で自動有効化すること。
- Streamable HTTPをloopback外にbindすること。
- write Filesystem Capabilityだけでdeleteを許可すること。
- reparse point解決前の文字列pathだけでallow判定すること。
- hash不一致の実行ファイルを自動再承認すること。
- Network `allow`をunrestricted outboundとして解釈すること。
- 子プロセスに親より広いcapabilityを付与すること。
- Skill選択を権限付与として扱うこと。
- completed Taskを書き換えること。
- Token Budget ClassをOllama context lengthと同一視すること。
- context要約で未完了Taskや利用者制約を消すこと。
- cleanup失敗状態でserveを開始すること。