feat: add Astro reference site and organize book contents

contents/4.1-ai-tools.md

@@ -0,0 +1,107 @@
+# 4.1. AI Tools
+
+## 目的と適用範囲
+
+AI Toolsは、WIP ClientがAIへ提供する、対象の配置を見て、できることを理解し、操作するための上位インターフェースである。本章で定義するAI向けの基礎ツールは **tree / inspect / invoke** の3操作に固定する。
+
+Protocol interactionをそのままToolとして公開するものではない。Protocolの`observe` / `fetch_interface` / `call_operation`は[3. Protocol](3-protocol.md)、取得・cache・観測整合性の責務は[4. Client](4-client.md)に従う。GUIやPTC / REPLなど、他のClientインターフェースの構成は本章で制限しない。
+
+## 基本的な利用モデル
+
+| AI向け操作 | AIが行うこと | Clientが引き受けること |
+| --- | --- | --- |
+| `tree(path, depth)` | indexableな対象の配置を見る | 必要なdepthの観測とtree表示 |
+| `inspect(path)` | 対象の説明とできることを知る | Object観測、Interface集合の解決、signature生成 |
+| `invoke(target, interface, operation, arguments)` | 選択した操作を名前付き引数で呼ぶ | 引数検証、観測との対応、validator、Protocol requestと結果の処理 |
+
+これらはProtocol interactionとの一対一対応ではない。特に`inspect`の対象はInterface参照ではなく、Objectを指すpathである。必要な`observe`と複数の`fetch_interface`はClient内部で行う。
+
+Inspectで見つけたOperationも`invoke`から呼び出し、Operationごとに新しいToolを登録しない。
+
+大量のObjectの発見は、各ドメインのObjectが公開する`list` / `search` / `query`等のOperationで行う。件数制限、検索条件、ページング等は、そのドメインに応じて各Operationが管理する。AIはこれらのOperationも`inspect`で確認し、`invoke`で呼び出す。発見方法が増えても基礎ツールは追加・変更しない。
+
+## `tree`: indexableな配置を見る
+
+`tree(path, depth)`は、起点をdepth 0として、指定depth内のindexableなツリーを全量取得・表示する。
+
+- 必要なcoverageを持つ観測を再利用できる。不足する場合はClientが`observe`で取得する。
+- 全量とは、指定した起点・depth・主体に公開されたindexableな範囲の全量であり、Worldspace全体ではない。
+- 名前、path、親子構造を中心に提示する。すべてのObjectのDescriptorやドメインデータを展開しない。
+- Protocolのdepth境界にある未観測のchildrenと、観測済みの空のindexable childrenを混同しない。
+- 指定depth内の一部を黙って省略して完全なtreeとして返さない。既存のresource limit内で成立しない場合は、その失敗を伝える。
+- Cacheに保持されたpathを単にprefixで集めてtreeにしない。Hostから観測したindexable edgeに従い、指定depth外やOperation経由で知っただけのentryを混ぜない。
+
+HostがTreeへ公開する範囲は、[Indexable childrenの条件](2.1-object-tree-schema.md#indexable-children)に従う。
+
+## `inspect`: 対象の説明とできることを知る
+
+`inspect(path)`は、そのpathで公開されているObjectの説明と操作を返す。
+
+AIがそのpathをtree、会話、Operation結果のいずれから知ったかは、事前条件にしない。ClientがまだObjectを観測していなくても、有効なpathを直接指定できる。Known Spaceにないことだけを理由に拒否せず、現在のHostの公開状態に従って観測する。
+
+Clientは次の情報を保持済みの観測から解決し、不足するものを取得する。
+
+1. 対象pathのObject。対象だけが必要なら`observe`の`depth = 0`を使用する。
+2. Objectが公開するInterface参照のordered set。
+3. 表示対象のInterfaceに対応する、取得・検証済みのDescriptor。
+
+Clientはこれらの情報から、Objectの説明とInterfaceごとの操作を提示する。AIに「先にObjectをobserveして、Interface参照を抜き出し、一つずつfetchする」という手順を要求しない。一方で、Objectの本文やドメインmetadataまで暗黙に読み込むわけではない。それらの取得は対象のOperationとして扱う。
+
+### 表示に必要な情報
+
+- 対象のpathと、公開されているObjectの説明。
+- InterfaceとOperationの対応。
+- Operation名、短い用途説明、名前付き引数、必須性、引数・結果の型。
+- 操作を理解するために必要な名前付き型・複合型の定義。
+
+生のDescriptor JSONを返すだけではなく、検証済みの情報から読みやすいObject signatureとInterface signatureを生成する。各signatureの表記は[4.2. Text View](4.2-text-view.md)に従う。同名Operationが複数Interfaceに存在しても、一つへ平坦化したり、出所を失ったりしない。
+
+Invokeへ渡すInterface参照とOperation名は区別して保持し、表示textを再parseして呼出先を決めない。Interfaceの未展開や取得失敗を「操作が存在しない」と誤表示しない。
+
+Signatureの配置や、詳細表示・表示対象を選択する具体的なTool引数は本章で固定しない。個々のsignatureを生成するときの全宣言の表示規則はText Viewに従い、表示側でInterface内部を切り詰めない。
+
+## `invoke`: 選んだ操作を実行する
+
+`invoke(target, interface, operation, arguments)`は、対象ObjectのInterfaceとOperationを明示して呼び出す。`target`は対象Objectのpathを指定するものであり、AIにProtocolのvalidator付きTargetを組み立てさせるものではない。
+
+`arguments`はOperationのparameter declarationに従う名前付きfieldのrecordであり、位置引数ではない。引数を持たないOperationには空のrecordを渡す。
+
+Interfaceを明示するのは、同じObjectの複数Interfaceに同名Operationがあり得るためである。Interfaceの選択をAIへ示すことと、Descriptorの取得手順をAIに管理させることは別である。
+
+選択するInterfaceは絶対scopeとlocal nameの組で識別する。Adapterが[Text Viewの短縮表記](4.2-text-view.md#参照表記)を入力として受ける場合も、入力境界で構造化参照へ変換し、Operation名は独立して保持する。Scope省略には明示contextが必要であり、対象pathからの推測や相対scopeの解決はしない。Protocolへ短縮表記のstringをそのまま送らない。
+
+ClientはObjectとDescriptorの観測を保持し、引数を検証し、path、Object validator、Interface参照とvalidator、および観測に存在する`scope_ref`をProtocol requestへ設定する。AIにvalidatorやscope Objectの`ref`の取得・コピー・更新をさせない。同一性管理やvalidatorはsignatureに含めない。`ref`のないscopeではidentityによる差し替え検出ができないことを許容し、AIへ代替identityの指定を要求しない。
+
+Pathを知っていることやInterfaceが表示されたことは、実行権限を意味しない。Hostは呼出時の公開状態、権限、capability、実行条件を引き続き検証する。ClientはresultをDescriptorに従って検証してから提示する。
+
+再観測とOperationの再実行を同一視しない。Stale、取消、拒否、結果不明などの扱いはProtocolと[ClientのFailure handling](4-client.md#failure-handling)に従う。結果不明のOperationを自動再実行せず、Operation名からread / writeやretry可否を推測しない。
+
+## Pathの発見と移動
+
+AIはtree、会話で示されたpath、Operation結果の`entry`などから次の対象を知ることができる。Pathを知っていること、ClientがObjectを観測・保持していること、indexable edgeも観測していることは別の状態である。[Clientの取得・保持・提示の分離](4-client.md#取得保持提示の分離)に従い、未観測のpathは必要になった時点でinspectできる。
+
+Clientが内部で保持する情報とAIに表示済みの情報は一致する必要がない。Treeの取得でObject情報を保持していても、AIには名前と構造だけを見せ、詳しい説明と操作はinspectで提示できる。
+
+Operation結果の`entry`型pathは、そのまま次の対象への参照として提示できる。すべての結果を即時に観測したり、再帰展開したりすることを必須にしない。AIが必要なpathを選んでinspectするときに、Clientが観測できる。
+
+Entryの抽出はDescriptorの型に従う。普通のstringを内容だけからpathと推測しない。結果のentryを観測・保持しても、それだけでindexable edgeを追加しない。
+
+Clientが付随的なentry取得を行う場合、その取得失敗と元のOperationの成否を混同しない。成功済みOperationを、結果の参照先が取得できなかったために失敗扱いして再実行させてはならない。
+
+## Tool bindingと表示
+
+本章の小文字表記は操作の呼称であり、providerごとのTool登録名の大文字・小文字やProtocol名の接頭辞は規定しない。AI providerがTool schemaを要求する場合は、Client adapterがこの3操作のschemaを提供する。Hostにprovider固有のTool schemaを提供させたり、取得したDescriptorごとにToolを追加登録したりしない。DescriptorはClient内部のOperation validationとsignature生成に用いる。
+
+Treeの具体的なtext layout、`depth`等の引数のdefault、inspectの表示選択引数、Tool response envelopeについて、本章は共通の具体schemaを定義しない。各bindingは、それらを提供するときにAIへ明示する契約として定め、本章の操作の意味を変えない。Text Viewもsignatureを包むresponse構造や配置を定義するものではない。
+
+取得・表示・cache保持を分離するが、特定の内部class構成、eviction algorithm、prefetch schedulerは要求しない。
+
+## 検証する利用シナリオ
+
+- 観測が空のClientで既知pathを直接inspectし、説明と操作を取得できる。
+- Treeが指定depthのindexable範囲を完全に提示し、cache内の他のpathを混ぜない。
+- 複数Interfaceに同名Operationがあっても、正しいInterfaceとOperationを選んでinvokeできる。
+- Search / list結果から必要なentryだけをinspectでき、全件先行取得を要求しない。
+- 非indexableなentryを観測した後も、rootからのtreeにそのentryが混入しない。
+- 参照先の取得失敗を、成功済みOperationの失敗や再実行の理由にしない。
+- 表示やcache利用によって、権限・観測整合性・結果不明の扱いを弱めない。