@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-workflow-job.js

@@ -0,0 +1,183 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { checkEntitlement } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { HOST_EVENT_LABELS, HOST_EVENT_TYPES } from "@aglyn/aglyn/app-utils/workflows";
+/**
+ * A `workflow` job (AGL-2919): an automation drafted from a description, or an
+ * existing automation explained — what it does, or why one of its runs failed.
+ *
+ * One kind, three modes, because the three share everything a job carries:
+ * the site, the gates, the meter and the automation vocabulary. `inputs.mode`
+ * picks the mode, and a job created without one drafts.
+ *
+ *  - `draft` writes a new automation to the site's Actions through the
+ *    workflows plugin's draft writer, OFF, built only from the triggers and
+ *    steps below that this workspace can run. What the description names that
+ *    the site does not have is left as a placeholder, never guessed.
+ *  - `explain` reads a saved automation — an action or a workflow — and
+ *    answers in plain words what it does.
+ *  - `diagnose` reads a saved automation and one of its FAILED runs, as the
+ *    run history recorded it, and answers why it failed and what to change.
+ *
+ * Nothing in any mode switches an automation on, runs one, or changes one.
+ */ export const AI_WORKFLOW_JOB_MODES = [
+    'draft',
+    'explain',
+    'diagnose'
+];
+/** What an explained automation is: an action, or a workflow of function calls. */ export const AI_WORKFLOW_TARGET_TYPES = [
+    'action',
+    'workflow'
+];
+const DOCUMENT_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/** A job's inputs read into its mode, or the sentence that says what is wrong with them. */ export function parseAiWorkflowJobInputs(inputs) {
+    var _ref;
+    const mode = (_ref = inputs == null ? void 0 : inputs['mode']) != null ? _ref : 'draft';
+    if (!AI_WORKFLOW_JOB_MODES.includes(mode)) {
+        return 'inputs.mode must be draft, explain or diagnose';
+    }
+    if (mode === 'draft') return {
+        mode
+    };
+    const targetType = inputs == null ? void 0 : inputs['targetType'];
+    const targetId = inputs == null ? void 0 : inputs['targetId'];
+    if (!AI_WORKFLOW_TARGET_TYPES.includes(targetType) || typeof targetId !== 'string' || !DOCUMENT_ID.test(targetId)) {
+        return 'Pick the automation to explain';
+    }
+    const target = {
+        targetType: targetType,
+        targetId
+    };
+    if (mode === 'explain') return _extends({
+        mode
+    }, target);
+    const runId = inputs == null ? void 0 : inputs['runId'];
+    if (typeof runId !== 'string' || !DOCUMENT_ID.test(runId)) return 'Pick the run to explain';
+    return _extends({
+        mode: 'diagnose'
+    }, target, {
+        runId
+    });
+}
+/** Each need as a sentence names it. */ export const AI_AUTOMATION_NEED_LABELS = {
+    crm: 'the CRM',
+    webhooks: 'webhooks',
+    bookings: 'bookings'
+};
+/**
+ * What this workspace can run, from the entitlements the executor itself
+ * reads before it runs a step: `crm` for the CRM steps, `webhooks` for a
+ * webhook post, and `bookings` for the booking trigger's door.
+ */ export function aiAutomationCapabilities(org) {
+    const billing = org;
+    return {
+        crm: checkEntitlement(billing, 'crm'),
+        webhooks: checkEntitlement(billing, 'webhooks'),
+        bookings: checkEntitlement(billing, 'bookings')
+    };
+}
+// ── The vocabulary ────────────────────────────────────────────────────────
+/**
+ * The triggers a drafted automation may start on: every host event, which is
+ * every event a server door emits. The on-page events (a click, a scroll) are
+ * left out: they watch one element of one page, which a description cannot
+ * name, and they belong to the page's own interactions.
+ */ export const AI_AUTOMATION_TRIGGERS = HOST_EVENT_TYPES;
+/** The triggers only a door of a part of the platform emits. */ export const AI_AUTOMATION_TRIGGER_NEEDS = {
+    booking: 'bookings',
+    taskCompleted: 'crm',
+    contactStageChanged: 'crm',
+    dealStageChanged: 'crm',
+    dealWon: 'crm',
+    dealLost: 'crm'
+};
+/**
+ * The steps a drafted automation may take: the server steps and the flow
+ * steps, which act on the person an event names. The on-page steps — show an
+ * element, open a menu, run a script — are left out for the reason the
+ * on-page triggers are: they need a selector on a page a description cannot
+ * name.
+ */ export const AI_AUTOMATION_STEP_TYPES = [
+    'sendEmail',
+    'notifyAdmins',
+    'enrollList',
+    'assignCampaign',
+    'runWorkflow',
+    'datasetAppend',
+    'updateDataset',
+    'webhookPost',
+    'siteAlert',
+    'wait',
+    'waitForEvent',
+    'exitFlow',
+    'setContactStage',
+    'addContactTag',
+    'assignContactOwner',
+    'createCrmTask',
+    'logCrmActivity'
+];
+/** The steps the executor refuses without a part of the platform. */ export const AI_AUTOMATION_STEP_NEEDS = {
+    webhookPost: 'webhooks',
+    setContactStage: 'crm',
+    addContactTag: 'crm',
+    assignContactOwner: 'crm',
+    createCrmTask: 'crm',
+    logCrmActivity: 'crm'
+};
+/** The trigger's name as the Actions editor labels it. */ export function aiAutomationTriggerLabel(event) {
+    var _HOST_EVENT_LABELS_event;
+    return (_HOST_EVENT_LABELS_event = HOST_EVENT_LABELS[event]) != null ? _HOST_EVENT_LABELS_event : event;
+}
+// ── A description the vocabulary cannot build ─────────────────────────────
+/**
+ * Why a description was answered with no automation. Each is a fixed reason
+ * with a fixed sentence, so what a person reads is never the model's own
+ * account of itself.
+ */ export const AI_AUTOMATION_UNSUPPORTED = [
+    'not-an-automation',
+    'no-trigger',
+    'no-step',
+    'needs-crm',
+    'needs-webhooks',
+    'needs-bookings'
+];
+/** The need an unsupported reason names, for the reasons that name one. */ export const AI_AUTOMATION_UNSUPPORTED_NEED = {
+    'needs-crm': 'crm',
+    'needs-webhooks': 'webhooks',
+    'needs-bookings': 'bookings'
+};
+export const AI_AUTOMATION_UNSUPPORTED_COPY = {
+    'not-an-automation': 'This description is not an automation — something that happens, and what to do then — so nothing was drafted.',
+    'no-trigger': 'Nothing on the platform can start an automation like this one, so nothing was drafted. Describe it as something that happens on your site, such as a form being submitted.',
+    'no-step': 'An automation cannot do what this description asks yet, so nothing was drafted.',
+    'needs-crm': 'This automation needs the CRM, which this workspace’s plan does not include, so nothing was drafted.',
+    'needs-webhooks': 'This automation needs webhooks, which this workspace’s plan does not include, so nothing was drafted.',
+    'needs-bookings': 'This automation needs bookings, which this workspace’s plan does not include, so nothing was drafted.'
+};
+// ── What a job tells a person ─────────────────────────────────────────────
+/** The id the workflows plugin is registered under. */ export const AI_WORKFLOWS_PLUGIN_ID = 'workflows';
+/** The resource the workflows plugin writes a drafted automation under. */ export const AI_AUTOMATION_RESOURCE = 'automation';
+export const AI_WORKFLOW_NO_SITE_COPY = 'This automation job names a site this workspace does not have.';
+export const AI_WORKFLOW_UNAVAILABLE_COPY = 'Automations are not available on this site.';
+export const AI_WORKFLOW_GONE_COPY = 'That automation no longer exists.';
+export const AI_WORKFLOW_RUN_GONE_COPY = 'That run is no longer in the automation’s history.';
+export const AI_WORKFLOW_RUN_NOT_FAILED_COPY = 'That run did not fail, so there is nothing to explain.';
+export const AI_WORKFLOW_NO_DRAFT_COPY = 'The AI could not draft an automation from this description. Try describing what happens, and what should happen then.';
+export const AI_WORKFLOW_NO_EXPLANATION_COPY = 'The AI could not explain this automation. Try again.';
+export const AI_WORKFLOW_SAVE_FAILURE_COPY = 'The automation was drafted but could not be saved. Try the job again.';
+
+//# sourceMappingURL=ai-workflow-job.js.map

