@downcity/agent 1.1.1

package/src/services/contact/Index.ts

@@ -0,0 +1,8 @@
+/**
+ * contact service 导出入口。
+ *
+ * 关键点（中文）
+ * - 保持 service 目录对外入口稳定，具体逻辑集中在 `ContactService`。
+ */
+
+export { ContactService } from "./ContactService.js";

package/src/services/contact/PROMPT.txt

@@ -0,0 +1,25 @@
+Contact service
+
+contact service 用来管理和其他 agent 的联系方式。一个 contact 代表一个已建立联系的远端 agent，并固定拥有一条长期对话历史。contact 可以是单向的：只要本 agent 能访问对方，就可以 check、chat、share。
+
+可用命令：
+- `city contact link`：生成一次性联系码，交给另一个 agent。
+- `city contact approve <code>`：使用对方给的联系码建立 contact。
+- `city contact list`：查看已保存的 agent 联系方式。
+- `city contact check <contact>` / `city contact check --to <ip:port>`：检查对方是否在线可用。
+- `city contact chat --to <contact> "<message>"`：和某个 agent 对话。
+- `city contact share --to <contact> --text ... | --link ... | <path...>`：分享文本、链接、文件或目录。
+- `city contact inbox`：查看收到的分享。
+- `city contact receive <share_id>`：接收某条分享。
+
+边界：
+- chat 用于对话，share 用于资料交接。
+- `city contact link` 返回中的 notes 会说明联系码适合本机、局域网还是公网 agent 使用；本地 localhost 联系码不能交给 server agent approve。
+- public-looking endpoint 仍可能被防火墙/NAT 阻断；以返回的 notes 为准，不要承诺公网一定可达。
+- `city start` 会自动写入 `DOWNCITY_PUBLIC_HOST` 供 contact link 使用；这不是要求用户手动配置的 token 或 endpoint。
+- `city contact approve` 会先建立单向关系，再由对方主动 ping 回本 agent，ping 成功才升级为 bidirectional。
+- local/private agent 连接 public agent 时通常只能 outbound-only，不要说成双向。
+- contact token 由 link/approve 自动交换；不要要求用户手动配置 token 环境变量。
+- `Contact link not found` 表示请求打到的 agent runtime 没有这条 link 记录，优先检查 endpoint/端口/agent 是否一致；过期会明确返回 `Contact link expired`。
+- receive 只接收内容，不自动执行、不安装 skill、不修改项目业务文件。
+- 不自动 approve 或 receive，除非用户明确要求。

package/src/services/contact/runtime/ApproveCallback.ts

@@ -0,0 +1,97 @@
+/**
+ * contact approve 回连能力推导。
+ *
+ * 关键点（中文）
+ * - 是否双向不能由接收方看到 endpoint 后猜测，必须由 approve 方基于双方网络关系声明。
+ * - 公网 endpoint 可以声明可回连；同机 loopback 或同一私网网段也可以声明可回连。
+ * - local/private 到 public server 默认不能回连，避免 server 端误显示 bidirectional。
+ */
+
+import type { ContactApproveCallbackDecision } from "@/types/contact/ContactApproval.js";
+import { classifyContactEndpoint } from "./EndpointNotice.js";
+
+function readHostname(endpoint: string): string {
+  const value = String(endpoint || "").trim();
+  if (!value) return "";
+  try {
+    return new URL(value).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  } catch {
+    return "";
+  }
+}
+
+function privateIpv4NetworkKey(endpoint: string): string | null {
+  const hostname = readHostname(endpoint);
+  const parts = hostname.split(".").map((item) => Number.parseInt(item, 10));
+  if (parts.length !== 4 || parts.some((item) => Number.isNaN(item))) return null;
+  return parts.slice(0, 3).join(".");
+}
+
+/**
+ * 推导 approve 方是否可以被发起方回连。
+ */
+export function buildContactApproveCallbackDecision(params: {
+  /**
+   * link code 中的目标 endpoint。
+   */
+  targetEndpoint: string;
+  /**
+   * approve 方自己的 endpoint。
+   */
+  requesterEndpoint?: string;
+}): ContactApproveCallbackDecision {
+  const endpoint = String(params.requesterEndpoint || "").trim();
+  const targetReachability = classifyContactEndpoint(params.targetEndpoint);
+  const requesterReachability = endpoint
+    ? classifyContactEndpoint(endpoint)
+    : "unknown";
+  if (!endpoint) {
+    return {
+      callbackOffered: false,
+      reason: "missing-requester-endpoint",
+      requesterReachability,
+      targetReachability,
+    };
+  }
+  if (requesterReachability === "public") {
+    return {
+      callbackOffered: true,
+      reason: "requester-public",
+      endpoint,
+      requesterReachability,
+      targetReachability,
+    };
+  }
+  if (
+    requesterReachability === "loopback" &&
+    targetReachability === "loopback"
+  ) {
+    return {
+      callbackOffered: true,
+      reason: "same-loopback-host",
+      endpoint,
+      requesterReachability,
+      targetReachability,
+    };
+  }
+  if (
+    requesterReachability === "private" &&
+    targetReachability === "private" &&
+    privateIpv4NetworkKey(endpoint) === privateIpv4NetworkKey(params.targetEndpoint)
+  ) {
+    return {
+      callbackOffered: true,
+      reason: "same-private-network",
+      endpoint,
+      requesterReachability,
+      targetReachability,
+    };
+  }
+  return {
+    callbackOffered: false,
+    reason: "requester-not-routable-from-target",
+    endpoint,
+    requesterReachability,
+    targetReachability,
+  };
+}

