clawconnect-agent 0.1.11 → 0.1.13

package/dist/hermes/runtime/hermes-runtime-chat.js

@@ -1,94 +1,35 @@
 import { randomUUID } from "crypto";
-import { readFileSync, statSync } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { join } from "path";
 import { spawn } from "child_process";
 import { buildMobileAssistantDeltaPayload, } from "../../core/relay/mobile-chat-run-bridge.js";
 import { buildToolInvocationUpdatedEvent, } from "../../core/relay/timeline-event-builder.js";
 import { forgetHermesSession, getMappedHermesSessionId, rememberHermesSession, } from "../hermes-session-store.js";
-import { extractDeliverablePaths } from "./hermes-runtime-artifacts.js";
-import { runHermesSessionExport } from "./hermes-runtime-sessions.js";
-import { CHAT_TIMEOUT_MS, CLAWCONNECT_MOBILE_BRIDGE_HINT, HERMES_AGENT_LOG_FILE, HERMES_INBOX_DIR, SUBPROCESS_ENV, resolveHermesBin, isHermesCommandDeniedTimeoutLine, isHermesMissingSessionError, runHermes, runHermesPython, sanitizeHermesChatOutput, stripAnsi, stripHermesSessionResumeNotices, } from "./hermes-runtime-process.js";
-import { collectHermesUsageSnapshot, listHermesSessions, readHermesStatusSnapshot } from "./hermes-runtime-usage.js";
-import { compactStringArray, sanitizeFileName, toRecord } from "./hermes-runtime-values.js";
+import { CHAT_TIMEOUT_MS, CLAWCONNECT_MOBILE_BRIDGE_HINT, HERMES_INBOX_DIR, SUBPROCESS_ENV, resolveHermesBin, isHermesCommandDeniedTimeoutLine, isHermesMissingSessionError, runHermes, sanitizeHermesChatOutput, stripAnsi, stripHermesSessionResumeNotices, } from "./hermes-runtime-process.js";
+import { collectHermesUsageSnapshot, listHermesSessions, readCachedHermesStatusSnapshot, readHermesStatusSnapshotAsync, } from "./hermes-runtime-usage.js";
+import { compactStringArray, sanitizeFileName } from "./hermes-runtime-values.js";
+import { detectHermesHistoryCompletion, selectHermesSessionForCompletedChat, } from "./hermes-runtime-history-completion.js";
+import { tryRunHermesApiChat } from "./hermes-runtime-api-client.js";
+import { resolveHermesPreloadedSkillContext } from "./hermes-runtime-preloaded-skills.js";
+import { createHermesToolLogWatcher, hermesToolState, } from "./hermes-runtime-tool-log-watcher.js";
+import { isHermesSlashCommandMessage, runHermesSlashCommand, } from "./hermes-runtime-slash-command.js";
+export { selectHermesSessionForCompletedChat } from "./hermes-runtime-history-completion.js";
+export { parseHermesToolLogLine } from "./hermes-runtime-tool-log-watcher.js";
+export { isHermesSlashCommandMessage } from "./hermes-runtime-slash-command.js";
 const HERMES_ASSISTANT_DELTA_FLUSH_MS = 120;
 const HERMES_ASSISTANT_DELTA_MAX_BYTES = 4096;
 const HERMES_HISTORY_COMPLETION_GRACE_MS = 2_000;
 const HERMES_HISTORY_COMPLETION_POLL_MS = 1_000;
+const HERMES_API_EMPTY_OUTPUT_HISTORY_COMPLETION_TIMEOUT_MS = 12_000;
+const HERMES_API_EMPTY_OUTPUT_HISTORY_COMPLETION_POLL_MS = 500;
+const HERMES_RUNTIME_CONTEXT_CACHE_MAX_AGE_MS = 5 * 60_000;
 const HERMES_COMMAND_DENIED_TIMEOUT_MESSAGE = "Timeout – denying command";
 const hermesChatQueues = new Map();
