@hermespilot/link 0.2.2 → 0.2.3

package/dist/{chunk-4YF43CT4.js → chunk-HIQBCPY4.js}

@@ -4643,7 +4643,7 @@ function toSummary(manifest, snapshot, profile) {
 }
 function isDefaultConversationTitle(title) {
   const normalized = title.trim().toLowerCase();
-  return !normalized || normalized === "untitled" || normalized === DEFAULT_CONVERSATION_TITLE;
+  return !normalized || normalized === "untitled" || normalized === DEFAULT_CONVERSATION_TITLE.toLowerCase();
 }
 function temporaryTitleFromUserMessage(content) {
   const normalized = content.replace(MEDIA_TAG_PATTERN, " ").replace(/\s+/gu, " ").trim();
@@ -4677,7 +4677,7 @@ import os2 from "os";
 import path7 from "path";
 
 // src/constants.ts
-var LINK_VERSION = "0.2.2";
+var LINK_VERSION = "0.2.3";
 var LINK_COMMAND = "hermeslink";
 var LINK_DEFAULT_PORT = 52379;
 var LINK_RUNTIME_DIR_NAME = ".hermeslink";
@@ -5068,6 +5068,46 @@ async function deleteHermesSession(sessionId, profileName = "default") {
     );
   }
 }
+async function renameHermesSession(sessionId, title, profileName = "default") {
+  const normalizedSessionId = sessionId.trim();
+  const normalizedTitle = title.trim();
+  if (!normalizedSessionId) {
+    throw new LinkHttpError(
+      400,
+      "hermes_session_id_required",
+      "Hermes session id is required"
+    );
+  }
+  if (!normalizedTitle) {
+    throw new LinkHttpError(
+      400,
+      "hermes_session_title_required",
+      "Hermes session title is required"
+    );
+  }
+  try {
+    await execFileAsync(
+      resolveHermesBin(),
+      [
+        ...profileArgs(profileName),
+        "sessions",
+        "rename",
+        normalizedSessionId,
+        normalizedTitle
+      ],
+      {
+        timeout: 1e4,
+        windowsHide: true
+      }
+    );
+  } catch (error) {
+    throw new LinkHttpError(
+      502,
+      "hermes_session_rename_failed",
+      error instanceof Error ? error.message : "Hermes session rename failed"
+    );
+  }
+}
 function resolveHermesBin() {
   return process.env.HERMES_BIN?.trim() || "hermes";
 }
@@ -5864,22 +5904,22 @@ var ConversationCommandHandlers = class {
         response: `\u5F53\u524D\u4F1A\u8BDD\u6807\u9898\uFF1A${input.manifest.title}`
       });
     }
-    await this.deps.writeManifest({
-      ...input.manifest,
+    const result = await this.deps.renameConversation(
+      input.manifest.id,
       title,
-      updated_at: (/* @__PURE__ */ new Date()).toISOString()
-    });
-    await this.deps.appendEvent(input.manifest.id, {
-      type: "conversation.updated",
-      payload: { command: "title", title }
-    });
+      {
+        manifest: input.manifest,
+        snapshot: input.snapshot,
+        source: "manual"
+      }
+    );
     return this.deps.appendCommandResult({
       manifest: await this.deps.readManifest(input.manifest.id),
       snapshot: input.snapshot,
       rawContent: input.rawContent,
       clientMessageId: input.clientMessageId,
       commandName: input.command.name,
-      response: `\u5DF2\u5C06\u5F53\u524D\u4F1A\u8BDD\u6807\u9898\u6539\u4E3A\uFF1A${title}`
+      response: `\u5DF2\u5C06\u5F53\u524D\u4F1A\u8BDD\u6807\u9898\u6539\u4E3A\uFF1A${result.manifest.title}`
     });
   }
   async handleModelCommand(input) {
@@ -6275,6 +6315,31 @@ function readAttachmentWaveform(attachment) {
   ).filter((item) => item !== void 0).slice(0, 96);
 }
 
+// src/config/config.ts
+var defaultLinkConfig = {
+  port: LINK_DEFAULT_PORT,
+  serverBaseUrl: "https://hermes-server.clawpilot.me",
+  relayBaseUrl: "https://hermes-relay.clawpilot.me",
+  appConnectTokenIssuer: "https://hermes-server.clawpilot.me",
+  appConnectTokenAudience: "hermes-link",
+  language: "auto"
+};
+async function loadConfig(paths = resolveRuntimePaths()) {
+  const existing = await readJsonFile(paths.configFile);
+  const language = normalizeConfiguredLanguage(existing?.language);
+  return {
+    ...defaultLinkConfig,
+    ...existing ?? {},
+    language
+  };
+}
+function normalizeConfiguredLanguage(language) {
+  if (language === "zh-CN" || language === "en" || language === "auto") {
+    return language;
+  }
+  return defaultLinkConfig.language;
+}
+
 // src/hermes/session-title.ts
 import { stat as stat6 } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
@@ -6389,12 +6454,19 @@ function isValidProfileName(value) {
 }
 
 // src/conversations/conversation-metadata.ts
