@dotcms/ai 26.10.20-1 → 26.10.21-1

package/src/tools/toolkit/tool-runtime.d.ts

@@ -0,0 +1,108 @@
+import { type DotCMSErrorCode, type DotCMSRuntime, type DotCMSRuntimeConfig } from '../../runtime';
+/**
+ * The runtime settings a tool host supplies once. Everything else a tool needs (its sandbox
+ * timeout, whether it gets the `spec` global) is decided per tool, not by the host.
+ */
+export type ToolRuntimeConfig = Pick<DotCMSRuntimeConfig, 'url' | 'token' | 'allow' | 'onCall' | 'onContextError' | 'includeStacks'>;
+/** What an individual tool asks of the runtime it is handed for one call. */
+export interface ToolRuntimeOptions {
+    /** Sandbox wall-clock timeout (ms) for `run()`. */
+    timeout?: number;
+    /** Inject the OpenAPI `spec` global into `run()`. */
+    includeSpec?: boolean;
+    /** Deadline (ms) for each direct `request()`. Default {@link DEFAULT_REQUEST_TIMEOUT_MS}. */
+    requestTimeout?: number;
+}
+/**
+ * Cap on any single error string handed back to the model.
+ *
+ * A dotCMS 5xx returns its full HTML stack-trace page, tens to hundreds of KB, and
+ * `HttpError.message` embeds the body verbatim. A transfer manifest keeps one message PER
+ * FAILED FILE, so 200 files against a broken instance would otherwise carry 200 copies of
+ * that page in a single tool result.
+ */
+export declare const MAX_ERROR_CHARS = 2000;
+/**
+ * The tool host is misconfigured — a deployment problem, not a bad tool call.
+ *
+ * Carries its own `code` so it lands in {@link ToolFailure} as `CONFIGURATION` rather than
+ * `UNKNOWN`, which is what lets the model tell "I called this wrong" from "this server
+ * cannot serve anyone right now".
+ */
+export declare class ConfigurationError extends Error {
+    readonly code: "CONFIGURATION";
+    /**
+     * `cause` carries the underlying error for the HOST (e.g. what a token resolver threw). It
+     * is never part of the message, which is what reaches the model.
+     */
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Build the runtime one tool call runs against. One place owns the per-request deadline —
+ * so every tool constructs its runtime the same way instead of re-deriving it (and silently
+ * drifting on which options they set).
+ *
+ * Called once per tool invocation, deliberately: the runtime owns its context cache, so a
+ * fresh runtime is what lets the next call see sites, content types or languages the
+ * previous call created. That is also why no session id is threaded through — a runtime
+ * that lives for one call has nothing to key a cache on.
+ */
+export declare function createToolRuntime(config: ToolRuntimeConfig, opts?: ToolRuntimeOptions): DotCMSRuntime;
+/**
+ * Normalize any thrown value to a message string, capped at {@link MAX_ERROR_CHARS}.
+ *
+ * The cap is the point: see MAX_ERROR_CHARS for why an uncapped `HttpError.message` is a
+ * real problem rather than a cosmetic one.
+ */
+export declare function errorMessage(error: unknown): string;
+/**
+ * Give a caught error a clearer message, and return that SAME error for the caller to throw.
+ *
+ * For an operation that explains a failure in its own terms ("the save was rejected as a
+ * net-loss conflict…") before rethrowing. Wrapping it in a new `Error` instead loses the
+ * error's class, and with it the `code`, the HTTP `status` and whether a retry can help: a 503
+ * worth retrying reaches the model as `UNKNOWN`, not retryable. Only a non-`Error` throw, which
+ * has no class to keep, becomes a plain `Error`.
+ */
+export declare function withMessage(error: unknown, message: string): Error;
+/**
+ * Every code a {@link ToolFailure} can carry: the runtime's error codes, `CONFIGURATION` for a
+ * connection the host has not set up, and `UNKNOWN` for anything that is not a typed error.
+ * A union rather than `string`, so a host switching on it gets completion and a misspelt code
+ * is a compile error rather than a branch that silently never runs.
+ */
+export type ToolFailureCode = DotCMSErrorCode | ConfigurationError['code'] | 'UNKNOWN';
+/** The structured failure a tool returns instead of a bare message. */
+export interface ToolFailure {
+    ok: false;
+    operation: string;
+    error: string;
+    /** Stable machine-readable code (`HTTP`, `TIMEOUT`, `POLICY`, …), or `UNKNOWN`. */
+    code: ToolFailureCode;
+    /**
+     * Whether retrying could help. A FIELD rather than only a type, because MCP hands the
+     * model a STRING — `instanceof` is unavailable on the far side, so anything the model
+     * needs to branch on has to survive JSON.
+     */
+    retryable: boolean;
+    /** HTTP status when the failure was an HTTP error. */
+    status?: number;
+    [key: string]: unknown;
+}
+/**
+ * Build the failure a tool returns instead of throwing.
+ *
+ * Owns the `[dotCMS - <operation>]` prefix convention in one place rather than as a
+ * template string at each throw site, and preserves the typed detail (`code`, `status`,
+ * `retryable`) that flattening to `.message` used to discard.
+ *
+ * Deliberately NOT a parallel error hierarchy: `formatSandboxResult` remains the layer for
+ * sandbox results (`execute`/`search` already use it). This is only for failures a tool
+ * call raises outside a sandbox result — a direct request, invalid arguments, a host
+ * misconfiguration.
+ */
+export declare function toToolFailure(operation: string, error: unknown, extra?: Record<string, unknown>): ToolFailure;
+/** Whether a tool result is a {@link ToolFailure} rather than the tool's normal result. */
+export declare function isToolFailure(value: unknown): value is ToolFailure;

package/src/tools/toolkit/types.d.ts

@@ -0,0 +1,120 @@
+import type { ToolModelOutput } from './results';
+import type { ToolFailure } from './tool-runtime';
+import type { RuntimeAllow } from '../../runtime';
+import type { z } from 'zod';
+/**
+ * Behavior hints a host forwards to its framework — they map one-to-one onto MCP's
+ * `ToolAnnotations`. Hints, not guarantees: `execute` is marked destructive because the code a
+ * model writes for it CAN delete content, not because every call does.
+ */
+export interface DotCMSToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+/** Options for `executeTool`. */
+export interface ExecuteToolOptions {
+    /**
+     * Allow-list or policy bounding what the model's code can reach — the same one
+     * `createRuntime` takes. The one tool that has it: here the MODEL chooses the endpoints,
+     * so this is the consumer governing the model, not configuring the tool.
+     */
+    allow?: RuntimeAllow;
+    /** Sandbox wall-clock timeout (ms) for the model's code. Default 45000. */
+    timeout?: number;
+    /** Pass host stack traces through to the code's error results. Default false. */
+    includeStacks?: boolean;
+}
+/** Options for the tools that call the API directly: the page and asset tools. */
+export interface RequestToolOptions {
+    /** Deadline (ms) for each request. Default 30000. */
+    requestTimeout?: number;
+}
+/** Options for `uploadAssetsTool` and `downloadAssetsTool`, which touch the local disk. */
+export interface AssetToolOptions extends RequestToolOptions {
+    /**
+     * The local directory the model's `src` / `dest` must stay inside — symlinks resolved.
+     * Required, because the paths come from the model: without a boundary a hosted server's
+     * `upload_assets` reads any directory the process can, and `download_assets` writes into
+     * any directory it can. `'/'` is the explicit "whole disk" choice, for a local agent acting
+     * as its own user.
+     */
+    root: string;
+}
+/** Options for `uploadAssetsTool`: the asset options, plus the limits on what one call sends. */
+export interface UploadToolOptions extends AssetToolOptions {
+    /**
+     * Largest file one call sends, in bytes. Default 100 MB. A larger file is a failure in the
+     * manifest, before it is read; the rest still upload. Each file is held in memory once
+     * while it is sent, so this also bounds the upload's memory. `Infinity` lifts it.
+     */
+    maxFileBytes?: number;
+    /**
+     * Most files one call sends, after `include`. Default 1,000. More is a VALIDATION
+     * failure before anything is sent. `Infinity` lifts it.
+     */
+    maxFiles?: number;
+    /**
+     * Most entries — files and directories — one call's walk of `src` visits, matched by
+     * `include` or not. Default 20,000. More is a VALIDATION failure before anything is sent,
+     * so a vast `src` with a narrow `include` is not walked to the end. `Infinity` lifts it.
+     */
+    maxScannedEntries?: number;
+}
+/**
+ * One dotCMS tool, shaped the way the Vercel AI SDK and the MCP TypeScript SDK both expect:
+ * pass it straight into AI SDK's `tools`, or into MCP's `registerTool` config. Every result is
+ * an object, as Google ADK requires.
+ *
+ * `execute` never throws. It validates `input` (it comes from the model, so this is the trust
+ * boundary), runs the tool, and resolves to the tool's result — or to a {@link ToolFailure}
+ * carrying a stable `code` and a `retryable` flag, because a model cannot `instanceof` its
+ * way through a failure.
+ *
+ * `input` is typed from the tool's own schema, so code that calls a tool directly gets
+ * completion and a compile error for a wrong field. That is a convenience for the caller, not
+ * the check: `execute` still validates at run time, because what reaches it from a model was
+ * never type-checked. A host that holds several tools in one list and calls whichever the
+ * model picked types that list as {@link AnyDotCMSTool}.
+ */
+export interface DotCMSTool<TInput extends z.ZodObject = z.ZodObject, TResult = unknown> extends DotCMSToolBase<TResult> {
+    readonly inputSchema: TInput;
+    execute(input: z.input<TInput>): Promise<TResult | ToolFailure>;
+}
+/**
+ * Any dotCMS tool, whatever its schema — the element type of a registry: `AnyDotCMSTool[]`, or
+ * a map from tool name to tool. `execute` takes `unknown`, because a registry dispatches on the
+ * name the model chose and hands over the model's arguments as they came; `execute` validates
+ * them. Every {@link DotCMSTool} is assignable to it.
+ */
+export interface AnyDotCMSTool extends DotCMSToolBase<unknown> {
+    readonly inputSchema: z.ZodObject;
+    execute(input: unknown): Promise<unknown>;
+}
+/** What every tool has, whatever its input: identity, annotations and rendering. */
+interface DotCMSToolBase<TResult> {
+    /**
+     * The name the tool's description expects to be called by. The descriptions refer to their
+     * siblings by these names ("use the `search` tool first"), so register each tool under it.
+     */
+    readonly name: string;
+    readonly title: string;
+    /** The model-facing description — tuned prompt text. */
+    readonly description: string;
+    readonly annotations: DotCMSToolAnnotations;
+    /**
+     * What the model sees of a result, for frameworks that ask (the AI SDK picks this up on its
+     * own): text for the tools that declare a text form (`search`, `execute`), structured JSON
+     * for the rest and for any failure.
+     */
+    toModelOutput(options: {
+        output: TResult | ToolFailure;
+    }): ToolModelOutput;
+    /**
+     * The same rendering, as the text a text-only transport such as an MCP `content` block
+     * carries: a text tool's output as-is, everything else pretty-printed JSON.
+     */
+    toText(output: TResult | ToolFailure): string;
+}
+export {};

package/src/tools.d.ts

@@ -0,0 +1 @@
+export * from './tools/index';

package/tools.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./tools.cjs.js').default;