@project-ajax/sdk 0.0.28

package/src/capabilities/tool.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from "vitest";
+import {
+	InvalidToolInputError,
+	InvalidToolOutputError,
+	ToolExecutionError,
+	tool,
+} from "./tool.js";
+
+describe("tool", () => {
+	it("sync execution", async () => {
+		const myTool = tool<{ name: string }, string>({
+			description: "Greet a user",
+			schema: {
+				type: "object",
+				properties: {
+					name: { type: "string" },
+				},
+				required: ["name"],
+				additionalProperties: false,
+			},
+			execute: (input) => {
+				return `Hello, ${input.name}!`;
+			},
+		});
+
+		const result = await myTool.handler({ name: "Alice" });
+
+		expect(result._tag).toBe("success");
+		if (result._tag === "success") {
+			expect(result.value).toBe("Hello, Alice!");
+		}
+	});
+
+	it("async execution", async () => {
+		const myTool = tool<{ id: number }, { data: string }>({
+			description: "Fetch data asynchronously",
+			schema: {
+				type: "object",
+				properties: {
+					id: { type: "number" },
+				},
+				required: ["id"],
+				additionalProperties: false,
+			},
+			execute: async (input) => {
+				// Simulate async operation
+				await new Promise((resolve) => setTimeout(resolve, 10));
+				return { data: `Data for ID ${input.id}` };
+			},
+		});
+
+		const result = await myTool.handler({ id: 42 });
+
+		expect(result._tag).toBe("success");
+		if (result._tag === "success") {
+			expect(result.value).toEqual({ data: "Data for ID 42" });
+		}
+	});
+
+	it("execution error", async () => {
+		const myTool = tool<Record<string, never>, string>({
+			description: "Throws an error",
+			schema: {
+				type: "object",
+				properties: {},
+				required: [],
+				additionalProperties: false,
+			},
+			execute: () => {
+				throw new Error("Something went wrong");
+			},
+		});
+
+		const result = await myTool.handler({});
+
+		expect(result._tag).toBe("error");
+		if (result._tag === "error") {
+			expect(result.error).toBeInstanceOf(ToolExecutionError);
+			expect(result.error.message).toBe("Something went wrong");
+		}
+	});
+
+	it("invalid input", async () => {
+		const myTool = tool<{ name: string }, string>({
+			description: "Requires a name property",
+			schema: {
+				type: "object",
+				properties: {
+					name: { type: "string" },
+				},
+				required: ["name"],
+				additionalProperties: false,
+			},
+			execute: (input) => {
+				return `Hello, ${input.name}!`;
+			},
+		});
+
+		const result = await myTool.handler({ age: 25 });
+
+		expect(result._tag).toBe("error");
+		if (result._tag === "error") {
+			expect(result.error).toBeInstanceOf(InvalidToolInputError);
+			expect(result.error.message).toContain("name");
+		}
+	});
+
+	it("invalid output", async () => {
+		const myTool = tool<Record<string, never>, { result: string }>({
+			name: "returnInvalidOutput",
+			description: "Returns output that doesn't match schema",
+			schema: {
+				type: "object",
+				properties: {},
+				required: [],
+				additionalProperties: false,
+			},
+			outputSchema: {
+				type: "object",
+				properties: {
+					result: { type: "string" },
+				},
+				required: ["result"],
+				additionalProperties: false,
+			},
+			// @ts-expect-error Testing invalid output - intentionally returning number instead of string
+			execute: () => {
+				return { result: 123 };
+			},
+		});
+
+		const result = await myTool.handler({});
+
+		expect(result._tag).toBe("error");
+		if (result._tag === "error") {
+			expect(result.error).toBeInstanceOf(InvalidToolOutputError);
+			expect(result.error.message).toContain("result");
+		}
+	});
+
+	it("invalid output with custom output schema", async () => {
+		const myTool = tool<
+			{ value: number },
+			{ doubled: number; message: string }
+		>({
+			name: "customOutput",
+			description: "Has custom output schema",
+			schema: {
+				type: "object",
+				properties: {
+					value: { type: "number" },
+				},
+				required: ["value"],
+				additionalProperties: false,
+			},
+			outputSchema: {
+				type: "object",
+				properties: {
+					doubled: { type: "number" },
+					message: { type: "string" },
+				},
+				required: ["doubled", "message"],
+				additionalProperties: false,
+			},
+			// @ts-expect-error Testing invalid output - intentionally missing message property
+			execute: (input) => {
+				return {
+					doubled: input.value * 2,
+				};
+			},
+		});
+
+		const result = await myTool.handler({ value: 5 });
+
+		expect(result._tag).toBe("error");
+		if (result._tag === "error") {
+			expect(result.error).toBeInstanceOf(InvalidToolOutputError);
+			expect(result.error.message).toContain("message");
+		}
+	});
+});

