@dotcms/ai 26.10.20-1 → 26.10.21-1

package/src/tools/operations/page-verify.d.ts

@@ -0,0 +1,164 @@
+import { LayoutRow } from './shared/page-common';
+import { type DotCMSRuntime } from '../../runtime';
+import { type Endpoint } from '../toolkit/endpoints';
+/**
+ * Every endpoint `verifyPage` calls — all reads. The `page_verify` tool enforces exactly this
+ * list, and `page-verify.spec.ts` checks every request against it. Add a request, add it here.
+ */
+export declare const PAGE_VERIFY_ENDPOINTS: readonly Endpoint[];
+/** Render modes the verify tool supports. LIVE = published; WORKING = latest saved (pre-publish). */
+export type VerifyMode = 'LIVE' | 'WORKING';
+/** The default render mode when the caller does not name one. */
+export declare const DEFAULT_MODE: VerifyMode;
+/** The default language id when the caller does not name one. */
+export declare const DEFAULT_LANGUAGE_ID = 1;
+/**
+ * Per-slot verdict:
+ * - ok               — the slot produced rendered HTML.
+ * - empty-vtl-error  — content IS placed in the slot, but it rendered empty → the container/widget
+ *                      VTL failed (a #dotParse error swallowed to nothing). Fix lives in Layer 1:
+ *                      re-run that VTL through POST /api/vtl/dynamic to get the parse/eval error.
+ * - empty-no-content — the slot resolved but has no contentlets placed. A placement gap, not a code
+ *                      bug — use page_place_content to add content.
+ * - cache-stale      — the slot rendered HTML, but the full page.rendered came back empty → a
+ *                      page-level cache problem. Set cachettl "0" and re-publish.
+ * - not-assembled    — the slot rendered HTML in isolation, but distinctive evidence from that
+ *                      HTML is absent from the assembled page → the template/theme omitted it.
+ */
+export type SlotVerdict = 'ok' | 'empty-vtl-error' | 'empty-no-content' | 'cache-stale' | 'not-assembled';
+export interface VerifySlotResult {
+    /** Container key as the layout addresses it (path for file containers, id for db containers). */
+    container: string;
+    /** Slot instance uuid. */
+    uuid: string;
+    /** Whether this slot produced non-empty rendered HTML. */
+    rendered: boolean;
+    /** Byte length of this slot's rendered HTML (0 when empty). */
+    bytes: number;
+    /** How many contentlets are placed in the slot (from the render response's contentlets map). */
+    contentCount: number;
+    /** Classification of the slot's render outcome. */
+    verdict: SlotVerdict;
+}
+/** The $URLMapContent resolution outcome — only present for URL-mapped (detail) pages. */
+export interface UrlMapResult {
+    /** True when the path resolved to a concrete detail contentlet (vs. the no-match branch). */
+    resolved: boolean;
+    /** The resolved contentlet identifier, when resolved. */
+    contentletId?: string;
+}
+export interface VerifyPageOptions {
+    dotcms: DotCMSRuntime;
+    /** Page URL path (e.g. "/about-us" or a URL-mapped detail slug like "/blog/my-post"). */
+    path: string;
+    /**
+     * Site to render against — hostname or identifier (UUID). Optional: when omitted the instance's
+     * current/default site is used (no host_id sent). Only NON-default sites need this.
+     */
+    site?: string;
+    /** Language id. Default 1. */
+    languageId?: number;
+    /** Render mode. Default "LIVE" (published). "WORKING" checks the latest saved, pre-publish. */
+    mode?: VerifyMode;
+    /** Include a bounded prefix of the assembled page HTML in the manifest. Default false. */
+    includeHtml?: boolean;
+}
+export interface VerifyHtmlResult {
+    /** Bounded prefix of the assembled page HTML. */
+    content: string;
+    /** Total JavaScript character count before truncation. */
+    totalChars: number;
+    /** Total UTF-8 byte count before truncation. */
+    totalBytes: number;
+    /** True when content is only a prefix of the assembled HTML. */
+    truncated: boolean;
+    /** Maximum number of characters returned in content. */
+    limit: number;
+}
+export interface VerifyPageManifest {
+    /** The path that was verified. */
+    path: string;
+    /** The page's resolved url. */
+    url: string;
+    /** The site the page rendered against (hostname when resolved, else "(default)"). */
+    site: string;
+    /** The render mode used. */
+    mode: VerifyMode;
+    /** Language id used. */
+    languageId: number;
+    /** HTTP status of the render call (200 even when the body is empty — see pageRendered). */
+    httpStatus: number;
+    /** True when page.rendered came back non-empty. A 200 with pageRendered=false is a swallowed error. */
+    pageRendered: boolean;
+    /** Byte length of the full page.rendered HTML. */
+    pageBytes: number;
+    /** Per-slot verdicts, in layout order. */
+    slots: VerifySlotResult[];
+    /** URL-map resolution for detail pages; null for a regular page. */
+    urlMap: UrlMapResult | null;
+    /** Actionable notices derived from the verdicts. */
+    warnings: string[];
+    /** One-line summary plus the next action to take. */
+    diagnosis: string;
+    /** Bounded assembled HTML, present only when includeHtml=true. */
+    html?: VerifyHtmlResult;
+}
+export declare const MAX_INCLUDED_HTML_CHARS = 20000;
+/**
+ * Verify that a dotCMS page actually renders — the layer that catches a blank slot, a swallowed
+ * #dotParse error, a cache-stale page, or an unpublished edit, none of which a VTL-only check
+ * (/api/vtl/dynamic) can see because that runs in a request context, not a render context.
+ *
+ * Wraps GET /api/v1/page/render/{uri} and absorbs its sharp edges:
+ *   - Host: the caller passes a hostname (or nothing); the tool resolves it to a host_id. host_id is
+ *     required only for a NON-default site — omit `site` and the default site is used.
+ *   - 200 != rendered: #dotParse swallows a VTL error into an empty HTTP 200, so a 200 with an empty
+ *     body is a failure, surfaced as pageRendered=false, not success.
+ *   - Two rendered layers that can disagree: each slot's rendered HTML (containers[].rendered[uuid])
+ *     vs. the assembled page.rendered. The disagreement IS the diagnosis (cache-stale) as opposed to
+ *     an empty slot (VTL error or no content).
+ *
+ * Returns a structured verdict — per-slot classification plus a one-line diagnosis with the next
+ * action — instead of two JSON blobs the caller has to compare by hand.
+ */
+export declare function verifyPage(options: VerifyPageOptions): Promise<VerifyPageManifest>;
+interface RenderResponse {
+    entity?: {
+        page?: {
+            rendered?: string;
+            pageURI?: string;
+            pageUrl?: string;
+            url?: string;
+        };
+        containers?: Record<string, RenderedContainer>;
+        layout?: {
+            body?: {
+                rows?: LayoutRow[];
+            };
+        };
+        urlContentMap?: {
+            identifier?: string;
+            inode?: string;
+        } | null;
+    };
+}
+interface RenderedContainer {
+    /** Per-slot rendered HTML, keyed by uuid (ContainerRendered.getRendered()). */
+    rendered?: Record<string, string>;
+    /** Per-slot placed contentlets, keyed by uuid (ContainerRaw.getContentletsMap()). */
+    contentlets?: Record<string, Array<{
+        identifier?: string;
+    }>>;
+}
+/** Assemble the verdict manifest from a render response. Pure — no I/O, so it is unit-testable. */
+export declare function buildManifest(input: {
+    path: string;
+    uri: string;
+    siteLabel: string;
+    mode: VerifyMode;
+    languageId: number;
+    status: number;
+    body: RenderResponse;
+    includeHtml?: boolean;
+}): VerifyPageManifest;
+export {};

