@downcity/agent 1.1.32 → 1.1.43

package/src/plugin/builtins/contact/runtime/ChatRuntime.ts

@@ -1,83 +0,0 @@
-/**
- * contact chat 运行时。
- *
- * 关键点（中文）
- * - 一个 contact 固定一条长期对话历史。
- * - 远端收到 chat 后运行本地 agent session，并返回 assistant 文本。
- */
-
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ContactChatResponse } from "@/plugin/builtins/contact/types/ContactChat.js";
-import type { SessionMessageV1 } from "@/session/types/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 turn = await params.context.session.get(sessionId).prompt({
-    query: params.message,
-  });
-  const result = await turn.finished;
-  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/plugin/builtins/contact/runtime/ContactPayload.ts

@@ -1,26 +0,0 @@
-/**
- * contact payload 解析工具。
- *
- * 关键点（中文）
- * - contact 的 CLI 与远端 HTTP action 都会接收宽松 JSON 输入。
- * - 这里统一收口对象、字符串与 contact token 读取，避免 action 注册表重复解析细节。
- */
-
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-
-/**
- * 将任意 JSON 值安全读取为对象。
- */
-export function readContactObject(value: JsonValue): JsonObject {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as JsonObject)
-    : {};
-}
-
-/**
- * 从 JSON 对象中读取并裁剪字符串字段。
- */
-export function readContactString(body: JsonObject, key: string): string {
-  const value = body[key];
-  return typeof value === "string" ? value.trim() : "";
-}

package/src/plugin/builtins/contact/runtime/ContactPromptAssets.ts

@@ -1,14 +0,0 @@
-/**
- * ContactPromptAssets：contact service 静态提示词资产。
- *
- * 关键点（中文）
- * - contact prompt 文本真实来源是 `PROMPT.ts.txt`。
- * - 这里统一做 `trim()`，避免运行时行为漂移。
- */
-
-import contactPromptText from "@/plugin/builtins/contact/PROMPT.js";
-
-/**
- * contact service system prompt。
- */
-export const CONTACT_SERVICE_PROMPT = contactPromptText.trim();

package/src/plugin/builtins/contact/runtime/ContactStore.ts

@@ -1,299 +0,0 @@
-/**
- * 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 "@/plugin/builtins/contact/types/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/plugin/builtins/contact/runtime/EndpointNotice.ts

@@ -1,125 +0,0 @@
-/**
- * contact endpoint 用户提示。
- *
- * 关键点（中文）
- * - `contact link` / `contact approve` 会被 agent 自己调用，返回结果必须直接说明可达性限制。
- * - loopback/private endpoint 不是错误，但需要提醒用户不要拿给无法访问该地址的远端 agent。
- */
-
-import type { ContactEndpointReachability } from "@/plugin/builtins/contact/types/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;
-}

package/src/plugin/builtins/contact/runtime/EndpointResolver.ts

