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

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.52",
+  "version": "1.7.55",
   "type": "module",
   "description": "Core SDK for roy-agent - Environment, Components, Tools, Sessions, Tasks",
   "main": "./dist/index.js",
@@ -28,12 +28,14 @@
     "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",
     "test:llm": "bun test test/llm/",
-    "test:llm:fast": "bun test --parallel 4 test/llm/"
+    "test:llm:fast": "bun test --parallel=4 test/llm/"
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.0",