pulse-coder-engine 0.0.1-alpha.3 → 0.0.1-alpha.6

package/dist/index.d.cts

@@ -1,51 +1,9 @@
-import { FlexibleSchema, ModelMessage, StepResult, ToolSet, streamText, Tool as Tool$1 } from 'ai';
-import { E as EnginePluginLoadOptions } from './index-DDqISE31.cjs';
-export { B as BuiltInSkillRegistry, a as EnginePlugin, b as EnginePluginContext, c as builtInMCPPlugin, d as builtInPlugins, e as builtInSkillsPlugin } from './index-DDqISE31.cjs';
+import { C as ClarificationRequest, T as Tool, L as LLMProviderFactory, S as SystemPromptOption, a as ToolHooks, b as Context, c as ToolExecutionContext, E as EnginePluginLoadOptions, I as ILogger, d as EngineRunHook } from './index-BkkQyz2L.cjs';
+export { B as BuiltInPlanModeService, e as BuiltInSkillRegistry, f as EnginePlugin, g as EnginePluginContext, h as Extension, i as IExtensionContext, j as IPlugin, M as ModePolicy, P as PlanIntentLabel, k as PlanMode, l as PlanModeEvent, m as PlanModeEventName, n as PlanModeService, o as PlanModeTransitionResult, p as ToolCategory, q as ToolMeta, r as ToolRisk, s as builtInMCPPlugin, t as builtInPlanModePlugin, u as builtInPlugins, v as builtInSkillsPlugin } from './index-BkkQyz2L.cjs';
+import { StepResult, ModelMessage, ToolSet, streamText, Tool as Tool$1 } from 'ai';
 import { z } from 'zod';
 import 'events';
 
-interface ClarificationRequest {
-    id: string;
-    question: string;
-    context?: string;
-    defaultAnswer?: string;
-    timeout: number;
-}
-interface ToolExecutionContext {
-    onClarificationRequest?: (request: ClarificationRequest) => Promise<string>;
-    abortSignal?: AbortSignal;
-}
-interface Tool<Input = any, Output = any> {
-    name: string;
-    description: string;
-    inputSchema: FlexibleSchema<Input>;
-    execute: (input: Input, context?: ToolExecutionContext) => Promise<Output>;
-}
-interface Context {
-    messages: ModelMessage[];
-}
-interface IPlugin {
-    name: string;
-    version: string;
-    extensions: Extension[];
-    activate(context: IExtensionContext): Promise<void>;
-    deactivate?(): Promise<void>;
-}
-interface Extension {
-    type: 'skill' | 'mcp' | 'tool' | 'context';
-    provider: any;
-}
-interface IExtensionContext {
-    registerTools(toolName: string, tool: Tool<any, any>): void;
-    logger: ILogger;
-}
-interface ILogger {
-    debug(message: string, meta?: Record<string, unknown>): void;
-    info(message: string, meta?: Record<string, unknown>): void;
-    warn(message: string, meta?: Record<string, unknown>): void;
-    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
-}
-
 interface LoopOptions {
     onText?: (delta: string) => void;
     onToolCall?: (toolCall: any) => void;
@@ -56,6 +14,14 @@ interface LoopOptions {
     onResponse?: (messages: StepResult<ToolSet>['response']['messages']) => void;
     abortSignal?: AbortSignal;
     tools?: Record<string, Tool>;
+    /** Custom LLM provider factory. Overrides the default provider when set. */
+    provider?: LLMProviderFactory;
+    /** Model name passed to the provider. Overrides DEFAULT_MODEL when set. */
+    model?: string;
+    /** Custom system prompt. See SystemPromptOption for the three supported forms. */
+    systemPrompt?: SystemPromptOption;
+    /** Hooks fired around every tool execution (before/after). */
+    hooks?: ToolHooks;
 }
 declare function loop(context: Context, options?: LoopOptions): Promise<string>;
 
@@ -169,6 +135,12 @@ interface StreamOptions {
         chunk: any;
     }) => void;
     toolExecutionContext?: ToolExecutionContext;