+var GENERATED_TITLE_RETRY_DELAYS_MS = [0, 1e3, 3e3];
+var TITLE_GENERATION_SOURCE_MAX_LENGTH = 12e3;
+var SESSION_TITLE_MAX_LENGTH = 120;
+var TITLE_GENERATION_REQUEST_TIMEOUT_MS = 3e4;
 var ConversationMetadataCoordinator = class {
   constructor(deps) {
     this.deps = deps;
   }
   deps;
   async refreshTitleFromHermes(manifest, options = {}) {
+    if (manifest.title_source === "manual" || manifest.title_source === "generated" || manifest.title_source === "temporary_user_message" || manifest.title_source === "temporary_fallback") {
+      return manifest;
+    }
     const snapshot = options.snapshot ?? await this.deps.store.readSnapshot(manifest.id).catch(
       () => createEmptySnapshot()
     );
@@ -6408,7 +6480,8 @@ var ConversationMetadataCoordinator = class {
     }
     const next = {
       ...manifest,
-      title
+      title,
+      title_source: "hermes"
     };
     await this.deps.store.writeManifest(next);
     await this.persistConversationStats(manifest.id, snapshot);
@@ -6421,6 +6494,92 @@ var ConversationMetadataCoordinator = class {
     });
     return { ...next, last_event_seq: event.seq, updated_at: event.created_at };
   }
+  scheduleGeneratedTitleRefresh(conversationId) {
+    for (const delay2 of GENERATED_TITLE_RETRY_DELAYS_MS) {
+      setTimeout(() => {
+        void this.generateTitleFromFirstRound(conversationId).catch(
+          () => void 0
+        );
+      }, delay2);
+    }
+  }
+  async renameConversation(conversationId, title, input) {
+    const normalizedTitle = normalizeConversationTitle(title);
+    if (!normalizedTitle) {
+      throw new LinkHttpError(
+        400,
+        "conversation_title_required",
+        "Conversation title is required"
+      );
+    }
+    const sourceChanged = input.manifest.title_source !== input.source;
+    if (normalizedTitle === input.manifest.title) {
+      if (!sourceChanged) {
+        return {
+          manifest: input.manifest,
+          event: {
+            seq: input.manifest.last_event_seq,
+            type: "conversation.updated",
+            conversation_id: conversationId,
+            created_at: input.manifest.updated_at,
+            payload: {
+              title: normalizedTitle,
+              title_source: input.manifest.title_source ?? normalizeConversationTitleSource(input.manifest.title),
+              hermes_synced: false
+            }
+          },
+          hermesSynced: false
+        };
+      }
+      const hermesSynced2 = await this.syncHermesSessionTitle(
+        input.manifest,
+        input.snapshot,
+        normalizedTitle,
+        input.source
+      );
+      const event2 = await this.deps.appendEvent(conversationId, {
+        type: "conversation.updated",
+        payload: {
+          title: normalizedTitle,
+          title_source: input.source,
+          hermes_synced: hermesSynced2
+        }
+      });
+      const next2 = {
+        ...input.manifest,
+        title_source: input.source,
+        updated_at: event2.created_at,
+        last_event_seq: event2.seq
+      };
+      await this.deps.store.writeManifest(next2);
+      await this.persistConversationStats(conversationId, input.snapshot);
+      return { manifest: next2, event: event2, hermesSynced: hermesSynced2 };
+    }
+    const hermesSynced = await this.syncHermesSessionTitle(
+      input.manifest,
+      input.snapshot,
+      normalizedTitle,
+      input.source
+    );
+    const event = await this.deps.appendEvent(conversationId, {
+      type: "conversation.updated",
+      payload: {
+        title: normalizedTitle,
+        title_source: input.source,
+        hermes_synced: hermesSynced
+      }
+    });
+    const next = {
+      ...input.manifest,
+      title: normalizedTitle,
+      title_source: input.source,
+      updated_at: event.created_at,
+      last_event_seq: event.seq
+    };
+    await this.deps.store.writeManifest(next);
+    await this.persistConversationStats(conversationId, input.snapshot);
+    return { manifest: next, event, hermesSynced };
+  }
   async persistConversationStats(conversationId, snapshot, statsOverride) {
     const manifest = await this.deps.store.readManifest(conversationId).catch(
       () => null
@@ -6467,16 +6626,152 @@ var ConversationMetadataCoordinator = class {
     const next = {
       ...manifest,
       title,
+      title_source: title === TEMPORARY_TITLE_FALLBACK ? "temporary_fallback" : "temporary_user_message",
       updated_at: event.created_at,
       last_event_seq: event.seq
     };
     await this.deps.store.writeManifest(next);
     return next;
   }
+  async generateTitleFromFirstRound(conversationId) {
+    const manifest = await this.deps.store.readManifest(conversationId).catch(
+      () => null
+    );
+    if (!manifest || manifest.status !== "active" || !canAutoGenerateTitle(manifest)) {
+      return;
+    }
+    const snapshot = await this.deps.store.readSnapshot(conversationId).catch(
+      () => createEmptySnapshot()
+    );
+    if (snapshot.messages.filter((message) => message.role === "user").length !== 1) {
+      return;
+    }
+    const dialogue = extractFirstRoundTitleSource(snapshot);
+    if (!dialogue) {
+      return;
+    }
+    const title = await requestGeneratedTitleFromServer({
+      paths: this.deps.paths,
+      sessionKey: manifest.id,
+      userMessage: dialogue.userMessage,
+      assistantMessage: dialogue.assistantMessage,
+      attachmentOnly: dialogue.attachmentOnly
+    }).catch(() => null);
+    if (!title) {
+      return;
+    }
+    const latestManifest = await this.deps.store.readManifest(conversationId).catch(
+      () => null
+    );
+    if (!latestManifest || latestManifest.status !== "active" || !canAutoGenerateTitle(latestManifest)) {
+      return;
+    }
+    await this.renameConversation(conversationId, title, {
+      manifest: latestManifest,
+      snapshot,
+      source: "generated"
+    }).catch(() => void 0);
+  }
+  async syncHermesSessionTitle(manifest, snapshot, title, source) {
+    try {
+      await renameHermesSession(
+        manifest.hermes_session_id,
+        title,
+        latestRuntimeRun(snapshot)?.profile ?? manifest.profile
+      );
+      return true;
+    } catch (error) {
+      if (source === "manual") {
+        throw error;
+      }
+      return false;
+    }
+  }
 };
 function createEmptySnapshot() {
   return { schema_version: 1, messages: [], runs: [] };
 }
+function extractFirstRoundTitleSource(snapshot) {
+  const userMessages = snapshot.messages.filter((message) => message.role === "user").sort((left, right) => Date.parse(left.created_at) - Date.parse(right.created_at));
+  if (userMessages.length !== 1) {
+    return null;
+  }
+  const [user] = userMessages;
+  const userText = truncateTitleSourceText(messageText(user));
+  const assistant = snapshot.messages.filter((message) => message.role === "assistant").filter((message) => Date.parse(message.created_at) >= Date.parse(user.created_at)).sort((left, right) => Date.parse(left.created_at) - Date.parse(right.created_at)).find((message) => messageText(message).length > 0);
+  if (!assistant) {
+    return null;
+  }
+  const assistantText = truncateTitleSourceText(messageText(assistant));
+  if (!assistantText) {
+    return null;
+  }
+  const attachmentOnly = !userText && user.parts.some((part) => part.type !== "text");
+  if (!userText && !attachmentOnly) {
+    return null;
+  }
+  return {
+    userMessage: userText,
+    assistantMessage: assistantText,
+    attachmentOnly
+  };
+}
+async function requestGeneratedTitleFromServer(input) {
+  const config = await loadConfig(input.paths);
+  const response = await fetch(
+    `${config.serverBaseUrl.replace(/\/+$/u, "")}/api/v1/session-titles/generate`,
+    {
+      method: "POST",
+      signal: AbortSignal.timeout(TITLE_GENERATION_REQUEST_TIMEOUT_MS),
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        sessionKey: input.sessionKey,
+        userMessage: input.userMessage,
+        assistantMessage: input.assistantMessage,
+        attachmentOnly: input.attachmentOnly,
+        scenario: input.attachmentOnly ? "attachment-only" : "first-round"
+      })
+    }
+  );
+  if (!response.ok) {
+    return null;
+  }
+  const payload = await response.json().catch(() => null);
+  return normalizeConversationTitle(payload?.title);
+}
+function normalizeConversationTitle(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.replace(/\s+/gu, " ").trim();
+  if (!normalized) {
+    return null;
+  }
+  return Array.from(normalized).slice(0, SESSION_TITLE_MAX_LENGTH).join("");
+}
+function truncateTitleSourceText(value) {
+  return Array.from(value.replace(/\s+/gu, " ").trim()).slice(0, TITLE_GENERATION_SOURCE_MAX_LENGTH).join("");
+}
+function canAutoGenerateTitle(manifest) {
+  switch (manifest.title_source) {
+    case "manual":
+    case "generated":
+    case "hermes":
+      return false;
+    case "default":
+    case "temporary_user_message":
+    case "temporary_fallback":
+      return true;
+    default:
+      return isDefaultConversationTitle(manifest.title);
+  }
+}
+function normalizeConversationTitleSource(title) {
+  return isDefaultConversationTitle(title) ? "default" : "hermes";
+}
 
 // src/conversations/conversation-turns.ts
 import { randomUUID as randomUUID5 } from "crypto";