package/src/lib/model/ai-workflow-job.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-workflow-job.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { HostActionStepType } from '@aglyn/aglyn/app-utils/actions'\nimport { checkEntitlement } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport {\n  HOST_EVENT_LABELS,\n  HOST_EVENT_TYPES,\n  type HostEventType,\n} from '@aglyn/aglyn/app-utils/workflows'\nimport type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types'\n\n/**\n * A `workflow` job (AGL-2919): an automation drafted from a description, or an\n * existing automation explained — what it does, or why one of its runs failed.\n *\n * One kind, three modes, because the three share everything a job carries:\n * the site, the gates, the meter and the automation vocabulary. `inputs.mode`\n * picks the mode, and a job created without one drafts.\n *\n *  - `draft` writes a new automation to the site's Actions through the\n *    workflows plugin's draft writer, OFF, built only from the triggers and\n *    steps below that this workspace can run. What the description names that\n *    the site does not have is left as a placeholder, never guessed.\n *  - `explain` reads a saved automation — an action or a workflow — and\n *    answers in plain words what it does.\n *  - `diagnose` reads a saved automation and one of its FAILED runs, as the\n *    run history recorded it, and answers why it failed and what to change.\n *\n * Nothing in any mode switches an automation on, runs one, or changes one.\n */\n\nexport const AI_WORKFLOW_JOB_MODES = ['draft', 'explain', 'diagnose'] as const\nexport type AiWorkflowJobMode = (typeof AI_WORKFLOW_JOB_MODES)[number]\n\n/** What an explained automation is: an action, or a workflow of function calls. */\nexport const AI_WORKFLOW_TARGET_TYPES = ['action', 'workflow'] as const\nexport type AiWorkflowTargetType = (typeof AI_WORKFLOW_TARGET_TYPES)[number]\n\nexport type AiWorkflowJobInputs =\n  | { mode: 'draft' }\n  | { mode: 'explain'; targetType: AiWorkflowTargetType; targetId: string }\n  | { mode: 'diagnose'; targetType: AiWorkflowTargetType; targetId: string; runId: string }\n\nconst DOCUMENT_ID = /^[A-Za-z0-9_-]{1,128}$/\n\n/** A job's inputs read into its mode, or the sentence that says what is wrong with them. */\nexport function parseAiWorkflowJobInputs(\n  inputs: Readonly<Record<string, unknown>> | null | undefined,\n): AiWorkflowJobInputs | string {\n  const mode = inputs?.['mode'] ?? 'draft'\n  if (!(AI_WORKFLOW_JOB_MODES as readonly unknown[]).includes(mode)) {\n    return 'inputs.mode must be draft, explain or diagnose'\n  }\n  if (mode === 'draft') return { mode }\n  const targetType = inputs?.['targetType']\n  const targetId = inputs?.['targetId']\n  if (\n    !(AI_WORKFLOW_TARGET_TYPES as readonly unknown[]).includes(targetType) ||\n    typeof targetId !== 'string' ||\n    !DOCUMENT_ID.test(targetId)\n  ) {\n    return 'Pick the automation to explain'\n  }\n  const target = { targetType: targetType as AiWorkflowTargetType, targetId }\n  if (mode === 'explain') return { mode, ...target }\n  const runId = inputs?.['runId']\n  if (typeof runId !== 'string' || !DOCUMENT_ID.test(runId)) return 'Pick the run to explain'\n  return { mode: 'diagnose', ...target, runId }\n}\n\n// ── What a workspace can run ──────────────────────────────────────────────\n\n/** A part of the platform some triggers and steps need beyond the actions builder itself. */\nexport type AiAutomationNeed = 'crm' | 'webhooks' | 'bookings'\n\nexport type AiAutomationCapabilities = Readonly<Record<AiAutomationNeed, boolean>>\n\n/** Each need as a sentence names it. */\nexport const AI_AUTOMATION_NEED_LABELS: Readonly<Record<AiAutomationNeed, string>> = {\n  crm: 'the CRM',\n  webhooks: 'webhooks',\n  bookings: 'bookings',\n}\n\n/**\n * What this workspace can run, from the entitlements the executor itself\n * reads before it runs a step: `crm` for the CRM steps, `webhooks` for a\n * webhook post, and `bookings` for the booking trigger's door.\n */\nexport function aiAutomationCapabilities(\n  org: Partial<AglynOrgBilling> | Readonly<Record<string, unknown>> | null | undefined,\n): AiAutomationCapabilities {\n  const billing = org as Partial<AglynOrgBilling> | null | undefined\n  return {\n    crm: checkEntitlement(billing, 'crm'),\n    webhooks: checkEntitlement(billing, 'webhooks'),\n    bookings: checkEntitlement(billing, 'bookings'),\n  }\n}\n\n// ── The vocabulary ────────────────────────────────────────────────────────\n\n/**\n * The triggers a drafted automation may start on: every host event, which is\n * every event a server door emits. The on-page events (a click, a scroll) are\n * left out: they watch one element of one page, which a description cannot\n * name, and they belong to the page's own interactions.\n */\nexport const AI_AUTOMATION_TRIGGERS: readonly HostEventType[] = HOST_EVENT_TYPES\n\n/** The triggers only a door of a part of the platform emits. */\nexport const AI_AUTOMATION_TRIGGER_NEEDS: Readonly<Partial<Record<HostEventType, AiAutomationNeed>>> = {\n  booking: 'bookings',\n  taskCompleted: 'crm',\n  contactStageChanged: 'crm',\n  dealStageChanged: 'crm',\n  dealWon: 'crm',\n  dealLost: 'crm',\n}\n\n/**\n * The steps a drafted automation may take: the server steps and the flow\n * steps, which act on the person an event names. The on-page steps — show an\n * element, open a menu, run a script — are left out for the reason the\n * on-page triggers are: they need a selector on a page a description cannot\n * name.\n */\nexport const AI_AUTOMATION_STEP_TYPES = [\n  'sendEmail',\n  'notifyAdmins',\n  'enrollList',\n  'assignCampaign',\n  'runWorkflow',\n  'datasetAppend',\n  'updateDataset',\n  'webhookPost',\n  'siteAlert',\n  'wait',\n  'waitForEvent',\n  'exitFlow',\n  'setContactStage',\n  'addContactTag',\n  'assignContactOwner',\n  'createCrmTask',\n  'logCrmActivity',\n] as const satisfies readonly HostActionStepType[]\n\nexport type AiAutomationStepType = (typeof AI_AUTOMATION_STEP_TYPES)[number]\n\n/** The steps the executor refuses without a part of the platform. */\nexport const AI_AUTOMATION_STEP_NEEDS: Readonly<Partial<Record<AiAutomationStepType, AiAutomationNeed>>> = {\n  webhookPost: 'webhooks',\n  setContactStage: 'crm',\n  addContactTag: 'crm',\n  assignContactOwner: 'crm',\n  createCrmTask: 'crm',\n  logCrmActivity: 'crm',\n}\n\n/** The trigger's name as the Actions editor labels it. */\nexport function aiAutomationTriggerLabel(event: string): string {\n  return HOST_EVENT_LABELS[event as HostEventType] ?? event\n}\n\n// ── A description the vocabulary cannot build ─────────────────────────────\n\n/**\n * Why a description was answered with no automation. Each is a fixed reason\n * with a fixed sentence, so what a person reads is never the model's own\n * account of itself.\n */\nexport const AI_AUTOMATION_UNSUPPORTED = [\n  'not-an-automation',\n  'no-trigger',\n  'no-step',\n  'needs-crm',\n  'needs-webhooks',\n  'needs-bookings',\n] as const\n\nexport type AiAutomationUnsupported = (typeof AI_AUTOMATION_UNSUPPORTED)[number]\n\n/** The need an unsupported reason names, for the reasons that name one. */\nexport const AI_AUTOMATION_UNSUPPORTED_NEED: Readonly<\n  Partial<Record<AiAutomationUnsupported, AiAutomationNeed>>\n> = {\n  'needs-crm': 'crm',\n  'needs-webhooks': 'webhooks',\n  'needs-bookings': 'bookings',\n}\n\nexport const AI_AUTOMATION_UNSUPPORTED_COPY: Readonly<Record<AiAutomationUnsupported, string>> = {\n  'not-an-automation':\n    'This description is not an automation — something that happens, and what to do then — so nothing was drafted.',\n  'no-trigger':\n    'Nothing on the platform can start an automation like this one, so nothing was drafted. Describe it as something that happens on your site, such as a form being submitted.',\n  'no-step': 'An automation cannot do what this description asks yet, so nothing was drafted.',\n  'needs-crm':\n    'This automation needs the CRM, which this workspace’s plan does not include, so nothing was drafted.',\n  'needs-webhooks':\n    'This automation needs webhooks, which this workspace’s plan does not include, so nothing was drafted.',\n  'needs-bookings':\n    'This automation needs bookings, which this workspace’s plan does not include, so nothing was drafted.',\n}\n\n// ── What a job tells a person ─────────────────────────────────────────────\n\n/** The id the workflows plugin is registered under. */\nexport const AI_WORKFLOWS_PLUGIN_ID = 'workflows'\n\n/** The resource the workflows plugin writes a drafted automation under. */\nexport const AI_AUTOMATION_RESOURCE = 'automation'\n\nexport const AI_WORKFLOW_NO_SITE_COPY = 'This automation job names a site this workspace does not have.'\nexport const AI_WORKFLOW_UNAVAILABLE_COPY = 'Automations are not available on this site.'\nexport const AI_WORKFLOW_GONE_COPY = 'That automation no longer exists.'\nexport const AI_WORKFLOW_RUN_GONE_COPY = 'That run is no longer in the automation’s history.'\nexport const AI_WORKFLOW_RUN_NOT_FAILED_COPY = 'That run did not fail, so there is nothing to explain.'\nexport const AI_WORKFLOW_NO_DRAFT_COPY =\n  'The AI could not draft an automation from this description. Try describing what happens, and what should happen then.'\nexport const AI_WORKFLOW_NO_EXPLANATION_COPY =\n  'The AI could not explain this automation. Try again.'\nexport const AI_WORKFLOW_SAVE_FAILURE_COPY =\n  'The automation was drafted but could not be saved. Try the job again.'\n"],"names":["checkEntitlement","HOST_EVENT_LABELS","HOST_EVENT_TYPES","AI_WORKFLOW_JOB_MODES","AI_WORKFLOW_TARGET_TYPES","DOCUMENT_ID","parseAiWorkflowJobInputs","inputs","mode","includes","targetType","targetId","test","target","runId","AI_AUTOMATION_NEED_LABELS","crm","webhooks","bookings","aiAutomationCapabilities","org","billing","AI_AUTOMATION_TRIGGERS","AI_AUTOMATION_TRIGGER_NEEDS","booking","taskCompleted","contactStageChanged","dealStageChanged","dealWon","dealLost","AI_AUTOMATION_STEP_TYPES","AI_AUTOMATION_STEP_NEEDS","webhookPost","setContactStage","addContactTag","assignContactOwner","createCrmTask","logCrmActivity","aiAutomationTriggerLabel","event","AI_AUTOMATION_UNSUPPORTED","AI_AUTOMATION_UNSUPPORTED_NEED","AI_AUTOMATION_UNSUPPORTED_COPY","AI_WORKFLOWS_PLUGIN_ID","AI_AUTOMATION_RESOURCE","AI_WORKFLOW_NO_SITE_COPY","AI_WORKFLOW_UNAVAILABLE_COPY","AI_WORKFLOW_GONE_COPY","AI_WORKFLOW_RUN_GONE_COPY","AI_WORKFLOW_RUN_NOT_FAILED_COPY","AI_WORKFLOW_NO_DRAFT_COPY","AI_WORKFLOW_NO_EXPLANATION_COPY","AI_WORKFLOW_SAVE_FAILURE_COPY"],"mappings":"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"}

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

