nolo-cli 0.1.30 → 0.1.32

package/server/handlers/agentRun/toolExecutor.ts

@@ -1,2909 +0,0 @@
-// 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.`,
-            });
-    }
-}