qlogicagent 2.18.6 → 2.18.8

package/dist/types/host-contract/index.d.ts

@@ -0,0 +1,1475 @@
+/**
+ * Gateway Host 接口冻结稿(契约包)—— 单一事实源:docs/agent-supervision-interfaces-freeze.md
+ *
+ * 本文件是 freeze §0-§4/§3.5 的 TypeScript 落型(2026-07-09 冻结,G3′/A1-A3 已闭环;
+ * 2026-07-10 Route B 补遗 X1-X7 入约:§13 通知 sink + host-state wire、ProfileConfigService keyId
+ * 正名 + revealKey、MemoryProfileService 库面收口——单一事实源 agent-supervision-authority-migration-spec.md)。
+ * 消费方:xiaozhiclaw-runtime gateway(实现方)+ qlogicagent agent 侧(GatewayDelegateRelay client)。
+ * 冻结纪律:接口不随实现漂移;任何字段/签名改动必须回评审(review-gate-checklist),
+ * S2 施工 lane 不得自行修改本文件。
+ *
+ * 标注 [S1 补定] 的辅助类型是 freeze 引用但未给定义的最小结构,属 S1 评审点,
+ * 其字段以 freeze 正文/recon 注释为据;实现 lane 负责与现状 store 形状做映射。
+ */
+export * from "./provider-profile.js";
+/** agent 逻辑身份(小智自身也是一个 agentId="qlogicagent")。自身 vs 第三方仅由此值决定(F2)。 */
+export type AgentId = string;
+/** 确定性派生的项目主键(freeze §11.4#2,抄 VSCode getWorkspaceId)。绝不随机、绝不裸路径。 */
+export type ProjectId = string;
+/** 会话稳定身份(创建即恒定,session-identity-alignment-spec)。 */
+export type CanonicalSessionId = string;
+/**
+ * Gateway-resolved model purposes. This is the single vocabulary shared by
+ * profile materialization and the agent-side model registry.
+ */
+export declare const MODEL_PURPOSES: readonly ["textGeneration", "smallModel", "stt", "tts", "imageGeneration", "imageUnderstanding", "videoGeneration", "videoUnderstanding", "threeDGeneration", "embedding", "voiceClone", "musicGeneration", "realtimeAudio", "realtimeVideo"];
+export type ModelPurpose = (typeof MODEL_PURPOSES)[number];
+/** 能力实例种类。 */
+export type MemberKind = "chat" | "product-leader" | "product-worker" | "goal-leader" | "solo-racer" | "workflow-node";
+/**
+ * 能力实例的结构化 handle(freeze §11.4#3,抄 VSCode ExtensionRunningLocation)。可判等、可字符串化。
+ * 取代今天各特性自造的 memberId 串(chat-* / product-*:*:* / goal-*:leader / solo-* / workflow-agent-*)。
+ */
+export interface MemberHandle {
+    kind: MemberKind;
+    /** 归属上下文:canonicalSessionId | productId | goalRunId | workflowRunId */
+    owner: string;
+    /** 人类可读名(instance 名/leader/worker 等) */
+    name: string;
+    /** 实例序号(≈ VSCode affinity;同种多实例区分) */
+    seq: number;
+}
+/** 稳定字符串键(路由/日志/存储用)。字段含分隔符即 fail-loud,绝不静默错路由。 */
+export declare function memberKey(h: MemberHandle): string;
+export declare function memberEquals(a: MemberHandle, b: MemberHandle): boolean;
+/**
+ * 一次委派/回合所需的会话上下文,由 SessionProjectService 解析后传入 Supervisor。
+ * cwd/resumeNativeId 不再由调用点各自拼装,而是从会话面权威解析。
+ */
+export interface SessionContext {
+    canonicalSessionId: CanonicalSessionId;
+    projectId: ProjectId;
+    /** 项目/worktree 工作目录 */
+    cwd: string;
+    /** 仅 native-cwd agent(codex/claude)有意义(freeze §11.4#5:传输层重连令牌,不承担状态恢复) */
+    resumeNativeId?: string;
+}
+/** sendTurn 的统一返回(freeze §11.1:消灭"外部对象 / 内部字符串"双形态)。 */
+export interface TurnResult {
+    content: string;
+    stopReason?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /** 仅诊断,永不进入下游解析输入 */
+    diagnostics?: unknown;
+}
+/** agent 实例存活/失败状态(freeze §5.1 判活 + §5.3 fail-loud)。 */
+export type AgentInstanceState = "starting" | "ready" | "busy" | "unresponsive" | "exited";
+/**
+ * 结构化失败归类(freeze §4 E3:失败一律结构化明示,不得降级成裸 error 串)。
+ * UNKNOWN = 无法归类时的显式兜底:禁止硬塞错误 code,也禁止因归不了类降级成裸串。
+ */
+export type LifecycleCode = "CANCELLED" | "PROCESS_EXIT" | "HEARTBEAT_TIMEOUT" | "TURN_TIMEOUT" | "UNKNOWN";
+/**
+ * 确定性派生 projectId —— host-contract leaf 内的唯一实现(project-id.ts):
+ * sha256(resolve(workspaceDir).toLowerCase()).hex[:16]。
+ * 两端(gateway/agent)共用同一实现,零协商对齐;绝不允许第二份实现(否则 projectData 键漂移=数据全丢)。
+ */
+export { deriveProjectId } from "./project-id.js";
+/** 三态鉴权(llmrouter 注 sk-qllm / direct 厂商 key / oauth)解析后的结果,注入 spawn env。 */
+export interface ResolvedCredentials {
+    mode: "llmrouter" | "direct" | "oauth";
+    env: Record<string, string>;
+}
+export interface AgentSpec {
+    /** 决定 self-descriptor(cliPath=process.execPath)还是第三方 descriptor(F2) */
+    agentId: AgentId;
+    /** cwd/resume 由此来(不再由调用点拼) */
+    session: SessionContext;
+    systemPrompt?: string;
+    /** Gateway materialized, session-scoped non-secret model/permission profile. */
+    profile?: ResolvedSpawnProfile;
+    /** 三态鉴权由 CredentialResolver 按 agentId 解析后显式传入(freeze §6.2);不糊在 envOverrides,明文不进事件/日志 */
+    credentials?: ResolvedCredentials;
+    /** 仅非密的运行覆盖(如 solo 自身分支 QLOGICAGENT_WORKTREE_WORKDIR/SOLO_LEAN) */
+    envOverrides?: Record<string, string>;
+}
+/**
+ * 回合输入内容块(多模态)。**精确镜像 `AcpContentBlock`**(acp-protocol.ts:249)——
+ * 覆盖 text/image/video/audio/file 全五类;评审纠正:早期 text/image/resource 偏窄漏了 video/audio/file。
+ * 随 ACP block union 演进则同步扩(单一事实源=acp-protocol.ts)。
+ */
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    url: string;
+    mimeType?: string;
+} | {
+    type: "video";
+    url: string;
+    mimeType?: string;
+} | {
+    type: "audio";
+    url: string;
+    mimeType?: string;
+} | {
+    type: "file";
+    fileId: string;
+    mimeType?: string;
+    size?: number;
+};
+/**
+ * 每回合上下文(2026-07-09 S3 综合补遗 A1;权威形状 = agent 侧 buildSessionMeta + turnId)。
+ * 现瘦 sendTurn(prompt:string) 收不下这些(executeTurn:632 实证)→ 富签名。
+ * 列已核实的承重字段,实现期随 buildSessionMeta 真实形状对齐收紧类型。
+ */
+export interface PerTurnMeta {
+    turnId?: string;
+    permissions?: unknown;
+    reasoning?: unknown;
+    assistantId?: string;
+    activeSkills?: string[];
+    attachments?: unknown[];
+    mcpServers?: unknown[];
+    [k: string]: unknown;
+}
+/** sendTurn 富输入(S3 综合补遗 A1:取代裸 prompt:string,承多模态内容块 + per-turn meta)。 */
+export interface TurnInput {
+    messages: ContentBlock[];
+    meta?: PerTurnMeta;
+}
+/**
+ * 中立监督每个 agent 进程(小智自身 + 第三方对等),不嵌套。
+ * 判活=ACK 响应性(freeze §5.1,内部实现,不暴露方法名清单)。失败=结构化事件(§5.3),不静默杀。
+ *
+ * 不变式(冻结):
+ * - F1 单注册:一个 memberKey(handle) 至多一个实例(池化种类按 key 复用)。
+ * - F2 自身/第三方唯一由 agentId 决定;调用点不得再各自决定进程形态。
+ * - F3 结构隔离(§11.4#4):host 与 agent 引导入口物理不同、互不派生;删除运行时"拒 qlogicagent"闸。
+ * - F4 判活单轨(§5.1):仅 ACK 响应性,无 agent 心跳、无方法名豁免清单;unresponsive 是状态非杀。
+ * - F5 leader 硬约束(§11.4#6):kind∈{product-leader,goal-leader} 时 agentId 必须 ="qlogicagent",接口层硬校验拒第三方。
+ * - F6 判活地板 = "任意协议消息计活"(§6.3);我方 agent 可另加 ping 作补充、不作地板。
+ */
+export interface AgentSupervisor {
+    /** 确保 handle 对应实例在跑(不在则 spawn,池化种类复用)。能力 endpoint 由 CapabilityService 统一注入(C2)。 */
+    ensure(handle: MemberHandle, spec: AgentSpec): Promise<void>;
+    /**
+     * 向实例发一个回合,流式事件经 subscribe 回流,最终 resolve 统一 TurnResult。取代 processManager.sendTask。
+     * (S3 综合补遗 A1)input 富签名:承多模态内容块 + per-turn meta(permissions/reasoning/assistantId/
+     * activeSkills/attachments/mcpServers);裸 prompt:string 会丢这些回合上下文。
+     */
+    sendTurn(handle: MemberHandle, input: TurnInput, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<TurnResult>;
+    /**
+     * 订阅实例的回合/生命周期事件(delta/tool/approval/media/relay/state)。见 §4 事件契约。
+     * (S3 综合补遗 A4)granularity:leader 用 "coarse"(省 delta,只收 tool/approval/lifecycle/media/turn 终态,
+     * 背压砍到控制面);ws/UI 用 "full"(逐 delta 全保真)。缺省 "full"。
+     */
+    subscribe(handle: MemberHandle, sink: SupervisorEventSink, opts?: {
+        granularity?: "full" | "coarse";
+    }): () => void;
+    /**
+     * 审批应答入口(2026-07-09 补遗#3,VSCode 实证):应答方法必须挂连接持有者,绝不挂事件面。
+     * VSCode 对齐:IAgent 事件流出(onDidSessionProgress/pending_confirmation)+ 应答方法流入
+     * (respondToPermissionRequest(requestId, approved),agentService.ts:1457;UI→进程全链
+     * agentSideEffects.ts:1013)。optionId 不透明透传(E2)。
+     */
+    respondApproval(handle: MemberHandle, approvalId: string, optionId: string): void;
+    /** 取消当前回合(不杀进程)。 */
+    cancel(handle: MemberHandle): Promise<void>;
+    /** 停止并回收实例(用户主动关闭 / 会话结束)。 */
+    stop(handle: MemberHandle): Promise<void>;
+    /** 查询状态(判活为内部 ACK 响应性,超时置 "unresponsive" 交 fail-loud,不自动静默杀)。 */
+    getState(handle: MemberHandle): AgentInstanceState;
+}
+/** [S1 补定] 生命周期记录事件(recordLifecycle 参数);与 §4 onLifecycle 同族。 */
+export interface LifecycleEvent {
+    state: AgentInstanceState | "cancelled";
+    /** ISO 时间戳 */
+    at: string;
+    reason?: string;
+    code?: LifecycleCode;
+}
+export interface SessionMeta {
+    canonicalSessionId: CanonicalSessionId;
+    projectId: ProjectId;
+    /** 主 agent(创建即锁定,severe 禁中途切换) */
+    agentId: AgentId;
+    cwd: string;
+    /** 每 native agent 的原生会话 id 映射(现状单 nativeBinding 由 importer 迁入,见 N2) */
+    nativeSessionIds?: Record<AgentId, string>;
+    lifecycle: string;
+}
+export interface NativeSessionSummary {
+    nativeId: string;
+    cwd: string;
+    updatedAt: number;
+    title?: string;
+}
+/**
+ * 原生会话索引提供者(codex-index 上移网关):按 agentId 读该 agent 的 native 会话目录(~/.codex 等)。
+ * 语义 = 索引/发现,NOT transcript owner(freeze §9 边界)。home/env 由 AgentDescriptor/CredentialResolver 供。
+ * qlogicagent 不再承担读取点(否则 session plane 又漏回 agent)。
+ */
+export interface NativeSessionIndexProvider {
+    /** 仅 native-cwd 后端(codex/claude)有 provider */
+    agentId: AgentId;
+    listNativeSessions(ctx: {
+        projectId: ProjectId;
+        cwd: string;
+    }): NativeSessionSummary[];
+    resolveNativeResumeId(sessionId: CanonicalSessionId, ctx: {
+        cwd: string;
+    }): string | undefined;
+}
+/**
+ * 拥有会话存储 + 项目作用域 + agentId 绑定 + canonical↔native 映射 + 生命周期状态。
+ * 唯一权威(不与 qlogicagent 并存)。崩溃恢复靠网关持有并重放(freeze §11.4#5)。
+ *
+ * 不变式(冻结):
+ * - S1 绑定权威唯一在网关;canonical id 创建即恒定。
+ * - S2 projectId 确定性派生(deriveProjectId),同一 cwd/URI 两端算出同值。
+ * - S3 resume 只是传输层重连令牌:状态恢复靠 replayStateTo 重放,不压在 resumeNativeId 上。
+ * - S4 native transcript 不接管:网关只持 canonical↔native 映射;codex ~/.codex rollout 归 agent 自己。
+ * - S5 无归属会话不默认归小智:listSessions 绝不把"无 agentId"会话塞进小智桶;要么显式绑定要么 fail-loud。
+ */
+export interface SessionProjectService {
+    /** 确定性派生 projectId(必须 = deriveProjectId 唯一实现)。 */
+    deriveProjectId(cwdOrWorkspaceUri: string): ProjectId;
+    /**
+     * 会话创建写点(2026-07-09 补遗#1,VSCode 实证):会话进入宿主权威存储的唯一入口。
+     * VSCode 对齐:host-owned 状态创建全程显式方法(agentService.ts:1655 createSession /
+     * workspacesManagementMainService.ts:45 createUntitledWorkspace),无一处隐式内部创建。
+     * 同时承担 projectId→cwd 注册表登记(补遗#4:填充折叠进创建写点,抄 doEnterWorkspace 内调
+     * registerWorkspaceBackup;不设独立 registerProjectRoot 契约方法)。幂等;同 id 异 projectId/cwd → throw。
+     */
+    createSession(sessionId: CanonicalSessionId, projectId: ProjectId, cwd: string): void;
+    /** 会话首轮锁定主 agent(创建即恒定,严禁中途切换)。权威落此,不再落 qlogicagent metadata。 */
+    bindSessionAgent(sessionId: CanonicalSessionId, agentId: AgentId): void;
+    /** 路由权威:已绑定会话永远返回其主 agent,忽略请求方携带值(反前端漂移)。 */
+    resolveAgent(sessionId: CanonicalSessionId, requestedAgentId?: AgentId): AgentId;
+    /** 解析一次委派/回合所需的完整会话上下文(供 Supervisor.ensure 用)。 */
+    resolveContext(sessionId: CanonicalSessionId): SessionContext;
+    /** canonical↔native 映射:resume 时取 agent 自持会话的原生 id(仅 codex/claude)。 */
+    getNativeResumeId(sessionId: CanonicalSessionId, agentId: AgentId): string | undefined;
+    /**
+     * canonical↔native 映射回填写点(2026-07-09 补遗#2,VSCode 实证):native id 由 agent 运行期产生、
+     * relay 在观察点回填。VSCode 对齐:跨边界的运行期 id 回填用显式 accept 方法
+     * ($acceptTerminalProcessId(stableId, runtimeId),extHost.protocol.ts:3159);同进程侧的
+     * native→canonical 反向路由缓存照 codexAgent.ts:574 留 relay 内存,不进本契约。
+     * 幂等;同 (sessionId,agentId) 异 nativeId → throw(身份恒定)。
+     */
+    recordNativeSessionId(sessionId: CanonicalSessionId, agentId: AgentId, nativeId: string): void;
+    /** 会话列表:按 项目 + agentId 分区(前端分区面的权威来源)。 */
+    listSessions(filter: {
+        projectId?: ProjectId;
+        agentId?: AgentId | "*";
+    }): SessionMeta[];
+    /** 生命周期:记录/恢复(崩溃后网关重放订阅/激活状态给重生 agent)。 */
+    recordLifecycle(sessionId: CanonicalSessionId, ev: LifecycleEvent): void;
+    replayStateTo(handle: MemberHandle, sessionId: CanonicalSessionId): Promise<void>;
+}
+export interface CapabilityEndpoint {
+    /** 唯一规范名(astraclaw_capabilities;不再双别名,C1) */
+    serverName: string;
+    transport: "stdio" | "ipc";
+    /** 网关稳定 endpoint */
+    address: string;
+    /** 演进用 */
+    version?: string;
+    /** token 放 ref、不放明文;由 gateway/CredentialResolver 解析。qlogicagent 只消费、不维护 registry。 */
+    auth?: {
+        kind: "none";
+    } | {
+        kind: "bearerRef";
+        ref: string;
+    };
+}
+/** [S1 补定] 已装技能引用(host 注册表成员)。 */
+export interface SkillRef {
+    name: string;
+    description?: string;
+    version?: string;
+    enabled: boolean;
+    /** provenance(catalog 安装 / 本地创建 / 晋升产物等) */
+    source?: string;
+}
+/** [S1 补定] MCP 连接器引用。 */
+export interface ConnectorRef {
+    serverName: string;
+    tools: string[];
+    transport?: string;
+}
+/** [S1 补定] host 管理的安装请求(装一次,全员共享;VSCode 扩展模型)。 */
+export interface InstallRequest {
+    kind: "skill" | "mcp";
+    id: string;
+    version?: string;
+    source?: string;
+}
+/**
+ * 拥有已装技能 + MCP 连接器的注册表 + 内容;对网关监督的每个 agent(含小智)统一注入一个能力 endpoint。
+ *
+ * 不变式(冻结):
+ * - C1 单注册:能力 server 唯一规范名,绝不注册第二别名。
+ * - C2 注入点唯一:能力注入只在 Supervisor spawn 处经本服务一处发生。
+ * - C3 内容 host 持有、使用 agent 侧:技能内容/连接器 config 归网关注册表;执行仍在 agent、经此 endpoint。
+ */
+export interface CapabilityService {
+    /** 供 Supervisor 在 spawn 每个 agent 时统一注入的能力接入点(对小智自己也走同一 endpoint)。 */
+    getEndpoint(forAgent: AgentId, session: SessionContext): CapabilityEndpoint;
+    /** 已装技能注册表(host 持有;装一次共享)。 */
+    listSkills(session: SessionContext): SkillRef[];
+    viewSkill(name: string): {
+        name: string;
+        content: string;
+    };
+    /** MCP 连接器:发现 + 调用(mcp_connectors_list / mcp_tool_call 的后端)。 */
+    listConnectors(session: SessionContext): ConnectorRef[];
+    callConnector(toolName: string, args: unknown): Promise<{
+        content: unknown;
+        details?: unknown;
+        imageUrls?: string[];
+    }>;
+    /** host 管理的安装(装一次,全员共享)。 */
+    install(ref: InstallRequest): Promise<void>;
+    uninstall(id: string): Promise<void>;
+}
+/** CredentialResolver —— 三态鉴权解析(G1)。token 传 ref,明文不进事件/日志。 */
+export interface CredentialResolver {
+    resolve(agentId: AgentId, ownerId: string): ResolvedCredentials;
+    /** bearerRef → 实际 token,仅在注入 spawn env 的边界解引用 */
+    deref(ref: string): string;
+}
+/** [Route B X5] 单把 key 的 wire 视图(keyId 寻址;key 材料只给掩码,明文走 revealKey)。 */
+export interface ProviderKeyInfo {
+    keyId: string;
+    /** 掩码展示(maskApiKey 语义);明文绝不进列表面 */
+    masked: string;
+    enabled: boolean;
+    label?: string;
+}
+/** [S1 补定] 供应商信息(settings 域,spec §15)。 */
+export interface ProviderInfo {
+    id: string;
+    name?: string;
+    hasKey: boolean;
+    enabled: boolean;
+    /** [Route B X5] keyId 级子清单(一 provider 多 key);B2 profile lane 按 wire 真实形状收紧(X3) */
+    keys?: ProviderKeyInfo[];
+}
+/** settings.addKey 的原子提交选项；只承载非密元数据/替换策略。 */
+export interface ProfileAddKeyOptions {
+    label?: string;
+    replaceExisting?: boolean;
+}
+/** [S1 补定] 模型信息(settings 域)。 */
+export interface ModelInfo {
+    id: string;
+    provider: string;
+    enabled: boolean;
+    active?: boolean;
+}
+/** [S1 补定] 用途绑定(哪个模型干哪件事:textGen/small/理解/stt/embedding…,spec §13)。 */
+export interface PurposeBinding {
+    purpose: ModelPurpose;
+    model: string;
+}
+/** UI/store projection of a persisted permission rule. */
+export interface PermissionRule {
+    id: string;
+    pattern: string;
+    action: "allow" | "deny" | "ask";
+}
+/** Session-effective permission rule; mirrors the agent permission engine exactly. */
+export interface EffectivePermissionRule {
+    pattern: string;
+    pathPrefix?: string;
+    behavior: "allow" | "ask" | "deny";
+    reason?: string;
+    source?: string;
+    requireOp?: "commandNetworkEgress";
+}
+export interface EffectivePermissionConfig {
+    mode: "default" | "auto" | "full_access";
+    rules: EffectivePermissionRule[];
+}
+/** Public host-owned permission policy projection; deliberately excludes rules, keys and tunables. */
+export interface PermissionPolicy {
+    mode: EffectivePermissionConfig["mode"];
+}
+/** A single non-secret binding materialized for a model purpose. */
+export interface ResolvedModelBinding {
+    model: string;
+    provider: string;
+    routing?: string;
+    credRef?: string;
+    baseUrl?: string;
+}
+/** Complete non-secret profile materialized by the gateway at a session boundary. */
+export interface ResolvedSpawnProfile {
+    bindings: Partial<Record<ModelPurpose, ResolvedModelBinding>>;
+    permissions: EffectivePermissionConfig;
+}
+/**
+ * ProfileConfigService —— 完整 profile/config 域(spec §13/§15)。
+ * 吸收今天转发主 adapter 的 settings.* + config.* + assistants.*,全改网关本地处理。
+ * 三作用域:用户全局 / per-agent(三态鉴权)/ 项目覆盖(值按作用域分,抄 VSCode ConfigurationTarget)。
+ * agent 只接收 resolveForSpawn 现算好的绑定,不再自算(ensureLlmrouterDefaultBindings 上移这里)。
+ */
+export interface ProfileConfigService {
+    getOverview(ownerId: string): {
+        providers: ProviderInfo[];
+        models: ModelInfo[];
+        bindings: PurposeBinding[];
+        injectedKeys: string[];
+    };
+    listProviders(ownerId: string): ProviderInfo[];
+    /**
+     * [Route B X5 正名] keyId 粒度(wire 真实粒度;一 provider 多 key,原 provider 级签名是 S1 臆造面)。
+     * 返回新铸 keyId。prepare 阶段完成目录解析/候选探针，commit 阶段重读最新 settings 后只做一次
+     * 原子替换；失败不改变旧文件/旧 key enabled 状态。[X4 过渡] 本刀仍按 legacy 形态把材料直存
+     * settings.json，ref 化另批完成。明文绝不进入日志、事件或通知。
+     * 默认 bindings 保持 gateway resolve-on-read；addKey 不隐式改 purposes，direct provider 也不自动绑空用途。
+     */
+    addKey(ownerId: string, provider: string, key: string, options?: ProfileAddKeyOptions): Promise<string>;
+    /** [X5] 按 keyId 删单把 key(池空随之删;llmrouter env 注入位特例落 injectedKeys 偏好)。false=未找到(不写盘)。 */
+    removeKey(ownerId: string, keyId: string): boolean;
+    validateKey(ownerId: string, provider: string): Promise<boolean>;
+    /** [X5] 按 keyId 启停单把 key。false=未找到(不写盘)。 */
+    toggleKey(ownerId: string, keyId: string, on: boolean): boolean;
+    /**
+     * [Route B X4] UI 显式索取明文(wire settings.getKey/copyKey 的唯一后端;剪贴板副作用移前端)。
+     * 红线:返回值绝不经 HostNotificationSink 广播、绝不落日志/事件;ref 期在此边界 deref(VSCode
+     * ISecretStorageService 同构:main 持密文,显式 API 解密返回调用方)。未找到 throw(fail-loud)。
+     */
+    revealKey(ownerId: string, keyId: string): string;
+    listModels(ownerId: string): ModelInfo[];
+    setActiveModel(ownerId: string, model: string): void;
+    getActiveModel(ownerId: string): string;
+    getPurposeBindings(ownerId: string): PurposeBinding[];
+    setBinding(ownerId: string, purpose: string, model: string): void;
+    getTunables(ownerId: string): Record<string, unknown>;
+    updateTunable(ownerId: string, key: string, value: unknown): void;
+    clearTunable(ownerId: string, key: string): void;
+    /**
+     * Persist the fixed "always allow this directory" rule. Callers supply only the path;
+     * pattern/behavior/reason are host policy and never cross the agent wire.
+     */
+    appendDirectoryAllowRule(ownerId: string, pathPrefix: string): void;
+    getPermissionRules(ownerId: string): PermissionRule[];
+    /** Read the user-global (A-domain) policy used by the public permission selector. */
+    getPermissionPolicy(ownerId: string): PermissionPolicy;
+    /** Replace only A-domain permissions.mode; rules and unrelated settings remain byte-semantically intact. */
+    updatePermissionMode(ownerId: string, mode: PermissionPolicy["mode"]): PermissionPolicy;
+    getAgentConfig(agentId: AgentId, ownerId: string): {
+        authPreference: "managed" | "account" | "userKey";
+        gatewayUrl?: string;
+        apiKeyRef?: string;
+    };
+    /** apiKey 存 ref */
+    setAgentConfig(agentId: AgentId, ownerId: string, patch: Partial<{
+        authPreference: string;
+        gatewayUrl: string;
+        apiKeyRef: string;
+    }>): void;
+    resolveForSpawn(agentId: AgentId, session: SessionContext): ResolvedSpawnProfile;
+}
+/** [S1 补定] 记忆查询(memory 域;实现 lane 与 memories.db 形状映射)。 */
+export interface MemoryQuery {
+    query?: string;
+    category?: string;
+    limit?: number;
+    days?: number;
+}
+/** [S1 补定] 记忆记录(最小契约面;byAgent 为 M-3 写入署名)。 */
+export interface MemoryRecord {
+    id: string;
+    content: string;
+    category?: string;
+    tags?: string[];
+    byAgent?: AgentId;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** [S1 补定] 记忆匹配条件(delete 用)。 */
+export interface MemoryMatch {
+    ids?: string[];
+    query?: string;
+}
+/**
+ * MemoryProfileService —— 记忆 + profile 数据(spec §14)。
+ * 小智可为默认写入/解释者,但非唯一 owner;任意 peer 经 host 读写(P2:写入必带 byAgent)。
+ * 是 memory MCP 能力模块(freeze §3.7)的 store-owner;三张脸(MCP 面/UI-API 面/brain proxy 面 X7)
+ * 都是 thin adapter,唯一写者恒为本服务(脸数≠拷贝数,M-1)。
+ *
+ * [Route B X6 裁决] 本服务只管 **A 域库面**(memories.db + 附件 + 晋升/蒸馏 JSON + 用户级 INDEX.md
+ * 派生渲染)。C 域 memdir(`<cwd>/.qlogicagent/memory/`)从 memory host-state **剥离**,归"项目文件面"
+ * (进用户仓的项目文件,类 .vscode/,非 host store):UI-API 的 memdir 分支由 gateway 文件服务本地应答
+ * (VSCode main IFileService 同构),agent 侧 qla 直接 fs 操作如常。`read(source, target)` 的 memdir
+ * 两义剥除——source 只指库内来源标识,绝不再指 memdir 文件。
+ */
+export interface MemoryProfileService {
+    atlas(query: MemoryQuery): MemoryRecord[];
+    read(source: string, target: string): MemoryRecord | undefined;
+    /** 显式记录写入者(M-3) */
+    write(record: MemoryRecord, byAgent: AgentId): void;
+    delete(match: MemoryMatch): void;
+    consolidate(candidates: MemoryRecord[], source: string): void;
+    promote(proposal: unknown): void;
+}
+/** [S1 补定] 首启进度状态。 */
+export interface OnboardingState {
+    completed: boolean;
+    step?: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+/** 开场行动卡(freeze §3.5:actor 必须显式声明,不再隐式=主程序,P3)。 */
+export interface ActionCard {
+    id: string;
+    label: string;
+    actor: AgentId;
+}
+/** OnboardingService —— 首启"认识你"(spec §14,host-owned)。 */
+export interface OnboardingService {
+    getState(ownerId: string): OnboardingState;
+    advance(ownerId: string, step: string): OnboardingState;
+}
+/** ActionSurfaceService —— 开场行动卡(spec §14,host-owned)。 */
+export interface ActionSurfaceService {
+    listActions(session: SessionContext): ActionCard[];
+}
+/**
+ * GatewayDelegateRelay —— 机制 B 的 gateway-routed delegate 唯一入口(6 处 spawn 点改调这里,P4)。
+ * 编排(小智)发 delegate → 网关解析 session/cred/capability → Supervisor.ensure+sendTurn → 事件回流。
+ * reconnect 后向重生实例 replay 状态(与 SessionProjectService.replayStateTo 协同;O3 场景 7)。
+ */
+export interface GatewayDelegateRelay {
+    delegate(from: MemberHandle | "user", to: {
+        handle: MemberHandle;
+        agentId: AgentId;
+    }, 
+    /** (S3 综合补遗 A1)富输入,与 sendTurn/x_delegate 一致;禁降回纯文本(评审:relay 若停 prompt:string 则富输入到此塌成文本) */
+    input: TurnInput, session: SessionContext, opts?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        granularity?: "full" | "coarse";
+        systemPrompt?: string;
+    }): Promise<TurnResult>;
+    subscribe(handle: MemberHandle, sink: SupervisorEventSink, opts?: {
+        granularity?: "full" | "coarse";
+    }): () => void;
+}
+export type RunId = string;
+/** [S1 补定] 运行事件(由 relay/supervisor 生命周期喂)。 */
+export interface RunEvent {
+    /** ISO 时间戳 */
+    at: string;
+    type: string;
+    member?: MemberHandle;
+    payload?: unknown;
+}
+/** [S1 补定] 运行状态(UI 权威读)。 */
+export interface RunState {
+    runId: RunId;
+    kind: "solo" | "product" | "goal";
+    projectId: ProjectId;
+    owner: SessionContext;
+    status: string;
+    events?: RunEvent[];
+    checkpoint?: unknown;
+    openedAt: string;
+    updatedAt: string;
+}
+/**
+ * RunStateStore —— Solo/Product/Goal 运行状态归属(A6,Core Host 一等公民)。
+ * "跑到哪了"的记录归 host,由 GatewayDelegateRelay + Supervisor 生命周期事件喂;
+ * qlogicagent 崩溃/重启进度不丢、UI 从宿主权威读。
+ * leader 大脑逻辑(怎么规划、派谁)仍留 qlogicagent,只写"计划"、不持久化"进度记录"(P5)。
+ */
+export interface RunStateStore {
+    openRun(kind: "solo" | "product" | "goal", owner: SessionContext): RunId;
+    recordEvent(runId: RunId, ev: RunEvent): void;
+    /** product/solo 检查点 */
+    checkpoint(runId: RunId, snapshot: unknown): void;
+    getRun(runId: RunId): RunState;
+    listRuns(filter: {
+        projectId: ProjectId;
+        kind?: string;
+    }): RunState[];
+}
+export interface EvBase {
+    /** 由 relay 合成(今天线上无 handle,只有 agentId+sessionId+delegationId 关联;R1) */
+    member: MemberHandle;
+    sessionId: string;
+    turnId: string;
+    requestId?: string;
+}
+/**
+ * 不变式(冻结):
+ * - E1 归属:回合事件必须带 (member, sessionId, turnId, requestId?);实例级 lifecycle 可省 turnId/sessionId,
+ *   但必须带 member + state。member 由 relay 合成(委派事件要归属到委派成员,不能寄生宿主 agentId,R1)。
+ * - E2 审批/media/lifecycle 均过网关边界,不走进程内直传;审批应答 optionId 不透明透传。
+ * - E3 失败一律 onLifecycle 结构化明示(code+diagnostics+retriable),不得降级成裸 error 串、不静默杀;
+ *   cancel 是显式 state:"cancelled" 非 "RPC aborted" 串。
+ * - E4 reconnect 要重放回合事件(S3 replayStateTo),今天只重放状态快照(R7)。
+ * - E5 relay 漏项 R1-R8 是 cutover 施工项(behind 本冻结接口,非开放设计题;清单见 findings §3)。
+ */
+export interface SupervisorEventSink {
+    /** turn.delta / turn.reasoning_delta(字段=delta,非 text) */
+    onDelta(e: EvBase & {
+        delta: string;
+        reasoning?: boolean;
+    }): void;
+    /** onTool 拆成 call/result 两事件、callId 配对(旧单 {name,status} 是错形状;R2)。 */
+    onToolCall(e: EvBase & {
+        callId: string;
+        name: string;
+        arguments?: string;
+        inputSummary?: string;
+        startedAt?: string;
+    }): void;
+    /**
+     * ⚠ name = relay 经 callId 从配对 tool_call 回填的 canonical name;不可信任原始 tool_result.name
+     * ——实测塌成通用 "tool"(真名只在 call 侧;entry.ts:233 `ev?.name ?? "tool"`,findings R2)。
+     */
+    onToolResult(e: EvBase & {
+        callId: string;
+        name: string;
+        ok: boolean;
+        error?: string;
+        outputPreview?: string;
+        finishedAt?: string;
+    }): void;
+    /**
+     * 审批:options[].optionId 是不透明、按审批种类而异的串(approved/cancel/abort/approved-execpolicy-amendment…);
+     * 应答走 AgentSupervisor.respondApproval(handle, approvalId, optionId) 原样透传——sink 是纯事件流出面,
+     * 不承载应答入口(2026-07-09 补遗#3:应答方法挂连接持有者,VSCode IAgent 同构)。
+     */
+    onApprovalRequest(e: EvBase & {
+        approvalId: string;
+        callId: string;
+        toolName: string;
+        arguments?: string;
+        message?: string;
+        category?: string;
+        options: Array<{
+            optionId: string;
+            name: string;
+            kind: string;
+        }>;
+    }): void;
+    /**
+     * media:统一 {mediaType,url,model,provider}(非 imageUrls[])。⚠R3:external agent 今天不发此事件
+     * (codex 图像漏成 tool_call),cutover 必须补 agents.prompt.media relay,否则 external media 无一等来源。
+     */
+    onMedia(e: EvBase & {
+        mediaType: string;
+        url: string;
+        model?: string;
+        provider?: string;
+    }): void;
+    /**
+     * 通用透传(S3 综合补遗 A3):承接今天 mapSessionUpdate 的 x_relay→relay 分支
+     * (acp-adapter.ts:824-850 的 tool_use_summary/task_updated/recovery/ask_user/instructions 等)。
+     * supervisor handleNotification 的 default:break(agent-supervisor.ts:742)会整块丢弃这些→前端富遥测/
+     * 编排面板全空;此口保前端契约不破。eventName=原方法名,payload 原样。
+     * **边界(评审)**:onRelay **只做非权威遥测透传,不承载控制语义**(控制/终态/审批走各自一等事件,不许经此绕行);
+     * payload 必须走红线脱敏(明文凭据/密钥不出)+ 大小上限(超限截断,防大帧 DoS)。
+     */
+    onRelay(e: EvBase & {
+        eventName: string;
+        payload: unknown;
+    }): void;
+    /**
+     * 回合终态 + agent 实例态。⚠R4/R5:今天线上的 turn.error 是裸串(丢 code/diagnostics/retriable);
+     * adapter 内部已有 code+diagnostics 但 external relay 无 error 分支 → 冻结要求补齐。
+     * agent 实例四态今天无一等事件(只有连接时 agent-status),F4/F6/fail-loud 要求补。
+     * UNKNOWN 兜底语义见 LifecycleCode。
+     */
+    onLifecycle(e: {
+        member: MemberHandle;
+        sessionId?: string;
+        turnId?: string;
+        state: AgentInstanceState | "cancelled";
+        reason?: string;
+        retriable?: boolean;
+        code?: LifecycleCode;
+        diagnostics?: {
+            pid?: number;
+            exitCode?: number | null;
+            signal?: string | null;
+            stderrTail?: string;
+            lastEventName?: string;
+            timedOutAfterMs?: number;
+            idleMs?: number;
+        };
+    }): void;
+}
+/** delegate 关联主键:leader 铸、gateway 校验唯一(T3/T4)。 */
+export type DelegationId = string;
+/** `x/delegate` 请求参数(agent→host,起一个 worker 回合,resolve TurnResult,隐式订阅该 delegation)。 */
+export interface DelegateRequestParams {
+    delegationId: DelegationId;
+    /** F5 leader 硬校验在 gateway 侧,不信任此处传入(T4) */
+    to: {
+        handle: MemberHandle;
+        agentId: AgentId;
+    };
+    input: TurnInput;
+    session: SessionContext;
+    /** Persona/instructions applied when the gateway registers or resumes the delegated session. */
+    systemPrompt?: string;
+    opts?: {
+        timeoutMs?: number;
+        granularity?: "full" | "coarse";
+    };
+}
+/** 回流事件种类(与 §4 SupervisorEventSink 方法 1:1,T10 无损镜像)。 */
+export type DelegateEventKind = "delta" | "tool_call" | "tool_result" | "approval_request" | "media" | "relay" | "lifecycle";
+/**
+ * `x/delegate.update` 帧(host→agent 通知,一事件一帧;不复用反向 session/update,T2)。
+ * event = 对应 SupervisorEventSink 事件去掉 member 后的对象(member 提到帧级,E1)。
+ */
+export interface DelegateUpdateFrame {
+    delegationId: DelegationId;
+    /** gateway 铸,每 delegation 单调;消费方校验连续,丢帧/乱序 fail-loud(T3/T6) */
+    seq: number;
+    /** 权威成员(E1,= to.handle;禁宿主盖名 R1) */
+    member: MemberHandle;
+    kind: DelegateEventKind;
+    /** 载荷镜像对应 sink 事件(去 member);sink 接口即权威形状 */
+    event: unknown;
+}
+/** `x/delegate.respond`(agent→host 通知,leader 来源审批应答;UI 来源走现有 ws approval-response,T8)。 */
+export interface DelegateRespondParams {
+    delegationId: DelegationId;
+    approvalId: string;
+    /** 不透明透传(E2) */
+    optionId: string;
+}
+/** `x/delegate.cancel`(agent→host 通知,取消回合不杀进程;终态出显式 cancelled,E3)。 */
+export interface DelegateCancelParams {
+    delegationId: DelegationId;
+    reason?: string;
+}
+/** wire 方法名(x/ 族;方法约定 acp-protocol.ts:42-80,非 x_ session-update 类型)。 */
+export declare const DELEGATE_WIRE_METHODS: {
+    readonly request: "x/delegate";
+    readonly update: "x/delegate.update";
+    readonly respond: "x/delegate.respond";
+    readonly cancel: "x/delegate.cancel";
+};
+/**
+ * [X1] Host 领域变更通知 sink —— 挂 **store-owner 服务层**,不挂 RPC handler(brain proxy/MCP 写路径
+ * 不经 handler,挂 handler 会漏通知;挂 owner 则 UI 写/brain 写/MCP 写全覆盖)。
+ * 装配期由 host-services 注入 gateway 事件总线(emitGatewayEvent→broadcast);服务 mutation 成功后调用。
+ * 事件名与今天线上帧逐字一致(memory.updated / skills.updated / turn.memory_written / system.activity,
+ * GatewayEventMap 既有键)——前端契约不破。
+ * 红线:payload 走脱敏(明文凭据/密钥绝不入,X4)+ 大小上限(同 onRelay 纪律)。
+ * VSCode 对照:变更事件挂 main 侧状态 owner(IWorkspaceContextService.onDidChangeWorkspaceFolders),
+ * 主动推送($acceptWorkspaceData),不挂请求处理器。
+ */
+export interface HostNotificationSink {
+    notify(eventName: string, payload: unknown): void;
+}
+/**
+ * [X7] qlogicagent 大脑经 x/host.request 可调用的 memory proxy 精确方法面。
+ * gateway 白名单与 qla HostMemoryProvider 都必须直接消费此常量，禁止两仓手抄后漂移。
+ */
+export declare const HOST_MEMORY_PROXY_METHODS: readonly ["search", "addText", "embedText", "ingestExtracted", "proposeExtracted", "consumePendingProposals", "feedback", "findRelatedEvents", "synthesizeTimeline", "getActivitySummary", "getAllProfiles", "setProfile", "getAtlas", "setMemoryArchived", "triggerDecay", "resolveConflicts"];
+export type HostMemoryProxyMethod = (typeof HOST_MEMORY_PROXY_METHODS)[number];
+/** [X7-C1a] Capability 大脑代理当前只开放两个只读方法；写面与 connector 尚未入约。 */
+export declare const HOST_CAPABILITY_PROXY_METHODS: readonly ["getSkillSnapshot", "readSkillFile", "recordSkillInvocation", "commitSkillMutation", "applyCuratorPlan", "prepareSkillInstall", "finalizeSkillInstall"];
+export type HostCapabilityProxyMethod = (typeof HOST_CAPABILITY_PROXY_METHODS)[number];
+/**
+ * [S3-Session-X7] Agent compute may submit only durable session results and load a
+ * resume view. Generic metadata patches and filesystem access are deliberately absent.
+ */
+export declare const HOST_SESSION_PROXY_METHODS: readonly ["loadForResume", "appendTranscript", "updateTitle", "saveState", "saveTaskSummary", "groupSplit"];
+export type HostSessionProxyMethod = (typeof HOST_SESSION_PROXY_METHODS)[number];
+/**
+ * [S3-D2-X7] Feedback/telemetry compute may use only these business operations. The
+ * gateway owns every durable file and the reliable upload state machine; generic file,
+ * object-patch, owner-id, and upload-batch mutation surfaces are intentionally absent.
+ */
+export declare const HOST_FEEDBACK_PROXY_METHODS: readonly ["commitTurnTelemetry", "listDistillableFeedback", "markFeedbackDistilled", "runUploadSweep"];
+export type HostFeedbackProxyMethod = (typeof HOST_FEEDBACK_PROXY_METHODS)[number];
+/** Project registry X7 is intentionally business-shaped; no generic registry/file patches. */
+export declare const HOST_PROJECT_PROXY_METHODS: readonly ["getSnapshot", "create", "switch", "update"];
+export type HostProjectProxyMethod = (typeof HOST_PROJECT_PROXY_METHODS)[number];
+export type HostProjectType = "default" | "personal" | "group" | "solo" | "product" | "automation";
+export interface HostProjectInfo {
+    id: ProjectId;
+    name: string;
+    workspaceDir: string;
+    type: HostProjectType;
+    status: "active" | "archived";
+    groupId?: string;
+    createdAt: string;
+    updatedAt: string;
+    planStatus?: "creating" | "running" | "completed" | "failed" | "cancelled";
+    planAgents?: string[];
+    planWinnerId?: string;
+    leaderSessionId?: string;
+    primaryWorkflowId?: string;
+}
+export type HostProjectSnapshotResult = {
+    activeProjectId: ProjectId | null;
+    projects: HostProjectInfo[];
+};
+export type HostProjectMutationResult = {
+    ok: true;
+    project: HostProjectInfo;
+    deduplicated?: boolean;
+};
+export type HostProjectRequestParams = {
+    service: "project";
+    method: "getSnapshot";
+    params: Record<string, never>;
+} | {
+    service: "project";
+    method: "create";
+    params: {
+        name: string;
+        workspaceDir?: string;
+        type?: Exclude<HostProjectType, "default">;
+        groupId?: string;
+    };
+} | {
+    service: "project";
+    method: "switch";
+    params: {
+        projectIdOrQuery: string;
+    };
+} | {
+    service: "project";
+    method: "update";
+    params: {
+        projectId: ProjectId;
+        planStatus?: HostProjectInfo["planStatus"];
+        planAgents?: string[];
+        planWinnerId?: string;
+        leaderSessionId?: string;
+        primaryWorkflowId?: string;
+    };
+};
+export interface HostTurnTelemetryInput {
+    model?: string;
+    provider?: string;
+    agentMode?: "chat" | "solo" | "product" | "workflow" | "unknown";
+    sourceChannel?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    toolSummary?: {
+        calledTools: string[];
+        failedTools: string[];
+        blockedTools: string[];
+    };
+    fileContext?: {
+        changedFileCount?: number;
+        changedPathsPreview?: string[];
+        hasTurnFileChanges?: boolean;
+    };
+}
+/** Minimal, non-message-text evidence returned to the agent-side pure distiller. */
+export interface HostDistillableFeedbackEvent {
+    feedbackId: string;
+    rating: "up" | "down";
+    reason?: "missed_requirement" | "incomplete" | "broken_file_link_or_panel" | "code_or_test_failed" | "factually_wrong" | "too_verbose" | "too_short" | "wrong_style" | "other";
+    state: "active";
+    sessionId: string;
+    turnId: string;
+}
+export interface HostFeedbackSweepResult {
+    uploaded: number;
+    queued: number;
+    retried: number;
+    exhausted: number;
+}
+export interface HostSessionToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Leaf contract copy of the persisted message wire shape; importing protocol here would cycle. */
+export interface HostSessionMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: HostSessionToolCall[];
+    tool_call_id?: string;
+    name?: string;
+    is_error?: boolean;
+    reasoning_content?: string;
+    toolReferences?: string[];
+    thinkingBlocks?: Array<{
+        thinking: string;
+        signature: string;
+    }>;
+    imageUrls?: string[];
+    imageDetail?: "auto" | "low" | "high" | "xhigh";
+    imagePixelLimit?: {
+        minPixels?: number;
+        maxPixels?: number;
+    };
+    videoUrls?: string[];
+    videoFps?: number;
+    audioFormat?: "mp3" | "wav" | "aac" | "m4a";
+    audioUrls?: string[];
+    fileIds?: Array<{
+        id: string;
+        mimeType?: string;
+        size?: number;
+    }>;
+    blocks?: Array<Record<string, unknown>>;
+    attachmentEntries?: Array<Record<string, unknown>>;
+    timestamp?: string;
+    turnId?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    displayMetadata?: Record<string, unknown>;
+}
+export interface HostSessionResumeMetadata {
+    sessionId: string;
+    projectId: string;
+    createdAt: string;
+    lastActiveAt: string;
+    turnCount: number;
+    messageCount: number;
+    type?: "personal" | "group";
+    title?: string;
+    agentId?: string;
+    model?: string;
+    taskSummary?: string;
+    carryoverSummary?: string;
+    previousSessionId?: string;
+    pinnedAt?: string;
+    archivedAt?: string;
+    sealedAt?: string;
+}
+export type HostSessionLoadForResumeResult = {
+    session: null | {
+        metadata: HostSessionResumeMetadata;
+        messages: HostSessionMessage[];
+        corruptLines?: number;
+    };
+};
+export type HostSessionAppendResult = {
+    status: "appended" | "duplicate" | "session-deleted";
+    messageCount: number;
+};
+export type HostSessionMutationResult = {
+    status: "updated" | "duplicate" | "session-deleted";
+};
+export type HostSessionGroupSplitResult = HostSessionMutationResult & {
+    nextSessionId?: string;
+};
+/** skill-lifecycle.json 的真实记录形状；扩展 provenance 字段必须原样往返。 */
+export interface HostSkillLifecycleRecord {
+    name: string;
+    state: "active" | "stale" | "archived";
+    createdAt: string;
+    lastUsedAt?: string;
+    lastViewedAt?: string;
+    lastPatchedAt?: string;
+    staleAt?: string;
+    archivedAt?: string;
+    pinned: boolean;
+    useCount: number;
+    positiveCount?: number;
+    negativeCount?: number;
+    source: "learned" | "created" | "installed" | "promoted";
+    resourceType?: string;
+    launcherRequired?: boolean;
+    manualReviewRequired?: boolean;
+    sourceTier?: "official" | "community";
+    riskTier?: "R0" | "R1" | "R2" | "R3";
+    artifactDigest?: string;
+    registryResourceId?: string;
+    registryVersion?: string;
+    registrySourceTier?: "official" | "community";
+    registryRiskTier?: "R0" | "R1" | "R2" | "R3";
+    registryEffectiveRiskTier?: "R0" | "R1" | "R2" | "R3";
+    registryKeptSignalAt?: string;
+    [extra: string]: unknown;
+}
+/** Gateway 对同一技能 store 的只读快照条目。active 只叠加全局/项目禁用，不叠 turn 工具条件。 */
+export interface HostSkillSnapshotEntry {
+    name: string;
+    filePath: string;
+    baseDir: string;
+    fileRevision: string;
+    globallyDisabled: boolean;
+    projectDisabled: boolean;
+    active: boolean;
+    systemGenerated: boolean;
+    description?: string;
+    version?: string;
+    category?: string;
+    author?: string;
+    requiredTools?: string[];
+    environments?: string[];
+    source?: HostSkillLifecycleRecord["source"];
+    registryVersion?: string;
+}
+/** profiles/<owner>/skill-bundles 中现有 bundle 的真实公开字段。 */
+export interface HostSkillBundleSnapshot {
+    name: string;
+    skills: string[];
+    filePath: string;
+}
+export type HostSkillSnapshotResponse = {
+    revision: string;
+    notModified: true;
+} | {
+    revision: string;
+    notModified: false;
+    skills: HostSkillSnapshotEntry[];
+    lifecycle: HostSkillLifecycleRecord[];
+    bundles: HostSkillBundleSnapshot[];
+};
+export interface HostSkillFileResponse {
+    name: string;
+    relativePath: string;
+    content: string;
+    baseDir: string;
+    revision: string;
+}
+export interface HostSkillInvocationResult {
+    name: string;
+    lastUsedAt: string;
+    useCount: number;
+    positiveCount: number;
+    negativeCount: number;
+}
+/** 单文件读取上限；host 在解码前按 bytes 检查。 */
+export declare const HOST_SKILL_FILE_MAX_BYTES: number;
+/** [X7-P] 单一 agent→host 一元请求通道的服务域。 */
+export type HostRequestService = "memory" | "profile" | "preview" | "capability" | "session" | "feedback" | "project";
+/** Preview Browser 的七个允许动作；tool 与 gateway 必须消费此单源。 */
+export declare const PREVIEW_BROWSER_ACTIONS: readonly ["navigate", "snapshot", "click", "type", "screenshot", "console", "network"];
+export type PreviewBrowserAction = (typeof PREVIEW_BROWSER_ACTIONS)[number];
+/** 每个 preview action 的精确 payload；禁止把任意 Electron IPC method/params 暴露给 agent。 */
+export interface PreviewBrowserActionParams {
+    navigate: {
+        url: string;
+        viewId?: string;
+    };
+    snapshot: {
+        viewId?: string;
+    };
+    click: {
+        ref: string;
+        viewId?: string;
+    };
+    type: {
+        ref: string;
+        text: string;
+        submit?: boolean;
+        viewId?: string;
+    };
+    screenshot: {
+        viewId?: string;
+    };
+    console: {
+        viewId?: string;
+    };
+    network: {
+        viewId?: string;
+    };
+}
+/** preview_browser tool 的判别联合参数；action 与 payload 字段保持关联。 */
+export type PreviewBrowserToolParams = {
+    [Action in PreviewBrowserAction]: {
+        action: Action;
+    } & PreviewBrowserActionParams[Action];
+}[PreviewBrowserAction];
+/** preview owner 回传的共享结果面。 */
+export interface PreviewBrowserDriveResult {
+    text?: string;
+    screenshotB64?: string;
+    error?: string;
+    details?: unknown;
+}
+export type HostMemoryRequestParams = {
+    service: "memory";
+    method: HostMemoryProxyMethod;
+    params: unknown[];
+};
+export type HostSessionRequestParams = {
+    service: "session";
+    method: "loadForResume";
+    params: {
+        sessionId: string;
+        projectId?: ProjectId;
+        includeMessages?: boolean;
+    };
+} | {
+    service: "session";
+    method: "appendTranscript";
+    params: {
+        sessionId: string;
+        turnId: string;
+        messageId: string;
+        sequence: number;
+        message: HostSessionMessage;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+            totalTokens?: number;
+        };
+        displayMetadata?: Record<string, unknown>;
+    };
+} | {
+    service: "session";
+    method: "updateTitle";
+    params: {
+        sessionId: string;
+        operationId: string;
+        title: string;
+    };
+} | {
+    service: "session";
+    method: "saveState";
+    params: {
+        sessionId: string;
+        turnId: string;
+        operationId: string;
+        model?: string;
+        usage: {
+            turnCount: number;
+            totalInputTokens: number;
+            totalOutputTokens: number;
+        };
+    };
+} | {
+    service: "session";
+    method: "saveTaskSummary";
+    params: {
+        sessionId: string;
+        operationId: string;
+        summary: string;
+        generatedAtTurn: number;
+    };
+} | {
+    service: "session";
+    method: "groupSplit";
+    params: {
+        sessionId: string;
+        operationId: string;
+        reason: "idle" | "turn-limit";
+        expectedLastActiveAt?: string;
+        expectedTurnCount?: number;
+    };
+};
+export type HostFeedbackRequestParams = {
+    service: "feedback";
+    method: "commitTurnTelemetry";
+    params: {
+        projectId: ProjectId;
+        sessionId: string;
+        turnId: string;
+        telemetry: HostTurnTelemetryInput;
+    };
+} | {
+    service: "feedback";
+    method: "listDistillableFeedback";
+    params: {
+        projectId: ProjectId;
+    };
+} | {
+    service: "feedback";
+    method: "markFeedbackDistilled";
+    params: {
+        projectId: ProjectId;
+        turnId: string;
+        clusterKey: string;
+        idempotencyKey: string;
+    };
+} | {
+    service: "feedback";
+    method: "runUploadSweep";
+    params: {
+        projectId: ProjectId;
+    };
+};
+/** Agent-originated profile store calls. UI/provider surfaces are intentionally excluded. */
+export declare const HOST_PROFILE_PROXY_METHODS: readonly ["getTunables", "updateTunable", "clearTunable", "appendDirectoryAllowRule"];
+export type HostProfileProxyMethod = typeof HOST_PROFILE_PROXY_METHODS[number];
+/**
+ * Profile proxy envelopes use positional args and never carry ownerId. The gateway injects the
+ * authenticated owner at dispatch. Directory approval policy is likewise host-owned: the agent
+ * may provide only pathPrefix, never pattern/behavior/reason.
+ */
+export type HostProfileRequestParams = {
+    service: "profile";
+    method: "getTunables";
+    params: [];
+} | {
+    service: "profile";
+    method: "updateTunable";
+    params: [key: string, value: unknown];
+} | {
+    service: "profile";
+    method: "clearTunable";
+    params: [key: string];
+} | {
+    service: "profile";
+    method: "appendDirectoryAllowRule";
+    params: [pathPrefix: string];
+};
+/** Capability C1a 只读请求。projectId 由 gateway 项目注册表解析，agent 不得传 cwd/ownerId。 */
+export interface HostGetSkillSnapshotParams {
+    projectId?: ProjectId;
+    knownRevision?: string;
+}
+export interface HostReadSkillFileParams {
+    name: string;
+    relativePath?: string;
+    expectedRevision?: string;
+}
+export interface HostRecordSkillInvocationParams {
+    name: string;
+    success: boolean;
+}
+/** One structured C2 write entrypoint. Content edits are CAS-only; null means create-if-absent. */
+export type HostSkillMutation = {
+    kind: "create";
+    name: string;
+    content: string;
+    source?: "created" | "learned";
+    supportingFile?: {
+        relativePath: string;
+        content: string;
+    };
+} | {
+    kind: "editContent";
+    name: string;
+    expectedRevision: string;
+    content: string;
+} | {
+    kind: "editSupportingFile";
+    name: string;
+    relativePath: string;
+    expectedRevision: string | null;
+    content: string;
+} | {
+    kind: "delete";
+    name: string;
+} | {
+    kind: "setGlobalDisabled";
+    name: string;
+    disabled: boolean;
+} | {
+    kind: "setProjectDisabled";
+    name: string;
+    projectId: ProjectId;
+    disabled: boolean;
+} | {
+    kind: "setPinned";
+    name: string;
+    pinned: boolean;
+} | {
+    kind: "promote";
+    name: string;
+};
+export interface HostCommitSkillMutationParams {
+    mutation: HostSkillMutation;
+}
+export type HostSkillMutationResult = {
+    kind: "create";
+    name: string;
+    revision: string;
+    changed: true;
+} | {
+    kind: "editContent";
+    name: string;
+    revision: string;
+    changed: true;
+} | {
+    kind: "editSupportingFile";
+    name: string;
+    revision: string;
+    changed: true;
+} | {
+    kind: "delete";
+    name: string;
+    deleted: true;
+} | {
+    kind: "setGlobalDisabled";
+    name: string;
+    disabled: boolean;
+    changed: boolean;
+} | {
+    kind: "setProjectDisabled";
+    name: string;
+    disabled: boolean;
+    changed: boolean;
+} | {
+    kind: "setPinned";
+    name: string;
+    pinned: boolean;
+    changed: boolean;
+} | {
+    kind: "promote";
+    name: string;
+    promoted: true;
+    changed: boolean;
+};
+export type HostSkillLifecycleState = HostSkillLifecycleRecord["state"];
+export interface HostCuratorTransition {
+    name: string;
+    from: HostSkillLifecycleState;
+    to: HostSkillLifecycleState;
+}
+export interface HostApplyCuratorPlanParams {
+    expectedRevision: string;
+    transitions: HostCuratorTransition[];
+}
+export interface HostApplyCuratorPlanResult {
+    revision: string;
+    changed: boolean;
+    transitioned: HostCuratorTransition[];
+}
+export type HostSkillInstallRiskTier = "R0" | "R1" | "R2" | "R3";
+export interface HostPrepareSkillInstallParams {
+    name: string;
+    version: string;
+    checksum: string;
+    sizeBytes: number;
+    allowReplace: boolean;
+    provenance: {
+        sourceTier: "official" | "community";
+        resourceRiskTier: HostSkillInstallRiskTier;
+        effectiveRiskTier: HostSkillInstallRiskTier;
+    };
+}
+export interface HostPrepareSkillInstallResult {
+    installationId: string;
+    artifactPath: string;
+    contentDir: string;
+    expiresAt: string;
+}
+export interface HostFinalizeSkillInstallParams {
+    installationId: string;
+    action: "adopt" | "discard";
+}
+export type HostFinalizeSkillInstallResult = {
+    action: "discard";
+    discarded: true;
+} | {
+    action: "adopt";
+    resourceId: string;
+    version: string;
+    skillName: string;
+    installDir: string;
+    checksum: string;
+    replaced: boolean;
+};
+export type HostCapabilityRequestParams = {
+    service: "capability";
+    method: "getSkillSnapshot";
+    params: HostGetSkillSnapshotParams;
+} | {
+    service: "capability";
+    method: "readSkillFile";
+    params: HostReadSkillFileParams;
+} | {
+    service: "capability";
+    method: "recordSkillInvocation";
+    params: HostRecordSkillInvocationParams;
+} | {
+    service: "capability";
+    method: "commitSkillMutation";
+    params: HostCommitSkillMutationParams;
+} | {
+    service: "capability";
+    method: "applyCuratorPlan";
+    params: HostApplyCuratorPlanParams;
+} | {
+    service: "capability";
+    method: "prepareSkillInstall";
+    params: HostPrepareSkillInstallParams;
+} | {
+    service: "capability";
+    method: "finalizeSkillInstall";
+    params: HostFinalizeSkillInstallParams;
+};
+export type HostPreviewRequestParams = {
+    [Action in PreviewBrowserAction]: {
+        service: "preview";
+        method: Action;
+        /** sessionId is injected by the turn backend for Electron pane attribution; it is not agent input. */
+        params: PreviewBrowserActionParams[Action] & {
+            sessionId?: string;
+        };
+    };
+}[PreviewBrowserAction];
+/**
+ * [X7-P] 跨进程 HostRequest 判别联合。memory/profile/preview 共用 `x/host.request`，
+ * service + method 二级分派；preview 的 method 与 payload 在类型层保持逐动作关联。
+ */
+export type HostRequestParams = HostMemoryRequestParams | HostProfileRequestParams | HostPreviewRequestParams | HostCapabilityRequestParams | HostSessionRequestParams | HostFeedbackRequestParams | HostProjectRequestParams;
+/** initialize 声明的真实已装配 host-request 服务；version 只接受冻结版本 1。 */
+export type HostRequestCapability = {
+    version: 1;
+    services: HostRequestService[];
+};
+/** [X7-P] wire 方法名(x/ 族)，旧 HostState 名称不保留兼容别名。 */
+export declare const HOST_REQUEST_WIRE_METHODS: {
+    readonly request: "x/host.request";
+};
+export declare function isHostSkillSnapshotResponse(value: unknown): value is HostSkillSnapshotResponse;
+export declare function isHostSkillFileResponse(value: unknown): value is HostSkillFileResponse;
+export declare function isHostSkillInvocationResult(value: unknown): value is HostSkillInvocationResult;
+export declare function isHostSkillMutationResult(value: unknown): value is HostSkillMutationResult;
+export declare function isHostApplyCuratorPlanResult(value: unknown): value is HostApplyCuratorPlanResult;
+export declare function isHostPrepareSkillInstallResult(value: unknown): value is HostPrepareSkillInstallResult;
+export declare function isHostFinalizeSkillInstallResult(value: unknown): value is HostFinalizeSkillInstallResult;
+export declare function isHostSessionLoadForResumeResult(value: unknown): value is HostSessionLoadForResumeResult;
+export declare function isHostSessionAppendResult(value: unknown): value is HostSessionAppendResult;
+export declare function isHostSessionMutationResult(value: unknown): value is HostSessionMutationResult;
+export declare function isHostSessionGroupSplitResult(value: unknown): value is HostSessionGroupSplitResult;
+/** Runtime wire guard used by the gateway before service dispatch. */
+export declare function isHostRequestParams(value: unknown): value is HostRequestParams;
+export declare function isHostFeedbackCommitResult(value: unknown): value is {
+    ok: true;
+};
+export declare function isHostDistillableFeedbackResult(value: unknown): value is {
+    events: HostDistillableFeedbackEvent[];
+};
+export declare function isHostFeedbackMarkResult(value: unknown): value is {
+    ok: true;
+    updated: boolean;
+};
+export declare function isHostFeedbackSweepResult(value: unknown): value is HostFeedbackSweepResult;
+export declare function isHostProjectSnapshotResult(value: unknown): value is HostProjectSnapshotResult;
+export declare function isHostProjectMutationResult(value: unknown): value is HostProjectMutationResult;
+/** Exact version + exact service-discriminant capability check; no prefix/coercion fallback. */
+export declare function supportsHostRequestService(capability: unknown, service: unknown): boolean;
+/**
+ * [X7 检索单源] FTS 分词 —— memories.db 的写侧(text_seg 列)与查侧(FTS 查询)**必须同一实现**,
+ * 漂移即召回静默清零(fts-segment.ts 文件头铁律)。B3 后唯一写者=gateway(runtime 仓),故经本契约包共享
+ * 单一实现(先例:deriveProjectId 同款 re-export);qla 侧 LocalMemoryStore 与 gateway memory-profile-sqlite
+ * 引用同一份,零复刻。纯函数零依赖(仅正则)。
+ * 实现体落在本契约模块内(src/host-contract/fts-segment.ts)而非 re-export skills——host-contract 是
+ * leaf(acp-protocol.ts 文件头依赖此不变式;反向 re-export 曾闭合 host-contract→skills→runtime→
+ * protocol→host-contract 模块环,check-architecture-boundaries top-level-cycles 抓出)。
+ */
+export { segmentForFts, segmentTextForFts } from "./fts-segment.js";