@@ -0,0 +1,261 @@
+/**
+ * @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 { ScreenSeoTextField } from '@aglyn/aglyn/app-utils/screen-seo-fields';
+import type { ReusableComponentProp } from '@aglyn/aglyn/foundation/definitions/platform.types';
+/**
+ * Assist level 3, the edit contract (AGL-2906): what the chat door proposes
+ * for a besigner canvas, and what the panel applies once the author says so.
+ *
+ * Shared by the server, which validates a model's proposal into these
+ * shapes, and the client, which applies them. Pure data and pure functions,
+ * so the panel imports it without pulling the palette or the runtime.
+ *
+ * ## The boundary
+ *
+ * A proposal is OPERATIONS, never a document. The server writes nothing: it
+ * answers with ops that name elements already on the canvas, or a validated
+ * subtree to insert, and the client applies them through the canvas's own
+ * guarded mutators, on confirm, as one undoable step. Every change lands as
+ * an unsaved edit on the version the editor has open — a draft — and on a
+ * version the live site serves, the editor's own new-version flow runs first.
+ */
+/** The eight operations a proposal may carry. */
+export declare const ASSIST_EDIT_OP_KINDS: readonly ["insertSubtree", "updateProps", "updateSx", "move", "remove", "setSeo", "rename", "saveAsComponent"];
+export type AssistEditOpKind = (typeof ASSIST_EDIT_OP_KINDS)[number];
+/** The id of the besigner view's edit action — the one edit a view offers. */
+export declare const ASSIST_EDIT_ACTION_ID = "edit.canvas";
+/** The name of the structured-output tool a model proposes an edit through. */
+export declare const ASSIST_EDIT_TOOL_NAME = "propose_canvas_edit";
+/** The besigner documents the edit rung opens on: those that keep versions. */
+export type AssistEditDocumentKind = 'screen' | 'component' | 'layout';
+export declare const ASSIST_EDIT_DOCUMENT_KINDS: readonly AssistEditDocumentKind[];
+/** The document a besigner route has open. */
+export interface AssistEditDocument {
+    kind: AssistEditDocumentKind;
+    documentId: string;
+    versionId: string;
+}
+/**
+ * The open document off a console path, or null off a route the edit rung
+ * serves. Only the versioned editors qualify — a template or an email editor
+ * has no version to make first, so the rung does not open there.
+ */
+export declare function assistEditDocumentOf(route: string): AssistEditDocument | null;
+/** Elements a request describes at most — the selection, its surroundings, its subtree. */
+export declare const ASSIST_EDIT_CONTEXT_MAX_NODES = 60;
+/** Props described per element at most. */
+export declare const ASSIST_EDIT_CONTEXT_MAX_PROPS = 16;
+/** Characters of a string prop the selected element carries into a request. */
+export declare const ASSIST_EDIT_SELECTED_TEXT_CHARS = 400;
+/** Characters of a string prop every other element carries. */
+export declare const ASSIST_EDIT_OUTLINE_TEXT_CHARS = 80;
+/**
+ * One element of the canvas outline a request carries. Ids, component ids
+ * and short primitive values only — never a stored document, never markup.
+ */
+export interface AssistEditCanvasNode {
+    id: string;
+    componentId: string;
+    /** Null for the document root. */
+    parentId: string | null;
+    /** Position among the parent's children. */
+    index: number;
+    childCount: number;
+    /** The layer name, when the author gave it one. */
+    name?: string;
+    /** Primitive props, strings shortened. */
+    props?: Record<string, string | number | boolean>;
+    /** The element's own styles — carried for the selected element only. */
+    sx?: Record<string, unknown>;
+    /**
+     * Described by its place alone, without props: an element around the
+     * selection, there so the model knows it exists and can ask for it.
+     */
+    brief?: boolean;
+    /**
+     * An element described earlier whose contents this one's are built like,
+     * the way the cards of a row are. Its own contents are left out.
+     */
+    like?: string;
+}
+export interface AssistEditCanvasContext {
+    /** The element the author has selected, or null. */
+    selectedId: string | null;
+    /**
+     * Elements in the whole document, the root included, so the prompt can say
+     * how much of it `nodes` leaves out. Absent from an outline sent by a panel
+     * that predates it.
+     */
+    total?: number;
+    nodes: AssistEditCanvasNode[];
+}
+/** An element of a validated subtree, in the flat shape the canvas stores. */
+export interface AssistEditNode {
+    $id: string;
+    componentId: string;
+    pluginId?: string;
+    parentId: string | null;
+    nodes: string[];
+    props: Record<string, unknown>;
+    sx?: Record<string, unknown>;
+    hidden?: boolean;
+}
+/**
+ * Every op that acts on an element names the component the server validated
+ * it as, so the client can refuse an element that has changed since.
+ */
+interface AssistEditNodeOpBase {
+    nodeId: string;
+    componentId: string;
+}
+export interface AssistEditInsertOp {
+    op: 'insertSubtree';
+    parentId: string;
+    /** The component the parent was validated as. */
+    parentComponentId: string;
+    /** Position among the parent's children; null appends. */
+    index: number | null;
+    rootId: string;
+    nodes: Record<string, AssistEditNode>;
+}
+export interface AssistEditUpdatePropsOp extends AssistEditNodeOpBase {
+    op: 'updateProps';
+    /** Merged over the props the element has; nothing else it carries changes. */
+    props: Record<string, unknown>;
+}
+export interface AssistEditUpdateSxOp extends AssistEditNodeOpBase {
+    op: 'updateSx';
+    /** Merged over the element's own styles, one key at a time. */
+    sx: Record<string, unknown>;
+}
+export interface AssistEditMoveOp extends AssistEditNodeOpBase {
+    op: 'move';
+    parentId: string;
+    /** The component the new parent was validated as. */
+    parentComponentId: string;
+    index: number | null;
+}
+export interface AssistEditRemoveOp extends AssistEditNodeOpBase {
+    op: 'remove';
+}
+export interface AssistEditRenameOp extends AssistEditNodeOpBase {
+    op: 'rename';
+    name: string;
+}
+export interface AssistEditSetSeoOp {
+    op: 'setSeo';
+    fields: Partial<Record<ScreenSeoTextField, string>>;
+}
+/**
+ * A property the promoted subtree declares (AGL-2908), in the shape the
+ * Properties dialog stores one — without a default.
+ *
+ * The server never sees a full value: the outline it read the selection from
+ * shortens every string. So the default is read off the live canvas at apply
+ * time, from the very field the token is about to replace, which is what
+ * makes the instance render what was there a moment before.
+ */
+export type AssistEditComponentProp = Omit<ReusableComponentProp, 'defaultValue'>;
+/** Where one property's token goes: an element of the selection, and a field of it. */
+export interface AssistEditPropBinding {
+    nodeId: string;
+    /** The component the element was validated as, so a changed one is refused. */
+    componentId: string;
+    /** A prop of that element, or `hideIf` for a part a Yes / no hides. */
+    field: string;
+    /** The property whose `{{prop.<name>}}` token the field takes. */
+    prop: string;
+}
+/**
+ * Save the selection as a reusable component (AGL-2908), with the properties
+ * the model proposed and the tokens bound into the tree.
+ *
+ * The only op that creates a document. It creates exactly the one the manual
+ * Save as reusable component creates, through the same host resources route,
+ * where the plan's entitlement and the route's allow-list are enforced — and
+ * it changes the open canvas the same way that action does, by swapping the
+ * promoted subtree for an instance. Nothing is published and nothing is
+ * saved: the swap is an unsaved edit on the version the editor has open.
+ */
+export interface AssistEditSaveAsComponentOp extends AssistEditNodeOpBase {
+    op: 'saveAsComponent';
+    /** The name the component is created under. */
+    name: string;
+    props: AssistEditComponentProp[];
+    bindings: AssistEditPropBinding[];
+}
+export type AssistEditOp = AssistEditInsertOp | AssistEditUpdatePropsOp | AssistEditUpdateSxOp | AssistEditMoveOp | AssistEditRemoveOp | AssistEditRenameOp | AssistEditSetSeoOp | AssistEditSaveAsComponentOp;
+/** Where a proposal applies, as the server read it off the request. */
+export interface AssistEditTarget extends AssistEditDocument {
+    hostId: string;
+}
+/** The counts the card shows before the author decides. */
+export interface AssistEditDiff {
+    /** Elements added, every element of every inserted subtree counted. */
+    added: number;
+    /** Elements removed — each with whatever it contains. */
+    removed: number;
+    propsChanged: number;
+    stylesChanged: number;
+    moved: number;
+    renamed: number;
+    /** Search fields filled in. */
+    seoFields: number;
+    /** Properties the selection declares once it is saved as a component. */
+    componentProps: number;
+    /** Selections saved as a reusable component — at most one per proposal. */
+    componentsSaved: number;
+}
+/** The most reasons a proposal carries for the changes validation left out. */
+export declare const ASSIST_EDIT_MAX_DROPPED_REASONS = 10;
+export interface AssistEditProposal {
+    id: typeof ASSIST_EDIT_ACTION_ID;
+    /** One line, in the model's words, of what the edit does. */
+    summary: string;
+    ops: AssistEditOp[];
+    diff: AssistEditDiff;
+    /** Why each change the model wrote and validation refused was left out. */
+    dropped: string[];
+    target: AssistEditTarget;
+}
+/** The counts for a list of ops. */
+export declare function summarizeAssistEditOps(ops: readonly AssistEditOp[]): AssistEditDiff;
+/** The diff as the lines a person reads, zero counts omitted. */
+export declare function describeAssistEditDiff(diff: AssistEditDiff): string[];
+/** The applied ops counted by kind, as the activity row names them (`{ set: 3, insert: 1 }`). */
+export declare function assistEditOpCounts(ops: readonly AssistEditOp[]): Record<string, number>;
+/** The words `assistEditOpCounts` counts under, for a door that reads them back. */
+export declare const ASSIST_EDIT_OP_COUNT_WORDS: readonly string[];
+/**
+ * Whether a `done` event's `edit` field is a proposal this client can apply.
+ * The server built it, so this is a shape check rather than a validation: it
+ * keeps a malformed or foreign payload from reaching the canvas mutators.
+ */
+export declare function isAssistEditProposal(value: unknown): value is AssistEditProposal;
+/** The body of `POST /api/assist/edit-applied`. */
+export interface AssistEditAppliedReport {
+    orgId: string;
+    hostId: string;
+    /** The exchange whose answer carried the proposal. */
+    exchangeId: string;
+    documentKind: AssistEditDocumentKind;
+    documentId: string;
+    /** The version the edits landed on — a new one when the open one was live. */
+    versionId: string;
+    opCounts: Record<string, number>;
+}
+export {};

