@fllf/agent-sdk 0.1.2 → 0.1.3

package/dist/testing/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolSchemaSnapshot = exports.assertToolSchemaSnapshot = exports.assertMessageHistoryStoreContract = exports.createTestAgent = exports.FakeTool = exports.ScriptedChatModel = exports.FakeChatModel = void 0;
+var models_1 = require("./models");
+Object.defineProperty(exports, "FakeChatModel", { enumerable: true, get: function () { return models_1.FakeChatModel; } });
+Object.defineProperty(exports, "ScriptedChatModel", { enumerable: true, get: function () { return models_1.ScriptedChatModel; } });
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "FakeTool", { enumerable: true, get: function () { return tools_1.FakeTool; } });
+var agent_1 = require("./agent");
+Object.defineProperty(exports, "createTestAgent", { enumerable: true, get: function () { return agent_1.createTestAgent; } });
+var history_contract_1 = require("./history-contract");
+Object.defineProperty(exports, "assertMessageHistoryStoreContract", { enumerable: true, get: function () { return history_contract_1.assertMessageHistoryStoreContract; } });
+var tool_schema_1 = require("./tool-schema");
+Object.defineProperty(exports, "assertToolSchemaSnapshot", { enumerable: true, get: function () { return tool_schema_1.assertToolSchemaSnapshot; } });
+Object.defineProperty(exports, "createToolSchemaSnapshot", { enumerable: true, get: function () { return tool_schema_1.createToolSchemaSnapshot; } });
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;;AAAA,mCAGkB;AAFd,uGAAA,aAAa,OAAA;AACb,2GAAA,iBAAiB,OAAA;AAOrB,iCAEiB;AADb,iGAAA,QAAQ,OAAA;AAMZ,iCAEiB;AADb,wGAAA,eAAe,OAAA;AAKnB,uDAE4B;AADxB,qIAAA,iCAAiC,OAAA;AAMrC,6CAGuB;AAFnB,uHAAA,wBAAwB,OAAA;AACxB,uHAAA,wBAAwB,OAAA"}

package/dist/testing/models.d.ts

