@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/llm/hooks.test.js

@@ -0,0 +1,233 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { LLMHooks } from "./hooks.js";
+import { globalHookManager } from "../hook/global-hook-manager.js";
+describe("LLMHooks", () => {
+    let hooks;
+    beforeEach(() => {
+        hooks = new LLMHooks();
+        // 清理 globalHookManager 中的 hooks
+        globalHookManager.clear();
+    });
+    afterEach(() => {
+        // 清理 globalHookManager 中的 hooks
+        globalHookManager.clear();
+    });
+    describe("constructor", () => {
+        test("should create instance with empty hooks", () => {
+            expect(hooks.getHooks()).toEqual([]);
+        });
+    });
+    describe("register", () => {
+        test("should register before invoke hook", () => {
+            const hook = async (context) => {
+                // 可以在此处修改 context.request
+            };
+            hooks.register("before-invoke", hook);
+            expect(hooks.getHooks()).toHaveLength(1);
+            expect(hooks.getHooks()[0].type).toBe("before-invoke");
+        });
+        test("should register after invoke hook", () => {
+            const hook = async (context) => {
+                // 可以在此处处理结果
+            };
+            hooks.register("after-invoke", hook);
+            expect(hooks.getHooks()).toHaveLength(1);
+        });
+        test("should register stream hook", () => {
+            const hook = async (context, event) => {
+                // 可以在此处处理流事件
+            };
+            hooks.register("stream", hook);
+            expect(hooks.getHooks()).toHaveLength(1);
+        });
+        test("should register multiple hooks", () => {
+            hooks.register("before-invoke", async () => { });
+            hooks.register("after-invoke", async () => { });
+            hooks.register("stream", async () => { });
+            expect(hooks.getHooks()).toHaveLength(3);
+        });
+        test("should register named hooks", () => {
+            hooks.register("before-invoke", async () => { }, "custom-before-hook");
+            hooks.register("after-invoke", async () => { }, "custom-after-hook");
+            const allHooks = hooks.getHooks();
+            expect(allHooks[0].name).toBe("custom-before-hook");
+            expect(allHooks[1].name).toBe("custom-after-hook");
+        });
+    });
+    describe("unregister", () => {
+        test("should unregister hook by reference", () => {
+            const hook = async () => { };
+            hooks.register("before-invoke", hook);
+            hooks.register("before-invoke", async () => { });
+            expect(hooks.getHooks()).toHaveLength(2);
+            hooks.unregister(hook);
+            expect(hooks.getHooks()).toHaveLength(1);
+        });
+        test("should unregister hook by name", () => {
+            hooks.register("before-invoke", async () => { }, "hook1");
+            hooks.register("before-invoke", async () => { }, "hook2");
+            expect(hooks.getHooks()).toHaveLength(2);
+            hooks.unregisterByName("hook1");
+            expect(hooks.getHooks()).toHaveLength(1);
+            expect(hooks.getHooks()[0].name).toBe("hook2");
+        });
+        test("should unregister all hooks of a type", () => {
+            hooks.register("before-invoke", async () => { });
+            hooks.register("after-invoke", async () => { });
+            hooks.register("stream", async () => { });
+            hooks.unregisterByType("before-invoke");
+            expect(hooks.getHooks()).toHaveLength(2);
+        });
+    });
+    describe("clear", () => {
+        test("should clear all hooks", () => {
+            hooks.register("before-invoke", async () => { });
+            hooks.register("after-invoke", async () => { });
+            hooks.clear();
+            expect(hooks.getHooks()).toEqual([]);
+        });
+    });
+    describe("executeBeforeInvoke", () => {
+        test("should execute before-invoke hooks in order", async () => {
+            const executionOrder = [];
+            hooks.register("before-invoke", async () => {
+                executionOrder.push("hook1");
+            });
+            hooks.register("before-invoke", async () => {
+                executionOrder.push("hook2");
+            });
+            const context = {
+                request: { messages: [] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            // 使用新的直接调用 globalHookManager 的方式
+            await globalHookManager.execute("llm:before.invoke", context);
+            expect(executionOrder).toEqual(["hook1", "hook2"]);
+        });
+        test("should allow hooks to modify context", async () => {
+            hooks.register("before-invoke", async (ctx) => {
+                ctx.request.messages = [
+                    { role: "system", content: "You are helpful" },
+                    ...ctx.request.messages,
+                ];
+            });
+            const context = {
+                request: { messages: [{ role: "user", content: "Hello" }] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            await globalHookManager.execute("llm:before.invoke", context);
+            expect(context.request.messages).toHaveLength(2);
+            expect(context.request.messages[0].role).toBe("system");
+        });
+        test("should isolate errors and continue executing remaining hooks", async () => {
+            const executionOrder = [];
+            hooks.register("before-invoke", async () => {
+                executionOrder.push("hook1");
+            });
+            hooks.register("before-invoke", async () => {
+                throw new Error("Hook error");
+            });
+            hooks.register("before-invoke", async () => {
+                executionOrder.push("hook3");
+            });
+            const context = {
+                request: { messages: [] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            // HookManager 会捕获错误并继续执行（错误隔离）
+            await globalHookManager.execute("llm:before.invoke", context);
+            // 错误被隔离，后续 hooks 继续执行
+            expect(executionOrder).toEqual(["hook1", "hook3"]);
+        });
+    });
+    describe("executeAfterInvoke", () => {
+        test("should execute after-invoke hooks in order", async () => {
+            const executionOrder = [];
+            hooks.register("after-invoke", async (ctx) => {
+                executionOrder.push("hook1");
+            });
+            hooks.register("after-invoke", async (ctx) => {
+                executionOrder.push("hook2");
+            });
+            const context = {
+                request: { messages: [] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            const result = {
+                output: { content: "test", finishReason: "stop" },
+                providerId: "openai",
+                model: "gpt-4",
+                latencyMs: 100,
+            };
+            await globalHookManager.execute("llm:after.invoke", { ...context, result });
+            expect(executionOrder).toEqual(["hook1", "hook2"]);
+        });
+        test("should allow hooks to modify result", async () => {
+            hooks.register("after-invoke", async (ctx, result) => {
+                result.output.content = result.output.content + " [modified]";
+            });
+            const context = {
+                request: { messages: [] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            const result = {
+                output: { content: "original", finishReason: "stop" },
+                providerId: "openai",
+                model: "gpt-4",
+                latencyMs: 100,
+            };
+            await globalHookManager.execute("llm:after.invoke", { ...context, result });
+            expect(result.output.content).toBe("original [modified]");
+        });
+    });
+    describe("executeStream", () => {
+        test("should execute stream hooks", async () => {
+            const events = [];
+            hooks.register("stream", async (ctx, event) => {
+                events.push(event);
+            });
+            const context = {
+                request: { messages: [] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            const event = { type: "text", content: "Hello" };
+            await hooks.executeStream(context, event);
+            expect(events).toHaveLength(1);
+            expect(events[0]).toEqual(event);
+        });
+        test("should allow hooks to modify stream event", async () => {
+            hooks.register("stream", async (ctx, event) => {
+                if (event.type === "text") {
+                    event.content = event.content.toUpperCase();
+                }
+            });
+            const context = {
+                request: { messages: [] },
+                providerId: "openai",
+                model: "gpt-4",
+            };
+            const event = { type: "text", content: "hello" };
+            await hooks.executeStream(context, event);
+            expect(event.content).toBe("HELLO");
+        });
+    });
+    describe("getHooksByType", () => {
+        test("should return hooks of specific type", () => {
+            hooks.register("before-invoke", async () => { });
+            hooks.register("after-invoke", async () => { });
+            hooks.register("before-invoke", async () => { });
+            hooks.register("stream", async () => { });
+            const beforeHooks = hooks.getHooksByType("before-invoke");
+            expect(beforeHooks).toHaveLength(2);
+            const afterHooks = hooks.getHooksByType("after-invoke");
+            expect(afterHooks).toHaveLength(1);
+        });
+    });
+});
+//# sourceMappingURL=hooks.test.js.map

package/dist/core/src/env/llm/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * LLM Component
+ * 提供 LLM 调用能力
+ */
+export { type LLMMessage, type LLMOutput, type UsageInfo, type ToolCall, type ToolResult, type ToolInfo, type LLMConfig, type LLMProvider, type ProviderConfig, type ProviderType, type LLMInvokeRequest, type LLMInvokeResult, type StreamEvent, } from "./types";
+export { LLMConfigSchema, ProviderConfigSchema, ProviderCapabilitiesSchema, ModelLimitsSchema, LLMDefaultConfigSchema, } from "./types";
+export { ProviderManager } from "./provider";
+export { LLMTransform } from "./transform";
+export { invoke, invokeNonStream, parseModelString, createInvokeConfig, type InvokeConfig, type InvokeOptions, type LLMToolContext, type ConvertedUsageInfo, } from "./invoke";
+export { type LLMHookType, type LLMHookContext, type LLMBeforeInvokeHook, type LLMAfterInvokeHook, type LLMStreamHook, type LLMHookRegistration, LLMHooks, } from "./hooks";
+export { LLMComponent, type LLMComponentOptions } from "./llm";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/src/env/llm/index.js

@@ -0,0 +1,16 @@
+/**
+ * LLM Component
+ * 提供 LLM 调用能力
+ */
+export { LLMConfigSchema, ProviderConfigSchema, ProviderCapabilitiesSchema, ModelLimitsSchema, LLMDefaultConfigSchema, } from "./types.js";
+// Provider
+export { ProviderManager } from "./provider.js";
+// Transform
+export { LLMTransform } from "./transform.js";
+// Invoke (AI SDK integration)
+export { invoke, invokeNonStream, parseModelString, createInvokeConfig, } from "./invoke.js";
+// Hooks
+export { LLMHooks, } from "./hooks.js";
+// Component
+export { LLMComponent } from "./llm.js";
+//# sourceMappingURL=index.js.map

package/dist/core/src/env/llm/invoke-threshold-check.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Test for skipThresholdCheck feature
+ *
+ * TDD: 测试 LLMInvokeRequest 的 skipThresholdCheck 参数
+ *
+ * 验证:
+ * 1. LLMInvokeRequest 类型支持 skipThresholdCheck 参数
+ * 2. SummaryAgent 调用时传入 skipThresholdCheck: true
+ */
+export {};
+//# sourceMappingURL=invoke-threshold-check.test.d.ts.map

package/dist/core/src/env/llm/invoke-threshold-check.test.js

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Test for skipThresholdCheck feature
+ *
+ * TDD: 测试 LLMInvokeRequest 的 skipThresholdCheck 参数
+ *
+ * 验证:
+ * 1. LLMInvokeRequest 类型支持 skipThresholdCheck 参数
+ * 2. SummaryAgent 调用时传入 skipThresholdCheck: true
+ */
+import { describe, test, expect, vi } from "bun:test";
+import { SummaryAgent } from "../agent/summary-agent.js";
+describe("skipThresholdCheck feature", () => {
+    describe("LLMInvokeRequest type", () => {
+        test("should support skipThresholdCheck parameter", () => {
+            // This test verifies the type exists - if TypeScript compiles, this passes
+            // We import the actual types to verify they compile correctly
+            const mockRequest = {
+                messages: [{ role: "user", content: "test" }],
+                skipThresholdCheck: true
+            };
+            // Type check - if this compiles, the type is correct
+            expect(mockRequest.skipThresholdCheck).toBe(true);
+        });
+        test("should allow skipThresholdCheck to be undefined (optional)", () => {
+            const mockRequest = {
+                messages: [{ role: "user", content: "test" }]
+                // skipThresholdCheck not specified
+            };
+            // Should compile without skipThresholdCheck
+            expect(mockRequest.messages).toHaveLength(1);
+        });
+    });
+    describe("SummaryAgent", () => {
+        test("should pass skipThresholdCheck to LLM invoke", async () => {
+            // Create mock LLMComponent that tracks the invoke call
+            const mockInvoke = vi.fn().mockResolvedValue({
+                output: {
+                    content: JSON.stringify({
+                        title: "Test",
+                        processKeyPoints: ["Point 1"],
+                        currentState: "State",
+                        nextSteps: ["Step 1"],
+                        userIntents: ["Intent 1"]
+                    }),
+                    finishReason: "stop"
+                },
+                providerId: "openai",
+                model: "gpt-4o",
+                latencyMs: 100
+            });
+            const mockLLMComponent = {
+                invoke: mockInvoke
+            };
+            // Create mock PromptComponent
+            const mockPromptComponent = {
+                render: vi.fn().mockResolvedValue("mocked prompt")
+            };
+            // Create SummaryAgent
+            const summaryAgent = new SummaryAgent(mockPromptComponent, mockLLMComponent);
+            // Run summary agent with array messages
+            await summaryAgent.run({
+                messages: [
+                    { role: "user", content: "test message 1" },
+                    { role: "assistant", content: "response 1" }
+                ],
+                userContext: "test context",
+                outputFormat: "json"
+            });
+            // Verify invoke was called with skipThresholdCheck: true
+            expect(mockInvoke).toHaveBeenCalled();
+            const invokeCall = mockInvoke.mock.calls[0][0];
+            expect(invokeCall.skipThresholdCheck).toBe(true);
+        });
+    });
+});
+//# sourceMappingURL=invoke-threshold-check.test.js.map

package/dist/core/src/env/llm/invoke-timeout.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=invoke-timeout.test.d.ts.map

package/dist/core/src/env/llm/invoke-timeout.test.js

@@ -0,0 +1,31 @@
+import { describe, test, expect } from "bun:test";
+import { withTimeout, TimeoutError } from "./invoke.js";
+describe("LLM 超时控制", () => {
+    describe("withTimeout", () => {
+        test("应该正常完成不超时的操作", async () => {
+            const result = await withTimeout(Promise.resolve("success"), 1000);
+            expect(result).toBe("success");
+        });
+        test("应该在超时时抛出 TimeoutError", async () => {
+            await expect(withTimeout(new Promise((resolve) => setTimeout(() => resolve("done"), 500)), 100 // 100ms 超时，但操作需要 500ms
+            )).rejects.toThrow("LLM invocation timeout after 100ms");
+        });
+        test("应该支持自定义错误消息", async () => {
+            await expect(withTimeout(new Promise((resolve) => setTimeout(() => resolve("done"), 500)), 100, "Custom timeout message")).rejects.toThrow("Custom timeout message");
+        });
+        test("应该支持取消超时", async () => {
+            const result = await withTimeout(new Promise((resolve) => setTimeout(() => resolve("done"), 50)), 1000 // 1000ms 超时，操作只需要 50ms
+            );
+            expect(result).toBe("done");
+        });
+    });
+    describe("TimeoutError", () => {
+        test("应该有正确的名称和消息", () => {
+            const error = new TimeoutError("test message", 100);
+            expect(error.name).toBe("TimeoutError");
+            expect(error.message).toBe("test message");
+            expect(error.timeout).toBe(100);
+        });
+    });
+});
+//# sourceMappingURL=invoke-timeout.test.js.map

package/dist/core/src/env/llm/invoke.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview LLM invocation with AI SDK integration.
+ *
+ * This module provides LLM invocation using AI SDK for better provider support.
+ * Stream events are published via Environment.pushEnvEvent().
+ */
+import type { ToolInfo, ToolResult, LLMOutput, LLMMessage } from "./types";
+import type { Environment } from "../interface";
+/**
+ * Invoke LLM 配置
+ */
+export interface InvokeConfig {
+    /** 模型标识符（格式: providerId/modelId） */
+    model: string;
+    /** Base URL */
+    baseURL?: string;
+    /** API Key */
+    apiKey: string;
+    /** 额外选项 */
+    options?: {
+        thinkingInText?: {
+            enabled?: boolean;
+            tags?: string[];
+        };
+    };
+}
+/**
+ * LLM 选项
+ */
+export interface InvokeOptions {
+    /** 消息列表 */
+    messages: LLMMessage[];
+    /** 工具列表 */
+    tools?: ToolInfo[];
+    /** 模型标识符（可选） */
+    model?: string;
+    /** 温度参数 */
+    temperature?: number;
+    /** 最大 Token 数 */
+    maxTokens?: number;
+    /** Environment 实例（用于发布流式事件，可选） */
+    env?: Environment;
+    /** 上下文信息（用于事件元数据） */
+    context?: {
+        /** Session ID */
+        sessionId?: string;
+        /** Message ID */
+        messageId?: string;
+    };
+}
+/**
+ * LLM Tool Context - Context for tool calls during LLM invocation
+ */
+export interface LLMToolContext {
+    /** Abort Signal */
+    abort?: AbortSignal | undefined;
+    /** 额外上下文 */
+    context?: Record<string, unknown>;
+}
+/**
+ * Usage 信息转换
+ */
+export interface ConvertedUsageInfo {
+    /** Prompt Token 数 */
+    promptTokens: number;
+    /** Completion Token 数 */
+    completionTokens: number;
+    /** 总 Token 数 */
+    totalTokens: number;
+}
+/**
+ * 超时错误
+ */
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(message: string, timeout: number);
+}
+/**
+ * 带超时的 Promise 包装器
+ *
+ * @param promise 要执行的 Promise
+ * @param timeoutMs 超时时间（毫秒）
+ * @param message 自定义错误消息
+ * @returns Promise 结果
+ * @throws TimeoutError 当超时时
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs?: number, message?: string): Promise<T>;
+/**
+ * 解析模型字符串
+ * 格式: "providerId/modelId"
+ */
+export declare function parseModelString(model?: string): {
+    providerId: string;
+    modelId: string;
+};
+/**
+ * 核心 LLM 调用函数
+ * 使用 AI SDK 的 streamText
+ *
+ * 流式事件通过 env.pushEnvEvent() 发布
+ *
+ * @param config - Invoke 配置
+ * @param options - LLM 选项
+ * @param ctx - Tool Context
+ * @returns ToolResult
+ */
+export declare function invoke(config: InvokeConfig, options: InvokeOptions, ctx: LLMToolContext): Promise<ToolResult>;
+/**
+ * 非流式 LLM 调用
+ *
+ * 使用 AI SDK 的 generateText API，返回完整响应
+ */
+export declare function invokeNonStream(config: InvokeConfig, options: InvokeOptions, ctx: LLMToolContext): Promise<LLMOutput>;
+/**
+ * 创建 LLM 配置
+ */
+export declare function createInvokeConfig(model: string, apiKey: string, baseURL?: string): InvokeConfig;
+//# sourceMappingURL=invoke.d.ts.map