@downcity/agent 1.1.1 → 1.1.5

package/src/service/builtins/contact/ContactService.ts

@@ -0,0 +1,799 @@
+/**
+ * ContactService：agent 点对点关系与分享服务。
+ *
+ * 关键点（中文）
+ * - `link/approve` 建立可信 contact，支持 outbound/inbound/bidirectional 三种可达方向。
+ * - 每个 contact 固定一条长期 chat history。
+ * - `share` 分享文本、链接、文件和目录，并进入对方 inbox。
+ */
+
+import type { Command } from "commander";
+import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
+import type { ServiceActions } from "@/shared/types/Service.js";
+import { BaseService } from "@/service/builtins/BaseService.js";
+import type {
+  ContactApproveCommandPayload,
+  ContactChatCommandPayload,
+  ContactCheckCommandPayload,
+  ContactLinkCommandPayload,
+  ContactReceiveCommandPayload,
+  ContactShareCommandPayload,
+} from "@/service/builtins/contact/types/ContactCommand.js";
+import type {
+  ContactApproveLinkRequest,
+  ContactApproveLinkResponse,
+} from "@/service/builtins/contact/types/ContactLink.js";
+import type {
+  ContactConfirmRequest,
+  ContactConfirmResponse,
+} from "@/service/builtins/contact/types/ContactApproval.js";
+import type { ContactPingResponse } from "@/service/builtins/contact/types/ContactCheck.js";
+import type { ContactChatResponse } from "@/service/builtins/contact/types/ContactChat.js";
+import type { AgentContact } from "@/service/builtins/contact/types/Contact.js";
+import type { SaveContactInboxShareInput } from "@/service/builtins/contact/types/ContactShare.js";
+import {
+  appendContactMessage,
+  createStableContactId,
+  findContact,
+  findContactByInboundToken,
+  listContacts,
+  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 {
+  listContactInboxShares,
+  saveContactInboxShare,
+} from "./runtime/InboxStore.js";
+import {
+  createShareInput,
+  receiveShare,
+} from "./runtime/ShareBundle.js";
+import { receiveContactChatMessage } from "./runtime/ChatRuntime.js";
+import { buildContactServiceSystemText } 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";
+
+function readObject(value: JsonValue): JsonObject {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as JsonObject)
+    : {};
+}
+
+function readString(body: JsonObject, key: string): string {
+  const value = body[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readNumber(body: JsonObject, key: string): number | undefined {
+  const value = body[key];
+  if (typeof value !== "number") return undefined;
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function readBoolean(body: JsonObject, key: string): boolean | undefined {
+  const value = body[key];
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function getHeaderToken(params: { headers?: Headers; body?: JsonObject }): string {
+  const fromHeader = String(params.headers?.get("x-downcity-contact-token") || "").trim();
+  if (fromHeader) return fromHeader;
+  return params.body ? readString(params.body, "token") : "";
+}
+
+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.globalEnv,
+    ...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 = {
+    ...context.globalEnv,
+    ...context.env,
+    ...process.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 service 类实现。
+ */
+export class ContactService extends BaseService {
+  /**
+   * service 名称。
+   */
+  readonly name = "contact";
+
+  /**
+   * 当前 service action 定义表。
+   */
+  readonly actions: ServiceActions;
+
+  constructor(agent: AgentRuntime | null) {
+    super(agent);
+    this.actions = {
+      link: {
+        command: {
+          description: "生成一次性 contact link code，交给另一个 agent approve",
+          configure(command: Command) {
+            command.option("--ttl-seconds <seconds>", "link 过期秒数，默认 600", Number);
+          },
+          mapInput({ opts }) {
+            const payload: JsonObject = {};
+            if (typeof opts.ttlSeconds === "number") payload.ttlSeconds = opts.ttlSeconds;
+            return payload;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.link(
+            params.context,
+            params.payload as ContactLinkCommandPayload,
+          )) as unknown as JsonValue,
+        }),
+      },
+      approve: {
+        command: {
+          description: "使用 contact link code 建立点对点联系",
+          configure(command: Command) {
+            command
+              .argument("<code>")
+              .option("--name <alias>", "本地 contact 别名");
+          },
+          mapInput({ args, opts }) {
+            const code = String(args[0] || "").trim();
+            if (!code) throw new Error("Missing link code");
+            const payload: JsonObject = { code };
+            if (typeof opts.name === "string") payload.name = opts.name;
+            return payload;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.approve(
+            params.context,
+            params.payload as unknown as ContactApproveCommandPayload,
+          )) as unknown as JsonValue,
+        }),
+      },
+      list: {
+        command: {
+          description: "列出已建立的 contact",
+          mapInput() {
+            return {};
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: {
+            contacts: await listContacts(params.context.rootPath),
+          } as unknown as JsonValue,
+        }),
+      },
+      check: {
+        command: {
+          description: "检查 contact 或 endpoint 当前是否在线可用",
+          configure(command: Command) {
+            command
+              .argument("[target]")
+              .option("--to <endpoint>", "直接检查未保存的 endpoint");
+          },
+          mapInput({ args, opts }) {
+            const payload: JsonObject = {};
+            const target = String(args[0] || "").trim();
+            if (target) payload.target = target;
+            if (typeof opts.to === "string") payload.endpoint = opts.to;
+            return payload;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.check(
+            params.context,
+            params.payload as ContactCheckCommandPayload,
+          )) as unknown as JsonValue,
+        }),
+      },
+      chat: {
+        command: {
+          description: "和某个 contact 的长期对话线聊天",
+          configure(command: Command) {
+            command.requiredOption("--to <contact>", "目标 contact").argument("[message...]");
+          },
+          mapInput({ args, opts }) {
+            const payload: JsonObject = {
+              to: String(opts.to || "").trim(),
+            };
+            const message = args.join(" ").trim();
+            if (message) payload.message = message;
+            return payload;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.chat(
+            params.context,
+            params.payload as unknown as ContactChatCommandPayload,
+          )) as unknown as JsonValue,
+        }),
+      },
+      share: {
+        command: {
+          description: "向 contact 分享文本、链接、文件或目录",
+          configure(command: Command) {
+            command
+              .requiredOption("--to <contact>", "目标 contact")
+              .option("--text <text>", "分享文本")
+              .option("--link <url...>", "分享链接")
+              .argument("[paths...]");
+          },
+          mapInput({ args, opts }) {
+            const links = Array.isArray(opts.link)
+              ? opts.link.map((item) => String(item || "").trim()).filter(Boolean)
+              : typeof opts.link === "string"
+                ? [opts.link]
+                : [];
+            return {
+              to: String(opts.to || "").trim(),
+              ...(typeof opts.text === "string" ? { text: opts.text } : {}),
+              ...(links.length > 0 ? { links } : {}),
+              paths: args.map((item) => String(item || "").trim()).filter(Boolean),
+            };
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.share(
+            params.context,
+            params.payload as unknown as ContactShareCommandPayload,
+          )) as unknown as JsonValue,
+        }),
+      },
+      inbox: {
+        command: {
+          description: "查看 contact inbox",
+          mapInput() {
+            return {};
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: {
+            shares: await listContactInboxShares(params.context.rootPath),
+          } as unknown as JsonValue,
+        }),
+      },
+      receive: {
+        command: {
+          description: "接收 inbox 中的 share",
+          configure(command: Command) {
+            command.argument("<shareId>");
+          },
+          mapInput({ args, opts }) {
+            const shareId = String(args[0] || "").trim();
+            if (!shareId) throw new Error("Missing shareId");
+            return {
+              shareId,
+            };
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await receiveShare({
+            projectRoot: params.context.rootPath,
+            shareId: (params.payload as unknown as ContactReceiveCommandPayload).shareId,
+          })) as unknown as JsonValue,
+        }),
+      },
+      remoteping: {
+        api: {
+          method: "POST",
+          path: "/api/contact/ping",
+          async mapInput(ctx) {
+            const body = (await ctx.req.json().catch(() => ({}))) as JsonValue;
+            return {
+              body,
+              token: getHeaderToken({
+                headers: ctx.req.raw.headers,
+                body: readObject(body),
+              }),
+            } as unknown as JsonValue;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.remotePing(
+            params.context,
+            params.payload as unknown as { token?: string },
+          )) as unknown as JsonValue,
+        }),
+      },
+      remoteapprove: {
+        api: {
+          method: "POST",
+          path: "/api/contact/approve",
+          async mapInput(ctx) {
+            return (await ctx.req.json()) as JsonValue;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.remoteApprove(
+            params.context,
+            readObject(params.payload) as unknown as ContactApproveLinkRequest,
+          )) as unknown as JsonValue,
+        }),
+      },
+      remoteconfirm: {
+        api: {
+          method: "POST",
+          path: "/api/contact/confirm",
+          async mapInput(ctx) {
+            return (await ctx.req.json()) as JsonValue;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.remoteConfirm(
+            params.context,
+            readObject(params.payload) as unknown as ContactConfirmRequest,
+          )) as unknown as JsonValue,
+        }),
+      },
+      remotechat: {
+        api: {
+          method: "POST",
+          path: "/api/contact/chat",
+          async mapInput(ctx) {
+            const body = (await ctx.req.json()) as JsonValue;
+            return {
+              body,
+              token: getHeaderToken({
+                headers: ctx.req.raw.headers,
+                body: readObject(body),
+              }),
+            } as unknown as JsonValue;
+          },
+        },
+        execute: async (params) => {
+          const payload = readObject(params.payload);
+          const body = readObject(payload.body);
+          return {
+            success: true,
+            data: (await receiveContactChatMessage({
+              context: params.context,
+              token: readString(payload, "token"),
+              message: readString(body, "message"),
+            })) as unknown as JsonValue,
+          };
+        },
+      },
+      remoteshare: {
+        api: {
+          method: "POST",
+          path: "/api/contact/share",
+          async mapInput(ctx) {
+            const body = (await ctx.req.json()) as JsonValue;
+            return {
+              body,
+              token: getHeaderToken({
+                headers: ctx.req.raw.headers,
+                body: readObject(body),
+              }),
+            } as unknown as JsonValue;
+          },
+        },
+        execute: async (params) => ({
+          success: true,
+          data: (await this.remoteShare(params.context, params.payload)) as unknown as JsonValue,
+        }),
+      },
+    };
+
+    this.lifecycle = {
+      start: () => undefined,
+      stop: () => undefined,
+    };
+  }
+
+  /**
+   * contact system 文本。
+   */
+  system(): string {
+    return buildContactServiceSystemText();
+  }
+
+  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),
+        service: "contact",
+      };
+    }
+    const contact = await findContactByInboundToken(context.rootPath, token);
+    return {
+      success: true,
+      agentName: getAgentName(context),
+      service: "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 = readObject(rawPayload);
+    const token = readString(payload, "token");
+    const body = readObject(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,
+    };
+  }
+}