@tunnelbox/core 0.1.0 → 0.1.8

package/src/types.ts

@@ -1,127 +1,175 @@
-/**
- * tunnelbox 统一协议类型（各智能体适配器共享）。
- * 与 relay/internal/proto、web/src/protocol 通过 JSON 互通（镜像维护）。
- */
-
-export interface Envelope<T = unknown> {
-  id?: string;
-  type: string;
-  payload: T;
-  ts: number;
-  /** 中继注入/回填：手机端会话 id，用于回路由 */
-  clientID?: string;
-}
-
-export function envelope<T>(type: string, payload: T, id?: string): Envelope<T> {
-  return { id, type, payload, ts: Date.now() };
-}
-
-export interface AgentInfo {
-  name: string;
-  version: string;
-  platform?: string;
-  directory?: string;
-  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor */
-  type?: string;
-  /** IANA 时区名（如 Asia/Shanghai），仅用于"电脑本地时间"展示 */
-  timezone?: string;
-  /** 能力位 */
-  capabilities?: {
-    streaming?: boolean;
-    thinking?: boolean;
-    permission?: boolean;
-    commands?: boolean;
-    abort?: boolean;
-  };
-}
-
-export type SessionStatus = "queued" | "running" | "idle" | "error";
-
-export interface SessionInfo {
-  id: string;
-  title: string;
-  created: number;
-  updated: number;
-  status: SessionStatus;
-  /** 会话所在工作区目录（dsh 按 workspace 分目录持久化） */
-  workspace?: string;
-}
-
-export interface WorkspaceInfo {
-  /** 工作区目录绝对路径 */
-  path: string;
-  /** 展示名（取目录名） */
-  name: string;
-  /** 该工作区内的会话数 */
-  sessionCount: number;
-  /** 最近会话更新时间 */
-  updated: number;
-}
-
-export interface Part {
-  id: string;
-  type: "text" | "tool" | "thinking";
-  text?: string;
-  delta?: string;
-  tool?: string;
-  args?: string;
-  complete?: boolean;
-}
-
-export interface ChatMessage {
-  id: string;
-  role: "user" | "assistant" | "tool" | "system";
-  parts: Part[];
-  created: number;
-}
-
-/** 权限请求的作答方式：approval=允许/拒绝/总是允许；choice=从选项中选择；input=输入文本。 */
-export type PermissionKind = "approval" | "choice" | "input";
-
-export interface PermissionRequest {
-  id: string;
-  sessionID: string;
-  tool: string;
-  args: Record<string, unknown>;
-  prompt?: string;
-  createdAt: number;
-  /** 作答方式（缺省视为 approval） */
-  kind?: PermissionKind;
-  /** choice 类型的可选项（显示为按钮列表） */
-  options?: string[];
-}
-
-/** 结构化提问（opencode question.v2.asked 等）中的单条问题。 */
-export interface QuestionInfo {
-  question: string;
-  header?: string;
-  options: string[];
-  multiple?: boolean;
-  custom?: boolean;
-}
-
-export interface QuestionRequest {
-  id: string;
-  sessionID: string;
-  prompt?: string;
-  questions: QuestionInfo[];
-  createdAt: number;
-}
-
-export interface CommandInfo {
-  name: string;
-  description?: string;
-}
-
-/** 账号体系（Phase 1）：电脑被手机账号认领后 relay 下发。 */
-export interface AgentClaimedMessage {
-  email?: string;
-}
-
-/** 账号体系（Phase 1）：电脑被解绑后 relay 下发，适配器应重置并重新生成 agentID。 */
-export interface AgentRevokedMessage {}
-
-/** agent 断开后中继推送给已连接手机（在线信号为 agent.info 广播）。 */
-export interface AgentOfflineMessage {
-  agentID?: string;
-}
+/**
+ * tunnelbox 统一协议类型（各智能体适配器共享）。
+ * 与 relay/internal/proto、web/src/protocol 通过 JSON 互通（镜像维护）。
+ */
+
+export interface Envelope<T = unknown> {
+  id?: string;
+  type: string;
+  payload: T;
+  ts: number;
+  /** 中继注入/回填：手机端会话 id，用于回路由 */
+  clientID?: string;
+}
+
+export function envelope<T>(type: string, payload: T, id?: string): Envelope<T> {
+  return { id, type, payload, ts: Date.now() };
+}
+
+export interface AgentInfo {
+  name: string;
+  version: string;
+  platform?: string;
+  directory?: string;
+  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor */
+  type?: string;
+  /** IANA 时区名（如 Asia/Shanghai），仅用于"电脑本地时间"展示 */
+  timezone?: string;
+  /** 能力位 */
+  capabilities?: {
+    streaming?: boolean;
+    thinking?: boolean;
+    permission?: boolean;
+    commands?: boolean;
+    abort?: boolean;
+  };
+}
+
+export type SessionStatus = "queued" | "running" | "idle" | "error";
+
+export interface SessionInfo {
+  id: string;
+  title: string;
+  created: number;
+  updated: number;
+  status: SessionStatus;
+  /** 会话所在工作区目录（dsh 按 workspace 分目录持久化） */
+  workspace?: string;
+}
+
+export interface WorkspaceInfo {
+  /** 工作区目录绝对路径 */
+  path: string;
+  /** 展示名（取目录名） */
+  name: string;
+  /** 该工作区内的会话数 */
+  sessionCount: number;
+  /** 最近会话更新时间 */
+  updated: number;
+}
+
+export interface Part {
+  id: string;
+  type: "text" | "tool" | "thinking";
+  text?: string;
+  delta?: string;
+  tool?: string;
+  args?: string;
+  complete?: boolean;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: "user" | "assistant" | "tool" | "system";
+  parts: Part[];
+  created: number;
+  /** 消息对应的模式/agent（opencode: build|plan），用于手机端气泡标注 */
+  mode?: string;
+}
+
+/** 权限请求的作答方式：approval=允许/拒绝/总是允许；choice=从选项中选择；input=输入文本。 */
+export type PermissionKind = "approval" | "choice" | "input";
+
+/**
+ * 审批"允许"的作用域（Hermes 审批门 / claude `canUseTool` 等宿主可能提供多种允许粒度）：
+ * - once    仅本次允许（默认）
+ * - session 本会话内允许
+ * - always  总是允许（宿主永久 allowlist）
+ * 手机端按请求方提供的 allowed 作用域渲染按钮；仅当 status="allow" 时生效，缺省视为 once。
+ */
+export type PermissionScope = "once" | "session" | "always";
+
+export interface PermissionRequest {
+  id: string;
+  sessionID: string;
+  tool: string;
+  args: Record<string, unknown>;
+  prompt?: string;
+  createdAt: number;
+  /** 作答方式（缺省视为 approval） */
+  kind?: PermissionKind;
+  /** choice 类型的可选项（显示为按钮列表） */
+  options?: string[];
+}
+
+/** 手机端对权限请求的应答（permission.reply）。status=allow 时可携带 scope 表达允许作用域。 */
+export interface PermissionReply {
+  permissionID: string;
+  status: "allow" | "deny";
+  /** 允许作用域（status=allow 时生效；缺省 once）。宿主仅接受其提供的 allowed 作用域。 */
+  scope?: PermissionScope;
+  /** 兼容旧字段：是否总是允许（等价 scope="always"）。 */
+  always?: boolean;
+  /** choice/input 型作答的选中值/输入文本。 */
+  value?: string;
+}
+
+/** 结构化提问（opencode question.v2.asked 等）中的单条问题。 */
+export interface QuestionInfo {
+  question: string;
+  header?: string;
+  options: string[];
+  multiple?: boolean;
+  custom?: boolean;
+}
+
+export interface QuestionRequest {
+  id: string;
+  sessionID: string;
+  prompt?: string;
+  questions: QuestionInfo[];
+  createdAt: number;
+  /**
+   * 会话内容锚点（可选）：该提问对应会话里哪条 assistant 消息/哪个 tool-call 部件，
+   * 前端可据此把选择卡内联到消息下方渲染（如 dsh 的 ask_user_question / exit_plan_mode）。
+   */
+  messageID?: string;
+  partID?: string;
+}
+
+export interface CommandInfo {
+  name: string;
+  description?: string;
+}
+
+/**
+ * 会话消息分页拉取请求（session.messages）：
+ * - 缺省（无 before）：返回最近 limit 条（首屏）；
+ * - before：返回早于该消息 id 的更早 limit 条（滚动到顶"加载更早"）。
+ */
+export interface SessionMessagesQuery {
+  sessionID: string;
+  before?: string;
+  limit?: number;
+}
+
+/** 会话消息应答（messages）：hasMore 用于手机端分页续拉（游标由手机端取已加载最旧一条的 id）。 */
+export interface SessionMessagesReply {
+  sessionID: string;
+  messages: ChatMessage[];
+  /** 更早历史是否仍存在（缺省 false）。 */
+  hasMore?: boolean;
+}
+
+/** 账号体系（Phase 1）：电脑被手机账号认领后 relay 下发。 */
+export interface AgentClaimedMessage {
+  email?: string;
+}
+
+/** 账号体系（Phase 1）：电脑被解绑后 relay 下发，适配器应重置并重新生成 agentID。 */
+export interface AgentRevokedMessage {}
+
+/** agent 断开后中继推送给已连接手机（在线信号为 agent.info 广播）。 */
+export interface AgentOfflineMessage {
+  agentID?: string;
+}