@@ -0,0 +1,34 @@
+import type { ChatModel, ChatRequest, ChatResponse, ModelCapabilities, ModelProviderName } from '../llm';
+export type ScriptedChatResponse = ChatResponse | ((request: ChatRequest) => ChatResponse | Promise<ChatResponse>);
+export interface ScriptedChatModelOptions {
+    name?: ModelProviderName;
+    model?: string;
+    capabilities?: Partial<ModelCapabilities>;
+    responses?: ScriptedChatResponse[];
+}
+export declare class ScriptedChatModel implements ChatModel {
+    readonly name: ModelProviderName;
+    readonly model: string;
+    readonly requests: ChatRequest[];
+    private readonly scriptedResponses;
+    private readonly modelCapabilities;
+    constructor(options?: ScriptedChatModelOptions);
+    capabilities(): ModelCapabilities;
+    queueResponse(response: ScriptedChatResponse): void;
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}
+export interface FakeChatModelOptions {
+    name?: ModelProviderName;
+    model?: string;
+    prefix?: string;
+}
+export declare class FakeChatModel implements ChatModel {
+    readonly name: ModelProviderName;
+    readonly model: string;
+    readonly requests: ChatRequest[];
+    private readonly prefix;
+    constructor(options?: FakeChatModelOptions);
+    capabilities(): ModelCapabilities;
+    chat(request: ChatRequest): Promise<ChatResponse>;
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/testing/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../src/testing/models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,SAAS,EACT,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACpB,MAAM,QAAQ,CAAC;AAIhB,MAAM,MAAM,oBAAoB,GAC1B,YAAY,GACZ,CAAC,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;AAEvE,MAAM,WAAW,wBAAwB;IACrC,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C,SAAS,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED,qBAAa,iBAAkB,YAAW,SAAS;IAC/C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAM;IACtC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;IAC3D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoB;gBAE1C,OAAO,GAAE,wBAA6B;IAalD,YAAY,IAAI,iBAAiB;IAIjC,aAAa,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAI7C,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAY1D;AAED,MAAM,WAAW,oBAAoB;IACjC,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,aAAc,YAAW,SAAS;IAC3C,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAM;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,oBAAyB;IAM9C,YAAY,IAAI,iBAAiB;IAS3B,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAY1D"}

package/dist/testing/models.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeChatModel = exports.ScriptedChatModel = void 0;
+const llm_1 = require("../llm");
+const messages_1 = require("../messages");
+class ScriptedChatModel {
+    name;
+    model;
+    requests = [];
+    scriptedResponses;
+    modelCapabilities;
+    constructor(options = {}) {
+        this.name = options.name ?? 'scripted';
+        this.model = options.model ?? 'scripted-model';
+        this.scriptedResponses = [...(options.responses ?? [])];
+        this.modelCapabilities = {
+            streaming: false,
+            toolCalling: true,
+            structuredOutput: false,
+            vision: false,
+            ...options.capabilities,
+        };
+    }
+    capabilities() {
+        return { ...this.modelCapabilities };
+    }
+    queueResponse(response) {
+        this.scriptedResponses.push(response);
+    }
+    async chat(request) {
+        this.requests.push(request);
+        const response = this.scriptedResponses.shift();
+        if (response === undefined) {
+            throw new llm_1.LLMProviderError('ScriptedChatModel has no queued response.', {
+                provider: this.name,
+                retryable: false,
+            });
+        }
+        return typeof response === 'function' ? await response(request) : response;
+    }
+}
+exports.ScriptedChatModel = ScriptedChatModel;
+class FakeChatModel {
+    name;
+    model;
+    requests = [];
+    prefix;
+    constructor(options = {}) {
+        this.name = options.name ?? 'fake';
+        this.model = options.model ?? 'fake-model';
+        this.prefix = options.prefix ?? 'reply:';
+    }
+    capabilities() {
+        return {
+            streaming: false,
+            toolCalling: true,
+            structuredOutput: false,
+            vision: false,
+        };
+    }
+    async chat(request) {
+        this.requests.push(request);
+        const lastUserMessage = [...request.messages]
+            .reverse()
+            .find((message) => message.role === 'user');
+        return {
+            role: 'assistant',
+            content: `${this.prefix}${lastUserMessage ? (0, messages_1.contentToText)(lastUserMessage.content) : ''}`,
+            toolCalls: [],
+        };
+    }
+}
+exports.FakeChatModel = FakeChatModel;
+//# sourceMappingURL=models.js.map

package/dist/testing/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/testing/models.ts"],"names":[],"mappings":";;;AAOA,gCAA0C;AAC1C,0CAA4C;AAa5C,MAAa,iBAAiB;IACjB,IAAI,CAAoB;IACxB,KAAK,CAAS;IACd,QAAQ,GAAkB,EAAE,CAAC;IACrB,iBAAiB,CAAyB;IAC1C,iBAAiB,CAAoB;IAEtD,YAAY,UAAoC,EAAE;QAC9C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,CAAC;QACvC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAAC;QAC/C,IAAI,CAAC,iBAAiB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC;QACxD,IAAI,CAAC,iBAAiB,GAAG;YACrB,SAAS,EAAE,KAAK;YAChB,WAAW,EAAE,IAAI;YACjB,gBAAgB,EAAE,KAAK;YACvB,MAAM,EAAE,KAAK;YACb,GAAG,OAAO,CAAC,YAAY;SAC1B,CAAC;IACN,CAAC;IAED,YAAY;QACR,OAAO,EAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;IACzC,CAAC;IAED,aAAa,CAAC,QAA8B;QACxC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC;QAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,IAAI,sBAAgB,CAAC,2CAA2C,EAAE;gBACpE,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,SAAS,EAAE,KAAK;aACnB,CAAC,CAAC;QACP,CAAC;QAED,OAAO,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC/E,CAAC;CACJ;AAxCD,8CAwCC;AAQD,MAAa,aAAa;IACb,IAAI,CAAoB;IACxB,KAAK,CAAS;IACd,QAAQ,GAAkB,EAAE,CAAC;IACrB,MAAM,CAAS;IAEhC,YAAY,UAAgC,EAAE;QAC1C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC;IAC7C,CAAC;IAED,YAAY;QACR,OAAO;YACH,SAAS,EAAE,KAAK;YAChB,WAAW,EAAE,IAAI;YACjB,gBAAgB,EAAE,KAAK;YACvB,MAAM,EAAE,KAAK;SAChB,CAAC;IACN,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,MAAM,eAAe,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;aACxC,OAAO,EAAE;aACT,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QAEhD,OAAO;YACH,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC,IAAA,wBAAa,EAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE;YACzF,SAAS,EAAE,EAAE;SAChB,CAAC;IACN,CAAC;CACJ;AAjCD,sCAiCC"}

package/dist/testing/tool-schema.d.ts

@@ -0,0 +1,6 @@
+import type { ChatToolSchema } from '../llm';
+import type { Tool } from '../tools';
+export type ToolSchemaSnapshot = ChatToolSchema;
+export declare function createToolSchemaSnapshot(tool: Tool): ToolSchemaSnapshot;
+export declare function assertToolSchemaSnapshot(tool: Tool, expected: ToolSchemaSnapshot): void;
+//# sourceMappingURL=tool-schema.d.ts.map

package/dist/testing/tool-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.d.ts","sourceRoot":"","sources":["../../src/testing/tool-schema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAErC,MAAM,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAEhD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,IAAI,GAAG,kBAAkB,CAEvE;AAED,wBAAgB,wBAAwB,CACpC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,kBAAkB,GAC7B,IAAI,CAEN"}

package/dist/testing/tool-schema.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolSchemaSnapshot = createToolSchemaSnapshot;
+exports.assertToolSchemaSnapshot = assertToolSchemaSnapshot;
+const strict_1 = __importDefault(require("node:assert/strict"));
+function createToolSchemaSnapshot(tool) {
+    return sortJson(tool.toOpenAISchema());
+}
+function assertToolSchemaSnapshot(tool, expected) {
+    strict_1.default.deepEqual(createToolSchemaSnapshot(tool), sortJson(expected));
+}
+function sortJson(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortJson);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nestedValue]) => [key, sortJson(nestedValue)]));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=tool-schema.js.map