package/src/tools/operations/shared/asset-common.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What `uploadAssets` and `downloadAssets` share: the entries their manifests are made of, the
+ * dotCMS path form both accept, and how a manifest is finished.
+ */
+export interface AssetManifestFile {
+    path: string;
+    bytes: number;
+    identifier?: string;
+}
+export interface AssetManifestFailure {
+    path: string;
+    error: string;
+}
+export interface AssetManifestSkipped {
+    path: string;
+    reason: string;
+}
+export declare function normalizeDotCMSPath(input: string): {
+    siteQualified?: string;
+    path: string;
+};
+export declare function sumBytes(files: AssetManifestFile[]): number;
+export declare function sortManifest<T extends {
+    files: AssetManifestFile[];
+    failures: AssetManifestFailure[];
+    skipped?: AssetManifestSkipped[];
+    notLive?: AssetManifestFile[];
+}>(manifest: T): T;

package/src/tools/operations/shared/glob.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `include` glob filter the asset operations share: `upload_assets` matches it against
+ * local paths relative to `src`, `download_assets` against dotCMS paths relative to the folder.
+ */
+/**
+ * Split an `include` string into its comma-separated patterns — but NOT on commas inside a brace
+ * group, so `*.{png,webp,jpg}` stays one pattern while `*.vtl,*.scss` is two. Exported for tests.
+ */
+export declare function splitIncludePatterns(include?: string): string[];
+/**
+ * Build a matcher over relative POSIX paths from a comma-separated `include` string. A file matches
+ * if it matches ANY pattern. No `include` → matches everything. Exported for tests.
+ *
+ * Supports the glob features callers reasonably assume from a standard glob:
+ *   - `*`  matches any run of chars WITHIN a path segment (does not cross `/`)
+ *   - `**` matches across segments, including zero (so a leading globstar also matches a top-level file)
+ *   - `?`  matches a single non-`/` char
+ *   - `{png,webp,jpg}` brace expansion (alternation)
+ * A pattern with no `/` matches the file's basename anywhere in the tree; a pattern with a `/` is
+ * anchored at the root of `src`.
+ */
+export declare function includeMatcher(include?: string): (rel: string) => boolean;

