@downcity/agent 1.1.35 → 1.1.43

package/src/plugin/builtins/contact/types/Contact.ts

@@ -1,82 +0,0 @@
-/**
- * contact 核心类型。
- *
- * 关键点（中文）
- * - 一个 contact 表示一个已确认的点对点 agent 关系。
- * - 每个 contact 固定拥有一条长期 chat history，不额外暴露 session 管理概念。
- */
-
-/**
- * contact 当前关系状态。
- */
-export type ContactStatus = "trusted" | "blocked";
-
-/**
- * contact 当前可达方向。
- */
-export type ContactReachability = "inbound" | "outbound" | "bidirectional";
-
-/**
- * agent contact 记录。
- */
-export interface AgentContact {
-  /**
-   * contact 稳定标识。
-   */
-  id: string;
-  /**
-   * 对方 agent 的展示名称。
-   */
-  name: string;
-  /**
-   * 对方 agent 的 HTTP endpoint；仅 inbound contact 可以为空。
-   */
-  endpoint: string | null;
-  /**
-   * 当前 agent 与对方 agent 的可达方向。
-   */
-  reachability: ContactReachability;
-  /**
-   * 当前关系状态。
-   */
-  status: ContactStatus;
-  /**
-   * 本 agent 调用对方时携带的 token；仅 inbound contact 可以为空。
-   */
-  outboundToken: string | null;
-  /**
-   * 对方调用本 agent 时必须携带的 token hash；仅 outbound contact 可以为空。
-   */
-  inboundTokenHash: string | null;
-  /**
-   * contact 创建时间戳。
-   */
-  createdAt: number;
-  /**
-   * 最近一次成功通信时间戳。
-   */
-  lastSeenAt?: number;
-}
-
-/**
- * contact chat 消息角色。
- */
-export type ContactChatMessageRole = "local" | "remote";
-
-/**
- * contact 长期对话历史中的单条消息。
- */
-export interface ContactChatMessage {
-  /**
-   * 消息角色。
-   */
-  role: ContactChatMessageRole;
-  /**
-   * 消息正文。
-   */
-  text: string;
-  /**
-   * 消息创建时间戳。
-   */
-  createdAt: number;
-}

package/src/plugin/builtins/contact/types/ContactApproval.ts

