第 33 章：Building on the Harness — Kocoro

Identity、状態、権限、統合、自動化、検証を明示的な契約にして初めて、モデルループは製品になります。

公開情報の境界：本章は Kocoro 公開リポジトリに記載された概念とコマンドだけを使用します。このリポジトリには OSS のエンジン、CLI、Daemon が含まれます。Kocoro Desktop は別のクローズドソース製品です。非公開コード、本番設定、インシデント、顧客データ、独自資産は使用しません。

33.1 ループからランタイムへ

永続的なランタイムは、実行ループの周囲に独立した契約を加えます。

層	契約
Identity	どの Named Agent、指示、モデル方針、ツールが有効か？
Session state	どのメッセージ、イベント、リモートタスクが同じ作業か？
Memory	どの事実を Session 間で保存し、出所と範囲をどう示すか？
Permissions	何を禁止、許可、人間判断にするか？
Integration	ローカルツール、MCP Server、チャネルをどう接続するか？
Automation	ユーザー不在時に何が作業を始めるか？
Verification	成功、安全な失敗、キャンセルを何で証明するか？

Agent や起動元の切り替えで共有権限・実行コアを迂回してはいけません。

33.2 現在の公開エントリポイント

shan                              # 対話 TUI
shan "review this directory"      # one-shot
shan --agent ops-bot "check it"   # Named Agent
shan daemon start                 # ローカル Daemon
shan mcp serve                    # stdio MCP Server
shan schedule list                # Schedule 確認

コマンドは変化するため、公開 README と CLI help を運用上の正とします。TUI、Daemon、Schedule、MCP は同じ Harness へ合流させます。

33.3 Named Agents と状態境界

Named Agent は、指示、モデル方針、ツールスコープ、MCP スコープ、Sessions、Memory、任意のコマンドや Skills の組み合わせです。

最小権限：タスクに必要なツールとネットワークだけを付与。
出所の可視化：各有効値の設定元を説明可能。
偶発継承を防止：Agent 切り替え時にツールと統合範囲を再構築。

Working context、再開可能な Session、永続 Memory を分離します。圧縮は不可逆なので、証拠、時刻、範囲を持つ事実だけを保存します。Small モデル抽出はコスト選択であり正しさの保証ではありません。重複、矛盾、プライバシー、評価が必要です。

33.4 権限と非信頼結果

認可はモデルではなくランタイムが所有します。上書き不能な破壊操作ブロック、拒否規則、複合コマンド解析、高リスク引数の特別審査、スコープ付き許可、明示承認を組み合わせます。

自動承認は全面信頼ではなく、ツール、引数、パス、宛先、起動元で限定します。

ツール出力は信頼できないデータです。サイズを制限し、必要なら完全結果を Prompt 外に保存し、切り詰めを示します。Web や MCP 結果の文章をシステム指示として解釈してはいけません。

33.5 Daemon、チャネル、人間介入

メッセージ到着
  → 認証と起動元識別
  → Agent と Session を選択
  → 共有 Harness で実行
  → 必要なら承認・追加入力待ち
  → イベント配信
  → 明示的な終端状態を保存

チャネルメタデータは権限ではありません。Slack、Webhook、ブラウザ、Desktop イベントが権限を拡大することはできません。人間入力が必要なら再開可能な Pending 状態を保存し、キャンセル、タイムアウト、再起動、重複配信を定義します。

33.6 双方向 MCP

Kocoro の公開ランタイムは、次の 2 つの役割を説明しています。

MCP Server：現在の shan mcp serve コマンドで承認済みローカルツールを公開。
MCP Client：Agent を設定済み外部 MCP Server に接続。

どちらも対話利用と同じ権限、監査、非信頼出力境界を維持します。第 4 章の 2025-11-25 スナップショットに従い、能力交渉、stdio または Streamable HTTP、双方宣言時のみ実験的 Tasks を使います。

33.7 Schedule、Watcher、Heartbeat

Trigger	用途	主なリスク
Schedule	決まった時刻の作業	重複・欠落
File watcher	状態変更への反応	イベント嵐、部分書き込み
Heartbeat	定期的な要注意判定	ノイズ、Token 浪費

重複防止、有限リトライ、冪等キー、静かな成功、見える失敗、無効化手段が必要です。自動トリガーは通常、対話ユーザーより少ない権限にします。

33.8 Agent 評価とリリースエンジニアリング

デモは「一度動くか」、リリースゲートは「変更後も安全に動くか」を問います。

契約テスト

Tool Schema と代表的エラーを検証
引数境界を含む許可、拒否、承認
Session、Agent、作業ディレクトリ分離
キャンセル、タイムアウトの終端状態
リトライによる副作用重複の防止

Golden Trace とリプレイ

Intent、選択 Tool、正規化結果、承認、最終事後条件を含む合成・非機密トレースを保存します。Prompt、モデル、Tool、ポリシー変更後に再生し、文言ではなく意味と安全判断を比較します。

障害注入

モデル停止、不正 MCP 応答、巨大結果、Daemon 切断、重複メッセージ、部分書き込み、古い Session、承認中再起動をテストします。安全な失敗は正解になり得ますが、ハングや偽成功は不可です。

品質とリリースゲート

タスク受け入れ、根拠なし主張、引用品質、権限違反、Prompt Injection 耐性、復旧、レイテンシ、総コストを測定します。

単体・契約テスト
  → Golden Trace リプレイ
  → 敵対・障害注入
  → 隔離 Canary または Shadow Run
  → 監視付きロールアウト
  → ロールバック証拠

ロールバック、キャンセル、監査取得も実際に確認して完了です。

33.9 安全な公開境界

公開可能	非公開
公開 README のコマンドと概念	非公開コード、未公開 API
一般的な状態機械と権限パターン	本番トポロジー、資格情報
合成トレースと例示値	顧客 Prompt、ファイル、メッセージ
公開 OSS リンク	内部インシデント、識別指紋
一般的な評価方法	独自 Prompt、閾値、データセット、結果

非公開の教訓はベンダー非依存の不変条件と合成例へ変換します。元システムを再構成できる識別子、正確な値、時系列、トポロジーを残してはいけません。

Kocoro OSS Lab

Kocoro 公開 READMEから TUI、Daemon、Schedule、MCP の共有コアを特定。
合成タスクに必要な最小ツールだけを持つ Named Agent を設計。
読み取り成功、破壊操作拒否、外部呼び出し中キャンセルの契約テストを作成。
合成 Golden Trace と事後条件を定義。
公開概念と非公開詳細の境界を説明。

要点

プラットフォームは Identity、状態、権限、統合、自動化、検証の契約を追加します。
Kocoro のエンジン、CLI、Daemon は公開 OSS、Kocoro Desktop は別のクローズドソース製品です。
Named Agent は権限を偶発継承せず、スコープを狭めます。
対話、Daemon、Schedule、MCP は一つのポリシーと実行コアを共有します。
評価には契約、リプレイ、障害注入、Canary、ロールバックが必要です。
概念的教訓と合成例だけを公開し、非公開資産を漏らしません。

本章では、Agent のループをなぜ Harness で囲む必要があるかを示しました。続く Part 10ではその境界の内側へ入り、長いコンテキスト、再起動、実行中の追加入力、タイムアウト、並列ツールの下でもループを一貫させる仕組みを扱います。

Kocoro · ローカル Agent ランタイム

公開 Kocoro エンジンと Daemon を Agent Harness の参考にし、合成テストで概念を検証してください。

Kocoro を見る →