package/src/tools/operations/shared/local-root.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Refuse `path` when it resolves outside `root`. No `root` means no boundary — for trusted,
+ * direct callers of the operations; the tools always set one.
+ */
+export declare function assertInsideRoot(root: string | undefined, label: 'src' | 'dest', path: string): Promise<void>;
+/**
+ * Refuse to write `file` when it would land outside `root`: its directory resolves elsewhere,
+ * or the file itself is a symlink — `writeFile` follows one, so a link planted inside the
+ * destination would otherwise redirect the write anywhere.
+ */
+export declare function assertWritableInsideRoot(root: string | undefined, file: string): Promise<void>;

package/src/tools/operations/shared/page-common.d.ts

@@ -0,0 +1,45 @@
+import type { DotCMSColumnContainer } from '@dotcms/types';
+import type { DotCMSRuntime } from '../../../runtime';
+/**
+ * Response shapes and probes shared by more than one page tool.
+ *
+ * Small on purpose: these are the pieces that were previously written out twice and had
+ * already started to drift, not a general dumping ground for page types.
+ */
+/**
+ * One row of a page layout, as `/api/v1/page/json` and `/api/v1/page/render` return it.
+ *
+ * Hoisted here because `page-verify` and `page-place-content` declared byte-identical
+ * copies, which meant two tools parsing the SAME response through two shapes nobody kept in
+ * step.
+ *
+ * The innermost element is DERIVED from `DotCMSColumnContainer` — the SDK's own page-asset
+ * contract — so a change to the container shape upstream fails here at compile time instead
+ * of drifting silently. `import type` erases at build, so this costs nothing at runtime.
+ *
+ * The surrounding optionality stays hand-written, and that is deliberate: the canonical
+ * `DotPageAssetLayoutRow` declares `columns` (and every field below it) as REQUIRED, which
+ * would be a lie about a response this code has not validated. Everything here is optional
+ * because the payload is unproven at compile time. `historyUUIDs` is picked off for the same
+ * reason — these tools never read it, and requiring it would assert a field that may be
+ * absent. `@dotcms/dotcms-models` also ships a `DotLayoutRow`, but it is the editor-side
+ * model (fully required, and its barrel pulls Angular into the transitive graph), so it is
+ * the wrong contract for a tool parsing a REST response.
+ */
+export interface LayoutRow {
+    columns?: Array<{
+        containers?: Array<Pick<DotCMSColumnContainer, 'identifier' | 'uuid'>>;
+    }>;
+}
+/**
+ * Whether a contentlet is published.
+ *
+ * THROWS on a failed read, and that is the contract callers depend on rather than an
+ * oversight. The two previous copies disagreed here: one swallowed every error into `false`,
+ * which conflates "this is not live" with "we could not find out" — and for the transfer
+ * manifest those are opposite conclusions, since a read failure reported as not-live sends
+ * the caller off to re-publish assets that were already fine. `upload-assets` needs the
+ * distinction, so the shared primitive is the honest one and the caller that wants a
+ * best-effort answer catches for itself.
+ */
+export declare function isContentLive(dotcms: DotCMSRuntime, identifier: string): Promise<boolean>;

