@elytracms/studio 0.0.57 → 0.0.59

package/dist/lib/ai/tools.d.ts

@@ -14,13 +14,19 @@
  *     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`)
- *     through the route's kept `generate` branch and return a COMPACT proposal
- *     summary as the tool output — the full proposal goes to the review UI via
+ *     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 adds `updateFields` as one more definition + one more executor case —
- * the map's shape leaves that slot open.
+ * 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).
@@ -29,7 +35,7 @@ import { z } from 'zod';
 import type { CmsDocument, CollectionDef, CollectionRegistry, LocaleConfig, ValidateDocumentOptions } from '@elytracms/core/cms-core';
 import type { ComponentManifest } from '@elytracms/core/component-registry';
 import type { ChatProposal } from './chat-state.js';
-import type { AiProvider, RelationCandidates, ResolvedKnowledge } from './types.js';
+import type { AiProvider, AssetCandidates, RelationCandidates, ResolvedKnowledge } from './types.js';
 /** A document the model may reference as a relation target (from a `searchDocuments` read). */
 export interface DocumentSearchResult {
     id: string;
@@ -108,8 +114,8 @@ export declare const chatToolDefinitions: {
     getDocument: {
         description: string;
         inputSchema: z.ZodObject<{
-            collection: z.ZodString;
-            id: z.ZodString;
+            collection: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     };
     createDocument: {
@@ -119,6 +125,20 @@ export declare const chatToolDefinitions: {
             instruction: z.ZodString;
         }, z.core.$strip>;
     };
+    updateFields: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            collection: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            changes: z.ZodArray<z.ZodObject<{
+                field: z.ZodString;
+                locale: z.ZodOptional<z.ZodString>;
+                blockId: z.ZodOptional<z.ZodString>;
+                prop: z.ZodOptional<z.ZodString>;
+                value: z.ZodOptional<z.ZodUnknown>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    };
     translateDocument: {
         description: string;
         inputSchema: z.ZodObject<{
@@ -134,6 +154,33 @@ export interface ChatToolCall {
     toolName: string;
     input: unknown;
 }
+/** The coordinates of the document currently open in the editor (EC-378 seam). */
+export interface CurrentDocumentRef {
+    collection: string;
+    id: string;
+}
+/**
+ * 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 declare function resolveDocumentTarget(input: {
+    collection?: string;
+    id?: string;
+}, current: CurrentDocumentRef | null | undefined): {
+    ok: true;
+    ref: CurrentDocumentRef;
+} | {
+    ok: false;
+    errorText: string;
+};
 /**
  * A tool execution outcome: an `output` posted back as the tool result, or an
  * `errorText` posted as an `output-error` part (the model sees the failure and
@@ -147,16 +194,27 @@ export type ChatToolOutcome = {
     errorText: string;
 };
 /**
- * The per-conversation relation-candidate store: every `searchDocuments` result
- * is recorded per collection, and `createDocument` may only reference the ids
- * gathered here (the `applyContentWithShape` enum leash makes a hallucinated id
- * structurally unrepresentable). Held by the panel per conversation — a new
- * conversation (EC-380 clear) starts an empty store.
+ * The per-conversation candidate store: every `searchDocuments` result is recorded
+ * per relation target collection, every `listAssets` result into one flat library
+ * pool (EC-381), and the terminal tools may only reference the ids gathered here
+ * (the `applyContentWithShape` / `buildUpdateProposal` enum + drop/loud leash makes
+ * a hallucinated relation OR asset id structurally unrepresentable / fail loud).
+ * Held by the panel per conversation — a new conversation (EC-380 clear) starts an
+ * empty store.
  */
 export interface ChatCandidateStore {
     record(collection: string, results: readonly DocumentSearchResult[]): void;
+    /** Record every `listAssets` result into the flat library pool (EC-381). */
+    recordAssets(results: readonly AssetSearchResult[]): void;
     /** Candidates for a target collection's relation fields, keyed by field name. */
     candidatesFor(collection: CollectionDef): RelationCandidates;
+    /**
+     * Candidates for a target collection's asset/image fields (EC-381), keyed by
+     * field name — every asset field shares the one flat searched-asset pool
+     * (`listAssets` has no field dimension). Empty when nothing was searched, so the
+     * asset field is then omitted from the shape (empty beats wrong).
+     */
+    assetCandidatesFor(collection: CollectionDef): AssetCandidates;
 }
 export declare function createChatCandidateStore(): ChatCandidateStore;
 export interface ChatToolExecutorOptions {
@@ -176,6 +234,13 @@ export interface ChatToolExecutorOptions {
      * The tool OUTPUT stays a compact summary; the patch never reaches the model.
      */
     onProposal: (toolCallId: string, proposal: ChatProposal) => void;
+    /**
+     * The document currently open in the editor (EC-378 seam) — a thunk read at
+     * EXECUTION time, so "this document" resolves against what is open NOW.
+     * `getDocument` / `updateFields` fall back to it when the model omits the
+     * target (see {@link resolveDocumentTarget}).
+     */
+    currentDocument?: () => CurrentDocumentRef | null | undefined;
     /** Current knowledge snapshot (thunk — the body thunk refreshes it per request). */
     knowledge?: () => ResolvedKnowledge | undefined;
     /** Component manifests — context for `allow`-leashed richText/blocks fields. */
@@ -197,6 +262,16 @@ export interface ChatToolExecutorOptions {
 export interface ChatToolExecutor {
     execute(call: ChatToolCall): Promise<ChatToolOutcome>;
 }
+/**
+ * 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 declare function projectRichTextAsMarkdown(document: CmsDocument, collection: CollectionDef): CmsDocument;
 /**
  * Build the client executor map. Every entry validates its input against
  * {@link chatToolDefinitions}' zod schema (the route validates UIMessages only

package/dist/lib/ai/tools.js

@@ -14,21 +14,30 @@
  *     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`)