package/src/lib/model/assist-edit.js

@@ -0,0 +1,175 @@
+/**
+ * @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.
+ */ /**
+ * Assist level 3, the edit contract (AGL-2906): what the chat door proposes
+ * for a besigner canvas, and what the panel applies once the author says so.
+ *
+ * Shared by the server, which validates a model's proposal into these
+ * shapes, and the client, which applies them. Pure data and pure functions,
+ * so the panel imports it without pulling the palette or the runtime.
+ *
+ * ## The boundary
+ *
+ * A proposal is OPERATIONS, never a document. The server writes nothing: it
+ * answers with ops that name elements already on the canvas, or a validated
+ * subtree to insert, and the client applies them through the canvas's own
+ * guarded mutators, on confirm, as one undoable step. Every change lands as
+ * an unsaved edit on the version the editor has open — a draft — and on a
+ * version the live site serves, the editor's own new-version flow runs first.
+ */ /** The eight operations a proposal may carry. */ export const ASSIST_EDIT_OP_KINDS = [
+    'insertSubtree',
+    'updateProps',
+    'updateSx',
+    'move',
+    'remove',
+    'setSeo',
+    'rename',
+    'saveAsComponent'
+];
+/** The id of the besigner view's edit action — the one edit a view offers. */ export const ASSIST_EDIT_ACTION_ID = 'edit.canvas';
+/** The name of the structured-output tool a model proposes an edit through. */ export const ASSIST_EDIT_TOOL_NAME = 'propose_canvas_edit';
+export const ASSIST_EDIT_DOCUMENT_KINDS = [
+    'screen',
+    'component',
+    'layout'
+];
+const COLLECTION_KINDS = {
+    screens: 'screen',
+    components: 'component',
+    layouts: 'layout'
+};
+const BESIGNER_DOCUMENT_ROUTE = /^\/[^/]+\/hosts\/[^/]+\/(screens|components|layouts)\/([A-Za-z0-9_-]{1,64})\/versions\/([A-Za-z0-9_-]{1,64})\/besigner\/?$/;
+/**
+ * The open document off a console path, or null off a route the edit rung
+ * serves. Only the versioned editors qualify — a template or an email editor
+ * has no version to make first, so the rung does not open there.
+ */ export function assistEditDocumentOf(route) {
+    const match = BESIGNER_DOCUMENT_ROUTE.exec(String(route != null ? route : ''));
+    if (!match) return null;
+    return {
+        kind: COLLECTION_KINDS[match[1]],
+        documentId: match[2],
+        versionId: match[3]
+    };
+}
+/* ------------------------------------------------------------------ *
+ * What the client tells the server about the canvas
+ * ------------------------------------------------------------------ */ /** Elements a request describes at most — the selection, its surroundings, its subtree. */ export const ASSIST_EDIT_CONTEXT_MAX_NODES = 60;
+/** Props described per element at most. */ export const ASSIST_EDIT_CONTEXT_MAX_PROPS = 16;
+/** Characters of a string prop the selected element carries into a request. */ export const ASSIST_EDIT_SELECTED_TEXT_CHARS = 400;
+/** Characters of a string prop every other element carries. */ export const ASSIST_EDIT_OUTLINE_TEXT_CHARS = 80;
+/** The most reasons a proposal carries for the changes validation left out. */ export const ASSIST_EDIT_MAX_DROPPED_REASONS = 10;
+/** The counts for a list of ops. */ export function summarizeAssistEditOps(ops) {
+    const diff = {
+        added: 0,
+        removed: 0,
+        propsChanged: 0,
+        stylesChanged: 0,
+        moved: 0,
+        renamed: 0,
+        seoFields: 0,
+        componentProps: 0,
+        componentsSaved: 0
+    };
+    for (const op of ops){
+        switch(op.op){
+            case 'insertSubtree':
+                diff.added += Object.keys(op.nodes).length;
+                break;
+            case 'remove':
+                diff.removed += 1;
+                break;
+            case 'updateProps':
+                diff.propsChanged += 1;
+                break;
+            case 'updateSx':
+                diff.stylesChanged += 1;
+                break;
+            case 'move':
+                diff.moved += 1;
+                break;
+            case 'rename':
+                diff.renamed += 1;
+                break;
+            case 'setSeo':
+                diff.seoFields += Object.keys(op.fields).length;
+                break;
+            case 'saveAsComponent':
+                diff.componentsSaved += 1;
+                diff.componentProps += op.props.length;
+                break;
+        }
+    }
+    return diff;
+}
+const plural = (count, one, many)=>`${count} ${count === 1 ? one : many}`;
+/** The diff as the lines a person reads, zero counts omitted. */ export function describeAssistEditDiff(diff) {
+    const lines = [];
+    if (diff.added) lines.push(`${plural(diff.added, 'element', 'elements')} added`);
+    if (diff.removed) lines.push(`${plural(diff.removed, 'element', 'elements')} removed`);
+    if (diff.propsChanged) {
+        lines.push(`${plural(diff.propsChanged, 'element’s settings', 'elements’ settings')} changed`);
+    }
+    if (diff.stylesChanged) {
+        lines.push(`${plural(diff.stylesChanged, 'element', 'elements')} restyled`);
+    }
+    if (diff.moved) lines.push(`${plural(diff.moved, 'element', 'elements')} moved`);
+    if (diff.renamed) lines.push(`${plural(diff.renamed, 'layer', 'layers')} renamed`);
+    if (diff.seoFields) {
+        lines.push(`${plural(diff.seoFields, 'search field', 'search fields')} filled in`);
+    }
+    if (diff.componentsSaved) {
+        lines.push(`saved as a reusable component with ${plural(diff.componentProps, 'property', 'properties')}`);
+    }
+    return lines;
+}
+/** The word each op kind is counted under in the activity row. */ const OP_COUNT_WORDS = {
+    updateProps: 'set',
+    updateSx: 'restyle',
+    insertSubtree: 'insert',
+    move: 'move',
+    remove: 'remove',
+    rename: 'rename',
+    setSeo: 'seo',
+    saveAsComponent: 'component'
+};
+/** The applied ops counted by kind, as the activity row names them (`{ set: 3, insert: 1 }`). */ export function assistEditOpCounts(ops) {
+    const counts = {};
+    for (const op of ops){
+        var _counts_word;
+        const word = OP_COUNT_WORDS[op.op];
+        if (word) counts[word] = ((_counts_word = counts[word]) != null ? _counts_word : 0) + 1;
+    }
+    return counts;
+}
+/** The words `assistEditOpCounts` counts under, for a door that reads them back. */ export const ASSIST_EDIT_OP_COUNT_WORDS = Object.values(OP_COUNT_WORDS);
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Whether a `done` event's `edit` field is a proposal this client can apply.
+ * The server built it, so this is a shape check rather than a validation: it
+ * keeps a malformed or foreign payload from reaching the canvas mutators.
+ */ export function isAssistEditProposal(value) {
+    if (!isRecord(value) || value['id'] !== ASSIST_EDIT_ACTION_ID) return false;
+    const target = value['target'];
+    if (!isRecord(target)) return false;
+    if (!ASSIST_EDIT_DOCUMENT_KINDS.includes(target['kind'])) return false;
+    if (typeof target['documentId'] !== 'string' || !target['documentId']) return false;
+    const ops = value['ops'];
+    if (!Array.isArray(ops) || !ops.length) return false;
+    return ops.every((op)=>isRecord(op) && ASSIST_EDIT_OP_KINDS.includes(op['op']));
+}
+
+//# sourceMappingURL=assist-edit.js.map