package/src/tools/operations/shared/page-path.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Normalization for the page paths callers hand to the page tools.
+ *
+ * Shared because all three tools build a request URL by interpolating a caller-supplied path
+ * into an endpoint template — `/api/v1/page/render${uri}`, `/api/v1/page/json${uri}` — and
+ * only `page_create` was normalizing first. The two that were not had a live correctness bug
+ * and a latent security one:
+ *
+ *   - Live today: `page_verify({ path: '/a/../b' })` renders `/b` while the manifest reports
+ *     `/a/../b`, and a `#` silently truncates the path. The tool's whole job is to report on
+ *     the page it actually checked, so reporting a different path than it read is a
+ *     correctness failure, not a cosmetic one.
+ *   - Latent: `requestCore` policy-checks the RAW request string and normalizes afterwards,
+ *     so a path like `/../../../../api/v1/users/current` would pass an `/api/v1/page/` prefix
+ *     allowlist and then resolve somewhere else entirely. No `allow` policy is configured
+ *     today, which is the only reason this is not already exploitable — and adding one is the
+ *     natural next hardening step for this tool surface.
+ */
+/**
+ * The canonical form of a page path: leading slash, `.`/`..` collapsed, query and fragment
+ * dropped, percent-encoding decoded, encoded separators refused.
+ *
+ * Returned so the CALLER can report what it actually requested. A tool that normalizes for
+ * the request but echoes the raw input in its manifest is telling the model about a page it
+ * did not look at.
+ */
+export declare function normalizePagePath(path: string, label?: string): string;
+/**
+ * Split a page-relative URL into the parent folder and the leaf url stored on the page.
+ *
+ *   "/books/index" → { folder: "/books", url: "index", fullPath: "/books/index" }
+ *   "/books"       → { folder: "/books", url: "index", fullPath: "/books/index" }
+ *   "/about-us/"   → { folder: "/about-us", url: "index", fullPath: "/about-us/index" }
+ *   "/"            → { folder: "/", url: "index", fullPath: "/index" }
+ *
+ * Shares its normalization with {@link normalizePagePath} but NOT its output: the folder-vs-leaf
+ * decision is page-create's alone. The URL API preserves a trailing slash but does not know that
+ * "/about-us/" means a folder index while "/about-us" means a leaf url, and dotCMS pages always
+ * have a leaf url (commonly "index"), so a path with no explicit leaf gets one — matching how the
+ * admin UI and the rest of the platform address a folder's default page.
+ *
+ * Segments are returned DECODED here, because they become folder and page names rather than
+ * parts of a URL.
+ */
+export declare function splitUrlPath(urlPath: string): {
+    folder: string;
+    url: string;
+    fullPath: string;
+};

package/src/tools/operations/shared/resolve.d.ts