@@ -1,150 +0,0 @@
-/**
- * contact approve 协议运行时类型。
- *
- * 关键点（中文）
- * - 这里只描述 link approve 状态机需要的输入，不包含具体存储实现。
- * - link approve 是点对点能力码消费流程，token 由协议自动交换。
- */
-
-import type { ContactApproveLinkRequest } from "./ContactLink.js";
-import type { ContactEndpointReachability } from "./ContactEndpoint.js";
-import type { ContactApproveCallbackReason } from "./ContactLink.js";
-
-/**
- * approve 方对“是否提供回连候选”的本地推导结果。
- */
-export interface ContactApproveCallbackDecision {
-  /**
-   * approve 方是否应该把自己的 endpoint/token 作为回连候选发给发起方做 confirm。
-   */
-  callbackOffered: boolean;
-  /**
-   * 本次推导的原因。
-   */
-  reason: ContactApproveCallbackReason;
-  /**
-   * approve 方自己的 endpoint；仅当推导过程解析出了 endpoint 时存在。
-   */
-  endpoint?: string;
-  /**
-   * approve 方 endpoint 的粗粒度可达范围。
-   */
-  requesterReachability: ContactEndpointReachability;
-  /**
-   * link code 中目标 endpoint 的粗粒度可达范围。
-   */
-  targetReachability: ContactEndpointReachability;
-}
-
-/**
- * 处理远端 contact link approve 请求的输入。
- */
-export interface ApproveContactLinkRequestInput {
-  /**
-   * 当前 agent 项目根目录，用于读取 link 记录并保存 contact。
-   */
-  projectRoot: string;
-  /**
-   * 当前 agent 名称，也就是 link 所属方名称。
-   */
-  ownerAgentName: string;
-  /**
-   * 当前 agent 对外 endpoint；当 link 记录不存在时仍会返回该值辅助诊断。
-   */
-  ownerEndpoint: string;
-  /**
-   * approve 方发来的 link id、secret、agent 名称和可选回连信息。
-   */
-  request: ContactApproveLinkRequest;
-  /**
-   * 当前时间戳；测试可注入，生产环境默认使用 Date.now()。
-   */
-  nowMs?: number;
-}
-
-/**
- * 远端 contact confirm 请求。
- */
-export interface ContactConfirmRequest {
-  /**
-   * 被 confirm 的 link id。
-   */
-  linkId: string;
-  /**
-   * link code 中的一次性明文 secret，用于确认请求来自同一个 approve 方。
-   */
-  secret: string;
-  /**
-   * approve 方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * approve 方提供给发起方主动检查的 endpoint。
-   */
-  endpoint: string;
-  /**
-   * 发起方主动调用 approve 方时携带的 token。
-   */
-  tokenForRequester: string;
-}
-
-/**
- * 远端 contact confirm 响应。
- */
-export interface ContactConfirmResponse {
-  /**
-   * confirm 请求是否执行成功。
-   */
-  success: boolean;
-  /**
-   * 发起方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 发起方是否已确认可以主动回连 approve 方。
-   */
-  confirmed: boolean;
-  /**
-   * confirm 后发起方保存的 contact 方向。
-   */
-  reachability: "inbound" | "bidirectional";
-  /**
-   * confirm 失败原因。
-   */
-  error?: string;
-}
-
-/**
- * 处理远端 contact confirm 请求的输入。
- */
-export interface ConfirmContactLinkRequestInput {
-  /**
-   * 当前 agent 项目根目录，用于读取 link 记录并更新 contact。
-   */
-  projectRoot: string;
-  /**
-   * 当前 agent 名称，也就是 link 所属方名称。
-   */
-  ownerAgentName: string;
-  /**
-   * confirm 方发来的 link id、secret、agent 名称和回连 token。
-   */
-  request: ContactConfirmRequest;
-  /**
-   * 发起方主动 ping approve 方的验证函数；只有验证成功才能升级为 bidirectional。
-   */
-  verifyCallback: (params: {
-    /**
-     * approve 方提供的回连 endpoint。
-     */
-    endpoint: string;
-    /**
-     * 发起方调用 approve 方时携带的 token。
-     */
-    token: string;
-  }) => Promise<boolean>;
-  /**
-   * 当前时间戳；测试可注入，生产环境默认使用 Date.now()。
-   */
-  nowMs?: number;
-}

package/src/plugin/builtins/contact/types/ContactChat.ts

@@ -1,47 +0,0 @@
-/**
- * contact chat 类型。
- *
- * 关键点（中文）
- * - 一个 contact 固定一条长期 chat history。
- * - 用户不需要主动维护 session id。
- */
-
-/**
- * contact chat 远端消息请求。
- */
-export interface ContactRemoteChatRequest {
-  /**
-   * 发送方 contact id。
-   */
-  senderContactId: string;
-  /**
-   * 消息正文。
-   */
-  message: string;
-  /**
-   * 消息创建时间戳。
-   */
-  createdAt: number;
-}
-
-/**
- * contact chat 响应。
- */
-export interface ContactChatResponse {
-  /**
-   * chat 是否成功。
-   */
-  success: boolean;
-  /**
-   * 对方回复文本。
-   */
-  reply: string;
-  /**
-   * 本地 contact id。
-   */
-  contactId: string;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}

package/src/plugin/builtins/contact/types/ContactCheck.ts

