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

package/dist/env/workflow/workflow-component.d.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview WorkflowComponent
+ *
+ * Workflow 组件入口，提供工作流管理和执行能力。
+ *
+ * 功能：
+ * - 工作流 CRUD 操作（通过 WorkflowService）
+ * - 工作流执行（通过 WorkflowEngine）
+ * - Decorator 节点注册
+ *
+ * Note: After session-based refactoring, workflow runs are managed via SessionComponent.
+ * The Session.metadata stores workflow run state (status, input, agentSessions).
+ * Node execution messages are stored in Session.messages with workflow.node.* roles.
+ */
+import 'reflect-metadata';
+import { BaseComponent, type ComponentConfig } from '../component';
+import type { WorkflowDefinition, RunOptions, RunResult } from './types';
+import { WorkflowService } from './service';
+import type { ToolComponent } from '../tool/tool-component';
+import type { LogTraceComponent } from '../log-trace/log-trace-component';
+import type { Environment } from '../interface';
+import type { AgentRunner } from './nodes/agent-node';
+export { EventBus, DAGManager, Scheduler, Executor, WorkflowEngine, } from './engine';
+export type { NodeExecutionContext, RunOptions, RunResult, RunStatus, NodeStatus, DAGAnalysis, SchedulerOptions, SchedulerState, ExecutorOptions, WorkflowEngineConfig, NodeContext, NodeFactory, } from './engine';
+export type { NodeDefinition, RetryConfig, TemplateResolver, } from './types';
+export type { WorkflowDefinition, } from './types/workflow';
+export { WorkflowService, WorkflowServiceRegistry, } from './service';
+export type { WorkflowOptions, NodeAsOptions, EdgeOptions, WorkflowMetadata, NodeMetadata, EdgeMetadata, ValidationResult, ConvertedWorkflowDefinition, ConvertedNodeDefinition, } from './types/decorators-types';
+export { Workflow, NodeAs, Edge, WorkflowEdges, getWorkflowMetadata, getNodeMetadatas, getEdgeMetadatas, DecoratorNode, } from './decorators';
+export type { DecoratorNodeConfig, } from './decorators/decorator-node';
+export { WorkflowConverter, } from './extractor/workflow-converter';
+export { createWorkflowFromClass } from './utils/create-workflow';
+export { registerDecoratorNodeType } from './utils/node-registry-helper';
+export interface WorkflowComponentConfig extends ComponentConfig {
+    /** 自动注册 decorator 节点类型 */
+    autoRegisterDecorators?: boolean;
+}
+export interface WorkflowComponentOptions {
+    /** Tool 组件（可选） */
+    toolComponent?: ToolComponent;
+    /** Log Trace 组件（可选） */
+    logTraceComponent?: LogTraceComponent;
+    /** Environment（包含 AgentComponent 等） */
+    env?: Environment;
+    /** Skill registry（可选） */
+    skillRegistry?: {
+        getSkill(name: string): any;
+        hasSkill(name: string): boolean;
+    };
+    /** Agent runner（可选，用于 agent 节点） */
+    agentRunner?: AgentRunner;
+}
+export declare class WorkflowComponent extends BaseComponent {
+    readonly name = "workflow";
+    readonly version = "1.0.0";
+    workflowService: WorkflowService | null;
+    sessionComponent: any;
+    private nodeRegistry;
+    private decoratorsRegistered;
+    /**
+     * 获取 WorkflowService 实例
+     */
+    getService(): WorkflowService | null;
+    private toolComponent?;
+    private logTraceComponent?;
+    private _workflowEnv?;
+    private skillRegistry?;
+    private agentRunner?;
+    /**
+     * 初始化 WorkflowComponent
+     */
+    init(options: any): Promise<void>;
+    /**
+     * 注册 decorator 节点类型
+     */
+    private registerDecorators;
+    /**
+     * Note: After session-based refactoring, runRepository is no longer needed.
+     * Workflow runs are managed via SessionComponent.
+     */
+    createService(options: {
+        workflowRepository: any;
+        toolComponent?: ToolComponent;
+        env?: Environment;
+        skillRegistry?: {
+            getSkill(name: string): any;
+            hasSkill(name: string): boolean;
+        };
+        sessionComponent?: any;
+        tagRepository?: any;
+    }): WorkflowService;
+    /**
+     * 运行工作流定义
+     */
+    runWorkflow(definition: WorkflowDefinition, input?: Record<string, any>, options?: RunOptions): Promise<RunResult>;
+    /**
+     * 停止组件并清理资源
+     *
+     * 遵循 Component 接口契约，通过 onStop 钩子实现
+     */
+    protected onStop(): Promise<void>;
+    /**
+     * 启动组件 - 初始化持久化的 SQLite WorkflowService
+     */
+    start(): Promise<void>;
+    /**
+     * 注册 ask_user 工具到 ToolComponent
+     *
+     * 这样 Workflow 中的 AgentNode 执行时，Agent 能够找到并调用 ask_user 工具。
+     * ask_user 工具会抛出 AskUserError，触发 workflow pause。
+     */
+    private registerAskUserTool;
+    /**
+     * 注册 workflow tools 到 ToolComponent
+     *
+     * 注册 5 个 workflow 工具：workflow_get, workflow_list, workflow_run,
+     * workflow_run_status, workflow_run_stop。
+     *
+     * 注意：这些工具不自动加入 defaultTools，只通过 ToolComponent 的注册表可见。
+     * 只有通过 allowedTools 明确引用的 agent（如 workflow-runner）才能使用。
+     */
+    private registerWorkflowTools;
+    /**
+     * 初始化 SQLite 持久化的 WorkflowService
+     *
+     * Note: After session-based refactoring, runRepository is no longer needed.
+     * Workflow runs are managed via SessionComponent.
+     */
+    private initSqliteService;
+    /**
+     * 创建内存中的 WorkflowService（用于快速运行或降级）
+     */
+    private createInMemoryService;
+    /**
+     * 停止组件
+     */
+    stop(): Promise<void>;
+}

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @roy-agent/core - Core SDK
+ */
+export { generateId, generateDescendingId } from "./utils/id";
+export { ATTACH_FILE_MAX_BYTES, sniffMimeType, isMediaType, parseImageInput, } from "./utils/media";
+export { type Environment, BaseEnvironment, } from "./env";
+export type { EnvironmentConfig, BaseEnvironmentConfig, EnvEvent, EnvEventMetadata, EnvEventHandler, Action, Context, } from "./env";
+export { type Component, type ComponentConfig, type ComponentSchema, type ComponentPaths, type ComponentStatus, type ComponentConfigChangeEvent, type ComponentWatchCallback, BaseComponent, } from "./env/component";
+export { globalHookManager, type HookPhase, type HookMeta, type BaseHookContext, // 通用 HookContext
+type BaseHook, // 通用 Hook
+type BaseHookFn, // 通用 HookFn
+type HookManagerOptions, type HookAction, type HookResult, type HookActionType, createHook, createPriorityHook, HookManager, } from "./env/hook";
+export { type XDGPaths, type XDGDirType, XDG_PATHS, getXDGPaths, getXDGPath, } from "./env/paths";
+export { type ConfigSource, type ConfigSourceType, type ConfigChangeEvent, type ComponentRegistration, ConfigComponent, } from "./config/config-component";
+export { LLMComponent, type LLMComponentOptions, type ContentPart, type LLMMessage, type LLMOutput, type UsageInfo, type ToolCall, type LLMConfig, type LLMProvider, type ProviderConfig, type ProviderType, type LLMInvokeRequest, type LLMInvokeResult, type StreamEvent, invoke, invokeNonStream, parseModelString, createInvokeConfig, type InvokeConfig, type InvokeOptions, type LLMToolContext, type ConvertedUsageInfo, LLMConfigSchema, ProviderConfigSchema, ProviderCapabilitiesSchema, ModelLimitsSchema, LLMDefaultConfigSchema, isOpencodeProvider, isOpencodeEndpoint, buildOpencodeHeaders, } from "./env/llm";
+export { ToolComponent, type ToolComponentConfig, type Tool, type ToolInfo, type ToolResult, type ToolResultMetadata, type ToolMetadata, type SandboxConfig, type ValidationResult, ToolRegistry, ToolValidator, getAllBuiltInTools, getBuiltInTool, bashTool, globTool, readFileTool, writeFileTool, editFileTool, grepTool, understandImageTool, setUnderstandImageLLMProvider, getUnderstandImageLLMProvider, resetUnderstandImageLLMProvider, type UnderstandImageLLMProvider, } from "./env/tool";
+export type { ToolContext } from "./env/tool/types";
+export type { ToolHookContext } from "./env/tool/tool-component";
+export { AgentComponent, type AgentComponentConfig, type AgentContext, AgentComponentConfigSchema, type Plugin, type HookPoint, type HookContext, } from "./env/agent";
+export { AgentRegistry, type AgentDefinition, type AgentType, type AgentConfig, type ExportOptions, } from "./env/agent/agent-registry";
+export { LogTraceComponent, type LogTraceConfig, type LogTraceComponentOptions, LogTraceConfigSchema, Traced, TracedAs, TracedLightweight, wrapFunction, type TracedOptions, createLogger, getLogDir, setLogDirOverride, setQuietMode, isQuietMode, getLogLevels, getLogLevel, setLoggerConfigComponent, SQLiteSpanStorage, type SpanContext, type SpanAttributes, type Span, type TraceInfo, type SpanStorage, type LogLevel, type LoggerConfig, type ILogger, SpanKind, SpanStatus, OTelTracerProvider, getTracerProvider, resetTracerProvider, type OTelTracer, type OTelSpan, type SpanOptions, propagation, } from "./env/log-trace";
+export { DebugComponent, TraceFormatter, TreeFormatter, ReplFormatter, type TraceDataSource, type TraceParserOptions, } from "./env/debug";
+export type { TraceEntry, TraceTreeNode, ParserOptions, LogDiscoveryOptions, TraceIdInfo, TraceSummary, TraceAction, LogLevel as DebugLogLevel, FormatOptions, } from "./env/debug";
+export { PromptComponent, type PromptComponentOptions, } from "./env/prompt/prompt-component";
+export { PromptStore } from "./env/prompt/prompt-store";
+export { closeDatabase } from "./env/workflow/storage/sqlite";
+export type { PromptConfig, PromptPath, PromptEntry, PromptSource, PromptHook, RenderHookContext, PromptHookMap, } from "./env/prompt/types";
+export { SessionComponent, MemorySessionStore, } from "./env/session";
+export type { Session, SessionMessage, SessionConfig, CreateSessionOptions, UpdateSessionOptions, ListSessionsOptions, AddMessageOptions, SessionCheckpoint, CompactOptions, CompactResult, CompactPreview, GetContextOptions, GetContextResult, CheckpointType, SearchMessagesOptions, MessageMatch, SearchResult, } from "./env/session/types";
+export { cascadeStopSessionTree, type CascadeStopOptions, type CascadeStopResult, } from "./env/session-tree-stopper";
+export { createMemoryAgentTools, } from "./env/memory/tools/memory-agent-tools";
+export type { SearchSessionsParams, GetSessionParams, WriteMemoryParams, } from "./env/memory/tools/memory-agent-tools";
+export { getBuiltInPrompt, getBuiltInPromptNames, } from "./env/prompt/prompts-index";
+export { TaskComponent, SQLiteTaskStore, getDefaultTaskDbPath, } from "./env/task";
+export type { Task, TaskOperation, TaskStatus, TaskPriority, ActionType, CreateTaskOptions, UpdateTaskOptions, ListTasksOptions, CreateOperationOptions, ListOperationsOptions, TaskConfig, } from "./env/task/types";
+export { TaskTagPlugin, createAutoTaskPlugin, type AutoTaskPluginConfig, } from "./env/task/plugins";
+export { TaskHookPoints, type TaskHookPoint, } from "./env/task/hooks";
+export { SkillComponent, } from "./env/skill";
+export type { SkillEntry, SkillListItem, SkillConfig, SkillPath, SkillSource, SkillToolParams, } from "./env/skill/types";
+export { McpComponent, } from "./env/mcp";
+export type { McpComponentConfig, McpComponentOptions, McpPath, McpServerConfig, McpServerLocalConfig, McpServerRemoteConfig, McpServerStatus, DiscoveredMcpServer, } from "./env/mcp";
+export { MemoryComponent, } from "./env/memory";
+export type { MemoryConfig, MemoryPath, MemorySource, RecordMemoryParams, RecallMemoryParams, RecordMemoryMode, RecordMemoryResult, } from "./env/memory/types";
+export type { MemoryComponentOptions } from "./env/memory";
+export { MemoryPlugin, createMemoryPlugin, } from "./env/memory/plugin";
+export type { MemoryPluginConfig, } from "./env/memory/plugin/types";
+export { CommandsComponent, } from "./env/commands";
+export type { CommandsComponentConfig, CommandIndex, ScanResult, ExecutionResult, DiscoverOptions, AddCommandOptions, RemoveCommandOptions, CommandSource, CommandsComponentOptions, } from "./env/commands";
+export * from "./env/event-source";
+export { ErrorCodes, RoyError, AgentError, ToolError, LLMError, ComponentError, ContextError, isRoyError, getErrorCode, } from "./env/errors";
+export type { ErrorCode } from "./env/errors";
+export { WorkflowComponent, type WorkflowComponentConfig, } from "./env/workflow/workflow-component";
+export { AskUserError, type NodeInterruptEvent, type WorkflowAskUserEvent, } from "./env/workflow/types/workflow-hil";
+export { Workflow, WorkflowEdges, NodeAs, Edge, } from "./env/workflow/decorators";
+export type { WorkflowOptions, NodeAsOptions, EdgeMetadata, } from "./env/workflow/types/decorators-types";
+export { createWorkflowFromClass, } from "./env/workflow/utils/create-workflow";
+export { registerDecoratorNodeType, } from "./env/workflow/utils/node-registry-helper";
+export { PluginComponent, type PluginComponentOptions, } from "./env/plugin/plugin-component";
+export { BasePlugin, type PluginEnv, type HookDefinition, type HookHandler, type AgentInstanceConfig, type ToolDefinition, type HookResult as PluginHookResult, type HookContext as PluginHookContext, } from "./env/plugin/types";

