@notionhq/workers 0.0.82

package/src/capabilities/tool.test.ts

@@ -0,0 +1,351 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
+import {
+	createToolCapability,
+	InvalidToolInputError,
+	InvalidToolOutputError,
+	ToolExecutionError,
+} from "./tool.js";
+
+describe("Worker.tool", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("sync execution", async () => {
+		const capability = createToolCapability<{ name: string }, string>(
+			"sayHello",
+			{
+				title: "Say Hello",
+				description: "Greet a user",
+				schema: {
+					type: "object",
+					properties: {
+						name: { type: "string" },
+					},
+					required: ["name"],
+					additionalProperties: false,
+				},
+				execute: (input: { name: string }) => {
+					return `Hello, ${input.name}!`;
+				},
+			},
+		);
+
+		const result = await capability.handler({ name: "Alice" });
+
+		expect(result).toEqual({ _tag: "success", value: "Hello, Alice!" });
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>"Hello, Alice!"</output>\n`,
+		);
+	});
+
+	it("async execution", async () => {
+		const capability = createToolCapability<{ id: number }, { data: string }>(
+			"fetchData",
+			{
+				title: "Fetch Data",
+				description: "Fetch data asynchronously",
+				schema: {
+					type: "object",
+					properties: {
+						id: { type: "number" },
+					},
+					required: ["id"],
+					additionalProperties: false,
+				},
+				execute: async (input: { id: number }) => {
+					// Simulate async operation
+					await new Promise((resolve) => setTimeout(resolve, 10));
+					return { data: `Data for ID ${input.id}` };
+				},
+			},
+		);
+
+		const result = await capability.handler({ id: 42 });
+
+		expect(result).toEqual({
+			_tag: "success",
+			value: { data: "Data for ID 42" },
+		});
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"data":"Data for ID 42"}</output>\n`,
+		);
+	});
+
+	it("execution error", async () => {
+		const capability = createToolCapability<Record<string, never>, string>(
+			"throwError",
+			{
+				title: "Throw Error",
+				description: "Throws an error",
+				schema: {
+					type: "object",
+					properties: {},
+					required: [],
+					additionalProperties: false,
+				},
+				execute: () => {
+					throw new Error("Something went wrong");
+				},
+			},
+		);
+
+		const result = (await capability.handler({})) as {
+			_tag: "error";
+			error: ToolExecutionError;
+		};
+
+		expect(result._tag).toBe("error");
+		expect(result.error).toBeInstanceOf(ToolExecutionError);
+		expect(result.error.message).toBe("Something went wrong");
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"_tag":"error","error":{"name":"ToolExecutionError","message":"Something went wrong"}}</output>\n`,
+		);
+	});
+
+	it("invalid input", async () => {
+		const capability = createToolCapability<{ name: string }, string>(
+			"sayHelloStrict",
+			{
+				title: "Say Hello",
+				description: "Requires a name property",
+				schema: {
+					type: "object",
+					properties: {
+						name: { type: "string" },
+					},
+					required: ["name"],
+					additionalProperties: false,
+				},
+				execute: (input: { name: string }) => {
+					return `Hello, ${input.name}!`;
+				},
+			},
+		);
+
+		const result = (await capability.handler({ age: 25 })) as {
+			_tag: "error";
+			error: InvalidToolInputError;
+		};
+
+		expect(result._tag).toBe("error");
+		expect(result.error).toBeInstanceOf(InvalidToolInputError);
+		expect(result.error.message).toContain("name");
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`\n<output>{"_tag":"error","error":{"name":"InvalidToolInputError"`,
+			),
+		);
+	});
+
+	it("invalid output", async () => {
+		const capability = createToolCapability<
+			Record<string, never>,
+			{ result: string }
+		>("invalidOutput", {
+			title: "Return Invalid Output",
+			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 capability.handler({})) as {
+			_tag: "error";
+			error: InvalidToolOutputError;
+		};
+
+		expect(result._tag).toBe("error");
+		expect(result.error).toBeInstanceOf(InvalidToolOutputError);
+		expect(result.error.message).toContain("result");
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`\n<output>{"_tag":"error","error":{"name":"InvalidToolOutputError"`,
+			),
+		);
+	});
+
+	it("rejects schema where required is missing properties", () => {
+		expect(() =>
+			createToolCapability<{ name: string; age: number }, string>("bad", {
+				title: "Bad",
+				description: "Missing required",
+				schema: {
+					type: "object",
+					properties: {
+						name: { type: "string" },
+						age: { type: "number" },
+					},
+					required: ["name"],
+					additionalProperties: false,
+				} as never,
+				execute: () => "",
+			}),
+		).toThrow(/properties \[age\] must be listed in "required"/);
+	});
+
+	it("rejects nested schema where required is missing properties", () => {
+		expect(() =>
+			createToolCapability<{ user: { name: string; email: string } }, string>(
+				"bad",
+				{
+					title: "Bad",
+					description: "Nested missing required",
+					schema: {
+						type: "object",
+						properties: {
+							user: {
+								type: "object",
+								properties: {
+									name: { type: "string" },
+									email: { type: "string" },
+								},
+								required: ["name"],
+								additionalProperties: false,
+							} as never,
+						},
+						required: ["user"],
+						additionalProperties: false,
+					},
+					execute: () => "",
+				},
+			),
+		).toThrow(/at properties\.user.*properties \[email\]/);
+	});
+
+	it("accepts schema with nullable (string | null) properties", () => {
+		const capability = createToolCapability<
+			{ name: string; nickname: string | null },
+			string
+		>("nullable", {
+			title: "Nullable",
+			description: "Has nullable properties",
+			schema: {
+				type: "object",
+				properties: {
+					name: { type: "string" },
+					nickname: {
+						anyOf: [{ type: "string" }, { type: "null" }],
+					},
+				},
+				required: ["name", "nickname"],
+				additionalProperties: false,
+			},
+			execute: ({ name, nickname }) => `${name} (${nickname ?? "no nickname"})`,
+		});
+
+		expect(capability.config.schema).toBeDefined();
+	});
+
+	it("rejects output schema where required is missing properties", () => {
+		expect(() =>
+			createToolCapability<
+				Record<string, never>,
+				{ result: string; count: number }
+			>("bad", {
+				title: "Bad",
+				description: "Output missing required",
+				schema: {
+					type: "object",
+					properties: {},
+					required: [],
+					additionalProperties: false,
+				},
+				outputSchema: {
+					type: "object",
+					properties: {
+						result: { type: "string" },
+						count: { type: "number" },
+					},
+					required: ["result"],
+					additionalProperties: false,
+				} as never,
+				execute: () => ({ result: "", count: 0 }),
+			}),
+		).toThrow(/properties \[count\] must be listed in "required"/);
+	});
+
+	it("invalid output with custom output schema", async () => {
+		const capability = createToolCapability<
+			{ value: number },
+			{ doubled: number; message: string }
+		>("customOutput", {
+			title: "Custom Output",
+			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: { value: number }) => {
+				return {
+					doubled: input.value * 2,
+				};
+			},
+		});
+
+		const result = (await capability.handler({ value: 5 })) as {
+			_tag: "error";
+			error: InvalidToolOutputError;
+		};
+
+		expect(result._tag).toBe("error");
+		expect(result.error).toBeInstanceOf(InvalidToolOutputError);
+		expect(result.error.message).toContain("message");
+
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			expect.stringContaining(
+				`\n<output>{"_tag":"error","error":{"name":"InvalidToolOutputError"`,
+			),
+		);
+	});
+});

package/src/capabilities/tool.ts

@@ -0,0 +1,279 @@
+import { Ajv } from "ajv";
+import type { AnyJSONSchema, JSONSchema } from "../json-schema.js";
+import type { HandlerOptions, JSONValue } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+
+/**
+ * Validates that every object schema in the tree has all its `properties`
+ * keys listed in `required`. Both providers require this.
+ *
+ * Throws a descriptive error at tool registration time (not request time)
+ * so the developer sees it immediately.
+ */
+function validateRequiredProperties(
+	schema: AnyJSONSchema,
+	path: string = "",
+): void {
+	if ("type" in schema && schema.type === "object" && "properties" in schema) {
+		const propKeys = Object.keys(schema.properties).sort();
+		const required = [...(schema.required ?? [])].sort();
+		const missing = propKeys.filter((k) => !required.includes(k));
+		if (missing.length > 0) {
+			throw new Error(
+				`Invalid schema${path ? ` at ${path}` : ""}: ` +
+					`properties [${missing.join(", ")}] must be listed in "required". ` +
+					"Both model providers require all properties to be required. " +
+					'Use anyOf with { type: "null" } for optional fields.',
+			);
+		}
+
+		// Recurse into nested property schemas
+		for (const [key, propSchema] of Object.entries(schema.properties)) {
+			validateRequiredProperties(
+				propSchema as AnyJSONSchema,
+				path ? `${path}.properties.${key}` : `properties.${key}`,
+			);
+		}
+
+		// Recurse into $defs
+		if ("$defs" in schema && schema.$defs) {
+			for (const [key, defSchema] of Object.entries(schema.$defs)) {
+				validateRequiredProperties(
+					defSchema,
+					path ? `${path}.$defs.${key}` : `$defs.${key}`,
+				);
+			}
+		}
+	}
+
+	// Recurse into array items
+	if ("type" in schema && schema.type === "array" && "items" in schema) {
+		validateRequiredProperties(
+			schema.items as AnyJSONSchema,
+			path ? `${path}.items` : "items",
+		);
+	}
+
+	// Recurse into anyOf branches
+	if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
+		for (let i = 0; i < schema.anyOf.length; i++) {
+			validateRequiredProperties(
+				schema.anyOf[i] as AnyJSONSchema,
+				path ? `${path}.anyOf[${i}]` : `anyOf[${i}]`,
+			);
+		}
+	}
+}
+
+export interface ToolConfiguration<
+	I extends JSONValue,
+	O extends JSONValue = JSONValue,
+> {
+	title: string;
+	description: string;
+	schema: JSONSchema<I>;
+	outputSchema?: JSONSchema<O>;
+	execute: (input: I, context: CapabilityContext) => 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";
+	}
+
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+		};
+	}
+}
+
+/**
+ * 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";
+	}
+
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+		};
+	}
+}
+
+/**
+ * An error returned when the tool execution fails.
+ */
+export class ToolExecutionError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ToolExecutionError";
+	}
+
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+		};
+	}
+}
+
+export type ToolCapability<
+	I extends JSONValue,
+	O extends JSONValue = JSONValue,
+> = ReturnType<typeof createToolCapability<I, O>>;
+
+/**
+ * Creates a capability definition for a tool to be used by an agent.
+ *
+ * @param config - The configuration for the tool.
+ * @returns A capability definition for the tool.
+ */
+export function createToolCapability<
+	I extends JSONValue,
+	O extends JSONValue = JSONValue,
+>(key: string, config: ToolConfiguration<I, O>) {
+	validateRequiredProperties(config.schema as AnyJSONSchema);
+	if (config.outputSchema) {
+		validateRequiredProperties(config.outputSchema as AnyJSONSchema);
+	}
+
+	const ajv = new Ajv();
+	const validateInput = ajv.compile(config.schema);
+	const validateOutput = config.outputSchema
+		? ajv.compile(config.outputSchema)
+		: null;
+
+	async function handler(input: JSONValue, options: HandlerOptions): Promise<O>;
+	async function handler(input: JSONValue): Promise<
+		| {
+				_tag: "success";
+				value: O;
+		  }
+		| {
+				_tag: "error";
+				error:
+					| InvalidToolInputError
+					| InvalidToolOutputError
+					| ToolExecutionError;
+		  }
+	>;
+	async function handler(
+		input: JSONValue,
+		options?: HandlerOptions,
+	): Promise<
+		| O
+		| {
+				_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",
+				);
+			}
+
+			const error = new InvalidToolInputError(
+				JSON.stringify(validateInput.errors, null, 2),
+			);
+
+			if (options?.concreteOutput) {
+				throw error;
+			}
+
+			const result = {
+				_tag: "error" as const,
+				error,
+			};
+
+			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+			return result;
+		}
+
+		try {
+			const capabilityContext = createCapabilityContext();
+			const result = await config.execute(input, capabilityContext);
+			if (validateOutput && !validateOutput(result)) {
+				const error = new InvalidToolOutputError(
+					JSON.stringify(validateOutput.errors, null, 2),
+				);
+
+				if (options?.concreteOutput) {
+					throw error;
+				}
+
+				const result = {
+					_tag: "error" as const,
+					error: new InvalidToolOutputError(
+						JSON.stringify(validateOutput.errors, null, 2),
+					),
+				};
+
+				process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+				return result;
+			}
+
+			if (options?.concreteOutput) {
+				return result;
+			}
+
+			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+			return {
+				_tag: "success" as const,
+				value: result,
+			};
+		} catch (err) {
+			const error = new ToolExecutionError(
+				err instanceof Error ? err.message : String(err),
+			);
+
+			if (options?.concreteOutput) {
+				throw error;
+			}
+
+			const result = {
+				_tag: "error" as const,
+				error,
+			};
+
+			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+
+			return result;
+		}
+	}
+
+	return {
+		_tag: "tool" as const,
+		key,
+		config: {
+			title: config.title,
+			description: config.description,
+			schema: config.schema,
+			outputSchema: config.outputSchema,
+		},
+		handler,
+	};
+}

package/src/error.ts

@@ -0,0 +1,19 @@
+/**
+ * An error that occurred during the execution of a worker capability.
+ */
+export class ExecutionError extends Error {
+	readonly cause: unknown;
+
+	constructor(cause: unknown) {
+		super(`Error during worker execution: ${cause}`);
+		this.name = "ExecutionError";
+		this.cause = cause;
+	}
+}
+
+/**
+ * Helper for exhaustive switch statements. TypeScript will error if a case is not handled.
+ */
+export function unreachable(value: never): never {
+	throw new Error(`Unreachable: ${value}`);
+}