@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/tool.ts

@@ -0,0 +1,319 @@
+import { Ajv } from "ajv";
+import addFormats from "ajv-formats";
+
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
+import { writeOutput } from "./output.js";
+import type { SchemaBuilder } from "./schema-builder.js";
+import { getSchema } from "./schema-builder.js";
+import type { HandlerOptions } from "./types.js";
+
+/**
+ * Any JSON-serializable value.
+ */
+export type JSONValue =
+	| string
+	| number
+	| boolean
+	| null
+	| JSONValue[]
+	| { [key: string]: JSONValue };
+
+/**
+ * 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 creation 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}]`,
+			);
+		}
+	}
+}
+
+/**
+ * Hints describing a tool's behavior. Advisory metadata read by the platform
+ * (not the model) to decide whether a call is safe to auto-execute or
+ * requires user confirmation.
+ *
+ * Field names mirror the MCP tool annotation shape
+ * (`McpServerToolAnnotations`) so worker tools flow through the same
+ * confirmation / auto-execute machinery as MCP tools.
+ *
+ * Only hints with active consumers in the Notion client are included.
+ */
+export interface ToolHints {
+	/**
+	 * The tool only reads state and has no side effects. Safe to call
+	 * repeatedly; safe to auto-execute under default policy. Tools without
+	 * this hint are treated as write tools and prompt for confirmation.
+	 */
+	readOnlyHint?: boolean;
+}
+
+/**
+ * Configuration passed to {@link createTool}.
+ */
+export interface ToolConfiguration<I extends JSONValue, O extends JSONValue = JSONValue> {
+	title: string;
+	description: string;
+	schema: SchemaBuilder<I>;
+	outputSchema?: SchemaBuilder<O>;
+	hints?: ToolHints;
+	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,
+			trace: this.stack,
+		};
+	}
+}
+
+/**
+ * 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,
+			trace: this.stack,
+		};
+	}
+}
+
+/**
+ * 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,
+			trace: this.stack,
+		};
+	}
+}
+
+type ToolErrorResult = {
+	_tag: "error";
+	error: { name: string; message: string; trace: string | undefined };
+};
+
+/**
+ * The manifest-visible configuration of a tool: the metadata from
+ * {@link ToolConfiguration} with the schema builders resolved to plain
+ * JSON Schemas.
+ */
+export type ToolManifestConfig = {
+	title: string;
+	description: string;
+	schema: AnyJSONSchema;
+	outputSchema: AnyJSONSchema | undefined;
+	hints: ToolHints | undefined;
+};
+
+/**
+ * A tool capability as returned by {@link createTool}.
+ *
+ * Note that a tool carries no key of its own — the build tool derives the
+ * capability key from the file the tool is default-exported from.
+ */
+export type Tool<I extends JSONValue = JSONValue, O extends JSONValue = JSONValue> = {
+	_tag: "tool";
+	config: ToolManifestConfig;
+	handler: (
+		input: I,
+		options?: HandlerOptions,
+	) => Promise<O | { _tag: "success"; value: O } | ToolErrorResult>;
+};
+
+/**
+ * Create a tool capability for use by an agent.
+ *
+ * Default-export the result from a file directly under `src/tools/` —
+ * the file's basename becomes the tool's key.
+ *
+ * @example
+ * ```ts
+ * // src/tools/sayHello.ts
+ * import { j } from "@notionhq/workers/alpha/schema-builder";
+ * import { createTool } from "@notionhq/workers/alpha/tool";
+ *
+ * export default createTool({
+ *   title: "Say Hello",
+ *   description: "Say hello to the user",
+ *   schema: j.object({ name: j.string() }),
+ *   execute: ({ name }) => {
+ *     return `Hello, ${name}!`;
+ *   },
+ * });
+ * ```
+ */
+export function createTool<I extends JSONValue, O extends JSONValue = JSONValue>(
+	config: ToolConfiguration<I, O>,
+): Tool<I, O> {
+	const inputSchema = getSchema(config.schema);
+	validateRequiredProperties(inputSchema as AnyJSONSchema);
+
+	const outputSchema: JSONSchema<O> | undefined = config.outputSchema
+		? getSchema(config.outputSchema)
+		: undefined;
+
+	if (outputSchema) {
+		validateRequiredProperties(outputSchema as AnyJSONSchema);
+	}
+
+	const ajv = new Ajv();
+	addFormats(ajv);
+	const validateInput = ajv.compile(inputSchema);
+	const validateOutput = outputSchema ? ajv.compile(outputSchema) : null;
+
+	async function handler(
+		input: I,
+		options?: HandlerOptions,
+	): Promise<O | { _tag: "success"; value: O } | ToolErrorResult> {
+		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: ToolErrorResult = {
+				_tag: "error",
+				error: { name: error.name, message: error.message, trace: error.stack },
+			};
+
+			writeOutput(result);
+
+			return result;
+		}
+
+		try {
+			const capabilityContext = createCapabilityContext("tool");
+			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 errorResult: ToolErrorResult = {
+					_tag: "error",
+					error: { name: error.name, message: error.message, trace: error.stack },
+				};
+
+				writeOutput(errorResult);
+
+				return errorResult;
+			}
+
+			if (options?.concreteOutput) {
+				return result;
+			}
+
+			writeOutput({ _tag: "success", value: result });
+
+			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: ToolErrorResult = {
+				_tag: "error",
+				error: { name: error.name, message: error.message, trace: error.stack },
+			};
+
+			writeOutput(result);
+
+			return result;
+		}
+	}
+
+	return {
+		_tag: "tool",
+		config: {
+			title: config.title,
+			description: config.description,
+			schema: inputSchema as AnyJSONSchema,
+			outputSchema: outputSchema as AnyJSONSchema | undefined,
+			hints: config.hints,
+		},
+		handler,
+	};
+}