@keo-ai/axiom 0.1.2 → 0.1.4

package/dist/function_call_loop/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Function Call Loop — Function Call 引擎。
+ *
+ * 核心能力：
+ * - 每次 tool 执行向上层回传执行前、执行后两个事件
+ * - 维护跨轮次的执行历史（Harness），tool 之间能互相看见
+ * - 每次调 LLM 之前动态决定暴露哪些 tool
+ * - 支持自定义上下文压缩
+ * - 每轮全局策略判断，决定继续执行还是终止降级
+ * - 单轮支持多个 tool 并行执行（Plan and Execute）
+ * - 系统 Prompt 完全由外部注入
+ */
+export { runLoopWithModel } from './loop';
+export type { Message, ToolCall, ToolDefinition, HarnessRecord, HarnessRecordStatus, ToolExecutionStartEvent, ToolExecutionEndEvent, LoopEvent, ToolDiscoverResult, ToolExecuteContext, Tool, ApprovalConfig, TurnPolicyResult, TurnPolicy, CompressionConfig, LLMCaller, LLMCallOptions, LoopConfig, LoopResult, PendingApprovalInfo, } from './types';

package/dist/function_call_loop/index.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Function Call Loop — Function Call 引擎。
+ *
+ * 核心能力：
+ * - 每次 tool 执行向上层回传执行前、执行后两个事件
+ * - 维护跨轮次的执行历史（Harness），tool 之间能互相看见
+ * - 每次调 LLM 之前动态决定暴露哪些 tool
+ * - 支持自定义上下文压缩
+ * - 每轮全局策略判断，决定继续执行还是终止降级
+ * - 单轮支持多个 tool 并行执行（Plan and Execute）
+ * - 系统 Prompt 完全由外部注入
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLoopWithModel = void 0;
+var loop_1 = require("./loop");
+Object.defineProperty(exports, "runLoopWithModel", { enumerable: true, get: function () { return loop_1.runLoopWithModel; } });

package/dist/function_call_loop/loop.d.ts

@@ -0,0 +1,23 @@
+import type { LoopConfig, LoopResult } from './types';
+export declare function runLoop(config: LoopConfig): Promise<LoopResult>;
+/**
+ * 便捷入口：直接指定模型运行 Function Call Loop。
+ * 内部自动创建 LLM Caller，无需手动实现 llmCaller.call。
+ *
+ * 环境变量配置：
+ * - `BAILIAN_API_KEY` — 必填
+ * - `BAILIAN_BASE_URL` — 可选，默认百炼兼容地址
+ * - `BAILIAN_DEFAULT_MODEL` — 可选，默认 `qwen-max`
+ *
+ * @example
+ * ```ts
+ * const result = await runLoopWithModel({
+ *   messages: [
+ *     { role: 'system', content: 'You are helpful' },
+ *     { role: 'user', content: 'What is the weather?' },
+ *   ],
+ *   tools: [...],
+ * });
+ * ```
+ */
+export declare function runLoopWithModel(config: Omit<LoopConfig, 'llmCaller'>): Promise<LoopResult>;

package/dist/function_call_loop/loop.js

