第 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 章の現行 2026-07-28 モデルに従います。プロトコルコアはステートレスで各リクエストが自己記述的です。stdio はローカル子プロセスに適し、リモート統合は独立した HTTP リクエストとして設計します。Tasks は対応を確認した後に使うオプトイン拡張であり、コアのグローバルなタスクシステムではありません。実装ごとの確認が必要です。安定版 Python SDK v2.0.0 は新しいコアを実装しましたが、release note では 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、閾値、データセット、結果

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

要点

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

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