@things-factory/ai-client-base 10.1.20 → 10.1.26

package/server/service/tool-registry/types.ts

@@ -12,7 +12,7 @@
  *
  * 설계 원칙:
  *   - **카테고리별 builder 시그니처 다양성을 통합**: read 는 (args, ctx) → any,
- *     write 는 (args, components) → BoardEditOp[], action 은 (args) → BoardActionOp.
+ *     write 는 (args, components) → SceneEditOp[], action 은 (args) → SceneActionOp.
  *     하나의 ToolSpec 에 모든 시그니처를 union 으로 담지 않고, 카테고리에 맞는
  *     builder 만 채우면 되도록 카테고리별 sub-interface 분리.
  *   - **kind 필드로 자가 분류**: registry 가 isReadTool / isWriteTool 자동 도출.
@@ -21,12 +21,40 @@
  *     점진적으로 다른 hardcoded tool 들 (addComponent / alignComponents 등) 도
  *     같은 registry 로 흡수 가능. 한 단계씩 byte-단위 동등성 단위 테스트 보장.
  */
-// 본 registry 는 LLM tool 노출 plugin point 에 한정되므로 도메인 type (BoardEditOp,
-// BoardActionOp 등) 은 알지 않는다. builder return 은 unknown 으로 두고, 카테고리
-// dispatcher (board-ai 의 toolCallToBoardEditOp / toolCallToBoardActionOp 등) 가 자기
+// 본 registry 는 LLM tool 노출 plugin point 에 한정되므로 도메인 type (SceneEditOp,
+// SceneActionOp 등) 은 알지 않는다. builder return 은 unknown 으로 두고, 카테고리
+// dispatcher (board-ai 의 toolCallToSceneEditOp / toolCallToSceneActionOp 등) 가 자기
 // 도메인 type 으로 좁힌다. 사용자가 ToolSpec<TWrite, TAction> generic 까지 정밀화하면
 // 좋겠지만, 11~50 개 spec 마다 type 인자 전파가 부담이라 unknown 으로 합의.
 
+// ── ToolCallContext — what the neutral conversation door hands a registered tool (A3) ──
+
+/**
+ * What `registryAssistantChat` — the door apps use (`assistantChat`, ADR-0061 decision 0) — hands a
+ * registered tool when it runs.
+ *
+ * `state` and `host` sit side by side. The twin's space tools read `ctx.state.host` while this door
+ * passed `ctx.host`, so they never saw the space; the two are never merged into one object.
+ *
+ * The board product's door (board-ai) passes its own shape and is not part of this contract.
+ */
+export interface ToolCallContext {
+  /** The request state the server built — domain, user, tx. The only basis for authorization. */
+  state: any
+  /**
+   * The client's `AssistantMode.hostContext`, passed through as is. **Untrusted** — a tool that reads
+   * an id from it checks that the id belongs to the caller's tenant. `{}` when none was sent.
+   */
+  host: Record<string, any>
+  /** The conversation's mode. Filled once modes are registered on the server (A2); absent until then. */
+  mode?: ToolCallMode
+}
+
+export interface ToolCallMode {
+  kind: string
+  target?: string
+}
+
 // ── 카테고리별 builder 시그니처 ──────────────────────────────────────
 
 /**
@@ -48,13 +76,12 @@ export interface ReadToolContext {
   /** 이외 주입은 카테고리별로 자유. tool 등록자가 type 좁힐 수 있도록 unknown 으로 보존. */
   [k: string]: any
 }
-
 /**
  * Write tool — domain edit op 발생. host 가 patch 적용 후 영속화.
  * 예: board-ai 의 addComponent / setFill / modifyBoard.
  *
  * builder 의 return type 은 unknown 으로 둔다 — 도메인별 dispatcher (예: board-ai 의
- * toolCallToBoardEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.
+ * toolCallToSceneEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.
  */
 export type WriteToolBuilder = (
   args: any,
@@ -65,13 +92,12 @@ export interface WriteToolContext {
   components?: ReadonlyArray<any>
   [k: string]: any
 }
-
 /**
  * Action tool — ephemeral scene 조작 (select / center / fit / sceneMode).
  * board model 변경 X, undo 영향 X. host 가 별도 channel 로 적용.
  *
- * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToBoardActionOp)
- * 가 자기 BoardActionOp 으로 cast.
+ * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToSceneActionOp)
+ * 가 자기 SceneActionOp 으로 cast.
  */
 export type ActionToolBuilder = (args: any) => any | null
 
@@ -91,9 +117,25 @@ export interface ExternalToolContext {
   state?: any
   [k: string]: any
 }
-
 // ── ToolSpec — 카테고리별 변형 ──────────────────────────────────────
 
+/**
+ * The privilege a tool requires — the same `category`/`privilege` the tool's GraphQL door declares
+ * (`@privilege(category, privilege, owner?, super?)`), so the fields mirror `PrivilegeObject`.
+ *
+ * A tool is not a new door; it is another way into a door that already exists. A tool that creates
+ * a Board goes through the privilege that creating a Board already needs. Minting an AI-only
+ * privilege name would put two doors on one effect, and one of them would end up looser.
+ */
+export interface ToolPrivilege {
+  category: string
+  privilege: string
+  /** Domain owners pass without the privilege — mirror the door's `domainOwnerGranted`. */
+  owner?: boolean
+  /** Super users pass without the privilege — mirror the door's `superUserGranted`. */
+  super?: boolean
+}
+
 /**
  * 모든 ToolSpec 공통 메타데이터.
  */
@@ -109,6 +151,14 @@ export interface ToolSpecBase {
   themeNote?: string
   /** JSON Schema for parameters — LLM tool schema 에 그대로 노출. */
   schema: any
+  /**
+   * The privilege a caller needs before this tool is offered or run. See `ToolPrivilege`.
+   *
+   * Expected for `write`, `action` and `external` — registration records a
+   * `tool-privilege-undeclared` warning for one without it (A1 stage one). A `read` tool without it is
+   * offered on domain membership alone, and its builder must check what it reads.
+   */
+  privilege?: ToolPrivilege
 }
 
 export interface ReadToolSpec extends ToolSpecBase {