@@ -0,0 +1,472 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runLoop = runLoop;
+exports.runLoopWithModel = runLoopWithModel;
+const harness_1 = require("./harness");
+const provider_1 = require("./provider");
+/**
+ * 运行 Function Call Loop。
+ * 按设计文档的完整流程执行，支持生命周期事件、Harness、Tool 发现、
+ * 上下文压缩、Turn Policy 和并行执行。
+ *
+ * @param config - Loop 配置
+ * @returns Loop 执行结果
+ */
+function buildInitialMessages(config) {
+    return [...config.messages];
+}
+function runLoop(config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const harness = new harness_1.Harness();
+        const messages = buildInitialMessages(config);
+        let turn = 0;
+        const signal = config.signal;
+        while (true) {
+            // 检查取消信号
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                break;
+            }
+            // 第一步：轮次加一
+            turn++;
+            // 第二步：全局轮次策略
+            const decision = yield runTurnPolicy(config, harness, turn);
+            if (decision.message) {
+                messages.push({ role: 'assistant', content: decision.message });
+                break;
+            }
+            if (decision.injectMessage) {
+                messages.push({ role: 'system', content: decision.injectMessage });
+            }
+            // 硬兜底检查
+            if (config.maxTurns !== undefined && turn >= config.maxTurns) {
+                messages.push({
+                    role: 'assistant',
+                    content: (_a = config.terminateMessage) !== null && _a !== void 0 ? _a : 'Max turns reached.',
+                });
+                break;
+            }
+            // 第三步：Tool 发现
+            const discoverResult = yield discoverTools(config, harness);
+            const visibleTools = discoverResult.filter((t) => t.visible);
+            const toolDefinitions = visibleTools.map((t) => ({
+                type: 'function',
+                function: {
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                },
+            }));
+            const visibleToolNames = new Set(visibleTools.map((t) => t.name));
+            // 第四步：上下文压缩
+            const messagesForLLM = yield compressMessages(config, messages, turn);
+            // 第五步：调用 LLM
+            const llmResponse = yield config.llmCaller.call(messagesForLLM, toolDefinitions, {
+                model: config.model,
+                temperature: config.temperature,
+                maxTokens: config.maxTokens,
+                topP: config.topP,
+                reasoningEffort: config.reasoningEffort,
+            });
+            // 第六步：检查 LLM 回复
+            if (!llmResponse.tool_calls || llmResponse.tool_calls.length === 0) {
+                messages.push({
+                    role: 'assistant',
+                    content: (_b = llmResponse.content) !== null && _b !== void 0 ? _b : '',
+                });
+                return {
+                    messages,
+                    harness: harness.getAll(),
+                    finalContent: llmResponse.content,
+                    turns: turn,
+                };
+            }
+            // 有 tool_calls，将 assistant message 加入 Messages
+            messages.push({
+                role: 'assistant',
+                content: (_c = llmResponse.content) !== null && _c !== void 0 ? _c : '',
+                tool_calls: llmResponse.tool_calls,
+            });
+            // 第七步：并行执行 tool
+            const harnessSnapshot = harness.snapshot();
+            const parallelResults = yield executeToolsInParallel(config, harness, llmResponse.tool_calls, visibleToolNames, harnessSnapshot, turn);
+            // 将 tool result messages 加入 Messages
+            for (const result of parallelResults) {
+                messages.push({
+                    role: 'tool',
+                    content: result.content,
+                    tool_call_id: result.toolCallId,
+                });
+            }
+            // 检查是否有待审批的 tool
+            const pending = parallelResults.find((r) => r.pendingApproval);
+            if (pending === null || pending === void 0 ? void 0 : pending.pendingApproval) {
+                return {
+                    messages,
+                    harness: harness.getAll(),
+                    finalContent: null,
+                    turns: turn,
+                    pendingApproval: {
+                        ticketId: pending.pendingApproval.ticketId,
+                        toolName: pending.pendingApproval.toolName,
+                        args: pending.pendingApproval.args,
+                        callId: pending.toolCallId,
+                    },
+                };
+            }
+            // 第八步：回到第一步继续下一轮
+        }
+        // Loop 被终止（Turn Policy 或硬限制）
+        const lastMessage = messages[messages.length - 1];
+        return {
+            messages,
+            harness: harness.getAll(),
+            finalContent: (lastMessage === null || lastMessage === void 0 ? void 0 : lastMessage.role) === 'assistant' ? lastMessage.content : null,
+            turns: turn,
+        };
+    });
+}
+/**
+ * 执行 Turn Policy。
+ */
+function runTurnPolicy(config, harness, turn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (config.turnPolicy) {
+            try {
+                return yield config.turnPolicy(harness.getAll(), turn, config.metadata);
+            }
+            catch (_c) {
+                return {};
+            }
+        }
+        // 默认策略
+        const maxTurns = (_a = config.maxTurns) !== null && _a !== void 0 ? _a : Infinity;
+        if (turn < maxTurns - 1) {
+            return {};
+        }
+        if (turn === maxTurns - 1) {
+            return {
+                injectMessage: config.warningMessage,
+            };
+        }
+        return {
+            message: (_b = config.terminateMessage) !== null && _b !== void 0 ? _b : 'Max turns reached.',
+        };
+    });
+}
+/**
+ * Tool 发现。
+ */
+function discoverTools(config, harness) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const results = [];
+        for (const tool of config.tools) {
+            if (tool.discover) {
+                try {
+                    const result = yield tool.discover(harness.getAll(), config.metadata);
+                    results.push(result);
+                }
+                catch (_a) {
+                    // discover 抛异常 → 视为不可见
+                    results.push({
+                        name: tool.name,
+                        description: tool.description,
+                        parameters: tool.parameters,
+                        visible: false,
+                    });
+                }
+            }
+            else {
+                // 没有 discover 函数 → 使用静态配置，可见
+                results.push({
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: tool.parameters,
+                    visible: true,
+                });
+            }
+        }
+        return results;
+    });
+}
+/**
+ * 将 Messages 按轮次分组（不含初始 system/user 消息）。
+ * 一轮 = 一个 assistant message + 其后的所有 tool messages。
+ */
+function groupMessagesByRound(messages) {
+    const rounds = [];
+    let i = 0;
+    // 跳过初始消息（system 和 user）
+    while (i < messages.length && messages[i].role !== 'assistant') {
+        i++;
+    }
+    // 从第一个 assistant 开始分组
+    while (i < messages.length) {
+        const round = [messages[i]];
+        i++;
+        while (i < messages.length && messages[i].role !== 'assistant') {
+            round.push(messages[i]);
+            i++;
+        }
+        rounds.push(round);
+    }
+    return rounds;
+}
+/**
+ * 上下文压缩。
+ */
+function compressMessages(config, messages, _turn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!config.compression) {
+            return messages;
+        }
+        const firstAssistantIndex = messages.findIndex((m) => m.role === 'assistant');
+        if (firstAssistantIndex === -1) {
+            return messages;
+        }
+        const initialMessages = messages.slice(0, firstAssistantIndex);
+        const restMessages = messages.slice(firstAssistantIndex);
+        const rounds = groupMessagesByRound(restMessages);
+        if (rounds.length <= config.compression.keepRounds) {
+            return messages;
+        }
+        const keepCount = config.compression.keepRounds;
+        const oldRounds = rounds.slice(0, rounds.length - keepCount);
+        const recentRounds = rounds.slice(rounds.length - keepCount);
+        try {
+            const compressed = yield config.compression.compress(oldRounds);
+            return [...initialMessages, ...compressed, ...recentRounds.flat()];
+        }
+        catch (_a) {
+            // compress 抛异常 → 视为不压缩
+            return messages;
+        }
+    });
+}
+/**
+ * 并行执行 tool。
+ */
+function executeToolsInParallel(config, harness, toolCalls, visibleToolNames, harnessSnapshot, turn) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const toolMap = new Map(config.tools.map((t) => [t.name, t]));
+        const signal = config.signal;
+        const promises = toolCalls.map((toolCall) => __awaiter(this, void 0, void 0, function* () {
+            const toolName = toolCall.function.name;
+            const callId = toolCall.id;
+            const rawArgs = toolCall.function.arguments;
+            let args;
+            try {
+                args = JSON.parse(rawArgs);
+            }
+            catch (_a) {
+                args = rawArgs;
+            }
+            const globalIndex = harness.length;
+            const pendingRecord = (0, harness_1.createPendingRecord)({
+                id: callId,
+                turn,
+                globalIndex,
+                toolName,
+                args,
+                rawArgs,
+            });
+            // 执行前事件
+            const startEvent = {
+                type: 'execution:start',
+                callId,
+                toolName,
+                args,
+                turn,
+            };
+            if (config.onEvent) {
+                try {
+                    yield config.onEvent(startEvent);
+                }
+                catch (_b) {
+                    // 事件回调异常不应阻塞主流程
+                }
+            }
+            let status = 'pending';
+            let result;
+            let error;
+            // 检查 tool 是否可见
+            if (!visibleToolNames.has(toolName)) {
+                status = 'error';
+                error = `Tool "${toolName}" is not visible in this turn`;
+            }
+            else {
+                const tool = toolMap.get(toolName);
+                if (!tool) {
+                    status = 'error';
+                    error = `Tool "${toolName}" not found`;
+                }
+                else {
+                    const context = {
+                        harness: harnessSnapshot,
+                        turn,
+                        metadata: config.metadata,
+                    };
+                    try {
+                        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                            status = 'cancelled';
+                        }
+                        else if (tool.approval) {
+                            const ticket = yield tool.approval.createTicket(args, context);
+                            if (ticket.approved) {
+                                // 已审批，直接执行
+                                result = yield tool.execute(args, context);
+                                status = 'success';
+                            }
+                            else {
+                                // 未审批，暂停 Loop
+                                result = { __type: 'PENDING_APPROVAL', ticketId: ticket.ticketId };
+                                status = 'success';
+                            }
+                        }
+                        else {
+                            result = yield tool.execute(args, context);
+                            status = 'success';
+                        }
+                    }
+                    catch (e) {
+                        status = 'error';
+                        error = e instanceof Error ? e.message : String(e);
+                    }
+                }
+            }
+            const finalRecord = (0, harness_1.finalizeRecord)(pendingRecord, status, result, error);
+            // 执行后事件
+            const endEvent = {
+                type: 'execution:end',
+                callId,
+                toolName,
+                status: finalRecord.status,
+                durationMs: finalRecord.durationMs,
+                result: finalRecord.result,
+                error: finalRecord.error,
+                turn,
+            };
+            const content = status === 'success'
+                ? typeof result === 'object' && result !== null
+                    ? JSON.stringify(result)
+                    : String(result !== null && result !== void 0 ? result : '')
+                : error !== null && error !== void 0 ? error : 'Execution failed';
+            return {
+                toolCallId: callId,
+                content,
+                record: finalRecord,
+                events: [endEvent],
+                pendingApproval: typeof result === 'object' &&
+                    result !== null &&
+                    '__type' in result &&
+                    result.__type === 'PENDING_APPROVAL'
+                    ? {
+                        ticketId: result.ticketId,
+                        toolName,
+                        args,
+                    }
+                    : undefined,
+            };
+        }));
+        const settled = yield Promise.allSettled(promises);
+        // 收集结果，按完成顺序追加到 Harness
+        const results = [];
+        for (const item of settled) {
+            if (item.status === 'fulfilled') {
+                results.push(item.value);
+            }
+            else {
+                // Promise 自身抛异常（极罕见，通常已被内部 try-catch 处理）
+                const failedCall = toolCalls[settled.indexOf(item)];
+                const fallbackRecord = (0, harness_1.createPendingRecord)({
+                    id: (_a = failedCall === null || failedCall === void 0 ? void 0 : failedCall.id) !== null && _a !== void 0 ? _a : `unknown-${Date.now()}`,
+                    turn,
+                    globalIndex: harness.length,
+                    toolName: (_b = failedCall === null || failedCall === void 0 ? void 0 : failedCall.function.name) !== null && _b !== void 0 ? _b : 'unknown',
+                    args: failedCall === null || failedCall === void 0 ? void 0 : failedCall.function.arguments,
+                    rawArgs: (_c = failedCall === null || failedCall === void 0 ? void 0 : failedCall.function.arguments) !== null && _c !== void 0 ? _c : '',
+                });
+                const finalRecord = (0, harness_1.finalizeRecord)(fallbackRecord, 'error', undefined, item.reason instanceof Error ? item.reason.message : String(item.reason));
+                results.push({
+                    toolCallId: (_d = failedCall === null || failedCall === void 0 ? void 0 : failedCall.id) !== null && _d !== void 0 ? _d : '',
+                    content: (_e = finalRecord.error) !== null && _e !== void 0 ? _e : 'Execution failed',
+                    record: finalRecord,
+                    events: [
+                        {
+                            type: 'execution:end',
+                            callId: (_f = failedCall === null || failedCall === void 0 ? void 0 : failedCall.id) !== null && _f !== void 0 ? _f : '',
+                            toolName: (_g = failedCall === null || failedCall === void 0 ? void 0 : failedCall.function.name) !== null && _g !== void 0 ? _g : 'unknown',
+                            status: 'error',
+                            durationMs: finalRecord.durationMs,
+                            error: finalRecord.error,
+                            turn,
+                        },
+                    ],
+                });
+            }
+        }
+        // 按完成顺序追加 HarnessRecord，并发出事件
+        for (const result of results) {
+            harness.append(result.record);
+            for (const event of result.events) {
+                if (config.onEvent) {
+                    try {
+                        yield config.onEvent(event);
+                    }
+                    catch (_h) {
+                        // 事件回调异常不应阻塞主流程
+                    }
+                }
+            }
+        }
+        return results;
+    });
+}
+const DEFAULT_BAILIAN_BASE_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1';
+const DEFAULT_BAILIAN_MODEL = 'qwen-max';
+/**
+ * 便捷入口：直接指定模型运行 Function Call Loop。
+ * 内部自动创建 LLM Caller，无需手动实现 llmCaller.call。
+ *
+ * 环境变量配置：
+ * - `BAILIAN_API_KEY` — 必填
+ * - `BAILIAN_BASE_URL` — 可选，默认百炼兼容地址
+ * - `BAILIAN_DEFAULT_MODEL` — 可选，默认 `qwen-max`
+ *
+ * @example
+ * ```ts
+ * const result = await runLoopWithModel({
+ *   messages: [
+ *     { role: 'system', content: 'You are helpful' },
+ *     { role: 'user', content: 'What is the weather?' },
+ *   ],
+ *   tools: [...],
+ * });
+ * ```
+ */
+function runLoopWithModel(config) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const apiKey = process.env.BAILIAN_API_KEY;
+        if (!apiKey) {
+            throw new Error('BAILIAN_API_KEY environment variable is not set.');
+        }
+        const llmCaller = (0, provider_1.createLLMCaller)({
+            apiKey,
+            baseUrl: (_a = process.env.BAILIAN_BASE_URL) !== null && _a !== void 0 ? _a : DEFAULT_BAILIAN_BASE_URL,
+            defaultModel: (_b = process.env.BAILIAN_DEFAULT_MODEL) !== null && _b !== void 0 ? _b : DEFAULT_BAILIAN_MODEL,
+        });
+        return runLoop(Object.assign(Object.assign({}, config), { llmCaller }));
+    });
+}

