@elytracms/studio 0.0.57 → 0.0.58

package/dist/lib/ai/shape.js

@@ -10,30 +10,33 @@
  *  - relation fields become an ENUM over the provided candidate ids (or are omitted
  *    when no candidates exist) — so a hallucinated relation id is not representable
  *    as valid structured output.
- *  - rich-text fields are emitted in the `{ version, doc }` ProseMirror storage shape
- *    (the `allow` leash on embeds is enforced later by `validateRichTextEmbeds`).
+ *  - asset/image fields become an ENUM over the searched library asset ids (or are
+ *    omitted when none were searched) — EC-381, the SAME leash as relations: a
+ *    proposed asset id must be a real, `listAssets`-returned library asset, and a
+ *    create shape with no searched assets simply has no asset property (empty beats
+ *    wrong; the assistant never generates or uploads).
+ *  - rich-text fields are MARKDOWN STRINGS (EC-379): the description names the
+ *    allowed subset, and the engine converts md → the `{ version, doc }` storage
+ *    envelope at proposal-build time. The field's `allow` config leashes component
+ *    EMBEDS only — markdown cannot express an embed, so the leash is satisfied by
+ *    construction (and still enforced downstream by `validateRichTextEmbeds`).
  *
  * Localized fields stay flat in the shape (the model authors one locale at a time);
  * the engine routes their values under `localized[locale]`.
  */
 import { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core';
-/** The rich-text `{ version, doc }` storage envelope, as a JSON Schema. */
-function richTextEnvelopeSchema() {
+import { MARKDOWN_PROSE_DESCRIPTION } from '@elytracms/core/rich-text';
+/**
+ * A rich-text field's model-facing schema (EC-379): a MARKDOWN string. The
+ * description carries the allowed subset (from the engine converter — one source
+ * of truth), so the model has something concrete to aim at; the engine converts
+ * the markdown into the `{ version, doc }` storage envelope at proposal-build
+ * time and rejects out-of-subset constructs with explicit issues.
+ */
+function richTextMarkdownSchema() {
     return {
-        type: 'object',
-        description: 'Rich text in the ProseMirror storage shape: { version, doc: { type: "doc", content: [...] } }.',
-        properties: {
-            version: { type: 'number' },
-            doc: {
-                type: 'object',
-                properties: {
-                    type: { type: 'string', const: 'doc' },
-                    content: { type: 'array', items: { type: 'object' } },
-                },
-                required: ['type', 'content'],
-            },
-        },
-        required: ['version', 'doc'],
+        type: 'string',
+        description: `Rich text, written as ${MARKDOWN_PROSE_DESCRIPTION} Write genuine, publishable prose.`,
     };
 }
 /** A field's model-facing description: resolved label + optional `ai.hint`. */
@@ -56,6 +59,7 @@ export function buildTargetShape(input) {
     const excluded = [];
     const localizedFields = [];
     const relationFields = [];
+    const assetFields = [];
     for (const field of input.collection.fields) {
         if (field.localized)
             localizedFields.push(field.name);
@@ -89,8 +93,30 @@ export function buildTargetShape(input) {
                 candidateIds: ids,
             });
         }
+        else if (field.type === 'asset') {
+            // EC-381 — same leash as relations: an asset field is an enum over the ids
+            // the model actually searched in the media library (`listAssets`). No
+            // searched assets ⇒ omit the field, so the proposal simply leaves it empty
+            // (an invented / to-be-uploaded id is structurally unrepresentable).
+            const candidates = input.assetCandidates?.[field.name] ?? [];
+            if (candidates.length === 0) {
+                delete properties[field.name];
+                continue;
+            }
+            const ids = candidates.map((c) => c.id);
+            const label = candidates
+                .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))
+                .join(', ');
+            const idSchema = {
+                type: 'string',
+                enum: ids,
+                description: `Choose an EXISTING library asset id, one of: ${label}. Leave empty if none fits.`,
+            };
+            properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema;
+            assetFields.push({ fieldName: field.name, multiple: field.multiple, candidateIds: ids });
+        }
         else if (field.type === 'richText') {
-            properties[field.name] = richTextEnvelopeSchema();
+            properties[field.name] = richTextMarkdownSchema();
         }
         const prop = properties[field.name];
         if (prop) {
@@ -108,6 +134,6 @@ export function buildTargetShape(input) {
         additionalProperties: false,
         ...(required.length > 0 ? { required } : {}),
     };
-    return { schema, excluded, localizedFields, relationFields };
+    return { schema, excluded, localizedFields, relationFields, assetFields };
 }
 //# sourceMappingURL=shape.js.map

