@dshremote/protocol 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @dshremote/protocol
+
+DshRemote 共享协议包：**单一事实来源**，同时被 Connector Plugin 与 Control Plane 引用。
+
+## 内容
+
+| 文件 | 说明 |
+| --- | --- |
+| `schemas/dshremote-event-v1.schema.json` | 事件契约 v1（技术方案 §3）：Connector 上传到 Control Plane 的结构化 Session 事件信封与全部 kind 的 payload |
+| `schemas/dshremote-protocol-v1.schema.json` | 通信协议 v1（技术方案 §4）：C2C 消息信封与全部消息类型的 payload |
+| `src/types.ts` | 上述两个 Schema 的 TS 投影（`DshRemoteEvent` / `C2CMessage` 判别联合） |
+
+## 维护约束
+
+- **三处同步**：修改契约必须同时更新 `src/types.ts`、对应 schema JSON、以及《DshRemote 技术方案》§3/§4。
+- **兼容性**：任何 breaking 变更必须升 `version`/`protocolVersion`/`schemaVersion` 并走连接握手协商（`hello`/`helloAck`），不允许静默改字段。
+- **敏感性**：契约只允许结构化安全子集（脱敏、截断）；完整 Prompt、环境变量、Provider 凭据、不必要的完整命令输出一律禁止进入本契约（FR-009.7）。

package/lib/index.js

@@ -0,0 +1 @@
+export * from './types.js';

package/lib/types/index.d.ts

@@ -0,0 +1 @@
+export * from './types.js';

package/lib/types/types.d.ts

