@downcity/agent 1.1.23 → 1.1.32

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

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

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

package/src/service/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 "@/service/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/service/builtins/contact/runtime/EndpointNotice.ts

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

@@ -1,178 +0,0 @@
-/**
- * contact inbox 存储。
- *
- * 关键点（中文）
- * - 每条 share 都是独立目录，避免大内容堆进单个 JSON。
- * - `inbox` 列表只读取 `meta.json`，保持轻量。
- */
-
-import fs from "fs-extra";
-import path from "node:path";
-import type {
-  ContactInboxShareMeta,
-  ContactInboxSharePayload,
-  SaveContactInboxShareInput,
-} from "@/service/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);
-}