@@ -8754,7 +9049,7 @@ var ConversationRunLifecycle = class {
       const hermesRun = await createHermesRun(
         {
           input: resolvedInput,
-          instructions: HERMES_LINK_DELIVERY_INSTRUCTIONS,
+          instructions: buildRunInstructions(run),
           session_id: hermesSessionId,
           model: run.model,
           ...conversationHistory.messages.length > 0 ? { conversation_history: conversationHistory.messages } : {}
@@ -9467,6 +9762,16 @@ ${details.join("\n")}` : emptyHermesResponseMessage();
     });
   }
 };
+function buildRunInstructions(run) {
+  return [
+    HERMES_LINK_DELIVERY_INSTRUCTIONS,
+    "",
+    "Current runtime selected by Hermes Link:",
+    `- Model: ${run.model ?? "hermes-agent"}`,
+    `- Provider: ${run.provider ?? "unknown"}`,
+    "If the user asks what model or provider you are currently using, answer from this runtime selection instead of inferring from earlier conversation history."
+  ].join("\n");
+}
 async function readdirWithDirs(directory) {
   return readdir5(directory, { withFileTypes: true }).catch((error) => {
     if (isNodeError10(error, "ENOENT")) {
@@ -9604,6 +9909,7 @@ var ConversationService = class {
       hasActiveRuns: () => this.activeRunControllers.size > 0,
       appendEvent: (conversationId, input) => this.appendEvent(conversationId, input),
       appendCommandResult: (input) => this.orchestration.appendCommandResult(input),
+      renameConversation: (conversationId, title, input) => this.metadata.renameConversation(conversationId, title, input),
       readManifest: (conversationId) => this.store.readManifest(conversationId),
       writeManifest: (manifest) => this.store.writeManifest(manifest)
     });
@@ -9624,7 +9930,7 @@ var ConversationService = class {
       isConversationActive: (conversationId) => this.store.isConversationActive(conversationId),
       writeBlob: (conversationId, input) => this.maintenance.writeBlob(conversationId, input),
       syncCronDeliveries: () => this.syncCronDeliveries(),
-      scheduleTitleRefresh: (conversationId) => this.refreshTitleFromHermesWithRetries(conversationId)
+      scheduleTitleRefresh: (conversationId) => this.metadata.scheduleGeneratedTitleRefresh(conversationId)
     });
     this.orchestration = new ConversationOrchestrationCoordinator({
       paths: this.paths,
@@ -9723,6 +10029,7 @@ var ConversationService = class {
       schema_version: 1,
       kind: "direct",
       title,
+      title_source: isDefaultConversationTitle(title) ? "default" : "hermes",
       status: "active",
       hermes_session_id: `hp_${id}`,
       profile_uid: profile.profileUid,
@@ -9776,6 +10083,10 @@ var ConversationService = class {
       title: "HermesLink \u5B9A\u65F6\u4EFB\u52A1",
       profileName
     });
+    await this.store.writeManifest({
+      ...await this.store.readActiveManifest(created.id),
+      title_source: "manual"
+    });
     return created.id;
   }
   async appendCronDelivery(input) {
@@ -9985,6 +10296,34 @@ var ConversationService = class {
       };
     });
   }
+  async renameConversation(conversationId, title) {
+    return this.withConversationLock(conversationId, async () => {
+      const manifest = await this.store.readActiveManifest(conversationId);
+      const snapshot = await this.store.readSnapshot(conversationId);
+      return this.renameConversationLocked(conversationId, title, {
+        manifest,
+        snapshot,
+        source: "manual"
+      });
+    });
+  }
+  async renameConversationLocked(conversationId, title, input) {
+    const result = await this.metadata.renameConversation(
+      conversationId,
+      title,
+      input
+    );
+    return {
+      conversation_id: conversationId,
+      title: result.manifest.title,
+      conversation: await this.queries.summarizeConversation(
+        result.manifest,
+        input.snapshot
+      ),
+      hermes_synced: result.hermesSynced,
+      last_event_seq: result.event.seq
+    };
+  }
   async listEvents(conversationId, after = 0) {
     return this.queries.listEvents(conversationId, after);
   }
@@ -10096,32 +10435,6 @@ var ConversationService = class {
   async deleteUnreferencedBlob(conversationId, blobId) {
     return this.maintenance.deleteUnreferencedBlob(conversationId, blobId);
   }
-  refreshTitleFromHermesWithRetries(conversationId) {
-    for (const delay2 of [0, 1e3, 3e3]) {
-      setTimeout(() => {
-        void this.withConversationLock(conversationId, async () => {
-          const manifest = await this.store.readManifest(conversationId).catch(
-            () => null
-          );
-          if (!manifest || manifest.status !== "active") {
-            return;
-          }
-          const snapshot = await this.store.readSnapshot(conversationId).catch(
-            () => emptySnapshot2()
-          );
-          await this.refreshTitleFromHermes(manifest, {
-            emitEvent: true,
-            snapshot
-          });
-        }).catch((error) => {
-          void this.logger.warn("conversation_title_sync_failed", {
-            conversation_id: conversationId,
-            error: error instanceof Error ? error.message : String(error)
-          });
-        });
-      }, delay2);
-    }
-  }
   async refreshTitleFromHermes(manifest, options = {}) {
     return this.metadata.refreshTitleFromHermes(manifest, options);
   }
@@ -10166,31 +10479,6 @@ function conversationMatchesProfile(manifest, profileName, profileUid) {
   return normalizeProfileName(manifest.profile_name_snapshot ?? manifest.profile) === profileName;
 }
 
-// src/config/config.ts
-var defaultLinkConfig = {
-  port: LINK_DEFAULT_PORT,
-  serverBaseUrl: "https://hermes-server.clawpilot.me",
-  relayBaseUrl: "https://hermes-relay.clawpilot.me",
-  appConnectTokenIssuer: "https://hermes-server.clawpilot.me",
-  appConnectTokenAudience: "hermes-link",
-  language: "auto"
-};
-async function loadConfig(paths = resolveRuntimePaths()) {
-  const existing = await readJsonFile(paths.configFile);
-  const language = normalizeConfiguredLanguage(existing?.language);
-  return {
-    ...defaultLinkConfig,
-    ...existing ?? {},
-    language
-  };
-}
-function normalizeConfiguredLanguage(language) {
-  if (language === "zh-CN" || language === "en" || language === "auto") {
-    return language;
-  }
-  return defaultLinkConfig.language;
-}
-
 // src/identity/identity.ts
 import { generateKeyPairSync, randomUUID as randomUUID7, sign } from "crypto";
 import { mkdir as mkdir8, chmod } from "fs/promises";
@@ -11058,6 +11346,21 @@ function registerConversationRoutes(router, options) {
       )
     };
   });
+  router.patch("/api/v1/conversations/:conversationId/title", async (ctx) => {
+    await authenticateRequest(ctx, paths);
+    const body = await readJsonBody(ctx.req);
+    const title = readString11(body, "title") ?? readString11(body, "name") ?? readString11(body, "display_name");
+    if (!title) {
+      throw new LinkHttpError(400, "title_required", "title is required");
+    }
+    ctx.body = {
+      ok: true,
+      ...await conversations.renameConversation(
+        ctx.params.conversationId,
+        title
+      )
+    };
+  });
   router.post("/api/v1/conversations/:conversationId/ack", async (ctx) => {
     await authenticateRequest(ctx, paths);
     ctx.body = { ok: true };
@@ -17141,6 +17444,22 @@ async function preparePairing(paths = resolveRuntimePaths()) {
     code: created.code,
     preferred_urls: qrPreferredUrls(routes)
   };
+  const expiresAt = new Date(Date.now() + 10 * 60 * 1e3).toISOString();
+  await writePairingSession(
+    {
+      session_id: created.sessionId,
+      code: created.code,
+      link_id: assigned.linkId,
+      display_name: defaultDisplayName(),
+      local_api_url: `http://127.0.0.1:${config.port}`,
+      server_base_url: config.serverBaseUrl,
+      relay_base_url: relayBaseUrl,
+      preferred_urls: qrPreferredUrls(routes),
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      expires_at: expiresAt
+    },
+    paths
+  );
   return {
     sessionId: created.sessionId,
     code: created.code,
@@ -17150,7 +17469,30 @@ async function preparePairing(paths = resolveRuntimePaths()) {
     displayName: defaultDisplayName(),
     linkId: assigned.linkId,
     routes,
-    qrPayload
+    qrPayload,
+    expiresAt
+  };
+}
+async function writePairingSession(input, paths = resolveRuntimePaths()) {
+  await writeJsonFile(pairingSessionPath(input.session_id, paths), input);
+  return input;
+}
+async function readPairingSession(sessionId, paths = resolveRuntimePaths()) {
+  const record = await readJsonFile(pairingSessionPath(sessionId, paths));
+  if (!record || record.session_id !== sessionId || typeof record.code !== "string" || typeof record.link_id !== "string" || typeof record.display_name !== "string" || typeof record.local_api_url !== "string" || typeof record.server_base_url !== "string" || typeof record.relay_base_url !== "string" || !Array.isArray(record.preferred_urls) || typeof record.created_at !== "string" || typeof record.expires_at !== "string") {
+    return null;
+  }
+  return {
+    session_id: record.session_id,
+    code: record.code,
+    link_id: record.link_id,
+    display_name: record.display_name,
+    local_api_url: record.local_api_url,
+    server_base_url: record.server_base_url,
+    relay_base_url: record.relay_base_url,
+    preferred_urls: record.preferred_urls.filter((value) => typeof value === "string"),
+    created_at: record.created_at,
+    expires_at: record.expires_at
   };
 }
 async function recordPairingClaim(input, paths = resolveRuntimePaths()) {
@@ -17274,6 +17616,9 @@ function defaultDisplayName() {
 function pairingClaimPath(sessionId, paths) {
   return path22.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.claimed.json`);
 }
+function pairingSessionPath(sessionId, paths) {
+  return path22.join(paths.pairingDir, `${Buffer.from(sessionId).toString("base64url")}.json`);
+}
 function qrPreferredUrls(routes) {
   return routes.preferredUrls.filter((url) => !url.includes("/api/v1/relay/links/")).slice(0, 1);
 }
@@ -17326,6 +17671,7 @@ function registerSystemRoutes(router, options) {
         conversation_delete: true,
         conversation_bulk_delete: true,
         conversation_cancel: true,
+        conversation_rename: true,
         blobs: true,
         devices: true,
         device_delete: true,
@@ -17887,6 +18233,435 @@ function writeUpdateSseEvent2(response, status) {
 `);
 }
 
+// src/http/routes/pairing.ts
+import QRCode from "qrcode";
+function registerPairingRoutes(router, options) {
+  const { paths } = options;
+  router.get("/pair", async (ctx) => {
+    const sessionId = readString11(ctx.query, "session_id");
+    if (!sessionId) {
+      throw new LinkHttpError(400, "pairing_session_required", "session_id is required");
+    }
+    const [session, config, identity] = await Promise.all([
+      readPairingSession(sessionId, paths),
+      loadConfig(paths),
+      loadIdentity(paths)
+    ]);
+    if (!session) {
+      throw new LinkHttpError(404, "pairing_session_not_found", "Pairing session was not found");
+    }
+    const state = await readPairingState(sessionId, paths);
+    const page = await renderPairingPage({
+      session,
+      state,
+      version: LINK_VERSION,
+      port: config.port,
+      linkId: identity?.link_id ?? session.link_id
+    });
+    ctx.set("content-type", "text/html; charset=utf-8");
+    ctx.set("cache-control", "no-store");
+    ctx.body = page;
+  });
+  router.get("/api/v1/pairing/session", async (ctx) => {
+    const sessionId = readString11(ctx.query, "session_id");
+    if (!sessionId) {
+      throw new LinkHttpError(400, "pairing_session_required", "session_id is required");
+    }
+    const session = await readPairingSession(sessionId, paths);
+    if (!session) {
+      throw new LinkHttpError(404, "pairing_session_not_found", "Pairing session was not found");
+    }
+    ctx.set("cache-control", "no-store");
+    ctx.body = {
+      ok: true,
+      session: {
+        ...session,
+        claimed: Boolean(await readPairingState(sessionId, paths).then((state) => state.claimed))
+      }
+    };
+  });
+}
+async function readPairingState(sessionId, paths) {
+  const claim = await readPairingClaim(sessionId, paths);
+  const session = await readPairingSession(sessionId, paths);
+  return {
+    claimed: Boolean(claim),
+    claim,
+    expiresAt: session?.expires_at ?? null
+  };
+}
+async function renderPairingPage(input) {
+  const session = input.session;
+  const qrPayload = JSON.stringify({
+    kind: "hermes_link_pairing",
+    version: 1,
+    link_id: session.link_id,
+    display_name: session.display_name,
+    session_id: session.session_id,
+    code: session.code,
+    preferred_urls: session.preferred_urls
+  });
+  const qrSvg = await QRCode.toString(qrPayload, {
+    type: "svg",
+    margin: 1,
+    width: 320,
+    errorCorrectionLevel: "M"
+  });
+  const qrDataUri = `data:image/svg+xml;base64,${Buffer.from(qrSvg).toString("base64")}`;
+  const currentUrl = session.local_api_url.replace(/\/+$/u, "");
+  const linkIdLabel = escapeHtml(input.linkId ?? session.link_id);
+  const expiresLabel = escapeHtml(formatDate(session.expires_at));
+  const statusLabel = input.state.claimed ? "\u5DF2\u5B8C\u6210\u914D\u5BF9" : "\u7B49\u5F85 App \u626B\u7801";
+  const statusHint = input.state.claimed ? "App \u5DF2\u5B8C\u6210\u914D\u5BF9\uFF0C\u8FD9\u4E2A\u9875\u9762\u53EF\u4EE5\u5173\u95ED\u3002" : "\u6253\u5F00 App \u626B\u7801\uFF0C\u6216\u8005\u590D\u5236\u914D\u5BF9\u7801\u624B\u52A8\u8F93\u5165\u3002";
+  return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="color-scheme" content="light dark" />
+  <title>Hermes Link Pairing</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #f4f5f7;
+      --panel: rgba(255, 255, 255, 0.78);
+      --panel-strong: rgba(255, 255, 255, 0.94);
+      --text: #151922;
+      --muted: #5f6673;
+      --line: rgba(21, 25, 34, 0.12);
+      --accent: #2d5cff;
+      --accent-soft: rgba(45, 92, 255, 0.12);
+      --good: #0b8457;
+      --shadow: 0 24px 90px rgba(18, 24, 38, 0.12);
+    }
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #0c1017;
+        --panel: rgba(16, 20, 28, 0.78);
+        --panel-strong: rgba(16, 20, 28, 0.94);
+        --text: #eef2f8;
+        --muted: #9ba4b3;
+        --line: rgba(255, 255, 255, 0.12);
+        --accent: #8ab4ff;
+        --accent-soft: rgba(138, 180, 255, 0.12);
+        --good: #67d7a7;
+        --shadow: 0 24px 90px rgba(0, 0, 0, 0.45);
+      }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      color: var(--text);
+      background: linear-gradient(180deg, var(--bg) 0%, color-mix(in srgb, var(--bg) 88%, var(--accent) 12%) 100%);
+    }
+    .shell {
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      padding: 28px 18px;
+    }
+    .panel {
+      width: min(1040px, 100%);
+      border: 1px solid var(--line);
+      border-radius: 28px;
+      background: var(--panel);
+      box-shadow: var(--shadow);
+      backdrop-filter: blur(18px);
+      overflow: hidden;
+    }
+    .hero {
+      display: grid;
+      grid-template-columns: minmax(0, 1.1fr) minmax(320px, 390px);
+      gap: 0;
+    }
+    .copy {
+      padding: 34px 34px 30px;
+      border-right: 1px solid var(--line);
+    }
+    .eyebrow {
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      padding: 8px 12px;
+      border-radius: 999px;
+      background: var(--accent-soft);
+      color: var(--accent);
+      font-size: 13px;
+      font-weight: 600;
+      letter-spacing: 0;
+    }
+    h1 {
+      margin: 18px 0 12px;
+      font-size: clamp(34px, 4vw, 52px);
+      line-height: 1.02;
+      letter-spacing: 0;
+    }
+    .subtitle {
+      max-width: 42ch;
+      margin: 0;
+      color: var(--muted);
+      font-size: 16px;
+      line-height: 1.7;
+    }
+    .meta-grid {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 14px;
+      margin-top: 26px;
+    }
+    .meta {
+      padding: 16px 16px 15px;
+      border-radius: 18px;
+      background: var(--panel-strong);
+      border: 1px solid var(--line);
+    }
+    .meta-label {
+      display: block;
+      color: var(--muted);
+      font-size: 12px;
+      line-height: 1.4;
+      margin-bottom: 8px;
+    }
+    .meta-value {
+      font-size: 15px;
+      line-height: 1.5;
+      word-break: break-word;
+    }
+    .stack {
+      margin-top: 24px;
+      display: grid;
+      gap: 12px;
+    }
+    .steps {
+      display: grid;
+      gap: 10px;
+      margin-top: 18px;
+    }
+    .step {
+      display: flex;
+      gap: 12px;
+      align-items: flex-start;
+      padding: 14px 16px;
+      border: 1px solid var(--line);
+      border-radius: 18px;
+      background: var(--panel-strong);
+    }
+    .step-badge {
+      flex: none;
+      width: 26px;
+      height: 26px;
+      border-radius: 999px;
+      display: grid;
+      place-items: center;
+      background: var(--accent-soft);
+      color: var(--accent);
+      font-size: 13px;
+      font-weight: 600;
+    }
+    .step-title {
+      font-size: 14px;
+      line-height: 1.45;
+      margin: 0;
+      font-weight: 600;
+    }
+    .step-copy {
+      margin: 3px 0 0;
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.55;
+    }
+    .qr {
+      padding: 26px 26px 30px;
+      background: linear-gradient(180deg, rgba(255,255,255,0.16), rgba(255,255,255,0));
+    }
+    .card {
+      border: 1px solid var(--line);
+      border-radius: 24px;
+      background: var(--panel-strong);
+      padding: 20px;
+    }
+    .status {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 12px;
+      margin-bottom: 18px;
+    }
+    .status-title {
+      margin: 0;
+      font-size: 18px;
+      line-height: 1.3;
+    }
+    .pill {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: 7px 11px;
+      border-radius: 999px;
+      background: rgba(11, 132, 87, 0.12);
+      color: var(--good);
+      font-size: 12px;
+      font-weight: 600;
+      white-space: nowrap;
+    }
+    .qr-frame {
+      display: grid;
+      place-items: center;
+      padding: 18px;
+      border-radius: 24px;
+      background: linear-gradient(180deg, rgba(45, 92, 255, 0.06), rgba(45, 92, 255, 0));
+      border: 1px solid var(--line);
+    }
+    .qr-frame img {
+      width: min(100%, 300px);
+      aspect-ratio: 1;
+      display: block;
+      border-radius: 18px;
+      background: #fff;
+      padding: 14px;
+    }
+    .code {
+      margin-top: 16px;
+      padding: 14px 16px;
+      border-radius: 18px;
+      border: 1px solid var(--line);
+      background: rgba(0, 0, 0, 0.03);
+      font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+      font-size: 22px;
+      letter-spacing: 0.18em;
+      text-align: center;
+      user-select: all;
+    }
+    .footer {
+      display: flex;
+      justify-content: space-between;
+      gap: 18px;
+      flex-wrap: wrap;
+      padding-top: 16px;
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.55;
+    }
+    .hint {
+      margin: 10px 0 0;
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.55;
+    }
+    @media (max-width: 920px) {
+      .hero { grid-template-columns: 1fr; }
+      .copy { border-right: none; border-bottom: 1px solid var(--line); }
+    }
+    @media (max-width: 640px) {
+      .copy, .qr { padding: 22px 18px; }
+      .meta-grid { grid-template-columns: 1fr; }
+      .status { align-items: flex-start; flex-direction: column; }
+      .code { font-size: 18px; letter-spacing: 0.14em; }
+    }
+  </style>
+</head>
+<body>
+  <main class="shell">
+    <section class="panel">
+      <div class="hero">
+        <div class="copy">
+          <span class="eyebrow">Hermes Link \xB7 ${escapeHtml(input.version)}</span>
+          <h1>\u5728 App \u91CC\u5B8C\u6210\u8FD9\u6B21\u914D\u5BF9</h1>
+          <p class="subtitle">\u8FD9\u4E0D\u662F\u4E00\u5F20\u5B64\u96F6\u96F6\u7684\u4E8C\u7EF4\u7801\u3002\u5B83\u540C\u65F6\u7ED9\u4F60\u914D\u5BF9\u72B6\u6001\u3001\u624B\u52A8\u7801\u3001\u6709\u6548\u671F\u548C\u5F53\u524D\u672C\u5730\u5730\u5740\uFF0C\u65B9\u4FBF Windows \u4F20\u7EDF\u63A7\u5236\u53F0\u3001\u8FDC\u7A0B\u7EC8\u7AEF\u548C\u6D4F\u89C8\u5668\u6253\u5F00\u65F6\u90FD\u80FD\u987A\u5229\u5B8C\u6210\u3002</p>
+          <div class="meta-grid">
+            <div class="meta">
+              <span class="meta-label">\u672C\u5730\u5730\u5740</span>
+              <div class="meta-value">${escapeHtml(currentUrl)}</div>
+            </div>
+            <div class="meta">
+              <span class="meta-label">Link ID</span>
+              <div class="meta-value">${linkIdLabel}</div>
+            </div>
+            <div class="meta">
+              <span class="meta-label">\u914D\u5BF9\u7801</span>
+              <div class="meta-value">${escapeHtml(session.code)}</div>
+            </div>
+            <div class="meta">
+              <span class="meta-label">\u8FC7\u671F\u65F6\u95F4</span>
+              <div class="meta-value">${expiresLabel}</div>
+            </div>
+          </div>
+          <div class="stack">
+            <div class="step">
+              <div class="step-badge">1</div>
+              <div>
+                <p class="step-title">\u5728 App \u91CC\u6253\u5F00\u201C\u8FDE\u63A5 Hermes Link\u201D</p>
+                <p class="step-copy">\u5148\u767B\u5F55 HermesPilot \u8D26\u53F7\uFF0C\u518D\u8D70\u626B\u7801\u6216\u624B\u52A8\u7801\u3002\u914D\u5BF9\u6210\u529F\u540E\uFF0CApp \u4F1A\u81EA\u52A8\u5207\u5230\u8FD9\u53F0 Link\u3002</p>
+              </div>
+            </div>
+            <div class="step">
+              <div class="step-badge">2</div>
+              <div>
+                <p class="step-title">\u626B\u4E8C\u7EF4\u7801\uFF0C\u6216\u76F4\u63A5\u8F93\u5165\u914D\u5BF9\u7801</p>
+                <p class="step-copy">\u5982\u679C\u626B\u7801\u4E0D\u65B9\u4FBF\uFF0CApp \u91CC\u4E5F\u53EF\u4EE5\u76F4\u63A5\u8F93\u5165\u8FD9\u4E2A\u9875\u9762\u663E\u793A\u7684\u914D\u5BF9\u7801\u3002</p>
+              </div>
+            </div>
+            <div class="step">
+              <div class="step-badge">3</div>
+              <div>
+                <p class="step-title">\u914D\u5BF9\u6210\u529F\u540E\uFF0C\u8FD9\u4E2A\u9875\u9762\u4F1A\u81EA\u52A8\u53D8\u6210\u5DF2\u5B8C\u6210\u72B6\u6001</p>
+                <p class="step-copy" id="statusHint">${escapeHtml(statusHint)}</p>
+              </div>
+            </div>
+          </div>
+          <p class="hint">\u53EF\u5728\u7EC8\u7AEF\u7EE7\u7EED\u4FDD\u7559\u8FD9\u4E2A\u9875\u9762\uFF0C\u65B9\u4FBF\u7A0D\u540E\u6838\u5BF9\u72B6\u6001\uFF1B\u5982\u679C\u914D\u5BF9\u5DF2\u7ECF\u6210\u529F\uFF0C\u9875\u9762\u4E0D\u4F1A\u518D\u8981\u6C42\u91CD\u65B0\u626B\u7801\u3002</p>
+        </div>
+        <div class="qr">
+          <div class="card">
+            <div class="status">
+              <h2 class="status-title" id="statusTitle">${escapeHtml(statusLabel)}</h2>
+              <span class="pill" id="statusPill">${input.state.claimed ? "\u5DF2\u626B\u7801" : "\u7B49\u5F85\u4E2D"}</span>
+            </div>
+            <div class="qr-frame">
+              <img src="${qrDataUri}" alt="Hermes Link pairing QR code" />
+            </div>
+            <div class="code">${escapeHtml(session.code)}</div>
+            <div class="footer">
+              <span>Local API: ${escapeHtml(currentUrl)}</span>
+              <span>Relay / Server \u4F1A\u540C\u65F6\u51C6\u5907\u53EF\u7528\u8DEF\u7EBF</span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  </main>
+  <script>
+    const sessionId = ${JSON.stringify(session.session_id)};
+    const refresh = async () => {
+      try {
+        const response = await fetch('/api/v1/pairing/session?session_id=' + encodeURIComponent(sessionId), {
+          headers: { accept: 'application/json' },
+        });
+        if (!response.ok) return;
+        const payload = await response.json();
+        if (payload?.session?.claimed) {
+          document.querySelector('#statusPill').textContent = '\u5DF2\u626B\u7801';
+          document.querySelector('#statusTitle').textContent = '\u5DF2\u5B8C\u6210\u914D\u5BF9';
+          document.querySelector('#statusHint').textContent = 'App \u5DF2\u5B8C\u6210\u914D\u5BF9\uFF0C\u8FD9\u4E2A\u9875\u9762\u53EF\u4EE5\u5173\u95ED\u3002';
+        }
+      } catch (_) {}
+    };
+    setInterval(refresh, 1500);
+    refresh();
+  </script>
+</body>
+</html>`;
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function formatDate(value) {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString("zh-CN", { hour12: false });
+}
+
 // src/http/app.ts
 async function createApp(options = {}) {
   const paths = options.paths ?? resolveRuntimePaths();
@@ -17916,6 +18691,7 @@ async function createApp(options = {}) {
     logger,
     onPairingClaimed: options.onPairingClaimed
   });
+  registerPairingRoutes(router, { paths });
   registerHermesUpdateRoutes(router, { paths, logger });
   registerLinkUpdateRoutes(router, { paths, logger });
   registerStatisticsRoutes(router, { paths, logger, conversations });
@@ -17964,4 +18740,4 @@ export {
   daemonLogFile,
   currentCliScriptPath
 };
-//# sourceMappingURL=chunk-4YF43CT4.js.map
+//# sourceMappingURL=chunk-HIQBCPY4.js.map