package/dist/testing/tool-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.js","sourceRoot":"","sources":["../../src/testing/tool-schema.ts"],"names":[],"mappings":";;;;;AAMA,4DAEC;AAED,4DAKC;AAfD,gEAAwC;AAMxC,SAAgB,wBAAwB,CAAC,IAAU;IAC/C,OAAO,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,CAAuB,CAAC;AACjE,CAAC;AAED,SAAgB,wBAAwB,CACpC,IAAU,EACV,QAA4B;IAE5B,gBAAM,CAAC,SAAS,CAAC,wBAAwB,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,OAAO,MAAM,CAAC,WAAW,CACrB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SAChB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CACjE,CAAC;AACN,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACvD,CAAC"}

package/dist/testing/tools.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { Tool } from '../tools';
+import type { ToolInput, ToolInputSchema, ToolOptions, ToolRunContext } from '../tools';
+declare const EmptyToolSchema: z.ZodObject<{}, z.core.$strip>;
+export interface FakeToolCall<TInput = unknown> {
+    input: TInput;
+    context: ToolRunContext;
+}
+export interface FakeToolOptions<TSchema extends ToolInputSchema, TResult> extends ToolOptions<TSchema, TResult> {
+    result?: TResult;
+    handler?: (input: ToolInput<TSchema>, context: ToolRunContext) => TResult | Promise<TResult>;
+}
+export declare class FakeTool<TSchema extends ToolInputSchema = typeof EmptyToolSchema, TResult = string> extends Tool<TSchema, TResult> {
+    readonly calls: Array<FakeToolCall<ToolInput<TSchema>>>;
+    private readonly result;
+    private readonly handler;
+    constructor(options?: Partial<FakeToolOptions<TSchema, TResult>>);
+    protected run(input: ToolInput<TSchema>, context: ToolRunContext): Promise<TResult>;
+}
+export {};
+//# sourceMappingURL=tools.d.ts.map

package/dist/testing/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/testing/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACH,IAAI,EACP,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACR,SAAS,EACT,eAAe,EACf,WAAW,EACX,cAAc,EACjB,MAAM,UAAU,CAAC;AAElB,QAAA,MAAM,eAAe,gCAAe,CAAC;AAErC,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,OAAO;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe,CAC5B,OAAO,SAAS,eAAe,EAC/B,OAAO,CACT,SAAQ,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CACN,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,OAAO,EAAE,cAAc,KACtB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnC;AAED,qBAAa,QAAQ,CACjB,OAAO,SAAS,eAAe,GAAG,OAAO,eAAe,EACxD,OAAO,GAAG,MAAM,CAClB,SAAQ,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAM;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+C;gBAE3D,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;cAyBhD,GAAG,CACf,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,EACzB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,OAAO,CAAC;CAQtB"}

