@elytracms/studio 0.0.56 → 0.0.58

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

@@ -1,16 +1,41 @@
 /**
- * The narrow tool set the creation flow's model works against (EC-199).
+ * 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 only declares their SHAPES (the model-facing
- * planner schema) and the reader interface the studio binds to operations. The engine
- * never gains a write path: `searchDocuments` / `listAssets` are reads that gather the
- * real ids a proposal may reference (a relation id is otherwise structurally
- * impossible — see `buildTargetShape`), and `createDocument` is the terminal action
- * that runs `applyContentWithShape` and yields a reviewable proposal. `updateFields`
- * and `translate` are deliberately NOT here — they are later slices (EC-332 / post-v1).
+ * 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).
  */
-import type { CmsDocument, JsonSchema } from '@elytracms/core/cms-core';
+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, 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;
@@ -22,11 +47,11 @@ export interface AssetSearchResult {
     title?: string;
 }
 /**
- * The client-side, operations-backed readers the orchestrator calls. The studio binds
+ * The client-side, operations-backed readers the executor calls. The studio binds
  * these to the user's authenticated operations client; tests bind an in-memory fake.
  * Reads only — there is no write tool (apply is a separate, human-gated draft write).
  */
-export interface CreateFlowTools {
+export interface ChatToolReaders {
     searchDocuments(input: {
         collection: string;
         query?: string;
@@ -37,41 +62,221 @@ export interface CreateFlowTools {
         limit?: number;
     }): Promise<AssetSearchResult[]>;
     /**
-     * Fetch a full document (values + localized) for the translate flow (EC-332). Optional:
-     * the creation flow never needs it, so a studio that only wires create can omit it.
+     * Fetch a full document (values + localized) — the translate flow and the model's
+     * `getDocument` tool. Optional: a studio that only wires create can omit it.
      */
     getDocument?(input: {
         collection: string;
         id: string;
     }): Promise<CmsDocument | null>;
 }
-/** One planned step the model returns — the discriminated tool/action union. */
-export type PlannerAction = {
-    action: 'searchDocuments';
-    collection: string;
-    query?: string;
-} | {
-    action: 'listAssets';
-    query?: string;
-} | {
-    action: 'createDocument';
+/** Per-search result cap (protects the wire — results become model context). */
+export declare const DEFAULT_SEARCH_LIMIT = 20;
+/**
+ * One model-facing tool definition for the route's `streamText` call. Structurally
+ * the SDK's `FunctionTool` WITHOUT `execute` (execution is client-side, always) —
+ * typed locally so this module needs no SDK import.
+ */
+export interface ChatToolDefinition {
+    description: string;
+    /** Zod input schema (the AI SDK accepts zod schemas as `inputSchema` directly). */
+    inputSchema: z.ZodType;
+}
+/**
+ * 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 declare const chatToolDefinitions: {
+    searchDocuments: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            collection: z.ZodString;
+            query: z.ZodOptional<z.ZodString>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    };
+    listAssets: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            query: z.ZodOptional<z.ZodString>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    };
+    getDocument: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            collection: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    createDocument: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            collection: z.ZodString;
+            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<{
+            collection: z.ZodString;
+            id: z.ZodString;
+            locale: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+};
+/** One forwarded tool call, as `useChat`'s `onToolCall` receives it. */
+export interface ChatToolCall {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+/** The coordinates of the document currently open in the editor (EC-378 seam). */
+export interface CurrentDocumentRef {
     collection: string;
-    instruction?: 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;
 } | {
-    action: 'translateDocument';
-    collection: string;
-    query?: string;
+    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
+ * can react — never a thrown exception into the stream).
+ */
+export type ChatToolOutcome = {
+    ok: true;
+    output: unknown;
 } | {
-    action: 'respond';
-    message: string;
+    ok: false;
+    errorText: string;
 };
-/** The schema name the planner call carries — how a FakeProvider tells plan vs. author. */
-export declare 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 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 {
+    /** The (route) provider the terminal engines proxy their model calls through. */
+    provider: AiProvider;
+    registry: CollectionRegistry;
+    /** The collections the assistant may target (unknown ids fail loud). */
+    collections: readonly CollectionDef[];
+    /** Operations-backed readers (client-side, user's session). */
+    readers: ChatToolReaders;
+    /** Mint a fresh document id for a new draft (studio: the CMS store's minter). */
+    mintDocumentId: (collectionId: string) => string;
+    /** Per-conversation relation-candidate store (see {@link createChatCandidateStore}). */
+    candidates: ChatCandidateStore;
+    /**
+     * Full proposal sink, keyed by `toolCallId` — the review UI's entry point.
+     * 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. */
+    components?: readonly ComponentManifest[];
+    /** Target locale for localized fields. */
+    locale?: string;
+    /** Locale config — required for `translateDocument`. */
+    localeConfig?: LocaleConfig;
+    /** Injected leashes / store for `applyContentWithShape`'s validation. */
+    validateRichTextEmbeds?: ValidateDocumentOptions['validateRichTextEmbeds'];
+    validateComposition?: ValidateDocumentOptions['validateComposition'];
+    store?: ValidateDocumentOptions['store'];
+    /** Max repair attempts inside `applyContentWithShape`. */
+    maxRepairAttempts?: number;
+    /** Per-search result cap (default {@link DEFAULT_SEARCH_LIMIT}). */
+    searchLimit?: number;
+}
+/** The executor `useChat`'s `onToolCall` dispatches into. */
+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
+ * 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 declare function plannerSchema(collectionIds: readonly string[]): JsonSchema;
-/** Coerce a raw structured-output object into a {@link PlannerAction}; `null` if unusable. */
-export declare function parsePlannerAction(raw: unknown): PlannerAction | null;
+export declare function createChatToolExecutor(options: ChatToolExecutorOptions): ChatToolExecutor;