@zooique/memora 3.0.1 → 4.0.0

package/dist/skill/skillScriptRunner.d.ts

@@ -1,7 +1,49 @@
+/**
+ * 技能脚本执行器 — L3 脚本运行时。
+ * 三级渐进披露 L3：脚本在宿主环境（隔离子进程）执行，源代码不入 LLM 上下文，
+ * 只有执行结果（stdout/stderr）作为工具返回值注入。
+ * 安全模型：继承宿主用户环境变量（用户会话环境——脚本可读项目所需配置与用户 shell 环境；
+ *   密钥默认经 SecretStorage→配置对象注入、不经 env（宿主默认路径）；env 回退配置模式
+ *   （MEMORA_API_KEY 等，security_rules 支持）下 key 在进程 env、对脚本可见——owner 信任
+ *   模型（默认自动批准）+ 脚本来源审阅（判据 B）为边界，视同用户本地 shell 语义）+ 超时
+ *   限制（默认 60s，最大 600s——适配脚本内 API 调用/批处理长耗时）+ 白名单 runtime（node/python/shell）+ Windows 隐藏窗口
+ *   （windowsHide:true，不弹 conhost）。
+ * 注：当前为简单子进程执行，非完整沙箱（文件系统/网络隔离由宿主在生产环境实现）。
+ */
+import * as childProcess from 'node:child_process';
 import type { CodeExecutionResult } from '../code-exec/types.js';
 import type { ScriptRuntime } from '../utils/scanner.js';
-/** 脚本执行结果（= CodeExecutionResult，复用代码执行结果形态，SSOT 不重复定义） */
-export type ScriptExecutionResult = CodeExecutionResult;
+/**
+ * 收集侧**内存护栏**产物（可选）。
+ *
+ * 语义边界：这是**内存防线**产物（防 Node 进程被超长输出撑爆），与上下文侧防线
+ * （调用方 `sanitizeExternalText` 的字符上限、`appendToolMessage` 入口关的 token 落盘）
+ * **量纲与目的均不同，不是同一件事的两处实现**。
+ *
+ * ⚠️ 只挂在 `ScriptExecutionResult`（内核子进程收集侧），**不进 `CodeExecutionResult`**——
+ * 后者是宿主 `ICodeExecutionProvider` 的公共返回类型，宿主执行器不产生这两个字段，
+ * 挂上去只会给集成方制造「我该不该填」的噪声。
+ */
+export interface OutputTruncationInfo {
+    /** 输出是否在收集侧被内存护栏截断 */
+    truncated?: boolean;
+    /** 被内存护栏丢弃的字节数（仅 `truncated` 为真时有意义） */
+    discardedBytes?: number;
+}
+/**
+ * 脚本执行结果 = 代码执行结果形态 + 收集侧护栏信息
+ *
+ * 复用 `CodeExecutionResult`（SSOT 不重复定义四个基础字段），仅在脚本侧**扩展**——
+ * 宿主 `run_code` 链路不受影响（字段可选，传纯 `CodeExecutionResult` 即合规）。
+ */
+export type ScriptExecutionResult = CodeExecutionResult & OutputTruncationInfo;
+/**
+ * 后台收割时限钳制：与同步共用 `normalizeTimeoutMs` 同一实现，只换上限常量。
+ *
+ * 单点是刻意的：后台若另写一个 clamp，就会与同步侧的「1s 下限 / 上限语义」分叉，
+ * 两处漂移后难以判断哪边是真理源。
+ */
+export declare function normalizeBackgroundTimeoutMs(timeoutMs: number): number;
 /**
  * Windows 平台 shell 档脚本守卫
  *
@@ -22,23 +64,79 @@ export type ScriptExecutionResult = CodeExecutionResult;
  * @returns 命中拦截返回显式错误文案（含替代方案），否则 null
  */
 export declare function guardWindowsShellScript(scriptPath: string, runtime: ScriptRuntime, platform: NodeJS.Platform): string | null;
