@warlock.js/ai-tools 4.5.0

package/esm/utility/date-time.mjs

@@ -0,0 +1,193 @@
+import { DateTimeError } from "../errors.mjs";
+import { literalField, objectSchema, optionalNumberField, optionalStringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/utility/date-time.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "date_time";
+/** Input schema for the `date_time` tool. */
+const inputSchema = objectSchema({
+	op: literalField([
+		"now",
+		"add",
+		"diff",
+		"format"
+	]),
+	iso: optionalStringField(),
+	from: optionalStringField(),
+	to: optionalStringField(),
+	amount: optionalNumberField(),
+	unit: optionalStringField(),
+	timeZone: optionalStringField(),
+	format: optionalStringField()
+});
+/**
+* The time units `add` and `diff` understand, each as its length in
+* milliseconds. Calendar-unaware on purpose: a "month" / "year" has no
+* fixed millisecond length, so they are deliberately excluded — adding
+* `30 days` is unambiguous in a way adding `1 month` is not.
+*/
+const UNIT_MS = {
+	milliseconds: 1,
+	seconds: 1e3,
+	minutes: 6e4,
+	hours: 36e5,
+	days: 864e5,
+	weeks: 6048e5
+};
+/** Singular aliases mapped to their canonical plural unit key. */
+const UNIT_ALIASES = {
+	millisecond: "milliseconds",
+	ms: "milliseconds",
+	second: "seconds",
+	sec: "seconds",
+	s: "seconds",
+	minute: "minutes",
+	min: "minutes",
+	m: "minutes",
+	hour: "hours",
+	hr: "hours",
+	h: "hours",
+	day: "days",
+	d: "days",
+	week: "weeks",
+	w: "weeks"
+};
+/** Resolve a (possibly aliased / singular) unit token to its ms length. */
+function unitToMs(unit) {
+	const ms = UNIT_MS[UNIT_ALIASES[unit] ?? unit];
+	if (ms === void 0) throw new DateTimeError(`Unknown unit "${unit}". Supported units: ${Object.keys(UNIT_MS).join(", ")}.`, { type: "invalid-unit" });
+	return ms;
+}
+/**
+* Parse an ISO-8601 instant into a {@link Date}, or throw a typed
+* {@link DateTimeError} when the string is missing or unparseable.
+*
+* @param iso - The ISO string from the model (may be undefined).
+* @param field - The input field name, for the error message.
+*/
+function parseIso(iso, field) {
+	if (iso === void 0) throw new DateTimeError(`"${field}" is required for this operation.`, { type: "invalid-input" });
+	const date = new Date(iso);
+	if (Number.isNaN(date.getTime())) throw new DateTimeError(`"${field}" is not a valid ISO-8601 instant: "${iso}".`, { type: "invalid-input" });
+	return date;
+}
+/**
+* Render a {@link Date} in a target time zone using `Intl`. The
+* `"iso"` format (the default) returns the instant's UTC ISO string;
+* any other `format` value is treated as an `Intl.DateTimeFormat`
+* locale-style rendering in the given `timeZone`.
+*
+* @throws DateTimeError `type: "invalid-time-zone"` when `timeZone` is
+*   not a recognized IANA zone.
+*/
+function render(date, format, timeZone) {
+	if (format === void 0 || format === "iso") {
+		if (timeZone !== void 0) assertTimeZone(timeZone);
+		return date.toISOString();
+	}
+	try {
+		return new Intl.DateTimeFormat("en-US", {
+			timeZone,
+			dateStyle: format === "date" ? "medium" : void 0,
+			timeStyle: format === "time" ? "medium" : void 0,
+			...format === "datetime" ? {
+				dateStyle: "medium",
+				timeStyle: "medium"
+			} : {}
+		}).format(date);
+	} catch (error) {
+		throw new DateTimeError(`Could not render with format "${format}"${timeZone ? ` in time zone "${timeZone}"` : ""}.`, {
+			type: "invalid-time-zone",
+			cause: error
+		});
+	}
+}
+/**
+* Validate an IANA time zone by attempting to construct a formatter for
+* it; an unrecognized zone makes `Intl` throw a `RangeError`.
+*
+* @throws DateTimeError `type: "invalid-time-zone"` for an unknown zone.
+*/
+function assertTimeZone(timeZone) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone });
+	} catch (error) {
+		throw new DateTimeError(`Unknown time zone "${timeZone}".`, {
+			type: "invalid-time-zone",
+			cause: error
+		});
+	}
+}
+/**
+* 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"
+*/
+function dateTimeTool(options, deps) {
+	const clock = deps?.clock ?? Date.now;
+	const defaultTimeZone = options?.defaultTimeZone;
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Work with dates and times. Set op to: \"now\" (current instant), \"add\" (shift iso by amount of unit), \"diff\" (signed to − from in unit; pass the start instant as iso or from), or \"format\" (render iso). Units are milliseconds, seconds, minutes, hours, days, or weeks (month/year are not supported). Pass instants as ISO-8601 strings; set format to \"iso\" (default), \"date\", \"time\", or \"datetime\", and timeZone as an IANA zone like \"Africa/Cairo\".",
+		input: inputSchema,
+		async execute(input) {
+			const timeZone = input.timeZone ?? defaultTimeZone;
+			switch (input.op) {
+				case "now": return { value: render(new Date(clock()), input.format, timeZone) };
+				case "format": return { value: render(parseIso(input.iso, "iso"), input.format, timeZone) };
+				case "add": {
+					const date = parseIso(input.iso, "iso");
+					if (input.amount === void 0) throw new DateTimeError("\"amount\" is required for the \"add\" operation.", { type: "invalid-input" });
+					if (input.unit === void 0) throw new DateTimeError("\"unit\" is required for the \"add\" operation.", { type: "invalid-input" });
+					return { value: render(new Date(date.getTime() + input.amount * unitToMs(input.unit)), input.format, timeZone) };
+				}
+				case "diff": {
+					const from = parseIso(input.iso ?? input.from, "iso (or from)");
+					const to = parseIso(input.to, "to");
+					if (input.unit === void 0) throw new DateTimeError("\"unit\" is required for the \"diff\" operation.", { type: "invalid-input" });
+					const diff = (to.getTime() - from.getTime()) / unitToMs(input.unit);
+					return { value: String(diff) };
+				}
+				default: {
+					const unreachable = input.op;
+					throw new DateTimeError(`Unsupported operation "${String(unreachable)}".`, { type: "unsupported-op" });
+				}
+			}
+		}
+	});
+}
+
+//#endregion
+export { dateTimeTool };
+//# sourceMappingURL=date-time.mjs.map

