@downcity/agent 1.1.1

package/bin/services/contact/runtime/EndpointNotice.d.ts

@@ -0,0 +1,39 @@
+/**
+ * contact endpoint 用户提示。
+ *
+ * 关键点（中文）
+ * - `contact link` / `contact approve` 会被 agent 自己调用，返回结果必须直接说明可达性限制。
+ * - loopback/private endpoint 不是错误，但需要提醒用户不要拿给无法访问该地址的远端 agent。
+ */
+import type { ContactEndpointReachability } from "../../../types/contact/ContactEndpoint.js";
+/**
+ * 判断 endpoint 的粗粒度可达范围。
+ */
+export declare function classifyContactEndpoint(endpoint: string): ContactEndpointReachability;
+/**
+ * 生成 `contact link` 返回提示。
+ */
+export declare function buildContactLinkNotes(params: {
+    /**
+     * link code 内写入的 endpoint。
+     */
+    endpoint: string;
+}): string[];
+/**
+ * 生成 `contact approve` 返回提示。
+ */
+export declare function buildContactApproveNotes(params: {
+    /**
+     * link code 中的目标 endpoint。
+     */
+    targetEndpoint: string;
+    /**
+     * approve 方随请求发送给对方的 endpoint。
+     */
+    requesterEndpoint?: string;
+    /**
+     * 对方是否已经主动 ping 回 approve 方并确认成功。
+     */
+    callbackConfirmed?: boolean;
+}): string[];
+//# sourceMappingURL=EndpointNotice.d.ts.map

package/bin/services/contact/runtime/EndpointNotice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndpointNotice.d.ts","sourceRoot":"","sources":["../../../../src/services/contact/runtime/EndpointNotice.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAsBtF;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,GACf,2BAA2B,CAY7B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,EAAE,CAsBX;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,GAAG,MAAM,EAAE,CA2BX"}

package/bin/services/contact/runtime/EndpointNotice.js

@@ -0,0 +1,98 @@
+/**
+ * contact endpoint 用户提示。
+ *
+ * 关键点（中文）
+ * - `contact link` / `contact approve` 会被 agent 自己调用，返回结果必须直接说明可达性限制。
+ * - loopback/private endpoint 不是错误，但需要提醒用户不要拿给无法访问该地址的远端 agent。
+ */
+function readHostname(endpoint) {
+    const value = String(endpoint || "").trim();
+    if (!value)
+        return "";
+    try {
+        return new URL(value).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    }
+    catch {
+        return "";
+    }
+}
+function isPrivateIpv4(hostname) {
+    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) {
+    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) {
+    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) {
+    const notes = [];
+    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;
+}
+//# sourceMappingURL=EndpointNotice.js.map

package/bin/services/contact/runtime/EndpointNotice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndpointNotice.js","sourceRoot":"","sources":["../../../../src/services/contact/runtime/EndpointNotice.ts"],"names":[],"mappings":"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"}

package/bin/services/contact/runtime/EndpointResolver.d.ts

@@ -0,0 +1,36 @@
+/**
+ * contact 自身 endpoint 解析。
+ *
+ * 关键点（中文）
+ * - endpoint 是 contact 协议内部字段，不暴露成普通用户命令参数。
+ * - 优先使用明确配置的公开地址，避免服务器 / 反向代理 / tunnel 场景被误判。
+ * - 监听 `0.0.0.0` 时只做本机网卡最佳努力探测，不访问外部网络。
+ */
+import os from "node:os";
+export interface ResolveContactSelfEndpointInput {
+    /**
+     * 运行时监听 host。
+     */
+    host?: string;
+    /**
+     * 运行时监听 port。
+     */
+    port?: number;
+    /**
+     * 环境变量读取来源，测试可注入。
+     */
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+    /**
+     * 网卡信息读取来源，测试可注入。
+     */
+    interfaces?: NodeJS.Dict<os.NetworkInterfaceInfo[]>;
+    /**
+     * 公网 IPv4 解析器，测试可注入。
+     */
+    resolvePublicIpv4?: () => Promise<string | null> | string | null;
+}
+/**
+ * 解析 contact link code 中写入的自身 endpoint。
+ */
+export declare function resolveContactSelfEndpoint(input: ResolveContactSelfEndpointInput): Promise<string>;
+//# sourceMappingURL=EndpointResolver.d.ts.map