+/**
+ * 同步杀树原语——**专供** `process.on('exit')` 钩子（`BackgroundTaskRegistry` 兜底收割）
+ *
+ * 为什么必须同步（与 `killProcessTree` 并存的原因，不是冗余双轨）：
+ *   exit 钩子返回后 Node 立即退出，异步 `spawn` 的 fork 由 libuv 线程池派发，
+ *   可能**来不及完成** taskkill 就随宿主进程消失——杀树静默失败（假阴性）。
+ *   `execFileSync` 在当前进程内同步等 taskkill 执行完，钩子返回前杀树已落地。
+ *
+ * - Windows：`execFileSync('taskkill', …)`；退出码 128（目标已退出）= 强杀已达成，静默；
+ *   其他失败（权限不足等）降级 `child.kill()` 并记 WARN。
+ * - POSIX：`process.kill(-pid, 'SIGKILL')` 本就是同步系统调用，语义与异步版一致。
+ *
+ * 调用纪律：只在 exit 钩子（或等价的「进程即将终止、无后续异步机会」语境）使用；
+ * 常规运行时收割仍走 `killProcessTree`（异步版有完整 error/close 事件处理）。
+ */
+export declare function killProcessTreeSync(child: childProcess.ChildProcess): void;
+/**
+ * 裸命令 → shell 派发形态（纯函数，平台参数化可测）
+ *
+ * Windows 经 `cmd /c`，类 Unix 经 `sh -c`。**不在此引入 powershell/bash 第二档**——
+ * 那是宿主 shell 选型的议题，内核只做「命令 → 平台默认 shell」的单点映射。
+ *
+ * ⚠️ **本函数是「命令实际派发到哪个 shell」的唯一真源**（2026-10-03 审查 P0 锚点）：
+ * 宿主把该事实注入 system prompt「## 运行环境 · 默认 Shell」段供模型避坑，
+ * 两侧若不一致 = 对模型说假话（曾发生：宿主报 `PowerShell` 而此处是 `cmd`，
+ * 模型写 PowerShell 语法却由 cmd 执行，每次必败）。
+ * 宿主环境快照的 `shell` 字段经公开导出**直接消费本函数派生**（environmentProvider）——
+ * 单一真源无镜像副本，改映射即两侧同步生效（与 `run_command` / `run_project_script`
+ * 的 shell 档共用此派发形态）。
+ */
+export declare function resolveShellCommand(command: string, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+/**
+ * 执行裸 shell 命令（**同步**）：与脚本执行共用同一套进程治理（命令执行能力方案 §13.6-A/B），
+ * 只多一层「命令 → shell 派发」解析。后台形态见 `backgroundTasks` 注册表——
+ * 同一治理实现的另一条消费路径，不是另一套实现。
+ */
+export declare function runShellCommand(command: string, cwd?: string, timeoutMs?: number): Promise<ScriptExecutionResult>;
+/**
+ * 启动**后台**裸命令（立即返回，不等待进程结束）
+ *
+ * @param command 裸命令
+ * @param cwd 工作目录
+ * @param timeoutMs 收割时限（**null = 不限时**；后台任务可活过 turn，见
+ *        `BackgroundTaskRegistry.detachAll`）；由调用方按
+ *        `BACKGROUND_MAX_TIMEOUT_MS` 钳制后传入（钳制真源不在本函数内分支）
+ * @param onSettled 终局回调（完成 / 超时 / 出错均经此，**只调用一次**）
+ * @returns 句柄：killNow = 中途终止（异步杀树原语，运行时收割用）；
+ *          killNowSync = 同步杀树原语（**仅** exit 钩子兜底用，见 `killProcessTreeSync`）
+ */
+export declare function startBackgroundCommand(command: string, cwd: string | undefined, timeoutMs: number | null, onSettled: (result: ScriptExecutionResult) => void): {
+    killNow: () => void;
+    killNowSync: () => void;
+    peek: () => ScriptExecutionResult;
+};
 /**
  * 执行技能脚本：在隔离子进程中运行，收集 stdout/stderr/exitCode/timedOut
  *
  * @param scriptPath 脚本绝对路径
  * @param runtime 运行时（node/python/shell 白名单三档）
  * @param args 传给脚本的参数数组
- * @param timeoutMs 超时（毫秒，限制在 [1s, MAX_TIMEOUT_MS] 内）
+ * @param timeoutMs 超时（毫秒，限制在 [1s, SYNC_MAX_TIMEOUT_MS] 内）
  * @param cwd 子进程工作目录（可选；run_project_script 以项目根为 cwd，
  *        使项目脚本可加载项目本地依赖/相对数据文件）
- * @param nodePath node 可执行文件路径（可选，缺省 'node' 走 PATH）——供宿主注入真实
- *        node 路径用。
- *        ⚠️ 宿主尚未接入——`hosts/memora-vscode` 零注入点，故实际恒走缺省 `'node'`。
- *        且真解不止「传个路径」：Electron 宿主（VS Code）的
- *        `process.execPath` 指向应用二进制，需配 `ELECTRON_RUN_AS_NODE` 一类环境变量才能以
- *        node 语义执行 `.mjs` **文件**，而内核只收路径、不收环境（边界铁律：内核不持有平台知识）。
- *        ⇒ 真解 = 接口扩展（宿主上报运行时环境，内核零解释转发），留待与宿主 shell 选型同批。
- *        此处保留该可选参数：接入点已就绪，扩展时无须再动调用链。
+ * @param nodePath node 可执行文件路径（可选，缺省 'node' 走 PATH）——宿主经
+ *        `AgentOptions.scriptNodePath` 注入用户显式配置（VS Code 宿主读
+ *        `memora.scriptNodePath` 工作区设置，未配置传 undefined 走缺省）。
+ *        ⚠️ 若宿主想自动注入 `process.execPath`（Electron 宿主该路径指向应用二进制），
+ *        需配 `ELECTRON_RUN_AS_NODE` 一类环境变量才能以 node 语义执行 `.mjs` **文件**，
+ *        而内核只收路径、不收环境（边界铁律：内核不持有平台知识）——故内核只留路径
+ *        注入点，运行时探测与环境变量配齐是宿主侧职责。
  */
 export declare function runSkillScript(scriptPath: string, runtime: ScriptRuntime, args?: string[], timeoutMs?: number, cwd?: string, nodePath?: string): Promise<ScriptExecutionResult>;
 /**
@@ -64,10 +162,10 @@ export declare function shouldFallbackPythonToPy(runtime: ScriptRuntime, platfor
 export declare function isPythonUnavailable(result: ScriptExecutionResult & {
     enoent: boolean;
 }, platform: NodeJS.Platform): boolean;
-/** formatExecutionResult 的三态标签配置：前缀与详情文案（run_skill_script / run_code 各自定制） */
+/** formatExecutionResult 的三态标签配置：前缀与详情文案（run_skill_script / run_code / run_command 各自定制） */
 export interface ExecutionResultFormatLabels {
-    /** 三态前缀标签（'SCRIPT' → [SCRIPT_TIMEOUT]/[SCRIPT_ERROR]；'CODE' → [CODE_TIMEOUT]/[CODE_ERROR]） */
-    kind: 'SCRIPT' | 'CODE';
+    /** 三态前缀标签（'SCRIPT' → [SCRIPT_TIMEOUT]/[SCRIPT_ERROR]；'CODE' → [CODE_TIMEOUT]/[CODE_ERROR]；'COMMAND' → [COMMAND_TIMEOUT]/[COMMAND_ERROR]） */
+    kind: 'SCRIPT' | 'CODE' | 'COMMAND';
     /** 超时详情文案（如「脚本执行超时（超过 120s）」） */
     timeoutDetail: string;
     /** 失败详情文案（如「代码执行失败」） */
@@ -83,7 +181,7 @@ export interface ExecutionResultFormatLabels {
  * @param labels 三态前缀标签与详情文案
  * @returns 格式化后的可读字符串（供工具返回值注入 LLM 上下文）
  */
-export declare function formatExecutionResult(result: CodeExecutionResult, labels: ExecutionResultFormatLabels): string;
+export declare function formatExecutionResult(result: CodeExecutionResult & OutputTruncationInfo, labels: ExecutionResultFormatLabels): string;
 /**
  * 格式化脚本执行结果为可读字符串（供 tool 返回值）：formatExecutionResult 的 SCRIPT 变体
  *
@@ -94,4 +192,38 @@ export declare function formatExecutionResult(result: CodeExecutionResult, label
  * @param timeoutMs 本次实际超时（毫秒）；省略则用 DEFAULT_TIMEOUT_MS（与执行侧默认同源）
  */
 export declare function formatScriptResult(result: ScriptExecutionResult, timeoutMs?: number): string;
+/**
+ * 同步命令的**实际生效超时**（毫秒）：run_command 同步路径的钳制真源入口。
+ *
+ * 存在的理由是「执行侧与文案侧同源」这条硬约束：`runShellCommand` 内部钳制，
+ * 若文案侧自行 clamp 就会重演「实际 60s 超时却告知超过 600s」的谎报。
+ * 调用方拿本值同时喂给执行与格式化，两侧恒等。
+ *
+ * @param timeoutMs LLM 传入值（undefined/非法 → 取默认 60s）
+ */
+export declare function resolveCommandTimeoutMs(timeoutMs: number | undefined): number;
+/**
+ * 格式化命令执行结果为可读字符串（run_command 同步 / kill_command 回传 / 后台回流共用）
+ *
+ * **定长真源在此**（见 `COMMAND_RESULT_MAX_CHARS`）：本函数是命令结果进上下文的唯一收口，
+ * 调用方**不要**再各自套一层上限——那会让「限了多少」在两处漂移。
+ *
+ * 超时文案用**调用方传入的本次实际生效超时**（`resolveCommandTimeoutMs` 的产物）；
+ * 传 undefined 表示本次未设收割时限（后台缺省），此时只说「超时」不编造秒数——
+ * 报一个不存在的秒数比不报更坏（LLM 会据此误判该等多久）。
+ */
+export declare function formatCommandResult(result: ScriptExecutionResult, effectiveTimeoutMs?: number): string;
+/**
+ * 格式化「被主动终止」的命令输出（kill_command 专用）
+ *
+ * ⚠️ 刻意**不走** `formatCommandResult`：进程被强杀时**没有退出码**——
+ * `peek()` 取的 -1 意思是「尚未退出」，不是「退出码 -1」。丢给三态格式化会被判成
+ * `[COMMAND_ERROR] 命令执行失败（退出码: -1）`，与 kill_command 头部的「已终止」
+ * 自相矛盾（对 LLM 是谎报：它会以为命令自己挂了，而不是被我们停掉）。
+ *
+ * 因此这里只如实列出截至终止时已捕获的输出，不声称任何退出状态。定长口径与
+ * `formatCommandResult` **同源**（同一对常量）——两个函数对「多少字进上下文」的
+ * 判断若有差异，LLM 就会在同一会话里看到两种长度 policy。
+ */
+export declare function formatKilledCommandOutput(result: ScriptExecutionResult): string;
 //# sourceMappingURL=skillScriptRunner.d.ts.map

package/dist/skill/skillScriptRunner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillScriptRunner.d.ts","sourceRoot":"","sources":["../../src/skill/skillScriptRunner.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,0DAA0D;AAC1D,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAoBxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACxB,MAAM,GAAG,IAAI,CAaf;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,MAAM,EAAO,EACnB,SAAS,GAAE,MAA2B,EACtC,GAAG,CAAC,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAgHhC;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACxB,OAAO,CAET;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,qBAAqB,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,EACnD,QAAQ,EAAE,MAAM,CAAC,QAAQ,GACxB,OAAO,CAGT;AAgCD,8EAA8E;AAC9E,MAAM,WAAW,2BAA2B;IAC1C,8FAA8F;IAC9F,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE,2BAA2B,GAClC,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,MAA2B,GACrC,MAAM,CAMR"}
+{"version":3,"file":"skillScriptRunner.d.ts","sourceRoot":"","sources":["../../src/skill/skillScriptRunner.ts"],"names":[],"mappings":"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"}