package/src/capabilities/tool.ts

@@ -0,0 +1,145 @@
+import { Ajv, type JSONSchemaType } from "ajv";
+
+type JSONValue =
+	| string
+	| number
+	| boolean
+	| null
+	| JSONValue[]
+	| { [key: string]: JSONValue };
+
+export interface ToolConfiguration<
+	I extends JSONValue,
+	O extends JSONValue = JSONValue,
+> {
+	description: string;
+	schema: JSONSchemaType<I>;
+	outputSchema?: JSONSchemaType<O>;
+	execute: (input: I) => O | Promise<O>;
+}
+
+/**
+ * An error returned when the input to a tool doesn't match the input schema.
+ */
+export class InvalidToolInputError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "InvalidToolInputError";
+	}
+}
+
+/**
+ * An error returned when the output from a tool doesn't match the output schema.
+ */
+export class InvalidToolOutputError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "InvalidToolOutputError";
+	}
+}
+
+/**
+ * An error returned when the tool execution fails.
+ */
+export class ToolExecutionError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ToolExecutionError";
+	}
+}
+
+/**
+ * Creates a capability definition for a tool to be used by an agent.
+ *
+ * Example:
+ *
+ * ```ts
+ * tool<{ name: string }>({
+ *   description: "Say hello to the user",
+ *   schema: {
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *     },
+ *     required: ["name"],
+ *   },
+ *   execute: ({ name }) => {
+ *     return `Hello, ${name}!`;
+ *   },
+ * })
+ * ```
+ *
+ * @param config - The configuration for the tool.
+ * @returns A capability definition for the tool.
+ */
+export function tool<I extends JSONValue, O extends JSONValue = JSONValue>(
+	config: ToolConfiguration<I, O>,
+) {
+	const ajv = new Ajv();
+	const validateInput = ajv.compile(config.schema);
+	const validateOutput = config.outputSchema
+		? ajv.compile(config.outputSchema)
+		: null;
+
+	return {
+		_tag: "tool",
+		config: {
+			description: config.description,
+			schema: config.schema,
+			outputSchema: config.outputSchema,
+		},
+		async handler(input: JSONValue): Promise<
+			| {
+					_tag: "success";
+					value: O;
+			  }
+			| {
+					_tag: "error";
+					error:
+						| InvalidToolInputError
+						| InvalidToolOutputError
+						| ToolExecutionError;
+			  }
+		> {
+			if (!validateInput(input)) {
+				// ajv resets the "errors" property on each validation call.
+				if (validateInput.errors == null) {
+					throw new Error(
+						"Unexpected: No validation errors after failed validation",
+					);
+				}
+
+				return {
+					_tag: "error" as const,
+					error: new InvalidToolInputError(
+						JSON.stringify(validateInput.errors, null, 2),
+					),
+				};
+			}
+
+			try {
+				const result = await config.execute(input);
+				if (validateOutput && !validateOutput(result)) {
+					return {
+						_tag: "error" as const,
+						error: new InvalidToolOutputError(
+							JSON.stringify(validateOutput.errors, null, 2),
+						),
+					};
+				}
+
+				return {
+					_tag: "success" as const,
+					value: result,
+				};
+			} catch (err) {
+				return {
+					_tag: "error" as const,
+					error: new ToolExecutionError(
+						err instanceof Error ? err.message : String(err),
+					),
+				};
+			}
+		},
+	};
+}