package/bin/services/contact/runtime/EndpointResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndpointResolver.d.ts","sourceRoot":"","sources":["../../../../src/services/contact/runtime/EndpointResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7D;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,CAAC;IACpD;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;CAClE;AAoFD;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/bin/services/contact/runtime/EndpointResolver.js

@@ -0,0 +1,113 @@
+/**
+ * contact 自身 endpoint 解析。
+ *
+ * 关键点（中文）
+ * - endpoint 是 contact 协议内部字段，不暴露成普通用户命令参数。
+ * - 优先使用明确配置的公开地址，避免服务器 / 反向代理 / tunnel 场景被误判。
+ * - 监听 `0.0.0.0` 时只做本机网卡最佳努力探测，不访问外部网络。
+ */
+import os from "node:os";
+function normalizeUrl(value, fallbackPort) {
+    const raw = String(value || "").trim();
+    if (!raw)
+        return formatUrl("127.0.0.1", fallbackPort);
+    if (/^https?:\/\//i.test(raw))
+        return raw.replace(/\/$/, "");
+    return formatUrl(raw, fallbackPort);
+}
+function formatUrl(host, port) {
+    const normalizedHost = String(host || "").trim() || "127.0.0.1";
+    if (normalizedHost.startsWith("["))
+        return `http://${normalizedHost}:${String(port)}`;
+    if (normalizedHost.includes(":") && !normalizedHost.includes(".")) {
+        return `http://[${normalizedHost}]:${String(port)}`;
+    }
+    return `http://${normalizedHost}:${String(port)}`;
+}
+function isWildcardHost(host) {
+    const value = String(host || "").trim().toLowerCase();
+    return !value || value === "0.0.0.0" || value === "::";
+}
+function isLoopbackHost(host) {
+    const value = String(host || "").trim().toLowerCase();
+    return value === "127.0.0.1" || value === "::1" || value === "localhost";
+}
+function detectLanIpv4FromInterfaces(interfaces = os.networkInterfaces()) {
+    for (const entries of Object.values(interfaces)) {
+        const items = (entries || []);
+        for (const rawItem of items) {
+            const family = typeof rawItem.family === "string"
+                ? rawItem.family
+                : rawItem.family === 4
+                    ? "IPv4"
+                    : "unknown";
+            if (family !== "IPv4")
+                continue;
+            if (rawItem.internal)
+                continue;
+            const address = String(rawItem.address || "").trim();
+            if (address)
+                return address;
+        }
+    }
+    return null;
+}
+function isIpv4Address(value) {
+    const parts = String(value || "").trim().split(".");
+    if (parts.length !== 4)
+        return false;
+    return parts.every((part) => {
+        if (!/^\d+$/.test(part))
+            return false;
+        const value = Number.parseInt(part, 10);
+        return value >= 0 && value <= 255;
+    });
+}
+async function resolvePublicIpv4FromNetwork() {
+    if (typeof fetch !== "function")
+        return null;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 800);
+    try {
+        const response = await fetch("https://api.ipify.org?format=json", {
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json().catch(() => null));
+        const ip = String(data?.ip || "").trim();
+        return isIpv4Address(ip) ? ip : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * 解析 contact link code 中写入的自身 endpoint。
+ */
+export async function resolveContactSelfEndpoint(input) {
+    const env = input.env || process.env;
+    const port = Number(input.port || env.DC_SERVER_PORT || 5314);
+    // 关键点（中文）：公开 URL 是最可靠来源，适配域名、反向代理和 tunnel。
+    const publicUrl = String(env.DOWNCITY_PUBLIC_URL || "").trim();
+    if (publicUrl)
+        return normalizeUrl(publicUrl, port);
+    const publicHost = String(env.DOWNCITY_PUBLIC_HOST || "").trim();
+    if (publicHost)
+        return formatUrl(publicHost, port);
+    const host = String(input.host || env.DC_SERVER_HOST || "127.0.0.1").trim();
+    if (!isWildcardHost(host) && !isLoopbackHost(host))
+        return formatUrl(host, port);
+    const lanIp = detectLanIpv4FromInterfaces(input.interfaces);
+    if (lanIp)
+        return formatUrl(lanIp, port);
+    // 关键点（中文）：云服务器公网 IP 可能不在网卡上，最后再做短超时公网探测。
+    const publicIp = String((await (input.resolvePublicIpv4 || resolvePublicIpv4FromNetwork)()) || "").trim();
+    if (isIpv4Address(publicIp))
+        return formatUrl(publicIp, port);
+    return formatUrl("127.0.0.1", port);
+}
+//# sourceMappingURL=EndpointResolver.js.map

package/bin/services/contact/runtime/EndpointResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndpointResolver.js","sourceRoot":"","sources":["../../../../src/services/contact/runtime/EndpointResolver.ts"],"names":[],"mappings":"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"}

package/bin/services/contact/runtime/InboxStore.d.ts

@@ -0,0 +1,33 @@
+/**
+ * contact inbox 存储。
+ *
+ * 关键点（中文）
+ * - 每条 share 都是独立目录，避免大内容堆进单个 JSON。
+ * - `inbox` 列表只读取 `meta.json`，保持轻量。
+ */
+import type { ContactInboxShareMeta, ContactInboxSharePayload, SaveContactInboxShareInput } from "../../../types/contact/ContactShare.js";
+/**
+ * 保存 inbox share。
+ */
+export declare function saveContactInboxShare(projectRoot: string, input: SaveContactInboxShareInput): Promise<ContactInboxShareMeta>;
+/**
+ * 读取 inbox share meta。
+ */
+export declare function readContactInboxShareMeta(projectRoot: string, shareId: string): Promise<ContactInboxShareMeta | null>;
+/**
+ * 读取 inbox share payload。
+ */
+export declare function readContactInboxSharePayload(projectRoot: string, shareId: string): Promise<ContactInboxSharePayload | null>;
+/**
+ * 列出 inbox share。
+ */
+export declare function listContactInboxShares(projectRoot: string): Promise<ContactInboxShareMeta[]>;
+/**
+ * 标记 share 已接收，并复制轻量状态到 received。
+ */
+export declare function markContactInboxShareReceived(projectRoot: string, shareId: string): Promise<ContactInboxShareMeta>;
+/**
+ * 读取 share 文件根目录。
+ */
+export declare function getInboxShareFilesRoot(projectRoot: string, shareId: string): string;
+//# sourceMappingURL=InboxStore.d.ts.map

package/bin/services/contact/runtime/InboxStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboxStore.d.ts","sourceRoot":"","sources":["../../../../src/services/contact/runtime/InboxStore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,iCAAiC,CAAC;AAoCzC;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,qBAAqB,CAAC,CA2ChC;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAKvC;AAED;;GAEG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAO1C;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAWlC;AAED;;GAEG;AACH,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,qBAAqB,CAAC,CAiBhC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnF"}

package/bin/services/contact/runtime/InboxStore.js

@@ -0,0 +1,142 @@
+/**
+ * contact inbox 存储。
+ *
+ * 关键点（中文）
+ * - 每条 share 都是独立目录，避免大内容堆进单个 JSON。
+ * - `inbox` 列表只读取 `meta.json`，保持轻量。
+ */
+import fs from "fs-extra";
+import path from "node:path";
+import { getContactInboxRootPath, getContactInboxShareFilesPath, getContactInboxShareMetaPath, getContactInboxSharePath, getContactInboxSharePayloadPath, getContactReceivedSharePath, } from "./Paths.js";
+function assertSafeRelativePath(relativePath) {
+    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) {
+    const item = input;
+    return Boolean(item &&
+        typeof item.id === "string" &&
+        typeof item.fromAgentName === "string" &&
+        (item.status === "pending" || item.status === "received"));
+}
+/**
+ * 保存 inbox share。
+ */
+export async function saveContactInboxShare(projectRoot, input) {
+    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, shareId) {
+    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, shareId) {
+    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;
+    return payload.kind === "share" ? payload : null;
+}
+/**
+ * 列出 inbox share。
+ */
+export async function listContactInboxShares(projectRoot) {
+    const root = getContactInboxRootPath(projectRoot);
+    if (!(await fs.pathExists(root)))
+        return [];
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const shares = [];
+    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, shareId) {
+    const meta = await readContactInboxShareMeta(projectRoot, shareId);
+    if (!meta)
+        throw new Error(`Share not found: ${shareId}`);
+    const next = {
+        ...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, shareId) {
+    return getContactInboxShareFilesPath(projectRoot, shareId);
+}
+//# sourceMappingURL=InboxStore.js.map

package/bin/services/contact/runtime/InboxStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InboxStore.js","sourceRoot":"","sources":["../../../../src/services/contact/runtime/InboxStore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,UAAU,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAM7B,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,+BAA+B,EAC/B,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AAEpB,SAAS,sBAAsB,CAAC,YAAoB;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,EAAE,CAAC,CAAC;IACtF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACzC,IACE,UAAU,KAAK,GAAG;QAClB,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC;QAC3B,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/C,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,EACpC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,yBAAyB,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,MAAM,IAAI,GAAG,KAA8C,CAAC;IAC5D,OAAO,OAAO,CACZ,IAAI;QACF,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ;QAC3B,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ;QACtC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,CAAC,CAC5D,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,WAAmB,EACnB,KAAiC;IAEjC,MAAM,SAAS,GAAG,uBAAuB,CAAC,WAAW,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,wBAAwB,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CACxB,QAAQ,EACR,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,CAC3D,CAAC;IAEF,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC7B,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,EAAE,KAAK,CAAC,OAAO,EAAE;YACrE,MAAM,EAAE,CAAC;SACV,CAAC,CAAC;QAEH,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/B,MAAM,YAAY,GAAG,sBAAsB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC/D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;YACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;YAChE,MAAM,OAAO,GACX,QAAQ,KAAK,QAAQ;gBACnB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;gBACrC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;YAC7C,MAAM,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,iDAAiD;QACjD,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE;YAC/D,MAAM,EAAE,CAAC;SACV,CAAC,CAAC;QACH,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE;YACjC,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,WAAmB,EACnB,OAAe;IAEf,MAAM,QAAQ,GAAG,4BAA4B,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACpE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,WAAmB,EACnB,OAAe;IAEf,MAAM,QAAQ,GAAG,+BAA+B,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACvE,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,MAAM,OAAO,GAAG,GAA+B,CAAC;IAChD,OAAO,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,WAAmB;IAEnB,MAAM,IAAI,GAAG,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;YAAE,SAAS;QACnC,MAAM,IAAI,GAAG,MAAM,yBAAyB,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACtE,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,WAAmB,EACnB,OAAe;IAEf,MAAM,IAAI,GAAG,MAAM,yBAAyB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnE,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC1D,MAAM,IAAI,GAA0B;QAClC,GAAG,IAAI;QACP,MAAM,EAAE,UAAU;KACnB,CAAC;IACF,MAAM,YAAY,GAAG,2BAA2B,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACvE,MAAM,EAAE,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IACjC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE;QAC7D,MAAM,EAAE,CAAC;KACV,CAAC,CAAC;IACH,wDAAwD;IACxD,MAAM,EAAE,CAAC,SAAS,CAAC,4BAA4B,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE;QAC3E,MAAM,EAAE,CAAC;KACV,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB,EAAE,OAAe;IACzE,OAAO,6BAA6B,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC"}

package/bin/services/contact/runtime/LinkApproval.d.ts

@@ -0,0 +1,20 @@
+/**
+ * contact link approve 状态机。
+ *
+ * 关键点（中文）
+ * - 远端 approve 只有一个入口：校验 link -> 保存 contact -> 消费 link。
+ * - 同一个 agent 在 link 有效期内可重试，用于恢复“远端已保存、本地保存失败”的半建联。
+ * - contact token 由协议自动交换，不依赖用户手动配置环境变量。
+ */
+import type { ContactApproveLinkResponse } from "../../../types/contact/ContactLink.js";
+import type { ApproveContactLinkRequestInput, ConfirmContactLinkRequestInput, ContactConfirmResponse } from "../../../types/contact/ContactApproval.js";
+export declare const CONTACT_LINK_NOT_FOUND_ERROR = "Contact link not found. This runtime does not have that link record. This usually means the approve request reached the wrong endpoint or port, the link was generated by another agent/project, or the local link store was cleared. If the code is expired, the remote agent returns Contact link expired instead.";
+/**
+ * 执行远端 link approve 状态转换。
+ */
+export declare function approveContactLinkRequest(input: ApproveContactLinkRequestInput): Promise<ContactApproveLinkResponse>;
+/**
+ * 执行远端 confirm 状态转换。
+ */
+export declare function confirmContactLinkRequest(input: ConfirmContactLinkRequestInput): Promise<ContactConfirmResponse>;
+//# sourceMappingURL=LinkApproval.d.ts.map

package/bin/services/contact/runtime/LinkApproval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkApproval.d.ts","sourceRoot":"","sources":["../../../../src/services/contact/runtime/LinkApproval.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,KAAK,EACV,8BAA8B,EAC9B,8BAA8B,EAC9B,sBAAsB,EACvB,MAAM,oCAAoC,CAAC;AAiB5C,eAAO,MAAM,4BAA4B,yTAC+Q,CAAC;AA0GzT;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,0BAA0B,CAAC,CA4FrC;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAgJjC"}