@@ -1,146 +0,0 @@
-/**
- * contact 自身 endpoint 解析。
- *
- * 关键点（中文）
- * - endpoint 是 contact 协议内部字段，不暴露成普通用户命令参数。
- * - 优先使用明确配置的公开地址，避免服务器 / 反向代理 / tunnel 场景被误判。
- * - 监听 `0.0.0.0` 时只做本机网卡最佳努力探测，不访问外部网络。
- */
-
-import os from "node:os";
-
-export interface ResolveContactSelfEndpointInput {
-  /**
-   * 运行时监听 host。
-   */
-  host?: string;
-  /**
-   * 运行时监听 port。
-   */
-  port?: number;
-  /**
-   * 环境变量读取来源，测试可注入。
-   */
-  env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
-  /**
-   * 网卡信息读取来源，测试可注入。
-   */
-  interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>;
-  /**
-   * 公网 IPv4 解析器，测试可注入。
-   */
-  resolvePublicIpv4?: () => Promise<string | null> | string | null;
-}
-
-function normalizeUrl(value: string, fallbackPort: number): string {
-  const raw = String(value || "").trim();
-  if (!raw) return formatUrl("127.0.0.1", fallbackPort);
-  if (/^https?:\/\//i.test(raw)) return raw.replace(/\/$/, "");
-  return formatUrl(raw, fallbackPort);
-}
-
-function formatUrl(host: string, port: number): string {
-  const normalizedHost = String(host || "").trim() || "127.0.0.1";
-  if (normalizedHost.startsWith("[")) return `http://${normalizedHost}:${String(port)}`;
-  if (normalizedHost.includes(":") && !normalizedHost.includes(".")) {
-    return `http://[${normalizedHost}]:${String(port)}`;
-  }
-  return `http://${normalizedHost}:${String(port)}`;
-}
-
-function isWildcardHost(host: string): boolean {
-  const value = String(host || "").trim().toLowerCase();
-  return !value || value === "0.0.0.0" || value === "::";
-}
-
-function isLoopbackHost(host: string): boolean {
-  const value = String(host || "").trim().toLowerCase();
-  return value === "127.0.0.1" || value === "::1" || value === "localhost";
-}
-
-function detectLanIpv4FromInterfaces(
-  interfaces: NodeJS.Dict<os.NetworkInterfaceInfo[]> = os.networkInterfaces(),
-): string | null {
-  for (const entries of Object.values(interfaces)) {
-    const items = (entries || []) as Array<{
-      address?: string;
-      family?: string | number;
-      internal?: boolean;
-    }>;
-    for (const rawItem of items) {
-      const family =
-        typeof rawItem.family === "string"
-          ? rawItem.family
-          : rawItem.family === 4
-            ? "IPv4"
-            : "unknown";
-      if (family !== "IPv4") continue;
-      if (rawItem.internal) continue;
-      const address = String(rawItem.address || "").trim();
-      if (address) return address;
-    }
-  }
-  return null;
-}
-
-function isIpv4Address(value: string): boolean {
-  const parts = String(value || "").trim().split(".");
-  if (parts.length !== 4) return false;
-  return parts.every((part) => {
-    if (!/^\d+$/.test(part)) return false;
-    const value = Number.parseInt(part, 10);
-    return value >= 0 && value <= 255;
-  });
-}
-
-async function resolvePublicIpv4FromNetwork(): Promise<string | null> {
-  if (typeof fetch !== "function") return null;
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 800);
-  try {
-    const response = await fetch("https://api.ipify.org?format=json", {
-      signal: controller.signal,
-    });
-    if (!response.ok) return null;
-    const data = (await response.json().catch(() => null)) as {
-      ip?: unknown;
-    } | null;
-    const ip = String(data?.ip || "").trim();
-    return isIpv4Address(ip) ? ip : null;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-/**
- * 解析 contact link code 中写入的自身 endpoint。
- */
-export async function resolveContactSelfEndpoint(
-  input: ResolveContactSelfEndpointInput,
-): Promise<string> {
-  const env = input.env || process.env;
-  const port = Number(input.port || env.DC_SERVER_PORT || 5314);
-
-  // 关键点（中文）：公开 URL 是最可靠来源，适配域名、反向代理和 tunnel。
-  const publicUrl = String(env.DOWNCITY_PUBLIC_URL || "").trim();
-  if (publicUrl) return normalizeUrl(publicUrl, port);
-
-  const publicHost = String(env.DOWNCITY_PUBLIC_HOST || "").trim();
-  if (publicHost) return formatUrl(publicHost, port);
-
-  const host = String(input.host || env.DC_SERVER_HOST || "127.0.0.1").trim();
-  if (!isWildcardHost(host) && !isLoopbackHost(host)) return formatUrl(host, port);
-
-  const lanIp = detectLanIpv4FromInterfaces(input.interfaces);
-  if (lanIp) return formatUrl(lanIp, port);
-
-  // 关键点（中文）：云服务器公网 IP 可能不在网卡上，最后再做短超时公网探测。
-  const publicIp = String(
-    (await (input.resolvePublicIpv4 || resolvePublicIpv4FromNetwork)()) || "",
-  ).trim();
-  if (isIpv4Address(publicIp)) return formatUrl(publicIp, port);
-
-  return formatUrl("127.0.0.1", port);
-}