@downcity/plugins 1.0.57 → 1.0.60

package/src/chat/runtime/ChatAuthorizationRuntime.ts

@@ -0,0 +1,229 @@
+/**
+ * ChatAuthorizationRuntime：ChatPlugin 内置授权能力。
+ *
+ * 关键点（中文）
+ * - 授权能力归属于 ChatPlugin，不再作为独立 plugin 注册。
+ * - chat runtime 仍通过通用 plugin hook / resolve 点调用，保持执行链路统一。
+ * - action 名称统一带 `authorization-` 前缀，避免和 chat 会话动作混淆。
+ */
+
+import type {
+  PluginActions,
+  PluginHooks,
+  PluginResolves,
+} from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import { CHAT_PLUGIN_POINTS } from "@/chat/runtime/PluginPoints.js";
+import type { ChatDispatchChannel } from "@/chat/types/ChatDispatcher.js";
+import {
+  CHAT_AUTHORIZATION_ACTIONS,
+  CHAT_AUTHORIZATION_CATALOG,
+  type ChatAuthorizationConfig,
+  type ChatAuthorizationEvaluateInput,
+  type ChatAuthorizationObservePrincipalPayload,
+  type ChatAuthorizationSetUserRolePayload,
+  type ChatAuthorizationSnapshot,
+  type ChatAuthorizationWriteConfigPayload,
+} from "@/auth/types/AuthPlugin.js";
+import {
+  readChatAuthorizationConfig,
+  setChatAuthorizationUserRole,
+  writeChatAuthorizationConfig,
+} from "@/auth/runtime/AuthorizationConfig.js";
+import {
+  evaluateIncomingChatAuthorization,
+  resolveAuthorizedUserRole,
+} from "@/auth/runtime/AuthorizationPolicy.js";
+import {
+  readAuthorizationSnapshot,
+  recordObservedAuthorizationPrincipal,
+} from "@/auth/runtime/AuthorizationStore.js";
+
+function toChannel(value: unknown): ChatDispatchChannel | null {
+  const text = String(value || "").trim().toLowerCase();
+  if (text === "telegram" || text === "feishu" || text === "qq") return text;
+  return null;
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function toEvaluateInput(payload: Record<string, unknown>): ChatAuthorizationEvaluateInput {
+  const channel = toChannel(payload.channel);
+  if (!channel) {
+    throw new Error("chat.authorizeIncoming requires a valid channel");
+  }
+  return {
+    channel,
+    chatId: String(payload.chatId || "").trim(),
+    ...(typeof payload.chatType === "string" ? { chatType: payload.chatType.trim() } : {}),
+    ...(typeof payload.userId === "string" ? { userId: payload.userId.trim() } : {}),
+    ...(typeof payload.username === "string" ? { username: payload.username.trim() } : {}),
+    ...(typeof payload.chatTitle === "string" ? { chatTitle: payload.chatTitle.trim() } : {}),
+  };
+}
+
+function toSnapshotData(snapshot: ChatAuthorizationSnapshot): JsonValue {
+  return {
+    catalog: CHAT_AUTHORIZATION_CATALOG as unknown as JsonValue,
+    config: snapshot.config as unknown as JsonValue,
+    users: snapshot.users as unknown as JsonValue,
+    chats: snapshot.chats as unknown as JsonValue,
+  };
+}
+
+/**
+ * 创建 ChatPlugin 内置授权 hooks。
+ */
+export function createChatAuthorizationHooks(): PluginHooks {
+  return {
+    guard: {
+      [CHAT_PLUGIN_POINTS.authorizeIncoming]: [
+        async ({ context, value }) => {
+          const input =
+            value && typeof value === "object" && !Array.isArray(value)
+              ? (value as Record<string, unknown>)
+              : {};
+          const evaluateInput = toEvaluateInput(input);
+          const authorizationConfig = readChatAuthorizationConfig(context);
+          const result = evaluateIncomingChatAuthorization({
+            config: context.config,
+            channel: evaluateInput.channel,
+            input: evaluateInput,
+            authorizationConfig,
+          });
+          if (result.decision !== "allow") {
+            throw new Error(result.reason || "chat authorization blocked");
+          }
+        },
+      ],
+    },
+    effect: {
+      [CHAT_PLUGIN_POINTS.observePrincipal]: [
+        async ({ context, value }) => {
+          const input = toRecord(
+            value,
+          ) as unknown as ChatAuthorizationObservePrincipalPayload;
+          const channel = toChannel(input.channel);
+          if (!channel) {
+            throw new Error("chat.observePrincipal requires a valid channel");
+          }
+          await recordObservedAuthorizationPrincipal({
+            context,
+            channel,
+            chatId: String(input.chatId || "").trim(),
+            ...(typeof input.chatType === "string"
+              ? { chatType: input.chatType.trim() }
+              : {}),
+            ...(typeof input.chatTitle === "string"
+              ? { chatTitle: input.chatTitle.trim() }
+              : {}),
+            ...(typeof input.userId === "string"
+              ? { userId: input.userId.trim() }
+              : {}),
+            ...(typeof input.username === "string"
+              ? { username: input.username.trim() }
+              : {}),
+          });
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * 创建 ChatPlugin 内置授权 resolve 点。
+ */
+export function createChatAuthorizationResolves(): PluginResolves {
+  return {
+    [CHAT_PLUGIN_POINTS.resolveUserRole]: async ({ context, value }) => {
+      const input =
+        value && typeof value === "object" && !Array.isArray(value)
+          ? (value as Record<string, unknown>)
+          : {};
+      const channel = toChannel(input.channel);
+      if (!channel) {
+        throw new Error("chat.resolveUserRole requires a valid channel");
+      }
+      const role = resolveAuthorizedUserRole({
+        channel,
+        userId: String(input.userId || "").trim(),
+        rootPath: context.rootPath,
+      });
+      return ((role || null) as unknown) as JsonValue;
+    },
+  };
+}
+
+/**
+ * 创建 ChatPlugin 内置授权 actions。
+ */
+export function createChatAuthorizationActions(): PluginActions {
+  return {
+    [CHAT_AUTHORIZATION_ACTIONS.snapshot]: {
+      execute: async ({ context }) => {
+        const snapshot = await readAuthorizationSnapshot({
+          context,
+        });
+        return {
+          success: true,
+          data: toSnapshotData(snapshot),
+        };
+      },
+    },
+    [CHAT_AUTHORIZATION_ACTIONS.readConfig]: {
+      execute: async ({ context }) => {
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+    [CHAT_AUTHORIZATION_ACTIONS.writeConfig]: {
+      execute: async ({ context, payload }) => {
+        const body = toRecord(
+          payload,
+        ) as unknown as ChatAuthorizationWriteConfigPayload;
+        const nextConfig =
+          body.config && typeof body.config === "object" && !Array.isArray(body.config)
+            ? (body.config as ChatAuthorizationConfig)
+            : {};
+        await writeChatAuthorizationConfig({
+          context,
+          nextConfig,
+        });
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+    [CHAT_AUTHORIZATION_ACTIONS.setUserRole]: {
+      execute: async ({ context, payload }) => {
+        const body = toRecord(
+          payload,
+        ) as unknown as ChatAuthorizationSetUserRolePayload;
+        const channel = toChannel(body.channel);
+        if (!channel) {
+          return {
+            success: false,
+            error: "authorization-set-user-role requires a valid channel",
+            message: "authorization-set-user-role requires a valid channel",
+          };
+        }
+        await setChatAuthorizationUserRole({
+          context,
+          channel,
+          userId: String(body.userId || "").trim(),
+          roleId: String(body.roleId || "").trim(),
+        });
+        return {
+          success: true,
+          data: readChatAuthorizationConfig(context) as unknown as JsonValue,
+        };
+      },
+    },
+  };
+}

package/src/chat/runtime/ChatChannelActions.ts

@@ -25,11 +25,11 @@ import {
   getChatChannelStatus,
   listChatChannelConfigurationDescriptions,
   normalizeChatChannelConfigPatch,
-  setChatChannelConfig,
-  setChatChannelEnabled,
 } from "./ChatChannelConfig.js";
 import {
+  type ChatRuntimeBindings,
   getChatChannelBot,
+  resolveChatPluginBindings,
   resolveTargetChannels,
 } from "./ChatChannelCore.js";
 import {
@@ -37,6 +37,18 @@ import {
   stopSingleChatChannel,
 } from "./ChatChannelLifecycle.js";
 
+type ChatRuntimeControlBindings = ChatRuntimeBindings & {
+  applyChannelRuntimePatch: NonNullable<ChatRuntimeBindings["applyChannelRuntimePatch"]>;
+};
+
+function getChatRuntimeBindings(context: AgentContext): ChatRuntimeControlBindings {
+  const plugin = resolveChatPluginBindings(context);
+  if (!plugin?.applyChannelRuntimePatch) {
+    throw new Error("ChatPlugin runtime instance is not available");
+  }
+  return plugin as ChatRuntimeControlBindings;
+}
+
 /**
  * 执行 `chat.status` action。
  */
@@ -163,9 +175,9 @@ export async function executeChatOpenAction(params: {
   payload: ChatOpenActionPayload;
 }) {
   const targets = resolveTargetChannels(params.payload.channel);
+  const plugin = getChatRuntimeBindings(params.context);
   for (const channel of targets) {
-    await setChatChannelEnabled({
-      context: params.context,
+    plugin.applyChannelRuntimePatch({
       channel,
       enabled: true,
     });
@@ -198,10 +210,10 @@ export async function executeChatCloseAction(params: {
   payload: ChatCloseActionPayload;
 }) {
   const targets = resolveTargetChannels(params.payload.channel);
+  const plugin = getChatRuntimeBindings(params.context);
   for (const channel of targets) {
     await stopSingleChatChannel(params.state, channel);
-    await setChatChannelEnabled({
-      context: params.context,
+    plugin.applyChannelRuntimePatch({
       channel,
       enabled: false,
     });
@@ -280,10 +292,13 @@ export async function executeChatConfigureAction(params: {
     }
   }
 
-  await setChatChannelConfig({
-    context: params.context,
+  const plugin = getChatRuntimeBindings(params.context);
+  plugin.applyChannelRuntimePatch({
     channel,
-    patch,
+    ...(typeof patch.enabled === "boolean" ? { enabled: patch.enabled } : {}),
+    ...(Object.prototype.hasOwnProperty.call(patch, "channelAccountId")
+      ? { channelAccountId: String(patch.channelAccountId || "").trim() || null }
+      : {}),
   });
 
   // 关键点（中文）：默认重载一次目标渠道，让新配置立刻生效。

package/src/chat/runtime/ChatChannelConfig.ts

@@ -2,13 +2,11 @@
  * ChatChannelConfig：chat 渠道配置与状态快照模块。
  *
  * 关键点（中文）
- * - 渠道配置摘要、状态快照、patch 归一化、downcity.json 落盘都收敛在这里。
- * - 所有配置写入都遵循“先改内存，再落盘”的一致性顺序。
+ * - 渠道配置摘要、状态快照、patch 归一化都收敛在这里。
+ * - chat.configure 的运行态写入由 ChatPlugin 实例承载，不再落盘到 downcity.json。
  * - 该模块不直接负责 action 流程控制，只提供可复用的底层能力。
  */
 
-import fs from "node:fs/promises";
-import path from "node:path";
 import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { StoredChannelAccount } from "@downcity/agent/internal/types/platform/Store.js";
@@ -109,47 +107,6 @@ export function getChatChannelStatus(
   };
 }
 
-/**
- * 更新内存配置与 downcity.json 中的 channel enabled 状态。
- */
-export async function setChatChannelEnabled(params: {
-  context: AgentContext;
-  channel: ChatChannelName;
-  enabled: boolean;
-}): Promise<void> {
-  const { context, channel, enabled } = params;
-
-  const configPlugins = ((context.config.plugins ??= {}) as {
-    chat?: {
-      channels?: Record<string, Record<string, unknown>>;
-    };
-  });
-  const chatConfig = (configPlugins.chat ??= {});
-  const channelConfigs = (chatConfig.channels ??= {});
-  const channelConfig = (channelConfigs[channel] ??= {});
-  channelConfig.enabled = enabled;
-
-  const shipPath = path.join(context.rootPath, "downcity.json");
-  let shipJson: Record<string, unknown> = {};
-  try {
-    const raw = await fs.readFile(shipPath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      shipJson = parsed as Record<string, unknown>;
-    }
-  } catch {
-    shipJson = {};
-  }
-
-  const shipPlugins = ((shipJson.plugins ??= {}) as Record<string, unknown>);
-  const shipChat = ((shipPlugins.chat ??= {}) as Record<string, unknown>);
-  const shipChannels = ((shipChat.channels ??= {}) as Record<string, unknown>);
-  const shipChannel = ((shipChannels[channel] ??= {}) as Record<string, unknown>);
-  shipChannel.enabled = enabled;
-
-  await fs.writeFile(shipPath, `${JSON.stringify(shipJson, null, 2)}\n`, "utf-8");
-}
-
 function isJsonObject(value: JsonValue): value is JsonObject {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -253,61 +210,6 @@ export function normalizeChatChannelConfigPatch(params: {
   return patch;
 }
 
-function applyChannelPatch(
-  target: Record<string, unknown>,
-  patch: Record<string, string | number | boolean | null>,
-): void {
-  for (const [key, value] of Object.entries(patch)) {
-    if (value === null) {
-      delete target[key];
-      continue;
-    }
-    target[key] = value;
-  }
-}
-
-/**
- * 更新单个 channel 配置（内存 + downcity.json）。
- */
-export async function setChatChannelConfig(params: {
-  context: AgentContext;
-  channel: ChatChannelName;
-  patch: Record<string, string | number | boolean | null>;
-}): Promise<void> {
-  const { context, channel, patch } = params;
-  if (Object.keys(patch).length === 0) return;
-
-  const configPlugins = ((context.config.plugins ??= {}) as {
-    chat?: {
-      channels?: Record<string, Record<string, unknown>>;
-    };
-  });
-  const chatConfig = (configPlugins.chat ??= {});
-  const channelConfigs = (chatConfig.channels ??= {});
-  const channelConfig = (channelConfigs[channel] ??= {});
-  applyChannelPatch(channelConfig, patch);
-
-  const shipPath = path.join(context.rootPath, "downcity.json");
-  let shipJson: Record<string, unknown> = {};
-  try {
-    const raw = await fs.readFile(shipPath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      shipJson = parsed as Record<string, unknown>;
-    }
-  } catch {
-    shipJson = {};
-  }
-
-  const shipPlugins = ((shipJson.plugins ??= {}) as Record<string, unknown>);
-  const shipChat = ((shipPlugins.chat ??= {}) as Record<string, unknown>);
-  const shipChannels = ((shipChat.channels ??= {}) as Record<string, unknown>);
-  const shipChannel = ((shipChannels[channel] ??= {}) as Record<string, unknown>);
-  applyChannelPatch(shipChannel, patch);
-
-  await fs.writeFile(shipPath, `${JSON.stringify(shipJson, null, 2)}\n`, "utf-8");
-}
-
 /**
  * 读取渠道 configuration 描述。
  */

package/src/chat/runtime/ChatChannelCore.ts

@@ -15,16 +15,30 @@ import { getStoredChannelAccountSync } from "@/chat/accounts/Store.js";
 
 const CHAT_CHANNEL_NAMES: ChatChannelName[] = ["telegram", "feishu", "qq"];
 
-type ChatRuntimeBindings = {
+export type ChatRuntimeBindings = {
   getChannelAccountId?(context: AgentContext, channel: ChatChannelName): string;
   resolveChannelAccount?(
     context: AgentContext,
     channel: ChatChannelName,
   ): StoredChannelAccount | null;
   isChannelEnabled?(context: AgentContext, channel: ChatChannelName): boolean;
+  applyChannelRuntimePatch?(params: {
+    /**
+     * 目标渠道。
+     */
+    channel: ChatChannelName;
+    /**
+     * 是否启用该渠道。
+     */
+    enabled?: boolean;
+    /**
+     * 绑定的账号池记录 ID；传入 null 表示清空绑定。
+     */
+    channelAccountId?: string | null;
+  }): void;
 };
 
-function resolveChatPluginBindings(
+export function resolveChatPluginBindings(
   context: AgentContext,
 ): ChatRuntimeBindings | null {
   const candidate = context.agent?.pluginInstances?.get?.("chat") as
@@ -78,10 +92,7 @@ export function resolveChannelAccountId(
   const plugin = resolveChatPluginBindings(context);
   const explicit = String(plugin?.getChannelAccountId?.(context, channel) || "").trim();
   if (explicit) return explicit;
-  const config = context.config.plugins?.chat?.channels?.[channel] as
-    | { channelAccountId?: unknown }
-    | undefined;
-  return String(config?.channelAccountId || "").trim();
+  return "";
 }
 
 /**
@@ -89,7 +100,8 @@ export function resolveChannelAccountId(
  *
  * 关键点（中文）
  * - 优先使用 ChatPlugin 实例上的显式解析逻辑。
- * - 若未命中，再回退到默认全局账号池 `~/.downcity/downcity.db`。
+ * - 若实例只提供 channelAccountId，再从默认全局账号池读取对应账号。
+ * - 不再从 downcity.json 隐式推断运行时账号。
  */
 export function resolveChannelAccount(
   context: AgentContext,
@@ -132,7 +144,7 @@ export function isChatChannelEnabled(
   if (typeof plugin?.isChannelEnabled === "function") {
     return plugin.isChannelEnabled(context, channel);
   }
-  return context.config.plugins?.chat?.channels?.[channel]?.enabled === true;
+  return false;
 }
 
 /**

package/src/chat/runtime/ChatPluginActionRegistry.ts

@@ -198,7 +198,7 @@ export function createChatPluginActions(params: {
     },
     configure: {
       command: {
-        description: "更新 chat 渠道参数（写入 downcity.json，可选立即重载）",
+        description: "更新 chat 渠道运行态参数（可选立即重载）",
         configure(command: Command) {
           command
             .requiredOption("--channel <name>", "指定渠道（telegram|feishu|qq）")

package/src/chat/runtime/PluginPoints.ts

@@ -56,7 +56,7 @@ export const CHAT_PLUGIN_POINTS = {
    *
    * 说明（中文）
    * - 仅做副作用记录，不返回值。
-   * - 典型实现方是 chat-authorization plugin。
+   * - ChatPlugin 内置授权能力会使用该点记录主体快照。
    */
   observePrincipal: "chat.observePrincipal",
   /**
@@ -64,7 +64,7 @@ export const CHAT_PLUGIN_POINTS = {
    *
    * 说明（中文）
    * - 由 chat plugin runtime 在 ingress 阶段显式调用。
-   * - 典型实现方是 chat-authorization plugin。
+   * - ChatPlugin 内置授权能力会使用该点执行角色与权限判定。
    */
   authorizeIncoming: "chat.authorizeIncoming",
   /**
@@ -72,7 +72,7 @@ export const CHAT_PLUGIN_POINTS = {
    *
    * 说明（中文）
    * - 主要用于在 history / queue metadata 中补齐授权上下文。
-   * - 典型实现方是 chat-authorization plugin。
+   * - ChatPlugin 内置授权能力会使用该点补齐用户角色。
    */
   resolveUserRole: "chat.resolveUserRole",
 } as const;

package/src/chat/types/ChannelStatus.ts

@@ -42,7 +42,7 @@ export type ChatChannelStateSnapshot = {
    */
   channel: ChatChannelName;
   /**
-   * 是否在配置中启用（`downcity.json` 的 `plugins.chat.channels.<channel>.enabled`）。
+   * 当前运行态是否启用该渠道。
    */
   enabled: boolean;
   /**

package/src/chat/types/ChatPluginOptions.ts

@@ -0,0 +1,79 @@
+/**
+ * ChatPlugin SDK / runtime 配置类型。
+ *
+ * 关键点（中文）
+ * - ChatPlugin 只接收 queue 行为与 channels 列表。
+ * - 每个 channel 对象自己负责 env / 凭据 / 账号池绑定解析。
+ * - 这样 ChatPlugin 不再理解 Telegram、Feishu、QQ 的具体配置字段。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { StoredChannelAccount } from "@downcity/agent/internal/types/platform/Store.js";
+import type { ChatChannelName } from "@/chat/types/ChannelStatus.js";
+import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+
+/**
+ * Chat channel 运行态 patch。
+ */
+export interface ChatChannelRuntimePatch {
+  /**
+   * 是否启用该 channel。
+   */
+  enabled?: boolean;
+  /**
+   * 绑定的账号池记录 ID。
+   *
+   * 说明（中文）
+   * - 传入字符串表示绑定到该账号池记录。
+   * - 传入 `null` 表示清空账号池绑定。
+   */
+  channelAccountId?: string | null;
+}
+
+/**
+ * Chat channel 对象协议。
+ */
+export interface ChatChannel {
+  /**
+   * channel 名称。
+   */
+  readonly name: ChatChannelName;
+  /**
+   * 当前 channel 是否启用。
+   */
+  isEnabled(context: AgentContext): boolean;
+  /**
+   * 当前 channel 绑定的账号池记录 ID。
+   */
+  getChannelAccountId(context: AgentContext): string;
+  /**
+   * 解析当前 channel 的运行态账号。
+   */
+  getAccount(context: AgentContext): StoredChannelAccount | null;
+  /**
+   * 应用运行态配置 patch。
+   */
+  applyRuntimePatch(patch: ChatChannelRuntimePatch): void;
+}
+
+/**
+ * ChatPlugin 显式构造参数。
+ */
+export interface ChatPluginOptions {
+  /**
+   * Chat queue worker 运行配置。
+   *
+   * 说明（中文）
+   * - 可用于不同 client 定制并发、突发合并等行为。
+   * - 这是 queue 行为的唯一运行配置入口。
+   */
+  queue?: Partial<ChatQueueWorkerConfig>;
+  /**
+   * 当前 agent 持有的 chat channels。
+   *
+   * 说明（中文）
+   * - 每个 channel 对象自己负责 env、凭据与账号池绑定解析。
+   * - 未传入时不启用任何 chat channel。
+   */
+  channels?: ChatChannel[];
+}

package/src/contact/ContactPlugin.ts

@@ -30,6 +30,7 @@ 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 type { ContactPluginOptions } from "@/contact/types/ContactPluginOptions.js";
 import {
   appendContactMessage,
   createStableContactId,
@@ -145,8 +146,14 @@ export class ContactPlugin extends BasePlugin {
    */
   readonly actions: PluginActions;
 
-  constructor() {
+  /**
+   * 当前实例持有的显式配置。
+   */
+  public readonly options: ContactPluginOptions;
+
+  constructor(options?: ContactPluginOptions) {
     super();
+    this.options = options || {};
     this.actions = createContactActions({
       link: async (context, payload) =>
         (await this.link(context, payload)) as unknown as JsonValue,
@@ -164,11 +171,6 @@ export class ContactPlugin extends BasePlugin {
       remoteShare: async (context, payload) =>
         (await this.remoteShare(context, payload)) as unknown as JsonValue,
     });
-
-    this.lifecycle = {
-      start: () => undefined,
-      stop: () => undefined,
-    };
   }
 
   /**
@@ -180,10 +182,16 @@ export class ContactPlugin extends BasePlugin {
 
   private async link(context: AgentContext, payload: ContactLinkCommandPayload) {
     const now = Date.now();
-    const ttlSeconds = Math.max(60, Number(payload.ttlSeconds || 600));
+    const ttlSeconds = Math.max(
+      60,
+      Number(payload.ttlSeconds || this.options.ttlSeconds || 600),
+    );
     const linkId = createContactId("link");
     const secret = createContactToken();
-    const endpoint = await resolveSelfEndpoint(context, payload.endpoint);
+    const endpoint = await resolveSelfEndpoint(
+      context,
+      payload.endpoint || this.options.endpoint,
+    );
     const agentName = getAgentName(context);
 
     await saveContactLinkRecord(context.rootPath, {
@@ -228,7 +236,7 @@ export class ContactPlugin extends BasePlugin {
       targetReachability === "loopback" ||
       targetReachability === "private";
     const requesterEndpointCandidate = shouldResolveRequesterEndpoint
-      ? await resolveSelfEndpoint(context, payload.endpoint)
+      ? await resolveSelfEndpoint(context, payload.endpoint || this.options.endpoint)
       : undefined;
     const callbackDecision = buildContactApproveCallbackDecision({
       targetEndpoint: parsed.endpoint,