@warlock.js/ai-tools 4.5.0

package/esm/register.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-tools/src/register.ts"],"sourcesContent":["import { ai, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  CalculatorInput,\n  CalculatorOptions,\n  CalculatorResult,\n  DateTimeInput,\n  DateTimeOptions,\n  DateTimeResult,\n  FetchUrlInput,\n  FetchUrlOptions,\n  FetchUrlResult,\n  HttpRequestInput,\n  HttpRequestOptions,\n  HttpRequestResult,\n  WebSearchInput,\n  WebSearchOptions,\n  WebSearchResult,\n} from \"./contracts\";\nimport { httpRequestTool } from \"./http/http-request\";\nimport { type McpFactory, mcp } from \"./mcp\";\nimport { calculatorTool } from \"./utility/calculator\";\nimport { dateTimeTool } from \"./utility/date-time\";\nimport { fetchUrlTool } from \"./web/fetch-url\";\nimport { webSearchTool } from \"./web/web-search\";\n\n/**\n * The `ai.tools.*` namespace — the five ready-made agent tools this\n * package vends. Each member is a factory returning a {@link ToolContract}\n * that drops straight into `ai.agent({ tools: [...] })`. Declared inline on\n * the `Ai` interface below (one block, one shape) rather than accreted\n * across the tool sub-barrels, mirroring the `ai.workspace` augmentation in\n * `@warlock.js/ai-workspace`.\n */\nexport interface AiToolsNamespace {\n  /** Search the web via a chosen provider; returns ranked LLM-ready hits. */\n  webSearch(options: WebSearchOptions): ToolContract<WebSearchInput, WebSearchResult>;\n  /** Fetch a URL (host-allowlisted, byte-capped) and return its content. */\n  fetchUrl(options?: FetchUrlOptions): ToolContract<FetchUrlInput, FetchUrlResult>;\n  /** A guarded HTTP/REST client — method + host allowlists, byte/timeout caps. */\n  http(options?: HttpRequestOptions): ToolContract<HttpRequestInput, HttpRequestResult>;\n  /** A SAFE arithmetic-expression evaluator (no `eval`/`Function`). */\n  calculator(options?: CalculatorOptions): ToolContract<CalculatorInput, CalculatorResult>;\n  /** Clock/calendar ops — now / add / diff / format over ISO instants. */\n  dateTime(options?: DateTimeOptions): ToolContract<DateTimeInput, DateTimeResult>;\n}\n\n/**\n * Attach the `tools` namespace and the `mcp` factory to the `ai` namespace\n * via module augmentation, per the `ai.`-namespace convention.\n * `@warlock.js/ai` now exposes a named `Ai` interface for exactly this, so\n * after a bare `import \"@warlock.js/ai-tools\"`, `ai.tools.webSearch(...)`,\n * `ai.tools.http(...)`, `ai.mcp(server)`, and `ai.mcp.serve(source)` are all\n * globally typed — no view/cast needed.\n */\ndeclare module \"@warlock.js/ai\" {\n  interface Ai {\n    /**\n     * Ready-made agent tools from `@warlock.js/ai-tools` — web search,\n     * fetch/scrape, HTTP/REST, calculator, and date-time. Each returns a\n     * `ToolContract` that slots into `ai.agent({ tools: [...] })`.\n     */\n    tools: AiToolsNamespace;\n    /**\n     * The Model Context Protocol surface — `ai.mcp(server)` connects to an\n     * external MCP server and adapts its tools as agent tools (Direction A),\n     * while `ai.mcp.serve(source, options)` exposes a local primitive AS an\n     * MCP server other clients can consume (Direction B).\n     */\n    mcp: McpFactory;\n  }\n}\n\n// Runtime registration: attach `tools` and `mcp` onto the shared `ai`\n// object the moment this module is imported (the augmentation above types\n// them). The `dateTime` factory's optional injectable-clock `deps` is a\n// test/advanced seam, omitted from the agent-facing signature — call\n// `dateTimeTool` directly to use it.\nai.tools = {\n  webSearch: webSearchTool,\n  fetchUrl: fetchUrlTool,\n  http: httpRequestTool,\n  calculator: calculatorTool,\n  dateTime: (options?: DateTimeOptions) => dateTimeTool(options),\n};\n\nai.mcp = mcp;\n"],"mappings":";;;;;;;;;AA6EA,GAAG,QAAQ;CACT,WAAW;CACX,UAAU;CACV,MAAM;CACN,YAAY;CACZ,WAAW,YAA8B,aAAa,OAAO;AAC/D;AAEA,GAAG,MAAM"}

package/esm/schema.mjs

