@ai-setting/roy-agent-core 1.7.51 → 1.7.53

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;

package/dist/utils/media.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Media utils — magic-byte mime sniffing, media-type gate, image-input parsing
+ *
+ * 借鉴 opencode 设计：
+ * - ATTACH_FILE_MAX_BYTES = 10 MiB（防止 base64 内存爆炸）
+ * - sniffAttachmentMime 优先 magic bytes，其次扩展名（mime-types），最后 application/octet-stream
+ * - parseImageInput 支持本地路径 / http(s) URL / data:base64 URL
+ *
+ * 设计取舍：
+ * - 不引入 mime-types npm 依赖，自己用常见扩展名映射兜底（轻量级）
+ * - isMediaType 用 startsWith gate：image/audio/video/application/pdf
+ * - image/svg+xml 不算 media（LLM 多用位图，SVG 太特殊）
+ */
+import type { ContentPart } from "../env/llm/types";
+/**
+ * 附件最大字节数（10 MiB）。
+ * 借鉴 opencode 的 ATTACH_FILE_MAX_BYTES = 10 * 1024 * 1024（run.ts:59）。
+ * 超过即拒收，避免 base64 编码后内存爆炸。
+ */
+export declare const ATTACH_FILE_MAX_BYTES: number;
+/**
+ * 通过 magic bytes 检测 mime type。
+ * 顺序：PNG → JPEG → GIF → WebP → PDF → BMP
+ * 都不匹配则 fallback 到扩展名推断，都没则 application/octet-stream
+ *
+ * @param buffer 文件内容（Buffer 或 Uint8Array）
+ * @param fallbackName 可选的文件名，用于扩展名 fallback（如 "image.png"）
+ * @returns mime type 字符串
+ */
+export declare function sniffMimeType(buffer: Uint8Array, fallbackName?: string): string;
+/**
+ * 判断 mime 是否为 LLM 支持的多模态媒体（image / audio / video / pdf）。
+ *
+ * image/svg+xml 故意排除：SVG 是矢量图，LLM 多用 vision 处理位图；
+ * 如未来需要可加入白名单。
+ */
+export declare function isMediaType(mime: string): boolean;
+/**
+ * 解析图像输入并归一化为 ContentPart。
+ *
+ * 三种输入形式：
+ * 1. 本地路径：读取文件、sniff mime、超 10 MiB 抛错、返回 { type: 'image', image: Buffer }
+ * 2. http(s) URL：原样返回 { type: 'image', image: url }，由下游 AI SDK 处理
+ * 3. data:base64 URL：原样返回 { type: 'image', image: dataUrl }
+ *
+ * @param input 图像输入字符串
+ * @returns ContentPart（必为 image 类型）
+ */
+export declare function parseImageInput(input: string): Promise<ContentPart>;
+/**
+ * Multi-source image MIME detection used by adapter-pi-ai.ts toPiMessages().
+ *
+ * Hardcoding `mimeType: "image/*"` upstream made every vision provider
+ * return HTTP 400 ("media type \"image/*\" not supported"). This helper
+ * sniffs from 4 sources, in priority order:
+ *
+ *   1. Explicit `mediaType` if it's already specific (not "image/*")
+ *   2. `data:` URL prefix (e.g. `data:image/jpeg;base64,...`)
+ *   3. HTTP(S) URL suffix (.jpg/.jpeg/.png/.gif/.webp/.bmp)
+ *   4. Buffer magic bytes (JPEG / PNG / GIF / WebP / BMP)
+ *
+ * If NONE of these succeed, throws an explicit error instead of silently
+ * emitting the `"image/*"` wildcard.
+ *
+ * @param image  Uint8Array buffer / data: URL / http(s) URL
+ * @param explicitMediaType  optional caller-provided MIME (e.g. from LLMMessage)
+ * @returns  detected MIME string (e.g. "image/jpeg")
+ * @throws  Error with clear message when MIME cannot be determined
+ */
+export declare function sniffImageMime(image: Uint8Array | string, explicitMediaType?: string): string;

