@elytracms/studio 0.0.56 → 0.0.58

package/dist/lib/ai/tools.js

@@ -1,74 +1,559 @@
-/** The schema name the planner call carries — how a FakeProvider tells plan vs. author. */
-export const PLANNER_SCHEMA_NAME = 'create_flow_action';
 /**
- * The structured-output schema for ONE planning step. `action` is a closed enum and
- * `collection` is leashed to the known collection ids, so the model can neither invent
- * an action nor target a collection that does not exist.
+ * The narrow tool set the assistant works against (EC-199, reshaped by EC-334).
+ *
+ * Per the ratified AD, tools execute CLIENT-side against the operations layer with
+ * the user's own session. This module carries the three pieces of that contract:
+ *
+ *  1. {@link chatToolDefinitions} — the SDK-native tool DEFINITIONS the route's
+ *     chat branch declares in `streamText`, deliberately WITHOUT `execute`, so the
+ *     SDK forwards every call to the client (the route stays a zero-data-access
+ *     proxy). Plain `{ description, inputSchema }` objects with zod schemas —
+ *     structurally the SDK's `FunctionTool`, with no SDK import (bundle discipline).
+ *  2. {@link ChatToolReaders} — the operations-backed read interface the studio
+ *     binds client-side (search / list / get). Reads only — the engine never gains
+ *     a write path; apply is a separate, human-gated draft write.
+ *  3. {@link createChatToolExecutor} — the client executor map `useChat`'s
+ *     `onToolCall` dispatches into. Readers pass through; the terminal tools run
+ *     the deterministic engines (`applyContentWithShape` / `translateDocument` /
+ *     `buildUpdateProposal`) and return a COMPACT proposal summary as the tool
+ *     output — the full proposal goes to the review UI via
+ *     `onProposal(toolCallId, …)`, never to the model.
+ *
+ * EC-378: `updateFields` is the edit-flow terminal tool — the model authors
+ * per-field changes directly (it has `getDocument` output + the conversation as
+ * context); the executor reads the CURRENT document, builds a validated update
+ * proposal (`buildUpdateProposal`), and hands it to the review sink. Its target
+ * (and `getDocument`'s) may be omitted to mean the document currently open in
+ * the editor — resolved via the {@link ChatToolExecutorOptions.currentDocument}
+ * seam ({@link resolveDocumentTarget}); the context block the panel injects is
+ * ADVISORY, the resolution here is what makes "this document" deterministic.
+ *
+ * The EC-199 planner enum/schema (`plannerSchema` / `parsePlannerAction`) retired
+ * with the hand-rolled orchestrator (EC-334 slice 2).
  */
