pulse-coder-engine 0.0.1-alpha.2 → 0.0.1-alpha.4

package/dist/index.d.cts

@@ -0,0 +1,627 @@
+import { FlexibleSchema, ModelMessage, LanguageModel, 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 { z } from 'zod';
+import 'events';
+
+/**
+ * Custom LLM provider factory - receives a model name and returns a LanguageModel.
+ * Use this to plug in any Vercel AI SDK-compatible provider.
+ *
+ * @example
+ * import { createOpenAI } from '@ai-sdk/openai';
+ * const provider: LLMProviderFactory = createOpenAI({ apiKey: '...' }).chat;
+ *
+ * @example
+ * import { createAnthropic } from '@ai-sdk/anthropic';
+ * const provider: LLMProviderFactory = createAnthropic({ apiKey: '...' });
+ */
+type LLMProviderFactory = (model: string) => LanguageModel;
+/**
+ * System prompt customization.
+ * - `string` — replaces the built-in prompt entirely.
+ * - `() => string` — factory evaluated on every request (supports dynamic prompts).
+ * - `{ append: string }` — appends extra content after the built-in prompt.
+ */
+type SystemPromptOption = string | (() => string) | {
+    append: string;
+};
+/**
+ * Hooks that fire around every tool execution.
+ *
+ * @example
+ * const hooks: ToolHooks = {
+ *   onBeforeToolCall: (name, input) => {
+ *     if (name === 'bash') throw new Error('bash tool is disabled');
+ *     return input; // can return modified input
+ *   },
+ *   onAfterToolCall: (name, input, output) => {
+ *     auditLog(name, input, output);
+ *     return output; // can return modified output
+ *   },
+ * };
+ */
+interface ToolHooks {
+    /**
+     * Called before a tool executes.
+     * Return a (possibly modified) input object, or throw to abort the call.
+     */
+    onBeforeToolCall?: (name: string, input: any) => any | Promise<any>;
+    /**
+     * Called after a tool executes.
+     * Return a (possibly modified) output value.
+     */
+    onAfterToolCall?: (name: string, input: any, output: any) => any | Promise<any>;
+}
+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;
+    onToolResult?: (toolResult: any) => void;
+    onStepFinish?: (step: StepResult<any>) => void;
+    onClarificationRequest?: (request: ClarificationRequest) => Promise<string>;
+    onCompacted?: (newMessages: ModelMessage[]) => void;
+    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>;
+
+/**
+ * 用户配置插件接口 - 面向终端用户
+ * 使用声明式配置扩展引擎能力
+ */
+interface UserConfigPlugin {
+    version: string;
+    name?: string;
+    description?: string;
+    tools?: Record<string, ToolConfig>;
+    mcp?: {
+        servers: MCPServerConfig[];
+    };
+    prompts?: {
+        system?: string;
+        user?: string;
+        assistant?: string;
+    };
+    subAgents?: SubAgentConfig[];
+    skills?: {
+        directories?: string[];
+        autoScan?: boolean;
+        cache?: boolean;
+    };
+    env?: Record<string, string>;
+    conditions?: {
+        environment?: string;
+        features?: string[];
+    };
+}
+/**
+ * 工具配置接口
+ */
+declare const ToolConfigSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        skill: "skill";
+        bash: "bash";
+        http: "http";
+        javascript: "javascript";
+        custom: "custom";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodAny>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    method: z.ZodOptional<z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+        PATCH: "PATCH";
+    }>>;
+    url: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodAny>;
+    params: z.ZodOptional<z.ZodAny>;
+    data: z.ZodOptional<z.ZodAny>;
+    code: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    conditions: z.ZodOptional<z.ZodObject<{
+        environment: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ToolConfig = z.infer<typeof ToolConfigSchema>;
+/**
+ * MCP 服务器配置接口
+ */
+declare const MCPServerConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodAny>;
+    cwd: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+/**
+ * 子代理配置接口
+ */
+declare const SubAgentConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    trigger: z.ZodArray<z.ZodString>;
+    prompt: z.ZodString;
+    model: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type SubAgentConfig = z.infer<typeof SubAgentConfigSchema>;
+/**
+ * 用户配置插件加载选项
+ */
+interface UserConfigPluginLoadOptions {
+    configs?: UserConfigPlugin[];
+    dirs?: string[];
+    scan?: boolean;
+}
+
+interface StreamOptions {
+    abortSignal?: AbortSignal;
+    onStepFinish?: (event: StepResult<any>) => void;
+    onChunk?: (event: {
+        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>[];
+    finishReason: string;
+};
+
+type CompactResult = {
+    didCompact: boolean;
+    reason?: string;
+    newMessages?: ModelMessage[];
+};
+declare const maybeCompactContext: (context: Context, options?: {
+    force?: boolean;
+    provider?: LLMProviderFactory;
+    model?: string;
+}) => Promise<CompactResult>;
+
+interface ClarifyInput {
+    question: string;
+    context?: string;
+    defaultAnswer?: string;
+    timeout?: number;
+}
+interface ClarifyOutput {
+    answer: string;
+    timedOut: boolean;
+}
+declare const ClarifyTool: Tool<ClarifyInput, ClarifyOutput>;
+
+declare const ReadTool: Tool<{
+    filePath: string;
+    offset?: number;
+    limit?: number;
+}, {
+    content: string;
+    totalLines?: number;
+}>;
+
+declare const WriteTool: Tool<{
+    filePath: string;
+    content: string;
+}, {
+    success: boolean;
+    created: boolean;
+    bytes: number;
+}>;
+
+declare const EditTool: Tool<{
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}, {
+    success: boolean;
+    replacements: number;
+    preview?: string;
+}>;
+
+declare const GrepTool: Tool<{
+    pattern: string;
+    path?: string;
+    glob?: string;
+    type?: string;
+    outputMode?: 'content' | 'files_with_matches' | 'count';
+    context?: number;
+    caseInsensitive?: boolean;
+    headLimit?: number;
+    offset?: number;
+    multiline?: boolean;
+}, {
+    output: string;
+    matches?: number;
+}>;
+
+declare const LsTool: Tool<{
+    path?: string;
+}, {
+    files: string[];
+}>;
+
+declare const BashTool: Tool<{
+    command: string;
+    timeout?: number;
+    cwd?: string;
+    description?: string;
+}, {
+    output: string;
+    error?: string;
+    exitCode?: number;
+}>;
+
+declare const TavilyTool: Tool<{
+    query: string;
+    maxResults?: number;
+}, {
+    results: Array<{
+        title: string;
+        url: string;
+        content: string;
+        score?: number;
+    }>;
+}>;
+
+declare const BuiltinTools: readonly [Tool<{
+    filePath: string;
+    offset?: number;
+    limit?: number;
+}, {
+    content: string;
+    totalLines?: number;
+}>, Tool<{
+    filePath: string;
+    content: string;
+}, {
+    success: boolean;
+    created: boolean;
+    bytes: number;
+}>, Tool<{
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll?: boolean;
+}, {
+    success: boolean;
+    replacements: number;
+    preview?: string;
+}>, Tool<{
+    pattern: string;
+    path?: string;
+    glob?: string;
+    type?: string;
+    outputMode?: "content" | "files_with_matches" | "count";
+    context?: number;
+    caseInsensitive?: boolean;
+    headLimit?: number;
+    offset?: number;
+    multiline?: boolean;
+}, {
+    output: string;
+    matches?: number;
+}>, Tool<{
+    path?: string;
+}, {
+    files: string[];
+}>, Tool<{
+    command: string;
+    timeout?: number;
+    cwd?: string;
+    description?: string;
+}, {
+    output: string;
+    error?: string;
+    exitCode?: number;
+}>, Tool<{
+    query: string;
+    maxResults?: number;
+}, {
+    results: Array<{
+        title: string;
+        url: string;
+        content: string;
+        score?: number;
+    }>;
+}>, Tool<ClarifyInput, ClarifyOutput>];
+declare const BuiltinToolsMap: Record<string, any>;
+declare const getFinalToolsMap: (customTools?: Record<string, Tool$1>) => Record<string, any>;
+
+/**
+ * 引擎配置选项
+ */
+interface EngineOptions {
+    enginePlugins?: EnginePluginLoadOptions;
+    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;
+}
+/**
+ * 重构后的引擎类
+ * 自动包含内置插件，支持可选禁用
+ */
+declare class Engine {
+    private pluginManager;
+    private tools;
+    private options;
+    private config;
+    constructor(options?: EngineOptions);
+    /**
+     * 初始化引擎和插件系统
+     * 自动包含内置插件
+     */
+    initialize(): Promise<void>;
+    /**
+     * 准备引擎插件列表（包含内置插件）
+     */
+    private prepareEnginePlugins;
+    /**
+     * 运行AI循环
+     */
+    run(context: Context, options?: LoopOptions): Promise<string>;
+    /**
+     * 获取插件状态
+     */
+    getPluginStatus(): {
+        enginePlugins: string[];
+        userConfigPlugins: string[];
+        tools: string[];
+        services: string[];
+        protocols: string[];
+    };
+    /**
+     * 获取工具
+     */
+    getTools(): Record<string, any>;
+    /**
+     * 获取服务
+     */
+    getService<T>(name: string): T | undefined;
+    /**
+     * 获取配置
+     */
+    getConfig<T>(key: string): T | undefined;
+    /**
+     * 设置配置
+     */
+    setConfig<T>(key: string, value: T): void;
+}
+
+/**
+ * 插件管理器 - 管理双轨插件系统
+ */
+declare class PluginManager {
+    private enginePlugins;
+    private userConfigPlugins;
+    private tools;
+    private services;
+    private protocols;
+    private config;
+    private events;
+    private logger;
+    constructor(logger?: ILogger);
+    /**
+     * 初始化插件系统
+     */
+    initialize(options?: {
+        enginePlugins?: EnginePluginLoadOptions;
+        userConfigPlugins?: UserConfigPluginLoadOptions;
+    }): Promise<void>;
+    /**
+     * 加载引擎插件
+     */
+    private loadEnginePlugins;
+    /**
+     * 扫描引擎插件目录
+     */
+    private scanEnginePlugins;
+    /**
+     * 加载单个引擎插件文件
+     */
+    private loadEnginePluginFile;
+    /**
+     * 初始化单个引擎插件
+     */
+    private initializeEnginePlugin;
+    /**
+     * 加载用户配置插件
+     */
+    private loadUserConfigPlugins;
+    /**
+     * 扫描用户配置插件目录
+     */
+    private scanUserConfigPlugins;
+    /**
+     * 加载单个用户配置文件
+     */
+    private loadUserConfigFile;
+    /**
+     * 应用用户配置
+     */
+    private applyUserConfig;
+    /**
+     * 验证核心能力
+     */
+    private validateCoreCapabilities;
+    /**
+     * 插件依赖排序
+     */
+    private sortPluginsByDependencies;
+    /**
+     * 工具获取
+     */
+    getTools(): Record<string, any>;
+    /**
+     * 服务获取
+     */
+    getService<T>(name: string): T | undefined;
+    /**
+     * 协议获取
+     */
+    getProtocol(name: string): any;
+    /**
+     * 获取插件状态
+     */
+    getStatus(): {
+        enginePlugins: string[];
+        userConfigPlugins: string[];
+        tools: string[];
+        services: string[];
+        protocols: string[];
+    };
+    /**
+     * 解析路径（支持 ~ 和相对路径）
+     */
+    private resolvePath;
+}
+
+export { BashTool, BuiltinTools, BuiltinToolsMap, type ClarificationRequest, ClarifyTool, type Context, EditTool, Engine, type Extension, GrepTool, type IExtensionContext, type ILogger, type IPlugin, type LLMProviderFactory, LsTool, PluginManager, Engine as PulseAgent, ReadTool, type SystemPromptOption, TavilyTool, type Tool, type ToolExecutionContext, type ToolHooks, type UserConfigPlugin, type UserConfigPluginLoadOptions, WriteTool, getFinalToolsMap, loop, maybeCompactContext, streamTextAI };