package/esm/utility/date-time.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-time.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/utility/date-time.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { DateTimeError } from \"../errors\";\nimport { literalField, objectSchema, optionalNumberField, optionalStringField } from \"./schema\";\nimport type {\n  DateTimeInput,\n  DateTimeOp,\n  DateTimeOptions,\n  DateTimeResult,\n} from \"../contracts/utility.type\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"date_time\";\n\n/** The closed set of operations the tool implements. */\nconst OPS: readonly DateTimeOp[] = [\"now\", \"add\", \"diff\", \"format\"];\n\n/**\n * A clock seam so tests are deterministic. Defaults to the real\n * {@link Date}; a test injects a fixed instant. Returns milliseconds\n * since the Unix epoch — the same contract as `Date.now()`.\n */\nexport type Clock = () => number;\n\n/** Construction dependencies for {@link dateTimeTool}, all optional. */\nexport interface DateTimeToolDeps {\n  /**\n   * The clock used by the `now` op. Defaults to `Date.now`. Injected in\n   * tests for deterministic output.\n   */\n  clock?: Clock;\n}\n\n/** Input schema for the `date_time` tool. */\nconst inputSchema = objectSchema<DateTimeInput>({\n  op: literalField<DateTimeOp>(OPS),\n  iso: optionalStringField(),\n  from: optionalStringField(),\n  to: optionalStringField(),\n  amount: optionalNumberField(),\n  unit: optionalStringField(),\n  timeZone: optionalStringField(),\n  format: optionalStringField(),\n});\n\n/**\n * The time units `add` and `diff` understand, each as its length in\n * milliseconds. Calendar-unaware on purpose: a \"month\" / \"year\" has no\n * fixed millisecond length, so they are deliberately excluded — adding\n * `30 days` is unambiguous in a way adding `1 month` is not.\n */\nconst UNIT_MS: Record<string, number> = {\n  milliseconds: 1,\n  seconds: 1_000,\n  minutes: 60_000,\n  hours: 3_600_000,\n  days: 86_400_000,\n  weeks: 604_800_000,\n};\n\n/** Singular aliases mapped to their canonical plural unit key. */\nconst UNIT_ALIASES: Record<string, string> = {\n  millisecond: \"milliseconds\",\n  ms: \"milliseconds\",\n  second: \"seconds\",\n  sec: \"seconds\",\n  s: \"seconds\",\n  minute: \"minutes\",\n  min: \"minutes\",\n  m: \"minutes\",\n  hour: \"hours\",\n  hr: \"hours\",\n  h: \"hours\",\n  day: \"days\",\n  d: \"days\",\n  week: \"weeks\",\n  w: \"weeks\",\n};\n\n/** Resolve a (possibly aliased / singular) unit token to its ms length. */\nfunction unitToMs(unit: string): number {\n  const canonical = UNIT_ALIASES[unit] ?? unit;\n  const ms = UNIT_MS[canonical];\n\n  if (ms === undefined) {\n    throw new DateTimeError(\n      `Unknown unit \"${unit}\". Supported units: ${Object.keys(UNIT_MS).join(\", \")}.`,\n      { type: \"invalid-unit\" },\n    );\n  }\n\n  return ms;\n}\n\n/**\n * Parse an ISO-8601 instant into a {@link Date}, or throw a typed\n * {@link DateTimeError} when the string is missing or unparseable.\n *\n * @param iso - The ISO string from the model (may be undefined).\n * @param field - The input field name, for the error message.\n */\nfunction parseIso(iso: string | undefined, field: string): Date {\n  if (iso === undefined) {\n    throw new DateTimeError(`\"${field}\" is required for this operation.`, {\n      type: \"invalid-input\",\n    });\n  }\n\n  const date = new Date(iso);\n\n  if (Number.isNaN(date.getTime())) {\n    throw new DateTimeError(`\"${field}\" is not a valid ISO-8601 instant: \"${iso}\".`, {\n      type: \"invalid-input\",\n    });\n  }\n\n  return date;\n}\n\n/**\n * Render a {@link Date} in a target time zone using `Intl`. The\n * `\"iso\"` format (the default) returns the instant's UTC ISO string;\n * any other `format` value is treated as an `Intl.DateTimeFormat`\n * locale-style rendering in the given `timeZone`.\n *\n * @throws DateTimeError `type: \"invalid-time-zone\"` when `timeZone` is\n *   not a recognized IANA zone.\n */\nfunction render(date: Date, format: string | undefined, timeZone: string | undefined): string {\n  if (format === undefined || format === \"iso\") {\n    // `timeZone` is irrelevant to a UTC ISO string, but validate it when\n    // supplied so a bad zone is reported rather than silently ignored.\n    if (timeZone !== undefined) {\n      assertTimeZone(timeZone);\n    }\n\n    return date.toISOString();\n  }\n\n  try {\n    return new Intl.DateTimeFormat(\"en-US\", {\n      timeZone,\n      dateStyle: format === \"date\" ? \"medium\" : undefined,\n      timeStyle: format === \"time\" ? \"medium\" : undefined,\n      ...(format === \"datetime\" ? { dateStyle: \"medium\", timeStyle: \"medium\" } : {}),\n    }).format(date);\n  } catch (error) {\n    throw new DateTimeError(\n      `Could not render with format \"${format}\"${\n        timeZone ? ` in time zone \"${timeZone}\"` : \"\"\n      }.`,\n      { type: \"invalid-time-zone\", cause: error },\n    );\n  }\n}\n\n/**\n * Validate an IANA time zone by attempting to construct a formatter for\n * it; an unrecognized zone makes `Intl` throw a `RangeError`.\n *\n * @throws DateTimeError `type: \"invalid-time-zone\"` for an unknown zone.\n */\nfunction assertTimeZone(timeZone: string): void {\n  try {\n    new Intl.DateTimeFormat(\"en-US\", { timeZone });\n  } catch (error) {\n    throw new DateTimeError(`Unknown time zone \"${timeZone}\".`, {\n      type: \"invalid-time-zone\",\n      cause: error,\n    });\n  }\n}\n\n/**\n * Build the `date_time` tool — a small clock/calendar utility the agent\n * can call to read the current instant, shift an instant, measure the\n * gap between two instants, or render one. The `op` discriminator selects\n * the operation:\n *\n * - **`now`** — the current instant, rendered per `format` / `timeZone`\n *   (defaults to a UTC ISO string). Reads the injectable {@link Clock}.\n * - **`add`** — `iso` shifted by `amount` of `unit` (e.g.\n *   `+3 days`); a negative `amount` shifts backward.\n * - **`diff`** — the signed difference `to − iso`, expressed in `unit`.\n * - **`format`** — `iso` rendered per `format` / `timeZone`.\n *\n * Units are millisecond-based (`milliseconds`…`weeks`, plus common\n * aliases); calendar-relative `month`/`year` are intentionally\n * unsupported because they have no fixed length.\n *\n * **Deterministic in tests.** The clock backing `now` is injectable via\n * `deps.clock`; production defaults to `Date.now`.\n *\n * **Errors flow as data.** A missing/invalid field, an unknown unit, or\n * an unrecognized time zone throws a {@link DateTimeError} inside the\n * handler; `tool()` surfaces it in `{ error }` so the agent self-corrects.\n *\n * @param options - Optional overrides; `name` renames the tool,\n *   `defaultTimeZone` applies when a call omits `timeZone`.\n * @param deps - Injectable dependencies (the {@link Clock}); defaults to real time.\n * @returns A `ToolContract<DateTimeInput, { value }>` ready for `tools: []`.\n *\n * @example\n * const clock = () => Date.parse(\"2026-06-22T00:00:00Z\");\n * const dt = dateTimeTool({}, { clock });\n * const { data } = await dt.invoke({ op: \"now\" });\n * console.log(data?.value); // \"2026-06-22T00:00:00.000Z\"\n */\nexport function dateTimeTool(\n  options?: DateTimeOptions,\n  deps?: DateTimeToolDeps,\n): ToolContract<DateTimeInput, DateTimeResult> {\n  const clock: Clock = deps?.clock ?? Date.now;\n  const defaultTimeZone = options?.defaultTimeZone;\n\n  return tool<DateTimeInput, DateTimeResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Work with dates and times. Set op to: \\\"now\\\" (current instant), \" +\n      '\"add\" (shift iso by amount of unit), \"diff\" (signed to − from in unit; ' +\n      \"pass the start instant as iso or from), \" +\n      'or \"format\" (render iso). Units are milliseconds, seconds, minutes, ' +\n      \"hours, days, or weeks (month/year are not supported). Pass instants as \" +\n      'ISO-8601 strings; set format to \"iso\" (default), \"date\", \"time\", or ' +\n      '\"datetime\", and timeZone as an IANA zone like \"Africa/Cairo\".',\n    input: inputSchema,\n    async execute(input) {\n      const timeZone = input.timeZone ?? defaultTimeZone;\n\n      switch (input.op) {\n        case \"now\": {\n          const date = new Date(clock());\n\n          return { value: render(date, input.format, timeZone) };\n        }\n\n        case \"format\": {\n          const date = parseIso(input.iso, \"iso\");\n\n          return { value: render(date, input.format, timeZone) };\n        }\n\n        case \"add\": {\n          const date = parseIso(input.iso, \"iso\");\n\n          if (input.amount === undefined) {\n            throw new DateTimeError('\"amount\" is required for the \"add\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          if (input.unit === undefined) {\n            throw new DateTimeError('\"unit\" is required for the \"add\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          const shifted = new Date(date.getTime() + input.amount * unitToMs(input.unit));\n\n          return { value: render(shifted, input.format, timeZone) };\n        }\n\n        case \"diff\": {\n          // Accept `from` as an alias for `iso` — models naturally pass\n          // `from` / `to` for a difference. `iso` wins when both are set.\n          const from = parseIso(input.iso ?? input.from, \"iso (or from)\");\n          const to = parseIso(input.to, \"to\");\n\n          if (input.unit === undefined) {\n            throw new DateTimeError('\"unit\" is required for the \"diff\" operation.', {\n              type: \"invalid-input\",\n            });\n          }\n\n          const diff = (to.getTime() - from.getTime()) / unitToMs(input.unit);\n\n          return { value: String(diff) };\n        }\n\n        default: {\n          // Exhaustiveness guard — the schema's literal union should make\n          // this unreachable, but a future op added to the union without a\n          // case here surfaces as typed data rather than silent fallthrough.\n          const unreachable: never = input.op;\n\n          throw new DateTimeError(`Unsupported operation \"${String(unreachable)}\".`, {\n            type: \"unsupported-op\",\n          });\n        }\n      }\n    },\n  });\n}\n"],"mappings":"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"}

