@downcity/plugins 1.0.4

package/src/contact/ContactPlugin.ts

@@ -0,0 +1,503 @@
+/**
+ * ContactPlugin：agent 点对点关系与分享插件。
+ *
+ * 关键点（中文）
+ * - `link/approve` 建立可信 contact，支持 outbound/inbound/bidirectional 三种可达方向。
+ * - 每个 contact 固定一条长期 chat history。
+ * - `share` 分享文本、链接、文件和目录，并进入对方 inbox。
+ */
+
+import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import type {
+  ContactApproveCommandPayload,
+  ContactChatCommandPayload,
+  ContactCheckCommandPayload,
+  ContactLinkCommandPayload,
+  ContactShareCommandPayload,
+} from "@/contact/types/ContactCommand.js";
+import type {
+  ContactApproveLinkRequest,
+  ContactApproveLinkResponse,
+} from "@/contact/types/ContactLink.js";
+import type {
+  ContactConfirmRequest,
+  ContactConfirmResponse,
+} from "@/contact/types/ContactApproval.js";
+import type { ContactPingResponse } from "@/contact/types/ContactCheck.js";
+import type { ContactChatResponse } from "@/contact/types/ContactChat.js";
+import type { AgentContact } from "@/contact/types/Contact.js";
+import type { SaveContactInboxShareInput } from "@/contact/types/ContactShare.js";
+import {
+  appendContactMessage,
+  createStableContactId,
+  findContact,
+  findContactByInboundToken,
+  normalizeContactEndpoint,
+  readContactMessages,
+  saveContact,
+  touchContactSeen,
+} from "./runtime/ContactStore.js";
+import {
+  createContactLinkCode,
+  parseContactLinkCode,
+} from "./runtime/LinkCode.js";
+import {
+  saveContactLinkRecord,
+} from "./runtime/LinkStore.js";
+import {
+  createContactId,
+  createContactToken,
+  hashContactToken,
+} from "./runtime/Token.js";
+import {
+  callContactApprove,
+  callContactChat,
+  callContactConfirm,
+  callContactPing,
+  callContactShare,
+} from "./runtime/RemoteClient.js";
+import { saveContactInboxShare } from "./runtime/InboxStore.js";
+import { createShareInput } from "./runtime/ShareBundle.js";
+import { buildContactPluginSystemText } from "./runtime/SystemProvider.js";
+import { resolveContactSelfEndpoint } from "./runtime/EndpointResolver.js";
+import {
+  buildContactApproveNotes,
+  buildContactLinkNotes,
+  classifyContactEndpoint,
+} from "./runtime/EndpointNotice.js";
+import {
+  approveContactLinkRequest,
+  confirmContactLinkRequest,
+} from "./runtime/LinkApproval.js";
+import { buildContactApproveCallbackDecision } from "./runtime/ApproveCallback.js";
+import { createContactActions } from "./Action.js";
+import {
+  readContactObject,
+  readContactString,
+} from "./runtime/ContactPayload.js";
+
+async function resolveSelfEndpoint(
+  context: AgentContext,
+  endpointOverride?: string,
+): Promise<string> {
+  const explicit = String(endpointOverride || "").trim();
+  if (explicit) return normalizeContactEndpoint(explicit);
+  const start = context.config.start || {};
+  const env = {
+    ...process.env,
+    ...context.env,
+  };
+  const runtimePort = Number(process.env.DC_SERVER_PORT || env.DC_SERVER_PORT || "");
+  // 关键点（中文）：link code 必须写入当前 runtime 的真实监听端口，不能使用可能已经过期的配置端口。
+  const port = Number.isFinite(runtimePort) && runtimePort > 0 ? runtimePort : start.port;
+  const runtimeHost = String(process.env.DC_SERVER_HOST || env.DC_SERVER_HOST || "").trim();
+  return normalizeContactEndpoint(
+    await resolveContactSelfEndpoint({
+      host: runtimeHost || start.host,
+      port,
+      env,
+    }),
+  );
+}
+
+function hasRuntimePublicEndpointEnv(context: AgentContext): boolean {
+  const env = {
+    ...process.env,
+    ...context.env,
+  };
+  return Boolean(
+    String(env.DOWNCITY_PUBLIC_URL || "").trim() ||
+      String(env.DOWNCITY_PUBLIC_HOST || "").trim(),
+  );
+}
+
+function getAgentName(context: AgentContext): string {
+  return String(context.config.name || "downcity-agent").trim() || "downcity-agent";
+}
+
+function requireOutboundContact(contact: AgentContact): {
+  endpoint: string;
+  token: string;
+} {
+  if (!contact.endpoint || !contact.outboundToken) {
+    throw new Error(`Contact is inbound-only and cannot be called directly: ${contact.name}`);
+  }
+  return {
+    endpoint: contact.endpoint,
+    token: contact.outboundToken,
+  };
+}
+
+/**
+ * Contact plugin 类实现。
+ */
+export class ContactPlugin extends BasePlugin {
+  /**
+   * plugin 名称。
+   */
+  readonly name = "contact";
+
+  /**
+   * 当前 plugin action 定义表。
+   */
+  readonly actions: PluginActions;
+
+  constructor(agent: AgentRuntime | null) {
+    super(agent);
+    this.actions = createContactActions({
+      link: async (context, payload) =>
+        (await this.link(context, payload)) as unknown as JsonValue,
+      approve: async (context, payload) =>
+        (await this.approve(context, payload)) as unknown as JsonValue,
+      check: async (context, payload) =>
+        (await this.check(context, payload)) as unknown as JsonValue,
+      chat: async (context, payload) =>
+        (await this.chat(context, payload)) as unknown as JsonValue,
+      share: async (context, payload) =>
+        (await this.share(context, payload)) as unknown as JsonValue,
+      remotePing: (context, payload) => this.remotePing(context, payload),
+      remoteApprove: (context, request) => this.remoteApprove(context, request),
+      remoteConfirm: (context, request) => this.remoteConfirm(context, request),
+      remoteShare: async (context, payload) =>
+        (await this.remoteShare(context, payload)) as unknown as JsonValue,
+    });
+
+    this.lifecycle = {
+      start: () => undefined,
+      stop: () => undefined,
+    };
+  }
+
+  /**
+   * contact system 文本。
+   */
+  system(): string {
+    return buildContactPluginSystemText();
+  }
+
+  private async link(context: AgentContext, payload: ContactLinkCommandPayload) {
+    const now = Date.now();
+    const ttlSeconds = Math.max(60, Number(payload.ttlSeconds || 600));
+    const linkId = createContactId("link");
+    const secret = createContactToken();
+    const endpoint = await resolveSelfEndpoint(context, payload.endpoint);
+    const agentName = getAgentName(context);
+
+    await saveContactLinkRecord(context.rootPath, {
+      id: linkId,
+      agentName,
+      endpoint,
+      secretHash: hashContactToken(secret),
+      createdAt: now,
+      expiresAt: now + ttlSeconds * 1000,
+      usedAt: null,
+    });
+
+    const code = createContactLinkCode({
+      version: 1,
+      linkId,
+      agentName,
+      endpoint,
+      secret,
+      createdAt: now,
+      expiresAt: now + ttlSeconds * 1000,
+    });
+    return {
+      code,
+      linkId,
+      agentName,
+      endpoint,
+      endpointReachability: classifyContactEndpoint(endpoint),
+      notes: buildContactLinkNotes({ endpoint }),
+      expiresAt: now + ttlSeconds * 1000,
+    };
+  }
+
+  private async approve(context: AgentContext, payload: ContactApproveCommandPayload) {
+    const parsed = parseContactLinkCode(payload.code);
+    // 关键点（中文）：approve 端不使用本机时钟预判过期，避免两台机器时钟不一致时把本来可用的 link 提前拦截。
+    // 是否过期统一交给 link 持有方在远端按本地记录判断。
+
+    const targetReachability = classifyContactEndpoint(parsed.endpoint);
+    const shouldResolveRequesterEndpoint =
+      payload.endpoint ||
+      hasRuntimePublicEndpointEnv(context) ||
+      targetReachability === "loopback" ||
+      targetReachability === "private";
+    const requesterEndpointCandidate = shouldResolveRequesterEndpoint
+      ? await resolveSelfEndpoint(context, payload.endpoint)
+      : undefined;
+    const callbackDecision = buildContactApproveCallbackDecision({
+      targetEndpoint: parsed.endpoint,
+      requesterEndpoint: requesterEndpointCandidate,
+    });
+    const requesterEndpoint = callbackDecision.callbackOffered
+      ? callbackDecision.endpoint
+      : undefined;
+    const tokenForRequester = requesterEndpoint ? createContactToken() : undefined;
+    const approveNotes = buildContactApproveNotes({
+      targetEndpoint: parsed.endpoint,
+    });
+    let response: ContactApproveLinkResponse;
+    try {
+      response = await callContactApprove<ContactApproveLinkResponse>({
+        endpoint: parsed.endpoint,
+        body: {
+          linkId: parsed.linkId,
+          secret: parsed.secret,
+          agentName: getAgentName(context),
+          callbackOffered: callbackDecision.callbackOffered,
+          callbackReason: callbackDecision.reason,
+          ...(requesterEndpoint ? { endpoint: requesterEndpoint } : {}),
+          ...(tokenForRequester ? { tokenForRequester } : {}),
+        } as unknown as JsonValue,
+      });
+    } catch (error) {
+      throw new Error(`${String(error)}\n${approveNotes.join("\n")}`);
+    }
+    if (!response.success) throw new Error(response.error || "Contact approve failed");
+
+    const name = String(payload.name || response.agentName || parsed.agentName).trim();
+    const contact = await saveContact(context.rootPath, {
+      id: createStableContactId(name),
+      name,
+      endpoint: response.endpoint || parsed.endpoint,
+      reachability: "outbound",
+      status: "trusted",
+      outboundToken: response.tokenForOwner,
+      inboundTokenHash: tokenForRequester ? hashContactToken(tokenForRequester) : null,
+      createdAt: Date.now(),
+      lastSeenAt: Date.now(),
+    });
+    let confirmed = false;
+    let confirmError: string | undefined;
+    if (requesterEndpoint && tokenForRequester) {
+      try {
+        const confirm = await callContactConfirm<ContactConfirmResponse>({
+          endpoint: parsed.endpoint,
+          body: {
+            linkId: parsed.linkId,
+            secret: parsed.secret,
+            agentName: getAgentName(context),
+            endpoint: requesterEndpoint,
+            tokenForRequester,
+          } as unknown as JsonValue,
+        });
+        confirmed = Boolean(confirm.success && confirm.confirmed);
+        if (!confirmed && confirm.error) confirmError = confirm.error;
+      } catch (error) {
+        // 关键点（中文）：confirm 只决定是否升级双向；approve 已成功时仍保留 outbound contact。
+        confirmError = String(error);
+      }
+    }
+    const finalContact = confirmed
+      ? await saveContact(context.rootPath, {
+          ...contact,
+          reachability: "bidirectional",
+          inboundTokenHash: tokenForRequester ? hashContactToken(tokenForRequester) : null,
+          lastSeenAt: Date.now(),
+        })
+      : contact;
+    const finalNotes = buildContactApproveNotes({
+      targetEndpoint: parsed.endpoint,
+      requesterEndpoint,
+      callbackConfirmed: confirmed,
+    });
+    return {
+      contact: finalContact,
+      reachability: finalContact.reachability,
+      targetEndpointReachability: classifyContactEndpoint(parsed.endpoint),
+      callbackOffered: callbackDecision.callbackOffered,
+      callbackConfirmed: confirmed,
+      callbackReason: callbackDecision.reason,
+      ...(requesterEndpoint ? { requesterEndpoint } : {}),
+      ...(confirmError ? { confirmError } : {}),
+      notes: finalNotes,
+    };
+  }
+
+  private async check(context: AgentContext, payload: ContactCheckCommandPayload) {
+    const startedAt = Date.now();
+    const endpointInput = String(payload.endpoint || "").trim();
+    const contact = endpointInput
+      ? null
+      : await findContact(context.rootPath, String(payload.target || "").trim());
+    const endpoint = endpointInput || contact?.endpoint || "";
+    if (!endpoint) throw new Error("contact target or --to endpoint is required");
+    if (contact && !contact.outboundToken) {
+      throw new Error(`Contact is inbound-only and cannot be checked directly: ${contact.name}`);
+    }
+
+    try {
+      const pong = await callContactPing<ContactPingResponse>({
+        endpoint,
+        token: contact?.outboundToken || undefined,
+      });
+      if (contact && pong.success) {
+        await touchContactSeen(context.rootPath, contact.id);
+      }
+      return {
+        target: contact?.name || endpoint,
+        endpoint: normalizeContactEndpoint(endpoint),
+        reachable: Boolean(pong.success),
+        authenticated: pong.authenticated,
+        latencyMs: Date.now() - startedAt,
+        agentName: pong.agentName,
+        ...(pong.error ? { error: pong.error } : {}),
+      };
+    } catch (error) {
+      return {
+        target: contact?.name || endpoint,
+        endpoint: normalizeContactEndpoint(endpoint),
+        reachable: false,
+        latencyMs: Date.now() - startedAt,
+        error: String(error),
+      };
+    }
+  }
+
+  private async chat(context: AgentContext, payload: ContactChatCommandPayload) {
+    const contact = await findContact(context.rootPath, payload.to);
+    if (!contact) throw new Error(`Contact not found: ${payload.to}`);
+    const message = String(payload.message || "").trim();
+    if (!message) {
+      return {
+        contact,
+        messages: await readContactMessages(context.rootPath, contact.id),
+      };
+    }
+
+    await appendContactMessage(context.rootPath, contact.id, {
+      role: "local",
+      text: message,
+      createdAt: Date.now(),
+    });
+    const outbound = requireOutboundContact(contact);
+    const response = await callContactChat<ContactChatResponse>({
+      endpoint: outbound.endpoint,
+      token: outbound.token,
+      body: {
+        senderContactId: contact.id,
+        message,
+        createdAt: Date.now(),
+      } as unknown as JsonValue,
+    });
+    if (!response.success) throw new Error(response.error || "Contact chat failed");
+    await appendContactMessage(context.rootPath, contact.id, {
+      role: "remote",
+      text: response.reply,
+      createdAt: Date.now(),
+    });
+    return response;
+  }
+
+  private async share(context: AgentContext, payload: ContactShareCommandPayload) {
+    const contact = await findContact(context.rootPath, payload.to);
+    if (!contact) throw new Error(`Contact not found: ${payload.to}`);
+    const outbound = requireOutboundContact(contact);
+    const share = await createShareInput({
+      context,
+      fromContactId: contact.id,
+      fromAgentName: getAgentName(context),
+      text: payload.text,
+      links: payload.links,
+      paths: payload.paths,
+    });
+    const response = await callContactShare<{ success: boolean; shareId?: string; error?: string }>({
+      endpoint: outbound.endpoint,
+      token: outbound.token,
+      body: share as unknown as JsonValue,
+    });
+    if (!response.success) throw new Error(response.error || "Contact share failed");
+    return {
+      shareId: response.shareId || share.meta.id,
+      to: contact.name,
+      items: share.payload.items.map((item) => ({
+        type: item.type,
+        title: item.title,
+      })),
+    };
+  }
+
+  private async remotePing(
+    context: AgentContext,
+    payload: { token?: string },
+  ): Promise<ContactPingResponse> {
+    const token = String(payload.token || "").trim();
+    if (!token) {
+      return {
+        success: true,
+        agentName: getAgentName(context),
+        plugin: "contact",
+      };
+    }
+    const contact = await findContactByInboundToken(context.rootPath, token);
+    return {
+      success: true,
+      agentName: getAgentName(context),
+      plugin: "contact",
+      authenticated: Boolean(contact && contact.status === "trusted"),
+    };
+  }
+
+  private async remoteApprove(
+    context: AgentContext,
+    request: ContactApproveLinkRequest,
+  ): Promise<ContactApproveLinkResponse> {
+    return await approveContactLinkRequest({
+      projectRoot: context.rootPath,
+      ownerAgentName: getAgentName(context),
+      ownerEndpoint: await resolveSelfEndpoint(context),
+      request,
+    });
+  }
+
+  private async remoteConfirm(
+    context: AgentContext,
+    request: ContactConfirmRequest,
+  ): Promise<ContactConfirmResponse> {
+    return await confirmContactLinkRequest({
+      projectRoot: context.rootPath,
+      ownerAgentName: getAgentName(context),
+      request,
+      verifyCallback: async ({ endpoint, token }) => {
+        const pong = await callContactPing<ContactPingResponse>({
+          endpoint,
+          token,
+        });
+        return Boolean(pong.success && pong.authenticated);
+      },
+    });
+  }
+
+  private async remoteShare(context: AgentContext, rawPayload: JsonValue) {
+    const payload = readContactObject(rawPayload);
+    const token = readContactString(payload, "token");
+    const body = readContactObject(payload.body);
+    const contact = await findContactByInboundToken(context.rootPath, token);
+    if (!contact || contact.status !== "trusted") {
+      throw new Error("Invalid contact token");
+    }
+    const share = body as unknown as SaveContactInboxShareInput;
+    const meta = {
+      ...share.meta,
+      fromContactId: contact.id,
+      fromAgentName: contact.name,
+      receivedAt: Date.now(),
+      status: "pending" as const,
+    };
+    await saveContactInboxShare(context.rootPath, {
+      meta,
+      payload: share.payload,
+      files: Array.isArray(share.files) ? share.files : [],
+    });
+    return {
+      success: true,
+      shareId: meta.id,
+    };
+  }
+}

package/src/contact/Index.ts

@@ -0,0 +1,8 @@
+/**
+ * contact plugin 导出入口。
+ *
+ * 关键点（中文）
+ * - Index 只负责导出类实现，具体逻辑集中在 `ContactPlugin`。
+ */
+
+export { ContactPlugin } from "./ContactPlugin.js";

package/src/contact/PROMPT.ts

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

package/src/contact/PROMPT.ts.txt

@@ -0,0 +1,25 @@
+Contact plugin
+
+contact plugin 用来管理和其他 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/contact/runtime/ApproveCallback.ts

@@ -0,0 +1,97 @@
+/**
+ * contact approve 回连能力推导。
+ *
+ * 关键点（中文）
+ * - 是否双向不能由接收方看到 endpoint 后猜测，必须由 approve 方基于双方网络关系声明。
+ * - 公网 endpoint 可以声明可回连；同机 loopback 或同一私网网段也可以声明可回连。
+ * - local/private 到 public server 默认不能回连，避免 server 端误显示 bidirectional。
+ */
+
+import type { ContactApproveCallbackDecision } from "@/contact/types/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,
+  };
+}