nolo-cli 0.1.26 → 0.1.29

package/server/handlers/agentRun/toolExecutor.ts

@@ -0,0 +1,2909 @@
+// packages/server/handlers/agentRun/toolExecutor.ts
+//
+// 服务端 tool 执行器。
+// 直接调用本机 API（无需 Redux），结果以字符串返回给 LLM。
+// 不持久化任何内容。
+
+import { markdownToSlate } from "../../../create/editor/transforms/markdownToSlate";
+import { slateToRenderMarkdown } from "../../../create/editor/transforms/slateToRenderMarkdown";
+import { extractMentionsFromSlate } from "../../../create/editor/utils/slateUtils";
+import { WEB_AUTH_TOKEN_COOKIE } from "../../../auth/tokenCookie";
+import { DataType } from "../../../create/types";
+import { NOLO_CLUSTER_SERVERS } from "../../../database/config";
+import { createAgentKey, createKey, createUserKey } from "../../../database/keys";
+import { ulid } from "../../../database/utils/ulid";
+import { saveBufferAsFile } from "../../../database/server/fileService";
+import { shareKey } from "../../../share/keys";
+import { DEFAULT_MODEL, getApiEndpoint } from "../../../ai/llm/providers";
+import type { AssistantToolCall, ToolExecutionContext } from "./types";
+import {
+    buildSkillDocMarkdown,
+    resolvePageSkillMetadata,
+    parseSkillDocProtocol,
+    parseExternalSkillMarkdown,
+    type SkillDocConfig,
+} from "../../../ai/skills/skillDocProtocol";
+import {
+    buildSkillDocFromArgs,
+    type CreateSkillDocArgs,
+} from "../../../ai/skills/skillDocBuilder";
+import {
+    diagnoseSkillDocument,
+    evaluateSkillDocument,
+} from "../../../ai/skills/skillDiagnostics";
+import {
+    buildSkillAgentRecord,
+    type CreateSkillAgentToolArgs,
+} from "../../../ai/tools/agent/skillAgentPreset";
+import {
+    prepareAgentDraftToolFunc,
+    type PrepareAgentDraftToolArgs,
+} from "../../../ai/tools/agent/prepareAgentDraftTool";
+import type { CreateAgentToolArgs } from "../../../ai/tools/agent/createAgentTool";
+import {
+    guardDestructiveAction,
+    guardPublicTableShare,
+    guardKnowledgeCapture,
+    isDestructiveShellCommand,
+    guardWorkspaceRead,
+    recordKnowledgeCapture,
+    recordWorkspaceRead,
+} from "./toolPolicyGuards";
+import { buildReadDocResult } from "../../../ai/tools/readDocTool";
+import { buildSkillFollowupResult } from "../../../ai/tools/skillFollowup";
+import { runZiweiChart } from "../../../ai/tools/ziweiChartTool";
+import { evaluateSmallVisualEditGuard } from "../../../ai/tools/appEditGuard";
+import {
+    analyzeAppStyleSystem,
+    buildAppStyleSystemHint,
+} from "../../../ai/tools/appReadSnapshot";
+import {
+    calculateParallelBranchPricing,
+    normalizeBudgetCredits,
+    summarizeParallelBudget,
+    summarizeParallelCosts,
+} from "../../../ai/tools/agent/parallelBudget";
+import {
+    extractAgentRuntimeServerBase,
+    normalizeServerOrigin,
+} from "../../../ai/agent/runtimeServerBase";
+import { extractEmailVerificationArtifacts } from "../../../ai/tools/emailTools";
+import { convertMarxistsBookToOfflineHtml } from "../../../ai/tools/marxistsOfflineBook";
+import { formatMarxistsOfflineBookDisplayData } from "../../../ai/tools/convertMarxistsBookTool";
+import {
+    formatJdProductDisplayData,
+    getKnownJdProductFallback,
+    hasSparseJdSpecifications,
+    isIncompleteProductData,
+    jdProductScraperFunc,
+    mergeJdProductData,
+    parseJdBrowserExtractedData,
+} from "../../../ai/tools/jdProductScraperTool";
+import {
+    buildDialogMessageSearchResults,
+    clampDialogSearchNumber,
+    normalizeDialogSearchText,
+} from "../../../ai/tools/dialogMessageSearch";
+import serverDb from "../../../database/server/db";
+import { createSpaceKey } from "../../../create/space/spaceKeys";
+import {
+    buildDeleteSpacesPreview,
+    filterSpaceDeletionCandidates,
+    resolveConfirmedSpaceDeletionTargets,
+    type SpaceMembershipLike,
+    type SpaceRecordLike,
+} from "../../../ai/tools/deleteSpacesToolModel";
+import { canonicalizeToolName } from "../../../ai/tools/toolNameAliases";
+import {
+    runCompleteDialogGoalTool,
+    runCreateDialogGoalTool,
+    runCreateScheduledTaskTool,
+    runGetDialogGoalTool,
+    runNotifyUserTool,
+    runQueryModelUsageTool,
+} from "./modelUsageToolHandlers";
+import { runTaskRunTool } from "./taskRunToolHandler";
+import { projectDialogActivityToSubjectRows } from "./tableActivityProjection";
+import { resolveExistingDialogRef } from "./dialogLookup";
+
+const APP_DEPLOY_POLL_INTERVAL_MS = 250;
+const APP_DEPLOY_POLL_TIMEOUT_MS = 60_000;
+const DEFAULT_PARALLEL_AGENT_BRANCH_TIMEOUT_MS = 10 * 60 * 1000;
+const configuredParallelAgentBranchTimeoutMs = Number(
+    process.env.PARALLEL_AGENT_BRANCH_TIMEOUT_MS,
+);
+const PARALLEL_AGENT_BRANCH_TIMEOUT_MS =
+    Number.isFinite(configuredParallelAgentBranchTimeoutMs) &&
+    configuredParallelAgentBranchTimeoutMs > 0
+        ? configuredParallelAgentBranchTimeoutMs
+        : DEFAULT_PARALLEL_AGENT_BRANCH_TIMEOUT_MS;
+const IMAGE_GENERATION_TOOL_NAMES = new Set([
+    "geminiFlashImage",
+    "geminiProImagePreview",
+    "openAIGptImageGenerate",
+    "openAIGptImageEdit",
+    "openAIGptImage",
+]);
+const FEEDBACK_AGENT_ID = "01NOLOFEEDBACKA000000000R1";
+
+const trimString = (value: unknown): string =>
+    typeof value === "string" ? value.trim() : "";
+
+const normalizeStringArray = (value: unknown): string[] => {
+    if (Array.isArray(value)) {
+        return value.map(trimString).filter(Boolean);
+    }
+    if (typeof value === "string") {
+        return value.split(",").map((item) => item.trim()).filter(Boolean);
+    }
+    return [];
+};
+
+const normalizeAgentReferencesForServerCreate = (value: unknown) =>
+    Array.isArray(value)
+        ? value
+            .filter((item): item is Record<string, unknown> =>
+                !!item && typeof item === "object" && !Array.isArray(item)
+            )
+            .map((item) => ({
+                dbKey: trimString(item.dbKey),
+                title: trimString(item.title),
+                type: trimString(item.type) || "knowledge",
+            }))
+            .filter((item) => item.dbKey)
+        : [];
+
+const normalizeRunnableAgentModel = (provider: string, model: string) => {
+    try {
+        getApiEndpoint({ provider, model } as any);
+        return { provider, model };
+    } catch (error) {
+        if (
+            error instanceof Error &&
+            (error.message.includes("Unsupported provider") ||
+                error.message.includes("Custom provider URL is required"))
+        ) {
+            return {
+                provider: DEFAULT_MODEL.provider,
+                model: DEFAULT_MODEL.name,
+            };
+        }
+        throw error;
+    }
+};
+
+const buildServerCreatedAgentRecord = (
+    userId: string,
+    args: CreateAgentToolArgs,
+    currentSpaceId?: string | null,
+) => {
+    const name = trimString(args.name);
+    const model = trimString(args.model);
+    const provider = trimString(args.provider);
+    if (!name) throw new Error("createAgent: name is required");
+    if (!model) throw new Error("createAgent: model is required");
+    if (!provider) throw new Error("createAgent: provider is required");
+    const runnableModel = normalizeRunnableAgentModel(provider, model);
+
+    const now = Date.now();
+    const id = ulid();
+    const greeting =
+        typeof args.greeting === "string"
+            ? args.greeting.trim()
+            : args.greeting && typeof args.greeting === "object"
+                ? args.greeting
+                : undefined;
+    return {
+        id,
+        type: DataType.AGENT,
+        userId,
+        createdAt: now,
+        updatedAt: now,
+        dialogCount: 0,
+        messageCount: 0,
+        tokenCount: 0,
+        spaceId: currentSpaceId || undefined,
+        name,
+        model: runnableModel.model,
+        provider: runnableModel.provider,
+        prompt: trimString(args.prompt),
+        introduction: trimString(args.introduction),
+        ...(greeting ? { greeting } : {}),
+        isPublic: args.isPublic === true,
+        tags: normalizeStringArray(args.tags),
+        tools: normalizeStringArray(args.tools),
+        references: normalizeAgentReferencesForServerCreate(args.references),
+        linkedSpaces: normalizeStringArray(args.linkedSpaces),
+        ...(typeof args.temperature === "number" ? { temperature: args.temperature } : {}),
+        ...(typeof args.top_p === "number" ? { top_p: args.top_p } : {}),
+        ...(typeof args.frequency_penalty === "number"
+            ? { frequency_penalty: args.frequency_penalty }
+            : {}),
+        ...(typeof args.presence_penalty === "number"
+            ? { presence_penalty: args.presence_penalty }
+            : {}),
+        ...(typeof args.max_tokens === "number" ? { max_tokens: args.max_tokens } : {}),
+        ...(args.reasoning_effort ? { reasoning_effort: args.reasoning_effort } : {}),
+        whitelist: args.isPublic === true ? [] : [],
+    };
+};
+const FEEDBACK_TABLE_ID = "01NOLOFEEDBACKT000000000R1";
+const TASK_BOARD_TABLE_ID = "NOLOTASKBOARD";
+const TASK_RUN_PRIMITIVE_TOOL_NAMES = new Set([
+    "readTaskContext",
+    "queryReadyWorkItems",
+    "upsertWorkItem",
+    "claimWorkItem",
+    "openDialog",
+    "recordArtifact",
+    "setBlocker",
+    "clearBlocker",
+    "requestReview",
+    "recordReview",
+    "submitOutcome",
+    "closeWorkItem",
+]);
+const SEARCH_DIALOG_MESSAGES_SCAN_LIMIT = 500;
+const SEARCH_DIALOG_MESSAGES_RESULT_LIMIT = 10;
+const SEARCH_DIALOG_MESSAGES_CONTEXT_LIMIT = 3;
+const SEARCH_DIALOG_MESSAGES_CLIP_CHARS = 1800;
+const SEARCH_DIALOG_MESSAGES_CONTEXT_CLIP_CHARS = 600;
+
+const sanitizeGeneratedHtmlFileName = (value: unknown, fallback: string): string => {
+    const raw = typeof value === "string" && value.trim() ? value.trim() : fallback;
+    const sanitized =
+        raw
+            .replace(/[\\/:*?"<>|]+/g, "-")
+            .replace(/\s+/g, "-")
+            .replace(/-+/g, "-")
+            .replace(/^-|-$/g, "")
+            .slice(0, 100) || fallback;
+    return /\.html?$/i.test(sanitized) ? sanitized : `${sanitized}.html`;
+};
+
+const buildFileContentUrl = (base: string, fileDbKey: string): string =>
+    `${base}/api/v1/db/file/content/${encodeURIComponent(fileDbKey)}`;
+
+const normalizeBase = (base: string): string => base.replace(/\/+$/, "");
+
+const normalizeSubjectRefs = (value: unknown): Array<{ kind: string; id: string; role?: string }> => {
+    if (!Array.isArray(value)) return [];
+    return value
+        .map((item) => {
+            if (!item || typeof item !== "object") return null;
+            const raw = item as Record<string, unknown>;
+            const kind = typeof raw.kind === "string" ? raw.kind.trim() : "";
+            const id = typeof raw.id === "string" ? raw.id.trim() : "";
+            if (!kind || !id) return null;
+            const role = typeof raw.role === "string" && raw.role.trim() ? raw.role.trim() : undefined;
+            return { kind, id, ...(role ? { role } : {}) };
+        })
+        .filter((item): item is { kind: string; id: string; role?: string } => Boolean(item));
+};
+
+function mergeSubjectRefs(
+    ...refGroups: unknown[]
+): Array<{ kind: string; id: string; role?: string }> {
+    const merged: Array<{ kind: string; id: string; role?: string }> = [];
+    const seen = new Set<string>();
+    for (const ref of refGroups.flatMap((group) => normalizeSubjectRefs(group))) {
+        const key = `${ref.kind}\u0000${ref.id}\u0000${ref.role ?? ""}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        merged.push(ref);
+    }
+    return merged;
+}
+
+const resolveSameOriginChildRunBase = (targetBase: string, mainBase: string) => {
+    if (normalizeServerOrigin(targetBase) !== normalizeServerOrigin(mainBase)) {
+        return targetBase;
+    }
+    const port = process.env.HTTP_PORT;
+    if (!port) return targetBase;
+    const host = process.env.PLATFORM_SERVER_HOST || "127.0.0.1";
+    const loopbackHost =
+        host === "0.0.0.0" || host === "::" || host === "[::]" ? "127.0.0.1" : host;
+    return `http://${loopbackHost}:${port}`;
+};
+
+const generateShareToken = (): string => {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    const charsLen = chars.length;
+    const maxValid = 252;
+    let token = "";
+    while (token.length < 10) {
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        for (let i = 0; i < bytes.length && token.length < 10; i += 1) {
+            if (bytes[i] < maxValid) {
+                token += chars.charAt(bytes[i] % charsLen);
+            }
+        }
+    }
+    return token;
+};
+const normalizeTaskRunPrimitiveArgs = (
+    toolName: string,
+    args: Record<string, any>,
+): Record<string, any> | null => {
+    if (!TASK_RUN_PRIMITIVE_TOOL_NAMES.has(toolName)) return null;
+    const dbKey = args.dbKey ?? args.rowDbKey;
+    const baseArgs = {
+        action: toolName,
+        ...(typeof dbKey === "string" && dbKey.trim() ? { dbKey: dbKey.trim() } : {}),
+        ...(typeof args.tenantId === "string" && args.tenantId.trim() ? { tenantId: args.tenantId.trim() } : {}),
+        ...(typeof args.tableId === "string" && args.tableId.trim() ? { tableId: args.tableId.trim() } : {}),
+        ...(typeof args.rowId === "string" && args.rowId.trim() ? { rowId: args.rowId.trim() } : {}),
+    };
+
+    if (toolName !== "upsertWorkItem" || Array.isArray(args.workItems)) {
+        return {
+            ...baseArgs,
+            ...args,
+            action: toolName,
+            ...(typeof dbKey === "string" && dbKey.trim() ? { dbKey: dbKey.trim() } : {}),
+            rowDbKey: undefined,
+        };
+    }
+
+    const id = args.workItemId ?? args.itemId ?? args.id;
+    const title = args.title ?? args.summary ?? args.description;
+    return {
+        ...baseArgs,
+        workItems: [
+            {
+                ...(typeof id === "string" && id.trim() ? { id: id.trim() } : {}),
+                ...(typeof args.kind === "string" && args.kind.trim()
+                    ? { kind: args.kind.trim() }
+                    : typeof args.type === "string" && args.type.trim()
+                      ? { kind: args.type.trim() }
+                      : {}),
+                ...(typeof args.ownerAgent === "string" && args.ownerAgent.trim()
+                    ? { ownerAgent: args.ownerAgent.trim() }
+                    : typeof args.owner === "string" && args.owner.trim()
+                      ? { ownerAgent: args.owner.trim() }
+                      : typeof args.agentKey === "string" && args.agentKey.trim()
+                        ? { ownerAgent: args.agentKey.trim() }
+                        : {}),
+                ...(typeof title === "string" && title.trim() ? { title: title.trim() } : {}),
+                ...(typeof args.status === "string" && args.status.trim()
+                    ? { status: args.status.trim() }
+                    : {}),
+                ...(Array.isArray(args.dependsOn) ? { dependsOn: args.dependsOn } : {}),
+                ...(Array.isArray(args.writeScope) ? { writeScope: args.writeScope } : {}),
+                ...(typeof args.reviewPolicy === "string" && args.reviewPolicy.trim()
+                    ? { reviewPolicy: args.reviewPolicy.trim() }
+                    : {}),
+            },
+        ],
+    };
+};
+const getAllowedRemoteServerBases = (): string[] =>
+    (process.env.AGENT_TOOL_ALLOWED_SERVER_BASES ?? "")
+        .split(",")
+        .map((base) => normalizeServerOrigin(base.trim()))
+        .filter((base): base is string => !!base);
+
+const buildFanoutServerList = (
+    originServer: string,
+    syncServers: unknown,
+): string[] => {
+    const normalizedOrigin = normalizeServerOrigin(originServer);
+    const candidates = Array.isArray(syncServers) ? syncServers : [];
+    const shouldIncludeNoloCluster =
+        !!normalizedOrigin &&
+        (/^https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?$/i.test(normalizedOrigin) ||
+            NOLO_CLUSTER_SERVERS.some(
+                (server) => normalizeServerOrigin(server) === normalizedOrigin,
+            ));
+    return Array.from(
+        new Set(
+            [
+                normalizedOrigin,
+                ...candidates,
+                ...(shouldIncludeNoloCluster ? NOLO_CLUSTER_SERVERS : []),
+            ]
+                .map((value) =>
+                    typeof value === "string" ? normalizeServerOrigin(value) : null,
+                )
+                .filter((value): value is string => !!value),
+        ),
+    );
+};
+
+export const resolveDelegatedServerBase = (
+    requestedBase: unknown,
+    mainBase: string,
+): { ok: true; base: string } | { ok: false; error: string } => {
+    if (typeof requestedBase !== "string" || !requestedBase.trim()) {
+        return { ok: true, base: mainBase };
+    }
+
+    const requestedOrigin = normalizeServerOrigin(requestedBase.trim());
+    if (!requestedOrigin) {
+        return {
+            ok: false,
+            error: `Invalid serverBase: ${String(requestedBase)}`,
+        };
+    }
+
+    const mainOrigin = normalizeServerOrigin(mainBase);
+    const isLocalMain =
+        !!mainOrigin &&
+        /^https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?$/i.test(mainOrigin);
+    const isNoloClusterTarget = NOLO_CLUSTER_SERVERS.some(
+        (server) => normalizeServerOrigin(server) === requestedOrigin,
+    );
+    if (
+        requestedOrigin === mainOrigin ||
+        getAllowedRemoteServerBases().includes(requestedOrigin) ||
+        (isLocalMain && isNoloClusterTarget)
+    ) {
+        return { ok: true, base: requestedOrigin };
+    }
+
+    return {
+        ok: false,
+        error:
+            `serverBase "${requestedOrigin}" is not allowed. ` +
+            "Add it to AGENT_TOOL_ALLOWED_SERVER_BASES before delegating current auth to a remote nolo server.",
+    };
+};
+
+export { extractAgentRuntimeServerBase, normalizeServerOrigin };
+
+const buildDelegatedAgentInput = (task: string, input: unknown): string => {
+    if (input === undefined || input === null) return task;
+    if (typeof input === "string") {
+        return `${task}\n\n--- INPUT (text) ---\n${input}`;
+    }
+    return `${task}\n\n--- INPUT (json) ---\n${JSON.stringify(input, null, 2)}`;
+};
+
+const isHttpImageData = (value: unknown): boolean =>
+    typeof value === "string" && /^https?:\/\//i.test(value.trim());
+
+const collectLatestImageUrlsFromMessages = (messages: unknown): string[] => {
+    if (!Array.isArray(messages)) return [];
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const content = (messages[index] as any)?.content;
+        if (!Array.isArray(content)) continue;
+        const urls = content
+            .map((part) =>
+                part?.type === "image_url" && typeof part.image_url?.url === "string"
+                    ? part.image_url.url.trim()
+                    : "",
+            )
+            .filter((url): url is string => isHttpImageData(url));
+        if (urls.length > 0) return [...new Set(urls)];
+    }
+    return [];
+};
+
+const fetchPersistedDialogImageUrls = async (
+    mainBase: string,
+    authToken: string,
+    dialogId?: string | null,
+): Promise<string[]> => {
+    if (!dialogId) return [];
+    try {
+        const res = await fetch(`${mainBase}/rpc/getConvMsgs`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+            },
+            body: JSON.stringify({ dialogId, limit: 80 }),
+        });
+        if (!res.ok) return [];
+        const messages = await res.json().catch(() => []);
+        return collectLatestImageUrlsFromMessages(messages);
+    } catch {
+        return [];
+    }
+};
+
+const resolveImageToolArgs = async (
+    toolName: string,
+    args: Record<string, any>,
+    mainBase: string,
+    authToken: string,
+    context?: ToolExecutionContext,
+): Promise<Record<string, any>> => {
+    if (!IMAGE_GENERATION_TOOL_NAMES.has(toolName)) return args;
+
+    const images = Array.isArray(args.images) ? args.images : [];
+    if (images.some((image: any) => isHttpImageData(image?.data))) {
+        return args;
+    }
+
+    let fallbackUrls = Array.isArray(context?.imageUrls)
+        ? context.imageUrls.filter((url) => isHttpImageData(url))
+        : [];
+    if (fallbackUrls.length === 0) {
+        fallbackUrls = await fetchPersistedDialogImageUrls(
+            mainBase,
+            authToken,
+            context?.dialogId,
+        );
+    }
+    if (fallbackUrls.length === 0) return args;
+
+    return {
+        ...args,
+        images: fallbackUrls.slice(0, Math.max(1, images.length)).map((url) => ({
+            data: url,
+        })),
+    };
+};
+
+const normalizeSkillImportUrl = (rawUrl: string): string => {
+    const trimmed = rawUrl.trim();
+    const githubBlobMatch = trimmed.match(
+        /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/,
+    );
+    if (githubBlobMatch) {
+        const [, owner, repo, ref, path] = githubBlobMatch;
+        return `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path}`;
+    }
+    return trimmed;
+};
+
+const withTaskRunContext = (
+    args: Record<string, any>,
+    context?: ToolExecutionContext,
+): Record<string, any> => {
+    const hasExplicitRowTarget =
+        (typeof args.dbKey === "string" && args.dbKey.trim()) ||
+        (typeof args.tenantId === "string" && args.tenantId.trim() &&
+            typeof args.tableId === "string" && args.tableId.trim() &&
+            typeof args.rowId === "string" && args.rowId.trim());
+    if (hasExplicitRowTarget) return args;
+    const rowDbKey =
+        typeof context?.runtimeContext?.taskRun?.rowDbKey === "string" &&
+        context.runtimeContext.taskRun.rowDbKey.trim()
+            ? context.runtimeContext.taskRun.rowDbKey.trim()
+            : "";
+    return rowDbKey ? { ...args, dbKey: rowDbKey } : args;
+};
+
+function buildAgentHandoffUserInput(args: {
+    message: string;
+    parentDialogId?: string;
+    subjectRefs?: Array<{ kind: string; id: string; role?: string }>;
+    subjectEvidenceLines?: string[];
+    runtimeContext?: Record<string, any>;
+}): string {
+    const taskRun = args.runtimeContext?.taskRun;
+    const rowDbKey =
+        typeof taskRun?.rowDbKey === "string" && taskRun.rowDbKey.trim()
+            ? taskRun.rowDbKey.trim()
+            : "";
+    const workItemId =
+        typeof taskRun?.workItemId === "string" && taskRun.workItemId.trim()
+            ? taskRun.workItemId.trim()
+            : "";
+    const artifactIds = Array.isArray(taskRun?.artifactIds)
+        ? taskRun.artifactIds.filter((item: unknown): item is string => typeof item === "string" && Boolean(item.trim()))
+        : [];
+    const subjectRefs = args.subjectRefs?.filter((ref) => ref?.kind && ref?.id) ?? [];
+    const subjectEvidenceLines = args.subjectEvidenceLines?.filter(Boolean) ?? [];
+    if (!args.parentDialogId && !rowDbKey && !workItemId && artifactIds.length === 0 && subjectRefs.length === 0 && subjectEvidenceLines.length === 0) {
+        return args.message;
+    }
+    return [
+        "--- Nolo agent handoff context ---",
+        "This block is orientation for the receiving agent. It is not a workflow decision, review result, or replacement for inspecting durable records.",
+        ...(args.parentDialogId ? [`- parentDialogId: ${args.parentDialogId}`] : []),
+        ...(rowDbKey ? [`- task row: ${rowDbKey}`] : []),
+        ...(workItemId ? [`- workItemId: ${workItemId}`] : []),
+        ...(artifactIds.length ? [`- artifactIds: ${artifactIds.join(",")}`] : []),
+        ...(subjectRefs.length
+            ? [
+                "- subjectRefs:",
+                ...subjectRefs.map((ref) => `  - ${ref.kind}:${ref.id}${ref.role ? ` (${ref.role})` : ""}`),
+            ]
+            : []),
+        ...(subjectEvidenceLines.length
+            ? [
+                "- referenced evidence snapshot (server-read durable facts at handoff time):",
+                ...subjectEvidenceLines.map((line) => `  - ${line}`),
+            ]
+            : []),
+        "- Start by reading the durable task context when task-run is available.",
+        "- To find the work evidence, inspect the task row fields that already exist: workItems.dialogIds, workItems.outcome, review.dialogId, activityRefs, agentRuns.dialogId/resultSummary, and artifactRefs.",
+        "- Use dialog read/search tools for exact wording or tool traces; do not infer completion or review status from this handoff text alone.",
+        "- Durable result channels include taskRun primitives such as submitOutcome, setBlocker, requestReview, recordReview, or closeWorkItem when they are available.",
+        "--- Handoff task ---",
+        args.message,
+    ].join("\n");
+}
+
+const asPlainRecord = (value: unknown): Record<string, any> =>
+    value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+
+const summarizeStringArray = (value: unknown, max = 6): string[] => {
+    if (!Array.isArray(value)) return [];
+    const items = value
+        .filter((item): item is string => typeof item === "string" && Boolean(item.trim()))
+        .map((item) => item.trim());
+    return items.length > max ? [...items.slice(0, max), `+${items.length - max} more`] : items;
+};
+
+const clipEvidenceText = (value: unknown, max = 220): string => {
+    if (typeof value !== "string") return "";
+    const compact = value.replace(/\s+/g, " ").trim();
+    return compact.length > max ? `${compact.slice(0, max - 3)}...` : compact;
+};
+
+async function buildReferencedDialogEvidenceLines(args: {
+    subjectRefs: Array<{ kind: string; id: string; role?: string }>;
+    userId?: string | null;
+}): Promise<string[]> {
+    const lines: string[] = [];
+    const seenDialogIds = new Set<string>();
+    for (const ref of args.subjectRefs) {
+        if (ref.kind !== "dialog" || !ref.id.trim()) continue;
+        const dialogId = ref.id.trim();
+        if (seenDialogIds.has(dialogId)) continue;
+        seenDialogIds.add(dialogId);
+        try {
+            const resolved = await resolveExistingDialogRef({
+                dialogId,
+                preferredUserId: args.userId,
+            });
+            if (!resolved?.dialogRecord) {
+                lines.push(`dialog:${dialogId}${ref.role ? ` (${ref.role})` : ""} not found`);
+                continue;
+            }
+            const dialog = asPlainRecord(resolved.dialogRecord);
+            const runtimeCheckpoint = asPlainRecord(dialog.runtimeCheckpoint);
+            const artifacts = asPlainRecord(dialog.artifacts);
+            const workspaceProgress = asPlainRecord(runtimeCheckpoint.workspaceProgress);
+            const workspaceLease = asPlainRecord(dialog.workspaceLease ?? runtimeCheckpoint.workspaceLease);
+            const messageCount = await countDialogMessages(dialogId);
+            const changedFiles = summarizeStringArray(
+                artifacts.changedFiles ?? workspaceProgress.changedFiles ?? workspaceLease.changedFiles,
+            );
+            const workspaceRoot = typeof workspaceLease.workspaceRoot === "string" && workspaceLease.workspaceRoot.trim()
+                ? workspaceLease.workspaceRoot.trim()
+                : typeof workspaceProgress.workspaceRoot === "string" && workspaceProgress.workspaceRoot.trim()
+                    ? workspaceProgress.workspaceRoot.trim()
+                    : "";
+            const status = typeof dialog.status === "string" && dialog.status.trim()
+                ? dialog.status.trim()
+                : "unknown";
+            const runtimeStatus = typeof runtimeCheckpoint.status === "string" && runtimeCheckpoint.status.trim()
+                ? runtimeCheckpoint.status.trim()
+                : "none";
+            const summary = clipEvidenceText(
+                dialog.resultSummary ?? runtimeCheckpoint.lastAssistantText ?? dialog.title,
+            );
+            lines.push(
+                [
+                    `dialog:${dialogId}${ref.role ? ` (${ref.role})` : ""}`,
+                    `status=${status}`,
+                    `runtimeStatus=${runtimeStatus}`,
+                    `messagesCount=${messageCount.count}${messageCount.truncated ? "+" : ""}`,
+                    `artifacts=${Object.keys(artifacts).length ? "present" : "none"}`,
+                    ...(workspaceRoot ? [`workspace=${workspaceRoot}`] : []),
+                    `changedFiles=${changedFiles.length ? changedFiles.join(",") : "none"}`,
+                    ...(summary ? [`summary="${summary}"`] : []),
+                ].join(" "),
+            );
+        } catch (error) {
+            const detail = error instanceof Error && error.message ? error.message : "read failed";
+            lines.push(`dialog:${dialogId}${ref.role ? ` (${ref.role})` : ""} unavailable: ${detail}`);
+        }
+    }
+    return lines;
+}
+
+async function countDialogMessages(dialogId: string, max = 200): Promise<{ count: number; truncated: boolean }> {
+    let count = 0;
+    const gte = createKey(DataType.DIALOG, dialogId, "msg", "");
+    const lte = createKey(DataType.DIALOG, dialogId, "msg", "\uffff");
+    for await (const _ of serverDb.iterator({ gte, lte })) {
+        count += 1;
+        if (count > max) return { count: max, truncated: true };
+    }
+    return { count, truncated: false };
+}
+
+const looksLikeLocalFilePath = (value: unknown): value is string => {
+    if (typeof value !== "string") return false;
+    const trimmed = value.trim();
+    if (!trimmed) return false;
+    return (
+        trimmed.startsWith("/") ||
+        trimmed.startsWith("./") ||
+        trimmed.startsWith("../") ||
+        trimmed.includes("/") ||
+        /\.[A-Za-z0-9_-]{1,12}$/.test(trimmed)
+    );
+};
+
+const normalizeToolExecutionArgs = (
+    toolName: string,
+    args: Record<string, any>,
+): Record<string, any> => {
+    if (toolName === "execShell") {
+        const command =
+            args.command ??
+            args.runCommand ??
+            args.run_command ??
+            args.terminalCommand ??
+            args.terminal_command ??
+            args.runInBash ??
+            args.run_in_bash ??
+            args.executeCommand ??
+            args.execute_command ??
+            args.execShell ??
+            args.bash ??
+            args.cmd;
+        return command == null ? args : { ...args, command };
+    }
+
+    if (toolName === "readFile") {
+        const filePath = args.filePath ?? args.path ?? args.filename ?? args.file;
+        return filePath == null ? args : { ...args, filePath };
+    }
+
+    if (toolName === "read") {
+        const filePath = args.filePath ?? args.path ?? args.filename ?? args.file;
+        if (filePath != null) return { ...args, filePath };
+        if (process.env.NOLO_DESKTOP === "1" && looksLikeLocalFilePath(args.dbKey)) {
+            return { ...args, filePath: args.dbKey };
+        }
+    }
+
+    return args;
+};
+
+export async function executeToolOnServer(
+    toolCall: AssistantToolCall,
+    serverBase: string,
+    authToken: string,
+    context?: ToolExecutionContext,
+): Promise<string> {
+    const mainBase = normalizeBase(serverBase);
+    const rawToolName = (toolCall.function.name || "").replace(/^functions\./, "").trim();
+    const toolName = canonicalizeToolName(rawToolName);
+    let args: Record<string, any> = {};
+    try {
+        args = JSON.parse(toolCall.function.arguments || "{}");
+    } catch {
+        return JSON.stringify({ error: "Invalid tool arguments JSON" });
+    }
+    args = normalizeToolExecutionArgs(toolName, args);
+    args = await resolveImageToolArgs(toolName, args, mainBase, authToken, context);
+
+    const currentAgentKey =
+        typeof context?.agentKey === "string" && context.agentKey.trim()
+            ? context.agentKey.trim()
+            : "";
+    const buildAuthHeaders = (): Record<string, string> => {
+        const headers: Record<string, string> = {};
+        if (authToken) {
+            headers.Authorization = `Bearer ${authToken}`;
+            headers.Cookie = `${WEB_AUTH_TOKEN_COOKIE}=${encodeURIComponent(authToken)}`;
+        }
+        if (currentAgentKey) {
+            headers["X-Nolo-Agent-Key"] = currentAgentKey;
+        }
+        return headers;
+    };
+
+    const post = async (
+        base: string,
+        path: string,
+        body: object
+    ): Promise<string> => {
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+            ...buildAuthHeaders(),
+        };
+
+        const res = await fetch(`${base}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            return JSON.stringify({ error: `HTTP ${res.status}`, detail: await res.text() });
+        }
+        return res.text();
+    };
+
+    const postJson = async (
+        base: string,
+        path: string,
+        body: object,
+    ): Promise<{
+        ok: boolean;
+        status: number;
+        text: string;
+        data: any;
+    }> => {
+        const headers: Record<string, string> = {
+            "Content-Type": "application/json",
+            ...buildAuthHeaders(),
+        };
+
+        const res = await fetch(`${base}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        const text = await res.text();
+        let data: any = null;
+        try {
+            data = text ? JSON.parse(text) : null;
+        } catch {
+            data = null;
+        }
+        return {
+            ok: res.ok,
+            status: res.status,
+            text,
+            data,
+        };
+    };
+
+    const postMain = async (path: string, body: object): Promise<string> =>
+        post(resolveSameOriginChildRunBase(mainBase, mainBase), path, body);
+
+    const sleep = (ms: number) =>
+        new Promise((resolve) => setTimeout(resolve, ms));
+
+    const withDialogId = (body: Record<string, any>): Record<string, any> => {
+        if (!context?.dialogId || "dialogId" in body) return body;
+        return {
+            ...body,
+            dialogId: context.dialogId,
+        };
+    };
+
+    const withFeedbackSubmitterUserId = (args: Record<string, any>): Record<string, any> => {
+        const agentKey = typeof context?.agentKey === "string" ? context.agentKey.trim() : "";
+        const userId = typeof context?.userId === "string" ? context.userId.trim() : "";
+        if (
+            !userId ||
+            !(
+                agentKey === `agent-pub-${FEEDBACK_AGENT_ID}` ||
+                agentKey.endsWith(`-${FEEDBACK_AGENT_ID}`)
+            )
+        ) {
+            return args;
+        }
+
+        const tableId = typeof args.tableId === "string" ? args.tableId.trim() : "";
+        const values =
+            args.values && typeof args.values === "object" && !Array.isArray(args.values)
+                ? args.values
+                : {};
+        if (tableId === FEEDBACK_TABLE_ID) {
+            return {
+                ...args,
+                values: {
+                    ...values,
+                    submitterUserId: values.submitterUserId || userId,
+                },
+            };
+        }
+        if (tableId === TASK_BOARD_TABLE_ID) {
+            return {
+                ...args,
+                values: {
+                    ...values,
+                    feedbackSubmitterUserId: values.feedbackSubmitterUserId || userId,
+                },
+            };
+        }
+        return args;
+    };
+
+    const deleteDbKey = async (dbKey: string): Promise<{ ok: boolean; status: number; text: string }> => {
+        const res = await fetch(`${mainBase}/api/v1/db/delete/${encodeURIComponent(dbKey)}`, {
+            method: "DELETE",
+            headers: buildAuthHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            text: await res.text(),
+        };
+    };
+
+    const spaceMemberKeysForDelete = (spaceId: string, record: SpaceRecordLike): string[] => {
+        const memberIds = new Set<string>();
+        if (context?.userId) memberIds.add(context.userId);
+        if (Array.isArray(record.members)) {
+            for (const memberId of record.members) {
+                if (typeof memberId === "string" && memberId.trim()) {
+                    memberIds.add(memberId.trim());
+                }
+            }
+        } else if (record.members && typeof record.members === "object") {
+            for (const memberId of Object.keys(record.members)) {
+                if (memberId.trim()) memberIds.add(memberId.trim());
+            }
+        }
+        return Array.from(memberIds).map((memberId) => createSpaceKey.member(memberId, spaceId));
+    };
+    const requireCurrentAgentKey = () => {
+        if (!currentAgentKey) {
+            return JSON.stringify({
+                error: "Current agent key is unavailable in server-side agent mode.",
+            });
+        }
+        return null;
+    };
+    const includesCaseInsensitive = (haystack: unknown, needle: unknown): boolean => {
+        const normalizedNeedle =
+            typeof needle === "string" && needle.trim() ? needle.trim().toLowerCase() : "";
+        if (!normalizedNeedle) return true;
+        const normalizedHaystack =
+            typeof haystack === "string" ? haystack.toLowerCase() : String(haystack || "").toLowerCase();
+        return normalizedHaystack.includes(normalizedNeedle);
+    };
+    const participantText = (participants: any): string =>
+        Array.isArray(participants)
+            ? participants
+                  .map((participant) =>
+                      [participant?.name, participant?.email]
+                          .filter((value) => typeof value === "string" && value.trim())
+                          .join(" "),
+                  )
+                  .join("\n")
+            : "";
+    const EMAIL_WAIT_GRACE_MS = 10_000;
+    const parseEmailTimestamp = (value: unknown): number | null => {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+        if (typeof value === "string" && value.trim()) {
+            const parsed = Date.parse(value);
+            return Number.isFinite(parsed) ? parsed : null;
+        }
+        return null;
+    };
+    const emailReceivedAtMs = (email: any): number | null =>
+        parseEmailTimestamp(email?.meta?.provider?.receivedAt) ??
+        parseEmailTimestamp(email?.receivedAt) ??
+        parseEmailTimestamp(email?.createdAt) ??
+        parseEmailTimestamp(email?.updatedAt);
+    const emailMatchesWaitFilters = (email: any, waitArgs: Record<string, any>): boolean =>
+        includesCaseInsensitive(email?.subject, waitArgs.subjectContains) &&
+        includesCaseInsensitive(email?.from?.email, waitArgs.fromContains) &&
+        includesCaseInsensitive(participantText(email?.to), waitArgs.toContains) &&
+        includesCaseInsensitive(
+            [email?.subject, email?.text, email?.html].filter(Boolean).join("\n"),
+            waitArgs.bodyContains,
+        );
+    const emailIsFreshForWait = (email: any, waitStartedAtMs: number): boolean => {
+        const receivedAtMs = emailReceivedAtMs(email);
+        if (receivedAtMs == null) return true;
+        return receivedAtMs >= waitStartedAtMs - EMAIL_WAIT_GRACE_MS;
+    };
+
+    const runChildAgent = async (
+        agentKey: string,
+        userInput: string,
+        requestedServerBase?: unknown,
+        requestedTimeoutMs?: unknown,
+        options?: {
+            background?: boolean;
+            parentDialogId?: string;
+            subjectRefs?: Array<{ kind: string; id: string; role?: string }>;
+            idempotencyKey?: string;
+        },
+    ) => {
+        let effectiveRequestedServerBase = requestedServerBase;
+        let autoRouted = false;
+        const allowedRemoteServerBases = getAllowedRemoteServerBases();
+        if (
+            allowedRemoteServerBases.length > 0 &&
+            (typeof requestedServerBase !== "string" || !requestedServerBase.trim())
+        ) {
+            try {
+                const res = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(agentKey)}`, {
+                    headers: buildAuthHeaders(),
+                });
+                if (res.ok) {
+                    const raw = await res.json();
+                    const agentRecord = raw?.data ?? raw;
+                    const runtimeServerBase = extractAgentRuntimeServerBase(agentRecord);
+                    const runtimeOrigin = runtimeServerBase
+                        ? normalizeServerOrigin(runtimeServerBase)
+                        : null;
+                    const mainOrigin = normalizeServerOrigin(mainBase);
+                    if (runtimeOrigin && runtimeOrigin !== mainOrigin) {
+                        effectiveRequestedServerBase = runtimeOrigin;
+                        autoRouted = true;
+                    }
+                }
+            } catch {
+                // Best effort only. If metadata cannot be read, run on the current server.
+            }
+        }
+
+        const target = resolveDelegatedServerBase(effectiveRequestedServerBase, mainBase);
+        if (!target.ok) {
+            return {
+                ok: false as const,
+                status: 400,
+                error: autoRouted
+                    ? `${target.error} Target agent declares this runtime serverBase in its delegation metadata.`
+                    : target.error,
+            };
+        }
+
+        const childRunBase = resolveSameOriginChildRunBase(target.base, mainBase);
+        const childSubjectRefs = mergeSubjectRefs(
+            context?.runtimeContext?.subjectRefs,
+            options?.subjectRefs,
+        );
+        const childRuntimeContext = options?.background || childSubjectRefs.length || options?.idempotencyKey
+            ? {
+                ...(context?.runtimeContext ?? {}),
+                surface: context?.runtimeContext?.surface ?? "server-script",
+                entrypoint:
+                    options?.background
+                        ? "agent-tool:startAgentDialog"
+                        : context?.runtimeContext?.entrypoint ?? "agent-tool:callAgent",
+                ...(childSubjectRefs.length ? { subjectRefs: childSubjectRefs } : {}),
+                ...(options?.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+            }
+            : context?.runtimeContext;
+        const res = await fetch(`${childRunBase}/api/agent/run`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...buildAuthHeaders() },
+            body: JSON.stringify({
+                agentKey,
+                userInput,
+                stream: false,
+                ...(options?.background ? { background: true } : {}),
+                spaceId: context?.currentSpaceId ?? undefined,
+                ...(options?.parentDialogId ? { parentDialogId: options.parentDialogId } : {}),
+                ...(childRuntimeContext ? { runtimeContext: childRuntimeContext } : {}),
+                ...(typeof requestedTimeoutMs === "number" &&
+                    Number.isFinite(requestedTimeoutMs) &&
+                    requestedTimeoutMs > 0
+                    ? { timeoutMs: requestedTimeoutMs }
+                    : {}),
+            }),
+        });
+        if (!res.ok) {
+            return {
+                ok: false as const,
+                status: res.status,
+                error: await res.text(),
+            };
+        }
+        const payload = await res.json();
+        return {
+            ok: true as const,
+            payload,
+            ...(typeof effectiveRequestedServerBase === "string" && effectiveRequestedServerBase.trim()
+                ? { serverBase: target.base }
+                : {}),
+            ...(autoRouted ? { autoRouted: true } : {}),
+        };
+    };
+
+    const waitForAppDeployResult = async (jobId: string) => {
+        const deadline = Date.now() + APP_DEPLOY_POLL_TIMEOUT_MS;
+        let latestPayload: any = null;
+
+        while (Date.now() < deadline) {
+            const statusResult = await postJson(
+                mainBase,
+                "/api/app/deploy/status",
+                { jobId },
+            );
+
+            if (!statusResult.ok) {
+                return JSON.stringify(
+                    statusResult.data ?? {
+                        error: `appDeploy status: HTTP ${statusResult.status}`,
+                        detail: statusResult.text,
+                    },
+                );
+            }
+
+            latestPayload = statusResult.data;
+            if (
+                latestPayload?.status === "succeeded" ||
+                latestPayload?.status === "failed"
+            ) {
+                if (latestPayload.status === "succeeded" && latestPayload.result) {
+                    const result = latestPayload.result;
+                    return JSON.stringify({
+                        ...result,
+                        jobId: latestPayload.jobId,
+                        status: latestPayload.status,
+                        summary: latestPayload.summary,
+                        steps: latestPayload.steps,
+                        appUrl: result.customUrl ?? result.url,
+                    });
+                }
+                return JSON.stringify(latestPayload);
+            }
+
+            await sleep(APP_DEPLOY_POLL_INTERVAL_MS);
+        }
+
+        return JSON.stringify({
+            ...(latestPayload && typeof latestPayload === "object"
+                ? latestPayload
+                : {
+                    success: true,
+                    jobId,
+                    status: "pending",
+                    summary: "部署任务仍在进行中",
+                }),
+            timeout: true,
+            nextAction:
+                "部署任务还未完成。请稍后再次查询该 jobId，或等待服务端完成后再继续向用户确认最终访问链接。",
+        });
+    };
+
+    const normalizeAppFiles = () => {
+        if (Array.isArray(args.files) && args.files.length > 0) return args.files;
+        if (Array.isArray(args.pages) && args.pages.length > 0) return args.pages;
+        return undefined;
+    };
+    const serverToolName = toolName;
+    const taskRunPrimitiveArgs = normalizeTaskRunPrimitiveArgs(serverToolName, args);
+    if (taskRunPrimitiveArgs) {
+        return runTaskRunTool(withTaskRunContext(taskRunPrimitiveArgs, context), authToken);
+    }
+
+    switch (serverToolName) {
+        // ── 网络/外部 API（同构，前后端都能调，这里走服务端代理）──
+        case "fetchWebpage":
+            return postMain("/api/fetch-webpage", withDialogId({ url: args.url }));
+        case "convertMarxistsBookToOfflineHtml": {
+            const result = await convertMarxistsBookToOfflineHtml({
+                startUrl: args.startUrl,
+                encoding: args.encoding,
+                maxPages: args.maxPages,
+                fetchImpl: fetch,
+            });
+            const fileName = sanitizeGeneratedHtmlFileName(
+                args.singleFileName,
+                `${result.title || "marxists-offline-book"}.html`,
+            );
+            const rawData: Record<string, unknown> = {
+                title: result.title,
+                startUrl: result.startUrl,
+                indexUrl: result.indexUrl,
+                stylesheetUrl: result.stylesheetUrl,
+                pages: result.pages,
+                validation: result.validation,
+                fileName,
+            };
+            if (args.saveAsFile !== false) {
+                if (!context?.userId) {
+                    rawData.saveWarning =
+                        "saveAsFile was requested, but the server tool execution context has no userId.";
+                } else {
+                    const { fileId, metadata } = await saveBufferAsFile(
+                        Buffer.from(result.html, "utf8"),
+                        {
+                            tenantId: context.userId,
+                            originalName: fileName,
+                            mimeType: "text/html; charset=utf-8",
+                            ownerType: "user",
+                            ownerId: context.userId,
+                            uploadedBy: context.userId,
+                            source: "ai-generated",
+                            model: "convertMarxistsBookToOfflineHtml",
+                            prompt: result.startUrl,
+                            tags: ["offline-book", "marxists-org", "html"],
+                            clientMetadata: {
+                                fileCategory: "document",
+                                sourceUrl: result.startUrl,
+                                indexUrl: result.indexUrl,
+                                stylesheetUrl: result.stylesheetUrl,
+                                pageCount: result.validation.pageCount,
+                            },
+                        },
+                    );
+                    const fileDbKey =
+                        typeof (metadata as any).dbKey === "string"
+                            ? (metadata as any).dbKey
+                            : `file-${context.userId}-${fileId}`;
+                    rawData.fileId = fileId;
+                    rawData.fileDbKey = fileDbKey;
+                    rawData.fileUrl = buildFileContentUrl(mainBase, fileDbKey);
+                }
+            }
+            if (args.outputMode === "html") {
+                rawData.html = result.html;
+            }
+            return JSON.stringify({
+                rawData,
+                displayData: formatMarxistsOfflineBookDisplayData({
+                    ...rawData,
+                    htmlIncluded: args.outputMode === "html",
+                }),
+            });
+        }
+        case "read_x_post":
+            return postMain(
+                "/api/read-x-post",
+                withDialogId({
+                    url: args.url,
+                    keepOpen: args.keepOpen,
+                    profileDir: args.profileDir,
+                    headless: args.headless,
+                }),
+            );
+        case "wereadGateway":
+            return postMain(
+                "/api/weread/gateway",
+                withDialogId(args),
+            );
+        case "exa_search":
+            return postMain(
+                "/api/exa-search",
+                withDialogId({
+                    query: args.query,
+                    numResults: args.numResults ?? 5,
+                    contents: args.contents,
+                }),
+            );
+        case "youtubeScraper":
+        case "ecommerceScraper":
+        case "amazonProductScraper":
+            return postMain(
+                "/api/apify-actor",
+                withDialogId({ actorId: args.actorId ?? serverToolName, input: args }),
+            );
+        case "taobaoTmallProductScraper":
+            return postMain(
+                "/api/apify-actor",
+                withDialogId({
+                    actorId: "sian.agency~taobao-tmall-product-scraper",
+                    input: {
+                        operation: "productDetail",
+                        itemId: args.itemId,
+                        detailDepth: args.detailDepth ?? "full",
+                    },
+                    resultType: "datasetItems",
+                }),
+            );
+        case "jdProductScraper": {
+            const result = await jdProductScraperFunc({
+                skuId: args.skuId,
+                url: args.url,
+            });
+            const skuId = typeof result.rawData?.skuId === "string" ? result.rawData.skuId : "";
+            if (
+                skuId &&
+                (isIncompleteProductData(result.rawData) ||
+                    hasSparseJdSpecifications(result.rawData))
+            ) {
+                const mobileUrl = `https://item.m.jd.com/product/${skuId}.html`;
+                const apifyText = await postMain(
+                    "/api/apify-actor",
+                    withDialogId({
+                        actorId: "apify~web-scraper",
+                        input: {
+                            startUrls: [{ url: mobileUrl }],
+                            maxPagesPerCrawl: 1,
+                            maxRequestRetries: 1,
+                            maxConcurrency: 1,
+                            proxyConfiguration: { useApifyProxy: true },
+                            pageFunction: `async function pageFunction(context) {
+  await new Promise((resolve) => setTimeout(resolve, 1500));
+  return {
+    url: context.request.url,
+    itemOnly: window._itemOnly || null,
+    itemInfo: window._itemInfo || null,
+    priceInfo: window.__price || window._price || null,
+    title: document.title,
+    html: document.documentElement ? document.documentElement.innerHTML : ""
+  };
+}`,
+                        },
+                        resultType: "datasetItems",
+                    }),
+                );
+                let apifyData: any = null;
+                try {
+                    apifyData = JSON.parse(apifyText || "null");
+                } catch {
+                    apifyData = null;
+                }
+                const browserItem = Array.isArray(apifyData) ? apifyData[0] : null;
+                if (browserItem && typeof browserItem === "object" && !("error" in browserItem)) {
+                    const browserFallback = parseJdBrowserExtractedData(browserItem, {
+                        skuId,
+                        url: mobileUrl,
+                    });
+                    result.rawData = mergeJdProductData(result.rawData, browserFallback);
+                }
+            }
+            if (skuId && isIncompleteProductData(result.rawData)) {
+                const knownFallback = getKnownJdProductFallback(skuId);
+                if (knownFallback) {
+                    result.rawData = mergeJdProductData(result.rawData, knownFallback);
+                }
+            }
+            result.displayData = formatJdProductDisplayData(result.rawData);
+            return JSON.stringify(result);
+        }
+        case "geminiFlashImage":
+        case "geminiProImagePreview":
+            return postMain("/api/gemini-image-preview", withDialogId(args));
+        case "openAIGptImageGenerate":
+            return postMain(
+                "/api/openai-image",
+                withDialogId({
+                    ...args,
+                    operation: "generate",
+                    model: "gpt-image-2",
+                })
+            );
+        case "openAIGptImageEdit":
+            return postMain(
+                "/api/openai-image",
+                withDialogId({
+                    ...args,
+                    operation: "edit",
+                    model: "gpt-image-2",
+                })
+            );
+        case "openAIGptImage":
+            return postMain("/api/openai-image", withDialogId(args));
+        case "remotionRenderVideo":
+            return postMain("/api/remotion/render", withDialogId(args));
+        case "ui_ask_choice": {
+            const question =
+                typeof args.question === "string" ? args.question.trim() : "";
+            const choices = Array.isArray(args.choices) ? args.choices : [];
+            const blocking = args.blocking !== false;
+            if (!question || choices.length === 0) {
+                return JSON.stringify({
+                    error: "ui_ask_choice",
+                    detail: "ui_ask_choice 需要 question 和至少一个 choice。",
+                });
+            }
+            return JSON.stringify({
+                type: "ui_ask_choice",
+                question,
+                choices,
+                blocking,
+            });
+        }
+        case "queryModelUsage": {
+            try {
+                return JSON.stringify(await runQueryModelUsageTool(args, context));
+            } catch (err: any) {
+                return JSON.stringify({
+                    error: "queryModelUsage",
+                    detail: err?.message ?? String(err),
+                });
+            }
+        }
+        case "createScheduledTask": {
+            try {
+                return JSON.stringify(await runCreateScheduledTaskTool(args, context));
+            } catch (err: any) {
+                return JSON.stringify({
+                    error: "createScheduledTask",
+                    detail: err?.message ?? String(err),
+                });
+            }
+        }
+        case "createDialogGoal": {
+            try {
+                return JSON.stringify(await runCreateDialogGoalTool(args, context));
+            } catch (err: any) {
+                return JSON.stringify({
+                    error: "createDialogGoal",
+                    detail: err?.message ?? String(err),
+                });
+            }
+        }
+        case "getDialogGoal": {
+            try {
+                return JSON.stringify(await runGetDialogGoalTool(args, context));
+            } catch (err: any) {
+                return JSON.stringify({
+                    error: "getDialogGoal",
+                    detail: err?.message ?? String(err),
+                });
+            }
+        }
+        case "completeDialogGoal": {
+            try {
+                return JSON.stringify(await runCompleteDialogGoalTool(args, context));
+            } catch (err: any) {
+                return JSON.stringify({
+                    error: "completeDialogGoal",
+                    detail: err?.message ?? String(err),
+                });
+            }
+        }
+        case "taskRun":
+            return runTaskRunTool(withTaskRunContext(args, context), authToken);
+        case "notifyUser": {
+            try {
+                return JSON.stringify(await runNotifyUserTool(args, context));
+            } catch (err: any) {
+                return JSON.stringify({
+                    error: "notifyUser",
+                    detail: err?.message ?? String(err),
+                });
+            }
+        }
+        case "rememberMemory":
+            return postMain("/api/memory/remember", withDialogId({
+                content: args.content,
+                scope: args.scope,
+                spaceId: context?.currentSpaceId ?? undefined,
+            }));
+        case "callAgent": {
+            const agentKey = typeof args.agentKey === "string" ? args.agentKey.trim() : "";
+            const task = typeof args.task === "string" ? args.task.trim() : "";
+            if (!agentKey) {
+                return JSON.stringify({ error: "callAgent: agentKey is required" });
+            }
+            if (!task) {
+                return JSON.stringify({ error: "callAgent: task is required" });
+            }
+            const childRun = await runChildAgent(
+                agentKey,
+                buildDelegatedAgentInput(task, args.input),
+                args.serverBase,
+            );
+            if (!childRun.ok) {
+                return JSON.stringify({
+                    error: `callAgent: HTTP ${childRun.status}`,
+                    detail: childRun.error,
+                });
+            }
+            const payload = childRun.payload;
+            return JSON.stringify({
+                success: true,
+                agentKey,
+                ...(childRun.serverBase ? { serverBase: childRun.serverBase } : {}),
+                ...(childRun.autoRouted ? { autoRouted: true } : {}),
+                dialogId: payload?.dialogId ?? null,
+                model: payload?.model ?? null,
+                provider: payload?.provider ?? null,
+                content: typeof payload?.content === "string" ? payload.content : "",
+                usage: payload?.usage ?? null,
+                artifacts: payload?.artifacts ?? null,
+            });
+        }
+        case "runStreamingAgent": {
+            const agentKey = typeof args.agentKey === "string" ? args.agentKey.trim() : "";
+            const userInput = typeof args.userInput === "string" ? args.userInput.trim() : "";
+            if (!agentKey) {
+                return JSON.stringify({ error: "runStreamingAgent: agentKey is required" });
+            }
+            if (!userInput) {
+                return JSON.stringify({ error: "runStreamingAgent: userInput is required" });
+            }
+            const childRun = await runChildAgent(agentKey, userInput, args.serverBase);
+            if (!childRun.ok) {
+                return JSON.stringify({
+                    error: `runStreamingAgent: HTTP ${childRun.status}`,
+                    detail: childRun.error,
+                });
+            }
+            const payload = childRun.payload;
+            return JSON.stringify({
+                success: true,
+                handoff: true,
+                agentKey,
+                ...(childRun.serverBase ? { serverBase: childRun.serverBase } : {}),
+                ...(childRun.autoRouted ? { autoRouted: true } : {}),
+                dialogId: payload?.dialogId ?? null,
+                ...(payload?.dialogKey ? { dialogKey: payload.dialogKey } : {}),
+                model: payload?.model ?? null,
+                content: typeof payload?.content === "string" ? payload.content : "",
+                usage: payload?.usage ?? null,
+                artifacts: payload?.artifacts ?? null,
+            });
+        }
+        case "startAgentDialog": {
+            const targetAgentKey =
+                typeof args.targetAgentKey === "string"
+                    ? args.targetAgentKey.trim()
+                    : typeof args.agentKey === "string"
+                      ? args.agentKey.trim()
+                      : "";
+            const message =
+                typeof args.message === "string"
+                    ? args.message.trim()
+                    : typeof args.userInput === "string"
+                      ? args.userInput.trim()
+                      : "";
+            if (!targetAgentKey) {
+                return JSON.stringify({ error: "startAgentDialog: targetAgentKey is required" });
+            }
+            if (!message) {
+                return JSON.stringify({ error: "startAgentDialog: message is required" });
+            }
+            const parentDialogId =
+                typeof args.parentDialogId === "string" && args.parentDialogId.trim()
+                    ? args.parentDialogId.trim()
+                    : typeof context?.dialogId === "string" && context.dialogId.trim()
+                      ? context.dialogId.trim()
+                      : undefined;
+            const timeoutMs =
+                typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs) && args.timeoutMs > 0
+                    ? args.timeoutMs
+                    : undefined;
+            const subjectRefs = normalizeSubjectRefs(args.subjectRefs);
+            const childSubjectRefs = mergeSubjectRefs(
+                context?.runtimeContext?.subjectRefs,
+                subjectRefs,
+            );
+            const subjectEvidenceLines = await buildReferencedDialogEvidenceLines({
+                subjectRefs: childSubjectRefs,
+                userId: context?.userId,
+            });
+            const childMessage = buildAgentHandoffUserInput({
+                message,
+                parentDialogId,
+                subjectRefs: childSubjectRefs,
+                subjectEvidenceLines,
+                runtimeContext: context?.runtimeContext,
+            });
+            const childRun = await runChildAgent(
+                targetAgentKey,
+                childMessage,
+                args.serverBase,
+                timeoutMs,
+                {
+                    background: true,
+                    parentDialogId,
+                    subjectRefs: childSubjectRefs,
+                    ...(typeof args.idempotencyKey === "string" && args.idempotencyKey.trim()
+                        ? { idempotencyKey: args.idempotencyKey.trim() }
+                        : {}),
+                },
+            );
+            if (!childRun.ok) {
+                return JSON.stringify({
+                    error: `startAgentDialog: HTTP ${childRun.status}`,
+                    detail: childRun.error,
+                });
+            }
+            const payload = childRun.payload;
+            const childDialogId = typeof payload?.dialogId === "string" && payload.dialogId.trim()
+                ? payload.dialogId.trim()
+                : "";
+            const childDialogKey = typeof payload?.dialogKey === "string" && payload.dialogKey.trim()
+                ? payload.dialogKey.trim()
+                : undefined;
+            const activityProjection = childDialogId
+                ? await projectDialogActivityToSubjectRows({
+                    db: serverDb,
+                    subjectRefs: childSubjectRefs,
+                    activityRef: {
+                        type: "dialog",
+                        dialogId: childDialogId,
+                        ...(childDialogKey ? { dialogKey: childDialogKey } : {}),
+                        role: "child-dialog",
+                        agentKey: targetAgentKey,
+                        ...(parentDialogId ? { parentDialogId } : {}),
+                        status: typeof payload?.status === "string" && payload.status.trim()
+                            ? payload.status.trim()
+                            : "pending",
+                        updatedAt: new Date().toISOString(),
+                    },
+                })
+                : undefined;
+            return JSON.stringify({
+                success: true,
+                status: payload?.status ?? "pending",
+                targetAgentKey,
+                childDialogId: childDialogId || null,
+                childDialogKey: childDialogKey ?? null,
+                ...(parentDialogId ? { parentDialogId } : {}),
+                ...(childRun.serverBase ? { serverBase: childRun.serverBase } : {}),
+                ...(childRun.autoRouted ? { autoRouted: true } : {}),
+                ...(activityProjection && activityProjection.updatedRowDbKeys.length
+                    ? {
+                        activityProjection: {
+                            updatedRowDbKeys: activityProjection.updatedRowDbKeys,
+                        },
+                    }
+                    : {}),
+            });
+        }
+        case "streamParallelAgents": {
+            const task = typeof args.task === "string" ? args.task.trim() : "";
+            const agents = Array.isArray(args.agents) ? args.agents : [];
+            const returnMode = args.returnMode === "continue" ? "continue" : "handoff";
+            const displayMode = "inline";
+            const defaultServerBase = args.serverBase;
+            const parallelSessionId = `parallel-${Date.now()}-${Math.random()
+                .toString(36)
+                .slice(2, 10)}`;
+            const timeoutMs =
+                typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs) && args.timeoutMs > 0
+                    ? args.timeoutMs
+                    : PARALLEL_AGENT_BRANCH_TIMEOUT_MS;
+            const budgetCredits = normalizeBudgetCredits(args.budgetCredits);
+            if (!task) {
+                return JSON.stringify({ error: "streamParallelAgents: task is required" });
+            }
+            if (agents.length === 0) {
+                return JSON.stringify({ error: "streamParallelAgents: agents is required" });
+            }
+
+            const results = await Promise.all(
+                agents.map(async (agent: Record<string, any>, index: number) => {
+                    const agentKey =
+                        typeof agent?.agentKey === "string" ? agent.agentKey.trim() : "";
+                    const label =
+                        typeof agent?.label === "string" && agent.label.trim()
+                            ? agent.label.trim()
+                            : `Agent ${index + 1}`;
+                    const branchId =
+                        typeof agent?.branchId === "string" && agent.branchId.trim()
+                            ? agent.branchId.trim()
+                            : `branch-${index + 1}`;
+                    if (!agentKey) {
+                        return {
+                            ok: false,
+                            label,
+                            branchId,
+                            agentKey,
+                            error: "missing agentKey",
+                            spentCredits: null,
+                        };
+                    }
+
+                    const childRun = await Promise.race([
+                        runChildAgent(agentKey, task, agent?.serverBase ?? defaultServerBase, timeoutMs),
+                        sleep(timeoutMs).then(() => ({
+                            ok: false as const,
+                            status: 408,
+                            error: `branch timeout after ${timeoutMs}ms`,
+                        })),
+                    ]);
+                    if (!childRun.ok) {
+                        return {
+                            ok: false,
+                            label,
+                            branchId,
+                            agentKey,
+                            error: childRun.error,
+                            status: childRun.status,
+                            authForwarded: Boolean(authToken),
+                            spentCredits: null,
+                        };
+                    }
+
+                    const payload = childRun.payload;
+                    const pricing = calculateParallelBranchPricing({
+                        usage: payload?.usage,
+                        agentKey,
+                        dialogId: payload?.dialogId ?? null,
+                        agentConfig: {
+                            id: agentKey,
+                            model:
+                                typeof payload?.model === "string" ? payload.model : null,
+                            provider:
+                                typeof payload?.provider === "string"
+                                    ? payload.provider
+                                    : null,
+                            inputPrice:
+                                typeof payload?.inputPrice === "number"
+                                    ? payload.inputPrice
+                                    : null,
+                            outputPrice:
+                                typeof payload?.outputPrice === "number"
+                                    ? payload.outputPrice
+                                    : null,
+                        },
+                    });
+                    return {
+                        ok: true,
+                        label,
+                        branchId,
+                        parallelSessionId,
+                        parallelIndex: index,
+                        agentKey,
+                        agentName: label,
+                        ...(childRun.serverBase ? { serverBase: childRun.serverBase } : {}),
+                        ...(childRun.autoRouted ? { autoRouted: true } : {}),
+                        dialogId: payload?.dialogId ?? null,
+                        model: payload?.model ?? null,
+                        provider: payload?.provider ?? null,
+                        content:
+                            typeof payload?.content === "string" ? payload.content.trim() : "",
+                        usage: payload?.usage ?? null,
+                        artifacts: payload?.artifacts ?? null,
+                        spentCredits: pricing.spentCredits,
+                        billedModel: pricing.billedModel,
+                        billedProvider: pricing.billedProvider,
+                        billingServiceTier: pricing.billingServiceTier,
+                        pricingError: pricing.pricingError,
+                    };
+                }),
+            );
+
+            const successful = results.filter((item) => item.ok);
+            const costSummary = summarizeParallelCosts(results);
+            const budget = summarizeParallelBudget({
+                budgetCredits,
+                results,
+            });
+            const stats = {
+                total: results.length,
+                succeeded: successful.length,
+                failed: results.length - successful.length,
+            };
+            const mergedContent = successful
+                .map((item) => `## ${item.label}\n\n${item.content || "(无内容)"}`)
+                .join("\n\n");
+
+            return JSON.stringify({
+                success: true,
+                handoff: returnMode === "handoff",
+                returnMode,
+                displayMode,
+                toolName: "streamParallelAgents",
+                content: mergedContent,
+                summary: `并行调用 ${stats.total} 个 Agent · ${stats.succeeded} 成功 · ${stats.failed} 失败`,
+                stats,
+                costSummary,
+                ...(budget ? { budget } : {}),
+                parallelSessionId,
+                results,
+                timeoutMs,
+                usage: successful.map((item) => item.usage).filter(Boolean),
+            });
+        }
+        case "ziweiChart":
+            return JSON.stringify(runZiweiChart(args));
+
+        // ── LevelDB 读写（同构，前后端均可用）──
+        case "read": {
+            if (looksLikeLocalFilePath(args.filePath)) {
+                return postMain("/api/read-file", {
+                    filePath: args.filePath,
+                    startLine: args.startLine,
+                    endLine: args.endLine,
+                });
+            }
+            const dbKey = args.dbKey;
+            if (!dbKey) return JSON.stringify({ error: "read: dbKey is required" });
+            const blockedReadResult = guardWorkspaceRead(dbKey, context);
+            if (blockedReadResult) return blockedReadResult;
+            const res = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(dbKey)}`, {
+                headers: { Authorization: `Bearer ${authToken}` },
+            });
+            if (!res.ok) return JSON.stringify({ error: `read: HTTP ${res.status}`, detail: await res.text() });
+            recordWorkspaceRead(dbKey, context);
+            return res.text();
+        }
+        case "searchDialogMessages": {
+            const dialogKey = normalizeDialogSearchText(args.dialogKey);
+            const query = normalizeDialogSearchText(args.query);
+            if (!dialogKey.startsWith("dialog-")) {
+                return JSON.stringify({ error: "searchDialogMessages: dialogKey must be a dialog-* dbKey" });
+            }
+            if (!query) {
+                return JSON.stringify({ error: "searchDialogMessages: query is required" });
+            }
+            const blockedReadResult = guardWorkspaceRead(dialogKey, context);
+            if (blockedReadResult) return blockedReadResult;
+            const dialogId = dialogKey.split("-").at(-1) || dialogKey;
+            const scanLimit = clampDialogSearchNumber(
+                args.scanLimit,
+                SEARCH_DIALOG_MESSAGES_SCAN_LIMIT,
+                1,
+                SEARCH_DIALOG_MESSAGES_SCAN_LIMIT,
+            );
+            const resultLimit = clampDialogSearchNumber(args.limit, 5, 1, SEARCH_DIALOG_MESSAGES_RESULT_LIMIT);
+            const contextMessages = clampDialogSearchNumber(
+                args.contextMessages,
+                1,
+                0,
+                SEARCH_DIALOG_MESSAGES_CONTEXT_LIMIT,
+            );
+            const res = await fetch(`${mainBase}/rpc/getConvMsgs`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${authToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ dialogId, limit: scanLimit }),
+            });
+            if (!res.ok) {
+                return JSON.stringify({ error: `searchDialogMessages: HTTP ${res.status}`, detail: await res.text() });
+            }
+            const newestFirst = await res.json();
+            const messages = Array.isArray(newestFirst) ? [...newestFirst].reverse() : [];
+            const matches = buildDialogMessageSearchResults({
+                messages,
+                query,
+                limit: resultLimit,
+                contextMessages,
+                role: typeof args.role === "string" ? args.role : undefined,
+                includeTools: args.includeTools,
+                contentClipChars: SEARCH_DIALOG_MESSAGES_CLIP_CHARS,
+                contextClipChars: SEARCH_DIALOG_MESSAGES_CONTEXT_CLIP_CHARS,
+            });
+            recordWorkspaceRead(dialogKey, context);
+            return JSON.stringify({
+                success: true,
+                dialogKey,
+                query,
+                scannedMessages: messages.length,
+                matches,
+            });
+        }
+        case "readDoc":
+        case "readPage": {
+            const id = typeof args.id === "string" ? args.id.trim() : "";
+            if (!id) return JSON.stringify({ error: `${serverToolName}: id is required` });
+            const blockedReadResult = guardWorkspaceRead(id, context);
+            if (blockedReadResult) return blockedReadResult;
+            const res = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(id)}`, {
+                headers: { Authorization: `Bearer ${authToken}` },
+            });
+            if (!res.ok) {
+                return JSON.stringify({
+                    error: `${serverToolName}: HTTP ${res.status}`,
+                    detail: await res.text(),
+                });
+            }
+            const page = await res.json();
+            recordWorkspaceRead(id, context);
+            return JSON.stringify(buildReadDocResult(page).rawData);
+        }
+        case "deleteSpaces": {
+            if (!context?.userId) {
+                return JSON.stringify({ error: "deleteSpaces: userId is required" });
+            }
+
+            const query = typeof args.query === "string" ? args.query.trim() : "";
+            if (!query) {
+                return JSON.stringify({ error: "deleteSpaces: query is required" });
+            }
+
+            const membershipsRes = await postJson(mainBase, "/rpc/getUserSpaceMemberships", {
+                userId: context.userId,
+            });
+            if (!membershipsRes.ok || !Array.isArray(membershipsRes.data)) {
+                return JSON.stringify({
+                    error: `deleteSpaces: membership HTTP ${membershipsRes.status}`,
+                    detail: membershipsRes.text,
+                });
+            }
+
+            const candidates = filterSpaceDeletionCandidates(
+                membershipsRes.data as SpaceMembershipLike[],
+                {
+                    query,
+                    matchMode: args.matchMode,
+                }
+            );
+            const spaceRecordsById: Record<string, SpaceRecordLike | null> = {};
+            for (const candidate of candidates) {
+                const spaceId = String(candidate.spaceId ?? "").replace(/^space-/, "");
+                if (!spaceId) continue;
+                const readRes = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(createSpaceKey.space(spaceId))}`, {
+                    headers: buildAuthHeaders(),
+                });
+                if (!readRes.ok) {
+                    spaceRecordsById[spaceId] = null;
+                    continue;
+                }
+                try {
+                    spaceRecordsById[spaceId] = await readRes.json();
+                } catch {
+                    spaceRecordsById[spaceId] = null;
+                }
+            }
+
+            const preview = buildDeleteSpacesPreview({
+                currentUserId: context.userId,
+                candidates,
+                spaceRecordsById,
+            });
+
+            const confirmedSpaceIds = Array.isArray(args.confirmedSpaceIds)
+                ? args.confirmedSpaceIds.filter((id: unknown): id is string => typeof id === "string" && id.trim())
+                : [];
+            if (confirmedSpaceIds.length === 0) {
+                return JSON.stringify({
+                    requiresConfirmation: true,
+                    message:
+                        "请让用户确认后，再带 confirmedSpaceIds 调用 deleteSpaces。只会删除 Space 壳和成员关系，不删除挂载内容。",
+                    ...preview,
+                });
+            }
+
+            const { targets, missingConfirmedSpaceIds } =
+                resolveConfirmedSpaceDeletionTargets(preview, confirmedSpaceIds);
+            const deletedSpaceIds: string[] = [];
+            const deletedKeys: string[] = [];
+            const failures: Array<{ dbKey: string; status: number; detail: string }> = [];
+
+            for (const target of targets) {
+                const record = spaceRecordsById[target.spaceId];
+                if (!record) continue;
+                const keys = [
+                    ...spaceMemberKeysForDelete(target.spaceId, record),
+                    createSpaceKey.space(target.spaceId),
+                ];
+                let targetFailed = false;
+                for (const key of keys) {
+                    const result = await deleteDbKey(key);
+                    if (!result.ok) {
+                        targetFailed = true;
+                        failures.push({ dbKey: key, status: result.status, detail: result.text });
+                    } else {
+                        deletedKeys.push(key);
+                    }
+                }
+                if (!targetFailed) deletedSpaceIds.push(target.spaceId);
+            }
+
+            return JSON.stringify({
+                deletedSpaceIds,
+                deletedKeys,
+                missingConfirmedSpaceIds,
+                skipped: preview.skipped,
+                failures,
+            });
+        }
+        case "createDoc":
+        case "createPage": {
+            const blockedKnowledgeResult = guardKnowledgeCapture({
+                context,
+                target: "doc",
+            });
+            if (blockedKnowledgeResult) return blockedKnowledgeResult;
+            const res = await fetch(`${mainBase}/api/page/create`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                body: JSON.stringify({
+                    title: args.title ?? "新文档",
+                    content: args.content ?? "",
+                    spaceId: args.spaceId,
+                    categoryId: args.categoryId,
+                }),
+            });
+            if (!res.ok) return JSON.stringify({ error: `createDoc: HTTP ${res.status}`, detail: await res.text() });
+            recordKnowledgeCapture(context);
+            return res.text();
+        }
+        case "createSkillDoc": {
+            let title = "New Skill";
+            let content = "";
+            try {
+                const built = buildSkillDocFromArgs(args as CreateSkillDocArgs);
+                title = built.title;
+                content = built.content;
+            } catch (error: any) {
+                return JSON.stringify({
+                    error: "createSkillDoc",
+                    detail: typeof error?.message === "string" ? error.message : String(error),
+                });
+            }
+
+            const blockedKnowledgeResult = guardKnowledgeCapture({
+                context,
+                target: "doc",
+            });
+            if (blockedKnowledgeResult) return blockedKnowledgeResult;
+
+            const res = await fetch(`${mainBase}/api/page/create`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                body: JSON.stringify({
+                    title,
+                    content,
+                    spaceId: args.spaceId,
+                    categoryId: args.categoryId,
+                }),
+            });
+            if (!res.ok) {
+                return JSON.stringify({ error: `createSkillDoc: HTTP ${res.status}`, detail: await res.text() });
+            }
+            recordKnowledgeCapture(context);
+            const created = await res.json();
+            return JSON.stringify(
+                buildSkillFollowupResult({
+                    dbKey: created?.dbKey ?? created?.id ?? "",
+                    title: created?.title ?? title,
+                    skillId: (args as CreateSkillDocArgs).name || undefined,
+                    spaceId: created?.spaceId ?? args.spaceId ?? null,
+                    toolNames: Array.isArray((args as CreateSkillDocArgs).toolNames)
+                        ? (args as CreateSkillDocArgs).toolNames
+                        : [],
+                    hasEvalConfig: Array.isArray((args as CreateSkillDocArgs).evalCases)
+                        && (args as CreateSkillDocArgs).evalCases!.length > 0,
+                }).rawData
+            );
+        }
+        case "doctorSkill": {
+            let page: any = null;
+            if (typeof args.id === "string" && args.id.trim()) {
+                const res = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(args.id.trim())}`, {
+                    headers: { Authorization: `Bearer ${authToken}` },
+                });
+                if (!res.ok) {
+                    return JSON.stringify({ error: `doctorSkill: HTTP ${res.status}`, detail: await res.text() });
+                }
+                page = await res.json();
+            }
+            const result = await diagnoseSkillDocument(
+                {
+                    id: page?.dbKey ?? args.id,
+                    title: page?.title,
+                    content: typeof args.content === "string" ? args.content : page?.content ?? "",
+                    meta: resolvePageSkillMetadata(page),
+                    tools: page?.tools,
+                },
+            );
+            return JSON.stringify(result);
+        }
+        case "evalSkill": {
+            let page: any = null;
+            const loadPage = async (dbKey: string) => {
+                const res = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(dbKey)}`, {
+                    headers: { Authorization: `Bearer ${authToken}` },
+                });
+                if (!res.ok) return undefined;
+                return res.json();
+            };
+            if (typeof args.id === "string" && args.id.trim()) {
+                page = await loadPage(args.id.trim());
+                if (!page) {
+                    return JSON.stringify({ error: `evalSkill: 未找到 ${args.id}` });
+                }
+            }
+            const result = await evaluateSkillDocument(
+                {
+                    id: page?.dbKey ?? args.id,
+                    title: page?.title,
+                    content: typeof args.content === "string" ? args.content : page?.content ?? "",
+                    meta: resolvePageSkillMetadata(page),
+                    tools: page?.tools,
+                },
+                {
+                    loadPage,
+                },
+            );
+            return JSON.stringify(result);
+        }
+        case "createSkillAgent": {
+            if (!context?.userId) {
+                return JSON.stringify({ error: "createSkillAgent: missing userId in execution context" });
+            }
+
+            const agent = buildSkillAgentRecord({
+                userId: context.userId,
+                currentSpaceId: context.currentSpaceId ?? undefined,
+                args: args as CreateSkillAgentToolArgs,
+            });
+
+            const res = await fetch(`${mainBase}/api/v1/db/write/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                body: JSON.stringify({
+                    userId: context.userId,
+                    customKey: agent.dbKey,
+                    data: agent,
+                }),
+            });
+            if (!res.ok) {
+                return JSON.stringify({ error: `createSkillAgent: HTTP ${res.status}`, detail: await res.text() });
+            }
+            if (agent.isPublic) {
+                const publicRes = await fetch(`${mainBase}/api/v1/db/write/`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                    body: JSON.stringify({
+                        userId: context.userId,
+                        customKey: agent.publicDbKey,
+                        data: agent,
+                    }),
+                });
+                if (!publicRes.ok) {
+                    return JSON.stringify({
+                        error: `createSkillAgent(public): HTTP ${publicRes.status}`,
+                        detail: await publicRes.text(),
+                    });
+                }
+            }
+            return res.text();
+        }
+        case "prepareAgentDraft": {
+            const result = await prepareAgentDraftToolFunc(args as PrepareAgentDraftToolArgs);
+            return JSON.stringify(result);
+        }
+        case "createAgent": {
+            if (!context?.userId) {
+                return JSON.stringify({ error: "createAgent: missing userId in execution context" });
+            }
+            let agent: ReturnType<typeof buildServerCreatedAgentRecord>;
+            try {
+                agent = buildServerCreatedAgentRecord(
+                    context.userId,
+                    args as CreateAgentToolArgs,
+                    context.currentSpaceId,
+                );
+            } catch (error) {
+                return JSON.stringify({
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            const privateKey = createAgentKey.private(context.userId, agent.id);
+            const publicKey = createAgentKey.public(agent.id);
+            const writeAgent = async (customKey: string) =>
+                fetch(`${mainBase}/api/v1/db/write/`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                    body: JSON.stringify({
+                        userId: context.userId,
+                        customKey,
+                        data: agent,
+                    }),
+                });
+
+            const privateRes = await writeAgent(privateKey);
+            if (!privateRes.ok) {
+                return JSON.stringify({
+                    error: `createAgent(private): HTTP ${privateRes.status}`,
+                    detail: await privateRes.text(),
+                });
+            }
+            if (agent.isPublic) {
+                const publicRes = await writeAgent(publicKey);
+                if (!publicRes.ok) {
+                    return JSON.stringify({
+                        error: `createAgent(public): HTTP ${publicRes.status}`,
+                        detail: await publicRes.text(),
+                    });
+                }
+            }
+            return JSON.stringify({
+                rawData: {
+                    ...agent,
+                    dbKey: privateKey,
+                    publicDbKey: agent.isPublic ? publicKey : undefined,
+                },
+                displayData: [
+                    `已创建 Agent: ${agent.name}`,
+                    `- ID: ${agent.id}`,
+                    `- 模型: ${agent.model}`,
+                    `- Provider: ${agent.provider}`,
+                    `- 是否公开: ${agent.isPublic ? "是" : "否"}`,
+                    agent.isPublic ? `- Public Key: ${publicKey}` : "",
+                ].filter(Boolean).join("\n"),
+            });
+        }
+        case "importSkill": {
+            const sourceUrl = typeof args.url === "string" ? normalizeSkillImportUrl(args.url) : "";
+            let rawMarkdown =
+                typeof args.content === "string" ? args.content.trim() : "";
+            if (!rawMarkdown && !sourceUrl) {
+                return JSON.stringify({ error: "importSkill: url 或 content 至少需要一个" });
+            }
+            if (!rawMarkdown) {
+                const sourceRes = await fetch(sourceUrl);
+                if (!sourceRes.ok) {
+                    return JSON.stringify({
+                        error: `importSkill(fetch): HTTP ${sourceRes.status}`,
+                        detail: await sourceRes.text(),
+                    });
+                }
+                rawMarkdown = (await sourceRes.text()).trim();
+            }
+
+            const parsed = parseExternalSkillMarkdown(rawMarkdown);
+            const title = typeof args.title === "string" && args.title.trim()
+                ? args.title.trim()
+                : parsed.name || "Imported Skill";
+            const skillConfig: SkillDocConfig = {
+                version: "0.1",
+                kind: "skill",
+                id:
+                    (parsed.name || title)
+                        .trim()
+                        .toLowerCase()
+                        .replace(/[^a-z0-9]+/g, "-")
+                        .replace(/^-+|-+$/g, "") || "imported-skill",
+                name: parsed.name || title,
+                description: parsed.description || "Imported external skill.",
+                triggerMode: "explicit",
+                toolNames: parsed.allowedTools,
+                budgetTier: "medium",
+                dispatchPreferred: false,
+                modalities: ["text"],
+            };
+            const content = buildSkillDocMarkdown({
+                body: [
+                    parsed.body,
+                    parsed.compatibility ? `## Compatibility\n${parsed.compatibility}` : "",
+                    sourceUrl ? `Imported from: ${sourceUrl}` : "",
+                ]
+                    .filter(Boolean)
+                    .join("\n\n"),
+                skillConfig,
+            });
+
+            const blockedKnowledgeResult = guardKnowledgeCapture({
+                context,
+                target: "doc",
+            });
+            if (blockedKnowledgeResult) return blockedKnowledgeResult;
+
+            const res = await fetch(`${mainBase}/api/page/create`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                body: JSON.stringify({
+                    title,
+                    content,
+                    spaceId: args.spaceId,
+                    categoryId: args.categoryId,
+                }),
+            });
+            if (!res.ok) {
+                return JSON.stringify({ error: `importSkill: HTTP ${res.status}`, detail: await res.text() });
+            }
+            recordKnowledgeCapture(context);
+            const created = await res.json();
+            return JSON.stringify(
+                buildSkillFollowupResult({
+                    dbKey: created?.dbKey ?? created?.id ?? "",
+                    title: created?.title ?? title,
+                    skillId: skillConfig.id,
+                    spaceId: created?.spaceId ?? args.spaceId ?? null,
+                    toolNames: skillConfig.toolNames ?? [],
+                    importedFrom: sourceUrl || null,
+                    hasEvalConfig: false,
+                }).rawData
+            );
+        }
+        case "shareTable": {
+            const blockedShareResult = guardPublicTableShare(context);
+            if (blockedShareResult) return blockedShareResult;
+            if (!context?.userId) {
+                return JSON.stringify({ error: "shareTable requires an authenticated user." });
+            }
+
+            const tableDbKey =
+                typeof args.dbKey === "string" && args.dbKey.trim()
+                    ? args.dbKey.trim()
+                    : typeof args.tenantId === "string" &&
+                        args.tenantId.trim() &&
+                        typeof args.tableId === "string" &&
+                        args.tableId.trim()
+                      ? `meta-${args.tenantId.trim()}-${args.tableId.trim()}`
+                      : "";
+            if (!tableDbKey) {
+                return JSON.stringify({
+                    error: "shareTable requires dbKey, or both tenantId and tableId.",
+                });
+            }
+
+            const tableReadRes = await fetch(
+                `${mainBase}/api/v1/db/read/${encodeURIComponent(tableDbKey)}`,
+                { headers: buildAuthHeaders() },
+            );
+            if (!tableReadRes.ok) {
+                return JSON.stringify({
+                    error: `shareTable: failed to read table meta (${tableReadRes.status})`,
+                    detail: await tableReadRes.text(),
+                });
+            }
+            const tableReadPayload = await tableReadRes.json();
+            const tableMeta = tableReadPayload?.data ?? tableReadPayload;
+            const tableOwnerId =
+                (typeof args.tenantId === "string" && args.tenantId.trim()) ||
+                (typeof tableMeta?.tenantId === "string" && tableMeta.tenantId.trim()) ||
+                context.userId;
+            const tableId =
+                (typeof args.tableId === "string" && args.tableId.trim()) ||
+                (typeof tableMeta?.tableId === "string" && tableMeta.tableId.trim()) ||
+                tableDbKey;
+
+            let settings: any = null;
+            try {
+                const settingsRes = await fetch(
+                    `${mainBase}/api/v1/db/read/${encodeURIComponent(createUserKey.settings(context.userId))}`,
+                    { headers: buildAuthHeaders() },
+                );
+                if (settingsRes.ok) {
+                    const settingsPayload = await settingsRes.json();
+                    settings = settingsPayload?.data ?? settingsPayload;
+                }
+            } catch {
+                settings = null;
+            }
+
+            const originServer =
+                normalizeServerOrigin(settings?.currentServer) ??
+                normalizeServerOrigin(mainBase) ??
+                normalizeBase(mainBase);
+            const fanoutServers = buildFanoutServerList(originServer, settings?.syncServers);
+            const token = generateShareToken();
+            const dbKey = shareKey.create(token);
+            const createdAt = Date.now();
+            const title =
+                (typeof args.title === "string" && args.title.trim()) ||
+                (typeof tableMeta?.displayName === "string" && tableMeta.displayName.trim()) ||
+                tableId;
+            const description =
+                typeof args.description === "string" && args.description.trim()
+                    ? args.description.trim()
+                    : undefined;
+            const visibility = args.visibility === "private" ? "private" : "community";
+
+            const sharedObject = {
+                type: DataType.TABLE,
+                version: 1,
+                data: {
+                    mode: "live",
+                    tableDbKey,
+                    tableOwnerId,
+                    originServer,
+                },
+                meta: {
+                    authorId: context.userId,
+                    createdAt,
+                    visibility,
+                    title,
+                    description,
+                    originalId: tableDbKey,
+                    mode: "live",
+                    tableDbKey,
+                    tableOwnerId,
+                    originServer,
+                },
+            };
+            const indexKeys = shareKey.allIndexKeysFromShare(dbKey, sharedObject);
+            const writeBody = {
+                data: sharedObject,
+                customKey: dbKey,
+                userId: context.userId,
+                indexKeys,
+            };
+            const originResult = {
+                server: originServer,
+                ...(await postJson(originServer, "/api/v1/db/write/", writeBody)),
+            };
+            if (!originResult.ok) {
+                return JSON.stringify({
+                    error: "shareTable: failed to publish on origin server",
+                    originServer,
+                    detail: originResult.text ?? "",
+                });
+            }
+            const replicaServers = fanoutServers.filter(
+                (server) => normalizeServerOrigin(server) !== originServer,
+            );
+            const replicaResults = await Promise.all(
+                replicaServers.map(async (server) => ({
+                    server,
+                    ...(await postJson(server, "/api/v1/db/write/", writeBody)),
+                })),
+            );
+            const writeResults = [originResult, ...replicaResults];
+
+            const replicaFailures = writeResults
+                .filter(
+                    (result) =>
+                        normalizeServerOrigin(result.server) !== originServer && !result.ok,
+                )
+                .map((result) => ({
+                    server: result.server,
+                    status: result.status,
+                    detail: result.text,
+                }));
+
+            return JSON.stringify({
+                token,
+                key: dbKey,
+                url: `/share/${token}`,
+                originServer,
+                replicatedServers: fanoutServers,
+                ...(replicaFailures.length > 0 ? { replicaFailures } : {}),
+            });
+        }
+        case "createTable":
+            {
+                const blockedKnowledgeResult = guardKnowledgeCapture({
+                    context,
+                    target: "table",
+                });
+                if (blockedKnowledgeResult) return blockedKnowledgeResult;
+            }
+            {
+                const result = await postMain("/api/table/create", {
+                spaceId: args.spaceId,
+                title: args.title,
+                description: args.description,
+                tags: args.tags,
+                categoryId: args.categoryId,
+                columns: args.columns,
+                withDefaultRows: args.withDefaultRows,
+            });
+                recordKnowledgeCapture(context);
+                return result;
+            }
+        case "addTableRow":
+            return postMain(
+                "/api/table/add-row",
+                withFeedbackSubmitterUserId({
+                    tenantId: args.tenantId,
+                    tableId: args.tableId,
+                    values: args.values,
+                }),
+            );
+        case "queryTableRows":
+            return postMain("/api/table/query-rows", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                filters: args.filters,
+                columns: args.columns,
+                limit: args.limit,
+                offset: args.offset,
+                includeBaseFields: args.includeBaseFields,
+                sortBy: args.sortBy,
+                sortOrder: args.sortOrder,
+            });
+        case "updateTableRow":
+            return postMain("/api/table/update-row", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                rowId: args.rowId,
+                dbKey: args.dbKey,
+                changes: args.changes,
+            });
+        case "deleteTableRow":
+            {
+                const blockedDeleteResult = guardDestructiveAction({
+                    context,
+                    target: "table_row_delete",
+                    detail: "deleteTableRow",
+                });
+                if (blockedDeleteResult) return blockedDeleteResult;
+            }
+            return postMain("/api/table/delete-row", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                rowId: args.rowId,
+                dbKey: args.dbKey,
+            });
+        case "addTableRows":
+            return postMain("/api/table/add-rows", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                rows: args.rows,
+            });
+        case "updateTableRows":
+            return postMain("/api/table/update-rows", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                updates: args.updates,
+            });
+        case "deleteTableRows":
+            {
+                const blockedDeleteResult = guardDestructiveAction({
+                    context,
+                    target: "table_row_delete",
+                    detail: "deleteTableRows",
+                });
+                if (blockedDeleteResult) return blockedDeleteResult;
+            }
+            return postMain("/api/table/delete-rows", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                rowIds: args.rowIds,
+                dbKeys: args.dbKeys,
+            });
+        case "addTableColumn":
+            return postMain("/api/table/add-column", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                name: args.name,
+                label: args.label,
+                type: args.type,
+                description: args.description,
+                required: args.required,
+                options: args.options,
+            });
+        case "deleteTableColumn":
+            {
+                const blockedDeleteResult = guardDestructiveAction({
+                    context,
+                    target: "table_column_delete",
+                    detail: "deleteTableColumn",
+                });
+                if (blockedDeleteResult) return blockedDeleteResult;
+            }
+            return postMain("/api/table/delete-column", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                columnName: args.columnName,
+            });
+        case "renameTableColumn":
+            return postMain("/api/table/rename-column", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                oldName: args.oldName,
+                newName: args.newName,
+            });
+        case "renameTableColumnLabel":
+            return postMain("/api/table/rename-column-label", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                columnName: args.columnName,
+                newLabel: args.newLabel,
+            });
+        case "renameTable":
+            return postMain("/api/table/rename", {
+                tenantId: args.tenantId,
+                tableId: args.tableId,
+                newName: args.newName,
+            });
+
+        case "updateDoc":
+        case "update_page": {
+            const { id, title, content, mode = "replace" } = args;
+            if (!id) return JSON.stringify({ error: "updateDoc: id (dbKey) is required" });
+            if (typeof content !== "string") {
+                return JSON.stringify({ error: "updateDoc: content is required" });
+            }
+
+            const existingRes = await fetch(`${mainBase}/api/v1/db/read/${encodeURIComponent(id)}`, {
+                headers: { Authorization: `Bearer ${authToken}` },
+            });
+            if (!existingRes.ok) {
+                return JSON.stringify({ error: `updateDoc(read): HTTP ${existingRes.status}`, detail: await existingRes.text() });
+            }
+
+            const existing = await existingRes.json();
+            const currentMarkdown =
+                typeof existing?.content === "string" && existing.content.trim()
+                    ? existing.content
+                    : slateToRenderMarkdown(
+                        Array.isArray(existing?.slateData) ? existing.slateData : [],
+                    );
+            const mergedMarkdown = mode === "append"
+                ? [currentMarkdown, content].filter(Boolean).join("\n\n")
+                : content;
+            const parsedProtocol = parseSkillDocProtocol(
+                mergedMarkdown,
+                existing?.meta,
+                existing?.tools,
+            );
+            const slateData = markdownToSlate(parsedProtocol.content) as any[];
+            const tools = extractMentionsFromSlate(slateData as any);
+
+            const changes: Record<string, any> = {
+                slateData,
+                content: parsedProtocol.content,
+                tools,
+                ...(parsedProtocol.meta ? { meta: parsedProtocol.meta } : {}),
+                updated_at: new Date().toISOString(),
+            };
+            if (typeof title === "string" && title.trim()) {
+                changes.title = title.trim();
+            }
+
+            const res = await fetch(`${mainBase}/api/v1/db/patch/${encodeURIComponent(id)}`, {
+                method: "PATCH",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                body: JSON.stringify(changes),
+            });
+            if (!res.ok) return JSON.stringify({ error: `updateDoc: HTTP ${res.status}`, detail: await res.text() });
+            return JSON.stringify({ success: true, id, title: changes.title ?? existing?.title });
+        }
+
+        // ── 数据库（服务端专属）──
+        case "executeSql":
+            return postMain("/api/v1/sqlite/execute_sql", { sql: args.sql, params: args.params });
+
+        // ── 文件系统 / shell（由目标 server 直接提供）──
+        case "readFile":
+            return postMain("/api/read-file", { filePath: args.filePath, startLine: args.startLine, endLine: args.endLine });
+        case "writeFile":
+            return postMain("/api/write-file", { filePath: args.filePath, content: args.content, overwrite: args.overwrite });
+        case "applyEdit":
+            return postMain("/api/apply-edit", { filePath: args.filePath, edits: args.edits });
+        case "execShell":
+            if (isDestructiveShellCommand({ command: args.command, input: args.input })) {
+                const blockedDeleteResult = guardDestructiveAction({
+                    context,
+                    target: "shell_command",
+                    detail: "execShell destructive command",
+                });
+                if (blockedDeleteResult) return blockedDeleteResult;
+            }
+            return postMain("/api/exec-shell", {
+                command: args.command,
+                cwd: args.cwd,
+                shell: args.shell,
+                interactive: args.interactive,
+                pty: args.pty,
+                sessionId: args.sessionId,
+                input: args.input,
+                close: args.close,
+            });
+        case "codeSearch":
+            return postMain("/api/code-search", {
+                query: args.query,
+                path: args.path ?? args.pathScope ?? args.dirPath,
+                glob: args.glob,
+                mode: args.mode ?? "content",
+                maxResults: args.maxResults ?? args.maxFiles,
+                caseSensitive: args.caseSensitive,
+            });
+        case "search_workspace":
+            return postMain("/api/search-repo", {
+                query: args.query,
+                pathScope: args.pathScope,
+                maxResults: args.maxResults,
+                contextLines: args.contextLines,
+            });
+        case "applyLineEdits":
+            return postMain("/api/apply-line-edits", { filePath: args.filePath, edits: args.edits });
+        case "checkEnv":
+        case "check_env":
+            return postMain("/api/check-env", { check: args.check ?? "build" });
+
+        // ── 浏览器自动化（服务端 Puppeteer）──
+        case "browser_openSession":
+        case "browser_closeSession":
+        case "browser_selectOption":
+        case "browser_click":
+        case "browser_typeText":
+        case "browser_readContent":
+        case "browser_probePage":
+            return postMain("/api/browser-tool", {
+                toolName: serverToolName,
+                params: args,
+            });
+
+        case "email_provision_identity": {
+            const missingAgentKey = requireCurrentAgentKey();
+            if (missingAgentKey) return missingAgentKey;
+            const result = await postJson(mainBase, "/rpc/provisionAgentEmailIdentity", {
+                ...args,
+                agentId: currentAgentKey,
+            });
+            if (!result.ok) {
+                return JSON.stringify(
+                    result.data ?? {
+                        error: `email_provision_identity: HTTP ${result.status}`,
+                        detail: result.text,
+                    },
+                );
+            }
+            return JSON.stringify(result.data ?? {});
+        }
+        case "email_wait_for": {
+            const missingAgentKey = requireCurrentAgentKey();
+            if (missingAgentKey) return missingAgentKey;
+
+            const timeoutSecondsRaw =
+                typeof args.timeoutSeconds === "number"
+                    ? args.timeoutSeconds
+                    : Number(args.timeoutSeconds ?? 60);
+            const timeoutMs = Math.min(Math.max(timeoutSecondsRaw, 1), 180) * 1000;
+            const pollIntervalRaw =
+                typeof args.pollIntervalMs === "number"
+                    ? args.pollIntervalMs
+                    : Number(args.pollIntervalMs ?? 3000);
+            const pollIntervalMs = Math.min(Math.max(pollIntervalRaw, 500), 10_000);
+            const limitRaw =
+                typeof args.limit === "number" ? args.limit : Number(args.limit ?? 20);
+            const limit = Math.min(Math.max(limitRaw, 1), 200);
+            const startedAt = Date.now();
+            let attempts = 0;
+
+            while (Date.now() - startedAt <= timeoutMs) {
+                attempts += 1;
+                const result = await postJson(mainBase, "/rpc/listEmails", {
+                    ownerId: currentAgentKey,
+                    mailbox: typeof args.mailbox === "string" ? args.mailbox : "inbox",
+                    status: args.status,
+                    tag: args.tag,
+                    limit,
+                });
+                if (!result.ok) {
+                    return JSON.stringify(
+                        result.data ?? {
+                            error: `email_wait_for: HTTP ${result.status}`,
+                            detail: result.text,
+                        },
+                    );
+                }
+                const items = Array.isArray(result.data) ? result.data : [];
+                const match = items.find(
+                    (email) => emailIsFreshForWait(email, startedAt) && emailMatchesWaitFilters(email, args),
+                );
+                if (match) {
+                    return JSON.stringify({
+                        email: match,
+                        attempts,
+                        waitedMs: Date.now() - startedAt,
+                    });
+                }
+                await sleep(pollIntervalMs);
+            }
+
+            return JSON.stringify({
+                error: `等待邮件超时：${Math.ceil(timeoutMs / 1000)} 秒内没有匹配邮件`,
+            });
+        }
+        case "email_extract_verification": {
+            let email: any = null;
+            let text = typeof args.text === "string" ? args.text : undefined;
+            let html = typeof args.html === "string" ? args.html : undefined;
+            if (typeof args.dbKey === "string" && args.dbKey.trim()) {
+                const result = await postJson(mainBase, "/rpc/getEmail", {
+                    dbKey: args.dbKey.trim(),
+                });
+                if (!result.ok) {
+                    return JSON.stringify(
+                        result.data ?? {
+                            error: `email_extract_verification: HTTP ${result.status}`,
+                            detail: result.text,
+                        },
+                    );
+                }
+                email = result.data;
+                text = typeof email?.text === "string" ? email.text : text;
+                html = typeof email?.html === "string" ? email.html : html;
+            }
+            if (!text && !html) {
+                return JSON.stringify({
+                    error: "必须提供 dbKey、text 或 html 中至少一个",
+                });
+            }
+            return JSON.stringify({
+                email,
+                ...extractEmailVerificationArtifacts({ text, html }),
+            });
+        }
+
+        // ── 应用部署管理 ──
+        case "appPreflight":
+            return postMain("/api/app/preflight", {
+                name: args.name,
+                code: args.code,
+                files: normalizeAppFiles(),
+                appId: args.appId,
+                framework: args.framework,
+                spaceId: args.spaceId,
+            });
+        case "appDeploy": {
+            const nextFiles = normalizeAppFiles();
+            const guardUserInput =
+                typeof context?.userInput === "string" ? context.userInput.trim() : "";
+            if (args.appId && guardUserInput && (typeof args.code === "string" || (Array.isArray(nextFiles) && nextFiles.length > 0))) {
+                const previousRead = await postJson(mainBase, "/api/app/prepare-edit", {
+                    appId: args.appId,
+                });
+                if (previousRead.ok) {
+                    const guardResult = evaluateSmallVisualEditGuard({
+                        userInput: guardUserInput,
+                        previousSource: previousRead.data ?? {},
+                        nextSource: {
+                            code: typeof args.code === "string" ? args.code : undefined,
+                            files: nextFiles,
+                        },
+                    });
+                    if (!guardResult.ok) {
+                        return JSON.stringify(guardResult.rawData);
+                    }
+                }
+            }
+
+            const deployStart = await postJson(mainBase, "/api/app/deploy", {
+                name: args.name,
+                code: args.code,
+                files: nextFiles,
+                appId: args.appId,
+                framework: args.framework,
+                spaceId: args.spaceId,
+            });
+            if (!deployStart.ok) {
+                return JSON.stringify(
+                    deployStart.data ?? {
+                        error: `appDeploy: HTTP ${deployStart.status}`,
+                        detail: deployStart.text,
+                    },
+                );
+            }
+
+            const jobId =
+                typeof deployStart.data?.jobId === "string"
+                    ? deployStart.data.jobId
+                    : "";
+            if (!jobId) {
+                return deployStart.text;
+            }
+            return waitForAppDeployResult(jobId);
+        }
+        case "appList":
+            return postMain("/api/app/list", args.spaceId ? { spaceId: args.spaceId } : {});
+        case "appDelete": {
+            if (!args.appId) {
+                return JSON.stringify({ error: "appDelete: appId is required; call appList first" });
+            }
+            {
+                const blockedDeleteResult = guardDestructiveAction({
+                    context,
+                    target: "app_delete",
+                    detail: "appDelete",
+                });
+                if (blockedDeleteResult) return blockedDeleteResult;
+            }
+            const lookupRes = await fetch(`${mainBase}/api/app/get`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${authToken}` },
+                body: JSON.stringify({ appId: args.appId }),
+            });
+            if (!lookupRes.ok) {
+                return JSON.stringify({ error: `appDelete lookup: HTTP ${lookupRes.status}`, detail: await lookupRes.text() });
+            }
+            const lookupJson = await lookupRes.json().catch(() => null) as { appKey?: string } | null;
+            if (!lookupJson?.appKey) {
+                return JSON.stringify({ error: "appDelete: appKey not found" });
+            }
+            const deleteRes = await fetch(`${mainBase}/api/v1/db/delete/${encodeURIComponent(lookupJson.appKey)}`, {
+                method: "DELETE",
+                headers: { Authorization: `Bearer ${authToken}` },
+            });
+            if (!deleteRes.ok) {
+                return JSON.stringify({ error: `appDelete: HTTP ${deleteRes.status}`, detail: await deleteRes.text() });
+            }
+            return deleteRes.text();
+        }
+        case "appRead":
+            if (!args.appId) {
+                return JSON.stringify({ error: "appRead: appId is required; call appList first" });
+            }
+            {
+                const readResult = await postJson(mainBase, "/api/app/prepare-edit", {
+                    appId: args.appId,
+                });
+                if (!readResult.ok) {
+                    return JSON.stringify(
+                        readResult.data ?? {
+                            error: `appRead: HTTP ${readResult.status}`,
+                            detail: readResult.text,
+                        },
+                    );
+                }
+                const styleSystemAnalysis = analyzeAppStyleSystem(readResult.data ?? {});
+                const styleSystemHint = buildAppStyleSystemHint(styleSystemAnalysis);
+                return JSON.stringify({
+                    ...(readResult.data ?? {}),
+                    styleSystemStatus: styleSystemAnalysis.status,
+                    legacyMigrationRecommended:
+                        styleSystemAnalysis.legacyMigrationRecommended,
+                    styleSystemEvidence: styleSystemAnalysis.evidence,
+                    ...(styleSystemHint ? { styleSystemHint } : {}),
+                });
+            }
+
+        default:
+            return JSON.stringify({
+                error: `Tool "${toolCall.function.name}" is not available in server-side agent mode.`,
+            });
+    }
+}