package/esm/utility/index.d.mts

@@ -0,0 +1,2 @@
+import { calculatorTool } from "./calculator.mjs";
+import { Clock, DateTimeToolDeps, dateTimeTool } from "./date-time.mjs";

package/esm/utility/index.mjs

@@ -0,0 +1,4 @@
+import { calculatorTool } from "./calculator.mjs";
+import { dateTimeTool } from "./date-time.mjs";
+
+export {  };

package/esm/utility/schema.mjs

@@ -0,0 +1,114 @@
+//#region ../@warlock.js/ai-tools/src/utility/schema.ts
+/**
+* Tiny, dependency-free [Standard Schema](https://standardschema.dev)
+* builders for the utility tools' input validation. This package pins
+* only `@warlock.js/ai` as a runtime peer, so rather than pull in a
+* schema library we hand-roll the few field shapes the calculator and
+* date-time tools need — the same approach `@warlock.js/ai`'s own
+* `tool()` tests use. Each builder returns a {@link StandardSchemaV1},
+* which is what `tool({ input })` validates against before calling
+* `execute`.
+*
+* These intentionally cover only the primitive cases the UTILITY tools
+* require (`string`, `optional string`, `optional number`, and a
+* `literal union` enum). 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 — accepts `undefined` (the property absent or
+* explicitly undefined) or a string, and rejects every other type.
+*/
+function optionalStringField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "string") return { value };
+		return { issues: [{
+			message: `"${key}" must be a string when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Optional finite-number field — accepts `undefined` or a finite number,
+* rejecting `NaN`/`Infinity` and non-number types.
+*/
+function optionalNumberField() {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (typeof value === "number" && Number.isFinite(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be a finite number when provided`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* Required literal-union field — accepts only one of `allowed`, rejecting
+* everything else. Used for discriminators like the date-time `op`.
+*
+* @param allowed - The closed set of permitted string literals.
+*/
+function literalField(allowed) {
+	return (value, key) => {
+		if (typeof value === "string" && allowed.includes(value)) return { value };
+		return { issues: [{
+			message: `"${key}" must be one of: ${allowed.join(", ")}`,
+			path: [key]
+		}] };
+	};
+}
+/**
+* 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<{ expression: string }>({
+*   expression: stringField(),
+* });
+*/
+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 outcome = field(source[key], key);
+				if ("issues" in outcome) {
+					issues.push(...outcome.issues);
+					continue;
+				}
+				if (outcome.value !== void 0) result[key] = outcome.value;
+			}
+			if (issues.length > 0) return { issues };
+			return { value: result };
+		}
+	} };
+}
+
+//#endregion
+export { literalField, objectSchema, optionalNumberField, optionalStringField, stringField };
+//# sourceMappingURL=schema.mjs.map