+    /** Custom LLM provider. Falls back to the default CoderAI provider when not set. */
+    provider?: LLMProviderFactory;
+    /** Model name to pass to the provider. Falls back to DEFAULT_MODEL when not set. */
+    model?: string;
+    /** Custom system prompt. See SystemPromptOption for the three supported forms. */
+    systemPrompt?: SystemPromptOption;
 }
 declare const streamTextAI: (messages: ModelMessage[], tools: Record<string, Tool>, options?: StreamOptions) => ReturnType<typeof streamText> & {
     steps: StepResult<any>[];
@@ -182,6 +154,8 @@ type CompactResult = {
 };
 declare const maybeCompactContext: (context: Context, options?: {
     force?: boolean;
+    provider?: LLMProviderFactory;
+    model?: string;
 }) => Promise<CompactResult>;
 
 interface ClarifyInput {
@@ -342,6 +316,83 @@ interface EngineOptions {
     userConfigPlugins?: UserConfigPluginLoadOptions;
     disableBuiltInPlugins?: boolean;
     config?: Record<string, any>;
+    /**
+     * 自定义 LLM Provider。
+     * 接收模型名称，返回 Vercel AI SDK LanguageModel 实例。
+     * 未设置时使用环境变量配置的默认 Provider（OpenAI / Anthropic）。
+     *
+     * @example
+     * import { createOpenAI } from '@ai-sdk/openai';
+     * const engine = new Engine({
+     *   llmProvider: createOpenAI({ apiKey: 'sk-...', baseURL: 'https://my-proxy/v1' }).chat,
+     *   model: 'gpt-4o',
+     * });
+     */
+    llmProvider?: LLMProviderFactory;
+    /**
+     * 模型名称，传递给 llmProvider。未设置时使用 DEFAULT_MODEL。
+     */
+    model?: string;
+    /**
+     * 直接注册自定义工具，无需创建 EnginePlugin。
+     * 这些工具会与内置工具以及插件注册的工具合并。
+     * 若与内置工具同名，自定义工具优先级更高。
+     *
+     * @example
+     * import { z } from 'zod';
+     * const engine = new Engine({
+     *   tools: {
+     *     myTool: {
+     *       name: 'myTool',
+     *       description: '查询内部数据库',
+     *       inputSchema: z.object({ query: z.string() }),
+     *       execute: async ({ query }) => fetchFromDB(query),
+     *     },
+     *   },
+     * });
+     */
+    tools?: Record<string, Tool>;
+    /**
+     * 自定义 System Prompt，三种形式：
+     * - `string` — 完全替换内置 prompt
+     * - `() => string` — 工厂函数，每次请求调用（支持动态 prompt）
+     * - `{ append: string }` — 在内置 prompt 末尾追加业务上下文
+     *
+     * @example
+     * const engine = new Engine({
+     *   systemPrompt: { append: '公司规范：所有变量使用 camelCase。禁止使用 any 类型。' },
+     * });
+     */
+    systemPrompt?: SystemPromptOption;
+    /**
+     * Tool 执行钩子，在每次工具调用前/后触发。
+     * - `onBeforeToolCall` 可以修改入参，或抛错来拦截调用。
+     * - `onAfterToolCall` 可以修改返回值（如脱敏、截断）。
+     *
+     * @example
+     * const engine = new Engine({
+     *   hooks: {
+     *     onBeforeToolCall: (name, input) => {
+     *       if (name === 'bash') throw new Error('bash 工具已被禁用');
+     *     },
+     *     onAfterToolCall: (name, input, output) => {
+     *       auditLogger.log({ name, input, output });
+     *       return output;
+     *     },
+     *   },
+     * });
+     */
+    hooks?: ToolHooks;
+    /**
+     * 自定义日志实现。未设置时使用 console.*。
+     * 兼容 winston / pino 等主流日志库。
+     *
+     * @example
+     * import pino from 'pino';
+     * const logger = pino();
+     * const engine = new Engine({ logger });
+     */
+    logger?: ILogger;
 }
 /**
  * 重构后的引擎类
@@ -362,6 +413,7 @@ declare class Engine {
      * 准备引擎插件列表（包含内置插件）
      */
     private prepareEnginePlugins;
+    private applyRunHooks;
     /**
      * 运行AI循环
      */
@@ -373,6 +425,7 @@ declare class Engine {
         enginePlugins: string[];
         userConfigPlugins: string[];
         tools: string[];
+        runHooks: string[];
         services: string[];
         protocols: string[];
     };
@@ -401,11 +454,13 @@ declare class PluginManager {
     private enginePlugins;
     private userConfigPlugins;
     private tools;
+    private runHooks;
     private services;
     private protocols;
     private config;
     private events;
     private logger;
+    constructor(logger?: ILogger);
     /**
      * 初始化插件系统
      */
@@ -457,6 +512,10 @@ declare class PluginManager {
      * 工具获取
      */
     getTools(): Record<string, any>;
+    /**
+     * 运行时钩子获取
+     */
+    getRunHooks(): EngineRunHook[];
     /**
      * 服务获取
      */
@@ -472,6 +531,7 @@ declare class PluginManager {
         enginePlugins: string[];
         userConfigPlugins: string[];
         tools: string[];
+        runHooks: string[];
         services: string[];
         protocols: string[];
     };
@@ -481,4 +541,4 @@ declare class PluginManager {
     private resolvePath;
 }
 
-export { BashTool, BuiltinTools, BuiltinToolsMap, type ClarificationRequest, ClarifyTool, type Context, EditTool, Engine, type Extension, GrepTool, type IExtensionContext, type ILogger, type IPlugin, LsTool, PluginManager, Engine as PulseAgent, ReadTool, TavilyTool, type Tool, type ToolExecutionContext, type UserConfigPlugin, type UserConfigPluginLoadOptions, WriteTool, getFinalToolsMap, loop, maybeCompactContext, streamTextAI };
+export { BashTool, BuiltinTools, BuiltinToolsMap, ClarificationRequest, ClarifyTool, Context, EditTool, Engine, GrepTool, ILogger, LLMProviderFactory, LsTool, PluginManager, Engine as PulseAgent, ReadTool, SystemPromptOption, TavilyTool, Tool, ToolExecutionContext, ToolHooks, type UserConfigPlugin, type UserConfigPluginLoadOptions, WriteTool, getFinalToolsMap, loop, maybeCompactContext, streamTextAI };

package/dist/index.d.ts

@@ -1,51 +1,9 @@
-import { FlexibleSchema, ModelMessage, StepResult, ToolSet, streamText, Tool as Tool$1 } from 'ai';
-import { E as EnginePluginLoadOptions } from './index-DDqISE31.js';
-export { B as BuiltInSkillRegistry, a as EnginePlugin, b as EnginePluginContext, c as builtInMCPPlugin, d as builtInPlugins, e as builtInSkillsPlugin } from './index-DDqISE31.js';
+import { C as ClarificationRequest, T as Tool, L as LLMProviderFactory, S as SystemPromptOption, a as ToolHooks, b as Context, c as ToolExecutionContext, E as EnginePluginLoadOptions, I as ILogger, d as EngineRunHook } from './index-BkkQyz2L.js';
+export { B as BuiltInPlanModeService, e as BuiltInSkillRegistry, f as EnginePlugin, g as EnginePluginContext, h as Extension, i as IExtensionContext, j as IPlugin, M as ModePolicy, P as PlanIntentLabel, k as PlanMode, l as PlanModeEvent, m as PlanModeEventName, n as PlanModeService, o as PlanModeTransitionResult, p as ToolCategory, q as ToolMeta, r as ToolRisk, s as builtInMCPPlugin, t as builtInPlanModePlugin, u as builtInPlugins, v as builtInSkillsPlugin } from './index-BkkQyz2L.js';
+import { StepResult, ModelMessage, ToolSet, streamText, Tool as Tool$1 } from 'ai';
 import { z } from 'zod';
 import 'events';
 
-interface ClarificationRequest {
-    id: string;
-    question: string;
-    context?: string;
-    defaultAnswer?: string;
-    timeout: number;
-}
-interface ToolExecutionContext {
-    onClarificationRequest?: (request: ClarificationRequest) => Promise<string>;
-    abortSignal?: AbortSignal;
-}
-interface Tool<Input = any, Output = any> {
-    name: string;
-    description: string;
-    inputSchema: FlexibleSchema<Input>;
-    execute: (input: Input, context?: ToolExecutionContext) => Promise<Output>;
-}
-interface Context {
-    messages: ModelMessage[];
-}
-interface IPlugin {
-    name: string;
-    version: string;
-    extensions: Extension[];
-    activate(context: IExtensionContext): Promise<void>;
-    deactivate?(): Promise<void>;
-}
-interface Extension {
-    type: 'skill' | 'mcp' | 'tool' | 'context';
-    provider: any;
-}
-interface IExtensionContext {
-    registerTools(toolName: string, tool: Tool<any, any>): void;
-    logger: ILogger;
-}
-interface ILogger {
-    debug(message: string, meta?: Record<string, unknown>): void;
-    info(message: string, meta?: Record<string, unknown>): void;
-    warn(message: string, meta?: Record<string, unknown>): void;
-    error(message: string, error?: Error, meta?: Record<string, unknown>): void;
-}
-
 interface LoopOptions {
     onText?: (delta: string) => void;
     onToolCall?: (toolCall: any) => void;
@@ -56,6 +14,14 @@ interface LoopOptions {
     onResponse?: (messages: StepResult<ToolSet>['response']['messages']) => void;
     abortSignal?: AbortSignal;
     tools?: Record<string, Tool>;
+    /** Custom LLM provider factory. Overrides the default provider when set. */
+    provider?: LLMProviderFactory;
+    /** Model name passed to the provider. Overrides DEFAULT_MODEL when set. */
+    model?: string;
+    /** Custom system prompt. See SystemPromptOption for the three supported forms. */
+    systemPrompt?: SystemPromptOption;
+    /** Hooks fired around every tool execution (before/after). */
+    hooks?: ToolHooks;
 }
 declare function loop(context: Context, options?: LoopOptions): Promise<string>;
 
@@ -169,6 +135,12 @@ interface StreamOptions {
         chunk: any;
     }) => void;
     toolExecutionContext?: ToolExecutionContext;
+    /** Custom LLM provider. Falls back to the default CoderAI provider when not set. */
+    provider?: LLMProviderFactory;
+    /** Model name to pass to the provider. Falls back to DEFAULT_MODEL when not set. */
+    model?: string;
+    /** Custom system prompt. See SystemPromptOption for the three supported forms. */
+    systemPrompt?: SystemPromptOption;
 }
 declare const streamTextAI: (messages: ModelMessage[], tools: Record<string, Tool>, options?: StreamOptions) => ReturnType<typeof streamText> & {
     steps: StepResult<any>[];
@@ -182,6 +154,8 @@ type CompactResult = {
 };
 declare const maybeCompactContext: (context: Context, options?: {
     force?: boolean;
+    provider?: LLMProviderFactory;
+    model?: string;
 }) => Promise<CompactResult>;
 
 interface ClarifyInput {
@@ -342,6 +316,83 @@ interface EngineOptions {
     userConfigPlugins?: UserConfigPluginLoadOptions;
     disableBuiltInPlugins?: boolean;
     config?: Record<string, any>;
+    /**
+     * 自定义 LLM Provider。
+     * 接收模型名称，返回 Vercel AI SDK LanguageModel 实例。
+     * 未设置时使用环境变量配置的默认 Provider（OpenAI / Anthropic）。
+     *
+     * @example
+     * import { createOpenAI } from '@ai-sdk/openai';
+     * const engine = new Engine({
+     *   llmProvider: createOpenAI({ apiKey: 'sk-...', baseURL: 'https://my-proxy/v1' }).chat,
+     *   model: 'gpt-4o',
+     * });
+     */
+    llmProvider?: LLMProviderFactory;
+    /**
+     * 模型名称，传递给 llmProvider。未设置时使用 DEFAULT_MODEL。
+     */
+    model?: string;
+    /**
+     * 直接注册自定义工具，无需创建 EnginePlugin。
+     * 这些工具会与内置工具以及插件注册的工具合并。
+     * 若与内置工具同名，自定义工具优先级更高。
+     *
+     * @example
+     * import { z } from 'zod';
+     * const engine = new Engine({
+     *   tools: {
+     *     myTool: {
+     *       name: 'myTool',
+     *       description: '查询内部数据库',
+     *       inputSchema: z.object({ query: z.string() }),
+     *       execute: async ({ query }) => fetchFromDB(query),
+     *     },
+     *   },
+     * });
+     */
+    tools?: Record<string, Tool>;
+    /**
+     * 自定义 System Prompt，三种形式：
+     * - `string` — 完全替换内置 prompt
+     * - `() => string` — 工厂函数，每次请求调用（支持动态 prompt）
+     * - `{ append: string }` — 在内置 prompt 末尾追加业务上下文
+     *
+     * @example
+     * const engine = new Engine({
+     *   systemPrompt: { append: '公司规范：所有变量使用 camelCase。禁止使用 any 类型。' },
+     * });
+     */
+    systemPrompt?: SystemPromptOption;
+    /**
+     * Tool 执行钩子，在每次工具调用前/后触发。
+     * - `onBeforeToolCall` 可以修改入参，或抛错来拦截调用。
+     * - `onAfterToolCall` 可以修改返回值（如脱敏、截断）。
+     *
+     * @example
+     * const engine = new Engine({
+     *   hooks: {
+     *     onBeforeToolCall: (name, input) => {
+     *       if (name === 'bash') throw new Error('bash 工具已被禁用');
+     *     },
+     *     onAfterToolCall: (name, input, output) => {
+     *       auditLogger.log({ name, input, output });
+     *       return output;
+     *     },
+     *   },
+     * });
+     */
+    hooks?: ToolHooks;
+    /**
+     * 自定义日志实现。未设置时使用 console.*。
+     * 兼容 winston / pino 等主流日志库。
+     *
+     * @example
+     * import pino from 'pino';
+     * const logger = pino();
+     * const engine = new Engine({ logger });
+     */
+    logger?: ILogger;
 }
 /**
  * 重构后的引擎类
@@ -362,6 +413,7 @@ declare class Engine {
      * 准备引擎插件列表（包含内置插件）
      */
     private prepareEnginePlugins;
+    private applyRunHooks;
     /**
      * 运行AI循环
      */
@@ -373,6 +425,7 @@ declare class Engine {
         enginePlugins: string[];
         userConfigPlugins: string[];
         tools: string[];
+        runHooks: string[];
         services: string[];
         protocols: string[];
     };
@@ -401,11 +454,13 @@ declare class PluginManager {
     private enginePlugins;
     private userConfigPlugins;
     private tools;
+    private runHooks;
     private services;
     private protocols;
     private config;
     private events;
     private logger;
+    constructor(logger?: ILogger);
     /**
      * 初始化插件系统
      */
@@ -457,6 +512,10 @@ declare class PluginManager {
      * 工具获取
      */
     getTools(): Record<string, any>;
+    /**
+     * 运行时钩子获取
+     */
+    getRunHooks(): EngineRunHook[];
     /**
      * 服务获取
      */
@@ -472,6 +531,7 @@ declare class PluginManager {
         enginePlugins: string[];
         userConfigPlugins: string[];
         tools: string[];
+        runHooks: string[];
         services: string[];
         protocols: string[];
     };
@@ -481,4 +541,4 @@ declare class PluginManager {
     private resolvePath;
 }
 
-export { BashTool, BuiltinTools, BuiltinToolsMap, type ClarificationRequest, ClarifyTool, type Context, EditTool, Engine, type Extension, GrepTool, type IExtensionContext, type ILogger, type IPlugin, LsTool, PluginManager, Engine as PulseAgent, ReadTool, TavilyTool, type Tool, type ToolExecutionContext, type UserConfigPlugin, type UserConfigPluginLoadOptions, WriteTool, getFinalToolsMap, loop, maybeCompactContext, streamTextAI };
+export { BashTool, BuiltinTools, BuiltinToolsMap, ClarificationRequest, ClarifyTool, Context, EditTool, Engine, GrepTool, ILogger, LLMProviderFactory, LsTool, PluginManager, Engine as PulseAgent, ReadTool, SystemPromptOption, TavilyTool, Tool, ToolExecutionContext, ToolHooks, type UserConfigPlugin, type UserConfigPluginLoadOptions, WriteTool, getFinalToolsMap, loop, maybeCompactContext, streamTextAI };