package/dist/lib/ai/shape.js.map

@@ -1 +1 @@
-{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../src/lib/ai/shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Target-shape derivation for `applyContentWithShape` (EC-331).\n *\n * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,\n * cms-core) rather than writing a new one, then applies the three leashes the AI\n * engine adds on top:\n *\n *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot\n *    write them).\n *  - relation fields become an ENUM over the provided candidate ids (or are omitted\n *    when no candidates exist) — so a hallucinated relation id is not representable\n *    as valid structured output.\n *  - rich-text fields are emitted in the `{ version, doc }` ProseMirror storage shape\n *    (the `allow` leash on embeds is enforced later by `validateRichTextEmbeds`).\n *\n * Localized fields stay flat in the shape (the model authors one locale at a time);\n * the engine routes their values under `localized[locale]`.\n */\nimport { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core'\nimport type { CollectionDef, FieldDef, JsonSchema } from '@elytracms/core/cms-core'\nimport type { RelationCandidates } from './types'\n\n/** A relation field's resolved candidate set — how the engine maps ids → reference envelopes. */\nexport interface TargetRelationField {\n  fieldName: string\n  /** The relation's target collection id. */\n  target: string\n  multiple: boolean\n  /** The allowed candidate ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** The derived target shape + the metadata the engine needs to post-process the output. */\nexport interface TargetShape {\n  /** The JSON Schema the structured output must satisfy. */\n  schema: JsonSchema\n  /** Field names removed by `ai.exclude` (untouchable). */\n  excluded: string[]\n  /** Field names whose values route under `localized[locale]`. */\n  localizedFields: string[]\n  /** Relation fields with their candidate enums. */\n  relationFields: TargetRelationField[]\n}\n\nexport interface BuildTargetShapeInput {\n  collection: CollectionDef\n  /** Relation candidate ids by field — a relation field with none is omitted from the shape. */\n  candidates?: RelationCandidates\n  /** UI locale for resolving field labels into descriptions. */\n  locale?: string\n}\n\n/** The rich-text `{ version, doc }` storage envelope, as a JSON Schema. */\nfunction richTextEnvelopeSchema(): JsonSchema {\n  return {\n    type: 'object',\n    description:\n      'Rich text in the ProseMirror storage shape: { version, doc: { type: \"doc\", content: [...] } }.',\n    properties: {\n      version: { type: 'number' },\n      doc: {\n        type: 'object',\n        properties: {\n          type: { type: 'string', const: 'doc' },\n          content: { type: 'array', items: { type: 'object' } },\n        },\n        required: ['type', 'content'],\n      },\n    },\n    required: ['version', 'doc'],\n  }\n}\n\n/** A field's model-facing description: resolved label + optional `ai.hint`. */\nfunction describe(field: FieldDef, locale?: string): string | undefined {\n  const label = resolveLabel(field.form?.label, locale) ?? field.name\n  const hint = field.ai?.hint\n  const parts = [label, hint].filter((p): p is string => typeof p === 'string' && p.length > 0)\n  return parts.length > 0 ? parts.join(' — ') : undefined\n}\n\n/**\n * Build the leash-aware target shape from a collection + candidates. Deterministic;\n * never throws. Reuses `collectionJsonSchema` as the base, then rewrites relations /\n * rich text and strips excluded fields.\n */\nexport function buildTargetShape(input: BuildTargetShapeInput): TargetShape {\n  const base = collectionJsonSchema(input.collection)\n  const properties: Record<string, JsonSchema> = {\n    ...((base.properties as Record<string, JsonSchema>) ?? {}),\n  }\n  const excluded: string[] = []\n  const localizedFields: string[] = []\n  const relationFields: TargetRelationField[] = []\n\n  for (const field of input.collection.fields) {\n    if (field.localized) localizedFields.push(field.name)\n\n    if (field.ai?.exclude) {\n      excluded.push(field.name)\n      delete properties[field.name]\n      continue\n    }\n\n    if (field.type === 'relation') {\n      const candidates = input.candidates?.[field.name] ?? []\n      if (candidates.length === 0) {\n        // No candidate ids ⇒ omit the field: the model cannot emit a relation value\n        // at all, so a hallucinated id is structurally impossible.\n        delete properties[field.name]\n        continue\n      }\n      const ids = candidates.map((c) => c.id)\n      const label = candidates\n        .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))\n        .join(', ')\n      const idSchema: JsonSchema = {\n        type: 'string',\n        enum: ids,\n        description: `Choose one of: ${label}`,\n      }\n      properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema\n      relationFields.push({\n        fieldName: field.name,\n        target: field.target,\n        multiple: field.multiple,\n        candidateIds: ids,\n      })\n    } else if (field.type === 'richText') {\n      properties[field.name] = richTextEnvelopeSchema()\n    }\n\n    const prop = properties[field.name]\n    if (prop) {\n      const desc = describe(field, input.locale)\n      // Preserve an existing description (e.g. relation enum / rich-text note).\n      if (desc && typeof prop.description !== 'string') prop.description = desc\n    }\n  }\n\n  const requiredIn = Array.isArray(base.required) ? (base.required as string[]) : []\n  const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined)\n\n  const schema: JsonSchema = {\n    type: 'object',\n    properties,\n    additionalProperties: false,\n    ...(required.length > 0 ? { required } : {}),\n  }\n  return { schema, excluded, localizedFields, relationFields }\n}\n"]}
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../src/lib/ai/shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Target-shape derivation for `applyContentWithShape` (EC-331).\n *\n * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,\n * cms-core) rather than writing a new one, then applies the three leashes the AI\n * engine adds on top:\n *\n *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot\n *    write them).\n *  - relation fields become an ENUM over the provided candidate ids (or are omitted\n *    when no candidates exist) — so a hallucinated relation id is not representable\n *    as valid structured output.\n *  - asset/image fields become an ENUM over the searched library asset ids (or are\n *    omitted when none were searched) — EC-381, the SAME leash as relations: a\n *    proposed asset id must be a real, `listAssets`-returned library asset, and a\n *    create shape with no searched assets simply has no asset property (empty beats\n *    wrong; the assistant never generates or uploads).\n *  - rich-text fields are MARKDOWN STRINGS (EC-379): the description names the\n *    allowed subset, and the engine converts md → the `{ version, doc }` storage\n *    envelope at proposal-build time. The field's `allow` config leashes component\n *    EMBEDS only — markdown cannot express an embed, so the leash is satisfied by\n *    construction (and still enforced downstream by `validateRichTextEmbeds`).\n *\n * Localized fields stay flat in the shape (the model authors one locale at a time);\n * the engine routes their values under `localized[locale]`.\n */\nimport { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core'\nimport type { CollectionDef, FieldDef, JsonSchema } from '@elytracms/core/cms-core'\nimport { MARKDOWN_PROSE_DESCRIPTION } from '@elytracms/core/rich-text'\nimport type { AssetCandidates, RelationCandidates } from './types'\n\n/** A relation field's resolved candidate set — how the engine maps ids → reference envelopes. */\nexport interface TargetRelationField {\n  fieldName: string\n  /** The relation's target collection id. */\n  target: string\n  multiple: boolean\n  /** The allowed candidate ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** An asset field's resolved candidate set — how the engine maps ids → asset envelopes (EC-381). */\nexport interface TargetAssetField {\n  fieldName: string\n  multiple: boolean\n  /** The allowed library asset ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** The derived target shape + the metadata the engine needs to post-process the output. */\nexport interface TargetShape {\n  /** The JSON Schema the structured output must satisfy. */\n  schema: JsonSchema\n  /** Field names removed by `ai.exclude` (untouchable). */\n  excluded: string[]\n  /** Field names whose values route under `localized[locale]`. */\n  localizedFields: string[]\n  /** Relation fields with their candidate enums. */\n  relationFields: TargetRelationField[]\n  /** Asset fields with their candidate enums (EC-381). */\n  assetFields: TargetAssetField[]\n}\n\nexport interface BuildTargetShapeInput {\n  collection: CollectionDef\n  /** Relation candidate ids by field — a relation field with none is omitted from the shape. */\n  candidates?: RelationCandidates\n  /** Asset candidate ids by field — an asset field with none is omitted from the shape (EC-381). */\n  assetCandidates?: AssetCandidates\n  /** UI locale for resolving field labels into descriptions. */\n  locale?: string\n}\n\n/**\n * A rich-text field's model-facing schema (EC-379): a MARKDOWN string. The\n * description carries the allowed subset (from the engine converter — one source\n * of truth), so the model has something concrete to aim at; the engine converts\n * the markdown into the `{ version, doc }` storage envelope at proposal-build\n * time and rejects out-of-subset constructs with explicit issues.\n */\nfunction richTextMarkdownSchema(): JsonSchema {\n  return {\n    type: 'string',\n    description: `Rich text, written as ${MARKDOWN_PROSE_DESCRIPTION} Write genuine, publishable prose.`,\n  }\n}\n\n/** A field's model-facing description: resolved label + optional `ai.hint`. */\nfunction describe(field: FieldDef, locale?: string): string | undefined {\n  const label = resolveLabel(field.form?.label, locale) ?? field.name\n  const hint = field.ai?.hint\n  const parts = [label, hint].filter((p): p is string => typeof p === 'string' && p.length > 0)\n  return parts.length > 0 ? parts.join(' — ') : undefined\n}\n\n/**\n * Build the leash-aware target shape from a collection + candidates. Deterministic;\n * never throws. Reuses `collectionJsonSchema` as the base, then rewrites relations /\n * rich text and strips excluded fields.\n */\nexport function buildTargetShape(input: BuildTargetShapeInput): TargetShape {\n  const base = collectionJsonSchema(input.collection)\n  const properties: Record<string, JsonSchema> = {\n    ...((base.properties as Record<string, JsonSchema>) ?? {}),\n  }\n  const excluded: string[] = []\n  const localizedFields: string[] = []\n  const relationFields: TargetRelationField[] = []\n  const assetFields: TargetAssetField[] = []\n\n  for (const field of input.collection.fields) {\n    if (field.localized) localizedFields.push(field.name)\n\n    if (field.ai?.exclude) {\n      excluded.push(field.name)\n      delete properties[field.name]\n      continue\n    }\n\n    if (field.type === 'relation') {\n      const candidates = input.candidates?.[field.name] ?? []\n      if (candidates.length === 0) {\n        // No candidate ids ⇒ omit the field: the model cannot emit a relation value\n        // at all, so a hallucinated id is structurally impossible.\n        delete properties[field.name]\n        continue\n      }\n      const ids = candidates.map((c) => c.id)\n      const label = candidates\n        .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))\n        .join(', ')\n      const idSchema: JsonSchema = {\n        type: 'string',\n        enum: ids,\n        description: `Choose one of: ${label}`,\n      }\n      properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema\n      relationFields.push({\n        fieldName: field.name,\n        target: field.target,\n        multiple: field.multiple,\n        candidateIds: ids,\n      })\n    } else if (field.type === 'asset') {\n      // EC-381 — same leash as relations: an asset field is an enum over the ids\n      // the model actually searched in the media library (`listAssets`). No\n      // searched assets ⇒ omit the field, so the proposal simply leaves it empty\n      // (an invented / to-be-uploaded id is structurally unrepresentable).\n      const candidates = input.assetCandidates?.[field.name] ?? []\n      if (candidates.length === 0) {\n        delete properties[field.name]\n        continue\n      }\n      const ids = candidates.map((c) => c.id)\n      const label = candidates\n        .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))\n        .join(', ')\n      const idSchema: JsonSchema = {\n        type: 'string',\n        enum: ids,\n        description: `Choose an EXISTING library asset id, one of: ${label}. Leave empty if none fits.`,\n      }\n      properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema\n      assetFields.push({ fieldName: field.name, multiple: field.multiple, candidateIds: ids })\n    } else if (field.type === 'richText') {\n      properties[field.name] = richTextMarkdownSchema()\n    }\n\n    const prop = properties[field.name]\n    if (prop) {\n      const desc = describe(field, input.locale)\n      // Preserve an existing description (e.g. relation enum / rich-text note).\n      if (desc && typeof prop.description !== 'string') prop.description = desc\n    }\n  }\n\n  const requiredIn = Array.isArray(base.required) ? (base.required as string[]) : []\n  const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined)\n\n  const schema: JsonSchema = {\n    type: 'object',\n    properties,\n    additionalProperties: false,\n    ...(required.length > 0 ? { required } : {}),\n  }\n  return { schema, excluded, localizedFields, relationFields, assetFields }\n}\n"]}

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