@@ -0,0 +1,43 @@
+import { type DotCMSRuntime } from '../../../runtime';
+import { type Endpoint } from '../../toolkit/endpoints';
+/**
+ * Every endpoint this module calls. Each operation that resolves a site or language includes
+ * these in its own list. `resolve.spec.ts` checks every request against them.
+ */
+export declare const RESOLVE_ENDPOINTS: readonly Endpoint[];
+/** A resolved site: the identifier the API needs, plus the hostname for manifests. */
+export interface ResolvedSite {
+    identifier: string;
+    hostname: string;
+}
+/**
+ * Resolve a site (hostname OR identifier) to its identifier + hostname.
+ *
+ * Order is deliberate — cheapest and least fallible first:
+ *   1. the session cache, when it actually has sites;
+ *   2. a direct `GET /api/v1/site/{id}` when the caller gave something UUID-shaped;
+ *   3. a filtered `GET /api/v1/site` lookup by hostname.
+ *
+ * Step 2 matters most for the reported failure: a caller who already knows the identifier
+ * should never be blocked by a cache, because the identifier is precisely what the
+ * downstream call needs and no lookup is required to use it.
+ */
+export declare function resolveSite(dotcms: DotCMSRuntime, site: string): Promise<ResolvedSite>;
+/**
+ * The instance's default site — what a path with no `//host` prefix means.
+ *
+ * The session cache first; then `GET /api/v1/site/defaultSite`, so a failed context load does
+ * not leave the caller unscoped. A failure of that read propagates as the instance error it is:
+ * falling back to "no site" would silently widen whatever the caller was about to scope.
+ */
+export declare function resolveDefaultSite(dotcms: DotCMSRuntime): Promise<ResolvedSite>;
+/**
+ * Resolve a language id against the instance.
+ *
+ * dotCMS silently falls back to its default language for an unknown id rather than
+ * rejecting it, so an unrecognised id does not fail — it quietly writes to a DIFFERENT
+ * language than the caller named while the manifest echoes the id they asked for. That is
+ * worth catching, but ONLY when the language list actually loaded: with an empty list the
+ * caller's explicit id is better evidence than our missing cache, so it is passed through.
+ */
+export declare function resolveLanguageId(dotcms: DotCMSRuntime, languageId?: number): Promise<number>;

package/src/tools/operations/upload-assets.d.ts

@@ -0,0 +1,64 @@
+import { type AssetManifestFailure, type AssetManifestFile, type AssetManifestSkipped } from './shared/asset-common';
+import { type DotCMSRuntime } from '../../runtime';
+import { type Endpoint } from '../toolkit/endpoints';
+/**
+ * Every endpoint `uploadAssets` calls — the `upload_assets` tool enforces exactly this list,
+ * and `upload-assets.spec.ts` checks every request against it. Add a request, add it here.
+ */
+export declare const UPLOAD_ASSETS_ENDPOINTS: readonly Endpoint[];
+export interface UploadAssetsOptions {
+    dotcms: DotCMSRuntime;
+    /** Absolute local directory the files are read from. */
+    src: string;
+    /** Host-qualified destination folder, e.g. `//demo.dotcms.com/application/themes/travel`. */
+    dest: string;
+    /** Comma-separated glob filter, matched against each path relative to `src`. */
+    include?: string;
+    /** Publish (`/api/v2/assets/publish`) rather than only save. */
+    publish: boolean;
+    /** After publishing, confirm each asset reports live. */
+    verify: boolean;
+    /**
+     * Directory `src` must be inside — after symlinks resolve. Omit only when YOU chose `src`;
+     * the `upload_assets` tool always sets it.
+     */
+    root?: string;
+    /**
+     * Largest file to send, in bytes. A larger one is recorded as a failure before it is read,
+     * and the rest still upload. Each file is held in memory once while it is sent, so this
+     * bounds the upload's memory. Unbounded when omitted; the `upload_assets` tool always sets it.
+     */
+    maxFileBytes?: number;
+    /**
+     * Most files one upload sends (after `include`). More is refused before anything is sent,
+     * and the directory walk stops as soon as it is exceeded. Unbounded when omitted; the
+     * `upload_assets` tool always sets it.
+     */
+    maxFiles?: number;
+    /**
+     * Most entries — files and directories — the walk of `src` visits, whether or not
+     * `include` selects them. More is refused before anything is sent. `maxFiles` alone does
+     * not bound the walk: a vast `src` with a narrow `include` matches few files and is walked
+     * to the end. Unbounded when omitted; the `upload_assets` tool always sets it.
+     */
+    maxScannedEntries?: number;
+}
+/** What `uploadAssets` returns — never the file bytes, only what landed and what did not. */
+export interface UploadAssetsManifest {
+    src: string;
+    dest: string;
+    count: number;
+    bytes: number;
+    files: AssetManifestFile[];
+    failures: AssetManifestFailure[];
+    skipped: AssetManifestSkipped[];
+    /** Published assets that did not report live when verified. */
+    notLive: AssetManifestFile[];
+    warnings: string[];
+}
+/**
+ * Upload every file under a local directory as dotCMS file assets, preserving relative
+ * paths. Files are saved or published one at a time; a failed file is recorded in the
+ * manifest rather than aborting the batch.
+ */
+export declare function uploadAssets(options: UploadAssetsOptions): Promise<UploadAssetsManifest>;

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

