@downcity/agent 1.1.25 → 1.1.32

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

@@ -0,0 +1,83 @@
+/**
+ * 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/ContactPromptAssets.ts

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -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 "@/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

@@ -0,0 +1,125 @@
+/**
+ * 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/InboxStore.ts

@@ -0,0 +1,178 @@
+/**
+ * contact inbox 存储。
+ *
+ * 关键点（中文）
+ * - 每条 share 都是独立目录，避免大内容堆进单个 JSON。
+ * - `inbox` 列表只读取 `meta.json`，保持轻量。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import type {
+  ContactInboxShareMeta,
+  ContactInboxSharePayload,
+  SaveContactInboxShareInput,
+} from "@/plugin/builtins/contact/types/ContactShare.js";
+import {
+  getContactInboxRootPath,
+  getContactInboxShareFilesPath,
+  getContactInboxShareMetaPath,
+  getContactInboxSharePath,
+  getContactInboxSharePayloadPath,
+  getContactReceivedSharePath,
+} from "./Paths.js";
+
+function assertSafeRelativePath(relativePath: string): string {
+  const value = String(relativePath || "").trim();
+  if (!value) throw new Error("relativePath is required");
+  if (path.isAbsolute(value)) throw new Error(`Absolute path is not allowed: ${value}`);
+  const normalized = path.normalize(value);
+  if (
+    normalized === "." ||
+    normalized.startsWith("..") ||
+    normalized.includes(`${path.sep}..${path.sep}`) ||
+    normalized.endsWith(`${path.sep}..`)
+  ) {
+    throw new Error(`Unsafe relative path: ${value}`);
+  }
+  return normalized;
+}
+
+function isMeta(input: unknown): input is ContactInboxShareMeta {
+  const item = input as Partial<ContactInboxShareMeta> | null;
+  return Boolean(
+    item &&
+      typeof item.id === "string" &&
+      typeof item.fromAgentName === "string" &&
+      (item.status === "pending" || item.status === "received"),
+  );
+}
+
+/**
+ * 保存 inbox share。
+ */
+export async function saveContactInboxShare(
+  projectRoot: string,
+  input: SaveContactInboxShareInput,
+): Promise<ContactInboxShareMeta> {
+  const inboxRoot = getContactInboxRootPath(projectRoot);
+  const sharePath = getContactInboxSharePath(projectRoot, input.meta.id);
+  const tempRoot = path.join(path.dirname(inboxRoot), ".inbox-tmp");
+  const tempPath = path.join(
+    tempRoot,
+    `${path.basename(sharePath)}.${process.pid}.${Date.now()}`,
+  );
+
+  await fs.ensureDir(inboxRoot);
+  await fs.remove(tempPath);
+  try {
+    await fs.ensureDir(tempPath);
+    await fs.writeJson(path.join(tempPath, "payload.json"), input.payload, {
+      spaces: 2,
+    });
+
+    const filesRoot = path.join(tempPath, "files");
+    for (const file of input.files) {
+      const relativePath = assertSafeRelativePath(file.relativePath);
+      const outputPath = path.join(filesRoot, relativePath);
+      const encoding = file.encoding === "base64" ? "base64" : "utf8";
+      const content =
+        encoding === "base64"
+          ? Buffer.from(file.content, "base64")
+          : Buffer.from(file.content, "utf-8");
+      await fs.ensureDir(path.dirname(outputPath));
+      await fs.writeFile(outputPath, content);
+    }
+
+    // meta 最后写入，正式目录只在整条 share 完整后出现，避免 inbox 暴露半成品。
+    await fs.writeJson(path.join(tempPath, "meta.json"), input.meta, {
+      spaces: 2,
+    });
+    await fs.move(tempPath, sharePath, {
+      overwrite: false,
+    });
+  } catch (error) {
+    await fs.remove(tempPath).catch(() => undefined);
+    throw error;
+  }
+
+  return input.meta;
+}
+
+/**
+ * 读取 inbox share meta。
+ */
+export async function readContactInboxShareMeta(
+  projectRoot: string,
+  shareId: string,
+): Promise<ContactInboxShareMeta | null> {
+  const filePath = getContactInboxShareMetaPath(projectRoot, shareId);
+  if (!(await fs.pathExists(filePath))) return null;
+  const raw = await fs.readJson(filePath).catch(() => null);
+  return isMeta(raw) ? raw : null;
+}
+
+/**
+ * 读取 inbox share payload。
+ */
+export async function readContactInboxSharePayload(
+  projectRoot: string,
+  shareId: string,
+): Promise<ContactInboxSharePayload | null> {
+  const filePath = getContactInboxSharePayloadPath(projectRoot, shareId);
+  if (!(await fs.pathExists(filePath))) return null;
+  const raw = await fs.readJson(filePath).catch(() => null);
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const payload = raw as ContactInboxSharePayload;
+  return payload.kind === "share" ? payload : null;
+}
+
+/**
+ * 列出 inbox share。
+ */
+export async function listContactInboxShares(
+  projectRoot: string,
+): Promise<ContactInboxShareMeta[]> {
+  const root = getContactInboxRootPath(projectRoot);
+  if (!(await fs.pathExists(root))) return [];
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  const shares: ContactInboxShareMeta[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const meta = await readContactInboxShareMeta(projectRoot, entry.name);
+    if (meta) shares.push(meta);
+  }
+  return shares.sort((a, b) => b.receivedAt - a.receivedAt);
+}
+
+/**
+ * 标记 share 已接收，并复制轻量状态到 received。
+ */
+export async function markContactInboxShareReceived(
+  projectRoot: string,
+  shareId: string,
+): Promise<ContactInboxShareMeta> {
+  const meta = await readContactInboxShareMeta(projectRoot, shareId);
+  if (!meta) throw new Error(`Share not found: ${shareId}`);
+  const next: ContactInboxShareMeta = {
+    ...meta,
+    status: "received",
+  };
+  const receivedPath = getContactReceivedSharePath(projectRoot, shareId);
+  await fs.ensureDir(receivedPath);
+  await fs.writeJson(path.join(receivedPath, "meta.json"), next, {
+    spaces: 2,
+  });
+  // received 区先完整写入，最后再更新 inbox meta，避免列表状态提前变成 received。
+  await fs.writeJson(getContactInboxShareMetaPath(projectRoot, shareId), next, {
+    spaces: 2,
+  });
+  return next;
+}
+
+/**
+ * 读取 share 文件根目录。
+ */
+export function getInboxShareFilesRoot(projectRoot: string, shareId: string): string {
+  return getContactInboxShareFilesPath(projectRoot, shareId);
+}