package/esm/utility/schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/utility/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 utility tools' input validation. This package pins\n * only `@warlock.js/ai` as a runtime peer, so rather than pull in a\n * schema library we hand-roll the few field shapes the calculator and\n * date-time tools need — the same approach `@warlock.js/ai`'s own\n * `tool()` tests use. Each builder returns a {@link StandardSchemaV1},\n * which is what `tool({ input })` validates against before calling\n * `execute`.\n *\n * These intentionally cover only the primitive cases the UTILITY tools\n * require (`string`, `optional string`, `optional number`, and a\n * `literal union` enum). 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 */\ntype 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 — accepts `undefined` (the property absent or\n * explicitly undefined) or a string, and rejects every other type.\n */\nexport function optionalStringField(): FieldValidator<string | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"string\") {\n      return { value };\n    }\n\n    return {\n      issues: [{ message: `\"${key}\" must be a string when provided`, path: [key] }],\n    };\n  };\n}\n\n/**\n * Optional finite-number field — accepts `undefined` or a finite number,\n * rejecting `NaN`/`Infinity` and non-number types.\n */\nexport function optionalNumberField(): FieldValidator<number | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"number\" && Number.isFinite(value)) {\n      return { value };\n    }\n\n    return {\n      issues: [\n        { message: `\"${key}\" must be a finite number when provided`, path: [key] },\n      ],\n    };\n  };\n}\n\n/**\n * Required literal-union field — accepts only one of `allowed`, rejecting\n * everything else. Used for discriminators like the date-time `op`.\n *\n * @param allowed - The closed set of permitted string literals.\n */\nexport function literalField<T extends string>(\n  allowed: readonly T[],\n): FieldValidator<T> {\n  return (value, key) => {\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/** 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<{ expression: string }>({\n *   expression: stringField(),\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 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          // Only carry through keys that resolved to a defined value, so\n          // optional-absent fields stay absent rather than becoming\n          // explicit `undefined` properties.\n          if (outcome.value !== undefined) {\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":";;;;;;;;;;;;;;;;AAkBA,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;;;;;AAMA,SAAgB,sBAA0D;CACxE,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAmC,MAAM,CAAC,GAAG;EAAE,CAAC,EAC9E;CACF;AACF;;;;;AAMA,SAAgB,sBAA0D;CACxE,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,GACpD,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CACN;GAAE,SAAS,IAAI,IAAI;GAA0C,MAAM,CAAC,GAAG;EAAE,CAC3E,EACF;CACF;AACF;;;;;;;AAQA,SAAgB,aACd,SACmB;CACnB,QAAQ,OAAO,QAAQ;EACrB,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;;;;;;;;;;;;;;;;;;AAwBA,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,UAAU,MAAM,OAAO,MAAgB,GAAa;IAE1D,IAAI,YAAY,SAAS;KACvB,OAAO,KAAK,GAAG,QAAQ,MAAM;KAE7B;IACF;IAKA,IAAI,QAAQ,UAAU,QACpB,OAAO,OAAiB,QAAQ;GAEpC;GAEA,IAAI,OAAO,SAAS,GAClB,OAAO,EAAE,OAAO;GAGlB,OAAO,EAAE,OAAO,OAAY;EAC9B;CACF,EACF;AACF"}