@@ -0,0 +1,56 @@
+import type { RequestCallEvent } from '../../runtime';
+/**
+ * A value given as-is, or a resolver read on every tool call — for tokens that rotate, come
+ * from a secrets manager, or are read lazily from a host's own configuration. A resolver may
+ * return `undefined` (e.g. an unset environment variable); the call then fails with a readable
+ * `CONFIGURATION` failure instead of the host crashing.
+ */
+export type Resolvable<T> = T | (() => T | undefined | Promise<T | undefined>);
+/** Who is calling which dotCMS instance — everything a tool needs that is not about the tool. */
+export interface DotCMSConnectionConfig {
+    /** dotCMS instance URL. */
+    url: Resolvable<string>;
+    /** dotCMS API token. Injected host-side — it never reaches the model or the sandbox. */
+    token: Resolvable<string>;
+    /** Observability hook fired around each request (token and sensitive bodies are never passed). */
+    onCall?: (event: RequestCallEvent) => void;
+    /** Called when loading instance context (sites, content types, …) fails. */
+    onContextError?: (label: string, error: unknown) => void;
+    /**
+     * Called when a `url` / `token` resolver throws — the host's view of the failure. The model
+     * is only told the connection could not be resolved: a resolver's own error (a secrets
+     * manager's message) can carry paths, key names or identifiers, so its detail comes here.
+     */
+    onResolveError?: (field: 'url' | 'token', error: unknown) => void;
+}
+/**
+ * A dotCMS connection: created once, handed to every tool. Holds no state and makes no request
+ * — so a host serving many users creates one per session, each with that user's token.
+ */
+export interface DotCMSConnection {
+    readonly __dotcmsConnection: true;
+    readonly config: Readonly<DotCMSConnectionConfig>;
+}
+/**
+ * Describe the dotCMS instance and identity the tools act as.
+ *
+ * ```ts
+ * const dotcms = dotcmsConnection({ url, token: () => secrets.get('dotcms') });
+ * const tools = [searchTool(dotcms), pageVerifyTool(dotcms)];
+ * ```
+ *
+ * Nothing is read, validated or fetched here — the values are resolved on each tool call.
+ */
+export declare function dotcmsConnection(config: DotCMSConnectionConfig): DotCMSConnection;
+/** Whether `value` came from {@link dotcmsConnection}. */
+export declare function isDotCMSConnection(value: unknown): value is DotCMSConnection;
+/**
+ * The URL and token for one call. Throws `ConfigurationError` when the tool was given no
+ * connection at all (a JavaScript caller, or a cast) or a resolver failed; an EMPTY value is
+ * left to `createToolRuntime`, which reports it the same way.
+ */
+export declare function resolveConnection(connection: unknown): Promise<{
+    url: string;
+    token: string;
+    config: DotCMSConnectionConfig;
+}>;

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

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { type DotCMSConnection } from './connection';
+import { type Endpoint } from './endpoints';
+import { type DotCMSRuntime } from '../../runtime';
+import type { DotCMSTool, DotCMSToolAnnotations, ExecuteToolOptions, RequestToolOptions } from './types';
+/** The union of every factory's options — what `createTool` may find on any of them. */
+type AnyToolOptions = Partial<ExecuteToolOptions> & Partial<RequestToolOptions>;
+/** What a tool's handler receives for one call. */
+export interface ToolContext<TOptions extends object> {
+    /** The options the tool's factory was called with. */
+    options: TOptions;
+    /**
+     * Build this call's runtime from the resolved connection. Throws `ConfigurationError` when
+     * the URL or token is empty, which `execute` turns into a `CONFIGURATION` failure.
+     */
+    runtime(runtimeOptions?: {
+        timeout?: number;
+        includeSpec?: boolean;
+    }): DotCMSRuntime;
+}
+/**
+ * The static half of a tool — everything except the connection and options a consumer passes
+ * its factory. `handler` receives input that already passed `inputSchema`, and anything it
+ * throws becomes a `ToolFailure`.
+ */
+export interface ToolDefinition<TInput extends z.ZodObject, TResult, TOptions extends object> {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: TInput;
+    annotations: DotCMSToolAnnotations;
+    /**
+     * Every endpoint the tool calls — enforced, not documented: any other request fails with
+     * a `POLICY` failure before it reaches the wire. `'model-chosen'` is for `execute` alone,
+     * where the model picks the endpoints and the consumer's `allow` bounds them instead.
+     */
+    endpoints: readonly Endpoint[] | 'model-chosen';
+    /** Appended to the rejection message when a request falls outside `endpoints`. */
+    endpointHint?: string;
+    /**
+     * The tool's text form, for a tool whose result IS text (`search`, `execute`): shown to the
+     * model as text rather than as a JSON string escaped inside an object. Omit it and results
+     * are shown as structured JSON. Declared here, typed against `TResult`, so the choice is the
+     * tool's — never inferred from what a result happens to look like.
+     */
+    toText?: (result: TResult) => string;
+    handler(input: z.output<TInput>, ctx: ToolContext<TOptions>): Promise<TResult>;
+}
+/** Identity helper that infers the generics, so each handler sees its own input type. */
+export declare function defineTool<TInput extends z.ZodObject, TResult, TOptions extends object = object>(definition: ToolDefinition<TInput, TResult, TOptions>): ToolDefinition<TInput, TResult, TOptions>;
+/**
+ * Turn a definition, a connection and a consumer's options into the tool a framework
+ * registers.
+ *
+ * Cheap and side-effect free: nothing is resolved or fetched here. The connection is resolved
+ * inside `execute`, on every call — so a host started without credentials still boots and
+ * lists its tools, and each call reports the `CONFIGURATION` problem instead of the host
+ * crashing at startup.
+ *
+ * The one thing checked here is the consumer's own static `allow` list (`executeTool`), which
+ * becomes the tool's policy now: an entry that is not a path throws a `ValidationError`, so a
+ * malformed security boundary fails at startup instead of opening the API (see
+ * `toRequestPolicy`).
+ */
+export declare function createTool<TInput extends z.ZodObject, TResult, TOptions extends AnyToolOptions>(definition: ToolDefinition<TInput, TResult, TOptions>, connection: DotCMSConnection, options: TOptions): DotCMSTool<TInput, TResult>;
+export {};

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

