@winmatrix/protocol 1.0.4 → 1.0.6

package/dist/agentEngine.js

@@ -0,0 +1,679 @@
+/**
+ * @winmatrix/protocol — 统一 Agent Engine Runtime Gateway DTO。
+ *
+ * 本文件是 server-pod 与 external-computer 共用的 Agent Engine 调用契约：
+ * V1/V2 调用计划、canonical LaunchSpec、Run/Session/Event Subscription 资源模型、
+ * 可重连事件 Envelope、交互回复、Engine/模型/option 发现与 Host wire DTO。
+ *
+ * 安全边界：
+ * - EngineInvocationPlan / EngineLaunchSpec / EngineOptionCatalog 属于公共 DTO，
+ *   MUST NOT 包含 callback token、credential、dynamic secret、Hook ID/config、
+ *   command、modulePath、script 或远程 URL。
+ * - ExternalTaskSecretBindings 是协议显式定义的 sensitive envelope，
+ *   其字段值禁止进入日志、持久化 metadata、trace、fingerprint 与事件。
+ */
+import { z } from 'zod';
+import { EngineFinalResultSchema, EngineHookProfileDescriptorSchema, EngineHookProfileRefSchema, EngineIdSchema, EngineInteractionOptionSchema, EngineInvocationPlanV1Schema, EngineProgressEventSchema, EngineToolNameSchema, EventRetentionSchema, EventStreamModeSchema, ExecutionDurabilitySchema, HostKindSchema, HostProfileSchema, TaskAssignParamsSchema, } from './schemas.js';
+/* ── 结构化输入 ── */
+/**
+ * startRun() 的初始输入 block。image/file 必须使用经授权的 artifact/resource
+ * reference，不得接受调用方机器的任意绝对路径。
+ */
+export const EngineContentBlockSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('text'),
+        text: z.string(),
+    }),
+    z.object({
+        kind: z.literal('image_ref'),
+        artifactRef: z.string().min(1),
+        mimeType: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal('file_ref'),
+        artifactRef: z.string().min(1),
+        name: z.string().optional(),
+        mimeType: z.string().optional(),
+    }),
+    z.object({
+        kind: z.literal('resource_ref'),
+        uri: z.string().min(1),
+        mimeType: z.string().optional(),
+    }),
+]);
+/** 调用方选择的 Engine mode/config；随 startRun() 原子提交。不得包含敏感配置键。 */
+export const EngineOptionSelectionSchema = z.object({
+    modeId: z.string().min(1).optional(),
+    values: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+});
+/* ── 稳定身份：Instance / Session / Run ── */
+/** 跨 Run 稳定的执行实例引用。 */
+export const ExecutionInstanceRefSchema = z.object({
+    instanceId: z.string().min(1),
+    hostKind: HostKindSchema,
+});
+/** Run provenance：冻结本次执行环境版本，用于历史解释、漂移检测与计量归因。 */
+export const RunExecutionSnapshotSchema = z.object({
+    hostProfile: HostProfileSchema.optional(),
+    digitalEmployeeId: z.string().optional(),
+    projectId: z.string().optional(),
+    configurationRevision: z.string().optional(),
+    imageDigest: z.string().optional(),
+});
+/**
+ * Engine 原生 Session 稳定身份。只使用 stable instance + engineId + sessionId；
+ * configurationRevision、imageDigest、项目和员工归属属于 Run provenance 或授权范围，
+ * 不进入 Session 身份。
+ */
+export const AgentEngineSessionRefSchema = z.object({
+    instance: ExecutionInstanceRefSchema,
+    engineId: EngineIdSchema,
+    sessionId: z.string().min(1),
+});
+/** Session binding：继续历史会话 SHALL 通过 startRun() 的 resume/fork 创建新 Run。 */
+export const EngineSessionBindingSchema = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('ephemeral') }),
+    z.object({ mode: z.literal('new') }),
+    z.object({
+        mode: z.literal('resume'),
+        session: AgentEngineSessionRefSchema,
+    }),
+    z.object({
+        mode: z.literal('fork'),
+        session: AgentEngineSessionRefSchema,
+    }),
+]);
+/** 一次不可变执行的稳定身份；Server 重启后仅凭该 Ref 恢复 getRunStatus/watchRun/cancelRun。 */
+export const AgentEngineRunRefSchema = z.object({
+    instance: ExecutionInstanceRefSchema,
+    executionSnapshot: RunExecutionSnapshotSchema,
+    runKey: z.string().min(1),
+    engineId: EngineIdSchema,
+    invocationFingerprint: z.string().min(1),
+});
+/**
+ * 两阶段启动的持久化记录：只包含完整 RunRef、launchSpecRef 与 preparedAt，
+ * 不得包含 prompt 副本或 control binding secret。
+ */
+export const PreparedRunRecordSchema = z.object({
+    ref: AgentEngineRunRefSchema,
+    launchSpecRef: z.string().min(1),
+    preparedAt: z.string().min(1),
+});
+/* ── Context budget（adapter 入口 last-mile 压缩配置） ── */
+export const ContextCompressionModeSchema = z.enum(['none', 'truncate_head', 'truncate_tail']);
+export const ContextBudgetSchema = z.object({
+    /** 当前 turn 输入文本的最大字符数（不含 systemPrompt）。 */
+    maxInputChars: z.number().int().positive().optional(),
+    /** systemPrompt 的最大字符数。 */
+    maxSystemChars: z.number().int().positive().optional(),
+    /** input + systemPrompt 的总字符数上限；优先压缩 input，必要时再压缩 systemPrompt。 */
+    maxContextChars: z.number().int().positive().optional(),
+    /** 压缩/截断模式；缺省由 adapter 按 'truncate_head' 处理（body-first）。 */
+    compression: ContextCompressionModeSchema.optional(),
+});
+/* ── V2 调用计划与 canonical LaunchSpec ── */
+/**
+ * V2 调用计划：结构化 blocks、model、permission、engineOptions 与 Session binding。
+ * 公共请求 DTO，MUST NOT 包含 Hook 字段、callback 或 secret。
+ */
+export const EngineInvocationPlanV2Schema = z.object({
+    schemaVersion: z.literal(2),
+    taskId: z.string().min(1),
+    engineId: EngineIdSchema,
+    hostKind: HostKindSchema,
+    hostProfile: HostProfileSchema.optional(),
+    toolName: EngineToolNameSchema,
+    input: z.object({
+        blocks: z.array(EngineContentBlockSchema).min(1),
+    }),
+    model: z
+        .object({
+        modelId: z.string().min(1),
+        reasoningEffort: z.string().min(1).optional(),
+    })
+        .optional(),
+    permissionMode: z.string().min(1).optional(),
+    engineOptions: EngineOptionSelectionSchema.optional(),
+    /** 非敏感系统提示词（每次 Run 随 plan 原子提交）；secret 走 Host 私有 binding。 */
+    systemPrompt: z.string().optional(),
+    workDir: z.string().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    /** 仅允许非敏感、可序列化配置；secret 走 Host 私有 binding。 */
+    env: z.record(z.string(), z.string()).optional(),
+    allowedTools: z.array(z.string()).optional(),
+    session: EngineSessionBindingSchema.optional(),
+    artifactPolicy: z.record(z.string(), z.unknown()).optional(),
+    /** 当前 turn 上下文预算；adapter 在入口对 input + systemPrompt 做 last-mile 截断。 */
+    contextBudget: ContextBudgetSchema.optional(),
+});
+/** V1/V2 compatibility union parser；Gateway canonicalizer 统一输出 V2。 */
+export const EngineInvocationPlanSchema = z.union([
+    EngineInvocationPlanV2Schema,
+    EngineInvocationPlanV1Schema,
+]);
+/** 边界兼容 parser：接受 V1 或 V2，不做语义重解释。 */
+export function parseEngineInvocationPlan(input) {
+    return EngineInvocationPlanSchema.parse(input);
+}
+/**
+ * V1→V2 canonicalizer：字符串 input 确定性转换为单个 text block；
+ * V1 sessionId+resume 映射为 resume/fork 之外的 Session binding 需要 instance 上下文。
+ */
+export function normalizeEngineInvocationPlanToV2(plan, context = {}) {
+    if ('schemaVersion' in plan && plan.schemaVersion === 2) {
+        return plan;
+    }
+    const v1 = plan;
+    let session;
+    if (v1.sessionId) {
+        if (!context.instance) {
+            throw new Error('normalizeEngineInvocationPlanToV2: V1 sessionId 需要 instance 上下文才能构造 SessionRef');
+        }
+        session = {
+            mode: 'resume',
+            session: {
+                instance: context.instance,
+                engineId: v1.engineId,
+                sessionId: v1.sessionId,
+            },
+        };
+    }
+    return {
+        schemaVersion: 2,
+        taskId: v1.taskId,
+        engineId: v1.engineId,
+        hostKind: v1.hostKind,
+        ...(v1.hostProfile ? { hostProfile: v1.hostProfile } : {}),
+        toolName: v1.toolName,
+        input: { blocks: [{ kind: 'text', text: v1.input }] },
+        ...(v1.workDir ? { workDir: v1.workDir } : {}),
+        ...(v1.timeoutMs != null ? { timeoutMs: v1.timeoutMs } : {}),
+        ...(v1.env ? { env: v1.env } : {}),
+        ...(v1.allowedTools ? { allowedTools: v1.allowedTools } : {}),
+        ...(session ? { session } : {}),
+        ...(v1.artifactPolicy ? { artifactPolicy: v1.artifactPolicy } : {}),
+    };
+}
+/**
+ * Host-neutral canonical 启动描述：默认值已展开、确定性排序/去重、
+ * 剥离仅用于业务审计的字段。fingerprint 只对该 spec 的非敏感字段计算。
+ * MUST NOT 包含 Pod argv、Sandbox command、External RPC frame、callback 或 secret。
+ */
+export const EngineLaunchSpecSchema = z.object({
+    schemaVersion: z.number().int().positive(),
+    engineId: EngineIdSchema,
+    hostKind: HostKindSchema,
+    input: z.object({
+        blocks: z.array(EngineContentBlockSchema).min(1),
+    }),
+    model: z
+        .object({
+        modelId: z.string().min(1),
+        reasoningEffort: z.string().min(1).optional(),
+    })
+        .optional(),
+    permissionMode: z.string().min(1).optional(),
+    engineOptions: EngineOptionSelectionSchema.optional(),
+    /** 非敏感系统提示词；参与 fingerprint，fingerprint 后不得修改。 */
+    systemPrompt: z.string().optional(),
+    workDir: z.string().optional(),
+    timeoutMs: z.number().int().positive(),
+    allowedTools: z.array(z.string()),
+    session: EngineSessionBindingSchema,
+    /** 内部受治理 Profile；按 profileId/version 确定性排序去重，参与 fingerprint。 */
+    engineHookProfiles: z.array(EngineHookProfileRefSchema),
+    nonSensitiveEnv: z.record(z.string(), z.string()),
+    artifactPolicy: z.record(z.string(), z.unknown()),
+    /** 当前 turn 上下文预算；参与 fingerprint，fingerprint 后不得修改。 */
+    contextBudget: ContextBudgetSchema.optional(),
+});
+/* ── Sensitive Run control bindings（external-computer） ── */
+/**
+ * SENSITIVE：external-computer 只允许短期、Run-scoped 的 capability token 与
+ * 无明文 credential reference；禁止任意 secret map。
+ * 字段值禁止进入日志、持久化 metadata、trace、fingerprint、事件与 Run 文件。
+ */
+export const ExternalTaskSecretBindingsSchema = z.object({
+    mcpCapabilityToken: z.string().min(1).optional(),
+    credentialReferences: z.array(z.string().min(1)).optional(),
+});
+/* ── 交互与取消 DTO ── */
+export const EngineRunErrorSchema = z.object({
+    code: z.string().min(1),
+    message: z.string(),
+    retryable: z.boolean().optional(),
+});
+export const EngineInteractionRequestSchema = z.object({
+    interactionId: z.string().min(1),
+    interactionType: z.enum(['permission', 'confirmation', 'question', 'selection']),
+    /** 最小必要的用户决策说明；权限请求只传用户决策所需的摘要。 */
+    prompt: z.string(),
+    options: z.array(EngineInteractionOptionSchema),
+    timeoutMs: z.number().int().positive().optional(),
+});
+/** 交互回复：responseId 幂等，interactionId 关联请求；不重复携带 instance/runKey。 */
+export const EngineInteractionResponseSchema = z.object({
+    responseId: z.string().min(1),
+    interactionId: z.string().min(1),
+    answer: z.discriminatedUnion('kind', [
+        z.object({
+            kind: z.literal('option'),
+            optionId: z.string().min(1),
+        }),
+        z.object({
+            kind: z.literal('text'),
+            text: z.string(),
+        }),
+    ]),
+});
+export const EngineInteractionReceiptSchema = z.object({
+    status: z.enum(['accepted', 'duplicate', 'rejected']),
+    responseId: z.string().min(1),
+    interactionId: z.string().min(1),
+    error: EngineRunErrorSchema.optional(),
+});
+export const EngineCancelRequestSchema = z.object({
+    requestId: z.string().min(1).optional(),
+    reason: z.string().optional(),
+});
+export const EngineCancelReceiptSchema = z.object({
+    status: z.enum(['accepted', 'duplicate', 'already_terminal', 'rejected']),
+    error: EngineRunErrorSchema.optional(),
+});
+/* ── 事件 Envelope 与 Run 快照 ── */
+/**
+ * Host 标准化后的统一事件 Envelope。Supervisor 或 daemon Run Registry 分配
+ * 单调递增 sequence；Gateway 只校验 runKey/engineId/fingerprint/sequence，
+ * 不解释 Engine 私有 frame。
+ */
+export const EngineEventEnvelopeSchema = z.object({
+    runKey: z.string().min(1),
+    engineId: EngineIdSchema,
+    invocationFingerprint: z.string().min(1),
+    sequence: z.number().int().positive(),
+    timestamp: z.string().min(1),
+    event: EngineProgressEventSchema,
+});
+export const EngineRunStatusSchema = z.enum([
+    'accepted',
+    'starting',
+    'running',
+    'waiting_interaction',
+    'cancel_requested',
+    'completed',
+    'failed',
+    'cancelled',
+    'interrupted',
+]);
+/** Host launch ack：只表达 accepted/existing，并返回本次实际协商的运行属性。 */
+export const HostLaunchAckSchema = z.object({
+    disposition: z.enum(['accepted', 'existing']),
+    ref: AgentEngineRunRefSchema,
+    sessionRef: AgentEngineSessionRefSchema.optional(),
+    executionDurability: ExecutionDurabilitySchema,
+    eventStreamMode: EventStreamModeSchema,
+    eventRetention: EventRetentionSchema.optional(),
+    runtimeVersion: z.string().optional(),
+    protocolVersion: z.string().optional(),
+});
+/** 单次 Run 的一致快照；业务恢复语义只能使用该 Run 级快照。 */
+export const EngineRunSnapshotSchema = z.object({
+    ref: AgentEngineRunRefSchema,
+    sessionRef: AgentEngineSessionRefSchema.optional(),
+    status: EngineRunStatusSchema,
+    executionDurability: ExecutionDurabilitySchema,
+    eventStreamMode: EventStreamModeSchema,
+    eventRetention: EventRetentionSchema.optional(),
+    lastSequence: z.number().int().nonnegative(),
+    pendingInteractions: z.array(EngineInteractionRequestSchema),
+    result: EngineFinalResultSchema.optional(),
+    recoverable: z.boolean(),
+    runtimeVersion: z.string().optional(),
+    protocolVersion: z.string().optional(),
+});
+/** Host wire：活动 Run 分页。 */
+export const ActiveRunListQuerySchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().positive(),
+    engineId: EngineIdSchema.optional(),
+});
+export const ActiveRunSummarySchema = z.object({
+    ref: AgentEngineRunRefSchema,
+    sessionRef: AgentEngineSessionRefSchema.optional(),
+    status: z.enum(['accepted', 'starting', 'running', 'waiting_interaction', 'cancel_requested']),
+    startedAt: z.string().optional(),
+    lastSequence: z.number().int().nonnegative(),
+    pendingInteractionCount: z.number().int().nonnegative(),
+});
+export const ActiveRunPageSchema = z.object({
+    runs: z.array(ActiveRunSummarySchema),
+    nextCursor: z.string().optional(),
+});
+/* ── Engine 原生 Session 数据面 ── */
+export const EngineSessionProjectScopeSchema = z.object({
+    projectId: z.string().optional(),
+    normalizedWorkDir: z.string().optional(),
+});
+export const EngineSessionListQuerySchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().positive(),
+    projectScope: EngineSessionProjectScopeSchema.optional(),
+});
+export const EngineSessionHistoryQuerySchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().positive(),
+    /** 定位 Engine 原生 Session 所需的项目/工作目录范围（语义=SDK 的 dir=projectPath，非 HOME）。 */
+    projectScope: EngineSessionProjectScopeSchema.optional(),
+    /** 需要额外授权与显式 opt-in；响应仍必须深度 redaction。 */
+    includeRawMessages: z.boolean().optional(),
+    /**
+     * 以下两项为 workstation-only 诊断选项（task 7.15）：external Host 忽略，
+     * workstation Host 透传给 Pod CLI 用于富诊断输出。
+     * - includeSystem：是否纳入 system/summary 消息。
+     * - noTruncate：是否禁止截断长消息（用于 diagnostics 全量回放）。
+     */
+    includeSystem: z.boolean().optional(),
+    noTruncate: z.boolean().optional(),
+    /** 是否只返回 session 元数据，跳过消息体（用于初始详情加载，避免大 payload 触发 sandbox stdout 截断）。 */
+    noMessages: z.boolean().optional(),
+    /**
+     * 是否返回拼接文本格式的消息（user/assistant 交替文本），替代结构化 messages[]。
+     * 体积远小于结构化 messages[]，可避免大会话触发 sandbox stdout 截断，
+     * 同时前端仍能获得完整对话文本。
+     */
+    joinedMessages: z.boolean().optional(),
+});
+export const EngineSessionSearchQuerySchema = z.object({
+    text: z.string().min(1),
+    cursor: z.string().optional(),
+    limit: z.number().int().positive(),
+    projectScope: EngineSessionProjectScopeSchema.optional(),
+});
+export const EngineSessionMessageSchema = z.object({
+    messageId: z.string().optional(),
+    role: z.enum(['user', 'assistant', 'system', 'tool', 'unknown']),
+    content: z.array(EngineContentBlockSchema),
+    timestamp: z.string().optional(),
+    redacted: z.boolean(),
+});
+export const EngineSessionSummarySchema = z.object({
+    ref: AgentEngineSessionRefSchema,
+    /** Engine 原生 Session 与 WinMatrix 产品会话使用不同身份与来源标识。 */
+    source: z.literal('engine_native'),
+    title: z.string().optional(),
+    projectId: z.string().optional(),
+    workDir: z.string().optional(),
+    createdAt: z.string().optional(),
+    lastActivityAt: z.string().optional(),
+    messageCount: z.number().int().nonnegative().optional(),
+});
+export const EngineSessionPageSchema = z.object({
+    sessions: z.array(EngineSessionSummarySchema),
+    nextCursor: z.string().optional(),
+});
+export const EngineSessionDetailSchema = z.object({
+    session: EngineSessionSummarySchema,
+    messages: z.array(EngineSessionMessageSchema),
+    /**
+     * 拼接文本格式的消息正文（user/assistant 交替文本）。
+     * 仅当 history query 的 joinedMessages=true 时由 Pod CLI 返回，
+     * 此时 messages 为空数组（schema 必填），正文走本字段以规避 stdout 截断。
+     */
+    joinedMessages: z.string().optional(),
+    nextCursor: z.string().optional(),
+    rawMessagesIncluded: z.boolean(),
+});
+export const EngineSessionSearchHitSchema = z.object({
+    session: EngineSessionSummarySchema,
+    matches: z.array(z.object({
+        messageId: z.string().optional(),
+        snippet: z.string(),
+        timestamp: z.string().optional(),
+    })),
+});
+export const EngineSessionSearchPageSchema = z.object({
+    hits: z.array(EngineSessionSearchHitSchema),
+    nextCursor: z.string().optional(),
+});
+export const EngineSessionDeleteRequestSchema = z.object({
+    requestId: z.string().min(1),
+});
+export const EngineSessionDeleteReceiptSchema = z.object({
+    status: z.enum(['deleted', 'already_deleted', 'rejected']),
+    error: EngineRunErrorSchema.optional(),
+});
+/* ── Engine / 模型 / option 发现 ── */
+export const EngineListQuerySchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().positive(),
+});
+export const EngineInstanceSummarySchema = z.object({
+    engineId: EngineIdSchema,
+    label: z.string().optional(),
+    availability: z.enum(['ready', 'unavailable', 'unknown']),
+    version: z.string().optional(),
+});
+export const EnginePageSchema = z.object({
+    engines: z.array(EngineInstanceSummarySchema),
+    nextCursor: z.string().optional(),
+});
+export const EngineModelListQuerySchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().positive(),
+});
+export const EngineModelDescriptorSchema = z.object({
+    modelId: z.string().min(1),
+    label: z.string().optional(),
+    isDefault: z.boolean(),
+    reasoningEfforts: z.array(z.string()).optional(),
+    contextWindow: z.number().int().positive().optional(),
+});
+export const EngineModelPageSchema = z.object({
+    models: z.array(EngineModelDescriptorSchema),
+    nextCursor: z.string().optional(),
+});
+/**
+ * Engine 实际提供的 mode、config options 与 slash commands。
+ * MUST NOT 暴露系统 Hook Profile、Hook config 或 Hook 实现。
+ */
+export const EngineOptionCatalogSchema = z.object({
+    engineId: EngineIdSchema,
+    modes: z.array(z.object({
+        modeId: z.string().min(1),
+        label: z.string(),
+        description: z.string().optional(),
+        isDefault: z.boolean(),
+    })),
+    configOptions: z.array(z.object({
+        optionId: z.string().min(1),
+        label: z.string(),
+        valueType: z.enum(['select', 'boolean', 'string', 'number']),
+        currentValue: z.union([z.string(), z.number(), z.boolean()]).optional(),
+        allowedValues: z
+            .array(z.object({
+            value: z.string(),
+            label: z.string(),
+        }))
+            .optional(),
+    })),
+    commands: z.array(z.object({
+        command: z.string().min(1),
+        description: z.string().optional(),
+        inputHint: z.string().optional(),
+    })),
+    checkedAt: z.string().min(1),
+});
+/* ── 分层运行诊断 ── */
+export const EngineReadinessIssueSchema = z.object({
+    code: z.string().min(1),
+    message: z.string(),
+});
+export const EngineReadinessSnapshotSchema = z.object({
+    engineId: EngineIdSchema,
+    instanceId: z.string().min(1),
+    hostKind: HostKindSchema,
+    checkedAt: z.string().min(1),
+    status: z.enum(['ready', 'degraded', 'unavailable']),
+    binaryStatus: z.enum(['found', 'missing', 'unsupported_version']),
+    credentialStatus: z.enum(['ready', 'missing', 'invalid', 'not_required', 'unknown']),
+    version: z.string().optional(),
+    issues: z.array(EngineReadinessIssueSchema),
+});
+export const HostHealthIssueSchema = z.object({
+    code: z.string().min(1),
+    message: z.string(),
+});
+const HostHealthSnapshotBaseSchema = z.object({
+    instanceId: z.string().min(1),
+    checkedAt: z.string().min(1),
+    status: z.enum(['healthy', 'degraded', 'unreachable']),
+    transportReady: z.boolean(),
+    latencyMs: z.number().nonnegative().optional(),
+    runtimeVersion: z.string().optional(),
+    protocolVersion: z.string().optional(),
+    configurationRevision: z.string().optional(),
+    imageDigest: z.string().optional(),
+    issues: z.array(HostHealthIssueSchema),
+});
+export const HostHealthSnapshotSchema = z.discriminatedUnion('hostKind', [
+    HostHealthSnapshotBaseSchema.extend({
+        hostKind: z.literal('workstation'),
+        sandboxApiReachable: z.boolean(),
+        podReady: z.boolean(),
+        supervisorReachable: z.boolean(),
+        mountReady: z.boolean().optional(),
+    }),
+    HostHealthSnapshotBaseSchema.extend({
+        hostKind: z.literal('external_computer'),
+        ownerResolved: z.boolean(),
+        connectionReady: z.boolean(),
+        heartbeatFresh: z.boolean(),
+        daemonReady: z.boolean(),
+    }),
+]);
+/* ── Host wire DTO（Server ↔ Sandbox API / daemon） ── */
+/** SENSITIVE：server-pod 私有 binding；callback token/dynamic secret 禁止日志与持久化。 */
+export const WorkstationRunPrivateBindingsSchema = z.object({
+    hostKind: z.literal('workstation'),
+    callback: z
+        .object({
+        url: z.string().min(1),
+        token: z.string().min(1),
+    })
+        .optional(),
+    dynamicSecrets: z.record(z.string(), z.string()).optional(),
+});
+/** SENSITIVE：external-computer 私有 binding；只允许协议定义的 sensitive envelope。 */
+export const ExternalRunPrivateBindingsSchema = z.object({
+    hostKind: z.literal('external_computer'),
+    secrets: ExternalTaskSecretBindingsSchema.optional(),
+});
+export const EngineRunPrivateBindingsSchema = z.discriminatedUnion('hostKind', [
+    WorkstationRunPrivateBindingsSchema,
+    ExternalRunPrivateBindingsSchema,
+]);
+/**
+ * Host launch request：canonical LaunchSpec 与本次 Run 的私有 binding 分字段承载。
+ * 非敏感 payload 走 argv/结构化字段；sensitive binding 走 stdin/Unix socket frame
+ * 或协议 sensitive envelope，禁止写入 argv、普通事件或临时文件。
+ */
+export const HostLaunchRequestSchema = z.object({
+    runKey: z.string().min(1),
+    invocationFingerprint: z.string().min(1),
+    launchSpec: EngineLaunchSpecSchema,
+    privateBindings: EngineRunPrivateBindingsSchema.optional(),
+});
+/* ── External Agent 新版 method params / event payload ── */
+/** task.assign additive 扩展：runKey/fingerprint/Host-neutral LaunchSpec/sensitive envelope。 */
+export const TaskAssignParamsV2Schema = TaskAssignParamsSchema.extend({
+    runKey: z.string().min(1).optional(),
+    invocationFingerprint: z.string().min(1).optional(),
+    launchSpec: EngineLaunchSpecSchema.optional(),
+    /** SENSITIVE：旧 mcpToken 仅兼容映射到 secretBindings.mcpCapabilityToken。 */
+    secretBindings: ExternalTaskSecretBindingsSchema.optional(),
+});
+export const TaskEventsSubscribeParamsSchema = z.object({
+    runKey: z.string().min(1),
+    afterSequence: z.number().int().nonnegative().optional(),
+});
+export const TaskInspectParamsSchema = z.object({
+    runKey: z.string().min(1),
+});
+export const TaskInteractionRespondParamsSchema = z.object({
+    runKey: z.string().min(1),
+    response: EngineInteractionResponseSchema,
+});
+export const TaskCancelRunParamsSchema = z.object({
+    runKey: z.string().min(1),
+    reason: z.string().optional(),
+});
+export const TaskActiveListParamsSchema = ActiveRunListQuerySchema.partial();
+export const TaskResultEventSchema = z.object({
+    runKey: z.string().min(1),
+    result: EngineFinalResultSchema,
+});
+export const AgentEngineModelsParamsSchema = z.object({
+    engineId: EngineIdSchema,
+    cursor: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+});
+export const AgentEngineOptionsParamsSchema = z.object({
+    engineId: EngineIdSchema,
+});
+export const AgentEngineProbeParamsSchema = z.object({
+    engineId: EngineIdSchema,
+});
+export const AgentEngineListParamsSchema = z.object({
+    cursor: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+});
+/** 统一 session.* wire params：完整 SessionRef，禁止外部传 HOME/store path。 */
+export const SessionListParamsV2Schema = z.object({
+    engineId: EngineIdSchema,
+    projectScope: EngineSessionProjectScopeSchema.optional(),
+    cursor: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+});
+export const SessionGetParamsV2Schema = z.object({
+    session: AgentEngineSessionRefSchema,
+    cursor: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+    includeRawMessages: z.boolean().optional(),
+});
+export const SessionSearchParamsSchema = z.object({
+    engineId: EngineIdSchema,
+    projectScope: EngineSessionProjectScopeSchema.optional(),
+    text: z.string().min(1),
+    cursor: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+});
+export const SessionDeleteParamsSchema = z.object({
+    session: AgentEngineSessionRefSchema,
+    requestId: z.string().min(1),
+});
+/** task.event payload：daemon 已标准化的 EngineEventEnvelope。 */
+export const TaskEventPayloadSchema = EngineEventEnvelopeSchema;
+/* ── Hook 协商（Host wire 内部） ── */
+export const HookProfileSupportRequestSchema = z.object({
+    required: z.array(EngineHookProfileRefSchema),
+});
+export const HookProfileSupportResponseSchema = z.object({
+    supported: z.array(EngineHookProfileDescriptorSchema),
+    unsupported: z.array(EngineHookProfileRefSchema),
+});
+/* ── Gateway protocol 版本协商 ── */
+/** daemon/agent-sdk 宣告支持的统一 Gateway protocol version；新 method/event 需先协商。 */
+export const AGENT_ENGINE_GATEWAY_PROTOCOL_VERSION = 1;
+export const AGENT_ENGINE_GATEWAY_MIN_PROTOCOL_VERSION = 1;
+export const GatewayProtocolCapabilitySchema = z.object({
+    gatewayProtocolVersion: z.number().int().positive(),
+    eventStreamMode: EventStreamModeSchema.optional(),
+    supportedEngineHookProfiles: z.array(EngineHookProfileDescriptorSchema).optional(),
+});
+/** Server 只有在 daemon 声明满足最低版本时才启用 ExternalComputerExecutionHost。 */
+export function supportsGatewayProtocol(declaredVersion) {
+    return (typeof declaredVersion === 'number' &&
+        declaredVersion >= AGENT_ENGINE_GATEWAY_MIN_PROTOCOL_VERSION);
+}
+//# sourceMappingURL=agentEngine.js.map