@@ -1,67 +0,0 @@
-/**
- * contact check 类型。
- *
- * 关键点（中文）
- * - check 只检测对方 agent 当前是否在线可用。
- * - check 不创建关系，也不写入 inbox。
- */
-
-/**
- * contact ping 响应。
- */
-export interface ContactPingResponse {
-  /**
-   * ping 是否成功。
-   */
-  success: boolean;
-  /**
-   * 对方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 对方 contact plugin 是否可用。
-   */
-  plugin: "contact";
-  /**
-   * token 校验是否通过。
-   */
-  authenticated?: boolean;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}
-
-/**
- * contact check 结果。
- */
-export interface ContactCheckResult {
-  /**
-   * 检测目标名称或 endpoint。
-   */
-  target: string;
-  /**
-   * 目标 endpoint。
-   */
-  endpoint: string;
-  /**
-   * 目标是否可访问。
-   */
-  reachable: boolean;
-  /**
-   * contact token 是否有效。
-   */
-  authenticated?: boolean;
-  /**
-   * 往返耗时。
-   */
-  latencyMs: number;
-  /**
-   * 对方 agent 名称。
-   */
-  agentName?: string;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}

package/src/plugin/builtins/contact/types/ContactCommand.ts

@@ -1,98 +0,0 @@
-/**
- * contact plugin command 类型。
- *
- * 关键点（中文）
- * - 这里只描述 action payload/response，不承载运行时存储逻辑。
- */
-
-/**
- * contact link command 输入。
- */
-export interface ContactLinkCommandPayload {
-  /**
-   * 内部解析出的本 agent 对外可访问 endpoint；CLI 不暴露该字段。
-   */
-  endpoint?: string;
-  /**
-   * link 过期秒数。
-   */
-  ttlSeconds?: number;
-}
-
-/**
- * contact approve command 输入。
- */
-export interface ContactApproveCommandPayload {
-  /**
-   * 人工转交的 link code。
-   */
-  code: string;
-  /**
-   * 本地保存 contact 时使用的别名。
-   */
-  name?: string;
-  /**
-   * 内部解析出的本 agent 对外可访问 endpoint；CLI 不暴露该字段，省略时 approve 方只建立主动访问对方的单向 contact。
-   */
-  endpoint?: string;
-}
-
-/**
- * contact check command 输入。
- */
-export interface ContactCheckCommandPayload {
-  /**
-   * 已保存 contact 名称。
-   */
-  target?: string;
-  /**
-   * 未保存 agent endpoint。
-   */
-  endpoint?: string;
-}
-
-/**
- * contact chat command 输入。
- */
-export interface ContactChatCommandPayload {
-  /**
-   * 已保存 contact 名称。
-   */
-  to: string;
-  /**
-   * 本轮消息正文。
-   */
-  message?: string;
-}
-
-/**
- * contact share command 输入。
- */
-export interface ContactShareCommandPayload {
-  /**
-   * 已保存 contact 名称。
-   */
-  to: string;
-  /**
-   * 分享的文本内容。
-   */
-  text?: string;
-  /**
-   * 分享的链接列表。
-   */
-  links?: string[];
-  /**
-   * 分享的文件或目录路径列表。
-   */
-  paths?: string[];
-}
-
-/**
- * contact receive command 输入。
- */
-export interface ContactReceiveCommandPayload {
-  /**
-   * inbox share id。
-   */
-  shareId: string;
-}

package/src/plugin/builtins/contact/types/ContactEndpoint.ts

@@ -1,16 +0,0 @@
-/**
- * contact endpoint 提示类型。
- *
- * 关键点（中文）
- * - endpoint 可达性只用于给 agent / 用户解释当前联系码适合谁使用。
- * - 它不参与鉴权，鉴权仍由 link secret 与 contact token 完成。
- */
-
-/**
- * contact endpoint 的粗粒度可达范围。
- */
-export type ContactEndpointReachability =
-  | "loopback"
-  | "private"
-  | "public"
-  | "unknown";

package/src/plugin/builtins/contact/types/ContactLink.ts