package/dist/testing/tools.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeTool = void 0;
+const zod_1 = require("zod");
+const tools_1 = require("../tools");
+const EmptyToolSchema = zod_1.z.object({});
+class FakeTool extends tools_1.Tool {
+    calls = [];
+    result;
+    handler;
+    constructor(options) {
+        const schema = (options?.schema ?? EmptyToolSchema);
+        const toolOptions = {
+            name: options?.name ?? 'fake_tool',
+            description: options?.description ?? 'A fake tool for tests.',
+            schema,
+        };
+        if (options?.timeoutMs !== undefined) {
+            toolOptions.timeoutMs = options.timeoutMs;
+        }
+        if (options?.errorMode !== undefined) {
+            toolOptions.errorMode = options.errorMode;
+        }
+        if (options?.canExecute !== undefined) {
+            toolOptions.canExecute = options.canExecute;
+        }
+        if (options?.serializeResult !== undefined) {
+            toolOptions.serializeResult = options.serializeResult;
+        }
+        super(toolOptions);
+        this.result = options?.result;
+        this.handler = options?.handler;
+    }
+    async run(input, context) {
+        this.calls.push({ input, context });
+        if (this.handler) {
+            return await this.handler(input, context);
+        }
+        return (this.result ?? 'ok');
+    }
+}
+exports.FakeTool = FakeTool;
+//# sourceMappingURL=tools.js.map

package/dist/testing/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/testing/tools.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,oCAEkB;AAQlB,MAAM,eAAe,GAAG,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAkBrC,MAAa,QAGX,SAAQ,YAAsB;IACnB,KAAK,GAA4C,EAAE,CAAC;IAC5C,MAAM,CAAsB;IAC5B,OAAO,CAA+C;IAEvE,YAAY,OAAoD;QAC5D,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,eAAe,CAAY,CAAC;QAC/D,MAAM,WAAW,GAAkC;YAC/C,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,WAAW;YAClC,WAAW,EAAE,OAAO,EAAE,WAAW,IAAI,wBAAwB;YAC7D,MAAM;SACT,CAAC;QACF,IAAI,OAAO,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,WAAW,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC9C,CAAC;QACD,IAAI,OAAO,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,WAAW,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC9C,CAAC;QACD,IAAI,OAAO,EAAE,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,WAAW,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QAChD,CAAC;QACD,IAAI,OAAO,EAAE,eAAe,KAAK,SAAS,EAAE,CAAC;YACzC,WAAW,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC1D,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IACpC,CAAC;IAES,KAAK,CAAC,GAAG,CACf,KAAyB,EACzB,OAAuB;QAEvB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAY,CAAC;IAC5C,CAAC;CACJ;AA5CD,4BA4CC"}

package/dist/tools/base.d.ts

@@ -1,14 +1,28 @@
 import { z } from 'zod';
-import type { ChatToolSchema } from '../llm/types';
+import { ToolError } from '../errors';
+import type { ChatToolSchema, ToolDefinition } from '../llm/types';
+import type { MessageContent } from '../messages/content';
 export type ToolInputSchema = z.ZodType;
 export type ToolInput<TSchema extends ToolInputSchema> = z.infer<TSchema>;
