@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/server/assist-edit.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AssistEditCanvasContext, type AssistEditDocumentKind, type AssistEditProposal, type AssistEditTarget } from '../model/assist-edit';
+import type { AiTool } from '../providers/contract';
+import { type AiGenerationCheckResult } from '../runtime/ai-doctrine';
+/**
+ * The chat door's edit rung, server half (AGL-2906): what the model is told
+ * about the canvas, the tool it proposes through, and the validation a
+ * proposal passes before a card is shown.
+ *
+ * Nothing here writes, and nothing here calls a model. A proposal is resolved
+ * into the ops of `model/assist-edit.ts` and handed to the panel, which
+ * applies them on the author's confirm.
+ *
+ * ## A closed world, like the navigate proposals
+ *
+ * The model may name only element ids the request described — the selection,
+ * its surroundings and its subtree — or the document root. An op naming
+ * anything else is dropped, never guessed at, because a plausible id pointed
+ * at the wrong element is the edit that looks right in a screenshot and is
+ * wrong on the page. Everything the model writes into a prop, a style or a
+ * new subtree passes the palette validators first.
+ */
+/** Ops one proposal may carry; a larger change is a generation job, not a chat turn. */
+export declare const ASSIST_EDIT_MAX_OPS = 20;
+/** New elements one insert may add. */
+export declare const ASSIST_EDIT_MAX_INSERT_NODES = 40;
+/**
+ * The output ceiling on the edit rung. Forty new elements written as
+ * name/value pairs need room the answer-only ceiling does not have.
+ */
+export declare const ASSIST_EDIT_MAX_OUTPUT_TOKENS = 4096;
+/**
+ * The structured-output tool the model proposes an edit through.
+ *
+ * Every field of an op is required and flat — `anyOf` unions and optional
+ * properties are not portable across strict tool implementations — so an op
+ * fills the fields it does not use with `""`, `[]` or `-1`. Props and styles
+ * travel as name/value pairs because a strict schema cannot describe a map
+ * whose keys depend on the element. The search fields come from the editor's
+ * own list, so the tool and the Screen Properties form cannot drift.
+ */
+export declare function assistEditTool(kind: AssistEditDocumentKind): AiTool;
+/**
+ * The edit protocol and the element catalog for one kind of document — a
+ * pure function of the kind, so it sits inside the cached prefix and every
+ * workspace editing that kind of document reads one copy of it. The catalog
+ * is the doctrine's for the document's surface, the one a generation on that
+ * surface is shown, carried in this block rather than one of its own.
+ */
+export declare function editCanvasBlock(kind: AssistEditDocumentKind): string;
+/**
+ * The canvas outline a request carried, held to what may enter a prompt.
+ *
+ * Client-supplied, so treated the way `sanitiseRoute` treats a route: ids and
+ * component ids to their own alphabets, props to primitives with markup,
+ * styles and handlers left out, strings shortened, and the whole outline
+ * capped. The document's size is kept only when it is a whole number the
+ * outline could have come from. What survives is encoded as JSON in its
+ * block, so a value cannot break out of its line into the instructions around
+ * it. Null when the outline does not describe the document root, which every
+ * op resolves against.
+ */
+export declare function parseAssistEditContext(raw: unknown): AssistEditCanvasContext | null;
+/**
+ * The per-request canvas block: the selection, what the outline covers and
+ * leaves out, the outline, and the settings each described element accepts.
+ * Volatile — it carries the author's own content — so it sits after every
+ * cache breakpoint.
+ *
+ * The framing is how the model knows what it is looking at. The outline is a
+ * neighborhood of the selection, and a model not told so reads it as the whole
+ * document and reports what it cannot see as missing. A thread replays earlier
+ * answers as history, and a model not told that this block replaces them
+ * answers about a selection from an earlier turn.
+ *
+ * Priced in two tiers: the elements the outline has always carried keep their
+ * settings, and the ones around them — there so the model knows they exist —
+ * come by place alone, a run of alike siblings on one line.
+ */
+export declare function editSelectionBlock(context: AssistEditCanvasContext): string;
+/**
+ * The edit's check: the model's tool call held to the canvas the request
+ * described and to the palette validators, resolved into a proposal. Its
+ * findings are doctrine violations with `rule: null` — the edit's own
+ * closed-world and palette checks, not one of the numbered rules — and each
+ * names a change the proposal leaves out.
+ */
+export declare function checkAssistEditAnswer(answer: Record<string, unknown>, scope: {
+    context: AssistEditCanvasContext;
+    target: AssistEditTarget;
+}): AiGenerationCheckResult<AssistEditProposal>;
+/**
+ * The model's tool call, resolved into a proposal — or a null proposal, with
+ * the reasons, when nothing survived.
+ *
+ * The chat door streams the reply to the reader as it arrives, so by the time
+ * the tool call can be checked the answer is already on screen and there is
+ * no turn left to re-ask in. The doctrine holds it as a streamed answer: a
+ * proposal with findings is still a proposal — the card applies the changes
+ * that survived and lists the rest under "Left out" — and no proposal comes
+ * back as the reasons.
+ */
+export declare function resolveAssistEdit(input: Record<string, unknown>, scope: {
+    context: AssistEditCanvasContext;
+    target: AssistEditTarget;
+}): {
+    proposal: AssistEditProposal | null;
+    dropped: string[];
+};