@downcity/agent 1.1.1

package/bin/services/contact/ContactService.js

@@ -0,0 +1,683 @@
+/**
+ * ContactService：agent 点对点关系与分享服务。
+ *
+ * 关键点（中文）
+ * - `link/approve` 建立可信 contact，支持 outbound/inbound/bidirectional 三种可达方向。
+ * - 每个 contact 固定一条长期 chat history。
+ * - `share` 分享文本、链接、文件和目录，并进入对方 inbox。
+ */
+import { BaseService } from "../BaseService.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) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function readString(body, key) {
+    const value = body[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function readNumber(body, key) {
+    const value = body[key];
+    if (typeof value !== "number")
+        return undefined;
+    return Number.isFinite(value) ? value : undefined;
+}
+function readBoolean(body, key) {
+    const value = body[key];
+    return typeof value === "boolean" ? value : undefined;
+}
+function getHeaderToken(params) {
+    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, endpointOverride) {
+    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) {
+    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) {
+    return String(context.config.name || "downcity-agent").trim() || "downcity-agent";
+}
+function requireOutboundContact(contact) {
+    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 名称。
+     */
+    name = "contact";
+    /**
+     * 当前 service action 定义表。
+     */
+    actions;
+    constructor(agent) {
+        super(agent);
+        this.actions = {
+            link: {
+                command: {
+                    description: "生成一次性 contact link code，交给另一个 agent approve",
+                    configure(command) {
+                        command.option("--ttl-seconds <seconds>", "link 过期秒数，默认 600", Number);
+                    },
+                    mapInput({ opts }) {
+                        const payload = {};
+                        if (typeof opts.ttlSeconds === "number")
+                            payload.ttlSeconds = opts.ttlSeconds;
+                        return payload;
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: (await this.link(params.context, params.payload)),
+                }),
+            },
+            approve: {
+                command: {
+                    description: "使用 contact link code 建立点对点联系",
+                    configure(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 = { 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)),
+                }),
+            },
+            list: {
+                command: {
+                    description: "列出已建立的 contact",
+                    mapInput() {
+                        return {};
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: {
+                        contacts: await listContacts(params.context.rootPath),
+                    },
+                }),
+            },
+            check: {
+                command: {
+                    description: "检查 contact 或 endpoint 当前是否在线可用",
+                    configure(command) {
+                        command
+                            .argument("[target]")
+                            .option("--to <endpoint>", "直接检查未保存的 endpoint");
+                    },
+                    mapInput({ args, opts }) {
+                        const payload = {};
+                        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)),
+                }),
+            },
+            chat: {
+                command: {
+                    description: "和某个 contact 的长期对话线聊天",
+                    configure(command) {
+                        command.requiredOption("--to <contact>", "目标 contact").argument("[message...]");
+                    },
+                    mapInput({ args, opts }) {
+                        const payload = {
+                            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)),
+                }),
+            },
+            share: {
+                command: {
+                    description: "向 contact 分享文本、链接、文件或目录",
+                    configure(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)),
+                }),
+            },
+            inbox: {
+                command: {
+                    description: "查看 contact inbox",
+                    mapInput() {
+                        return {};
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: {
+                        shares: await listContactInboxShares(params.context.rootPath),
+                    },
+                }),
+            },
+            receive: {
+                command: {
+                    description: "接收 inbox 中的 share",
+                    configure(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.shareId,
+                    })),
+                }),
+            },
+            remoteping: {
+                api: {
+                    method: "POST",
+                    path: "/api/contact/ping",
+                    async mapInput(ctx) {
+                        const body = (await ctx.req.json().catch(() => ({})));
+                        return {
+                            body,
+                            token: getHeaderToken({
+                                headers: ctx.req.raw.headers,
+                                body: readObject(body),
+                            }),
+                        };
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: (await this.remotePing(params.context, params.payload)),
+                }),
+            },
+            remoteapprove: {
+                api: {
+                    method: "POST",
+                    path: "/api/contact/approve",
+                    async mapInput(ctx) {
+                        return (await ctx.req.json());
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: (await this.remoteApprove(params.context, readObject(params.payload))),
+                }),
+            },
+            remoteconfirm: {
+                api: {
+                    method: "POST",
+                    path: "/api/contact/confirm",
+                    async mapInput(ctx) {
+                        return (await ctx.req.json());
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: (await this.remoteConfirm(params.context, readObject(params.payload))),
+                }),
+            },
+            remotechat: {
+                api: {
+                    method: "POST",
+                    path: "/api/contact/chat",
+                    async mapInput(ctx) {
+                        const body = (await ctx.req.json());
+                        return {
+                            body,
+                            token: getHeaderToken({
+                                headers: ctx.req.raw.headers,
+                                body: readObject(body),
+                            }),
+                        };
+                    },
+                },
+                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"),
+                        })),
+                    };
+                },
+            },
+            remoteshare: {
+                api: {
+                    method: "POST",
+                    path: "/api/contact/share",
+                    async mapInput(ctx) {
+                        const body = (await ctx.req.json());
+                        return {
+                            body,
+                            token: getHeaderToken({
+                                headers: ctx.req.raw.headers,
+                                body: readObject(body),
+                            }),
+                        };
+                    },
+                },
+                execute: async (params) => ({
+                    success: true,
+                    data: (await this.remoteShare(params.context, params.payload)),
+                }),
+            },
+        };
+        this.lifecycle = {
+            start: () => undefined,
+            stop: () => undefined,
+        };
+    }
+    /**
+     * contact system 文本。
+     */
+    system() {
+        return buildContactServiceSystemText();
+    }
+    async link(context, payload) {
+        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,
+        };
+    }
+    async approve(context, payload) {
+        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;
+        try {
+            response = await callContactApprove({
+                endpoint: parsed.endpoint,
+                body: {
+                    linkId: parsed.linkId,
+                    secret: parsed.secret,
+                    agentName: getAgentName(context),
+                    callbackOffered: callbackDecision.callbackOffered,
+                    callbackReason: callbackDecision.reason,
+                    ...(requesterEndpoint ? { endpoint: requesterEndpoint } : {}),
+                    ...(tokenForRequester ? { tokenForRequester } : {}),
+                },
+            });
+        }
+        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;
+        if (requesterEndpoint && tokenForRequester) {
+            try {
+                const confirm = await callContactConfirm({
+                    endpoint: parsed.endpoint,
+                    body: {
+                        linkId: parsed.linkId,
+                        secret: parsed.secret,
+                        agentName: getAgentName(context),
+                        endpoint: requesterEndpoint,
+                        tokenForRequester,
+                    },
+                });
+                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,
+        };
+    }
+    async check(context, payload) {
+        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({
+                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),
+            };
+        }
+    }
+    async chat(context, payload) {
+        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({
+            endpoint: outbound.endpoint,
+            token: outbound.token,
+            body: {
+                senderContactId: contact.id,
+                message,
+                createdAt: Date.now(),
+            },
+        });
+        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;
+    }
+    async share(context, payload) {
+        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({
+            endpoint: outbound.endpoint,
+            token: outbound.token,
+            body: share,
+        });
+        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,
+            })),
+        };
+    }
+    async remotePing(context, payload) {
+        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"),
+        };
+    }
+    async remoteApprove(context, request) {
+        return await approveContactLinkRequest({
+            projectRoot: context.rootPath,
+            ownerAgentName: getAgentName(context),
+            ownerEndpoint: await resolveSelfEndpoint(context),
+            request,
+        });
+    }
+    async remoteConfirm(context, request) {
+        return await confirmContactLinkRequest({
+            projectRoot: context.rootPath,
+            ownerAgentName: getAgentName(context),
+            request,
+            verifyCallback: async ({ endpoint, token }) => {
+                const pong = await callContactPing({
+                    endpoint,
+                    token,
+                });
+                return Boolean(pong.success && pong.authenticated);
+            },
+        });
+    }
+    async remoteShare(context, rawPayload) {
+        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;
+        const meta = {
+            ...share.meta,
+            fromContactId: contact.id,
+            fromAgentName: contact.name,
+            receivedAt: Date.now(),
+            status: "pending",
+        };
+        await saveContactInboxShare(context.rootPath, {
+            meta,
+            payload: share.payload,
+            files: Array.isArray(share.files) ? share.files : [],
+        });
+        return {
+            success: true,
+            shareId: meta.id,
+        };
+    }
+}
+//# sourceMappingURL=ContactService.js.map