@@ -0,0 +1,127 @@
+//#region ../@warlock.js/ai-tools/src/schema.ts
+/**
+* Tiny, dependency-free [Standard Schema](https://standardschema.dev)
+* builders for the tools' input validation. The package pins only
+* `@warlock.js/ai` as a required runtime peer and keeps every heavy
+* dependency optional, so rather than pull in a schema library we
+* hand-roll the few shapes the tools need — exactly the pattern
+* `@warlock.js/ai`'s own `tool()` tests use. Each builder returns a
+* `StandardSchemaV1`, which is what `tool({ input })` validates against
+* before calling `execute`.
+*
+* These intentionally cover only the primitive cases the bundled tools
+* require (`string`, an optional string drawn from a fixed set, an
+* optional string-to-string record, and an opaque passthrough value),
+* plus an `object` of fields. They are not a general-purpose validator.
+*/
+/** The vendor tag stamped on every issue these builders produce. */
+const VENDOR = "ai-tools";
+/** Required string field — rejects anything that is not a string. */
+function stringField() {
+	return (value, key) => {
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional string field constrained to a fixed set of allowed values.
+* Accepts `undefined` (the property absent or explicitly undefined) or
+* one of `allowed`; rejects any other string and every non-string type.
+* Used for `method` so an out-of-vocabulary verb is a clean validation
+* error rather than reaching the handler.
+*
+* @param allowed - The exhaustive set of permitted string literals.
+*/
+function optionalStringEnumField(allowed) {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "string" && allowed.includes(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be one of: ${allowed.join(", ")}`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional string-to-string record field — accepts `undefined` or a flat
+* object whose every value is a string, and rejects arrays, non-objects,
+* and any record with a non-string value. Used for per-call `headers`.
+*/
+function optionalStringRecordField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{
+			message: `"${key}" must be an object of string values when provided`,
+			path: [key]
+		}] };
+		const source = value;
+		const result = {};
+		for (const recordKey of Object.keys(source)) {
+			const entry = source[recordKey];
+			if (typeof entry !== "string") return { issues: [{
+				message: `"${key}.${recordKey}" must be a string`,
+				path: [key, recordKey]
+			}] };
+			result[recordKey] = entry;
+		}
+		return { value: result };
+	};
+}
+/**
+* Opaque passthrough field — accepts any value (including `undefined`)
+* verbatim, performing no validation. Used for a request `body` whose
+* shape the tool deliberately does not constrain: an object is later
+* JSON-serialized, a string is sent as-is.
+*/
+function passthroughField() {
+	return (value) => ({ value });
+}
+/**
+* Build a {@link StandardSchemaV1} for a flat object whose every property
+* is validated by a {@link FieldValidator}. The input must be a non-null
+* object; each declared field is validated and the (possibly coerced)
+* values are collected into the typed result. All field issues are merged
+* so the caller sees every problem at once.
+*
+* `T` is constrained to `object` rather than `Record<string, unknown>` so
+* the tool IO `interface`s (which carry no implicit string index
+* signature) satisfy it directly — only the declared keys in `shape` are
+* ever read, so a string index signature is never required.
+*
+* @example
+* const schema = objectSchema<{ url: string; method?: HttpMethod }>({
+*   url: stringField(),
+*   method: optionalStringEnumField(["GET", "POST"]),
+* });
+*/
+function objectSchema(shape) {
+	return { "~standard": {
+		version: 1,
+		vendor: VENDOR,
+		validate(input) {
+			if (typeof input !== "object" || input === null || Array.isArray(input)) return { issues: [{ message: "input must be an object" }] };
+			const source = input;
+			const issues = [];
+			const result = {};
+			for (const key of Object.keys(shape)) {
+				const field = shape[key];
+				const present = key in source;
+				const outcome = field(source[key], key);
+				if ("issues" in outcome) {
+					issues.push(...outcome.issues);
+					continue;
+				}
+				if (outcome.value !== void 0 || present) result[key] = outcome.value;
+			}
+			if (issues.length > 0) return { issues };
+			return { value: result };
+		}
+	} };
+}
+
+//#endregion
+export { objectSchema, optionalStringEnumField, optionalStringRecordField, passthroughField, stringField };
+//# sourceMappingURL=schema.mjs.map

package/esm/schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../../../@warlock.js/ai-tools/src/schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Tiny, dependency-free [Standard Schema](https://standardschema.dev)\n * builders for the tools' input validation. The package pins only\n * `@warlock.js/ai` as a required runtime peer and keeps every heavy\n * dependency optional, so rather than pull in a schema library we\n * hand-roll the few shapes the tools need — exactly the pattern\n * `@warlock.js/ai`'s own `tool()` tests use. Each builder returns a\n * `StandardSchemaV1`, which is what `tool({ input })` validates against\n * before calling `execute`.\n *\n * These intentionally cover only the primitive cases the bundled tools\n * require (`string`, an optional string drawn from a fixed set, an\n * optional string-to-string record, and an opaque passthrough value),\n * plus an `object` of fields. They are not a general-purpose validator.\n */\n\n/** The vendor tag stamped on every issue these builders produce. */\nconst VENDOR = \"ai-tools\";\n\n/**\n * A single field validator inside {@link objectSchema}: given a value,\n * return either the coerced value or a list of issues. Field validators\n * receive the raw property and the property name (for issue messages).\n */\nexport type FieldValidator<T> = (\n  value: unknown,\n  key: string,\n) => { value: T } | { issues: StandardSchemaV1.Issue[] };\n\n/** Required string field — rejects anything that is not a string. */\nexport function stringField(): FieldValidator<string> {\n  return (value, key) => {\n    if (typeof value === \"string\") {\n      return { value };\n    }\n\n    return { issues: [{ message: `\"${key}\" must be a string`, path: [key] }] };\n  };\n}\n\n/**\n * Optional string field constrained to a fixed set of allowed values.\n * Accepts `undefined` (the property absent or explicitly undefined) or\n * one of `allowed`; rejects any other string and every non-string type.\n * Used for `method` so an out-of-vocabulary verb is a clean validation\n * error rather than reaching the handler.\n *\n * @param allowed - The exhaustive set of permitted string literals.\n */\nexport function optionalStringEnumField<T extends string>(\n  allowed: readonly T[],\n): FieldValidator<T | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"string\" && (allowed as readonly string[]).includes(value)) {\n      return { value: value as T };\n    }\n\n    return {\n      issues: [\n        {\n          message: `\"${key}\" must be one of: ${allowed.join(\", \")}`,\n          path: [key],\n        },\n      ],\n    };\n  };\n}\n\n/**\n * Optional string-to-string record field — accepts `undefined` or a flat\n * object whose every value is a string, and rejects arrays, non-objects,\n * and any record with a non-string value. Used for per-call `headers`.\n */\nexport function optionalStringRecordField(): FieldValidator<\n  Record<string, string> | undefined\n> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n      return {\n        issues: [\n          { message: `\"${key}\" must be an object of string values when provided`, path: [key] },\n        ],\n      };\n    }\n\n    const source = value as Record<string, unknown>;\n    const result: Record<string, string> = {};\n\n    for (const recordKey of Object.keys(source)) {\n      const entry = source[recordKey];\n\n      if (typeof entry !== \"string\") {\n        return {\n          issues: [\n            {\n              message: `\"${key}.${recordKey}\" must be a string`,\n              path: [key, recordKey],\n            },\n          ],\n        };\n      }\n\n      result[recordKey] = entry;\n    }\n\n    return { value: result };\n  };\n}\n\n/**\n * Opaque passthrough field — accepts any value (including `undefined`)\n * verbatim, performing no validation. Used for a request `body` whose\n * shape the tool deliberately does not constrain: an object is later\n * JSON-serialized, a string is sent as-is.\n */\nexport function passthroughField(): FieldValidator<unknown> {\n  return (value) => ({ value });\n}\n\n/** The per-key field validator map describing an object schema's shape. */\ntype ObjectShape<T> = {\n  [K in keyof T]-?: FieldValidator<T[K]>;\n};\n\n/**\n * Build a {@link StandardSchemaV1} for a flat object whose every property\n * is validated by a {@link FieldValidator}. The input must be a non-null\n * object; each declared field is validated and the (possibly coerced)\n * values are collected into the typed result. All field issues are merged\n * so the caller sees every problem at once.\n *\n * `T` is constrained to `object` rather than `Record<string, unknown>` so\n * the tool IO `interface`s (which carry no implicit string index\n * signature) satisfy it directly — only the declared keys in `shape` are\n * ever read, so a string index signature is never required.\n *\n * @example\n * const schema = objectSchema<{ url: string; method?: HttpMethod }>({\n *   url: stringField(),\n *   method: optionalStringEnumField([\"GET\", \"POST\"]),\n * });\n */\nexport function objectSchema<T extends object>(\n  shape: ObjectShape<T>,\n): StandardSchemaV1<T> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      validate(input) {\n        if (typeof input !== \"object\" || input === null || Array.isArray(input)) {\n          return { issues: [{ message: \"input must be an object\" }] };\n        }\n\n        const source = input as Record<string, unknown>;\n        const issues: StandardSchemaV1.Issue[] = [];\n        const result: Record<string, unknown> = {};\n\n        for (const key of Object.keys(shape) as (keyof T)[]) {\n          const field = shape[key];\n          const present = (key as string) in source;\n          const outcome = field(source[key as string], key as string);\n\n          if (\"issues\" in outcome) {\n            issues.push(...outcome.issues);\n\n            continue;\n          }\n\n          // Carry through any key that resolved to a defined value. A\n          // passthrough field can legitimately resolve to `undefined`\n          // even when the property was present (e.g. an explicit\n          // `body: undefined`); only suppress keys that were absent so\n          // optional-absent fields stay absent.\n          if (outcome.value !== undefined || present) {\n            result[key as string] = outcome.value;\n          }\n        }\n\n        if (issues.length > 0) {\n          return { issues };\n        }\n\n        return { value: result as T };\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAmBA,MAAM,SAAS;;AAaf,SAAgB,cAAsC;CACpD,QAAQ,OAAO,QAAQ;EACrB,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAqB,MAAM,CAAC,GAAG;EAAE,CAAC,EAAE;CAC3E;AACF;;;;;;;;;;AAWA,SAAgB,wBACd,SAC+B;CAC/B,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,YAAa,QAA8B,SAAS,KAAK,GAC5E,OAAO,EAAS,MAAW;EAG7B,OAAO,EACL,QAAQ,CACN;GACE,SAAS,IAAI,IAAI,oBAAoB,QAAQ,KAAK,IAAI;GACtD,MAAM,CAAC,GAAG;EACZ,CACF,EACF;CACF;AACF;;;;;;AAOA,SAAgB,4BAEd;CACA,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO,EACL,QAAQ,CACN;GAAE,SAAS,IAAI,IAAI;GAAqD,MAAM,CAAC,GAAG;EAAE,CACtF,EACF;EAGF,MAAM,SAAS;EACf,MAAM,SAAiC,CAAC;EAExC,KAAK,MAAM,aAAa,OAAO,KAAK,MAAM,GAAG;GAC3C,MAAM,QAAQ,OAAO;GAErB,IAAI,OAAO,UAAU,UACnB,OAAO,EACL,QAAQ,CACN;IACE,SAAS,IAAI,IAAI,GAAG,UAAU;IAC9B,MAAM,CAAC,KAAK,SAAS;GACvB,CACF,EACF;GAGF,OAAO,aAAa;EACtB;EAEA,OAAO,EAAE,OAAO,OAAO;CACzB;AACF;;;;;;;AAQA,SAAgB,mBAA4C;CAC1D,QAAQ,WAAW,EAAE,MAAM;AAC7B;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,aACd,OACqB;CACrB,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,SAAS,OAAO;GACd,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,0BAA0B,CAAC,EAAE;GAG5D,MAAM,SAAS;GACf,MAAM,SAAmC,CAAC;GAC1C,MAAM,SAAkC,CAAC;GAEzC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GAAkB;IACnD,MAAM,QAAQ,MAAM;IACpB,MAAM,UAAW,OAAkB;IACnC,MAAM,UAAU,MAAM,OAAO,MAAgB,GAAa;IAE1D,IAAI,YAAY,SAAS;KACvB,OAAO,KAAK,GAAG,QAAQ,MAAM;KAE7B;IACF;IAOA,IAAI,QAAQ,UAAU,UAAa,SACjC,OAAO,OAAiB,QAAQ;GAEpC;GAEA,IAAI,OAAO,SAAS,GAClB,OAAO,EAAE,OAAO;GAGlB,OAAO,EAAE,OAAO,OAAY;EAC9B;CACF,EACF;AACF"}

package/esm/utility/calculator.d.mts

@@ -0,0 +1,35 @@
+import { CalculatorInput, CalculatorOptions, CalculatorResult } from "../contracts/utility.type.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/utility/calculator.d.ts
+/**
+ * Build the `calculator` tool — a SAFE arithmetic evaluator the agent can
+ * call to compute a numeric expression. It supports `+ - * / % ^`, unary
+ * signs, parentheses, and decimal/scientific-notation literals, with the
+ * usual precedence (`^` highest and right-associative, then `* / %`, then
+ * `+ -`).
+ *
+ * **Safety.** The expression is tokenized and evaluated with a
+ * shunting-yard pass — it NEVER calls `eval` or `new Function`. The
+ * lexer only recognizes numbers, parentheses, and the fixed operator set,
+ * so there is no path to an identifier, function call, or property
+ * access; any other character is a syntax error returned as data.
+ *
+ * **Errors flow as data.** A malformed expression, division/modulo by
+ * zero, or a non-finite result throws a {@link CalculatorError} inside
+ * the handler; `tool()` catches it and surfaces it in the returned
+ * `{ error }` field (the LLM-visible message is preserved), so the agent
+ * reads the failure and self-corrects instead of crashing.
+ *
+ * @param options - Optional overrides; `name` renames the LLM-visible tool.
+ * @returns A `ToolContract<{ expression }, { result }>` ready to drop into `tools: []`.
+ *
+ * @example
+ * const calc = calculatorTool();
+ * const { data } = await calc.invoke({ expression: "(3 + 4) * 2" });
+ * console.log(data?.result); // 14
+ */
+declare function calculatorTool(options?: CalculatorOptions): ToolContract<CalculatorInput, CalculatorResult>;
+//#endregion
+export { calculatorTool };
+//# sourceMappingURL=calculator.d.mts.map

package/esm/utility/calculator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/utility/calculator.ts"],"mappings":";;;;;;AAiZA;;;;;;;;;;;;;;;AAEiD;;;;;;;;;;iBAFjC,cAAA,CACd,OAAA,GAAU,iBAAA,GACT,YAAA,CAAa,eAAA,EAAiB,gBAAA"}

package/esm/utility/calculator.mjs

@@ -0,0 +1,272 @@
+import { CalculatorError } from "../errors.mjs";
+import { objectSchema, stringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/utility/calculator.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "calculator";
+/** Input schema for the `calculator` tool: a single `expression` string. */
+const inputSchema = objectSchema({ expression: stringField() });
+/** The closed set of supported binary operators. */
+const OPERATORS = {
+	"+": {
+		precedence: 1,
+		associativity: "left",
+		apply: (a, b) => a + b
+	},
+	"-": {
+		precedence: 1,
+		associativity: "left",
+		apply: (a, b) => a - b
+	},
+	"*": {
+		precedence: 2,
+		associativity: "left",
+		apply: (a, b) => a * b
+	},
+	"/": {
+		precedence: 2,
+		associativity: "left",
+		apply: (a, b) => {
+			if (b === 0) throw new CalculatorError("Division by zero.", { type: "divide-by-zero" });
+			return a / b;
+		}
+	},
+	"%": {
+		precedence: 2,
+		associativity: "left",
+		apply: (a, b) => {
+			if (b === 0) throw new CalculatorError("Modulo by zero.", { type: "divide-by-zero" });
+			return a % b;
+		}
+	},
+	"^": {
+		precedence: 3,
+		associativity: "right",
+		apply: (a, b) => a ** b
+	}
+};
+/**
+* Tokenize an arithmetic expression into {@link Token}s. Recognizes
+* decimal and scientific-notation numbers (`3`, `4.5`, `1e3`, `2.5E-2`),
+* the operators in {@link OPERATORS}, and parentheses; whitespace is
+* skipped. Any other character is a syntax error — there is no path to
+* an identifier, function call, or property access, so nothing
+* code-like can be smuggled in.
+*
+* @throws CalculatorError `type: "syntax"` on an unrecognized character
+*   or a malformed number.
+*/
+function tokenize(expression) {
+	const tokens = [];
+	let index = 0;
+	while (index < expression.length) {
+		const char = expression[index];
+		if (char === " " || char === "	" || char === "\n" || char === "\r") {
+			index += 1;
+			continue;
+		}
+		if (char === "(" || char === ")") {
+			tokens.push({
+				type: "paren",
+				value: char
+			});
+			index += 1;
+			continue;
+		}
+		if (char in OPERATORS) {
+			tokens.push({
+				type: "operator",
+				value: char
+			});
+			index += 1;
+			continue;
+		}
+		if (isDigit(char) || char === ".") {
+			const { value, nextIndex } = readNumber(expression, index);
+			tokens.push({
+				type: "number",
+				value
+			});
+			index = nextIndex;
+			continue;
+		}
+		throw new CalculatorError(`Unexpected character "${char}" at position ${index}. Only numbers, parentheses, and the operators + - * / % ^ are allowed.`, { type: "syntax" });
+	}
+	return tokens;
+}
+/** True for an ASCII digit `0`–`9`. */
+function isDigit(char) {
+	return char >= "0" && char <= "9";
+}
+/**
+* Read a single number literal starting at `start`. Consumes an optional
+* integer part, optional fraction, and optional exponent
+* (`e`/`E` with an optional sign). Returns the parsed value and the index
+* just past the literal.
+*
+* @throws CalculatorError `type: "syntax"` if the consumed run is not a
+*   valid finite number (e.g. a lone `.` or `1e` with no exponent).
+*/
+function readNumber(expression, start) {
+	let index = start;
+	while (index < expression.length && isDigit(expression[index])) index += 1;
+	if (expression[index] === ".") {
+		index += 1;
+		while (index < expression.length && isDigit(expression[index])) index += 1;
+	}
+	if (expression[index] === "e" || expression[index] === "E") {
+		index += 1;
+		if (expression[index] === "+" || expression[index] === "-") index += 1;
+		while (index < expression.length && isDigit(expression[index])) index += 1;
+	}
+	const literal = expression.slice(start, index);
+	const value = Number(literal);
+	if (!Number.isFinite(value)) throw new CalculatorError(`Invalid number literal "${literal}".`, { type: "syntax" });
+	return {
+		value,
+		nextIndex: index
+	};
+}
+/**
+* Evaluate a token stream with a single left-to-right pass that resolves
+* unary signs, then a shunting-yard conversion that interleaves operator
+* application — so the result is produced without ever building an AST or
+* calling `eval`/`Function`.
+*
+* Unary `+`/`-` are detected positionally: a `+`/`-` is unary when it
+* starts the expression or directly follows another operator or an
+* opening paren. A unary `-` folds into the following number literal
+* (and a unary `+` is a no-op), which keeps the operator stack purely
+* binary.
+*
+* @throws CalculatorError on malformed structure (`type: "syntax"`),
+*   division/modulo by zero (`type: "divide-by-zero"`), or a non-finite
+*   result (`type: "overflow"`).
+*/
+function evaluate(tokens) {
+	const values = [];
+	const operators = [];
+	/** Pop the top operator and apply it to the top two values. */
+	const applyTop = () => {
+		const operator = operators.pop();
+		if (operator === void 0) throw new CalculatorError("Malformed expression.", { type: "syntax" });
+		const right = values.pop();
+		const left = values.pop();
+		if (left === void 0 || right === void 0) throw new CalculatorError(`Operator "${operator}" is missing an operand.`, { type: "syntax" });
+		values.push(OPERATORS[operator].apply(left, right));
+	};
+	let expectOperand = true;
+	let pendingSign = 1;
+	for (let i = 0; i < tokens.length; i += 1) {
+		const token = tokens[i];
+		if (token.type === "number") {
+			if (!expectOperand) throw new CalculatorError("Unexpected number — a number cannot directly follow another value.", { type: "syntax" });
+			values.push(pendingSign * token.value);
+			pendingSign = 1;
+			expectOperand = false;
+			continue;
+		}
+		if (token.type === "paren") {
+			if (token.value === "(") {
+				if (!expectOperand) throw new CalculatorError("Unexpected \"(\" — it cannot directly follow a value.", { type: "syntax" });
+				if (pendingSign === -1) {
+					values.push(-1);
+					operators.push("*");
+					pendingSign = 1;
+				}
+				operators.push("(");
+				expectOperand = true;
+				continue;
+			}
+			if (expectOperand) throw new CalculatorError("Unexpected \")\" — an operand was expected.", { type: "syntax" });
+			let foundOpen = false;
+			while (operators.length > 0) {
+				if (operators[operators.length - 1] === "(") {
+					operators.pop();
+					foundOpen = true;
+					break;
+				}
+				applyTop();
+			}
+			if (!foundOpen) throw new CalculatorError("Unbalanced parentheses.", { type: "syntax" });
+			expectOperand = false;
+			continue;
+		}
+		if (expectOperand) {
+			if (token.value === "-") {
+				pendingSign = -pendingSign;
+				continue;
+			}
+			if (token.value === "+") continue;
+			throw new CalculatorError(`Operator "${token.value}" has no left-hand operand.`, { type: "syntax" });
+		}
+		const incoming = OPERATORS[token.value];
+		while (operators.length > 0) {
+			const top = operators[operators.length - 1];
+			if (top === "(") break;
+			const topSpec = OPERATORS[top];
+			const higher = topSpec.precedence > incoming.precedence;
+			const equalLeft = topSpec.precedence === incoming.precedence && incoming.associativity === "left";
+			if (higher || equalLeft) {
+				applyTop();
+				continue;
+			}
+			break;
+		}
+		operators.push(token.value);
+		expectOperand = true;
+	}
+	if (expectOperand) throw new CalculatorError("Expression ends with an operator or is empty.", { type: "syntax" });
+	while (operators.length > 0) {
+		if (operators[operators.length - 1] === "(") throw new CalculatorError("Unbalanced parentheses.", { type: "syntax" });
+		applyTop();
+	}
+	const result = values.pop();
+	if (result === void 0 || values.length > 0) throw new CalculatorError("Malformed expression.", { type: "syntax" });
+	if (!Number.isFinite(result)) throw new CalculatorError("Result is not a finite number.", { type: "overflow" });
+	return result;
+}
+/**
+* Build the `calculator` tool — a SAFE arithmetic evaluator the agent can
+* call to compute a numeric expression. It supports `+ - * / % ^`, unary
+* signs, parentheses, and decimal/scientific-notation literals, with the
+* usual precedence (`^` highest and right-associative, then `* / %`, then
+* `+ -`).
+*
+* **Safety.** The expression is tokenized and evaluated with a
+* shunting-yard pass — it NEVER calls `eval` or `new Function`. The
+* lexer only recognizes numbers, parentheses, and the fixed operator set,
+* so there is no path to an identifier, function call, or property
+* access; any other character is a syntax error returned as data.
+*
+* **Errors flow as data.** A malformed expression, division/modulo by
+* zero, or a non-finite result throws a {@link CalculatorError} inside
+* the handler; `tool()` catches it and surfaces it in the returned
+* `{ error }` field (the LLM-visible message is preserved), so the agent
+* reads the failure and self-corrects instead of crashing.
+*
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+* @returns A `ToolContract<{ expression }, { result }>` ready to drop into `tools: []`.
+*
+* @example
+* const calc = calculatorTool();
+* const { data } = await calc.invoke({ expression: "(3 + 4) * 2" });
+* console.log(data?.result); // 14
+*/
+function calculatorTool(options) {
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Evaluate an arithmetic expression and return the numeric result. Supports + - * / % ^, parentheses, unary +/-, and decimal or scientific-notation numbers. Does not support variables or functions — pass a literal expression like \"(3 + 4) * 2\".",
+		input: inputSchema,
+		async execute(input) {
+			const tokens = tokenize(input.expression);
+			if (tokens.length === 0) throw new CalculatorError("Expression is empty.", { type: "syntax" });
+			return { result: evaluate(tokens) };
+		}
+	});
+}
+
+//#endregion
+export { calculatorTool };
+//# sourceMappingURL=calculator.mjs.map

package/esm/utility/calculator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculator.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/utility/calculator.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { CalculatorError } from \"../errors\";\nimport { objectSchema, stringField } from \"./schema\";\nimport type {\n  CalculatorInput,\n  CalculatorOptions,\n  CalculatorResult,\n} from \"../contracts/utility.type\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"calculator\";\n\n/** Input schema for the `calculator` tool: a single `expression` string. */\nconst inputSchema = objectSchema<CalculatorInput>({\n  expression: stringField(),\n});\n\n/**\n * A binary operator the evaluator understands, with its precedence and\n * associativity. Higher `precedence` binds tighter; `^` is the only\n * right-associative operator (so `2 ^ 3 ^ 2` is `2 ^ (3 ^ 2)`).\n */\ninterface OperatorSpec {\n  precedence: number;\n  associativity: \"left\" | \"right\";\n  /** Apply the operator to its two operands. May throw {@link CalculatorError}. */\n  apply(left: number, right: number): number;\n}\n\n/** The closed set of supported binary operators. */\nconst OPERATORS: Record<string, OperatorSpec> = {\n  \"+\": { precedence: 1, associativity: \"left\", apply: (a, b) => a + b },\n  \"-\": { precedence: 1, associativity: \"left\", apply: (a, b) => a - b },\n  \"*\": { precedence: 2, associativity: \"left\", apply: (a, b) => a * b },\n  \"/\": {\n    precedence: 2,\n    associativity: \"left\",\n    apply: (a, b) => {\n      if (b === 0) {\n        throw new CalculatorError(\"Division by zero.\", { type: \"divide-by-zero\" });\n      }\n\n      return a / b;\n    },\n  },\n  \"%\": {\n    precedence: 2,\n    associativity: \"left\",\n    apply: (a, b) => {\n      if (b === 0) {\n        throw new CalculatorError(\"Modulo by zero.\", { type: \"divide-by-zero\" });\n      }\n\n      return a % b;\n    },\n  },\n  \"^\": { precedence: 3, associativity: \"right\", apply: (a, b) => a ** b },\n};\n\n/** A lexed token: a number literal, an operator, or a parenthesis. */\ntype Token =\n  | { type: \"number\"; value: number }\n  | { type: \"operator\"; value: string }\n  | { type: \"paren\"; value: \"(\" | \")\" };\n\n/**\n * Tokenize an arithmetic expression into {@link Token}s. Recognizes\n * decimal and scientific-notation numbers (`3`, `4.5`, `1e3`, `2.5E-2`),\n * the operators in {@link OPERATORS}, and parentheses; whitespace is\n * skipped. Any other character is a syntax error — there is no path to\n * an identifier, function call, or property access, so nothing\n * code-like can be smuggled in.\n *\n * @throws CalculatorError `type: \"syntax\"` on an unrecognized character\n *   or a malformed number.\n */\nfunction tokenize(expression: string): Token[] {\n  const tokens: Token[] = [];\n  let index = 0;\n\n  while (index < expression.length) {\n    const char = expression[index];\n\n    if (char === \" \" || char === \"\\t\" || char === \"\\n\" || char === \"\\r\") {\n      index += 1;\n\n      continue;\n    }\n\n    if (char === \"(\" || char === \")\") {\n      tokens.push({ type: \"paren\", value: char });\n      index += 1;\n\n      continue;\n    }\n\n    if (char in OPERATORS) {\n      tokens.push({ type: \"operator\", value: char });\n      index += 1;\n\n      continue;\n    }\n\n    if (isDigit(char) || char === \".\") {\n      const { value, nextIndex } = readNumber(expression, index);\n      tokens.push({ type: \"number\", value });\n      index = nextIndex;\n\n      continue;\n    }\n\n    throw new CalculatorError(\n      `Unexpected character \"${char}\" at position ${index}. Only numbers, parentheses, and the operators + - * / % ^ are allowed.`,\n      { type: \"syntax\" },\n    );\n  }\n\n  return tokens;\n}\n\n/** True for an ASCII digit `0`–`9`. */\nfunction isDigit(char: string): boolean {\n  return char >= \"0\" && char <= \"9\";\n}\n\n/**\n * Read a single number literal starting at `start`. Consumes an optional\n * integer part, optional fraction, and optional exponent\n * (`e`/`E` with an optional sign). Returns the parsed value and the index\n * just past the literal.\n *\n * @throws CalculatorError `type: \"syntax\"` if the consumed run is not a\n *   valid finite number (e.g. a lone `.` or `1e` with no exponent).\n */\nfunction readNumber(\n  expression: string,\n  start: number,\n): { value: number; nextIndex: number } {\n  let index = start;\n\n  while (index < expression.length && isDigit(expression[index])) {\n    index += 1;\n  }\n\n  if (expression[index] === \".\") {\n    index += 1;\n\n    while (index < expression.length && isDigit(expression[index])) {\n      index += 1;\n    }\n  }\n\n  if (expression[index] === \"e\" || expression[index] === \"E\") {\n    index += 1;\n\n    if (expression[index] === \"+\" || expression[index] === \"-\") {\n      index += 1;\n    }\n\n    while (index < expression.length && isDigit(expression[index])) {\n      index += 1;\n    }\n  }\n\n  const literal = expression.slice(start, index);\n  const value = Number(literal);\n\n  if (!Number.isFinite(value)) {\n    throw new CalculatorError(`Invalid number literal \"${literal}\".`, {\n      type: \"syntax\",\n    });\n  }\n\n  return { value, nextIndex: index };\n}\n\n/**\n * Evaluate a token stream with a single left-to-right pass that resolves\n * unary signs, then a shunting-yard conversion that interleaves operator\n * application — so the result is produced without ever building an AST or\n * calling `eval`/`Function`.\n *\n * Unary `+`/`-` are detected positionally: a `+`/`-` is unary when it\n * starts the expression or directly follows another operator or an\n * opening paren. A unary `-` folds into the following number literal\n * (and a unary `+` is a no-op), which keeps the operator stack purely\n * binary.\n *\n * @throws CalculatorError on malformed structure (`type: \"syntax\"`),\n *   division/modulo by zero (`type: \"divide-by-zero\"`), or a non-finite\n *   result (`type: \"overflow\"`).\n */\nfunction evaluate(tokens: Token[]): number {\n  const values: number[] = [];\n  const operators: string[] = [];\n\n  /** Pop the top operator and apply it to the top two values. */\n  const applyTop = (): void => {\n    const operator = operators.pop();\n\n    if (operator === undefined) {\n      throw new CalculatorError(\"Malformed expression.\", { type: \"syntax\" });\n    }\n\n    const right = values.pop();\n    const left = values.pop();\n\n    if (left === undefined || right === undefined) {\n      throw new CalculatorError(\n        `Operator \"${operator}\" is missing an operand.`,\n        { type: \"syntax\" },\n      );\n    }\n\n    values.push(OPERATORS[operator].apply(left, right));\n  };\n\n  // `expectOperand` tracks the positional state machine: at the start, and\n  // immediately after an operator or \"(\", we expect an operand (a number,\n  // a \"(\", or a unary sign). After a number or \")\", we expect a binary\n  // operator or \")\".\n  let expectOperand = true;\n  // Pending unary sign multiplier folded into the next numeric operand.\n  let pendingSign = 1;\n\n  for (let i = 0; i < tokens.length; i += 1) {\n    const token = tokens[i];\n\n    if (token.type === \"number\") {\n      if (!expectOperand) {\n        throw new CalculatorError(\n          \"Unexpected number — a number cannot directly follow another value.\",\n          { type: \"syntax\" },\n        );\n      }\n\n      values.push(pendingSign * token.value);\n      pendingSign = 1;\n      expectOperand = false;\n\n      continue;\n    }\n\n    if (token.type === \"paren\") {\n      if (token.value === \"(\") {\n        if (!expectOperand) {\n          throw new CalculatorError(\n            'Unexpected \"(\" — it cannot directly follow a value.',\n            { type: \"syntax\" },\n          );\n        }\n\n        // A unary sign in front of a parenthesized group is modeled by\n        // pushing the sign as a multiplication: `-(…)` becomes `-1 * (…)`.\n        if (pendingSign === -1) {\n          values.push(-1);\n          operators.push(\"*\");\n          pendingSign = 1;\n        }\n\n        operators.push(\"(\");\n        expectOperand = true;\n\n        continue;\n      }\n\n      // token.value === \")\"\n      if (expectOperand) {\n        throw new CalculatorError(\n          'Unexpected \")\" — an operand was expected.',\n          { type: \"syntax\" },\n        );\n      }\n\n      let foundOpen = false;\n\n      while (operators.length > 0) {\n        if (operators[operators.length - 1] === \"(\") {\n          operators.pop();\n          foundOpen = true;\n\n          break;\n        }\n\n        applyTop();\n      }\n\n      if (!foundOpen) {\n        throw new CalculatorError(\"Unbalanced parentheses.\", { type: \"syntax\" });\n      }\n\n      expectOperand = false;\n\n      continue;\n    }\n\n    // token.type === \"operator\"\n    if (expectOperand) {\n      // A `+`/`-` in operand position is a unary sign; anything else is a\n      // misplaced binary operator.\n      if (token.value === \"-\") {\n        pendingSign = -pendingSign;\n\n        continue;\n      }\n\n      if (token.value === \"+\") {\n        continue;\n      }\n\n      throw new CalculatorError(\n        `Operator \"${token.value}\" has no left-hand operand.`,\n        { type: \"syntax\" },\n      );\n    }\n\n    const incoming = OPERATORS[token.value];\n\n    while (operators.length > 0) {\n      const top = operators[operators.length - 1];\n\n      if (top === \"(\") {\n        break;\n      }\n\n      const topSpec = OPERATORS[top];\n      const higher = topSpec.precedence > incoming.precedence;\n      const equalLeft =\n        topSpec.precedence === incoming.precedence &&\n        incoming.associativity === \"left\";\n\n      if (higher || equalLeft) {\n        applyTop();\n\n        continue;\n      }\n\n      break;\n    }\n\n    operators.push(token.value);\n    expectOperand = true;\n  }\n\n  if (expectOperand) {\n    throw new CalculatorError(\n      \"Expression ends with an operator or is empty.\",\n      { type: \"syntax\" },\n    );\n  }\n\n  while (operators.length > 0) {\n    if (operators[operators.length - 1] === \"(\") {\n      throw new CalculatorError(\"Unbalanced parentheses.\", { type: \"syntax\" });\n    }\n\n    applyTop();\n  }\n\n  const result = values.pop();\n\n  if (result === undefined || values.length > 0) {\n    throw new CalculatorError(\"Malformed expression.\", { type: \"syntax\" });\n  }\n\n  if (!Number.isFinite(result)) {\n    throw new CalculatorError(\"Result is not a finite number.\", {\n      type: \"overflow\",\n    });\n  }\n\n  return result;\n}\n\n/**\n * Build the `calculator` tool — a SAFE arithmetic evaluator the agent can\n * call to compute a numeric expression. It supports `+ - * / % ^`, unary\n * signs, parentheses, and decimal/scientific-notation literals, with the\n * usual precedence (`^` highest and right-associative, then `* / %`, then\n * `+ -`).\n *\n * **Safety.** The expression is tokenized and evaluated with a\n * shunting-yard pass — it NEVER calls `eval` or `new Function`. The\n * lexer only recognizes numbers, parentheses, and the fixed operator set,\n * so there is no path to an identifier, function call, or property\n * access; any other character is a syntax error returned as data.\n *\n * **Errors flow as data.** A malformed expression, division/modulo by\n * zero, or a non-finite result throws a {@link CalculatorError} inside\n * the handler; `tool()` catches it and surfaces it in the returned\n * `{ error }` field (the LLM-visible message is preserved), so the agent\n * reads the failure and self-corrects instead of crashing.\n *\n * @param options - Optional overrides; `name` renames the LLM-visible tool.\n * @returns A `ToolContract<{ expression }, { result }>` ready to drop into `tools: []`.\n *\n * @example\n * const calc = calculatorTool();\n * const { data } = await calc.invoke({ expression: \"(3 + 4) * 2\" });\n * console.log(data?.result); // 14\n */\nexport function calculatorTool(\n  options?: CalculatorOptions,\n): ToolContract<CalculatorInput, CalculatorResult> {\n  return tool<CalculatorInput, CalculatorResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Evaluate an arithmetic expression and return the numeric result. \" +\n      \"Supports + - * / % ^, parentheses, unary +/-, and decimal or \" +\n      \"scientific-notation numbers. Does not support variables or \" +\n      \"functions — pass a literal expression like \\\"(3 + 4) * 2\\\".\",\n    input: inputSchema,\n    async execute(input) {\n      const tokens = tokenize(input.expression);\n\n      if (tokens.length === 0) {\n        throw new CalculatorError(\"Expression is empty.\", { type: \"syntax\" });\n      }\n\n      return { result: evaluate(tokens) };\n    },\n  });\n}\n"],"mappings":"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"}

