@world-engines/protocol-ts 0.1.0-alpha.0

package/dist/gen/v1/mcp.d.ts

@@ -0,0 +1,373 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+import { ErrorInfo } from "./common.js";
+/**
+ * 渐进式召回的截断原因。调用方必须把 UNSPECIFIED 与 truncated=false 绑定；
+ * truncated=true 时原因必须非 UNSPECIFIED，禁止把预算耗尽伪装成完整结果。
+ */
+export declare enum RetrievalTruncationReason {
+    RETRIEVAL_TRUNCATION_REASON_UNSPECIFIED = 0,
+    RETRIEVAL_TRUNCATION_REASON_BYTE_BUDGET = 1,
+    RETRIEVAL_TRUNCATION_REASON_RESULT_LIMIT = 2,
+    RETRIEVAL_TRUNCATION_REASON_DEADLINE = 3,
+    UNRECOGNIZED = -1
+}
+export declare function retrievalTruncationReasonFromJSON(object: any): RetrievalTruncationReason;
+export declare function retrievalTruncationReasonToJSON(object: RetrievalTruncationReason): string;
+export declare enum RetrievalMatchArm {
+    RETRIEVAL_MATCH_ARM_UNSPECIFIED = 0,
+    RETRIEVAL_MATCH_ARM_VECTOR = 1,
+    RETRIEVAL_MATCH_ARM_KEYWORD = 2,
+    RETRIEVAL_MATCH_ARM_RELATIONAL = 3,
+    RETRIEVAL_MATCH_ARM_TRIE = 4,
+    RETRIEVAL_MATCH_ARM_NGRAM = 5,
+    UNRECOGNIZED = -1
+}
+export declare function retrievalMatchArmFromJSON(object: any): RetrievalMatchArm;
+export declare function retrievalMatchArmToJSON(object: RetrievalMatchArm): string;
+export declare enum RecallRealworldProvenance {
+    RECALL_REALWORLD_PROVENANCE_UNSPECIFIED = 0,
+    RECALL_REALWORLD_PROVENANCE_HAS_PROTOTYPE = 1,
+    RECALL_REALWORLD_PROVENANCE_FICTIONAL = 2,
+    UNRECOGNIZED = -1
+}
+export declare function recallRealworldProvenanceFromJSON(object: any): RecallRealworldProvenance;
+export declare function recallRealworldProvenanceToJSON(object: RecallRealworldProvenance): string;
+export declare enum McpTool {
+    MCP_TOOL_UNSPECIFIED = 0,
+    /** MCP_TOOL_GRAPH_QUERY - 玩家图向量 db 查询 */
+    MCP_TOOL_GRAPH_QUERY = 1,
+    /** MCP_TOOL_VECTOR_SEARCH - 向量近邻搜索 */
+    MCP_TOOL_VECTOR_SEARCH = 2,
+    /** MCP_TOOL_FULL_TEXT_SEARCH - 全文搜索 */
+    MCP_TOOL_FULL_TEXT_SEARCH = 3,
+    /** MCP_TOOL_ENTITY_GET - 按 id 取实体 */
+    MCP_TOOL_ENTITY_GET = 4,
+    /** MCP_TOOL_RELATION_LIST - 列实体的关系 */
+    MCP_TOOL_RELATION_LIST = 5,
+    /** MCP_TOOL_SAVE_COMMIT_LOCK - 存档冲突仲裁前置锁 */
+    MCP_TOOL_SAVE_COMMIT_LOCK = 6,
+    /** MCP_TOOL_WORLD_EVENT_EMIT - 写入世界事件 */
+    MCP_TOOL_WORLD_EVENT_EMIT = 7,
+    /** MCP_TOOL_GRAPH_RAG_SEARCH - GraphRAG 组合检索 */
+    MCP_TOOL_GRAPH_RAG_SEARCH = 8,
+    /** MCP_TOOL_EXPLORE_WORLD - director 高层探索 服务端拦截路由到子代理 不反向穿透客户端 */
+    MCP_TOOL_EXPLORE_WORLD = 9,
+    /** MCP_TOOL_PROPOSE_ACTION - 多人场景行动提案 Phase2 接线 服务端拦截不反向穿透客户端 */
+    MCP_TOOL_PROPOSE_ACTION = 10,
+    /** MCP_TOOL_SCENE_CLAIM - 场景占用声明 客户端 WS 帧驱动 非导演工具 (ADR-0058 wire 冻结保留 ADR-0059 导演只用 propose_action) */
+    MCP_TOOL_SCENE_CLAIM = 11,
+    /** MCP_TOOL_TURN_ACQUIRE - 回合获取 客户端 WS 帧驱动 非导演工具 */
+    MCP_TOOL_TURN_ACQUIRE = 12,
+    UNRECOGNIZED = -1
+}
+export declare function mcpToolFromJSON(object: any): McpTool;
+export declare function mcpToolToJSON(object: McpTool): string;
+/**
+ * 反向 MCP 工具的连接级能力声明。所有哈希均为 64 位小写十六进制 SHA-256。
+ * max_request_bytes/max_result_bytes 必须非零；timeout_ms 必须非零。
+ * read_only=false 的 effect 工具若 schema/hash 不一致，服务端必须 fail closed。
+ */
+export interface McpToolCapability {
+    tool_name: string;
+    contract_version: number;
+    read_only: boolean;
+    idempotent: boolean;
+    max_request_bytes: number;
+    max_result_bytes: number;
+    input_schema_sha256: string;
+    output_schema_sha256: string;
+    supports_cancel: boolean;
+    /** v1 固定为 false；在新增独立 progress frame 前禁止声明 true。 */
+    supports_progress: boolean;
+    timeout_ms: number;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 客户端在 Hello 中发送的连接级不可变能力清单。
+ * generation 在同一逻辑客户端每次清单变化时单调递增；tools 按 tool_name UTF-8 字节序排序且不重复。
+ * manifest_sha256 绑定 generation、contract_version 与完整规范化 tools 清单。
+ */
+export interface McpSessionCapabilities {
+    generation: string;
+    contract_version: number;
+    tools: McpToolCapability[];
+    manifest_sha256: string;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 服务端在 HelloAck 中返回的能力交集。accepted_tools 只能来自客户端清单与服务端清单的严格交集。
+ * manifest_sha256 必须逐字回显已校验的客户端 manifest；legacy=true 时 accepted_tools 必须为空。
+ */
+export interface McpSessionCapabilityAck {
+    generation: string;
+    contract_version: number;
+    accepted_tools: McpToolCapability[];
+    manifest_sha256: string;
+    legacy: boolean;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/** MCP 反向穿透 服务端发起调用 客户端 wasm 执行后回包 */
+export interface McpToolCall {
+    call_id: string;
+    tool_name: string;
+    arguments_json: Uint8Array;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+export interface McpToolResult {
+    call_id: string;
+    ok: boolean;
+    result_json: Uint8Array;
+    error?: ErrorInfo | undefined;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 一条批量召回查询。query_index 在同一请求中必须唯一。
+ * query_embedding_f32_le 是严格 little-endian IEEE-754 Float32 连续字节；长度必须等于
+ * embedding_dimension * 4，且每个分量必须是 finite（拒绝 NaN/Inf）。
+ * descriptor_sha256 必须是 64 位小写十六进制，并与批请求 descriptor_sha256 完全一致。
+ * content_byte_budget 是该 query 的 summaries 作为父 RetrieveBatchResponse.summaries repeated
+ * occurrence 编码时占用的 protobuf 字节子预算：每项均包含父字段 tag、length prefix 与完整
+ * RecallSummaryV1 encoded bytes。它必须非零且不大于所属批请求 content_byte_budget。
+ */
+export interface RetrievalQueryV1 {
+    query_index: number;
+    query_embedding_f32_le: Uint8Array;
+    embedding_dimension: number;
+    descriptor_sha256: string;
+    query_text: string;
+    fields: string[];
+    edge_kinds: string[];
+    depth: number;
+    content_byte_budget: number;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 一次只读快照上的批量召回。operation_id 非空且在重试中保持不变；
+ * runtime_scope_sha256/descriptor_sha256 均为 64 位小写十六进制。
+ * queries 必须按 query_index 严格升序且无重复。content_byte_budget 是完整
+ * RetrieveBatchResponse protobuf message encoded byte length 的硬上限，包含响应内全部 field tag、
+ * length prefix、varint/fixed、repeated/map 嵌套、content_bytes 与预算回显字段本身；只排除外层
+ * McpToolResult、WS frame 与加密 framing。content_byte_budget/turn_remaining_content_bytes 必须
+ * 非零；turn remaining 不得超过单 turn 硬上限 1048576，content budget 必须
+ * <= min(262144, turn_remaining_content_bytes)，每条 query 的子预算还必须 <= content budget。
+ * turn remaining 不是 actor 授权值：它必须逐值等于 host-owned TurnWorkBudget 在当前 active
+ * connection/turn ledger 中的剩余额度，并与 operation_id/runtime scope 在同一原子 CAS 内校验、
+ * 预留和最终扣减；不匹配、ledger 不存在或 CAS 失败均必须在查询前 fail closed。外层 WS 独立
+ * 执行传输帧上限，不能替代本预算。
+ */
+export interface RetrieveBatchRequest {
+    operation_id: string;
+    runtime_scope_sha256: string;
+    descriptor_sha256: string;
+    queries: RetrievalQueryV1[];
+    content_byte_budget: number;
+    turn_remaining_content_bytes: number;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 单条结构化命中原因。arm 必须非 UNSPECIFIED，rank 从 1 开始，score 必须 finite。
+ * matched_terms 与 relation_edge_kinds 必须去重并按 UTF-8 字节序稳定排序；不适用时为空。
+ */
+export interface RecallMatchReasonV1 {
+    arm: RetrievalMatchArm;
+    rank: number;
+    score: number;
+    matched_terms: string[];
+    relation_edge_kinds: string[];
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 摘要的最小来源证据。seed_entity_id/hop 记录图扩展路径；source_message_id/turn_id/write_seq
+ * 记录玩家世界写入来源，作者基线实体可省略这三项。realworld_provenance 与 prototype_name
+ * 遵循 ADR-0131；只有 HAS_PROTOTYPE 可携带非空 prototype_name。
+ */
+export interface RecallProvenanceV1 {
+    seed_entity_id: string;
+    hop: number;
+    source_message_id: string;
+    turn_id: string;
+    write_seq: string;
+    realworld_provenance: RecallRealworldProvenance;
+    prototype_name: string;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 渐进披露第一阶段返回的最小摘要。why_matched 与 provenance 均必须非空并稳定排序，
+ * 第一阶段必须能结构化审计“为何命中”及“事实来自哪里”。field_values_utf8 的值是对应字段的
+ * 完整 UTF-8 字节，edge_lists_utf8_json 的值是按稳定键排序的 canonical UTF-8 JSON 数组；
+ * 禁止截断单个 UTF-8 值或 JSON 值。why_matched 按 arm 数值、rank、UTF-8 字节序排序；
+ * provenance 按 seed_entity_id、hop、source_message_id 的 UTF-8 字节序排序。content_sha256
+ * 绑定除自身以外的全部规范化内容，包含 why_matched/provenance，但不绑定 protobuf framing。
+ */
+export interface RecallSummaryV1 {
+    query_index: number;
+    recall_id: string;
+    entity_id: string;
+    entity_kind: string;
+    display_name: string;
+    summary: string;
+    relevance_score: number;
+    available_fields: string[];
+    available_edge_kinds: string[];
+    materialized_depth: number;
+    field_values_utf8: {
+        [key: string]: Uint8Array;
+    };
+    edge_lists_utf8_json: {
+        [key: string]: Uint8Array;
+    };
+    content_sha256: string;
+    why_matched: RecallMatchReasonV1[];
+    provenance: RecallProvenanceV1[];
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+export interface RecallSummaryV1_FieldValuesUtf8Entry {
+    key: string;
+    value: Uint8Array;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+export interface RecallSummaryV1_EdgeListsUtf8JsonEntry {
+    key: string;
+    value: Uint8Array;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * summaries 先按 query_index、再按稳定 recall_id 排序。content_bytes 必须等于回填最终字段值后
+ * RetrieveBatchResponse.encode(response).finish().byteLength，包含本响应内全部 protobuf framing、
+ * content_bytes 与 content_byte_budget 自身，只排除外层 McpToolResult、WS frame 与加密 framing。
+ * producer 必须迭代编码直到 content_bytes 达到 fixed point，再 readback 重编码确认相等；consumer
+ * 必须重编码核验相等后才按该值原子扣减 turn remaining。content_bytes 必须
+ * <= content_byte_budget，且 content_byte_budget 必须原样回显已校验的请求预算。
+ * operation_id/runtime_scope_sha256/descriptor_sha256 必须逐值等于原请求；continuation_token 只能由
+ * host 签发并绑定上述三元组、下一 query/recall 游标和预算 ledger，actor 不能自造或跨 scope 重放。
+ * truncated=false 时 reason 必须 UNSPECIFIED、continuation_token 为空且 omitted_summary_count=0；
+ * truncated=true 时 reason 必须非 UNSPECIFIED，并在完整 summary 边界停止。若同一 query 尚有
+ * 后续结果，continuation_token 必须非空；否则 next_query_index 指向首个未开始的 query。
+ */
+export interface RetrieveBatchResponse {
+    operation_id: string;
+    runtime_scope_sha256: string;
+    descriptor_sha256: string;
+    summaries: RecallSummaryV1[];
+    content_bytes: number;
+    truncated: boolean;
+    truncation_reason: RetrievalTruncationReason;
+    next_query_index?: number | undefined;
+    continuation_token: string;
+    omitted_summary_count: number;
+    content_byte_budget: number;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * 对第一阶段 recall_id 做受控展开。query_index、operation_id、runtime scope 与 descriptor
+ * 必须和原批请求/响应一致；recall_ids/fields/edge_kinds 均须非空、去重并稳定排序。
+ * content_byte_budget 是完整 RetrievalExpandResponse protobuf message encoded byte length 的硬上限，
+ * 采用与 RetrieveBatchRequest 完全相同的 framing/fixed-point 口径；turn remaining 同样只扣最终
+ * response encoded bytes。turn remaining 必须逐值等于同一 host-owned active connection/turn ledger，
+ * 并与本 operation/scope 做原子 CAS；actor 声明没有授权性。content budget 必须
+ * <= min(262144, turn remaining)，否则展开前 fail closed。continuation_token 必须是 host 签发且绑定
+ * operation_id、runtime_scope_sha256、descriptor_sha256、query_index、recall 游标与预算 ledger 的原 token。
+ */
+export interface RetrievalExpandRequest {
+    operation_id: string;
+    runtime_scope_sha256: string;
+    descriptor_sha256: string;
+    query_index: number;
+    recall_ids: string[];
+    fields: string[];
+    edge_kinds: string[];
+    depth: number;
+    content_byte_budget: number;
+    continuation_token: string;
+    turn_remaining_content_bytes: number;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+/**
+ * summaries 只包含本次请求 recall_ids 的完整原子投影，并保持请求顺序。
+ * 截断只能发生在完整字段值、完整 edge list 或完整 summary 边界；任何部分 UTF-8/JSON
+ * 值都必须 fail closed。truncated 字段组合规则与 RetrieveBatchResponse 相同。content_bytes 必须
+ * 等于回填最终值后 RetrievalExpandResponse.encode(response).finish().byteLength，并执行同样的
+ * fixed-point/readback 校验；它必须 <= content_byte_budget，且预算原样回显已校验的展开请求值。
+ * response 的 operation_id/runtime_scope_sha256/descriptor_sha256/query_index 必须逐值等于请求；
+ * 后续 continuation_token 只能由 host 续签到同一绑定，禁止跨 operation/scope/descriptor 重放。
+ */
+export interface RetrievalExpandResponse {
+    operation_id: string;
+    runtime_scope_sha256: string;
+    descriptor_sha256: string;
+    query_index: number;
+    summaries: RecallSummaryV1[];
+    content_bytes: number;
+    truncated: boolean;
+    truncation_reason: RetrievalTruncationReason;
+    continuation_token: string;
+    omitted_field_count: number;
+    omitted_edge_count: number;
+    omitted_summary_count: number;
+    content_byte_budget: number;
+    _unknownFields?: {
+        [key: number]: Uint8Array[];
+    } | undefined;
+}
+export declare const McpToolCapability: MessageFns<McpToolCapability>;
+export declare const McpSessionCapabilities: MessageFns<McpSessionCapabilities>;
+export declare const McpSessionCapabilityAck: MessageFns<McpSessionCapabilityAck>;
+export declare const McpToolCall: MessageFns<McpToolCall>;
+export declare const McpToolResult: MessageFns<McpToolResult>;
+export declare const RetrievalQueryV1: MessageFns<RetrievalQueryV1>;
+export declare const RetrieveBatchRequest: MessageFns<RetrieveBatchRequest>;
+export declare const RecallMatchReasonV1: MessageFns<RecallMatchReasonV1>;
+export declare const RecallProvenanceV1: MessageFns<RecallProvenanceV1>;
+export declare const RecallSummaryV1: MessageFns<RecallSummaryV1>;
+export declare const RecallSummaryV1_FieldValuesUtf8Entry: MessageFns<RecallSummaryV1_FieldValuesUtf8Entry>;
+export declare const RecallSummaryV1_EdgeListsUtf8JsonEntry: MessageFns<RecallSummaryV1_EdgeListsUtf8JsonEntry>;
+export declare const RetrieveBatchResponse: MessageFns<RetrieveBatchResponse>;
+export declare const RetrievalExpandRequest: MessageFns<RetrievalExpandRequest>;
+export declare const RetrievalExpandResponse: MessageFns<RetrievalExpandResponse>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+type Exact<P, I extends P> = P extends Builtin ? P : P & {
+    [K in keyof P]: Exact<P[K], I[K]>;
+} & {
+    [K in Exclude<keyof I, KeysOfUnion<P>>]: never;
+};
+interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create<I extends Exact<DeepPartial<T>, I>>(base?: I): T;
+    fromPartial<I extends Exact<DeepPartial<T>, I>>(object: I): T;
+}
+export {};