-export interface ToolOptions<TSchema extends ToolInputSchema> {
+export type ToolErrorMode = 'return_to_model' | 'throw';
+export type ToolPermissionChecker = (context: ToolRunContext) => boolean | Promise<boolean>;
+export interface ToolRunContext {
+    runId: string;
+    agentName?: string | undefined;
+    sessionId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface ToolOptions<TSchema extends ToolInputSchema, TResult = unknown> {
     name: string;
     description: string;
     schema: TSchema;
+    timeoutMs?: number;
+    errorMode?: ToolErrorMode;
+    canExecute?: ToolPermissionChecker;
+    serializeResult?: (result: TResult) => MessageContent;
 }
-export declare class ToolValidationError extends Error {
-    readonly toolName: string;
+export declare class ToolValidationError extends ToolError {
     readonly issues: readonly z.core.$ZodIssue[];
     constructor(toolName: string, error: z.ZodError);
 }
@@ -16,13 +30,30 @@ export declare abstract class Tool<TSchema extends ToolInputSchema = ToolInputSc
     readonly name: string;
     readonly description: string;
     readonly schema: TSchema;
-    protected constructor(options: ToolOptions<TSchema>);
+    readonly timeoutMs: number | undefined;
+    readonly errorMode: ToolErrorMode;
+    private readonly permissionChecker;
+    private readonly resultSerializer;
+    protected constructor(options: ToolOptions<TSchema, TResult>);
     /**
      * 模型返回的是未可信的 JSON 参数，进入具体工具前必须先通过 schema。
      * 子类只实现 run(validatedInput)，不用重复写参数校验样板代码。
      */
-    execute(parameters: unknown): Promise<TResult>;
+    execute(parameters: unknown, context?: Partial<ToolRunContext>): Promise<TResult>;
+    /**
+     * 工具结果最终要作为消息内容反馈给模型。
+     * 默认策略：字符串与 content block 数组原样透传，其余值用 JSON 序列化，
+     * 避免对象被降级成 "[object Object]" 这类对模型无意义的文本。
+     */
+    serializeResult(result: TResult): MessageContent;
+    toToolSchema(): ToolDefinition;
+    /**
+     * @deprecated 请使用 toToolSchema()；此方法返回 OpenAI 专有形状。
+     */
     toOpenAISchema(): ChatToolSchema;
-    protected abstract run(parameters: ToolInput<TSchema>): TResult | Promise<TResult>;
+    protected abstract run(parameters: ToolInput<TSchema>, context: ToolRunContext): TResult | Promise<TResult>;
+    protected canExecute(_context: ToolRunContext): boolean | Promise<boolean>;
+    private ensureCanExecute;
+    private runWithControls;
 }
 //# sourceMappingURL=base.d.ts.map

package/dist/tools/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/tools/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,OAAO,CAAC;AACxC,MAAM,MAAM,SAAS,CAAC,OAAO,SAAS,eAAe,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAE1E,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,eAAe;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBAEjC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ;CAMlD;AAED,8BAAsB,IAAI,CACtB,OAAO,SAAS,eAAe,GAAG,eAAe,EACjD,OAAO,GAAG,OAAO;IAEjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB,SAAS,aAAa,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC;IAMnD;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IASpD,cAAc,IAAI,cAAc;IAYhC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CACrF"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/tools/base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGH,SAAS,EAGZ,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,OAAO,CAAC;AACxC,MAAM,MAAM,SAAS,CAAC,OAAO,SAAS,eAAe,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC1E,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,OAAO,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAI5F,MAAM,WAAW,cAAc;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC/C,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,WAAW,CAAC,OAAO,SAAS,eAAe,EAAE,OAAO,GAAG,OAAO;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,cAAc,CAAC;CACzD;AAED,qBAAa,mBAAoB,SAAQ,SAAS;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBAEjC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ;CAalD;AAED,8BAAsB,IAAI,CACtB,OAAO,SAAS,eAAe,GAAG,eAAe,EACjD,OAAO,GAAG,OAAO;IAEjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoC;IACtE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoD;IAErF,SAAS,aAAa,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC;IAY5D;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAUvF;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc;IAwBhD,YAAY,IAAI,cAAc;IAS9B;;OAEG;IACH,cAAc,IAAI,cAAc;IAahC,SAAS,CAAC,QAAQ,CAAC,GAAG,CAClB,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,EAC9B,OAAO,EAAE,cAAc,GACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAE7B,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;YAI5D,gBAAgB;YAWhB,eAAe;CAyDhC"}

package/dist/tools/base.js

@@ -2,13 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tool = exports.ToolValidationError = void 0;
 const zod_1 = require("zod");
-class ToolValidationError extends Error {
-    toolName;
+const errors_1 = require("../errors");
+const content_1 = require("../messages/content");
+const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+class ToolValidationError extends errors_1.ToolError {
     issues;
     constructor(toolName, error) {
-        super(`Tool "${toolName}" received invalid parameters.`);
-        this.name = 'ToolValidationError';
-        this.toolName = toolName;
+        super(`Tool "${toolName}" received invalid parameters.`, {
+            code: 'tool_validation',
+            retryable: false,
+            toolName,
+            cause: error,
+            metadata: {
+                toolName,
+                issueCount: error.issues.length,
+            },
+        });
         this.issues = error.issues;
     }
 }
@@ -17,35 +26,253 @@ class Tool {
     name;
     description;
     schema;
+    timeoutMs;
+    errorMode;
+    permissionChecker;
+    resultSerializer;
     constructor(options) {
+        validateToolOptions(options);
         this.name = options.name;
         this.description = options.description;
         this.schema = options.schema;
+        this.timeoutMs = options.timeoutMs;
+        this.errorMode = options.errorMode ?? 'return_to_model';
+        this.permissionChecker = options.canExecute;
+        this.resultSerializer = options.serializeResult;
     }
     /**
      * 模型返回的是未可信的 JSON 参数，进入具体工具前必须先通过 schema。
      * 子类只实现 run(validatedInput)，不用重复写参数校验样板代码。
      */
-    async execute(parameters) {
+    async execute(parameters, context) {
         const parsed = await this.schema.safeParseAsync(parameters);
         if (!parsed.success) {
             throw new ToolValidationError(this.name, parsed.error);
         }
-        return await this.run(parsed.data);
+        const runContext = createToolRunContext(context);
+        return await this.runWithControls(parsed.data, runContext);
     }
+    /**
+     * 工具结果最终要作为消息内容反馈给模型。
+     * 默认策略：字符串与 content block 数组原样透传，其余值用 JSON 序列化，
+     * 避免对象被降级成 "[object Object]" 这类对模型无意义的文本。
+     */
+    serializeResult(result) {
+        if (this.resultSerializer) {
+            return this.resultSerializer(result);
+        }
+        if (typeof result === 'string') {
+            return result;
+        }
+        if ((0, content_1.isMessageContent)(result)) {
+            return result;
+        }
+        if (result === undefined) {
+            return '';
+        }
+        try {
+            return JSON.stringify(result) ?? String(result);
+        }
+        catch {
+            return String(result);
+        }
+    }
+    toToolSchema() {
+        return {
+            name: this.name,
+            description: this.description,
+            strict: true,
+            parameters: toStrictObjectSchema(this.schema),
+        };
+    }
+    /**
+     * @deprecated 请使用 toToolSchema()；此方法返回 OpenAI 专有形状。
+     */
     toOpenAISchema() {
+        const schema = this.toToolSchema();
         return {
             type: 'function',
             function: {
-                name: this.name,
-                description: this.description,
-                strict: true,
-                parameters: toStrictObjectSchema(this.schema),
+                name: schema.name,
+                description: schema.description,
+                strict: schema.strict ?? true,
+                parameters: schema.parameters,
             },
         };
     }
+    canExecute(_context) {
+        return true;
+    }
+    async ensureCanExecute(context) {
+        const allowedBySubclass = await this.canExecute(context);
+        const allowedByOptions = this.permissionChecker
+            ? await this.permissionChecker(context)
+            : true;
+        if (!allowedBySubclass || !allowedByOptions) {
+            throw new errors_1.ToolPermissionError(this.name);
+        }
+    }
+    async runWithControls(parameters, context) {
+        const attemptSignal = createToolAttemptSignal(this.name, context.signal, this.timeoutMs);
+        const startedAt = Date.now();
+        let timeoutId;
+        let abortCleanup;
+        try {
+            const controlledContext = withToolSignal(context, attemptSignal.signal);
+            const operation = (async () => {
+                await this.ensureCanExecute(controlledContext);
+                return await this.run(parameters, controlledContext);
+            })();
+            const race = [operation];
+            if (this.timeoutMs !== undefined && this.timeoutMs > 0) {
+                race.push(new Promise((_resolve, reject) => {
+                    timeoutId = setTimeout(() => {
+                        attemptSignal.abortForTimeout();
+                        reject(new errors_1.ToolTimeoutError(this.name, this.timeoutMs));
+                    }, this.timeoutMs);
+                }));
+            }
+            const abortRace = createToolAbortRace(this.name, attemptSignal.signal, attemptSignal.abortedByCaller);
+            if (abortRace !== undefined) {
+                race.push(abortRace.promise);
+                abortCleanup = abortRace.cleanup;
+            }
+            return await Promise.race(race);
+        }
+        catch (error) {
+            if (attemptSignal.timedOut()) {
+                throw new errors_1.ToolTimeoutError(this.name, this.timeoutMs ?? Date.now() - startedAt, {
+                    cause: error,
+                });
+            }
+            if (attemptSignal.abortedByCaller()) {
+                throw new errors_1.ToolAbortError(this.name, { cause: error });
+            }
+            throw error;
+        }
+        finally {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            abortCleanup?.();
+            attemptSignal.cleanup();
+        }
+    }
 }
 exports.Tool = Tool;
+function validateToolOptions(options) {
+    if (typeof options.name !== 'string' || !TOOL_NAME_PATTERN.test(options.name)) {
+        throwInvalidToolOption('name', 'must be 1-64 characters and contain only letters, numbers, underscores, or hyphens', typeof options.name === 'string' ? options.name : '<invalid>');
+    }
+    if (typeof options.description !== 'string' || options.description.trim().length === 0) {
+        throwInvalidToolOption('description', 'must be a non-empty string', options.name);
+    }
+    if (!isZodSchema(options.schema)) {
+        throwInvalidToolOption('schema', 'must be a Zod schema', options.name);
+    }
+    if (options.timeoutMs !== undefined
+        && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+        throwInvalidToolOption('timeoutMs', 'must be a non-negative finite number', options.name);
+    }
+    if (options.errorMode !== undefined
+        && options.errorMode !== 'return_to_model'
+        && options.errorMode !== 'throw') {
+        throwInvalidToolOption('errorMode', 'must be "return_to_model" or "throw"', options.name);
+    }
+    if (options.canExecute !== undefined && typeof options.canExecute !== 'function') {
+        throwInvalidToolOption('canExecute', 'must be a function', options.name);
+    }
+    if (options.serializeResult !== undefined && typeof options.serializeResult !== 'function') {
+        throwInvalidToolOption('serializeResult', 'must be a function', options.name);
+    }
+}
+function throwInvalidToolOption(option, reason, toolName) {
+    throw new errors_1.ToolConfigurationError(`Invalid ToolOptions.${option}: ${reason}.`, {
+        toolName,
+        metadata: {
+            option,
+            toolName,
+        },
+    });
+}
+function isZodSchema(value) {
+    return typeof value === 'object'
+        && value !== null
+        && 'safeParseAsync' in value
+        && typeof value.safeParseAsync === 'function';
+}
+function createToolRunContext(context) {
+    return {
+        runId: context?.runId ?? 'standalone',
+        agentName: context?.agentName,
+        sessionId: context?.sessionId,
+        metadata: context?.metadata,
+        signal: context?.signal,
+    };
+}
+function createToolAttemptSignal(toolName, callerSignal, timeoutMs) {
+    if (callerSignal?.aborted) {
+        throw new errors_1.ToolAbortError(toolName, { cause: callerSignal.reason });
+    }
+    const needsSignal = callerSignal !== undefined || (timeoutMs !== undefined && timeoutMs > 0);
+    if (!needsSignal) {
+        return {
+            signal: undefined,
+            timedOut: () => false,
+            abortedByCaller: () => false,
+            abortForTimeout: () => undefined,
+            cleanup: () => undefined,
+        };
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    let abortedByCaller = false;
+    const onCallerAbort = () => {
+        abortedByCaller = true;
+        controller.abort(callerSignal?.reason);
+    };
+    callerSignal?.addEventListener('abort', onCallerAbort, { once: true });
+    return {
+        signal: controller.signal,
+        timedOut: () => timedOut,
+        abortedByCaller: () => abortedByCaller,
+        abortForTimeout: () => {
+            timedOut = true;
+            controller.abort();
+        },
+        cleanup: () => {
+            callerSignal?.removeEventListener('abort', onCallerAbort);
+        },
+    };
+}
+function withToolSignal(context, signal) {
+    return {
+        ...context,
+        signal,
+    };
+}
+function createToolAbortRace(toolName, signal, abortedByCaller) {
+    if (signal === undefined) {
+        return undefined;
+    }
+    let onAbort;
+    const promise = new Promise((_resolve, reject) => {
+        onAbort = () => {
+            if (abortedByCaller()) {
+                reject(new errors_1.ToolAbortError(toolName));
+            }
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    return {
+        promise,
+        cleanup: () => {
+            if (onAbort !== undefined) {
+                signal.removeEventListener('abort', onAbort);
+            }
+        },
+    };
+}
 function toStrictObjectSchema(schema) {
     const jsonSchema = zod_1.z.toJSONSchema(schema);
     const normalizedSchema = stripUnsupportedJsonSchemaFields(jsonSchema);