package/esm/web/fetch-url.d.mts

@@ -0,0 +1,39 @@
+import { FetchUrlInput, FetchUrlOptions, FetchUrlResult } from "../contracts/web.type.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/web/fetch-url.d.ts
+/**
+ * Build the agent-facing `fetch_url` tool — fetch a URL over the global
+ * `fetch` (Node 18+) and hand the model back rendered `content`.
+ *
+ * Guardrails, applied in order before/around the network call:
+ * - **`allowHosts`** — when set, a request to any host not in the list is
+ *   rejected before the fetch (an SSRF guardrail).
+ * - **`timeoutMs`** — the request is aborted via `AbortSignal.timeout`
+ *   (default {@link DEFAULT_TIMEOUT_MS}).
+ * - **`maxBytes`** — the response body is read up to this cap and the
+ *   result flags `truncated` when it was cut off (default
+ *   {@link DEFAULT_MAX_BYTES}).
+ * - **`extract`** — `"html"` returns the raw body; `"text"` (default) and
+ *   `"markdown"` run `@mozilla/readability` over `jsdom`, lazily imported
+ *   so they stay OPTIONAL peers — a missing peer throws the curated
+ *   install string.
+ *
+ * **Errors flow as data.** Every guardrail rejection and network failure
+ * throws a typed {@link WebToolError}; the `tool()` wrapper catches it and
+ * surfaces it in the returned `{ error }` field — `invoke()` never throws
+ * — so the agent reads the failure and self-corrects.
+ *
+ * @param options - Tool-name override, byte cap, timeout, extract mode,
+ *   and host allowlist.
+ * @returns A `ToolContract<{ url }, FetchUrlResult>`.
+ *
+ * @example
+ * const fetchUrl = fetchUrlTool({ extract: "text", allowHosts: ["docs.stripe.com"] });
+ * const { data } = await fetchUrl.invoke({ url: "https://docs.stripe.com/api" });
+ * console.log(data?.content, data?.truncated);
+ */
+declare function fetchUrlTool(options?: FetchUrlOptions): ToolContract<FetchUrlInput, FetchUrlResult>;
+//#endregion
+export { fetchUrlTool };
+//# sourceMappingURL=fetch-url.d.mts.map