@@ -0,0 +1,572 @@
+/**
+ * @dshremote/protocol —— DshRemote 共享协议类型。
+ *
+ * 单一事实来源：`schemas/dshremote-event-v1.schema.json`（事件契约 v1）
+ * 与 `schemas/dshremote-protocol-v1.schema.json`（Connector↔Control Plane 通信协议）。
+ * 本文件是这些 Schema 的 TS 投影；改动必须三处同步（types.ts / 两个 schema / 设计文档 §3、§4）。
+ *
+ * 对应《DshRemote 技术方案 v0.1》§3（事件契约）与 §4（通信协议）。
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** 通用标识（connectionId / sessionId / runId / taskId / projectId 等）。 */
+export type DshRemoteId = string;
+export declare const EVENT_KINDS: readonly ["sessionMeta", "turnStart", "turnEnd", "stepStart", "stepEnd", "userMessage", "assistantMessage", "toolCall", "toolResult", "error", "approvalAsked", "approvalDecided", "runStatus", "artifactRef"];
+export type EventKind = (typeof EVENT_KINDS)[number];
+/** 文本内容块。 */
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/** 思考/推理内容块（对应 Harness ContentBlock 的 reasoning 类型，渲染为可折叠 "Think"）。 */
+export interface ReasoningBlock {
+    type: 'reasoning';
+    text: string;
+}
+/** 内容块：v1 仅 text + reasoning（与 Harness ContentBlock 对齐）；图片/附件引用留待 v1.1。 */
+export type ContentBlock = TextBlock | ReasoningBlock;
+/** 脱敏后的 token 用量摘要（不允许出现 Provider 原始账单元数据）。 */
+export interface TokenUsageSummary {
+    inputTokens?: number;
+    outputTokens?: number;
+    /** 缓存命中读取 token（provider 回报该桶时才有）。 */
+    cacheReadTokens?: number;
+    /** 缓存写入 token（provider 回报该桶时才有）。 */
+    cacheWriteTokens?: number;
+    /** 推理输出 token 子集（provider 回报该桶时才有）。 */
+    reasoningTokens?: number;
+    /** 输入 + 输出精确合计（provider 回报或可推导时才有）。 */
+    totalTokens?: number;
+    /** 本轮贡献的 provider/model 路由（去重，供「提供方/模型」展示）。 */
+    routes?: Array<{
+        provider?: string;
+        model?: string;
+    }>;
+}
+/**
+ * 单步 LLM 耗时快照（由 connector 在采集时从 harness 事件时间推导，对齐官方
+ * sessionStats 口径：step/start → assistant/message = llmMs；首个 token delta →
+ * ttftMs；随后到 assistant/message = decodeMs）。web 侧据此折叠每轮/全程统计。
+ */
+export interface LLMTiming {
+    /** step/start → assistant/message 的模型墙钟耗时（ms）。 */
+    llmMs: number;
+    /** step/start → 首个 token delta（ms）；该步未产出 token delta 时缺省。 */
+    ttftMs?: number;
+    /** 首个 token delta → assistant/message（ms）；无首 token 时缺省。 */
+    decodeMs?: number;
+}
+/** turn 结束原因，映射自 Harness TurnEndReasonMap（session.md）。 */
+export type TurnEndReason = 'completed' | 'aborted' | 'blocked' | 'error' | 'max-tokens' | 'interrupted';
+/** Run 状态，映射自需求 FR-007。 */
+export type RunStatus = 'Queued' | 'Running' | 'WaitingForApproval' | 'Completed' | 'Failed' | 'Stopped' | 'ConnectionLost' | 'TimedOut' | 'LimitReached';
+/** 审批结果，映射自 Harness ApprovalOutcome（approval.md）。 */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+export interface ErrorSummary {
+    message: string;
+    code?: string;
+    /** 可关联的错误标识（不泄露 Secret）。 */
+    errorId?: string;
+}
+export interface SessionMetaPayload {
+    title?: string;
+    /** cwd 摘要：只允许目录名等非敏感摘要，禁止绝对路径。 */
+    cwdSummary?: string;
+    projectId?: string;
+    createdBy: 'local' | 'webhook' | 'cloud';
+}
+export interface TurnStartPayload {
+    turn: number;
+}
+export interface TurnEndPayload {
+    turn: number;
+    reason: TurnEndReason;
+    error?: ErrorSummary;
+}
+export interface StepStartPayload {
+    turn: number;
+    step: number;
+}
+export interface StepEndPayload {
+    turn: number;
+    step: number;
+}
+export interface UserMessagePayload {
+    content: ContentBlock[];
+    source: 'user' | 'inject' | 'webhook' | 'plugin';
+    /** source 为 'plugin' 时的插件名（远程投递记 'dshremote'；harness 上下文快照记
+     * '@deepseek-ai/dsh-system-prompt'）。web 据此把「远程用户消息」与「上下文注入」区分。 */
+    sourcePlugin?: string;
+    /** source 为 'plugin' 时的 form（如 'snapshot'），用于标注上下文快照。 */
+    sourceForm?: string;
+}
+export interface AssistantMessagePayload {
+    content: ContentBlock[];
+    usage?: TokenUsageSummary;
+    interrupted?: boolean;
+    /** 单步 LLM 耗时（第 3 步采集；被中断/无 timing 时缺省）。 */
+    timing?: LLMTiming;
+}
+export interface ToolCallPayload {
+    callId: string;
+    name: string;
+    /** 模型原始 arguments JSON 字符串（脱敏 + 截断后）。 */
+    arguments: string;
+}
+export interface ToolResultPayload {
+    callId: string;
+    /** 结果摘要（非完整输出）。 */
+    summary?: string;
+    error?: {
+        name: string;
+        code: string;
+    };
+    /** 白名单字段（如 dsh-tool-fs 的上下文 diff），其余丢弃。 */
+    meta?: Record<string, JsonValue>;
+}
+export interface ErrorEventPayload {
+    error: ErrorSummary;
+    /** 关联的 turn（若有）。 */
+    turn?: number;
+}
+export interface ApprovalAskedPayload {
+    requestId: string;
+    toolName: string;
+    callId?: string;
+    reason?: string;
+}
+export interface ApprovalDecidedPayload {
+    requestId: string;
+    outcome: ApprovalOutcome;
+}
+export interface RunStatusPayload {
+    runId: string;
+    status: RunStatus;
+    reason?: string;
+}
+export interface ArtifactRefPayload {
+    artifactId: string;
+    name: string;
+    size: number;
+    type: string;
+    retentionMs?: number;
+    downloadAuthorized: boolean;
+}
+export interface EventEnvelopeBase {
+    schema: 'dshremote.event';
+    version: 1;
+    connectionId: DshRemoteId;
+    sessionId: DshRemoteId;
+    runId?: DshRemoteId;
+    /** Connector 本地分配，按 session 单调递增（seq = 已上传数）。 */
+    seq: number;
+    /** Unix epoch ms。 */
+    time: number;
+    /** 幂等键 = `${connectionId}:${sessionId}:${seq}`。 */
+    msgId: string;
+}
+export type DshRemoteEvent = (EventEnvelopeBase & {
+    kind: 'sessionMeta';
+    payload: SessionMetaPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'turnStart';
+    payload: TurnStartPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'turnEnd';
+    payload: TurnEndPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'stepStart';
+    payload: StepStartPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'stepEnd';
+    payload: StepEndPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'userMessage';
+    payload: UserMessagePayload;
+}) | (EventEnvelopeBase & {
+    kind: 'assistantMessage';
+    payload: AssistantMessagePayload;
+}) | (EventEnvelopeBase & {
+    kind: 'toolCall';
+    payload: ToolCallPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'toolResult';
+    payload: ToolResultPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'error';
+    payload: ErrorEventPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'approvalAsked';
+    payload: ApprovalAskedPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'approvalDecided';
+    payload: ApprovalDecidedPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'runStatus';
+    payload: RunStatusPayload;
+}) | (EventEnvelopeBase & {
+    kind: 'artifactRef';
+    payload: ArtifactRefPayload;
+});
+export declare const C2C_MESSAGE_TYPES: readonly ["hello", "helloAck", "pairing.consume", "pairing.ack", "credential.rotate", "connection.revoke", "project.sync", "session.event", "session.reconcile", "session.gap", "gap.unrecoverable", "session.settings", "session.settingsResult", "session.command", "session.commandResult", "session.create", "session.createResult", "session.queue", "session.queueUpdate", "task.dispatch", "task.sync", "run.ack", "run.control", "run.status", "approval.request", "approval.answer", "approval.localDecided", "artifact.register", "artifact.fetch", "artifact.content", "ping", "pong"];
+export type C2CMessageType = (typeof C2C_MESSAGE_TYPES)[number];
+export interface C2CMessageBase {
+    v: 1;
+    /** 幂等键（uuid），两端各自去重。 */
+    msgId: string;
+    ackId?: string;
+}
+export interface HelloPayload {
+    protocolVersion: 1;
+    schemaVersion: 1;
+    connectionId: DshRemoteId;
+    /** 一次性 nonce，签名原文 = connectionId + ':' + nonce。 */
+    nonce: string;
+    /** 长期凭证（Ed25519 私钥）对 nonce 的签名，base64。 */
+    signature: string;
+    capabilities: {
+        harnessVersion: string;
+        pluginVersion: string;
+        profile: string;
+        providers: string[];
+    };
+    /** 节点友好名（hostname / 自定义），供云端多节点识别；缺省回退 connectionId 略称。 */
+    nodeName?: string;
+}
+export interface HelloAckPayload {
+    accepted: boolean;
+    protocolVersion: 1;
+    schemaVersion: 1;
+    reason?: string;
+}
+export interface PairingConsumePayload {
+    ticket: string;
+    /** 本机生成的 Ed25519 公钥（base64），注册到 Control Plane。 */
+    publicKey: string;
+}
+/** P→C：配对消费结果。 */
+export interface PairingAckPayload {
+    connectionId: DshRemoteId;
+    accepted: boolean;
+    reason?: string;
+}
+export interface CredentialRotatePayload {
+    requestId: string;
+    /** P→C 触发时省略；C→P 应答时携带新公钥。 */
+    publicKey?: string;
+}
+export interface ConnectionRevokePayload {
+    reason?: string;
+}
+export interface ProjectSummary {
+    projectId: DshRemoteId;
+    displayName: string;
+    repoSummary?: string;
+    branchSummary?: string;
+    available: boolean;
+    lastSyncedAt: number;
+}
+export interface ProjectSyncPayload {
+    projects: ProjectSummary[];
+    /** 本机移除/不可用的 projectId。 */
+    removed: DshRemoteId[];
+}
+export interface SessionEventPayload {
+    event: DshRemoteEvent;
+}
+export interface SessionReconcileEntry {
+    sessionId: DshRemoteId;
+    /** 已同步的最大 seq；-1 表示尚未同步。 */
+    lastSyncedSeq: number;
+    status: 'active' | 'ended' | 'unknown';
+}
+export interface SessionReconcilePayload {
+    sessions: SessionReconcileEntry[];
+    /** 当前 connector 进程拥有的云端会话 id（createRemoteSession 创建的 agent 句柄）。
+     * 供云端判定会话是否可写：非 owned 的会话设置控件在 UI 上应禁用。 */
+    ownedSessionIds?: string[];
+}
+/** P→C：云端发现缺口后请求补拉（fromSeq 不含、toSeq 含）。 */
+export interface SessionGapPayload {
+    sessionId: DshRemoteId;
+    fromSeq: number;
+    toSeq: number;
+}
+/**
+ * C→P：缺口不可完整补拉（FR-005.9 v1.1）。
+ * Connector 配置了重放上限（cap>0）且请求区间早于保留窗口时回发——
+ * 避免云端静默拿到部分数据造成永久缺口。云端收到后应记录并告警
+ * （不无限重试同一区间）。
+ */
+export interface GapUnrecoverablePayload {
+    sessionId: DshRemoteId;
+    /** 云端请求的 fromSeq（不含）。 */
+    fromSeq: number;
+    /** Connector 本地保留的最早 seq（含）；缺失部分为 [fromSeq+1, oldestSeq-1]。 */
+    oldestSeq: number;
+    /** 云端请求的 toSeq（含），用于记录区间。 */
+    toSeq: number;
+}
+export interface TaskDispatchPayload {
+    deliveryId: string;
+    /** Control Plane 派发时即创建的 Run 记录 id（run.ack 回填）。 */
+    runId: DshRemoteId;
+    taskId: string;
+    projectId: DshRemoteId;
+    prompt: string;
+    /** 允许范围内的策略覆盖（FR-006.5）。 */
+    policyOverrides?: Record<string, JsonValue>;
+    offlinePolicy: 'skip' | 'deliver_later' | 'queue';
+    /** 重试时递增；同一 deliveryId 的首次尝试为 1。 */
+    attempt: number;
+}
+/**
+ * 本地 Harness 任务投影（FR-006.10）：Connector 把授权范围内本地创建的
+ * 临时/定时任务（Harness schedule 事件折叠）同步到云端，仅作只读展示，
+ * 不参与云端调度（FR-006.4：云端定时器是权威，本地 schedule 不自动等同）。
+ */
+export interface LocalTaskSummary {
+    /** 本地稳定标识（Harness ScheduleId）。 */
+    localTaskId: string;
+    /** 所属本地 Session。 */
+    sessionId: DshRemoteId;
+    name: string;
+    prompt: string;
+    /** 一次性（after/at）或重复（every）。 */
+    kind: 'after' | 'at' | 'every';
+    /** RFC3339 或 afterSeconds 摘要，仅展示。 */
+    scheduleSummary?: string;
+    /** 最近一次活动（创建/派发）时刻。 */
+    updatedAt: number;
+}
+export interface TaskSyncPayload {
+    /** 授权范围内全部本地任务（全量快照，替换式）。 */
+    tasks: LocalTaskSummary[];
+}
+export interface RunAckPayload {
+    deliveryId: string;
+    accepted: boolean;
+    reason?: string;
+    runId?: DshRemoteId;
+    sessionId?: DshRemoteId;
+}
+export interface RunControlPayload {
+    runId: DshRemoteId;
+    sessionId?: DshRemoteId;
+    action: 'stop' | 'resume' | 'retry';
+    /** resume/retry 时的下一条用户消息。 */
+    message?: string;
+}
+/** P→C：云端修改会话设置（FR-005.x）。model/reasoningEffort 随时可改；preset 仅空白会话可改。 */
+export interface SessionSettingsPayload {
+    sessionId: DshRemoteId;
+    provider?: string;
+    model?: string;
+    reasoningEffort?: string;
+    /** 仅当会话尚未产生首条消息（turn/start 未提交）时可设置；否则 Harness 抛 agent-preset-locked。 */
+    preset?: string;
+}
+/** C→P：会话设置应用结果。 */
+export interface SessionSettingsResultPayload {
+    sessionId: DshRemoteId;
+    ok: boolean;
+    reason?: string;
+}
+/** P→C：会话命令（goal/plan）。由 Harness 插件（dsh-goal / dsh-plan-mode）真实执行。 */
+export interface SessionCommandPayload {
+    sessionId: DshRemoteId;
+    command: 'plan' | 'goal';
+    /** plan：目标状态（缺省则切换当前）；goal：目标文本（objective 必填）。 */
+    active?: boolean;
+    objective?: string;
+}
+/** C→P：会话命令执行结果。 */
+export interface SessionCommandResultPayload {
+    sessionId: DshRemoteId;
+    command: 'plan' | 'goal';
+    ok: boolean;
+    reason?: string;
+    /** 结果摘要（流程：plan 目标状态 / goal 目标摘要）。 */
+    detail?: string;
+}
+/** P→C：同步创建远程会话（connector 建好 agent 会话并返回 sessionId，供 UI 直接进入）。 */
+export interface SessionCreatePayload {
+    projectId: DshRemoteId;
+    prompt: string;
+    /** 创建时指定模型（可缺省，connector 用默认 deepseek-v4-flash）。 */
+    model?: string;
+    /** 创建时指定思考强度（reasoningEffort，如 off/low/high/max）。 */
+    effort?: string;
+}
+/** C→P：同步创建会话结果。 */
+export interface SessionCreateResultPayload {
+    ok: boolean;
+    sessionId?: DshRemoteId;
+    reason?: string;
+}
+/** C→P：审批已在本地（dsh）决定——通知云端撤销该 pending 审批，云端弹窗随之关闭。 */
+export interface ApprovalLocalDecidedPayload {
+    requestId: string;
+    outcome: ApprovalOutcome;
+}
+/** C→P：会话排队消息快照（来自 harness agent.inbox.nextTurn，云端镜像显示，刷新不丢）。 */
+export interface SessionQueuePayload {
+    sessionId: DshRemoteId;
+    items: Array<{
+        id: string;
+        text: string;
+    }>;
+}
+/** P→C：对会话排队消息的操作（编辑/删除/插队），落 harness agent.inbox。 */
+export interface SessionQueueUpdatePayload {
+    sessionId: DshRemoteId;
+    itemId?: string;
+    action: 'edit' | 'remove' | 'insert';
+    /** edit 或 insert 的文本内容。 */
+    text?: string;
+}
+export interface ApprovalRequestPayload {
+    requestId: string;
+    agentId?: string;
+    sessionId?: DshRemoteId;
+    runId?: DshRemoteId;
+    toolName: string;
+    callId?: string;
+    reason?: string;
+    /** 审批有效期（epoch ms），过期按 rejected 处理。 */
+    expiresAt: number;
+}
+export interface ApprovalAnswerPayload {
+    requestId: string;
+    outcome: ApprovalOutcome;
+}
+export interface ArtifactRegisterPayload {
+    artifactId: string;
+    runId: DshRemoteId;
+    name: string;
+    size: number;
+    type: string;
+    retentionMs?: number;
+}
+/** FR-009.6：云端发起制品受控下载（CP → Connector）。 */
+export interface ArtifactFetchPayload {
+    requestId: string;
+    artifactId: string;
+    runId: DshRemoteId;
+    /** 单次下载最大字节（Connector 超限拒绝）；缺省用协议默认值。 */
+    maxBytes?: number;
+}
+/** FR-009.6：Connector 回传制品内容（base64，小文件/文本结果）。 */
+export interface ArtifactContentPayload {
+    requestId: string;
+    ok: boolean;
+    error?: string;
+    name?: string;
+    type?: string;
+    size?: number;
+    /** base64 编码的制品内容。 */
+    contentBase64?: string;
+}
+export interface PingPayload {
+    t: number;
+}
+export type C2CMessage = (C2CMessageBase & {
+    type: 'hello';
+    payload: HelloPayload;
+}) | (C2CMessageBase & {
+    type: 'helloAck';
+    payload: HelloAckPayload;
+}) | (C2CMessageBase & {
+    type: 'pairing.consume';
+    payload: PairingConsumePayload;
+}) | (C2CMessageBase & {
+    type: 'pairing.ack';
+    payload: PairingAckPayload;
+}) | (C2CMessageBase & {
+    type: 'credential.rotate';
+    payload: CredentialRotatePayload;
+}) | (C2CMessageBase & {
+    type: 'connection.revoke';
+    payload: ConnectionRevokePayload;
+}) | (C2CMessageBase & {
+    type: 'project.sync';
+    payload: ProjectSyncPayload;
+}) | (C2CMessageBase & {
+    type: 'session.event';
+    payload: SessionEventPayload;
+}) | (C2CMessageBase & {
+    type: 'session.reconcile';
+    payload: SessionReconcilePayload;
+}) | (C2CMessageBase & {
+    type: 'session.gap';
+    payload: SessionGapPayload;
+}) | (C2CMessageBase & {
+    type: 'gap.unrecoverable';
+    payload: GapUnrecoverablePayload;
+}) | (C2CMessageBase & {
+    type: 'session.settings';
+    payload: SessionSettingsPayload;
+}) | (C2CMessageBase & {
+    type: 'session.settingsResult';
+    payload: SessionSettingsResultPayload;
+}) | (C2CMessageBase & {
+    type: 'session.command';
+    payload: SessionCommandPayload;
+}) | (C2CMessageBase & {
+    type: 'session.commandResult';
+    payload: SessionCommandResultPayload;
+}) | (C2CMessageBase & {
+    type: 'session.create';
+    payload: SessionCreatePayload;
+}) | (C2CMessageBase & {
+    type: 'session.createResult';
+    payload: SessionCreateResultPayload;
+}) | (C2CMessageBase & {
+    type: 'session.queue';
+    payload: SessionQueuePayload;
+}) | (C2CMessageBase & {
+    type: 'session.queueUpdate';
+    payload: SessionQueueUpdatePayload;
+}) | (C2CMessageBase & {
+    type: 'task.dispatch';
+    payload: TaskDispatchPayload;
+}) | (C2CMessageBase & {
+    type: 'task.sync';
+    payload: TaskSyncPayload;
+}) | (C2CMessageBase & {
+    type: 'run.ack';
+    payload: RunAckPayload;
+}) | (C2CMessageBase & {
+    type: 'run.control';
+    payload: RunControlPayload;
+}) | (C2CMessageBase & {
+    type: 'run.status';
+    payload: RunStatusPayload;
+}) | (C2CMessageBase & {
+    type: 'approval.request';
+    payload: ApprovalRequestPayload;
+}) | (C2CMessageBase & {
+    type: 'approval.answer';
+    payload: ApprovalAnswerPayload;
+}) | (C2CMessageBase & {
+    type: 'approval.localDecided';
+    payload: ApprovalLocalDecidedPayload;
+}) | (C2CMessageBase & {
+    type: 'artifact.register';
+    payload: ArtifactRegisterPayload;
+}) | (C2CMessageBase & {
+    type: 'artifact.fetch';
+    payload: ArtifactFetchPayload;
+}) | (C2CMessageBase & {
+    type: 'artifact.content';
+    payload: ArtifactContentPayload;
+}) | (C2CMessageBase & {
+    type: 'ping';
+    payload: PingPayload;
+}) | (C2CMessageBase & {
+    type: 'pong';
+    payload: PingPayload;
+});
+/** 生成 msgId 幂等键：`${connectionId}:${sessionId}:${seq}`（事件）或 uuid（控制消息）。 */
+export declare function eventMsgId(connectionId: DshRemoteId, sessionId: DshRemoteId, seq: number): string;