-export function plannerSchema(collectionIds) {
+import { z } from 'zod';
+import { resolveDocumentTitle } from '@elytracms/core/cms-core';
+import { parseRichTextValue, richTextValueToMarkdownProse } from '@elytracms/core/rich-text';
+import { applyContentWithShape } from './apply-content.js';
+import { translateDocument } from './translate-document.js';
+import { buildUpdateProposal } from './update-fields.js';
+import { aiProvenance } from './provenance.js';
+/** Per-search result cap (protects the wire — results become model context). */
+export const DEFAULT_SEARCH_LIMIT = 20;
+/**
+ * The tool set the native chat branch declares (EC-334). No `execute` on any entry:
+ * the SDK forwards each call to the client, which executes reads against the
+ * operations layer with the user's session and posts the result back; the terminal
+ * tools (`createDocument` / `translateDocument`) run the deterministic engines
+ * client-side and return a compact proposal summary as the tool output. The route
+ * itself never executes anything.
+ *
+ * Collections are NOT enum-leashed here — the route has zero data access, so it has
+ * no catalog; the catalog reaches the model through the request `context` (system
+ * prompt), and every id a proposal references must come from a tool RESULT
+ * (client-validated; `applyContentWithShape` still enum-leashes relation ids).
+ */
+export const chatToolDefinitions = {
+    searchDocuments: {
+        description: 'Search documents in a collection. Use it to find the REAL ids a relation may ' +
+            'reference, or to locate an existing document — never invent an id. Returns ' +
+            '{ id, title } summaries.',
+        inputSchema: z.object({
+            collection: z
+                .string()
+                .describe('Target collection id (from the catalog in the system context).'),
+            query: z.string().optional().describe('Optional search text (title match).'),
+            limit: z.number().int().positive().optional().describe('Max results.'),
+        }),
+    },
+    listAssets: {
+        description: 'List or search assets (images, files). Use it to find REAL asset ids — never ' +
+            'invent one. Returns { id, title } summaries.',
+        inputSchema: z.object({
+            query: z.string().optional().describe('Optional search text.'),
+            limit: z.number().int().positive().optional().describe('Max results.'),
+        }),
+    },
+    getDocument: {
+        description: 'Fetch one full document (values + localized values + block ids) by collection and ' +
+            'id. Omit both to read the document currently open in the editor. Rich-text field ' +
+            'values are returned as markdown strings where faithfully expressible.',
+        inputSchema: z.object({
+            collection: z
+                .string()
+                .optional()
+                .describe('Collection id. Omit to target the currently open document.'),
+            id: z
+                .string()
+                .optional()
+                .describe('Document id (from a searchDocuments result). Omit to target the currently open document.'),
+        }),
+    },
+    createDocument: {
+        description: 'Author a NEW document in a collection as a reviewable draft proposal. Terminal ' +
+            'step of a creation request — call it once you have gathered the real ids you ' +
+            'need. Returns a compact proposal summary.',
+        inputSchema: z.object({
+            collection: z.string().describe('Target collection id.'),
+            instruction: z.string().describe('What to write, refining the user request.'),
+        }),
+    },
+    updateFields: {
+        description: 'Change specific fields of an EXISTING document as a reviewable proposal — THE ' +
+            'tool for every edit request (change / fix / remove / replace / rewrite wording, ' +
+            'values, or a page-builder element). Call getDocument first to see the current ' +
+            'values (and block ids), then pass ONLY the fields that change. A block prop ' +
+            '(e.g. a Hero headline) is addressed as field + blockId + prop. Omit collection ' +
+            'and id to target the document currently open in the editor. A rich-text field ' +
+            'takes the FULL new value as a MARKDOWN string (headings, lists, links, bold/italic, ' +
+            'blockquotes — no images, code, tables, or HTML).',
+        inputSchema: z.object({
+            collection: z
+                .string()
+                .optional()
+                .describe('Collection id. Omit to target the currently open document.'),
+            id: z
+                .string()
+                .optional()
+                .describe('Document id. Omit to target the currently open document.'),
+            changes: z
+                .array(z.object({
+                field: z.string().describe('Field name from the collection schema.'),
+                locale: z
+                    .string()
+                    .optional()
+                    .describe("Locale of a LOCALIZED field (defaults to the editor's working locale)."),
+                blockId: z
+                    .string()
+                    .optional()
+                    .describe('For a blocks field: the id of the block to change (from getDocument).'),
+                prop: z
+                    .string()
+                    .optional()
+                    .describe('With blockId: the component prop to change.'),
+                value: z
+                    .unknown()
+                    .optional()
+                    .describe('The new value (a rich-text field takes a markdown string). null clears the field/prop.'),
+            }))
+                .min(1)
+                .describe('The field changes — only what changes, never the whole document.'),
+        }),
+    },
+    translateDocument: {
+        description: 'Fill the EMPTY locale values of an existing document (search for it first to ' +
+            'get its id). Only for translation requests — never for edits (use updateFields ' +
+            'to change existing content). Returns a compact proposal summary.',
+        inputSchema: z.object({
+            collection: z.string().describe('Collection id.'),
+            id: z.string().describe('Document id (from a searchDocuments result).'),
+            locale: z.string().optional().describe('Target locale (defaults to the active one).'),
+        }),
+    },
+};
+/**
+ * Resolve a tool call's target document from its (optional) input coordinates
+ * and the current-document seam (EC-378). Deterministic:
+ *
+ *  - both given → use them verbatim;
+ *  - both omitted → the currently open document (error when none is open);
+ *  - `collection` given with `id` omitted → the open document ONLY when the
+ *    collections match — a named collection must never silently cross onto a
+ *    different open document.
+ *
+ * Pure — tested directly; `getDocument` and `updateFields` share it.
+ */
+export function resolveDocumentTarget(input, current) {
+    if (input.collection !== undefined && input.id !== undefined) {
+        return { ok: true, ref: { collection: input.collection, id: input.id } };
+    }
+    if (!current) {
+        return {
+            ok: false,
+            errorText: 'No target document — pass collection and id, or ask the user to open the document in the editor.',
+        };
+    }
+    if (input.collection !== undefined && input.collection !== current.collection) {
+        return {
+            ok: false,
+            errorText: `The open document is in collection "${current.collection}", not "${input.collection}" — pass the document id explicitly.`,
+        };
+    }
+    return { ok: true, ref: { collection: current.collection, id: input.id ?? current.id } };
+}
+export function createChatCandidateStore() {
+    const searched = new Map();
+    const searchedAssets = new Map();
     return {
-        type: 'object',
-        properties: {
-            action: {
-                type: 'string',
-                enum: ['searchDocuments', 'listAssets', 'createDocument', 'translateDocument', 'respond'],
-                description: 'searchDocuments: find real ids for a relation target before creating. ' +
-                    'listAssets: find real asset ids. createDocument: author the document once ' +
-                    'you have what you need. translateDocument: fill the empty locale values of an ' +
-                    'existing document (search for it first to get its id). ' +
-                    'respond: reply without creating anything.',
+        record(collection, results) {
+            const byId = searched.get(collection) ?? new Map();
+            for (const result of results)
+                byId.set(result.id, result);
+            searched.set(collection, byId);
+        },
+        recordAssets(results) {
+            for (const result of results)
+                searchedAssets.set(result.id, result);
+        },
+        candidatesFor(collection) {
+            const candidates = {};
+            for (const field of collection.fields) {
+                if (field.type !== 'relation')
+                    continue;
+                const found = searched.get(field.target);
+                if (!found || found.size === 0)
+                    continue;
+                candidates[field.name] = [...found.values()].map((r) => ({ id: r.id, ...(r.title ? { label: r.title } : {}) }));
+            }
+            return candidates;
+        },
+        assetCandidatesFor(collection) {
+            const candidates = {};
+            if (searchedAssets.size === 0)
+                return candidates;
+            const pool = [...searchedAssets.values()].map((a) => ({ id: a.id, ...(a.title ? { label: a.title } : {}) }));
+            for (const field of collection.fields) {
+                if (field.type !== 'asset')
+                    continue;
+                candidates[field.name] = pool;
+            }
+            return candidates;
+        },
+    };
+}
+function issueSummary(issues) {
+    return issues
+        .slice(0, 5)
+        .map((issue) => issue.message)
+        .join('; ');
+}
+/**
+ * The MODEL-facing view of a document (EC-379): rich-text field values are
+ * projected to markdown strings — but ONLY when the engine's loss-guarded
+ * inverse can express them faithfully (subset-only content, round-trip proven).
+ * A document carrying embeds, internal `ref` links, or out-of-subset marks keeps
+ * its `{ version, doc }` envelope, so nothing the model later echoes back can
+ * silently lose structure. Applies to the `getDocument` TOOL OUTPUT only; the
+ * proposal/apply paths always read the raw stored document.
+ */
+export function projectRichTextAsMarkdown(document, collection) {
+    const richTextFields = collection.fields
+        .filter((field) => field.type === 'richText')
+        .map((field) => field.name);
+    if (richTextFields.length === 0)
+        return document;
+    const mapBucket = (bucket) => {
+        let next = bucket;
+        for (const name of richTextFields) {
+            const value = next[name];
+            if (value === undefined || value === null)
+                continue;
+            const parsed = parseRichTextValue(value);
+            if (!parsed.ok)
+                continue;
+            const markdown = richTextValueToMarkdownProse(parsed.value);
+            if (markdown === undefined)
+                continue; // not faithfully expressible → keep the envelope
+            if (next === bucket)
+                next = { ...bucket };
+            next[name] = markdown;
+        }
+        return next;
+    };
+    const values = mapBucket(document.values);
+    const localized = document.localized
+        ? Object.fromEntries(Object.entries(document.localized).map(([locale, bucket]) => [locale, mapBucket(bucket)]))
+        : undefined;
+    return { ...document, values, ...(localized ? { localized } : {}) };
+}
+/**
+ * Build the client executor map. Every entry validates its input against
+ * {@link chatToolDefinitions}' zod schema (the route validates UIMessages only
+ * structurally — deep input validation is the client's), executes with the
+ * user's session, and returns a JSON-safe outcome. EC-378's `updateFields`
+ * lands as one more case in this dispatch.
+ */
+export function createChatToolExecutor(options) {
+    const searchLimit = options.searchLimit ?? DEFAULT_SEARCH_LIMIT;
+    function collectionById(id) {
+        return options.collections.find((c) => c.id === id);
+    }
+    async function searchDocuments(input) {
+        if (!collectionById(input.collection)) {
+            return { ok: false, errorText: `Unknown collection "${input.collection}" — use a collection id from the catalog.` };
+        }
+        const limit = Math.min(input.limit ?? searchLimit, searchLimit);
+        const results = (await options.readers.searchDocuments({
+            collection: input.collection,
+            ...(input.query ? { query: input.query } : {}),
+            limit,
+        })).slice(0, limit);
+        options.candidates.record(input.collection, results);
+        return { ok: true, output: results };
+    }
+    async function listAssets(input) {
+        const limit = Math.min(input.limit ?? searchLimit, searchLimit);
+        const results = (await options.readers.listAssets({
+            ...(input.query ? { query: input.query } : {}),
+            limit,
+        })).slice(0, limit);
+        // EC-381 — leash asset fields to what the model actually searched, exactly as
+        // searchDocuments feeds the relation store.
+        options.candidates.recordAssets(results);
+        return { ok: true, output: results };
+    }
+    async function getDocument(input) {
+        if (!options.readers.getDocument) {
+            return { ok: false, errorText: 'Reading documents is not available here.' };
+        }
+        const target = resolveDocumentTarget(input, options.currentDocument?.());
+        if (!target.ok)
+            return { ok: false, errorText: target.errorText };
+        const document = await options.readers.getDocument(target.ref);
+        if (!document) {
+            return {
+                ok: false,
+                errorText: `Document "${target.ref.collection}/${target.ref.id}" was not found.`,
+            };
+        }
+        // EC-379: the model reads (and re-authors) rich text as markdown.
+        const collection = collectionById(target.ref.collection);
+        return { ok: true, output: collection ? projectRichTextAsMarkdown(document, collection) : document };
+    }
+    /** EC-378 — the edit-flow terminal tool: current doc + model-authored changes → validated proposal. */
+    async function updateFields(toolCallId, input) {
+        if (!options.readers.getDocument) {
+            return { ok: false, errorText: 'Reading documents is not available here.' };
+        }
+        const target = resolveDocumentTarget(input, options.currentDocument?.());
+        if (!target.ok)
+            return { ok: false, errorText: target.errorText };
+        const collection = collectionById(target.ref.collection);
+        if (!collection) {
+            return {
+                ok: false,
+                errorText: `Unknown collection "${target.ref.collection}" — use a collection id from the catalog.`,
+            };
+        }
+        const document = await options.readers.getDocument(target.ref);
+        if (!document) {
+            return {
+                ok: false,
+                errorText: `Document "${target.ref.collection}/${target.ref.id}" was not found.`,
+            };
+        }
+        const result = buildUpdateProposal({
+            registry: options.registry,
+            collection,
+            document,
+            changes: input.changes,
+            candidates: options.candidates.candidatesFor(collection),
+            assetCandidates: options.candidates.assetCandidatesFor(collection),
+            ...(options.locale ? { locale: options.locale } : {}),
+            ...(options.localeConfig ? { localeConfig: options.localeConfig } : {}),
+            ...(options.validateRichTextEmbeds
+                ? { validateRichTextEmbeds: options.validateRichTextEmbeds }
+                : {}),
+            ...(options.validateComposition ? { validateComposition: options.validateComposition } : {}),
+            ...(options.store ? { store: options.store } : {}),
+        });
+        if (!result.ok) {
+            return {
+                ok: false,
+                errorText: `The proposed changes did not pass validation: ${issueSummary(result.issues)}`,
+            };
+        }
+        if (result.kind === 'no-change') {
+            return {
+                ok: true,
+                output: {
+                    status: 'no-change',
+                    note: 'The requested change matches the current values — there is nothing to update.',
+                },
+            };
+        }
+        options.onProposal(toolCallId, {
+            origin: 'update',
+            collection: collection.id,
+            documentId: document.id,
+            patch: result.patch,
+            provenance: aiProvenance(options.provider),
+            attempts: 1,
+            issues: result.issues,
+            before: result.before,
+        });
+        // Compact summary only — the full patch goes to the review UI, not the model.
+        const titleValues = {
+            ...result.patch.values,
+            ...(options.locale ? result.patch.localized?.[options.locale] : {}),
+        };
+        return {
+            ok: true,
+            output: {
+                status: 'proposed',
+                collection: collection.id,
+                documentId: document.id,
+                title: resolveDocumentTitle(collection, titleValues, document.id),
+                changedFields: result.changedFields,
+                note: 'Update proposal created; the editor reviews and applies it in the studio. Summarize the change briefly — do not repeat the content.',
+            },
+        };
+    }
+    async function createDocument(toolCallId, input) {
+        const collection = collectionById(input.collection);
+        if (!collection) {
+            return { ok: false, errorText: `Unknown collection "${input.collection}" — use a collection id from the catalog.` };
+        }
+        const documentId = options.mintDocumentId(collection.id);
+        const knowledge = options.knowledge?.();
+        const result = await applyContentWithShape({
+            provider: options.provider,
+            registry: options.registry,
+            collection,
+            documentId,
+            instruction: input.instruction,
+            ...(knowledge ? { knowledge } : {}),
+            ...(options.components ? { components: options.components } : {}),
+            candidates: options.candidates.candidatesFor(collection),
+            // EC-381 — asset/image fields are leashed to searched library assets.
+            assetCandidates: options.candidates.assetCandidatesFor(collection),
+            ...(options.locale ? { locale: options.locale } : {}),
+            ...(options.validateRichTextEmbeds
+                ? { validateRichTextEmbeds: options.validateRichTextEmbeds }
+                : {}),
+            ...(options.validateComposition ? { validateComposition: options.validateComposition } : {}),
+            ...(options.store ? { store: options.store } : {}),
+            ...(options.maxRepairAttempts !== undefined
+                ? { maxRepairAttempts: options.maxRepairAttempts }
+                : {}),
+        });
+        if (!result.ok) {
+            return {
+                ok: false,
+                errorText: `The drafted ${collection.id} did not pass validation: ${issueSummary(result.issues)}`,
+            };
+        }
+        options.onProposal(toolCallId, {
+            origin: 'create',
+            collection: collection.id,
+            documentId,
+            patch: result.patch,
+            provenance: result.provenance,
+            attempts: result.attempts,
+            issues: result.issues,
+        });
+        // Compact summary only — the full patch goes to the review UI, not the model.
+        return {
+            ok: true,
+            output: {
+                status: 'proposed',
+                collection: collection.id,
+                documentId,
+                title: resolveDocumentTitle(collection, result.patch.values, documentId),
+                note: 'Draft proposal created; the editor reviews and applies it in the studio. Summarize briefly — do not repeat the content.',
             },
-            collection: {
-                type: 'string',
-                ...(collectionIds.length > 0 ? { enum: [...collectionIds] } : {}),
-                description: 'Target collection id (for searchDocuments / createDocument / translateDocument).',
+        };
+    }
+    async function translate(toolCallId, input) {
+        const collection = collectionById(input.collection);
+        if (!collection) {
+            return { ok: false, errorText: `Unknown collection "${input.collection}" — use a collection id from the catalog.` };
+        }
+        if (!options.readers.getDocument || !options.localeConfig) {
+            return { ok: false, errorText: 'Translation is not available here.' };
+        }
+        const document = await options.readers.getDocument({
+            collection: input.collection,
+            id: input.id,
+        });
+        if (!document) {
+            return { ok: false, errorText: `Document "${input.collection}/${input.id}" was not found.` };
+        }
+        const knowledge = options.knowledge?.();
+        const result = await translateDocument({
+            provider: options.provider,
+            collection,
+            document,
+            localeConfig: options.localeConfig,
+            ...(input.locale ? { targetLocales: [input.locale] } : {}),
+            ...(knowledge ? { knowledge } : {}),
+        });
+        if (result.total === 0) {
+            return {
+                ok: true,
+                output: {
+                    status: 'nothing-to-translate',
+                    note: 'Every locale value is already filled — there is nothing to translate.',
+                },
+            };
+        }
+        if (result.translated === 0) {
+            return { ok: false, errorText: 'The translation did not produce any content.' };
+        }
+        options.onProposal(toolCallId, {
+            origin: 'translate',
+            collection: collection.id,
+            documentId: document.id,
+            patch: {
+                collection: collection.id,
+                id: document.id,
+                values: result.document.values,
+                ...(result.document.localized ? { localized: result.document.localized } : {}),
             },
-            query: {
-                type: 'string',
-                description: 'Optional search text (searchDocuments / listAssets / translateDocument).',
+            provenance: result.provenance,
+            attempts: 1,
+            issues: [],
+            before: {
+                values: document.values,
+                ...(document.localized ? { localized: document.localized } : {}),
             },
-            instruction: {
-                type: 'string',
-                description: 'What to write, refining the user request (createDocument).',
+        });
+        return {
+            ok: true,
+            output: {
+                status: 'proposed',
+                collection: collection.id,
+                documentId: document.id,
+                translatedUnits: result.translated,
+                note: 'Translation proposal created; the editor reviews and applies it in the studio.',
             },
-            message: { type: 'string', description: 'Assistant reply text (respond).' },
+        };
+    }
+    return {
+        async execute(call) {
+            const definition = chatToolDefinitions[call.toolName];
+            if (!definition) {
+                return { ok: false, errorText: `Unknown tool "${call.toolName}".` };
+            }
+            const parsed = definition.inputSchema.safeParse(call.input);
+            if (!parsed.success) {
+                return { ok: false, errorText: `Invalid ${call.toolName} input: ${parsed.error.message}` };
+            }
+            try {
+                switch (call.toolName) {
+                    case 'searchDocuments':
+                        return await searchDocuments(parsed.data);
+                    case 'listAssets':
+                        return await listAssets(parsed.data);
+                    case 'getDocument':
+                        return await getDocument(parsed.data);
+                    case 'createDocument':
+                        return await createDocument(call.toolCallId, parsed.data);
+                    case 'updateFields':
+                        return await updateFields(call.toolCallId, parsed.data);
+                    case 'translateDocument':
+                        return await translate(call.toolCallId, parsed.data);
+                    default:
+                        return { ok: false, errorText: `Unknown tool "${call.toolName}".` };
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    errorText: `The ${call.toolName} step failed: ${error instanceof Error ? error.message : 'unknown error'}`,
+                };
+            }
         },
-        required: ['action'],
-        additionalProperties: false,
     };
 }
-/** Coerce a raw structured-output object into a {@link PlannerAction}; `null` if unusable. */
-export function parsePlannerAction(raw) {
-    if (typeof raw !== 'object' || raw === null)
-        return null;
-    const value = raw;
-    const action = value.action;
-    const str = (k) => typeof value[k] === 'string' && value[k].length > 0 ? value[k] : undefined;
-    switch (action) {
-        case 'searchDocuments': {
-            const collection = str('collection');
-            if (!collection)
-                return null;
-            return { action, collection, ...(str('query') ? { query: str('query') } : {}) };
-        }
-        case 'listAssets':
-            return { action, ...(str('query') ? { query: str('query') } : {}) };
-        case 'createDocument': {
-            const collection = str('collection');
-            if (!collection)
-                return null;
-            return { action, collection, ...(str('instruction') ? { instruction: str('instruction') } : {}) };
-        }
-        case 'translateDocument': {
-            const collection = str('collection');
-            if (!collection)
-                return null;
-            return { action, collection, ...(str('query') ? { query: str('query') } : {}) };
-        }
-        case 'respond':
-            return { action, message: str('message') ?? '' };
-        default:
-            return null;
-    }
-}
 //# sourceMappingURL=tools.js.map