@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/shared/@ai-setting/{roy-agent-core-p2r27era.js → roy-agent-core-mxdc756a.js}

@@ -10,7 +10,7 @@ import {
 } from "./roy-agent-core-1pg0fepg.js";
 import {
   builtInPrompts
-} from "./roy-agent-core-gdsqp6j8.js";
+} from "./roy-agent-core-6masakz4.js";
 import {
   DEFAULT_SUBAGENT_PROMPT
 } from "./roy-agent-core-rx16h2m1.js";

package/dist/shared/@ai-setting/{roy-agent-core-p8ak03s0.js → roy-agent-core-w527pcpe.js}

@@ -10,7 +10,7 @@ import {
   invoke,
   invokeNonStream,
   toolParametersToJsonSchema
-} from "./roy-agent-core-zy3hqfwg.js";
+} from "./roy-agent-core-0hq21px2.js";
 import {
   ContextError,
   ErrorCodes
@@ -51,47 +51,207 @@ import {
   stream as piStream,
   getModel
 } from "@earendil-works/pi-ai";
+
+// src/env/llm/reasoning-defense.ts
+var DEEPSEEK_PROVIDER_PREFIX = "deepseek";
+var DEEPSEEK_MODEL_MARKER = "deepseek";
+function shouldInjectReasoningContent(provider, modelId) {
+  const p = (provider ?? "").toLowerCase();
+  const m = (modelId ?? "").toLowerCase();
+  if (p === DEEPSEEK_PROVIDER_PREFIX || p.startsWith(`${DEEPSEEK_PROVIDER_PREFIX}-`)) {
+    return true;
+  }
+  return m.includes(DEEPSEEK_MODEL_MARKER);
+}
+function injectReasoningContent(messages) {
+  return messages.map((msg) => {
+    if (msg?.role !== "assistant")
+      return msg;
+    if ("reasoning_content" in msg)
+      return msg;
+    return { ...msg, reasoning_content: "" };
+  });
+}
+function applyReasoningDefense(payload, target) {
+  if (!payload || typeof payload !== "object")
+    return payload;
+  if (!shouldInjectReasoningContent(target.provider, target.modelId))
+    return payload;
+  const messages = payload.messages;
+  if (!Array.isArray(messages))
+    return payload;
+  return { ...payload, messages: injectReasoningContent(messages) };
+}
+function createReasoningDefenseHook(target) {
+  return (payload) => applyReasoningDefense(payload, target);
+}
+
+// src/env/llm/adapter-pi-ai.ts
 var logger = createLogger("llm:adapter-pi-ai");
 var KNOWN_PROVIDER_APIS = {
-  anthropic: { api: "anthropic-messages", contextLimit: 200000, maxTokensLimit: 8192 },
-  openai: { api: "openai-responses", contextLimit: 128000, maxTokensLimit: 16384 },
-  google: { api: "google-generative-ai", contextLimit: 1e6, maxTokensLimit: 8192 },
-  "google-vertex": { api: "google-vertex", contextLimit: 1e6, maxTokensLimit: 8192 },
-  deepseek: { api: "openai-completions", contextLimit: 64000, maxTokensLimit: 8192 },
-  xai: { api: "openai-completions", contextLimit: 131072, maxTokensLimit: 8192 },
-  groq: { api: "openai-completions", contextLimit: 32768, maxTokensLimit: 8192 },
-  minimax: { api: "openai-completions", contextLimit: 128000, maxTokensLimit: 8192 },
-  "minimax-cn": { api: "openai-completions", contextLimit: 128000, maxTokensLimit: 8192 },
-  moonshotai: { api: "openai-completions", contextLimit: 128000, maxTokensLimit: 8192 },
-  "kimi-coding": { api: "openai-completions", contextLimit: 128000, maxTokensLimit: 8192 }
+  anthropic: {
+    api: "anthropic-messages",
+    apiProtocol: "anthropic-messages",
+    contextLimit: 200000,
+    maxTokensLimit: 8192
+  },
+  openai: {
+    api: "openai-responses",
+    apiProtocol: "openai-responses",
+    contextLimit: 128000,
+    maxTokensLimit: 16384
+  },
+  google: {
+    api: "google-generative-ai",
+    apiProtocol: "google-generative-ai",
+    contextLimit: 1e6,
+    maxTokensLimit: 8192
+  },
+  "google-vertex": {
+    api: "google-vertex",
+    apiProtocol: "google-vertex",
+    contextLimit: 1e6,
+    maxTokensLimit: 8192
+  },
+  deepseek: {
+    api: "openai-completions",
+    apiProtocol: "openai-completions",
+    contextLimit: 64000,
+    maxTokensLimit: 8192
+  },
+  glm: {
+    api: "openai-completions",
+    apiProtocol: "openai-completions",
+    contextLimit: 128000,
+    maxTokensLimit: 8192
+  },
+  xai: {
+    api: "openai-completions",
+    apiProtocol: "openai-completions",
+    contextLimit: 131072,
+    maxTokensLimit: 8192
+  },
+  groq: {
+    api: "openai-completions",
+    apiProtocol: "openai-completions",
+    contextLimit: 32768,
+    maxTokensLimit: 8192
+  },
+  minimax: {
+    api: "anthropic-messages",
+    apiProtocol: "anthropic-messages",
+    contextLimit: 128000,
+    maxTokensLimit: 8192
+  },
+  "minimax-cn": {
+    api: "anthropic-messages",
+    apiProtocol: "anthropic-messages",
+    contextLimit: 128000,
+    maxTokensLimit: 8192
+  },
+  moonshotai: {
+    api: "openai-completions",
+    apiProtocol: "openai-completions",
+    contextLimit: 128000,
+    maxTokensLimit: 8192
+  },
+  "kimi-coding": {
+    api: "openai-completions",
+    apiProtocol: "openai-completions",
+    contextLimit: 128000,
+    maxTokensLimit: 8192
+  }
+};
+var PROVIDER_ENDPOINT_APIS = {
+  minimax: [
+    { pathIncludes: "/anthropic", apiProtocol: "anthropic-messages" },
+    { pathIncludes: "/v1", apiProtocol: "openai-completions" }
+  ],
+  "minimax-cn": [
+    { pathIncludes: "/anthropic", apiProtocol: "anthropic-messages" },
+    { pathIncludes: "/v1", apiProtocol: "openai-completions" }
+  ]
+};
+var ENDPOINT_RULES_SORTED = Object.fromEntries(Object.entries(PROVIDER_ENDPOINT_APIS).map(([provider, rules]) => [
+  provider,
+  [...rules].sort((a, b) => b.pathIncludes.length - a.pathIncludes.length)
+]));
+var PROVIDER_API_OVERRIDES = {
+  "minimax-responses": "openai-responses",
+  "minimax-openai": "openai-completions"
 };
-function resolvePiModel(provider, modelId, baseURL) {
+function resolveApiProtocol(provider, baseURL, explicitProtocol) {
+  if (explicitProtocol)
+    return explicitProtocol;
+  if (PROVIDER_API_OVERRIDES[provider])
+    return PROVIDER_API_OVERRIDES[provider];
+  const endpointRules = ENDPOINT_RULES_SORTED[provider];
+  if (endpointRules) {
+    for (const rule of endpointRules) {
+      if (baseURL?.includes(rule.pathIncludes))
+        return rule.apiProtocol;
+    }
+  }
+  const declared = KNOWN_PROVIDER_APIS[provider]?.apiProtocol;
+  if (declared)
+    return declared;
+  if (baseURL?.includes("/responses"))
+    return "openai-responses";
+  if (baseURL?.includes("anthropic")) {
+    logger.warn(`[adapter-pi-ai] provider "${provider}" 的协议靠 baseURL 含 "anthropic" 推断为 anthropic-messages；` + `建议在 KNOWN_PROVIDER_APIS 或调用处显式声明 apiProtocol（Task #4383 P1）`, { provider, inferred_api_protocol: "anthropic-messages", base_url: baseURL });
+    return "anthropic-messages";
+  }
+  return KNOWN_PROVIDER_APIS[provider]?.api || "openai-completions";
+}
+var REASONING_COMPAT_PIN = {
+  supportsDeveloperRole: false,
+  thinkingFormat: "openai",
+  supportsReasoningEffort: false
+};
+var REASONING_SAFE_PROTOCOLS = new Set([
+  "openai-completions",
+  "anthropic-messages"
+]);
+var warnedReasoningRefusals = new Set;
+function resolveModelReasoning(provider, modelId, capabilities, apiProtocol) {
+  const requested = capabilities?.reasoning === true;
+  if (!requested)
+    return false;
+  if (!apiProtocol || !REASONING_SAFE_PROTOCOLS.has(apiProtocol)) {
+    const key = `${provider}:${apiProtocol ?? "<unresolved>"}`;
+    if (!warnedReasoningRefusals.has(key)) {
+      warnedReasoningRefusals.add(key);
+      logger.warn(`[adapter-pi-ai] provider "${provider}" (${apiProtocol ?? "unresolved"}) 的 capabilities.reasoning=true 被忽略：` + `该协议无法通过 compat pin 保持请求体字节一致，打开会破坏 prompt cache 前缀（Task #4403）`, { provider, model_id: modelId, api_protocol: apiProtocol });
+    }
+    return false;
+  }
+  return true;
+}
+function buildPiCacheOptions(args) {
+  const out = {};
+  if (args.sessionId)
+    out.sessionId = args.sessionId;
+  if (args.apiProtocol === "openai-completions") {
+    out.cacheRetention = args.cacheRetention ?? "long";
+  } else if (args.cacheRetention) {
+    out.cacheRetention = args.cacheRetention;
+  }
+  return out;
+}
+function resolvePiModel(provider, modelId, baseURL, capabilities) {
   const builtIn = getModel(provider, modelId);
   if (builtIn)
     return baseURL ? { ...builtIn, baseUrl: baseURL } : builtIn;
-  const providerApiOverride = {
-    "minimax-responses": "openai-responses",
-    "minimax-openai": "openai-completions"
-  };
-  let configuredApi;
-  if (providerApiOverride[provider]) {
-    configuredApi = providerApiOverride[provider];
-  } else if (provider === "minimax" || provider === "minimax-cn") {
-    configuredApi = baseURL?.includes("anthropic") ? "anthropic-messages" : "openai-completions";
-  } else if (baseURL?.includes("/responses")) {
-    configuredApi = "openai-responses";
-  } else if (baseURL?.includes("anthropic")) {
-    configuredApi = "anthropic-messages";
-  } else {
-    configuredApi = KNOWN_PROVIDER_APIS[provider]?.api || "openai-completions";
-  }
+  const configuredApi = resolveApiProtocol(provider, baseURL);
+  const reasoning = resolveModelReasoning(provider, modelId, capabilities, configuredApi);
   return {
     id: modelId,
     name: modelId,
     api: configuredApi,
     provider,
     baseUrl: baseURL || "",
-    reasoning: false,
+    reasoning,
+    ...reasoning ? { compat: { ...REASONING_COMPAT_PIN } } : {},
     input: ["text", "image"],
     cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
     contextWindow: KNOWN_PROVIDER_APIS[provider]?.contextLimit || 128000,
@@ -214,7 +374,7 @@ class EmbeddingNotSupportedError extends Error {
 class PiAiAdapter {
   name = "pi-ai";
   async chat(req) {
-    const model = resolvePiModel(req.provider, req.modelId, req.baseURL);
+    const model = resolvePiModel(req.provider, req.modelId, req.baseURL, req.capabilities);
     const ctx = {
       systemPrompt: [req.systemPrompt, extractSystemPrompt(req.messages)].filter(Boolean).join(`
 
@@ -228,12 +388,21 @@ class PiAiAdapter {
       temperature: req.temperature,
       maxTokens: req.maxTokens,
       signal: req.signal,
+      ...buildPiCacheOptions({
+        apiProtocol: model.api,
+        sessionId: req.sessionId,
+        cacheRetention: req.cacheRetention
+      }),
+      onPayload: createReasoningDefenseHook({
+        provider: req.provider,
+        modelId: req.modelId
+      }),
       ...piRequestExtras(req)
     });
     return fromAssistantMessage(msg);
   }
   async stream(req) {
-    const model = resolvePiModel(req.provider, req.modelId, req.baseURL);
+    const model = resolvePiModel(req.provider, req.modelId, req.baseURL, req.capabilities);
     const ctx = {
       systemPrompt: [req.systemPrompt, extractSystemPrompt(req.messages)].filter(Boolean).join(`
 
@@ -241,7 +410,23 @@ class PiAiAdapter {
       messages: toPiMessages(req.messages),
       tools: toPiTools(req.tools)
     };
-    const eventStream = piStream(model, ctx, { apiKey: req.apiKey, baseURL: req.baseURL, temperature: req.temperature, maxTokens: req.maxTokens, signal: req.signal, ...piRequestExtras(req) });
+    const eventStream = piStream(model, ctx, {
+      apiKey: req.apiKey,
+      baseURL: req.baseURL,
+      temperature: req.temperature,
+      maxTokens: req.maxTokens,
+      signal: req.signal,
+      ...buildPiCacheOptions({
+        apiProtocol: model.api,
+        sessionId: req.sessionId,
+        cacheRetention: req.cacheRetention
+      }),
+      onPayload: createReasoningDefenseHook({
+        provider: req.provider,
+        modelId: req.modelId
+      }),
+      ...piRequestExtras(req)
+    });
     return { events: eventStream, result: async () => fromAssistantMessage(await eventStream.result()) };
   }
   async embed(_req) {
@@ -893,6 +1078,39 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 var logger2 = createLogger("llm");
+function normalizeUsage(usage) {
+  if (!usage)
+    return;
+  const normalized = {
+    promptTokens: usage.promptTokens ?? 0,
+    completionTokens: usage.completionTokens ?? 0,
+    totalTokens: usage.totalTokens ?? 0
+  };
+  if (usage.cacheRead !== undefined)
+    normalized.cacheRead = usage.cacheRead;
+  if (usage.cacheWrite !== undefined)
+    normalized.cacheWrite = usage.cacheWrite;
+  if (usage.cacheMiss !== undefined)
+    normalized.cacheMiss = usage.cacheMiss;
+  if (usage.cacheRead !== undefined || usage.cacheWrite !== undefined) {
+    const reads = usage.cacheRead ?? 0;
+    const writes = usage.cacheWrite ?? 0;
+    const cacheSum = reads + writes;
+    const prompt = usage.promptTokens ?? 0;
+    const completion = usage.completionTokens ?? 0;
+    const nonCachedTotal = prompt + completion + cacheSum;
+    const aiSdkTotal = prompt + completion;
+    const isPiAiShape = Math.abs(usage.totalTokens - nonCachedTotal) <= 1;
+    if (isPiAiShape) {
+      normalized.promptTokensTotal = prompt + cacheSum;
+    } else if (Math.abs(usage.totalTokens - aiSdkTotal) <= 1) {
+      normalized.promptTokensTotal = Math.max(prompt, cacheSum);
+    } else {
+      normalized.promptTokensTotal = Math.max(prompt, cacheSum);
+    }
+  }
+  return normalized;
+}
 async function resolveFallbackProviderConfig(providerId) {
   const home = os.homedir();
   const authPath = path.join(home, ".roy-agent", "auth.json");
@@ -929,6 +1147,7 @@ class LLMComponent extends BaseComponent {
   configWatcher;
   cachedAdapter;
   cachedAdapterProvider;
+  adapterOverride;
   constructor() {
     super();
   }
@@ -1146,6 +1365,7 @@ class LLMComponent extends BaseComponent {
         model: `${providerId}/${model}`,
         apiKey,
         baseURL: provider?.baseURL,
+        ...capabilities ? { capabilities } : {},
         ...effectiveThinkingInText?.enabled ? {
           options: {
             thinkingInText: {
@@ -1164,6 +1384,8 @@ class LLMComponent extends BaseComponent {
     };
   }
   getAdapter() {
+    if (this.adapterOverride)
+      return this.adapterOverride;
     const currentProvider = process.env.ROY_LLM_PROVIDER || "pi-ai";
     if (this.cachedAdapter && this.cachedAdapterProvider === currentProvider) {
       return this.cachedAdapter;
@@ -1172,6 +1394,9 @@ class LLMComponent extends BaseComponent {
     this.cachedAdapterProvider = currentProvider;
     return this.cachedAdapter;
   }
+  __setAdapterForTest(adapter) {
+    this.adapterOverride = adapter;
+  }
   invalidateAdapterCache() {
     this.cachedAdapter = undefined;
     this.cachedAdapterProvider = undefined;
@@ -1194,7 +1419,8 @@ class LLMComponent extends BaseComponent {
       apiKey: ctx.invokeConfig.apiKey || "",
       baseURL: ctx.invokeConfig.baseURL,
       signal: ctx.abortSignal,
-      sessionId: request.context?.sessionId
+      sessionId: request.context?.sessionId,
+      capabilities: ctx.invokeConfig.capabilities
     };
     let output = {
       content: "",
@@ -1246,11 +1472,14 @@ class LLMComponent extends BaseComponent {
         output.finishReason = parsed.tool_calls?.length ? "tool-calls" : "stop";
         output.toolCalls = parsed.tool_calls || [];
         if (parsed.usage) {
-          finishUsage = {
+          finishUsage = normalizeUsage({
             promptTokens: parsed.usage.promptTokens ?? parsed.usage.inputTokens ?? 0,
             completionTokens: parsed.usage.completionTokens ?? parsed.usage.outputTokens ?? 0,
-            totalTokens: parsed.usage.totalTokens ?? 0
-          };
+            totalTokens: parsed.usage.totalTokens ?? 0,
+            cacheRead: parsed.usage.cacheRead,
+            cacheWrite: parsed.usage.cacheWrite,
+            cacheMiss: parsed.usage.cacheMiss
+          });
         }
         output.usage = finishUsage;
       } catch {
@@ -1263,11 +1492,7 @@ class LLMComponent extends BaseComponent {
     output.finishReason = resp.finishReason;
     output.toolCalls = resp.toolCalls || [];
     if (resp.usage) {
-      finishUsage = {
-        promptTokens: resp.usage.promptTokens ?? 0,
-        completionTokens: resp.usage.completionTokens ?? 0,
-        totalTokens: resp.usage.totalTokens ?? 0
-      };
+      finishUsage = normalizeUsage(resp.usage);
     }
     output.usage = finishUsage;
     return this.finalizeOutput(request, ctx, output, finishUsage, startTime, adapter.name);
@@ -1362,6 +1587,7 @@ class LLMComponent extends BaseComponent {
         throw contextError;
       }
     }
+    this.emitCompletedEvent(request, `${ctx.providerId}/${ctx.model}`, output.content, output.usage, adapterName);
     return {
       output,
       providerId: ctx.providerId,
@@ -1369,6 +1595,31 @@ class LLMComponent extends BaseComponent {
       latencyMs
     };
   }
+  emitCompletedEvent(request, model, content, usage, adapterName) {
+    try {
+      this.env?.pushEnvEvent?.({
+        id: randomUUID(),
+        type: "llm.completed",
+        timestamp: Date.now(),
+        metadata: {
+          source: "llm.component.invoke",
+          sessionId: request.context?.sessionId,
+          messageId: request.context?.messageId
+        },
+        payload: {
+          type: "completed",
+          content,
+          metadata: {
+            model,
+            usage,
+            adapter: adapterName
+          }
+        }
+      });
+    } catch (err) {
+      logger2.warn("Failed to push llm.completed event", { error: String(err) });
+    }
+  }
   getApiKey(providerId) {
     const providers = this.getLLMConfig("llm.providers", {});
     return providers?.[providerId]?.apiKey;

package/dist/shared/@ai-setting/{roy-agent-core-3tv1q6f2.js → roy-agent-core-ytr2w0vb.js}

@@ -10,12 +10,12 @@ import {
 } from "./roy-agent-core-dv714bqh.js";
 import {
   SessionMessageConverter
-} from "./roy-agent-core-pk1b3kvf.js";
+} from "./roy-agent-core-2b8jtv7m.js";
 import {
   parseToolArgsStrict,
   safeParseToolArgs,
   withTimeout
-} from "./roy-agent-core-zy3hqfwg.js";
+} from "./roy-agent-core-0hq21px2.js";
 import {
   getCurrentBgTaskId
 } from "./roy-agent-core-c1v263jn.js";

package/dist/shared/@ai-setting/{roy-agent-core-yd21n6c7.js → roy-agent-core-zvemdfx5.js}

@@ -1,7 +1,7 @@
 import {
   MemorySessionStore,
   SQLiteSessionStore
-} from "./roy-agent-core-h93v6p6y.js";
+} from "./roy-agent-core-7qy3nffr.js";
 import {
   init_loose_json,
   tryParseJsonFromText

package/dist/test-utils/child-process-mock.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Shared `child_process` mock factory for `mock.module(...)`.
+ *
+ * ## 为什么需要它（Task #4420）
+ *
+ * Bun 当前对 `mock.module("child_process", factory)` 采用 **ESM exports 语义**：
+ * factory 返回的对象被当作模块的**完整导出面**，而不是「在真实模块上打补丁」。
+ * 因此只要少提供一个命名导出，任何**静态** `import { x } from "child_process"`
+ * 该导出的模块都会在**模块加载期**直接抛：
+ *
+ * ```
+ * SyntaxError: Export named 'exec' not found in module 'node:child_process'.
+ * ```
+ *
+ * 更糟的是：
+ *   1. 报错指向**被 import 的模块**（如 `event-source-handlers.ts`），
+ *      而不是写了不完整 mock 的**测试文件** —— 极难定位。
+ *   2. mock.module 在同一 `bun test` 进程内**跨文件泄漏**（bun 不像 jest
+ *      每文件独立 registry），所以还会顺带炸掉后面无关的文件。
+ *
+ * ## 历史事故（同一个坑踩了 3 次）
+ *
+ * - Task #2372：`event-source-handlers-builtin.test.ts` 只 mock `spawn`，
+ *   炸掉后面所有静态 import `spawnSync` 的模块（见
+ *   `util/process/process-tree-killer.ts` 里的 lazy-import 规避注释）。
+ * - Task #4331：源码 `event-source-handlers.ts` 新增 `exec as execSync`，
+ *   但该测试的 mock 没跟上 → 整个文件 48/64 条测试挂红（Task #4420 修的就是这个）。
+ *
+ * ## 解决方式
+ *
+ * **导出面从真实模块自省派生**，永不手写清单：
+ *   - `require("node:child_process")` 枚举出真实存在的导出名
+ *   - 对每个导出，默认**透传真实实现**，只把测试显式 `overrides` 的键替换掉
+ *   - 额外补一个 `default`（ESM namespace 有 `default`，`require()` 没有 ——
+ *     这也是历史 mock 需要手写 `default: {...}` 的原因，现在自动生成）
+ *
+ * 这样即使未来 Node/Bun 新增导出，或源码新增 `import { execFile }`，
+ * mock 也不会因为「缺导出」再次炸掉整个测试文件。
+ *
+ * ## 用法
+ *
+ * ```ts
+ * import { createChildProcessMockModule } from "../../../test-utils/child-process-mock";
+ *
+ * beforeEach(() => {
+ *   mock.module("child_process", () =>
+ *     createChildProcessMockModule({ spawn: spawnMock }),
+ *   );
+ * });
+ * ```
+ *
+ * 注意：`mock.module` 的 specifier 用 `"child_process"` 还是
+ * `"node:child_process"` 都能命中（Bun 会把两者归一），helper 内部统一
+ * 从 `node:child_process` 自省。
+ */
+/**
+ * 当前 Node/Bun 上 `node:child_process` 的完整命名导出清单（运行时自省）。
+ *
+ * 在 Bun 上为：`ChildProcess`, `exec`, `execFile`, `execFileSync`,
+ * `execSync`, `fork`, `spawn`, `spawnSync`。
+ */
+export declare const CHILD_PROCESS_EXPORT_NAMES: readonly string[];
+type ChildProcessModule = Record<string, any>;
+/**
+ * 构造一个**导出面完整**的 `child_process` mock 模块对象。
+ *
+ * @param overrides 需要替换为测试替身（spy/stub）的导出。其余导出保持真实实现，
+ *                  既保证导出面完整，又避免把未测行为也一起假掉。
+ * @returns 可直接被 `mock.module("child_process", () => ...)` 返回的模块对象，
+ *          含 `default` 自引用（`default` 上的键与命名导出保持一致）。
+ */
+export declare function createChildProcessMockModule(overrides?: ChildProcessModule): ChildProcessModule;
+export {};

package/dist/util/process/process-tree-killer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview 跨平台进程树杀进程工具
+ *
+ * 用于 delegate_task 超时/stop 时彻底清理子 agent 派生的进程树（包括孙进程），
+ * 防止端口、文件句柄、孤儿进程泄漏。
+ *
+ * 平台策略：
+ * - POSIX (Linux / macOS)：要求子进程以 `detached: true` + 子进程是进程组 leader，
+ *   通过 `process.kill(-pid, signal)` 杀进程组。如果子进程没有 detached（PID 不是负数），退化为直接杀 PID。
+ * - Windows：永远用 `taskkill /pid <pid> /f /t` 杀进程树（不依赖 detached）。
+ *
+ * 验证 + 重试机制：
+ * - 每次 kill 后等待 retryDelayMs，用 `process.kill(pid, 0)`（POSIX）或 `tasklist`（Windows）验证进程是否存活
+ * - 如果仍存活，重试（最多 retry 次，默认 3 次）
+ * - 全部重试完仍存活：记录 error 日志（由外层 process-registry 负责）
+ *
+ * 多平台代码路径在测试中可通过 `_setPlatformForTests()` 切换。
+ */
+import type { ChildProcess, SpawnOptions, SpawnSyncOptions, SpawnSyncReturns } from "child_process";
+type SpawnFn = (cmd: string, args: string[], opts: SpawnOptions) => ChildProcess;
+export declare function _setSpawnForTests(s: SpawnFn | undefined): void;
+type SpawnSyncFn = (cmd: string, args: string[], opts: SpawnSyncOptions) => SpawnSyncReturns<Buffer | string>;
+export declare function _setSpawnSyncForTests(s: SpawnSyncFn | undefined): void;
+export interface KillProcessTreeOptions {
+    /** 信号类型（仅 POSIX）。默认 SIGKILL */
+    signal?: NodeJS.Signals;
+    /** 已废弃字段，保留以兼容早期 API。SIGKILL 默认立即生效 */
+    gracefulTimeoutMs?: number;
+    /** 最大重试次数（默认 3） */
+    retry?: number;
+    /** 重试间隔（ms，默认 500） */
+    retryDelayMs?: number;
+}
+/** 杀进程结果 */
+export interface KillProcessTreeResult {
+    /** 杀掉的进程 ID */
+    pid: number;
+    /** 使用的平台策略 */
+    platform: NodeJS.Platform;
+    /** 实际发出的信号（POSIX）或命令（Windows） */
+    signal: string;
+    /** 是否成功（不一定准确，例如 POSIX 中 ESRCH 被忽略视为软成功） */
+    success: boolean;
+    /** 实际尝试次数 */
+    attempts: number;
+    /** 最后一次尝试后进程是否仍存活（true=没杀干净） */
+    stillAlive: boolean;
+}
+export declare function _setPlatformForTests(p: NodeJS.Platform): void;
+export declare function _resetPlatformForTests(): void;
+/**
+ * 杀进程树（跨平台）。不会 throw；ESRCH / EPERM 等"进程已不存在"类错误静默忽略。
+ *
+ * 验证 + 重试：
+ * - 每次 kill 后等待 retryDelayMs（默认 500ms）
+ * - 用 `process.kill(pid, 0)`（POSIX）或 `tasklist`（Windows）验证进程是否存活
+ * - 如果仍存活，重试（最多 retry 次，默认 3 次）
+ * - 全部重试完仍存活：通过 stillAlive: true 返回，由外层记录 error 日志
+ *
+ * POSIX 默认使用 SIGKILL 杀进程组，要求子进程 spawn 时带 `detached: true`。
+ * Windows 调用 `taskkill /f /t` 杀进程树（不依赖 detached）。
+ *
+ * @param pid 进程 PID（必须为正整数）
+ * @param options 可选项
+ */
+export declare function killProcessTree(pid: number, options?: KillProcessTreeOptions): Promise<KillProcessTreeResult>;
+export {};

package/dist/utils/id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview ID Generation Utilities
+ */
+/**
+ * Generate a unique ID with optional prefix
+ */
+export declare function generateId(prefix?: string): string;
+/**
+ * Generate a descending ID (useful for creating IDs that sort newest first)
+ */
+export declare function generateDescendingId(prefix?: string): string;

package/dist/utils/loose-json.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Loose JSON extraction helpers
+ *
+ * LLM 经常把「本该结构化」的结果当纯文本吐出来，格式五花八门：
+ *   1. 纯 JSON
+ *   2. Markdown ```json ... ``` 代码块
+ *   3. 夹在解释文字中的第一个 `{...}`
+ *
+ * 这些 helper 从任意文本里尽力抠出 JSON 对象，返回 null 表示没找到。
+ *
+ * 原实现内联在 `env/workflow/plugins/workflow-json-output-plugin.ts`，
+ * 2026-10-16 抽到 utils 以便 session 压缩的 checkpoint 降级路径复用
+ * （避免 session → workflow/plugins 的反向耦合）。
+ */
+/**
+ * Helper: try to parse a string as a JSON object.
+ * Returns the parsed object (excluding arrays/primitives), or null.
+ */
+export declare function tryParseJsonString(s: string): Record<string, unknown> | null;
+/**
+ * Extract a JSON object from arbitrary LLM text.
+ *
+ * Tries (in order):
+ *   1. Whole text is JSON
+ *   2. Markdown ```json ... ``` code block
+ *   3. First {...} substring
+ *
+ * Returns null if no valid JSON object is found.
+ */
+export declare function tryParseJsonFromText(text: string): Record<string, unknown> | null;