package/src/services/contact/runtime/ChatRuntime.ts

@@ -0,0 +1,82 @@
+/**
+ * contact chat 运行时。
+ *
+ * 关键点（中文）
+ * - 一个 contact 固定一条长期对话历史。
+ * - 远端收到 chat 后运行本地 agent session，并返回 assistant 文本。
+ */
+
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { ContactChatResponse } from "@/types/contact/ContactChat.js";
+import type { SessionMessageV1 } from "@/types/session/SessionMessages.js";
+import {
+  appendContactMessage,
+  findContactByInboundToken,
+} from "./ContactStore.js";
+
+function extractMessageText(message: SessionMessageV1 | null | undefined): string {
+  const parts = Array.isArray((message as { parts?: unknown } | null)?.parts)
+    ? ((message as { parts: unknown[] }).parts)
+    : [];
+  return parts
+    .map((part) => {
+      if (!part || typeof part !== "object") return "";
+      const item = part as { type?: unknown; text?: unknown };
+      return item.type === "text" ? String(item.text || "") : "";
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+}
+
+/**
+ * 处理远端 contact chat 消息。
+ */
+export async function receiveContactChatMessage(params: {
+  /**
+   * 当前 agent context。
+   */
+  context: AgentContext;
+  /**
+   * 入站 contact token。
+   */
+  token: string;
+  /**
+   * 消息正文。
+   */
+  message: string;
+}): Promise<ContactChatResponse> {
+  const contact = await findContactByInboundToken(params.context.rootPath, params.token);
+  if (!contact || contact.status !== "trusted") {
+    return {
+      success: false,
+      reply: "",
+      contactId: "",
+      error: "Invalid contact token",
+    };
+  }
+
+  const now = Date.now();
+  await appendContactMessage(params.context.rootPath, contact.id, {
+    role: "remote",
+    text: params.message,
+    createdAt: now,
+  });
+
+  const sessionId = `contact_${contact.id}`;
+  const result = await params.context.session.get(sessionId).run({
+    query: params.message,
+  });
+  const reply = extractMessageText(result.assistantMessage);
+  await appendContactMessage(params.context.rootPath, contact.id, {
+    role: "local",
+    text: reply,
+    createdAt: Date.now(),
+  });
+
+  return {
+    success: true,
+    reply,
+    contactId: contact.id,
+  };
+}

package/src/services/contact/runtime/ContactStore.ts

@@ -0,0 +1,299 @@
+/**
+ * contact 存储。
+ *
+ * 关键点（中文）
+ * - 一个 contact 一个目录，目录内保存 `contact.json` 与 `messages.jsonl`。
+ * - 查找 contact 支持 id/name，方便 CLI 使用别名。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type {
+  AgentContact,
+  ContactReachability,
+  ContactChatMessage,
+} from "@/types/contact/Contact.js";
+import { hashContactToken, toContactSlug } from "./Token.js";
+import {
+  getContactDirectoryPath,
+  getContactJsonPath,
+  getContactMessagesPath,
+  getContactsRootPath,
+} from "./Paths.js";
+
+function normalizeEndpoint(endpoint: string): string {
+  const raw = String(endpoint || "").trim();
+  if (!raw) throw new Error("endpoint is required");
+  const withProtocol = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  const url = new URL(withProtocol);
+  url.pathname = "";
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+
+function isReachability(input: unknown): input is ContactReachability {
+  return input === "inbound" || input === "outbound" || input === "bidirectional";
+}
+
+function isContactStatus(input: unknown): input is AgentContact["status"] {
+  return input === "trusted" || input === "blocked";
+}
+
+function normalizeOptionalEndpoint(input: unknown): string | null | undefined {
+  if (input === undefined || input === null) return null;
+  if (typeof input !== "string") return undefined;
+  try {
+    return normalizeEndpoint(input);
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeOptionalToken(input: unknown): string | null | undefined {
+  if (input === undefined || input === null) return null;
+  if (typeof input !== "string") return undefined;
+  const value = input.trim();
+  return value || null;
+}
+
+function normalizeOptionalTimestamp(input: unknown): number | undefined {
+  return typeof input === "number" && Number.isFinite(input) ? input : undefined;
+}
+
+function inferStoredReachability(params: {
+  endpoint: string | null;
+  outboundToken: string | null;
+  inboundTokenHash: string | null;
+}): ContactReachability {
+  if (params.endpoint && params.outboundToken && params.inboundTokenHash) {
+    return "bidirectional";
+  }
+  if (params.endpoint && params.outboundToken) return "outbound";
+  return "inbound";
+}
+
+function isReachabilityStateValid(contact: AgentContact): boolean {
+  if (contact.reachability !== "inbound" && (!contact.endpoint || !contact.outboundToken)) {
+    return false;
+  }
+  if (contact.reachability !== "outbound" && !contact.inboundTokenHash) {
+    return false;
+  }
+  return true;
+}
+
+function normalizeStoredContact(input: unknown): AgentContact | null {
+  const item = input as Partial<AgentContact> | null;
+  if (!item || typeof item.id !== "string" || typeof item.name !== "string") {
+    return null;
+  }
+
+  const endpoint = normalizeOptionalEndpoint(item.endpoint);
+  const outboundToken = normalizeOptionalToken(item.outboundToken);
+  const inboundTokenHash = normalizeOptionalToken(item.inboundTokenHash);
+  if (endpoint === undefined || outboundToken === undefined || inboundTokenHash === undefined) {
+    return null;
+  }
+
+  const contact: AgentContact = {
+    id: item.id,
+    name: item.name.trim(),
+    endpoint,
+    reachability: isReachability(item.reachability)
+      ? item.reachability
+      : inferStoredReachability({
+          endpoint,
+          outboundToken,
+          inboundTokenHash,
+        }),
+    status: isContactStatus(item.status) ? item.status : "trusted",
+    outboundToken,
+    inboundTokenHash,
+    createdAt: normalizeOptionalTimestamp(item.createdAt) ?? 0,
+    ...(normalizeOptionalTimestamp(item.lastSeenAt) !== undefined
+      ? { lastSeenAt: normalizeOptionalTimestamp(item.lastSeenAt) }
+      : {}),
+  };
+
+  if (!contact.name || !isReachabilityStateValid(contact)) return null;
+  return contact;
+}
+
+function resolveReachability(contact: AgentContact): ContactReachability {
+  if (contact.reachability) return contact.reachability;
+  if (contact.endpoint && contact.outboundToken && contact.inboundTokenHash) {
+    return "bidirectional";
+  }
+  if (contact.endpoint && contact.outboundToken) return "outbound";
+  return "inbound";
+}
+
+/**
+ * 创建 contact id。
+ */
+export function createStableContactId(name: string): string {
+  return `contact_${toContactSlug(name)}`;
+}
+
+/**
+ * 归一化 endpoint。
+ */
+export function normalizeContactEndpoint(endpoint: string): string {
+  return normalizeEndpoint(endpoint);
+}
+
+/**
+ * 保存 contact。
+ */
+export async function saveContact(
+  projectRoot: string,
+  contact: AgentContact,
+): Promise<AgentContact> {
+  const normalized: AgentContact = {
+    ...contact,
+    id: contact.id || createStableContactId(contact.name),
+    name: String(contact.name || "").trim(),
+    endpoint: contact.endpoint ? normalizeEndpoint(contact.endpoint) : null,
+    reachability: resolveReachability(contact),
+    status: contact.status || "trusted",
+    outboundToken: contact.outboundToken || null,
+    inboundTokenHash: contact.inboundTokenHash || null,
+    createdAt: contact.createdAt || Date.now(),
+  };
+  if (!normalized.name) throw new Error("contact name is required");
+  if (normalized.reachability !== "inbound" && !normalized.endpoint) {
+    throw new Error("contact endpoint is required for outbound contacts");
+  }
+  if (normalized.reachability !== "inbound" && !normalized.outboundToken) {
+    throw new Error("contact approve response did not include the peer token; generate a fresh link and approve again");
+  }
+  if (normalized.reachability !== "outbound" && !normalized.inboundTokenHash) {
+    throw new Error("contact inbound token hash is required for inbound contacts");
+  }
+  await fs.ensureDir(getContactDirectoryPath(projectRoot, normalized.id));
+  await fs.writeJson(getContactJsonPath(projectRoot, normalized.id), normalized, {
+    spaces: 2,
+  });
+  await fs.ensureFile(getContactMessagesPath(projectRoot, normalized.id));
+  return normalized;
+}
+
+/**
+ * 读取 contact。
+ */
+export async function readContact(
+  projectRoot: string,
+  contactId: string,
+): Promise<AgentContact | null> {
+  const filePath = getContactJsonPath(projectRoot, contactId);
+  if (!(await fs.pathExists(filePath))) return null;
+  const raw = await fs.readJson(filePath).catch(() => null);
+  // 关键点（中文）：读取时归一化可恢复字段，避免一次局部写入让已收到的 contact 在列表中消失。
+  return normalizeStoredContact(raw);
+}
+
+/**
+ * 列出全部 contact。
+ */
+export async function listContacts(projectRoot: string): Promise<AgentContact[]> {
+  const root = getContactsRootPath(projectRoot);
+  if (!(await fs.pathExists(root))) return [];
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const contacts: AgentContact[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const contact = await readContact(projectRoot, entry.name);
+    if (contact) contacts.push(contact);
+  }
+  return contacts.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * 按 id/name 查找 contact。
+ */
+export async function findContact(
+  projectRoot: string,
+  query: string,
+): Promise<AgentContact | null> {
+  const value = String(query || "").trim();
+  if (!value) return null;
+  const contacts = await listContacts(projectRoot);
+  const lower = value.toLowerCase();
+  return (
+    contacts.find((item) => item.id.toLowerCase() === lower) ||
+    contacts.find((item) => item.name.toLowerCase() === lower) ||
+    contacts.find((item) => item.name.toLowerCase().includes(lower)) ||
+    null
+  );
+}
+
+/**
+ * 根据入站 token 查找 contact。
+ */
+export async function findContactByInboundToken(
+  projectRoot: string,
+  token: string,
+): Promise<AgentContact | null> {
+  const tokenHash = hashContactToken(token);
+  const contacts = await listContacts(projectRoot);
+  return contacts.find((item) => item.inboundTokenHash === tokenHash) || null;
+}
+
+/**
+ * 更新 contact 最近在线时间。
+ */
+export async function touchContactSeen(
+  projectRoot: string,
+  contactId: string,
+  seenAt: number = Date.now(),
+): Promise<AgentContact | null> {
+  const contact = await readContact(projectRoot, contactId);
+  if (!contact) return null;
+  return await saveContact(projectRoot, {
+    ...contact,
+    lastSeenAt: seenAt,
+  });
+}
+
+/**
+ * 追加 contact chat 消息。
+ */
+export async function appendContactMessage(
+  projectRoot: string,
+  contactId: string,
+  message: ContactChatMessage,
+): Promise<void> {
+  const filePath = getContactMessagesPath(projectRoot, contactId);
+  await fs.ensureDir(path.dirname(filePath));
+  await fs.appendFile(filePath, `${JSON.stringify(message)}\n`, "utf-8");
+}
+
+/**
+ * 读取 contact chat 历史。
+ */
+export async function readContactMessages(
+  projectRoot: string,
+  contactId: string,
+): Promise<ContactChatMessage[]> {
+  const filePath = getContactMessagesPath(projectRoot, contactId);
+  if (!(await fs.pathExists(filePath))) return [];
+  const text = await fs.readFile(filePath, "utf-8");
+  const out: ContactChatMessage[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed) as ContactChatMessage;
+      if (
+        (parsed.role === "local" || parsed.role === "remote") &&
+        typeof parsed.text === "string"
+      ) {
+        out.push(parsed);
+      }
+    } catch {
+      // 忽略损坏的历史行，避免单条坏数据阻断整个 contact。
+    }
+  }
+  return out;
+}

package/src/services/contact/runtime/EndpointNotice.ts

@@ -0,0 +1,125 @@
+/**
+ * contact endpoint 用户提示。
+ *
+ * 关键点（中文）
+ * - `contact link` / `contact approve` 会被 agent 自己调用，返回结果必须直接说明可达性限制。
+ * - loopback/private endpoint 不是错误，但需要提醒用户不要拿给无法访问该地址的远端 agent。
+ */
+
+import type { ContactEndpointReachability } from "@/types/contact/ContactEndpoint.js";
+
+function readHostname(endpoint: string): string {
+  const value = String(endpoint || "").trim();
+  if (!value) return "";
+  try {
+    return new URL(value).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  } catch {
+    return "";
+  }
+}
+
+function isPrivateIpv4(hostname: string): boolean {
+  const parts = hostname.split(".").map((item) => Number.parseInt(item, 10));
+  if (parts.length !== 4 || parts.some((item) => Number.isNaN(item))) return false;
+  if (parts[0] === 10) return true;
+  if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+  if (parts[0] === 192 && parts[1] === 168) return true;
+  if (parts[0] === 169 && parts[1] === 254) return true;
+  return false;
+}
+
+/**
+ * 判断 endpoint 的粗粒度可达范围。
+ */
+export function classifyContactEndpoint(
+  endpoint: string,
+): ContactEndpointReachability {
+  const hostname = readHostname(endpoint);
+  if (!hostname) return "unknown";
+  if (
+    hostname === "localhost" ||
+    hostname === "::1" ||
+    hostname.startsWith("127.")
+  ) {
+    return "loopback";
+  }
+  if (isPrivateIpv4(hostname)) return "private";
+  return "public";
+}
+
+/**
+ * 生成 `contact link` 返回提示。
+ */
+export function buildContactLinkNotes(params: {
+  /**
+   * link code 内写入的 endpoint。
+   */
+  endpoint: string;
+}): string[] {
+  const reachability = classifyContactEndpoint(params.endpoint);
+  if (reachability === "loopback") {
+    return [
+      "This link endpoint is local-only. Only an agent on the same machine can approve it; a server agent cannot approve a link generated by this local agent.",
+      "Start city from a reachable environment before generating a new link; city start automatically writes the public host used by contact links when it can detect one.",
+    ];
+  }
+  if (reachability === "private") {
+    return [
+      "This link endpoint is private-network only. Agents must be on the same LAN/VPN to approve it; a public server agent may not be able to reach it.",
+    ];
+  }
+  if (reachability === "public") {
+    return [
+      "This link can be approved by agents that can reach this endpoint before the code expires.",
+      "Downcity cannot verify firewall or NAT reachability from here; if approval cannot connect, restart city from a reachable server, domain, or tunnel.",
+    ];
+  }
+  return [
+    "Downcity could not classify this link endpoint. Make sure the receiving agent can reach it before approving.",
+  ];
+}
+
+/**
+ * 生成 `contact approve` 返回提示。
+ */
+export function buildContactApproveNotes(params: {
+  /**
+   * link code 中的目标 endpoint。
+   */
+  targetEndpoint: string;
+  /**
+   * approve 方随请求发送给对方的 endpoint。
+   */
+  requesterEndpoint?: string;
+  /**
+   * 对方是否已经主动 ping 回 approve 方并确认成功。
+   */
+  callbackConfirmed?: boolean;
+}): string[] {
+  const notes: string[] = [];
+  const targetReachability = classifyContactEndpoint(params.targetEndpoint);
+  if (targetReachability === "loopback") {
+    notes.push(
+      "The approved link points to a local-only endpoint. This only works when both agents run on the same machine.",
+    );
+  } else if (targetReachability === "private") {
+    notes.push(
+      "The approved link points to a private-network endpoint. This only works when this agent can reach that LAN/VPN address.",
+    );
+  }
+
+  if (params.requesterEndpoint && params.callbackConfirmed) {
+    notes.push(
+      "This contact is bidirectional: the peer confirmed it can ping this agent back, so both agents can initiate check, chat, and share.",
+    );
+  } else if (params.requesterEndpoint) {
+    notes.push(
+      "This contact is outbound-only for now: this agent sent a callback candidate, but the peer has not confirmed it can ping this agent back.",
+    );
+  } else {
+    notes.push(
+      "This contact is outbound-only from this side: this agent can call the peer, but the peer cannot call back unless this agent was started with a reachable address that city start can provide to contact.",
+    );
+  }
+  return notes;
+}