nolo-cli 0.1.39 → 0.1.41

package/ai/agent/runAgentBackground.ts

@@ -0,0 +1,310 @@
+// packages/ai/agent/runAgentBackground.ts
+// 后台运行 agent 并通过 SSE 监听结果
+//
+// 使用方式（在组件/thunk 中）：
+//   dispatch(runAgentBackground({
+//     agentKey: "agent-xxx",
+//     userInput: "帮我搜索...",
+//     spaceId: "space-yyy",       // 可选，写入 space 索引
+//     onStatusChange: (s) => ..., // 可选，实时更新 UI 状态
+//     onDone: (result) => ...,    // 可选，成功回调
+//     onFailed: (error) => ...,   // 可选，失败回调
+//   }));
+
+import { createAsyncThunk } from "@reduxjs/toolkit";
+import type { RootState } from "../../app/store";
+import { selectCurrentServer } from "../../app/settings/settingSlice";
+import { resolveRetryAfterMs } from "../../app/utils/retryAfter";
+import { selectCurrentToken } from "../../auth/authSlice";
+import { createSSEParser } from "../chat/parseMultilineSSE";
+
+export type DialogStatus = "pending" | "running" | "done" | "failed" | "cancelled" | "reconnecting";
+
+export interface RunAgentBackgroundResult {
+    dialogId: string;
+    content?: string;
+    usage?: unknown;
+}
+
+export interface RunAgentBackgroundArgs {
+    agentKey: string;
+    userInput: string;
+    serverBase?: string;
+    spaceId?: string;
+    /** 任务状态变化时触发（pending → running → done/failed） */
+    onStatusChange?: (status: DialogStatus) => void;
+    /** agent 成功完成时触发 */
+    onDone?: (result: { dialogId: string; content?: string; usage?: unknown }) => void;
+    /** agent 失败时触发 */
+    onFailed?: (error: string) => void;
+    /** 外部取消信号 */
+    signal?: AbortSignal;
+}
+
+const MAX_SSE_RETRIES = 3;
+const SSE_RETRY_DELAY_MS = 1500;
+const MAX_RUN_START_RETRIES = 1;
+
+type RetryableError = Error & { retryable?: boolean; retryAfterMs?: number };
+
+function createRetryableError(message: string, retryAfterMs?: number): RetryableError {
+    return Object.assign(new Error(message), {
+        retryable: true,
+        retryAfterMs,
+    });
+}
+
+function createSubscriptionError(
+    status: number,
+    hasBody: boolean,
+    retryAfterMs?: number
+): RetryableError {
+    const message = !hasBody
+        ? `事件流响应缺少 body (${status})`
+        : `无法订阅事件流 (${status})`;
+
+    if (status === 401 || status === 403) {
+        return new Error(message);
+    }
+
+    return createRetryableError(message, retryAfterMs);
+}
+
+async function waitForRetryDelay(retryAfterMs: number, signal: AbortSignal) {
+    if (signal.aborted) throw new DOMException("Aborted", "AbortError");
+    await new Promise<void>((resolve, reject) => {
+        let timeoutId: ReturnType<typeof setTimeout> | null = null;
+        const onAbort = () => {
+            if (timeoutId !== null) clearTimeout(timeoutId);
+            signal.removeEventListener("abort", onAbort);
+            reject(new DOMException("Aborted", "AbortError"));
+        };
+        timeoutId = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, retryAfterMs);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+
+function parseRetryableJson(text: string) {
+    try {
+        return JSON.parse(text) as {
+            error?: string;
+            reason?: string;
+            retryable?: boolean;
+            retryAfterMs?: number;
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 订阅单次 dialog 事件流，收到 done/failed 则 resolve/reject，
+ * 流意外关闭时 reject 并标记 retryable=true 供上层重试。
+ */
+async function listenToDialogEvents(
+    dialogId: string,
+    currentServer: string,
+    authHeader: string,
+    signal: AbortSignal,
+    onStatusChange?: (status: DialogStatus) => void,
+    onDone?: (result: { dialogId: string; content?: string; usage?: unknown }) => void,
+    onFailed?: (error: string) => void,
+): Promise<RunAgentBackgroundResult> {
+    let eventsRes: Response;
+    try {
+        eventsRes = await fetch(
+            `${currentServer}/api/events/dialog-${dialogId}`,
+            {
+                method: "GET",
+                headers: {
+                    Accept: "text/event-stream",
+                    ...(authHeader && { Authorization: authHeader }),
+                },
+                signal,
+            }
+        );
+    } catch (e) {
+        if (e instanceof Error && e.name === "AbortError") throw e;
+        throw createRetryableError("事件流连接失败");
+    }
+
+    if (!eventsRes.ok || !eventsRes.body) {
+        throw createSubscriptionError(
+            eventsRes.status,
+            !!eventsRes.body,
+            resolveRetryAfterMs(eventsRes.headers, SSE_RETRY_DELAY_MS)
+        );
+    }
+
+    const reader = eventsRes.body.getReader();
+    const decoder = new TextDecoder();
+    const parseSSE = createSSEParser();
+
+    return new Promise<RunAgentBackgroundResult>((resolve, reject) => {
+        const processStream = async () => {
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+
+                    const chunk = decoder.decode(value, { stream: true });
+                    const events = parseSSE(chunk);
+
+                    for (const event of events) {
+                        const type = event.type as string;
+
+                        if (type === "status") {
+                            onStatusChange?.(event.status as DialogStatus);
+                        } else if (type === "done") {
+                            const result = {
+                                dialogId,
+                                content: event.content as string | undefined,
+                                usage: event.usage,
+                            };
+                            onStatusChange?.("done");
+                            onDone?.(result);
+                            reader.cancel().catch(() => { });
+                            resolve(result);
+                            return;
+                        } else if (type === "failed") {
+                            const errMsg = (event.error as string) ?? "未知错误";
+                            onStatusChange?.("failed");
+                            onFailed?.(errMsg);
+                            reader.cancel().catch(() => { });
+                            reject(new Error(errMsg));
+                            return;
+                        }
+                    }
+                }
+                // 流正常关闭但未收到 done/failed（服务重启等），标记可重试
+                const err = createRetryableError("事件流意外关闭");
+                reject(err);
+            } catch (e: unknown) {
+                if (e instanceof Error && e.name === "AbortError") {
+                    resolve({ dialogId });
+                } else {
+                    reject(e);
+                }
+            }
+        };
+
+        processStream();
+    });
+}
+
+export const runAgentBackground = createAsyncThunk<
+    RunAgentBackgroundResult,
+    RunAgentBackgroundArgs,
+    { state: RootState }
+>("agent/runBackground", async (args, { getState, signal: thunkSignal }) => {
+    const { agentKey, userInput, serverBase, spaceId, onStatusChange, onDone, onFailed } = args;
+
+    const state = getState();
+    const currentServer = serverBase?.trim().replace(/\/+$/, "") || selectCurrentServer(state);
+    const token = selectCurrentToken(state);
+    if (!currentServer) throw new Error("未配置服务器地址");
+
+    const authHeader = token ? `Bearer ${token}` : "";
+
+    // ── Step 1: 触发后台运行，获取 dialogId ──────────────────────────────────
+    const effectiveSignal = args.signal ?? thunkSignal;
+    let runResponse:
+        | {
+            dialogId: string;
+            status: string;
+            serverBase?: string;
+        }
+        | null = null;
+
+    for (let attempt = 0; attempt <= MAX_RUN_START_RETRIES; attempt++) {
+        const runRes = await fetch(`${currentServer}/api/agent/run`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(authHeader && { Authorization: authHeader }),
+            },
+            body: JSON.stringify({
+                agentKey,
+                userInput,
+                spaceId,
+                background: true,
+                runtimeContext: {
+                    surface: "web",
+                    host: "browser",
+                    runtime: "react",
+                    entrypoint: "background-agent-run",
+                    capabilities: ["background", "sse-events"],
+                },
+            }),
+            signal: effectiveSignal,
+        });
+
+        if (runRes.ok) {
+            runResponse = (await runRes.json()) as {
+                dialogId: string;
+                status: string;
+                serverBase?: string;
+            };
+            break;
+        }
+
+        const errText = await runRes.text();
+        const payload = parseRetryableJson(errText);
+        const retryAfterMs = resolveRetryAfterMs(
+            runRes.headers,
+            SSE_RETRY_DELAY_MS,
+            payload?.retryAfterMs
+        );
+        const retryable =
+            payload?.retryable === true ||
+            payload?.reason === "core_draining" ||
+            runRes.status === 502 ||
+            runRes.status === 503 ||
+            runRes.status === 504;
+
+        if (retryable && attempt < MAX_RUN_START_RETRIES) {
+            await waitForRetryDelay(retryAfterMs, effectiveSignal);
+            continue;
+        }
+
+        throw new Error(`启动后台任务失败 (${runRes.status}): ${errText}`);
+    }
+
+    if (!runResponse) {
+        throw new Error("启动后台任务失败：未收到可用的后台运行响应");
+    }
+
+    const {
+        dialogId,
+        serverBase: routedServerBase,
+    } = runResponse;
+    onStatusChange?.("pending");
+
+    // ── Step 2: 订阅 SSE 事件流（含断线重连，最多 3 次）────────────────────────
+    let lastError: Error | undefined;
+
+    const eventServer =
+        typeof routedServerBase === "string" && routedServerBase.trim()
+            ? routedServerBase.trim().replace(/\/+$/, "")
+            : currentServer;
+
+    for (let attempt = 0; attempt <= MAX_SSE_RETRIES; attempt++) {
+        try {
+            return await listenToDialogEvents(
+                dialogId, eventServer, authHeader, effectiveSignal,
+                onStatusChange, onDone, onFailed,
+            );
+        } catch (e: any) {
+            if (e?.name === "AbortError") throw e;          // 用户主动取消，不重试
+            if (!e?.retryable || attempt >= MAX_SSE_RETRIES) throw e; // 非可重试错误或超限
+            lastError = e;
+            onStatusChange?.("reconnecting");
+            await waitForRetryDelay(e?.retryAfterMs ?? SSE_RETRY_DELAY_MS, effectiveSignal);
+        }
+    }
+
+    throw lastError ?? new Error("事件流重连失败");
+});

package/ai/agent/runAgentClientLoop.ts

@@ -0,0 +1,164 @@
+// packages/ai/agent/runAgentClientLoop.ts
+//
+// 客户端多轮 Agent 循环：复现服务端 runAgentLoop 的逻辑
+// - 不支持 Response API（当前全部走 OpenAI Completions 格式）
+// - 工具执行通过 executeToolCall 在客户端完成
+// - 每轮：调 LLM → 有 tool_calls → 执行工具 → 追加 tool 消息 → 继续
+
+import { RootState } from "../../app/store";
+import { Message } from "../../app/types";
+import { read } from "../../database/dbSlice";
+import { fetchAgentContexts } from "../agent/fetchAgentContexts";
+import { generateRequestBody } from "../llm/generateRequestBody";
+import { getApiEndpoint } from "../llm/providers";
+import { selectCurrentServer } from "../../app/settings/settingSlice";
+import { selectCurrentToken } from "../../auth/authSlice";
+import { performFetchRequest } from "../chat/fetchUtils";
+import { executeToolCall } from "../agent/executeToolCall";
+import { extractCustomId } from "../../core/prefix";
+import { updateTokensAction } from "../../chat/dialog/actions/updateTokensAction";
+import {
+  recordConsecutiveToolFailure,
+  type ToolFailureGuardState,
+} from "../agent/toolFailureGuard";
+
+export interface RunAgentClientLoopArgs {
+  agentKey: string;
+  content: any;
+  parentMessageId?: string;
+  billingDialogKey?: string;
+}
+
+export interface RunAgentClientLoopResult {
+  content: string;
+  toolCallCount: number;
+}
+
+/**
+ * 客户端多轮 Agent 执行循环。
+ *
+ * 使用场景：callAgentTool 的 client 模式、runAgent thunk。
+ * 不适合需要流式输出的场景（请用 runStreamingAgent）。
+ */
+export async function runAgentClientLoop(
+  args: RunAgentClientLoopArgs,
+  thunkApi: any
+): Promise<RunAgentClientLoopResult> {
+  const { agentKey, content, parentMessageId, billingDialogKey } = args;
+  const { getState, dispatch } = thunkApi;
+  const state = getState() as RootState;
+
+  // 1. 加载 Agent 配置
+  const agentConfig = await dispatch(read({ dbKey: agentKey })).unwrap();
+
+  // 2. 加载 Agent 上下文（知识库 / references）
+  const agentContexts = await fetchAgentContexts(
+    agentConfig.references,
+    dispatch
+  );
+
+  // 3. 构造首轮 body（generateRequestBody 会注入 system prompt）
+  const initialMessages: Message[] = [{ role: "user", content }];
+  const body = generateRequestBody({
+    agentConfig,
+    messages: initialMessages,
+    userInput: typeof content === "string" ? content : JSON.stringify(content),
+    contexts: agentContexts,
+  });
+  body.stream = false; // 多轮模式不用流式
+
+  // body.messages 包含了 system 消息 + 用户消息，后续累积 tool 结果入此数组
+  const messages: Message[] = body.messages as Message[];
+
+  const api = getApiEndpoint(agentConfig);
+  const currentServer = selectCurrentServer(state);
+  const token = selectCurrentToken(state);
+
+  let finalContent = "";
+  let toolCallCount = 0;
+  const toolFailureGuard: ToolFailureGuardState = {
+    signature: null,
+    count: 0,
+  };
+
+  // 4. 多轮循环
+  loop:
+  for (;;) {
+    // 更新 messages（含累积的 tool 结果）
+    body.messages = messages;
+
+    const response = await performFetchRequest({
+      agentConfig,
+      api,
+      bodyData: body as any,
+      currentServer,
+      token,
+    });
+
+    const data = await response.json();
+    const choice = data.choices?.[0];
+
+    if (billingDialogKey && data?.usage) {
+      await updateTokensAction(
+        {
+          dialogId: extractCustomId(billingDialogKey),
+          dialogKey: billingDialogKey,
+          usage: data.usage,
+          agentConfig,
+        },
+        thunkApi
+      );
+    }
+
+    if (!choice) {
+      console.warn("[runAgentClientLoop] 响应中找不到 choices[0]，停止");
+      break;
+    }
+
+    const assistantMsg = choice.message;
+    const finishReason: string = choice.finish_reason ?? "";
+
+    // 追加 assistant 消息
+    messages.push(assistantMsg);
+
+    // 记录文本内容
+    if (typeof assistantMsg.content === "string" && assistantMsg.content) {
+      finalContent = assistantMsg.content;
+    }
+
+    // 无工具调用 or 模型明确 stop → 结束
+    if (!assistantMsg.tool_calls?.length || finishReason === "stop") {
+      break;
+    }
+
+    // 5. 执行工具调用
+    for (const tc of assistantMsg.tool_calls) {
+      toolCallCount++;
+      const toolResultContent = await executeToolCall(tc, thunkApi, {
+        parentMessageId,
+        agentKey,
+      });
+      const stopReason = recordConsecutiveToolFailure(
+        toolFailureGuard,
+        tc,
+        toolResultContent
+      );
+      if (stopReason) {
+        finalContent = stopReason;
+        messages.push({
+          role: "tool",
+          tool_call_id: tc.id,
+          content: toolResultContent,
+        } as any);
+        break loop;
+      }
+      messages.push({
+        role: "tool",
+        tool_call_id: tc.id,
+        content: toolResultContent,
+      } as any);
+    }
+  }
+
+  return { content: finalContent, toolCallCount };
+}

package/ai/agent/runtimeGuidance.ts

@@ -0,0 +1,116 @@
+import { canonicalizeToolNames } from "../tools/toolNameAliases";
+import { buildContextLayerContractBlock } from "./contextLayerContract";
+import { buildStartupProtocolBlock } from "./startupProtocol";
+
+export type RuntimeGuidanceToolOptions = {
+  hasCheckEnvTool: boolean;
+  hasExecShellTool: boolean;
+  hasRememberMemoryTool: boolean;
+  hasDocTools: boolean;
+  hasBrowserTools: boolean;
+  hasEmailRegistrationTools: boolean;
+  hasEmailRegistrationWorkflow: boolean;
+};
+
+const normalizeToolName = (name: string): string =>
+  name.replace(/[-_]/g, "").toLowerCase();
+
+const hasAnyTool = (normalizedTools: Set<string>, candidates: string[]): boolean =>
+  candidates.some((candidate) => normalizedTools.has(normalizeToolName(candidate)));
+
+const hasAllTools = (normalizedTools: Set<string>, candidates: string[]): boolean =>
+  candidates.every((candidate) => normalizedTools.has(normalizeToolName(candidate)));
+
+const buildEmailRegistrationWorkflowBlock = (
+  enabled: boolean
+): string => {
+  if (!enabled) return "";
+
+  return [
+    "--- 邮箱验证码注册流程 ---",
+    "当用户要求你注册网站账号时，只允许处理用户明确指定的当前目标网站，不要自行扩展到其他网站、批量注册或规避平台风控。",
+    "",
+    "分阶段协议：discover before acting -> assess supportability -> register -> verify -> closeout。",
+    "",
+    "推荐流程：",
+    "1. discover before acting：先用 browser_openSession / browser_readContent 阅读页面，确认目标注册页 URL、账号用途、必填项和停止条件；不要一打开页面就盲点按钮。如果缺少目标网站，先询问用户。",
+    "2. assess supportability：先判断该流程是否支持当前受控自动化。遇到 CAPTCHA、手机号验证、支付、身份/KYC、OAuth-only、服务条款确认、或任何看起来像规避风控的步骤时，必须立即停止并向用户说明 blockingReason；不要硬闯。",
+    "3. register：只有在确认支持后，才使用 email_provision_identity 为当前 agent 生成受控域名邮箱身份，再使用 browser_openSession / browser_typeText / browser_click / browser_readContent 填写并提交注册表单。",
+    "4. verify：提交后使用 email_wait_for 等待该 agent 收件箱里的验证邮件，再用 email_extract_verification 提取验证码或验证链接，回填验证码或打开验证链接完成验证。",
+    "5. closeout：无论成功还是失败都要 always close sessions，主动清理浏览器会话（例如 browser_closeSession）。如果流程失败，必须明确 failedStage 与 blockingReason，并说明可恢复选项；不要盲目尝试无关网站或绕过验证。",
+    "6. 最终只在对话中返回账号、邮箱和一次性生成的密码；不要持久化密码，不要写入 agent metadata、数据库、文档或记忆。",
+    "",
+    "必须暂停并询问用户的情况：CAPTCHA、手机号验证、支付、身份/KYC、OAuth 授权、OAuth-only、服务条款确认、或任何看起来像规避风控的步骤。",
+    "如果流程失败，说明 failedStage、blockingReason 和可恢复选项，不要盲目尝试无关网站或绕过验证。",
+  ].join("\n");
+};
+
+const buildWebResearchToolPolicyBlock = (
+  hasExecShellTool: boolean,
+  hasFetchWebpageTool: boolean
+): string => {
+  if (!hasExecShellTool || !hasFetchWebpageTool) return "";
+
+  return [
+    "--- 生产环境网页研究工具策略 ---",
+    "生产环境网页研究优先使用 fetchWebpage、站点 Markdown / llms.txt、或专用浏览/搜索工具。",
+    "不要用 execShell 调 curl、grep、sed 等命令抓网页或截取网页段落；生产环境通常会禁用 dev shell，反复尝试只会浪费回合。",
+    "如果网页内容过长或锚点段落没有被单独提取，先寻找该文档站提供的 Markdown 版本、独立页面、llms.txt 索引或更具体 URL，再继续回答。",
+  ].join("\n");
+};
+
+export const resolveRuntimeGuidanceToolOptions = (
+  tools: string[] = []
+): RuntimeGuidanceToolOptions => {
+  const normalizedTools = canonicalizeToolNames(tools);
+  const normalizedToolSet = new Set(normalizedTools.map(normalizeToolName));
+  const hasBrowserTools = hasAllTools(normalizedToolSet, [
+    "browser_openSession",
+    "browser_readContent",
+    "browser_typeText",
+    "browser_click",
+    "browser_closeSession",
+  ]);
+  const hasBrowserProbe = hasAnyTool(normalizedToolSet, ["browser_probePage", "browserProbePage"]);
+  const hasEmailRegistrationTools = hasAllTools(normalizedToolSet, [
+    "email_provision_identity",
+    "email_wait_for",
+    "email_extract_verification",
+  ]);
+
+  return {
+    hasCheckEnvTool: normalizedTools.includes("checkEnv"),
+    hasExecShellTool: normalizedTools.includes("execShell"),
+    hasRememberMemoryTool: normalizedTools.includes("rememberMemory"),
+    hasDocTools: normalizedTools.some((tool) =>
+      ["read", "readDoc", "readPage", "createDoc", "updateDoc"].includes(tool)
+    ),
+    hasBrowserTools,
+    hasEmailRegistrationTools,
+    // Require browser_probePage to be present before enabling email registration workflow guidance.
+    hasEmailRegistrationWorkflow: hasBrowserTools && hasBrowserProbe && hasEmailRegistrationTools,
+  };
+};
+
+export const buildRuntimeGuidanceBlocks = (tools: string[] = []) => {
+  const options = resolveRuntimeGuidanceToolOptions(tools);
+  const normalizedTools = canonicalizeToolNames(tools);
+
+  return {
+    startupProtocol: buildStartupProtocolBlock({
+      hasCheckEnvTool: options.hasCheckEnvTool,
+      hasExecShellTool: options.hasExecShellTool,
+    }),
+    contextLayerContract: buildContextLayerContractBlock({
+      hasRememberMemoryTool: options.hasRememberMemoryTool,
+      hasDocTools: options.hasDocTools,
+    }),
+    emailRegistrationWorkflow: buildEmailRegistrationWorkflowBlock(
+      options.hasEmailRegistrationWorkflow
+    ),
+    webResearchToolPolicy: buildWebResearchToolPolicyBlock(
+      options.hasExecShellTool,
+      normalizedTools.includes("fetchWebpage")
+    ),
+  };
+};

package/ai/agent/serverOrigin.ts

@@ -0,0 +1,7 @@
+export const normalizeServerOrigin = (base: string): string | null => {
+  try {
+    return new URL(base).origin.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+};