package/dist/utils/temp-file-manager/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * TempFileManager — singleton manager for tool output truncation temp files.
+ *
+ * When tool output is truncated, the full content is saved to a temp file so the
+ * LLM can use `read_file` to retrieve specific portions.
+ *
+ * Features:
+ * - Cross-platform: uses `os.tmpdir()` + `path.join()` (Linux/macOS/Windows)
+ * - Process lifecycle: cleans up on exit/SIGINT/SIGTERM
+ * - Stale file sweep: cleans up files older than 24h at startup
+ * - Concurrent safe: uses `crypto.randomUUID()` for unique filenames
+ * - Large file safety: warns for content > 10MB (does not block)
+ * - Singleton: shared instance via `getInstance()`
+ *
+ * File naming: `roy-agent-truncation-{pid}-{uuid}-{prefix}.txt`
+ * Examples:
+ *   Linux:   /tmp/roy-agent-truncation-12345-abc123-def456-bash.txt
+ *   macOS:   /var/folders/xx/yy/T/roy-agent-truncation-12345-abc123-def456-bash.txt
+ *   Windows: C:\Users\xxx\AppData\Local\Temp\roy-agent-truncation-12345-abc123-def456-bash.txt
+ */
+export declare class TempFileManager {
+    private static _instance;
+    private readonly _files;
+    private _hooksRegistered;
+    private static readonly FILE_PREFIX;
+    private static readonly FILE_EXT;
+    private static readonly LARGE_FILE_THRESHOLD;
+    private static readonly STALE_FILE_AGE_MS;
+    /**
+     * Private constructor — use `getInstance()` instead.
+     */
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * Note: This intentionally holds a strong reference for the process lifetime
+     * because process exit hooks reference the instance.
+     */
+    static getInstance(): TempFileManager;
+    /**
+     * Reset the singleton instance (for testing only).
+     *
+     * @internal
+     */
+    static _resetForTesting(): void;
+    /**
+     * Write content to a temporary file and track it for later cleanup.
+     *
+     * @param content - The text content to write to the file
+     * @param prefix - A short string to identify the source (e.g., tool name)
+     * @returns Absolute path to the created temp file
+     *
+     * @example
+     * const path = await TempFileManager.getInstance().writeTempFile(
+     *   "large output...",
+     *   "bash"
+     * );
+     * // → "/tmp/roy-agent-truncation-12345-abc123-bash.txt"
+     */
+    writeTempFile(content: string, prefix?: string): Promise<string>;
+    /**
+     * Remove all temp files created by this instance.
+     *
+     * Missing files are silently skipped (no error thrown).
+     */
+    cleanupAll(): Promise<void>;
+    /**
+     * Get the count of currently tracked temp files.
+     *
+     * Useful for tests and diagnostics.
+     */
+    getActiveFileCount(): number;
+    /**
+     * Sweep stale temp files from previous sessions (older than 24h).
+     *
+     * Called automatically on first instantiation. Can also be called manually
+     * for housekeeping (e.g., on a timer).
+     *
+     * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+     * @returns Number of files deleted
+     */
+    sweepStaleFiles(maxAgeMs?: number): Promise<number>;
+    /**
+     * Ensure process exit hooks are registered (idempotent).
+     *
+     * Hooks clean up all tracked temp files when the process exits.
+     */
+    ensureHooksRegistered(): void;
+    /**
+     * Sanitize the prefix string to be safe for filenames.
+     *
+     * Removes characters that are problematic on any platform:
+     * - Path separators (/, \)
+     * - Reserved characters (<, >, :, ", |, ?, *)
+     * - Control characters
+     * - Spaces (replaced with -)
+     */
+    private sanitizePrefix;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-setting/roy-agent-core",
-  "version": "1.7.51",
+  "version": "1.7.53",
   "type": "module",
   "description": "Core SDK for roy-agent - Environment, Components, Tools, Sessions, Tasks",
   "main": "./dist/index.js",
@@ -28,7 +28,9 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bunup",
+    "build": "bunup && bun run build:dts",
+    "build:dts": "tsc -p tsconfig.dts.json --noCheck",
+    "typecheck:dts": "tsc -p tsconfig.dts.json --noEmit",
     "build:main": "bunup -- --entry src/index.ts",
     "clean": "rm -rf dist",
     "typecheck": "npx tsc --noEmit --skipLibCheck --project tsconfig.json",