@@ -0,0 +1,52 @@
+import { type RequestPolicy } from '../../adapter/request-core';
+import type { RuntimeAllow } from '../../runtime';
+/**
+ * One endpoint a tool may call: an HTTP method and a path pattern, e.g.
+ * `'POST /api/v1/page/{pageId}/content'`.
+ *
+ * In the pattern, `{name}` matches exactly one path segment and a trailing `/**` matches
+ * anything below that prefix. Patterns are matched against the RESOLVED path the request core
+ * hands a policy (dot-segments and encoded dots already collapsed), so `/**` cannot be used
+ * to climb out of its prefix.
+ */
+export type Endpoint = `${'GET' | 'POST' | 'PUT' | 'DELETE'} /${string}`;
+/**
+ * What loading instance context reads. The runtime does it on a tool's behalf, so every tool
+ * that touches context includes these — they are the one endpoint list the toolkit owns.
+ * Every other list lives next to the operation that makes those requests.
+ */
+export declare const CONTEXT_ENDPOINTS: readonly Endpoint[];
+/** Whether `req` is one of `endpoints`. */
+export declare function matchesEndpoint(endpoints: readonly Endpoint[], req: {
+    method: string;
+    path: string;
+}): boolean;
+/**
+ * The calls `endpoints` would refuse, as `METHOD path` strings — empty when every call is
+ * covered. Paths are resolved the way the request core resolves them before its policy check.
+ *
+ * What keeps an allow-list honest: the operation specs run every call their fakes see through
+ * this, so a request added to an operation without adding it to the tool's endpoints fails
+ * the build instead of being refused in production.
+ */
+export declare function unlistedCalls(endpoints: readonly Endpoint[], calls: ReadonlyArray<{
+    method?: string;
+    path: string;
+}>): string[];
+/**
+ * The policy for a fixed-purpose tool: exactly the endpoints it owns, and nothing else.
+ *
+ * The consumer never configures this — the tool knows what it calls. It is least privilege by
+ * construction: a bug in `page_verify`, or a page path shaped to reach somewhere else, cannot
+ * get past the render and site-lookup endpoints the tool actually needs.
+ */
+export declare function toolPolicy(toolName: string, endpoints: readonly Endpoint[], hint?: string): RequestPolicy;
+/**
+ * The policy for `execute`, where the MODEL chooses the endpoints: the consumer's `allow`
+ * bounds its code, plus the context reads the runtime makes on the tool's behalf — so a narrow
+ * `allow` never silently empties the `sites` / `contentTypes` globals the code relies on.
+ * Those reads expose nothing the code does not already hold as globals.
+ *
+ * No `allow` means no policy: the model's code may call anything the token permits.
+ */
+export declare function modelChosenPolicy(allow: RuntimeAllow | undefined): RequestPolicy | undefined;