package/dist/index.js

@@ -47,7 +47,7 @@ import {
 } from "./shared/@ai-setting/roy-agent-core-j5c3chtn.js";
 import {
   DebugComponent
-} from "./shared/@ai-setting/roy-agent-core-0cfaqnz9.js";
+} from "./shared/@ai-setting/roy-agent-core-k25gv86p.js";
 import {
   ReplFormatter,
   TraceFormatter,
@@ -66,7 +66,7 @@ import {
   BaseEnvironment,
   generateDescendingId,
   generateId
-} from "./shared/@ai-setting/roy-agent-core-rcfewbzr.js";
+} from "./shared/@ai-setting/roy-agent-core-4sx6sdb2.js";
 import {
   TaskComponent
 } from "./shared/@ai-setting/roy-agent-core-39xejr39.js";
@@ -92,7 +92,7 @@ import {
   larkCliHandler,
   resolveBountyIMSystemPrompt,
   timerHandler
-} from "./shared/@ai-setting/roy-agent-core-ezgsem94.js";
+} from "./shared/@ai-setting/roy-agent-core-ph5qbqcx.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -109,7 +109,7 @@ import {
 import {
   TaskTagPlugin,
   createAutoTaskPlugin
-} from "./shared/@ai-setting/roy-agent-core-pkpkctvf.js";
+} from "./shared/@ai-setting/roy-agent-core-hch2geta.js";
 import {
   EventStoreImpl,
   getSharedEventStore,
@@ -127,7 +127,7 @@ import"./shared/@ai-setting/roy-agent-core-brwzs8wf.js";
 import"./shared/@ai-setting/roy-agent-core-j8e92gj8.js";
 import {
   WorkflowComponent
-} from "./shared/@ai-setting/roy-agent-core-s214vmmd.js";
+} from "./shared/@ai-setting/roy-agent-core-4vpk40ss.js";
 import {
   init_node_registry_helper,
   registerDecoratorNodeType

package/dist/shared/@ai-setting/{roy-agent-core-rcfewbzr.js → roy-agent-core-4sx6sdb2.js}

@@ -1,6 +1,6 @@
 import {
   createAutoTaskPlugin
-} from "./roy-agent-core-pkpkctvf.js";
+} from "./roy-agent-core-hch2geta.js";
 import {
   ContextError,
   ErrorCodes

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

@@ -8,7 +8,7 @@ import {
   extractPerTaskChatId,
   extractPerTaskChatName,
   mergeChatOwnership
-} from "./roy-agent-core-pkpkctvf.js";
+} from "./roy-agent-core-hch2geta.js";
 import {
   getSharedEventStore
 } from "./roy-agent-core-yhsssn86.js";

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.52",
+  "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",