- *     through the route's kept `generate` branch and return a COMPACT proposal
- *     summary as the tool output — the full proposal goes to the review UI via
+ *     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 adds `updateFields` as one more definition + one more executor case —
- * the map's shape leaves that slot open.
+ * 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).
  */
 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;
 /**
@@ -66,10 +75,18 @@ export const chatToolDefinitions = {
         }),
     },
     getDocument: {
-        description: 'Fetch one full document (values + localized values) by collection and id.',
+        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().describe('Collection id.'),
-            id: z.string().describe('Document id (from a searchDocuments result).'),
+            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: {
@@ -81,9 +98,52 @@ export const chatToolDefinitions = {
             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). Returns a compact proposal summary.',
+        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).'),
@@ -91,8 +151,39 @@ export const chatToolDefinitions = {
         }),
     },
 };
+/**
+ * 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 {
         record(collection, results) {
             const byId = searched.get(collection) ?? new Map();
@@ -100,6 +191,10 @@ export function createChatCandidateStore() {
                 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) {
@@ -112,6 +207,18 @@ export function createChatCandidateStore() {
             }
             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) {
@@ -120,6 +227,45 @@ function issueSummary(issues) {
         .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
@@ -151,17 +297,107 @@ export function createChatToolExecutor(options) {
             ...(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 document = await options.readers.getDocument(input);
+        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 "${input.collection}/${input.id}" was not found.` };
+            return {
+                ok: false,
+                errorText: `Document "${target.ref.collection}/${target.ref.id}" was not found.`,
+            };
         }
-        return { ok: true, output: document };
+        // 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);
@@ -179,6 +415,8 @@ export function createChatToolExecutor(options) {
             ...(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 }
@@ -301,9 +539,10 @@ export function createChatToolExecutor(options) {
                         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);
-                    // EC-378: case 'updateFields' lands here (leashed field-update proposals).
                     default:
                         return { ok: false, errorText: `Unknown tool "${call.toolName}".` };
                 }