package/esm/utility/date-time.d.mts

@@ -0,0 +1,57 @@
+import { DateTimeInput, DateTimeOptions, DateTimeResult } from "../contracts/utility.type.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/utility/date-time.d.ts
+/**
+ * A clock seam so tests are deterministic. Defaults to the real
+ * {@link Date}; a test injects a fixed instant. Returns milliseconds
+ * since the Unix epoch — the same contract as `Date.now()`.
+ */
+type Clock = () => number;
+/** Construction dependencies for {@link dateTimeTool}, all optional. */
+interface DateTimeToolDeps {
+  /**
+   * The clock used by the `now` op. Defaults to `Date.now`. Injected in
+   * tests for deterministic output.
+   */
+  clock?: Clock;
+}
+/**
+ * Build the `date_time` tool — a small clock/calendar utility the agent
+ * can call to read the current instant, shift an instant, measure the
+ * gap between two instants, or render one. The `op` discriminator selects
+ * the operation:
+ *
+ * - **`now`** — the current instant, rendered per `format` / `timeZone`
+ *   (defaults to a UTC ISO string). Reads the injectable {@link Clock}.
+ * - **`add`** — `iso` shifted by `amount` of `unit` (e.g.
+ *   `+3 days`); a negative `amount` shifts backward.
+ * - **`diff`** — the signed difference `to − iso`, expressed in `unit`.
+ * - **`format`** — `iso` rendered per `format` / `timeZone`.
+ *
+ * Units are millisecond-based (`milliseconds`…`weeks`, plus common
+ * aliases); calendar-relative `month`/`year` are intentionally
+ * unsupported because they have no fixed length.
+ *
+ * **Deterministic in tests.** The clock backing `now` is injectable via
+ * `deps.clock`; production defaults to `Date.now`.
+ *
+ * **Errors flow as data.** A missing/invalid field, an unknown unit, or
+ * an unrecognized time zone throws a {@link DateTimeError} inside the
+ * handler; `tool()` surfaces it in `{ error }` so the agent self-corrects.
+ *
+ * @param options - Optional overrides; `name` renames the tool,
+ *   `defaultTimeZone` applies when a call omits `timeZone`.
+ * @param deps - Injectable dependencies (the {@link Clock}); defaults to real time.
+ * @returns A `ToolContract<DateTimeInput, { value }>` ready for `tools: []`.
+ *
+ * @example
+ * const clock = () => Date.parse("2026-06-22T00:00:00Z");
+ * const dt = dateTimeTool({}, { clock });
+ * const { data } = await dt.invoke({ op: "now" });
+ * console.log(data?.value); // "2026-06-22T00:00:00.000Z"
+ */
+declare function dateTimeTool(options?: DateTimeOptions, deps?: DateTimeToolDeps): ToolContract<DateTimeInput, DateTimeResult>;
+//#endregion
+export { Clock, DateTimeToolDeps, dateTimeTool };
+//# sourceMappingURL=date-time.d.mts.map

package/esm/utility/date-time.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-time.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/utility/date-time.ts"],"mappings":";;;;;;AAqBA;;;KAAY,KAAA;AAAK;AAAA,UAGA,gBAAA;EAAgB;;;AAKlB;EAAb,KAAA,GAAQ,KAAK;AAAA;;;;;;;;;;;;;;;;;AAqL8B;;;;;;;;;;;;;;;;;;;iBAH7B,YAAA,CACd,OAAA,GAAU,eAAA,EACV,IAAA,GAAO,gBAAA,GACN,YAAA,CAAa,aAAA,EAAe,cAAA"}