@@ -1,169 +0,0 @@
-/**
- * contact link 类型。
- *
- * 关键点（中文）
- * - link code 是人工转交的一次性点对点建联凭证。
- * - approve 成功后 link 立即失效。
- */
-
-/**
- * link code 内部载荷。
- */
-export interface ContactLinkCodePayload {
-  /**
-   * link code 协议版本。
-   */
-  version: 1;
-  /**
-   * link 稳定标识。
-   */
-  linkId: string;
-  /**
-   * 发起方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 发起方 HTTP endpoint。
-   */
-  endpoint: string;
-  /**
-   * 一次性明文 secret。
-   */
-  secret: string;
-  /**
-   * link 创建时间戳。
-   */
-  createdAt: number;
-  /**
-   * link 过期时间戳。
-   */
-  expiresAt: number;
-}
-
-/**
- * 本地保存的 link 记录。
- */
-export interface ContactLinkRecord {
-  /**
-   * link 稳定标识。
-   */
-  id: string;
-  /**
-   * 发起方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 发起方 HTTP endpoint。
-   */
-  endpoint: string;
-  /**
-   * 一次性 secret hash。
-   */
-  secretHash: string;
-  /**
-   * link 创建时间戳。
-   */
-  createdAt: number;
-  /**
-   * link 过期时间戳。
-   */
-  expiresAt: number;
-  /**
-   * link 被使用的时间戳。
-   */
-  usedAt?: number | null;
-  /**
-   * 已使用该 link 的 approve 方 agent 名称；用于同一 agent 在网络中断或本地保存失败后做幂等重试。
-   */
-  approvedAgentName?: string | null;
-  /**
-   * approve 方在建联时提供的 HTTP endpoint；没有公开 endpoint 时为空。
-   */
-  approvedEndpoint?: string | null;
-  /**
-   * 发起方发给 approve 方的明文 contact token；只保存在本地 link 记录中，用于同一 link 在有效期内重试恢复。
-   */
-  tokenForOwner?: string | null;
-  /**
-   * approve 方发给发起方的明文 contact token；仅作为 confirm 阶段的本地恢复元数据。
-   */
-  tokenForRequester?: string | null;
-  /**
-   * approve 方推导回连候选的原因；用于 confirm 失败后的诊断。
-   */
-  callbackReason?: ContactApproveCallbackReason | null;
-  /**
-   * 发起方成功 confirm 并升级为 bidirectional 的时间戳。
-   */
-  confirmedAt?: number | null;
-}
-
-/**
- * approve 方声明自己可被回连的推导原因。
- */
-export type ContactApproveCallbackReason =
-  | "missing-requester-endpoint"
-  | "requester-public"
-  | "same-loopback-host"
-  | "same-private-network"
-  | "requester-not-routable-from-target";
-
-/**
- * 远端 approve link 请求。
- */
-export interface ContactApproveLinkRequest {
-  /**
-   * link 稳定标识。
-   */
-  linkId: string;
-  /**
-   * 一次性明文 secret。
-   */
-  secret: string;
-  /**
-   * approve 方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * approve 方 HTTP endpoint；缺省时只建立发起方可接收请求的单向 contact。
-   */
-  endpoint?: string;
-  /**
-   * 发起方后续调用 approve 方时使用的 token；只有 approve 方提供 endpoint 时才需要。
-   */
-  tokenForRequester?: string;
-  /**
-   * approve 方是否提供了一个回连候选；这不是双向确认结果，发起方必须再执行 confirm 主动检查。
-   */
-  callbackOffered?: boolean;
-  /**
-   * approve 方推导 `callbackOffered` 的原因，方便接收方和用户诊断网络关系。
-   */
-  callbackReason?: ContactApproveCallbackReason;
-}
-
-/**
- * 远端 approve link 响应。
- */
-export interface ContactApproveLinkResponse {
-  /**
-   * approve 是否成功。
-   */
-  success: boolean;
-  /**
-   * 发起方 agent 名称。
-   */
-  agentName: string;
-  /**
-   * 发起方 HTTP endpoint。
-   */
-  endpoint: string;
-  /**
-   * approve 方后续调用发起方时使用的 token。
-   */
-  tokenForOwner: string;
-  /**
-   * 失败原因。
-   */
-  error?: string;
-}