package/dist/function_call_loop/provider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Function Call Loop 独立的 LLM Provider 实现。
+ * 兼容 OpenAI 协议，不依赖 predict 模块。
+ */
+import type { Message, ToolCall, ToolDefinition, LLMCallOptions } from './types';
+export interface ProviderOptions {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly defaultModel: string;
+}
+/**
+ * 基于 OpenAI 协议的 LLM 调用器。
+ */
+export declare function createLLMCaller(options: ProviderOptions): {
+    call(messages: ReadonlyArray<Message>, tools: ReadonlyArray<ToolDefinition>, callOptions?: LLMCallOptions): Promise<{
+        readonly content: string | null;
+        readonly tool_calls?: ReadonlyArray<ToolCall>;
+    }>;
+};

package/dist/function_call_loop/provider.js

@@ -0,0 +1,91 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLLMCaller = createLLMCaller;
+/**
+ * 基于 OpenAI 协议的 LLM 调用器。
+ */
+function createLLMCaller(options) {
+    return {
+        call(messages, tools, callOptions) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c;
+                const url = `${options.baseUrl}/chat/completions`;
+                const body = {
+                    model: (_a = callOptions === null || callOptions === void 0 ? void 0 : callOptions.model) !== null && _a !== void 0 ? _a : options.defaultModel,
+                    messages: messages.map((m) => {
+                        var _a;
+                        return ({
+                            role: m.role,
+                            content: m.content,
+                            tool_calls: (_a = m.tool_calls) === null || _a === void 0 ? void 0 : _a.map((tc) => ({
+                                id: tc.id,
+                                type: tc.type,
+                                function: {
+                                    name: tc.function.name,
+                                    arguments: tc.function.arguments,
+                                },
+                            })),
+                            tool_call_id: m.tool_call_id,
+                        });
+                    }),
+                    temperature: callOptions === null || callOptions === void 0 ? void 0 : callOptions.temperature,
+                    max_tokens: callOptions === null || callOptions === void 0 ? void 0 : callOptions.maxTokens,
+                    top_p: callOptions === null || callOptions === void 0 ? void 0 : callOptions.topP,
+                    tools: tools.length > 0
+                        ? tools.map((t) => ({
+                            type: t.type,
+                            function: {
+                                name: t.function.name,
+                                description: t.function.description,
+                                parameters: t.function.parameters,
+                            },
+                        }))
+                        : undefined,
+                };
+                let response;
+                try {
+                    response = yield fetch(url, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            Authorization: `Bearer ${options.apiKey}`,
+                        },
+                        body: JSON.stringify(body),
+                    });
+                }
+                catch (cause) {
+                    throw new Error(`[llm] ${cause instanceof Error ? cause.message : String(cause)}`);
+                }
+                if (!response.ok) {
+                    const text = yield response.text();
+                    throw new Error(`[llm] HTTP ${response.status}: ${text}`);
+                }
+                const data = (yield response.json());
+                const choice = (_b = data.choices) === null || _b === void 0 ? void 0 : _b[0];
+                if (!choice) {
+                    throw new Error('[llm] No choice in response');
+                }
+                return {
+                    content: choice.message.content,
+                    tool_calls: (_c = choice.message.tool_calls) === null || _c === void 0 ? void 0 : _c.map((tc) => ({
+                        id: tc.id,
+                        type: tc.type,
+                        function: {
+                            name: tc.function.name,
+                            arguments: tc.function.arguments,
+                        },
+                    })),
+                };
+            });
+        },
+    };
+}