# AI Agent Sandbox MCP Server v1

Windows 11上でlocal Ollamaを利用し、明示的に承認したFilesystem、Process、Network操作だけをAppContainer内で実行するMCP Serverです。MCP公開Toolは `agent_run` と `agent_status` の2つです。

## 動作要件

- Windows 11 x64
- 管理者権限（TaskごとのWFP filter追加・削除に必要）
- Base Filtering Engine (BFE)が実行中
- Ollama。tested versionは実測した `0.32.6`。minimum supported versionは未確定です。
- 必須local model: `hf.co/unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL`

サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。

## 初回セットアップ

管理者としてPowerShellを起動し、Release Bundleへ移動します。

```powershell
ollama --version
ollama pull hf.co/unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL
ollama serve
```

別の管理者PowerShellで診断します。

```powershell
.\agent-mcp.exe check --config .\agent.yaml --lang ja
```

`administrator=true`、`bfe_engine_open=true`、`wfp_write_transaction=true`、`wfp_filter_add_delete=true` が必要です。probeはdynamic WFP filterを追加後すぐ削除し、残留させません。

## agent.yaml

Filesystem pathは能力ごとに指定します。未指定能力はdenyです。

```yaml
sandbox:
  filesystem:
    read: [C:/work/fixture]
    write: [C:/work/fixture]
    execute:
      - C:/Program Files/dotnet/dotnet.exe
    delete: [C:/work/fixture]
```

実行ファイルはcanonical absolute pathとSHA-256の両方を承認します。

```powershell
(Get-FileHash -Algorithm SHA256 -LiteralPath 'C:\Program Files\dotnet\dotnet.exe').Hash
```

```yaml
sandbox:
  process:
    allow_shell: false
    approvals:
      - path: C:/Program Files/dotnet/dotnet.exe
        sha256: <64桁の実測値>
```

Sandbox processからの子process生成は、承認済みpathであってもOSのchild-process restrictionで拒否されます。build/testで必要な各実行ファイルは事前にpath/hash承認し、個別の `process_run` としてBrokerから起動してください。E2Eではbuild server、node reuse、shared compilationを無効化し、in-process buildまたはBrokerから直接起動できるself-testを使用します。Networkは既定でlocalhostを含めdenyです。allow時はTask開始時にhostをIPへsnapshot化します。

```yaml
sandbox:
  network:
    mode: allow
    allow:
      - host: 127.0.0.1
        ports: [11434]
```

Ollama通信は管理Broker側から行うため、Sandbox processのnetwork許可とは独立です。

## stdio

WFP操作のため、stdioではMCP Client自体を管理者PowerShellから起動します。Client設定例:

```json
{
  "mcpServers": {
    "agent-sandbox": {
      "command": "C:\\tools\\agent-sandbox-mcp\\agent-mcp.exe",
      "args": ["serve", "--config", "C:\\tools\\agent-sandbox-mcp\\agent.yaml", "--lang", "ja", "--transport", "stdio"]
    }
  }
}
```

`agent_run`へ自然言語の依頼を送り、返却されたUUIDを `agent_status` でterminal stateまでpollします。複数Taskはqueuedで受理しますが、planning/runningおよびTask Resource適用は全体で1件です。

## Streamable HTTP

管理者PowerShellでserverを起動します。

```powershell
.\agent-mcp.exe serve --config .\agent.yaml --lang ja --transport http
```

Client endpointは `http://127.0.0.1:8080/mcp` です。設定できるbindは `127.0.0.1` または `::1` だけです。Streamable HTTP POSTだけを使用し、GET SSE、`/sse`、`/message` Legacy SSEは利用できません。

## LogとRecovery

- `logs/application.log`: 起動・診断・管理event
- `logs/llm.jsonl`: LLM request/response、token usage、tool result
- `logs/audit.jsonl`: Task ID付きfile/process/policy/ACL/WFP/recovery event
- `state/journals/`: crash recovery journal。正常終了後は空
- `state/backups/`: 大容量file transaction backup。正常終了後は空

log directoryは起動ユーザーだけがアクセスできるprotected DACLへ設定されます。起動時はMCP受付前にRecoveryを実行し、復旧不能なhash競合があれば起動しません。

正常停止後、`agent-mcp.exe` descendant、追加ACL、WFP filter、loopback exemption、`state/backups`、`state/journals` が残っていないことを確認してください。loopback exemptionは `CheckNetIsolation.exe LoopbackExempt -s` で確認できます。

## よくあるエラー

- `error 5` / administrator=false: 管理者PowerShellから起動してください。
- BFE open失敗: `Get-Service BFE` でBase Filtering Engineを確認してください。
- Ollama接続失敗: `ollama list`、endpoint、model名を確認してください。
- executable deny: pathをabsolute/canonicalにし、更新後のSHA-256を再取得してください。
- file deny: 対象pathを必要なread/write/execute/delete能力へ追加し、再起動してください。
- rollback拒否: Task中に外部processが同じfileを変更しています。Audit Logとjournalを確認し、手動reviewしてください。

## ソースからのbuild／release

```powershell
dotnet restore AgentSandboxMcp.slnx
dotnet build AgentSandboxMcp.slnx -c Release --no-restore
dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore
.\scripts\Publish-Release.ps1
```

生成物はすべてrepository rootの `build/` に集約されます。

- `build/Debug/<ProjectName>/`: Debug build
- `build/Release/<ProjectName>/`: Release build
- `build/obj/<ProjectName>/`: restoreおよびcompiler中間生成物
- `build/Release/publish/`: win-x64 self-contained Bundle、version付きZIP、checksum

`artifacts/` はローカルの試験証跡・デバッグログ用です。`artifacts/` と `build/` はどちらもGit管理外です。

Release scriptはwin-x64 self-contained directory、version付きZIP、ZIP checksum、publish manifestを生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。完全な `agent-mcp check` は管理者PowerShellで実行してください。