package/src/tools/toolkit/lenient-boolean.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/**
+ * A boolean that also accepts the string forms tool-calling clients (MCP and others) often
+ * send ("true"/"false"/"1"/"0"). Plain `z.coerce.boolean()` is wrong here: it uses JS
+ * truthiness, so the string "false" becomes `true`. This maps the string forms to their
+ * intended value and leaves real booleans untouched.
+ *
+ * The default is declared twice, on purpose. The inner one covers a blank string, which the
+ * preprocess turns into `undefined` AFTER the outer wrapper has already let it through. The
+ * outer one is what marks the field optional in the generated JSON Schema: a preprocess hides
+ * the inner default from `z.toJSONSchema`, so without it the schema a model reads lists the
+ * field as REQUIRED even though omitting it is the normal case.
+ */
+export declare const lenientBoolean: (defaultValue: boolean) => z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDefault<z.ZodBoolean>>>;

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

@@ -0,0 +1,32 @@
+import { type ToolFailure } from './tool-runtime';
+/**
+ * What the two code tools (`search`, `execute`) resolve to: the capped text of the model's
+ * code's result. An object rather than a bare string because some frameworks (Google ADK)
+ * require tool results to be objects.
+ */
+export interface CodeToolResult {
+    result: string;
+}
+/** A JSON value: the shape the Vercel AI SDK requires of a `json` model output. */
+export type JSONValue = null | string | number | boolean | {
+    [key: string]: JSONValue | undefined;
+} | JSONValue[];
+/** A tool's model-facing output, in the shape the Vercel AI SDK's `toModelOutput` returns. */
+export type ToolModelOutput = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'json';
+    value: JSONValue;
+};
+/**
+ * How a tool shows one of its results to the model — the one place that is decided.
+ *
+ * `toText` is the TOOL's declaration that it has a text form, typed against its own result:
+ * nothing is inferred from the value's shape, so a result can never be mistaken for text
+ * because it happens to look like one. A tool without it is shown as structured JSON, and so
+ * is a failure from any tool.
+ */
+export declare function renderToolOutput<TResult>(toText: ((result: TResult) => string) | undefined, output: TResult | ToolFailure): ToolModelOutput;
+/** A model output as the text a text-only transport (an MCP `content` block) carries. */
+export declare function modelOutputText(output: ToolModelOutput): string;