wip-reference/contents/4.1-ai-tools.md

4.1. AI Tools

目的と適用範囲

AIがWIPの対象を操作するには、その配置を見つけ、何ができるかを確認し、操作を選ぶ必要がある。Clientはこのための基礎ツールとして、tree / inspect / invokeの3操作を提供する。

この3操作は、Protocolのobserve / fetch_interface / call_operationをそのまま公開したものではない。必要な取得、cache、観測整合性の管理はClientが引き受ける。Protocol interactionは3. Protocol、Clientの責務は4. Clientに従う。GUIやPTC / REPLなど、他のClientインターフェースの構成は、この3操作に制限しない。

基本的な利用モデル

AI向け操作	AIが行うこと	Clientが引き受けること
tree(path, depth)	indexableな対象の配置を見る	必要なdepthの観測とtree表示
inspect(path)	対象の説明とできることを知る	Object観測、Interface集合の解決、signature生成
invoke(target, interface, operation, arguments)	選択した操作を名前付き引数で呼ぶ	引数検証、観測との対応、validator、Protocol requestと結果の処理

例えばinspectが受け取るのは、Interface参照ではなくObjectのpathである。Clientはそのpathに必要なobserveと複数のfetch_interfaceを内部で行う。AI向け操作とProtocol interactionは、一対一には対応しない。

Inspectで見つけたOperationは、invokeで呼ぶ。Operationごとに新しいToolを登録することはない。

大量のObjectを発見する場合も、各ドメインのObjectが公開するlist / search / query等をinspectし、invokeする。件数制限、検索条件、ページング等は、それぞれのOperationがドメインに応じて管理する。発見方法が増えても、基礎ツールは3操作のままである。

tree: indexableな配置を見る

tree(path, depth)は、起点をdepth 0として、指定depth内のindexableなツリーを全量取得・表示する。「全量」の範囲は、指定した起点・depth・主体に公開されたindexableな範囲であり、Worldspace全体ではない。

• 必要なcoverageを持つ観測を再利用できる。不足する場合はClientがobserveで取得する。
• 名前、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の条件に従う。

inspect: 対象の説明とできることを知る

inspect(path)は、そのpathで公開されているObjectの説明と操作を返す。AIは、treeでまだ見ていないpathも直接指定できる。

Pathをtree、会話、Operation結果のどこから知ったかは事前条件にしない。Clientが未観測であっても、Known Spaceにないことだけを理由に拒否せず、現在のHostの公開状態に従って観測する。

Clientは、保持済みの観測を使い、不足する情報を取得する。

1. 対象pathのObject。対象だけが必要ならobserveのdepth = 0を使用する。
2. Objectが公開するInterface参照のordered set。
3. 表示対象のInterfaceに対応する、取得・検証済みのDescriptor。

この情報から、Objectの説明とInterfaceごとの操作を提示する。AIにObjectのobserve、Interface参照の抽出、個別のfetchという手順を管理させない。ただし、Objectの本文やドメインmetadataまで暗黙に読み込むことはなく、それらは対象のOperationで取得する。

表示に必要な情報

• 対象のpathと、公開されているObjectの説明。
• InterfaceとOperationの対応。
• Operation名、短い用途説明、名前付き引数、必須性、引数・結果の型。
• 操作を理解するために必要な名前付き型・複合型の定義。

Clientは生のDescriptor JSONを返すだけでなく、検証済み情報からObject signatureとInterface signatureを生成する。表記は4.2. Text Viewに従う。同名Operationが複数Interfaceにあっても、一つへ平坦化したり、出所を失ったりしない。

Invokeへ渡すInterface参照とOperation名は、表示とは別に保持する。表示textを再parseして呼出先を決めず、Interfaceの未展開や取得失敗も「操作が存在しない」と誤表示しない。

Signatureの配置、詳細表示、表示対象を選ぶ具体的なTool引数は固定しない。一方、個々のsignatureはText Viewの全宣言の表示規則に従う。表示側でInterface内部を切り詰めない。

invoke: 選んだ操作を実行する

invoke(target, interface, operation, arguments)は、対象ObjectのInterfaceとOperationを明示して呼び出す。同じObjectの複数Interfaceに同名Operationがあり得るため、Interfaceも選ぶ必要がある。

targetで指定するのは対象Objectのpathである。Protocolのvalidator付きTargetをAIに組み立てさせるものではない。argumentsはparameter declarationに従う名前付きfieldのrecordであり、位置引数ではない。引数のないOperationには空のrecordを渡す。

Interfaceの選択はAIへ示すが、Descriptorの取得手順はAIに管理させない。選択するInterfaceは、絶対scopeとlocal nameの組で識別する。AdapterがText Viewの短縮表記を入力として受ける場合は、入力境界で構造化参照へ変換し、Operation名を独立して保持する。Scopeの省略には明示contextが必要であり、対象pathからの推測や相対scopeの解決はしない。短縮表記のstringをProtocolへそのまま送らない。

ClientはObjectとDescriptorの観測を保持して引数を検証し、path、Object validator、Interface参照とvalidator、観測に存在するscope_refをProtocol requestへ設定する。AIにvalidatorやscope Objectのrefを取得・コピー・更新させず、同一性管理やvalidatorをsignatureにも含めない。refのないscopeではidentityによる差し替え検出ができないことを許容し、AIへ代替identityを要求しない。

Interfaceが表示されていても、それだけで実行権限があるとは限らない。Pathを知っていることも同様である。Hostは呼出時の公開状態、権限、capability、実行条件を検証し、Clientは返されたresultをDescriptorに従って検証してから提示する。

再観測とOperationの再実行は、別の処理である。Stale、取消、拒否、結果不明などは、ProtocolとClientのFailure handlingに従って扱う。結果不明のOperationを自動再実行せず、Operation名からread / writeやretry可否を推測しない。

Pathの発見と移動

AIはtree、会話で示されたpath、Operation結果のentryなどから次の対象を知ることができる。しかし、pathを知ること、ClientがObjectを観測・保持すること、indexable edgeも観測することは別である。Clientの取得・保持・提示の分離に従い、未観測のpathは必要になった時点でinspectできる。

Clientが保持する情報と、AIに表示済みの情報も一致する必要はない。Treeの取得でObject情報を保持していても、AIには名前と構造だけを見せ、詳しい説明と操作はinspectで提示できる。

Operation結果のentry型pathは、次の対象への参照としてそのまま提示できる。全件を即時に観測したり再帰展開したりする必要はなく、AIが必要なpathを選んでinspectするときに観測できる。Entryの抽出はDescriptorの型に従い、普通のstringを内容だけからpathと推測しない。結果のentryを観測・保持しても、それだけではindexable edgeを追加しない。

Clientが付随的にentryを取得する場合、参照先の取得失敗を元のOperationの失敗と混同しない。すでに成功したOperationを、参照先が取得できなかったために失敗扱いして再実行させてはならない。

Tool bindingと表示

tree、inspect、invokeという小文字表記は操作の呼称であり、providerごとのTool登録名の大文字・小文字やProtocol名の接頭辞を規定しない。AI providerがTool schemaを要求する場合は、Client adapterが3操作のschemaを提供する。Hostへprovider固有のschemaを要求したり、取得したDescriptorごとにToolを追加登録したりしない。DescriptorはClient内部のOperation validationとsignature生成に使う。

Treeのtext layout、depth等のdefault、inspectの表示選択引数、Tool response envelopeには、共通の具体schemaを定めない。各bindingは、それらを提供するときにAIへ明示する契約として定め、3操作の意味は変えない。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利用によって、権限・観測整合性・結果不明の扱いを弱めない。