-const HERMES_SLASH_COMMAND_SCRIPT = String.raw `
-import contextlib
-import io
-import json
-import os
-import sys
-
-from rich.console import Console
-
-import cli as cli_mod
-from cli import HermesCLI
-
-command = os.environ.get("CLAWCONNECT_HERMES_SLASH_COMMAND", "").strip()
-resume = os.environ.get("CLAWCONNECT_HERMES_SLASH_RESUME", "").strip() or None
-if command and not command.startswith("/"):
-    command = "/" + command
-
-with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
-    cli = HermesCLI(model=None, compact=True, resume=resume, verbose=False)
-
-buf = io.StringIO()
-cli.console = Console(file=buf, force_terminal=True, width=120)
-
-def approve_once(prompt=""):
-    if prompt:
-        print(prompt, end="")
-    return "1"
-
-def approve_once_modal(*args, **kwargs):
-    return "once"
-
-try:
-    cli._prompt_text_input = approve_once
-    cli._prompt_text_input_modal = approve_once_modal
-except Exception:
-    pass
-
-old_cprint = getattr(cli_mod, "_cprint", None)
-if old_cprint is not None:
-    cli_mod._cprint = lambda text: print(text)
-
-try:
-    with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
-        keep_going = cli.process_command(command)
-    pending_inputs = []
-    pending_queue = getattr(cli, "_pending_input", None)
-    if pending_queue is not None:
-        while True:
-            try:
-                pending_inputs.append(pending_queue.get_nowait())
-            except Exception:
-                break
-    payload = {
-        "ok": True,
-        "output": buf.getvalue().rstrip(),
-        "sessionId": getattr(cli, "session_id", None),
-        "keepGoing": bool(keep_going),
-        "pendingInputs": pending_inputs,
-    }
-except Exception as exc:
-    payload = {
-        "ok": False,
-        "output": buf.getvalue().rstrip(),
-        "error": str(exc),
-        "sessionId": getattr(cli, "session_id", None),
-    }
-finally:
-    if old_cprint is not None:
-        cli_mod._cprint = old_cprint
-
-sys.stdout.write(json.dumps(payload, ensure_ascii=False))
-`;
+const EMPTY_PRELOADED_SKILL_CONTEXT = {
+    cliArgs: [],
+    requiredToolsets: [],
+    skillNames: [],
+};
 export async function runHermesChat(params, context = {}) {
     const record = params && typeof params === "object" && !Array.isArray(params)
         ? params
@@ -98,19 +39,33 @@ export async function runHermesChat(params, context = {}) {
         ? record.sessionKey.trim()
         : "main";
     if (isHermesSlashCommandMessage(rawMessage)) {
-        return await runSerializedHermesChat(sessionKey, () => (runHermesSlashCommand({ message: rawMessage, sessionKey, hermesSessionId: record.hermesSessionId })));
+        return await runSerializedHermesChat(sessionKey, () => (runHermesSlashCommand({
+            message: rawMessage,
+            sessionKey,
+            hermesSessionId: record.hermesSessionId,
+            runQueuedChat: (queuedMessage, hermesSessionId) => runHermesChat({
+                message: queuedMessage,
+                sessionKey,
+                ...(hermesSessionId ? { hermesSessionId } : {}),
+            }),
+        })));
     }
-    const message = await prepareHermesMessage(rawMessage, record.attachments, sessionKey);
-    if (!message.trim()) {
+    const sourceRunId = typeof context.requestId === "string" && context.requestId.trim().length > 0
+        ? context.requestId.trim()
+        : undefined;
+    const preparationPlan = planHermesChatPreparation(rawMessage);
+    const preparedMessage = await prepareHermesMessage(rawMessage, record.attachments, sessionKey, sourceRunId, preparationPlan);
+    if (!preparedMessage.cliMessage.trim()) {
         throw new Error("message_required");
     }
     return await runSerializedHermesChat(sessionKey, async () => {
         return await runHermesChatPrepared({
             rawMessage,
-            message,
+            preparedMessage,
             sessionKey,
             hermesSessionId: record.hermesSessionId,
             context,
+            preparationPlan,
         });
     });
 }
@@ -135,14 +90,64 @@ async function runHermesChatPrepared(params) {
         : undefined;
     const mappedResume = explicitResume ? undefined : await getMappedHermesSessionId(params.sessionKey);
     let resume = explicitResume ?? mappedResume;
+    const preloadedSkillContext = params.preparationPlan.preloadFileTransferSkill
+        ? await resolveHermesPreloadedSkillContext({ forceFileTransfer: true })
+        : EMPTY_PRELOADED_SKILL_CONTEXT;
+    try {
+        const apiChat = await tryRunHermesApiChat({
+            message: params.preparedMessage.apiMessage,
+            instructions: params.preparedMessage.apiInstructions,
+            sessionKey: params.sessionKey,
+            resume,
+            preloadedSkillNames: preloadedSkillContext.skillNames,
+            requiredToolsets: preloadedSkillContext.requiredToolsets,
+            context: params.context,
+        });
+        if (apiChat) {
+            const recoveredOutput = await recoverEmptyHermesApiOutputFromHistory({
+                output: apiChat.output,
+                hermesSessionId: apiChat.hermesSessionId,
+                sessionKey: params.sessionKey,
+                userMessage: params.rawMessage,
+                abortSignal: params.context.abortSignal,
+            });
+            return recoveredOutput ? { ...apiChat, output: recoveredOutput } : apiChat;
+        }
+    }
+    catch (error) {
+        if (!mappedResume || !isHermesMissingSessionError(error)) {
+            throw error;
+        }
+        await forgetHermesSession(params.sessionKey, mappedResume);
+        resume = undefined;
+        const retryApiChat = await tryRunHermesApiChat({
+            message: params.preparedMessage.apiMessage,
+            instructions: params.preparedMessage.apiInstructions,
+            sessionKey: params.sessionKey,
+            preloadedSkillNames: preloadedSkillContext.skillNames,
+            requiredToolsets: preloadedSkillContext.requiredToolsets,
+            context: params.context,
+        });
+        if (retryApiChat) {
+            const recoveredOutput = await recoverEmptyHermesApiOutputFromHistory({
+                output: retryApiChat.output,
+                hermesSessionId: retryApiChat.hermesSessionId,
+                sessionKey: params.sessionKey,
+                userMessage: params.rawMessage,
+                abortSignal: params.context.abortSignal,
+            });
+            return recoveredOutput ? { ...retryApiChat, output: recoveredOutput } : retryApiChat;
+        }
+    }
     const beforeSessions = await listHermesSessions();
     let rawOutput;
     try {
         rawOutput = await runHermesChatOnce({
-            message: params.message,
+            message: params.preparedMessage.cliMessage,
             sessionKey: params.sessionKey,
             resume,
             context: params.context,
+            preloadedSkillArgs: preloadedSkillContext.cliArgs,
             historyCompletion: () => detectHermesHistoryCompletion({
                 beforeSessions,
                 resume,
@@ -158,9 +163,10 @@ async function runHermesChatPrepared(params) {
         await forgetHermesSession(params.sessionKey, mappedResume);
         resume = undefined;
         rawOutput = await runHermesChatOnce({
-            message: params.message,
+            message: params.preparedMessage.cliMessage,
             sessionKey: params.sessionKey,
             context: params.context,
+            preloadedSkillArgs: preloadedSkillContext.cliArgs,
             historyCompletion: () => detectHermesHistoryCompletion({
                 beforeSessions,
                 sessionKey: params.sessionKey,
@@ -180,257 +186,72 @@ async function runHermesChatPrepared(params) {
     }
     const usage = mappedSession?.hermesSessionId
         ? await collectHermesUsageSnapshot(mappedSession.hermesSessionId)
-        : readHermesStatusSnapshot();
+        : await readHermesStatusSnapshotAsync();
     return {
         output,
         sessionKey: params.sessionKey,
-        artifactPaths: extractDeliverablePaths(output, { userMessage: params.rawMessage }),
+        artifactPaths: [],
         usage,
     };
 }
-async function runHermesChatOnce(params) {
-    const args = ["chat", "--query", params.message, "--quiet", "--source", "pocketclaw", "--yolo"];
-    if (params.resume) {
-        args.push("--resume", params.resume);
-    }
-    return params.context.publishEvent
-        ? await runHermesChatStreaming(args, params.sessionKey, params.context, params.historyCompletion)
-        : runHermes(args, CHAT_TIMEOUT_MS);
-}
-async function detectHermesHistoryCompletion(params) {
-    const sessions = await listHermesSessions();
-    const mappedSession = selectHermesSessionForCompletedChat(sessions, {
-        beforeSessions: params.beforeSessions,
-        resume: params.resume,
-        userMessage: params.userMessage,
-    });
-    if (!mappedSession?.hermesSessionId) {
-        return undefined;
-    }
-    const exportResult = await runHermesSessionExport({
-        sessionKey: params.sessionKey,
-        hermesSessionId: mappedSession.hermesSessionId,
-        output: "-",
-    });
-    if (!exportResult.ok) {
+async function recoverEmptyHermesApiOutputFromHistory(params) {
+    if (sanitizeHermesChatOutput(params.output).trim()) {
         return undefined;
     }
-    return latestAssistantReplyFromHermesExport(exportResult.payload, params.userMessage);
-}
-function latestAssistantReplyFromHermesExport(payload, userMessage) {
-    const output = toRecord(payload).output;
-    const parsed = parseHermesChatExportOutput(output);
-    const record = toRecord(parsed);
-    const rawMessages = Array.isArray(record.messages)
-        ? record.messages
-        : Array.isArray(record.items)
-            ? record.items
-            : Array.isArray(parsed)
-                ? parsed
-                : [];
-    if (rawMessages.length === 0) {
-        return undefined;
-    }
-    const normalizedUser = normalizeSessionSelectionText(userMessage);
-    if (!normalizedUser) {
+    if (!params.hermesSessionId?.trim()) {
         return undefined;
     }
-    let latestUserIndex = -1;
-    let latestUserMatchesCurrentRequest = false;
-    for (let index = rawMessages.length - 1; index >= 0; index -= 1) {
-        const message = toRecord(rawMessages[index]);
-        if (normalizeHistoryRoleValue(message.role) !== "user") {
-            continue;
+    const deadline = Date.now() + HERMES_API_EMPTY_OUTPUT_HISTORY_COMPLETION_TIMEOUT_MS;
+    while (Date.now() <= deadline) {
+        if (params.abortSignal?.aborted) {
+            throw new Error("hermes_chat_aborted");
         }
-        const text = normalizeSessionSelectionText(extractHermesHistoryText(message));
-        latestUserIndex = index;
-        latestUserMatchesCurrentRequest = text.length > 0
-            && (text.includes(normalizedUser) || normalizedUser.includes(text));
-        break;
-    }
-    if (latestUserIndex < 0 || !latestUserMatchesCurrentRequest) {
-        return undefined;
-    }
-    for (let index = rawMessages.length - 1; index >= latestUserIndex + 1; index -= 1) {
-        const message = toRecord(rawMessages[index]);
-        if (normalizeHistoryRoleValue(message.role) !== "assistant") {
-            continue;
+        const detectedOutput = await detectHermesHistoryCompletion({
+            beforeSessions: [],
+            resume: params.hermesSessionId,
+            sessionKey: params.sessionKey,
+            userMessage: params.userMessage,
+        });
+        if (detectedOutput) {
+            return detectedOutput;
         }
-        const text = sanitizeHermesChatOutput(extractHermesHistoryText(message)).trim();
-        if (text) {
-            return text;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            break;
         }
+        await sleep(Math.min(HERMES_API_EMPTY_OUTPUT_HISTORY_COMPLETION_POLL_MS, remainingMs));
     }
     return undefined;
 }
-function parseHermesChatExportOutput(value) {
-    if (typeof value !== "string") {
-        return value;
-    }
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return {};
-    }
-    try {
-        return JSON.parse(trimmed);
-    }
-    catch {
-        const firstObjectBrace = trimmed.indexOf("{");
-        const lastObjectBrace = trimmed.lastIndexOf("}");
-        if (firstObjectBrace >= 0 && lastObjectBrace > firstObjectBrace) {
-            try {
-                return JSON.parse(trimmed.slice(firstObjectBrace, lastObjectBrace + 1));
-            }
-            catch {
-                return {};
-            }
-        }
-        return {};
-    }
-}
-function normalizeHistoryRoleValue(value) {
-    return typeof value === "string" ? value.trim().toLowerCase().replace("_", "") : "";
-}
-function extractHermesHistoryText(record) {
-    const content = record.content;
-    if (typeof content === "string") {
-        return content;
-    }
-    if (Array.isArray(content)) {
-        return content
-            .flatMap((block) => {
-            const blockRecord = toRecord(block);
-            const type = typeof blockRecord.type === "string" ? blockRecord.type.trim().toLowerCase() : "";
-            if (type && type !== "text" && type !== "output_text" && type !== "input_text") {
-                return [];
-            }
-            return typeof blockRecord.text === "string" ? [blockRecord.text] : [];
-        })
-            .filter((text) => text.trim().length > 0)
-            .join("\n\n");
-    }
-    for (const key of ["text", "message", "output"]) {
-        const value = record[key];
-        if (typeof value === "string" && value.trim()) {
-            return value;
-        }
-    }
-    return "";
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
 }
-export function isHermesSlashCommandMessage(message) {
-    return /^\/[A-Za-z0-9][\w-]*(?:\s|$)/.test(message.trim());
-}
-export function selectHermesSessionForCompletedChat(sessions, options = {}) {
-    const resume = options.resume?.trim();
-    if (resume) {
-        return sessions.find((session) => session.hermesSessionId === resume);
-    }
-    const beforeIds = new Set((options.beforeSessions ?? []).map((session) => session.hermesSessionId));
-    const newSessions = sessions.filter((session) => !beforeIds.has(session.hermesSessionId));
-    if (newSessions.length === 0) {
-        return sessions[0];
-    }
-    const normalizedUserMessage = normalizeSessionSelectionText(options.userMessage);
-    if (normalizedUserMessage) {
-        const matched = newSessions.find((session) => {
-            const haystack = normalizeSessionSelectionText([
-                session.displayName,
-                session.derivedTitle,
-                session.label,
-            ].filter(Boolean).join(" "));
-            return haystack.length > 0
-                && (haystack.includes(normalizedUserMessage) || normalizedUserMessage.includes(haystack));
-        });
-        if (matched) {
-            return matched;
-        }
-    }
-    return newSessions[0];
-}
-function normalizeSessionSelectionText(value) {
-    return value
-        ?.replace(/\[Hermes runtime context][\s\S]*$/i, "")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, 80)
-        .toLowerCase() ?? "";
-}
-export async function runHermesSlashCommand(params) {
-    const command = params.message.trim();
-    const resume = typeof params.hermesSessionId === "string" && params.hermesSessionId.trim().length > 0
-        ? params.hermesSessionId.trim()
-        : await getMappedHermesSessionId(params.sessionKey);
-    const raw = runHermesPython(HERMES_SLASH_COMMAND_SCRIPT, {
-        CLAWCONNECT_HERMES_SLASH_COMMAND: command,
-        CLAWCONNECT_HERMES_SLASH_RESUME: resume ?? "",
-    });
-    const payload = parseHermesSlashCommandPayload(raw);
-    const output = sanitizeHermesChatOutput(payload.output ?? "").trim();
-    if (!payload.ok) {
-        const message = [output, payload.error].filter(Boolean).join("\n").trim() || "hermes_slash_command_failed";
-        throw new Error(message);
-    }
-    const sessionId = typeof payload.sessionId === "string" && payload.sessionId.trim().length > 0
-        ? payload.sessionId.trim()
-        : undefined;
-    if (sessionId) {
-        await rememberHermesSession(params.sessionKey, {
-            sessionKey: params.sessionKey,
-            hermesSessionId: sessionId,
-            displayName: sessionId,
-            label: command,
-            lastActivityAt: new Date().toISOString(),
-            kind: "hermes",
-        });
-    }
-    if (/^\/(?:new|reset)\b/i.test(command) && resume && sessionId && sessionId !== resume) {
-        await forgetHermesSession(resume, resume);
-    }
-    if (payload.pendingInputs && payload.pendingInputs.length > 0) {
-        const queuedMessage = payload.pendingInputs.join("\n\n").trim();
-        if (queuedMessage) {
-            const queued = await runHermesChat({
-                message: queuedMessage,
-                sessionKey: params.sessionKey,
-                ...(sessionId ? { hermesSessionId: sessionId } : {}),
-            });
-            return {
-                ...queued,
-                output: [output, queued.output].filter((part) => part && part !== "(no output)").join("\n\n") || queued.output,
-            };
-        }
-    }
-    const usage = await collectHermesUsageSnapshot(sessionId);
-    return {
-        output: output || "(no output)",
-        sessionKey: params.sessionKey,
-        artifactPaths: [],
-        usage,
-    };
-}
-function parseHermesSlashCommandPayload(raw) {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("invalid_hermes_slash_command_payload");
+async function runHermesChatOnce(params) {
+    const args = [
+        "chat",
+        "--query",
+        params.message,
+        "--quiet",
+        "--source",
+        "pocketclaw",
+        ...(params.preloadedSkillArgs ?? []),
+        "--yolo",
+    ];
+    if (params.resume) {
+        args.push("--resume", params.resume);
     }
-    const record = parsed;
-    return {
-        ok: record.ok === true,
-        output: typeof record.output === "string" ? record.output : undefined,
-        error: typeof record.error === "string" ? record.error : undefined,
-        sessionId: typeof record.sessionId === "string" ? record.sessionId : undefined,
-        pendingInputs: Array.isArray(record.pendingInputs)
-            ? record.pendingInputs.filter((value) => typeof value === "string" && value.trim().length > 0)
-            : undefined,
-    };
+    const runId = params.context.requestId ?? `hermes-${Date.now()}`;
+    const env = hermesChatSubprocessEnv(runId, params.sessionKey);
+    return params.context.publishEvent
+        ? await runHermesChatStreaming(args, params.sessionKey, params.context, runId, env, params.historyCompletion)
+        : runHermes(args, CHAT_TIMEOUT_MS, env);
 }
-async function runHermesChatStreaming(args, sessionKey, context, historyCompletion) {
+async function runHermesChatStreaming(args, sessionKey, context, runId, env, historyCompletion) {
     const child = spawn(resolveHermesBin(), args, {
-        env: SUBPROCESS_ENV,
+        env,
         stdio: ["ignore", "pipe", "pipe"],
         windowsHide: true,
     });
-    const runId = context.requestId ?? `hermes-${Date.now()}`;
     let output = "";
     let stderr = "";
     let seq = 0;
@@ -552,7 +373,8 @@ async function runHermesChatStreaming(args, sessionKey, context, historyCompleti
                     sessionKey,
                     seq: seq += 1,
                     timestampMs,
-                    delta,
+                    // canonical message.part.delta 是同一 part 的绝对状态；Hermes CLI stdout 这里 flush 的只是增量片段。
+                    delta: output,
                 }),
             });
         }
@@ -797,125 +619,27 @@ export function buildHermesAssistantDeltaPayload(params) {
         includeTimelineEvents: true,
     });
 }
-function hermesToolState(event) {
-    if (event.phase === "completed") {
-        return "success";
-    }
-    if (event.phase === "failed") {
-        return "failed";
-    }
-    return "streaming_output";
-}
-function createHermesToolLogWatcher(onEvent) {
-    let offset = 0;
-    let timer;
-    try {
-        offset = statSync(HERMES_AGENT_LOG_FILE).size;
-    }
-    catch {
-        offset = 0;
-    }
-    const poll = () => {
-        let content = "";
-        try {
-            const bytes = readFileSync(HERMES_AGENT_LOG_FILE);
-            if (bytes.length < offset) {
-                offset = 0;
-            }
-            if (bytes.length === offset) {
-                return;
-            }
-            content = bytes.subarray(offset).toString("utf8");
-            offset = bytes.length;
-        }
-        catch {
-            return;
-        }
-        for (const line of content.split(/\r?\n/)) {
-            const event = parseHermesToolLogLine(line);
-            if (event) {
-                onEvent(event);
-            }
-        }
-    };
+function hermesChatSubprocessEnv(runId, sessionKey) {
     return {
-        start: () => {
-            if (timer) {
-                return;
-            }
-            timer = setInterval(poll, 250);
-            timer.unref?.();
-        },
-        stop: () => {
-            poll();
-            if (timer) {
-                clearInterval(timer);
-                timer = undefined;
-            }
-        },
+        ...SUBPROCESS_ENV,
+        CLAWCONNECT_SOURCE_RUN_ID: runId,
+        CLAWCONNECT_SESSION_KEY: sessionKey,
+        CLAWCONNECT_CHAT_SESSION_KEY: sessionKey,
     };
 }
-export function parseHermesToolLogLine(line) {
-    const clean = stripAnsi(line).trim();
-    if (!clean) {
-        return null;
-    }
-    const executor = clean.match(/\bagent\.tool_executor:\s*tool\s+([A-Za-z0-9_.-]+)\s+(.+)$/i);
-    if (executor) {
-        const toolName = normalizeHermesToolName(executor[1] ?? "tool");
-        const detail = (executor[2] ?? "").trim();
-        if (/\b(?:running|started|executing|start)\b/i.test(detail)) {
-            return {
-                toolName,
-                phase: "streaming",
-                text: `${toolName} ${detail}`.trim(),
-                isError: false,
-            };
-        }
-        const failed = /\b(?:failed|error|errored|denied|aborted)\b/i.test(detail);
-        return {
-            toolName,
-            phase: failed ? "failed" : "completed",
-            text: `${toolName} ${detail}`.trim(),
-            isError: failed,
-        };
-    }
-    const toolLogger = clean.match(/\btools\.([A-Za-z0-9_.-]+):\s*(.+)$/i);
-    if (!toolLogger) {
-        return null;
-    }
-    const loggerName = toolLogger[1] ?? "tool";
-    if (!/(?:_tool|_tools)$/i.test(loggerName)) {
-        return null;
-    }
-    let toolName = normalizeHermesToolName(loggerName);
-    let detail = (toolLogger[2] ?? "").trim();
-    if (/\b(?:Shutting down \d+ remaining sandbox(?:\(es\))?|Manually cleaned up environment|Cleaned \d+ environments?)\b/i.test(detail)) {
-        return null;
-    }
-    const nestedTool = detail.match(/^([A-Za-z0-9_.-]+):\s*(.+)$/);
-    if (nestedTool) {
-        toolName = normalizeHermesToolName(nestedTool[1] ?? toolName);
-        detail = (nestedTool[2] ?? "").trim();
-    }
-    if (!detail) {
-        return null;
+const CLAWCONNECT_MOBILE_TURN_INSTRUCTION = "Use [ClawConnect mobile turn] metadata only for ClawConnect file-transfer attribution and message identity. Do not mention it in the answer.";
+function buildClawConnectMobileTurnMetadata(sourceRunId, sessionKey) {
+    if (!sourceRunId) {
+        return undefined;
     }
-    return {
-        toolName,
-        phase: "streaming",
-        text: `${toolName}: ${detail}`,
-    };
-}
-function normalizeHermesToolName(rawName) {
-    const normalized = rawName
-        .trim()
-        .replace(/[^A-Za-z0-9_.-]+/g, "_")
-        .replace(/_tools$/i, "")
-        .replace(/_tool$/i, "");
-    return normalized || "tool";
+    // 这个块是 ClawConnect 和 Hermes history 的稳定身份合同；客户端展示时会剥离它。
+    return [
+        "[ClawConnect mobile turn]",
+        `sourceRunId: ${sourceRunId}`,
+        `sessionKey: ${sessionKey}`,
+    ].join("\n");
 }
-async function prepareHermesMessage(message, attachments, sessionKey) {
+async function prepareHermesMessage(message, attachments, sessionKey, sourceRunId, preparationPlan = planHermesChatPreparation(message)) {
     const refs = [];
     if (Array.isArray(attachments)) {
         const safeSession = sessionKey.replace(/[^\w.-]/g, "_") || "main";
@@ -938,16 +662,61 @@ async function prepareHermesMessage(message, attachments, sessionKey) {
             refs.push(`[file attached: ${filePath} (${mimeType})]`);
         }
     }
-    const sections = [message.trim()];
+    const userSections = [message.trim()];
     if (refs.length > 0) {
-        sections.push(refs.join("\n"));
-    }
-    const runtimeHint = buildHermesRuntimeContextHint(readHermesStatusSnapshot());
-    if (runtimeHint) {
-        sections.push(runtimeHint);
-    }
-    sections.push(CLAWCONNECT_MOBILE_BRIDGE_HINT);
-    return sections.filter(Boolean).join("\n\n").trim();
+        userSections.push(refs.join("\n"));
+    }
+    const runtimeHint = buildHermesRuntimeContextHint(readCachedHermesStatusSnapshot(HERMES_RUNTIME_CONTEXT_CACHE_MAX_AGE_MS));
+    const turnMetadata = buildClawConnectMobileTurnMetadata(sourceRunId, sessionKey);
+    const apiMessageSections = [...userSections];
+    if (turnMetadata) {
+        apiMessageSections.push(turnMetadata);
+    }
+    const apiInstructionSections = [
+        runtimeHint,
+        CLAWCONNECT_MOBILE_BRIDGE_HINT,
+        turnMetadata ? CLAWCONNECT_MOBILE_TURN_INSTRUCTION : undefined,
+    ];
+    const cliMessageSections = [
+        ...userSections,
+        runtimeHint,
+        CLAWCONNECT_MOBILE_BRIDGE_HINT,
+        turnMetadata
+            ? [turnMetadata, CLAWCONNECT_MOBILE_TURN_INSTRUCTION].join("\n")
+            : undefined,
+    ];
+    return {
+        apiMessage: apiMessageSections.filter(Boolean).join("\n\n").trim(),
+        apiInstructions: apiInstructionSections.filter(Boolean).join("\n\n").trim() || undefined,
+        cliMessage: cliMessageSections.filter(Boolean).join("\n\n").trim(),
+    };
+}
+function planHermesChatPreparation(message) {
+    return {
+        preloadFileTransferSkill: shouldPreloadHermesFileTransferSkill(message),
+    };
+}
+function shouldPreloadHermesFileTransferSkill(message) {
+    const text = message.trim();
+    const lower = text.toLowerCase();
+    if (!text) {
+        return false;
+    }
+    if (/\bfile-transfer\b|clawconnect\s+send-file/.test(lower)) {
+        return true;
+    }
+    const pathOrExtension = /(?:^|\s|["'“”‘’])(?:~|\/|[a-z]:\\)|\.(?:png|jpe?g|gif|webp|heic|pdf|docx?|xlsx?|pptx?|zip|txt|md)\b/i.test(text);
+    const englishSend = /\b(send|transfer|upload|attach|share|copy)\b/i.test(text);
+    const englishFile = /\b(file|image|photo|picture|screenshot|document|attachment)\b/i.test(text) || pathOrExtension;
+    const englishTarget = /\b(phone|iphone|mobile|clawlink|this device|me)\b/i.test(text);
+    if (englishSend && englishFile && englishTarget) {
+        return true;
+    }
+    const chineseSend = /发送|发给|发到|发过来|传到|传给|传输|上传|分享|转发|给我|发/.test(text);
+    const chineseFile = /文件|图片|照片|截图|文档|附件|桌面|本机|路径|微信图片/.test(text) || pathOrExtension;
+    const chineseTarget = /手机|移动端|这台|给我|发过来|iPhone|ClawLink/i.test(text);
+    // 文件传输技能会触发 Hermes CLI 的 skills list；普通文本必须不走这条慢路径。
+    return chineseSend && chineseFile && chineseTarget;
 }
 export function buildHermesRuntimeContextHint(snapshot) {
     const details = compactStringArray([