docs: define operation IDL and entry discovery

4.1-ai-tools-example.md

@@ -10,7 +10,7 @@ AI用Toolsは、WIP ClientがAIへ提供する想定インターフェースで
 
 `discover(scope, query)` は、Clientが保持するDiscoverable Spaceから目的に関連するエントリを探す。
 
-検索対象は、Hostから`fetch_tree`によって取得されたindexableなエントリ公開情報に限定する。OperationやLinkによって新たに発見されたエントリはKnown Spaceには追加されるが、それだけでは`discover`の検索対象にはならない。
+検索対象は、Hostから`fetch_tree`によって取得されたindexableなエントリ公開情報に限定する。Operationによって新たに発見されたentry pathは、一時的な結果として扱うか、取得してKnown Spaceへ保持できるが、それだけでは`discover`の検索対象にはならない。
 
 `discover`はドメインデータを検索する操作ではない。Issue本文やRAG corpusなどを検索する場合は、その能力を持つObjectのOperationを`invoke`する。
 
@@ -23,14 +23,17 @@ Objectのドメインデータをpropertiesとして直接公開することは
 例えばIssueでは、次のような操作が示され得る。
 
 - `read_body()` — 本文を読む。
-- `get_metadata()` — 期日、担当者、ラベル、関連ObjectへのLinkなどを取得する。
+- `get_metadata()` — 期日、担当者、ラベルなどを取得する。
+- `get_related_items()` — 関連Objectのentry pathを取得する。
 - `close(reason: string)` — 理由を添えてIssueをクローズする。
 
 Operationはシグネチャだけでなく、AIが用途を判断できる短いdescriptionを持つ。長文ドキュメントを埋め込むことは想定しない。
 
+Operationのinput / output schemaは[WIP IDL](draft/wip-idl.md)として取得する。ClientはIDLをparseし、利用するAI providerが要求するTool schemaへ変換する。JSON Schema等への変換はAI向けClient adapterの責務であり、HostがWIP interfaceとして提供する必要はない。
+
 ## `invoke`
 
-`invoke(target, operation, input)` は、`inspect`によって発見したOperationを実行する。
+`invoke(target, operation, input)` は、`inspect`によって発見したOperationを実行する。`input`はOperationのWIP IDLで定義された名前付きfieldを持つrecordであり、位置引数は用いない。引数を持たないOperationには空のrecordを渡す。
 
 PTC / REPL bindingでは、通常のメソッド呼び出しへ投影してよい。
 
@@ -46,13 +49,12 @@ AIが新しいエントリを知る経路は複数ある。
 
 - `discover`によってDiscoverable Spaceから見つける。
 - Known Space上の既知エントリを辿る。
-- Operationの結果としてエントリまたはエントリツリーを受け取る。
-- Operation結果に含まれるLinkから別エントリを知る。
+- Operation Resultの`entry`型としてpathを受け取る。
 
-新たに発見されたエントリの保持、Treeへの統合、indexableな範囲の管理はClientの責務とし、このページではAI向けToolの意味論だけを扱う。
+ClientはOperation Resultからentry pathを抽出し、必要なpathを`fetch`または`fetch_tree`する。新たに取得したエントリの保持、Treeへの統合、indexableな範囲の管理はClientの責務とし、このページではAI向けToolの意味論だけを扱う。
 
 ## ドメイン検索
 
 全文検索、semantic retrieval、外部API検索などはWIP固有のToolにはしない。
 
-検索能力を持つObjectが`query`や`search`などのOperationを公開し、AIはそれを`invoke`する。結果としてエントリやエントリツリーが返された場合、それらはClientを通して新たなKnown Spaceとして利用可能になる。
+検索能力を持つObjectが`query`や`search`などのOperationを公開し、AIはそれを`invoke`する。結果として`entry`型のpathが返された場合、Clientは必要なpathを取得し、一時的な発見結果として利用するかKnown Spaceへ保持できる。