package/esm/web/fetch-url.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-url.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-tools/src/web/fetch-url.ts"],"mappings":";;;;;;;AA6SA;;;;;;;;;;;;;;;AAE6C;;;;;;;;;;;;;iBAF7B,YAAA,CACd,OAAA,GAAU,eAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}

package/esm/web/fetch-url.mjs

@@ -0,0 +1,228 @@
+import { WebToolError } from "../errors.mjs";
+import { objectSchema, stringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-tools/src/web/fetch-url.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "fetch_url";
+/** Default hard cap on response bytes read before truncation. */
+const DEFAULT_MAX_BYTES = 1e6;
+/** Default per-request timeout in milliseconds. */
+const DEFAULT_TIMEOUT_MS = 15e3;
+/** Default rendering mode for the fetched document. */
+const DEFAULT_EXTRACT = "text";
+/** Input schema: `{ url }`. */
+const inputSchema = objectSchema({ url: stringField() });
+const READABILITY_MODULE_ID = "@mozilla/readability";
+const JSDOM_MODULE_ID = "jsdom";
+let ReadabilitySdk;
+let JsdomSdk;
+let isReadabilityAvailable;
+let loadingPromise;
+const READABILITY_INSTALL_INSTRUCTIONS = `
+The fetch_url text/markdown extractor requires the @mozilla/readability and jsdom packages.
+Install them with:
+
+  npm install @mozilla/readability jsdom
+
+Or with your preferred package manager:
+
+  pnpm add @mozilla/readability jsdom
+  yarn add @mozilla/readability jsdom
+`.trim();
+/**
+* Settle the lazy import of `@mozilla/readability` + `jsdom` once,
+* concurrency-safe. Only needed for the `"text"` / `"markdown"` extract
+* modes — `"html"` returns the raw body and never loads them. A bare
+* `catch` flips the flag to `false`; the curated install string surfaces
+* at use time via {@link WebToolError}, never a raw module-resolution
+* stack trace.
+*/
+function loadReadability() {
+	if (isReadabilityAvailable !== void 0) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			ReadabilitySdk = await import(READABILITY_MODULE_ID);
+			JsdomSdk = await import(JSDOM_MODULE_ID);
+			isReadabilityAvailable = true;
+		} catch {
+			isReadabilityAvailable = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Parse the input URL, rejecting anything unparseable or not over
+* `http`/`https` with a typed {@link WebToolError}.
+*/
+function parseUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new WebToolError(`fetch_url received an unparseable URL: "${raw}".`, { type: "invalid-url" });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new WebToolError(`fetch_url only supports http(s) URLs; got "${url.protocol}".`, { type: "invalid-url" });
+	return url;
+}
+/**
+* Enforce the host allowlist (an SSRF guardrail) before any network call.
+* When `allowHosts` is set, a request to a host not in it is rejected;
+* matching is exact on the URL hostname (case-insensitive).
+*/
+function assertHostAllowed(url, allowHosts) {
+	if (!allowHosts || allowHosts.length === 0) return;
+	const host = url.hostname.toLowerCase();
+	if (!allowHosts.some((entry) => entry.toLowerCase() === host)) throw new WebToolError(`fetch_url blocked host "${url.hostname}" — it is not in the allowHosts allowlist.`, {
+		type: "denied-host",
+		context: { host: url.hostname }
+	});
+}
+/**
+* Read the response body up to `maxBytes`, stopping early once the cap is
+* reached. Returns the decoded text and whether it was truncated. When
+* the body has no stream (a stubbed `Response`), falls back to `.text()`
+* and truncates the decoded string at `maxBytes`.
+*/
+async function readBody(response, maxBytes) {
+	const stream = response.body;
+	if (!stream) {
+		const text = await response.text();
+		if (text.length > maxBytes) return {
+			body: text.slice(0, maxBytes),
+			truncated: true
+		};
+		return {
+			body: text,
+			truncated: false
+		};
+	}
+	const reader = stream.getReader();
+	const chunks = [];
+	let received = 0;
+	let truncated = false;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (value) {
+			received += value.byteLength;
+			chunks.push(value);
+			if (received >= maxBytes) {
+				truncated = true;
+				await reader.cancel();
+				break;
+			}
+		}
+	}
+	const merged = new Uint8Array(received);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	const sliced = truncated ? merged.subarray(0, maxBytes) : merged;
+	return {
+		body: new TextDecoder().decode(sliced),
+		truncated
+	};
+}
+/**
+* Render the fetched HTML into the configured `extract` mode. `"html"`
+* returns the raw body untouched; `"text"` and `"markdown"` run
+* `@mozilla/readability` over a `jsdom` document, throwing a curated
+* {@link WebToolError} when those optional peers are absent. `"markdown"`
+* applies a light heading/paragraph conversion over the extracted text.
+*/
+async function render(html, url, extract) {
+	if (extract === "html") return html;
+	await loadReadability();
+	if (!isReadabilityAvailable) throw new WebToolError(READABILITY_INSTALL_INSTRUCTIONS, { type: "missing-peer" });
+	const dom = new JsdomSdk.JSDOM(html, { url });
+	const article = new ReadabilitySdk.Readability(dom.window.document).parse();
+	if (extract === "markdown") return article?.content ? htmlToMarkdown(article.content) : article?.textContent ?? "";
+	return article?.textContent ?? "";
+}
+/**
+* Minimal HTML→Markdown reduction for readability's extracted article
+* HTML — headings become `#` prefixes, paragraphs/line-breaks become
+* blank-line separated blocks, and remaining tags are stripped. This is a
+* pragmatic conversion, not a full CommonMark serializer.
+*/
+function htmlToMarkdown(html) {
+	return html.replace(/<h([1-6])[^>]*>(.*?)<\/h\1>/gis, (_match, level, text) => {
+		return `\n\n${"#".repeat(Number(level))} ${stripTags(text).trim()}\n\n`;
+	}).replace(/<\/(p|div|section|article|li)>/gi, "\n\n").replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Strip any remaining HTML tags from a fragment. */
+function stripTags(html) {
+	return html.replace(/<[^>]+>/g, "");
+}
+/**
+* Build the agent-facing `fetch_url` tool — fetch a URL over the global
+* `fetch` (Node 18+) and hand the model back rendered `content`.
+*
+* Guardrails, applied in order before/around the network call:
+* - **`allowHosts`** — when set, a request to any host not in the list is
+*   rejected before the fetch (an SSRF guardrail).
+* - **`timeoutMs`** — the request is aborted via `AbortSignal.timeout`
+*   (default {@link DEFAULT_TIMEOUT_MS}).
+* - **`maxBytes`** — the response body is read up to this cap and the
+*   result flags `truncated` when it was cut off (default
+*   {@link DEFAULT_MAX_BYTES}).
+* - **`extract`** — `"html"` returns the raw body; `"text"` (default) and
+*   `"markdown"` run `@mozilla/readability` over `jsdom`, lazily imported
+*   so they stay OPTIONAL peers — a missing peer throws the curated
+*   install string.
+*
+* **Errors flow as data.** Every guardrail rejection and network failure
+* throws a typed {@link WebToolError}; the `tool()` wrapper catches it and
+* surfaces it in the returned `{ error }` field — `invoke()` never throws
+* — so the agent reads the failure and self-corrects.
+*
+* @param options - Tool-name override, byte cap, timeout, extract mode,
+*   and host allowlist.
+* @returns A `ToolContract<{ url }, FetchUrlResult>`.
+*
+* @example
+* const fetchUrl = fetchUrlTool({ extract: "text", allowHosts: ["docs.stripe.com"] });
+* const { data } = await fetchUrl.invoke({ url: "https://docs.stripe.com/api" });
+* console.log(data?.content, data?.truncated);
+*/
+function fetchUrlTool(options) {
+	const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const extract = options?.extract ?? DEFAULT_EXTRACT;
+	const allowHosts = options?.allowHosts;
+	if (extract !== "html") loadReadability();
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Fetch a web page or document by URL and return its main content as text (readability-extracted), raw HTML, or Markdown. Use to read a specific page you already have the URL for.",
+		input: inputSchema,
+		async execute(input) {
+			const url = parseUrl(input.url);
+			assertHostAllowed(url, allowHosts);
+			let response;
+			try {
+				response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+			} catch (cause) {
+				throw new WebToolError(`fetch_url request failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+					type: "request-failed",
+					cause
+				});
+			}
+			const { body, truncated } = await readBody(response, maxBytes);
+			const content = await render(body, response.url || url.toString(), extract);
+			return {
+				url: response.url || url.toString(),
+				status: response.status,
+				content,
+				truncated
+			};
+		}
+	});
+}
+
+//#endregion
+export { fetchUrlTool };
+//# sourceMappingURL=fetch-url.mjs.map