package/lib/types.js

@@ -0,0 +1,81 @@
+/**
+ * @dshremote/protocol —— DshRemote 共享协议类型。
+ *
+ * 单一事实来源：`schemas/dshremote-event-v1.schema.json`（事件契约 v1）
+ * 与 `schemas/dshremote-protocol-v1.schema.json`（Connector↔Control Plane 通信协议）。
+ * 本文件是这些 Schema 的 TS 投影；改动必须三处同步（types.ts / 两个 schema / 设计文档 §3、§4）。
+ *
+ * 对应《DshRemote 技术方案 v0.1》§3（事件契约）与 §4（通信协议）。
+ */
+// ---------------------------------------------------------------------------
+// 事件契约 v1（技术方案 §3）
+// ---------------------------------------------------------------------------
+export const EVENT_KINDS = [
+    'sessionMeta',
+    'turnStart',
+    'turnEnd',
+    'stepStart',
+    'stepEnd',
+    'userMessage',
+    'assistantMessage',
+    'toolCall',
+    'toolResult',
+    'error',
+    'approvalAsked',
+    'approvalDecided',
+    'runStatus',
+    'artifactRef',
+];
+// ---------------------------------------------------------------------------
+// 通信协议 v1（技术方案 §4）
+// ---------------------------------------------------------------------------
+export const C2C_MESSAGE_TYPES = [
+    // 握手与版本协商
+    'hello',
+    'helloAck',
+    // 配对与凭证
+    'pairing.consume',
+    'pairing.ack',
+    'credential.rotate',
+    'connection.revoke',
+    // 项目
+    'project.sync',
+    // Session 事件与对账
+    'session.event',
+    'session.reconcile',
+    'session.gap',
+    'gap.unrecoverable',
+    // 会话设置
+    'session.settings',
+    'session.settingsResult',
+    // 会话命令（goal/plan）
+    'session.command',
+    'session.commandResult',
+    // 同步创建远程会话
+    'session.create',
+    'session.createResult',
+    // 会话排队消息（镜像 harness agent.inbox）
+    'session.queue',
+    'session.queueUpdate',
+    // 任务与 Run
+    'task.dispatch',
+    'task.sync',
+    'run.ack',
+    'run.control',
+    'run.status',
+    // 审批
+    'approval.request',
+    'approval.answer',
+    'approval.localDecided',
+    // 制品
+    'artifact.register',
+    'artifact.fetch',
+    'artifact.content',
+    // 心跳
+    'ping',
+    'pong',
+];
+/** 生成 msgId 幂等键：`${connectionId}:${sessionId}:${seq}`（事件）或 uuid（控制消息）。 */
+export function eventMsgId(connectionId, sessionId, seq) {
+    return `${connectionId}:${sessionId}:${seq}`;
+}