@aglyn/plugins-ai 1.0.0-beta.229 → 1.0.0-beta.231

package/src/lib/model/ai-svg.js

@@ -0,0 +1,265 @@
+/**
+ * @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 { sanitizeSvg } from "@aglyn/aglyn/app-utils/sanitize-svg";
+/**
+ * The SVG an illustration arrives as (AGL-3602), and the one gate it passes
+ * before it is stored.
+ *
+ * A model writes SVG as text, and SVG is a document: it can carry script,
+ * event handlers, links out and HTML. The upload route strips all of that
+ * from anything it stores (`sanitize-svg`), so a dangerous answer could never
+ * be SERVED — but a stripped answer is no longer the picture the model meant,
+ * so this does not quietly accept one. Anything the sanitizer would have to
+ * remove, and anything a self-contained static picture has no use for, is a
+ * problem the model is told about and asked to fix once; a second answer with
+ * a problem is not stored at all.
+ *
+ * A picture that passes is:
+ *
+ * - one `<svg>` root in the SVG namespace, with a `viewBox` in the shape asked
+ *   for, and balanced tags;
+ * - at most `AI_SVG_MAX_BYTES`;
+ * - self-contained: no `<image>`, no `<foreignObject>`, no `<script>`, no
+ *   `<a>`, no event handler, no link or `url(…)` to anything but a `#fragment`
+ *   in the same document, no `@import` and no `@font-face`;
+ * - static: no `<animate>`, `<set>` or other animation element;
+ * - for a logo mark, free of `<text>`: a mark, never a wordmark;
+ * - unchanged by `sanitizeSvg`.
+ */ /** The largest illustration stored, in bytes of UTF-8. */ export const AI_SVG_MAX_BYTES = 200 * 1024;
+/** The `viewBox` each shape is drawn in. */ export const AI_SVG_VIEWBOX = {
+    '1:1': '0 0 512 512',
+    '4:3': '0 0 640 480',
+    '3:4': '0 0 480 640',
+    '16:9': '0 0 960 540',
+    '9:16': '0 0 540 960'
+};
+/** How far a `viewBox`'s proportions may stray from the shape asked for. */ const RATIO_TOLERANCE = 0.03;
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+const FORBIDDEN_ELEMENTS = [
+    [
+        /<\s*(?:[\w-]+:)?script\b/i,
+        'script',
+        'Remove every <script> element.'
+    ],
+    [
+        /<\s*(?:[\w-]+:)?foreignObject\b/i,
+        'foreign-object',
+        'Remove every <foreignObject> element.'
+    ],
+    [
+        /<\s*(?:[\w-]+:)?image\b/i,
+        'image',
+        'Remove every <image> element: draw with shapes and paths only.'
+    ],
+    [
+        /<\s*(?:[\w-]+:)?(?:iframe|embed|object|audio|video|canvas)\b/i,
+        'embed',
+        'Remove every embedded document or media element.'
+    ],
+    [
+        /<\s*(?:[\w-]+:)?a\b/i,
+        'link',
+        'Remove every <a> element: the picture links nowhere.'
+    ],
+    [
+        /<\s*(?:[\w-]+:)?(?:animate|animateMotion|animateTransform|set|discard)\b/i,
+        'animation',
+        'Remove every animation element: the picture is static.'
+    ]
+];
+/** The proportions of a `viewBox` value, or `null` when it is not one. */ function viewBoxRatio(value) {
+    const parts = value.trim().split(/[\s,]+/).map(Number);
+    if (parts.length !== 4 || parts.some((part)=>!Number.isFinite(part))) return null;
+    const [, , width, height] = parts;
+    return width > 0 && height > 0 ? width / height : null;
+}
+/**
+ * Whether every element opened is closed, in order, under ONE root that
+ * closes last. Comments and CDATA are skipped.
+ */ function tagsBalance(svg) {
+    const stripped = svg.replace(/<!--[\s\S]*?-->/g, '').replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '');
+    const stack = [];
+    let closedRoot = false;
+    for (const match of stripped.matchAll(/<(\/?)([A-Za-z][\w:.-]*)[^<>]*?(\/?)>/g)){
+        const [, closing, name, selfClosing] = match;
+        // Anything after the root closed is a second root.
+        if (closedRoot) return false;
+        if (selfClosing) {
+            if (!stack.length) return false;
+            continue;
+        }
+        if (closing) {
+            if (stack.pop() !== name) return false;
+            if (!stack.length) closedRoot = true;
+        } else {
+            stack.push(name);
+        }
+    }
+    return stack.length === 0 && closedRoot;
+}
+/**
+ * The gate. `markup` is the model's answer; the result is the document to
+ * store, or the problems to send back.
+ */ export function checkAiSvgMarkup(markup, aspectRatio, style) {
+    const problems = [];
+    const svg = String(markup != null ? markup : '').trim()// An XML declaration is harmless and the sanitizer would drop it.
+    .replace(/^<\?xml[^>]*\?>\s*/i, '');
+    if (!svg) {
+        return {
+            svg: null,
+            problems: [
+                {
+                    code: 'empty',
+                    detail: 'Answer with the SVG document itself.'
+                }
+            ]
+        };
+    }
+    const bytes = new TextEncoder().encode(svg).length;
+    if (bytes > AI_SVG_MAX_BYTES) {
+        problems.push({
+            code: 'too-large',
+            detail: `The SVG is ${Math.round(bytes / 1024)} KB; keep it under ${AI_SVG_MAX_BYTES / 1024} KB with fewer, simpler paths.`
+        });
+    }
+    const root = /^<svg\b([^>]*)>/i.exec(svg);
+    if (!root || !/<\/svg>$/i.test(svg)) {
+        problems.push({
+            code: 'root',
+            detail: 'Answer with exactly one <svg> element and nothing around it.'
+        });
+    } else {
+        const attributes = root[1];
+        if (!new RegExp(`xmlns\\s*=\\s*["']${SVG_NAMESPACE.replace(/[.]/g, '\\.')}["']`).test(attributes)) {
+            problems.push({
+                code: 'namespace',
+                detail: `Give the <svg> element xmlns="${SVG_NAMESPACE}".`
+            });
+        }
+        const viewBox = /\bviewBox\s*=\s*["']([^"']*)["']/.exec(attributes);
+        const expected = viewBoxRatio(AI_SVG_VIEWBOX[aspectRatio]);
+        const ratio = viewBox ? viewBoxRatio(viewBox[1]) : null;
+        if (ratio === null) {
+            problems.push({
+                code: 'viewbox',
+                detail: `Give the <svg> element viewBox="${AI_SVG_VIEWBOX[aspectRatio]}".`
+            });
+        } else if (Math.abs(ratio - expected) / expected > RATIO_TOLERANCE) {
+            problems.push({
+                code: 'viewbox-shape',
+                detail: `The viewBox is the wrong shape; use viewBox="${AI_SVG_VIEWBOX[aspectRatio]}".`
+            });
+        }
+    }
+    if (root && !tagsBalance(svg)) {
+        problems.push({
+            code: 'malformed',
+            detail: 'The SVG is not well-formed: close every element you open.'
+        });
+    }
+    for (const [pattern, code, detail] of FORBIDDEN_ELEMENTS){
+        if (pattern.test(svg)) problems.push({
+            code,
+            detail
+        });
+    }
+    if (/\son[a-z]+\s*=/i.test(svg)) {
+        problems.push({
+            code: 'event-handler',
+            detail: 'Remove every on… event attribute.'
+        });
+    }
+    for (const match of svg.matchAll(/\s(?:xlink:)?href\s*=\s*["']([^"']*)["']/gi)){
+        if (!match[1].trim().startsWith('#')) {
+            problems.push({
+                code: 'external-ref',
+                detail: 'A href may only point at an element of this same SVG (#id).'
+            });
+            break;
+        }
+    }
+    for (const match of svg.matchAll(/url\(\s*['"]?([^)'"]*)/gi)){
+        if (!match[1].trim().startsWith('#')) {
+            problems.push({
+                code: 'external-url',
+                detail: 'url(…) may only point at an element of this same SVG (#id).'
+            });
+            break;
+        }
+    }
+    if (/@import\b/i.test(svg) || /@font-face\b/i.test(svg)) {
+        problems.push({
+            code: 'external-css',
+            detail: 'Remove @import and @font-face; use generic font families (sans-serif, serif) if any.'
+        });
+    }
+    if (style === 'logo' && /<\s*(?:[\w-]+:)?text\b/i.test(svg)) {
+        problems.push({
+            code: 'wordmark',
+            detail: 'A logo mark has no lettering: draw it with shapes and paths only.'
+        });
+    }
+    if (!problems.length) {
+        const sanitized = sanitizeSvg(svg);
+        if (sanitized.changed) {
+            problems.push({
+                code: 'unsafe',
+                detail: `Remove what an SVG served as an image may not carry: ${sanitized.removed.join(', ')}.`
+            });
+        }
+    }
+    return problems.length ? {
+        svg: null,
+        problems
+    } : {
+        svg,
+        problems
+    };
+}
+/** A color a person may name: `#rgb` or `#rrggbb`. */ export function isAiSvgColor(value) {
+    return typeof value === 'string' && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim());
+}
+/**
+ * The colors a site's theme names, in the order a picture reaches for them:
+ * the primary and secondary colors first, then the backgrounds and text.
+ */ export function aiSvgThemePalette(colors) {
+    if (!colors) return [];
+    const order = [
+        'primary.main',
+        'secondary.main',
+        'background.default',
+        'background.paper',
+        'text.primary',
+        'primary.light',
+        'primary.dark',
+        'secondary.light',
+        'secondary.dark'
+    ];
+    const keys = [
+        ...order.filter((key)=>key in colors),
+        ...Object.keys(colors).filter((key)=>!order.includes(key))
+    ];
+    const palette = [];
+    for (const key of keys){
+        var _colors_key;
+        const value = String((_colors_key = colors[key]) != null ? _colors_key : '').trim().toLowerCase();
+        if (isAiSvgColor(value) && !palette.includes(value)) palette.push(value);
+        if (palette.length >= 6) break;
+    }
+    return palette;
+}
+
+//# sourceMappingURL=ai-svg.js.map

package/src/lib/model/ai-svg.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-svg.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 { sanitizeSvg } from '@aglyn/aglyn/app-utils/sanitize-svg'\nimport type { AiImageAspectRatio, AiSvgStyle } from '../providers/image-contract'\n\n/**\n * The SVG an illustration arrives as (AGL-3602), and the one gate it passes\n * before it is stored.\n *\n * A model writes SVG as text, and SVG is a document: it can carry script,\n * event handlers, links out and HTML. The upload route strips all of that\n * from anything it stores (`sanitize-svg`), so a dangerous answer could never\n * be SERVED — but a stripped answer is no longer the picture the model meant,\n * so this does not quietly accept one. Anything the sanitizer would have to\n * remove, and anything a self-contained static picture has no use for, is a\n * problem the model is told about and asked to fix once; a second answer with\n * a problem is not stored at all.\n *\n * A picture that passes is:\n *\n * - one `<svg>` root in the SVG namespace, with a `viewBox` in the shape asked\n *   for, and balanced tags;\n * - at most `AI_SVG_MAX_BYTES`;\n * - self-contained: no `<image>`, no `<foreignObject>`, no `<script>`, no\n *   `<a>`, no event handler, no link or `url(…)` to anything but a `#fragment`\n *   in the same document, no `@import` and no `@font-face`;\n * - static: no `<animate>`, `<set>` or other animation element;\n * - for a logo mark, free of `<text>`: a mark, never a wordmark;\n * - unchanged by `sanitizeSvg`.\n */\n\n/** The largest illustration stored, in bytes of UTF-8. */\nexport const AI_SVG_MAX_BYTES = 200 * 1024\n\n/** The `viewBox` each shape is drawn in. */\nexport const AI_SVG_VIEWBOX: Readonly<Record<AiImageAspectRatio, string>> = {\n  '1:1': '0 0 512 512',\n  '4:3': '0 0 640 480',\n  '3:4': '0 0 480 640',\n  '16:9': '0 0 960 540',\n  '9:16': '0 0 540 960',\n}\n\n/** How far a `viewBox`'s proportions may stray from the shape asked for. */\nconst RATIO_TOLERANCE = 0.03\n\nconst SVG_NAMESPACE = 'http://www.w3.org/2000/svg'\n\nexport interface AiSvgProblem {\n  /** Stable per finding, for specs and logs. */\n  code: string\n  /** What the model is told to fix. */\n  detail: string\n}\n\nexport interface AiSvgCheck {\n  /** The document to store, or `null` when it has a problem. */\n  svg: string | null\n  problems: AiSvgProblem[]\n}\n\nconst FORBIDDEN_ELEMENTS: ReadonlyArray<[RegExp, string, string]> = [\n  [/<\\s*(?:[\\w-]+:)?script\\b/i, 'script', 'Remove every <script> element.'],\n  [/<\\s*(?:[\\w-]+:)?foreignObject\\b/i, 'foreign-object', 'Remove every <foreignObject> element.'],\n  [/<\\s*(?:[\\w-]+:)?image\\b/i, 'image', 'Remove every <image> element: draw with shapes and paths only.'],\n  [/<\\s*(?:[\\w-]+:)?(?:iframe|embed|object|audio|video|canvas)\\b/i, 'embed', 'Remove every embedded document or media element.'],\n  [/<\\s*(?:[\\w-]+:)?a\\b/i, 'link', 'Remove every <a> element: the picture links nowhere.'],\n  [\n    /<\\s*(?:[\\w-]+:)?(?:animate|animateMotion|animateTransform|set|discard)\\b/i,\n    'animation',\n    'Remove every animation element: the picture is static.',\n  ],\n]\n\n/** The proportions of a `viewBox` value, or `null` when it is not one. */\nfunction viewBoxRatio(value: string): number | null {\n  const parts = value.trim().split(/[\\s,]+/).map(Number)\n  if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part))) return null\n  const [, , width, height] = parts\n  return width > 0 && height > 0 ? width / height : null\n}\n\n/**\n * Whether every element opened is closed, in order, under ONE root that\n * closes last. Comments and CDATA are skipped.\n */\nfunction tagsBalance(svg: string): boolean {\n  const stripped = svg.replace(/<!--[\\s\\S]*?-->/g, '').replace(/<!\\[CDATA\\[[\\s\\S]*?\\]\\]>/g, '')\n  const stack: string[] = []\n  let closedRoot = false\n  for (const match of stripped.matchAll(/<(\\/?)([A-Za-z][\\w:.-]*)[^<>]*?(\\/?)>/g)) {\n    const [, closing, name, selfClosing] = match\n    // Anything after the root closed is a second root.\n    if (closedRoot) return false\n    if (selfClosing) {\n      if (!stack.length) return false\n      continue\n    }\n    if (closing) {\n      if (stack.pop() !== name) return false\n      if (!stack.length) closedRoot = true\n    } else {\n      stack.push(name)\n    }\n  }\n  return stack.length === 0 && closedRoot\n}\n\n/**\n * The gate. `markup` is the model's answer; the result is the document to\n * store, or the problems to send back.\n */\nexport function checkAiSvgMarkup(\n  markup: unknown,\n  aspectRatio: AiImageAspectRatio,\n  style: AiSvgStyle,\n): AiSvgCheck {\n  const problems: AiSvgProblem[] = []\n  const svg = String(markup ?? '')\n    .trim()\n    // An XML declaration is harmless and the sanitizer would drop it.\n    .replace(/^<\\?xml[^>]*\\?>\\s*/i, '')\n  if (!svg) {\n    return { svg: null, problems: [{ code: 'empty', detail: 'Answer with the SVG document itself.' }] }\n  }\n  const bytes = new TextEncoder().encode(svg).length\n  if (bytes > AI_SVG_MAX_BYTES) {\n    problems.push({\n      code: 'too-large',\n      detail: `The SVG is ${Math.round(bytes / 1024)} KB; keep it under ${AI_SVG_MAX_BYTES / 1024} KB with fewer, simpler paths.`,\n    })\n  }\n  const root = /^<svg\\b([^>]*)>/i.exec(svg)\n  if (!root || !/<\\/svg>$/i.test(svg)) {\n    problems.push({ code: 'root', detail: 'Answer with exactly one <svg> element and nothing around it.' })\n  } else {\n    const attributes = root[1]\n    if (!new RegExp(`xmlns\\\\s*=\\\\s*[\"']${SVG_NAMESPACE.replace(/[.]/g, '\\\\.')}[\"']`).test(attributes)) {\n      problems.push({ code: 'namespace', detail: `Give the <svg> element xmlns=\"${SVG_NAMESPACE}\".` })\n    }\n    const viewBox = /\\bviewBox\\s*=\\s*[\"']([^\"']*)[\"']/.exec(attributes)\n    const expected = viewBoxRatio(AI_SVG_VIEWBOX[aspectRatio]) as number\n    const ratio = viewBox ? viewBoxRatio(viewBox[1]) : null\n    if (ratio === null) {\n      problems.push({\n        code: 'viewbox',\n        detail: `Give the <svg> element viewBox=\"${AI_SVG_VIEWBOX[aspectRatio]}\".`,\n      })\n    } else if (Math.abs(ratio - expected) / expected > RATIO_TOLERANCE) {\n      problems.push({\n        code: 'viewbox-shape',\n        detail: `The viewBox is the wrong shape; use viewBox=\"${AI_SVG_VIEWBOX[aspectRatio]}\".`,\n      })\n    }\n  }\n  if (root && !tagsBalance(svg)) {\n    problems.push({ code: 'malformed', detail: 'The SVG is not well-formed: close every element you open.' })\n  }\n  for (const [pattern, code, detail] of FORBIDDEN_ELEMENTS) {\n    if (pattern.test(svg)) problems.push({ code, detail })\n  }\n  if (/\\son[a-z]+\\s*=/i.test(svg)) {\n    problems.push({ code: 'event-handler', detail: 'Remove every on… event attribute.' })\n  }\n  for (const match of svg.matchAll(/\\s(?:xlink:)?href\\s*=\\s*[\"']([^\"']*)[\"']/gi)) {\n    if (!match[1].trim().startsWith('#')) {\n      problems.push({\n        code: 'external-ref',\n        detail: 'A href may only point at an element of this same SVG (#id).',\n      })\n      break\n    }\n  }\n  for (const match of svg.matchAll(/url\\(\\s*['\"]?([^)'\"]*)/gi)) {\n    if (!match[1].trim().startsWith('#')) {\n      problems.push({ code: 'external-url', detail: 'url(…) may only point at an element of this same SVG (#id).' })\n      break\n    }\n  }\n  if (/@import\\b/i.test(svg) || /@font-face\\b/i.test(svg)) {\n    problems.push({\n      code: 'external-css',\n      detail: 'Remove @import and @font-face; use generic font families (sans-serif, serif) if any.',\n    })\n  }\n  if (style === 'logo' && /<\\s*(?:[\\w-]+:)?text\\b/i.test(svg)) {\n    problems.push({ code: 'wordmark', detail: 'A logo mark has no lettering: draw it with shapes and paths only.' })\n  }\n  if (!problems.length) {\n    const sanitized = sanitizeSvg(svg)\n    if (sanitized.changed) {\n      problems.push({\n        code: 'unsafe',\n        detail: `Remove what an SVG served as an image may not carry: ${sanitized.removed.join(', ')}.`,\n      })\n    }\n  }\n  return problems.length ? { svg: null, problems } : { svg, problems }\n}\n\n/** A color a person may name: `#rgb` or `#rrggbb`. */\nexport function isAiSvgColor(value: unknown): value is string {\n  return typeof value === 'string' && /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim())\n}\n\n/**\n * The colors a site's theme names, in the order a picture reaches for them:\n * the primary and secondary colors first, then the backgrounds and text.\n */\nexport function aiSvgThemePalette(colors: Readonly<Record<string, string>> | null | undefined): string[] {\n  if (!colors) return []\n  const order = [\n    'primary.main',\n    'secondary.main',\n    'background.default',\n    'background.paper',\n    'text.primary',\n    'primary.light',\n    'primary.dark',\n    'secondary.light',\n    'secondary.dark',\n  ]\n  const keys = [...order.filter((key) => key in colors), ...Object.keys(colors).filter((key) => !order.includes(key))]\n  const palette: string[] = []\n  for (const key of keys) {\n    const value = String(colors[key] ?? '').trim().toLowerCase()\n    if (isAiSvgColor(value) && !palette.includes(value)) palette.push(value)\n    if (palette.length >= 6) break\n  }\n  return palette\n}\n"],"names":["sanitizeSvg","AI_SVG_MAX_BYTES","AI_SVG_VIEWBOX","RATIO_TOLERANCE","SVG_NAMESPACE","FORBIDDEN_ELEMENTS","viewBoxRatio","value","parts","trim","split","map","Number","length","some","part","isFinite","width","height","tagsBalance","svg","stripped","replace","stack","closedRoot","match","matchAll","closing","name","selfClosing","pop","push","checkAiSvgMarkup","markup","aspectRatio","style","problems","String","code","detail","bytes","TextEncoder","encode","Math","round","root","exec","test","attributes","RegExp","viewBox","expected","ratio","abs","pattern","startsWith","sanitized","changed","removed","join","isAiSvgColor","aiSvgThemePalette","colors","order","keys","filter","key","Object","includes","palette","toLowerCase"],"mappings":"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"}

package/src/lib/model/ai-usage-by-user.d.ts

@@ -44,11 +44,12 @@ export declare const AI_USAGE_BY_USER_RETENTION_MONTHS = 13;
  * What an AI request was FOR, as the per-user rollup buckets it.
  *
  * `assist` is a console chat turn; `element`, `blog` and `section` are the
- * besigner's three assist modes; the rest are generation job kinds, named
+ * besigner's three assist modes; `image` is a picture made in the Media
+ * library (AGL-3602); the rest are generation job kinds, named
  * exactly as the job document names them so a reader can join the two — or
  * a purpose another plugin named on the text-generation seam.
  */
-export type AiUsageKind = 'assist' | 'element' | 'blog' | 'section' | AiJobKind | PluginAiUsageKind;
+export type AiUsageKind = 'assist' | 'element' | 'blog' | 'section' | 'image' | AiJobKind | PluginAiUsageKind;
 /**
  * A purpose another plugin named on the core's text-generation seam
  * (AGL-3324): the plugin's id and a word, hyphenated — `outreach-curate` —

package/src/lib/model/ai-usage-by-user.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-usage-by-user.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 { AiJobKind } from './ai-jobs.types'\nimport { assistCreditsFromUsd } from '../usage/assist-credits'\n\n/**\n * PER-USER AI USAGE (AGL-2928): the pure half.\n *\n * The org rollup at `assistUsage/{month}` says what a workspace spent on AI\n * and nothing about who spent it. This module is the shape and the arithmetic\n * of the second rollup — one document per person per month, under the org,\n * keyed by uid — so an agency or a multi-brand workspace can see which of its\n * people, on which site, is generating what. No prose, no PII beyond the uid\n * the document is keyed by.\n *\n * The write lives in the plugin's `usage/ai-usage-by-user.ts`, inside the\n * same batch as the org rollup. Everything here is dependency-free so the\n * plugin's tables and the doors that serve them read one definition of a\n * share, a month key and a retention window.\n */\n\n/** `orgs/{orgId}/{this}/{uid}/{months}/{YYYY-MM}` — the subcollection names. */\nexport const AI_USAGE_BY_USER_COLLECTION = 'aiUsageByUser'\nexport const AI_USAGE_BY_USER_MONTHS_COLLECTION = 'months'\n\n/**\n * How many months a person's usage is kept, counted from the month it\n * describes. Thirteen: a full year of month-over-month comparison for a\n * workspace admin, plus the month in progress. A TTL policy on the month\n * document's `expiresAt` enforces it — see `aiUsageByUserExpiry`.\n */\nexport const AI_USAGE_BY_USER_RETENTION_MONTHS = 13\n\n/**\n * What an AI request was FOR, as the per-user rollup buckets it.\n *\n * `assist` is a console chat turn; `element`, `blog` and `section` are the\n * besigner's three assist modes; the rest are generation job kinds, named\n * exactly as the job document names them so a reader can join the two — or\n * a purpose another plugin named on the text-generation seam.\n */\nexport type AiUsageKind =\n  | 'assist'\n  | 'element'\n  | 'blog'\n  | 'section'\n  | AiJobKind\n  | PluginAiUsageKind\n\n/**\n * A purpose another plugin named on the core's text-generation seam\n * (AGL-3324): the plugin's id and a word, hyphenated — `outreach-curate` —\n * so its spend sits in the same `byKind` map as a job kind and a reader can\n * tell whose it was.\n */\nexport type PluginAiUsageKind = `${string}-${string}`\n\n/** One person's month, zero-filled — the shape every reader hands on. */\nexport interface AiUsageByUserMonth {\n  uid: string\n  month: string\n  /** Credits drawn, each request rounded up as the meter rounds. */\n  credits: number\n  /**\n   * The measured provider spend behind `credits`. Server-side only: no\n   * customer surface renders it, and `aiUsageShare` is how it becomes a\n   * figure a customer may see.\n   */\n  estCostUsd: number\n  requests: number\n  refusals: number\n  /** Credits by `AiUsageKind`. */\n  byKind: Record<string, number>\n  /** Credits by host id, for requests that named a site. */\n  byHost: Record<string, number>\n}\n\nconst MONTH_KEY = /^\\d{4}-(0[1-9]|1[0-2])$/\n\n/** Whether `value` is a `YYYY-MM` month key. */\nexport function isAiUsageMonthKey(value: unknown): value is string {\n  return typeof value === 'string' && MONTH_KEY.test(value)\n}\n\n/**\n * The month keys a reader may ask for, newest first: the month in progress\n * and the twelve before it — the retention window, so a picker built from\n * this list never names a month the TTL has reaped.\n */\nexport function aiUsageMonthKeys(\n  now: Date = new Date(),\n  count: number = AI_USAGE_BY_USER_RETENTION_MONTHS,\n): string[] {\n  const keys: string[] = []\n  for (let back = 0; back < count; back += 1) {\n    keys.push(\n      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - back, 1))\n        .toISOString()\n        .slice(0, 7),\n    )\n  }\n  return keys\n}\n\n/** Whether `month` is inside the window `aiUsageMonthKeys` describes. */\nexport function aiUsageMonthWithinRetention(\n  month: string,\n  now: Date = new Date(),\n): boolean {\n  return isAiUsageMonthKey(month) && aiUsageMonthKeys(now).includes(month)\n}\n\n/**\n * When a month document expires: the first instant of the month that is\n * `AI_USAGE_BY_USER_RETENTION_MONTHS` after the one it describes has closed.\n *\n * A `Date`, not a number: the TTL policy keys on a Firestore Timestamp and\n * silently governs nothing when the field is a number. Deterministic per\n * month, so every increment into the document re-stamps the same value and\n * the policy never moves under a month that is still being written.\n */\nexport function aiUsageByUserExpiry(month: string): Date {\n  if (!isAiUsageMonthKey(month)) {\n    throw new Error(`not a month key: ${month}`)\n  }\n  const [year, monthOfYear] = month.split('-').map(Number)\n  return new Date(\n    Date.UTC(year, monthOfYear + AI_USAGE_BY_USER_RETENTION_MONTHS, 1),\n  )\n}\n\n/**\n * The kind an assist request was, read off the route it arrived on — for the\n * meters that carry a route and no kind of their own. The three besigner\n * modes name themselves in the path; everything else is a chat turn.\n */\nexport function aiUsageKindFromRoute(route: string | null | undefined): AiUsageKind {\n  const tail = String(route ?? '').split('/').filter(Boolean).pop() ?? ''\n  if (tail === 'element' || tail === 'blog' || tail === 'section') return tail\n  return 'assist'\n}\n\n/**\n * One person's share of the workspace's spend for the month, in `[0, 1]`.\n *\n * Measured on the dollar figures, never on credits: the org meter rounds the\n * month's spend up ONCE, while a person's credits round each request up, so\n * a roster's credits can sum to a little more than the pool they drew from.\n * The ratio of measured spends has no such drift. Clamped, because a month\n * document written a moment after the org rollup is still a fraction, not a\n * percentage over one hundred — and rounded to a basis point, which is finer\n * than any surface renders and coarser than floating-point noise.\n */\nexport function aiUsageShare(\n  userEstCostUsd: number,\n  orgEstCostUsd: number,\n): number {\n  const user = Number(userEstCostUsd)\n  const org = Number(orgEstCostUsd)\n  if (!Number.isFinite(user) || user <= 0) return 0\n  if (!Number.isFinite(org) || org <= 0) return 0\n  return Math.min(1, Math.round((user / org) * 10_000) / 10_000)\n}\n\nconst finite = (value: unknown): number => {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\nconst creditMap = (raw: unknown): Record<string, number> => {\n  const out: Record<string, number> = {}\n  for (const [key, value] of Object.entries(\n    (raw ?? {}) as Record<string, unknown>,\n  )) {\n    const credits = Math.floor(finite(value))\n    if (credits > 0) out[key] = credits\n  }\n  return out\n}\n\n/**\n * A month document as a complete record. Absent and malformed fields read as\n * zero; a `credits` the writer never set is derived from the spend, so a\n * document written before the field existed still ranks.\n */\nexport function aiUsageByUserMonthFrom(\n  raw: Record<string, unknown> | null | undefined,\n  uid: string,\n  month: string,\n): AiUsageByUserMonth {\n  const estCostUsd = finite(raw?.['estCostUsd'])\n  const stored = Math.floor(finite(raw?.['credits']))\n  return {\n    uid,\n    month,\n    credits: stored > 0 ? stored : assistCreditsFromUsd(estCostUsd),\n    estCostUsd,\n    requests: Math.floor(finite(raw?.['requests'])),\n    refusals: Math.floor(finite(raw?.['refusals'])),\n    byKind: creditMap(raw?.['byKind']),\n    byHost: creditMap(raw?.['byHost']),\n  }\n}\n\n/** The kinds a person drew the most credits on, dearest first. */\nexport function topAiUsageKinds(\n  byKind: Record<string, number>,\n  limit = 3,\n): Array<{ kind: string; credits: number }> {\n  return Object.entries(byKind)\n    .map(([kind, credits]) => ({ kind, credits }))\n    .sort((a, b) => b.credits - a.credits || a.kind.localeCompare(b.kind))\n    .slice(0, limit)\n}\n\n/** Two month documents for one person, summed — the roster column's figure. */\nexport function sumAiUsageCredits(months: readonly AiUsageByUserMonth[]): number {\n  return months.reduce((sum, entry) => sum + entry.credits, 0)\n}\n"],"names":["assistCreditsFromUsd","AI_USAGE_BY_USER_COLLECTION","AI_USAGE_BY_USER_MONTHS_COLLECTION","AI_USAGE_BY_USER_RETENTION_MONTHS","MONTH_KEY","isAiUsageMonthKey","value","test","aiUsageMonthKeys","now","Date","count","keys","back","push","UTC","getUTCFullYear","getUTCMonth","toISOString","slice","aiUsageMonthWithinRetention","month","includes","aiUsageByUserExpiry","Error","year","monthOfYear","split","map","Number","aiUsageKindFromRoute","route","String","tail","filter","Boolean","pop","aiUsageShare","userEstCostUsd","orgEstCostUsd","user","org","isFinite","Math","min","round","finite","parsed","creditMap","raw","out","key","Object","entries","credits","floor","aiUsageByUserMonthFrom","uid","estCostUsd","stored","requests","refusals","byKind","byHost","topAiUsageKinds","limit","kind","sort","a","b","localeCompare","sumAiUsageCredits","months","reduce","sum","entry"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-usage-by-user.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 { AiJobKind } from './ai-jobs.types'\nimport { assistCreditsFromUsd } from '../usage/assist-credits'\n\n/**\n * PER-USER AI USAGE (AGL-2928): the pure half.\n *\n * The org rollup at `assistUsage/{month}` says what a workspace spent on AI\n * and nothing about who spent it. This module is the shape and the arithmetic\n * of the second rollup — one document per person per month, under the org,\n * keyed by uid — so an agency or a multi-brand workspace can see which of its\n * people, on which site, is generating what. No prose, no PII beyond the uid\n * the document is keyed by.\n *\n * The write lives in the plugin's `usage/ai-usage-by-user.ts`, inside the\n * same batch as the org rollup. Everything here is dependency-free so the\n * plugin's tables and the doors that serve them read one definition of a\n * share, a month key and a retention window.\n */\n\n/** `orgs/{orgId}/{this}/{uid}/{months}/{YYYY-MM}` — the subcollection names. */\nexport const AI_USAGE_BY_USER_COLLECTION = 'aiUsageByUser'\nexport const AI_USAGE_BY_USER_MONTHS_COLLECTION = 'months'\n\n/**\n * How many months a person's usage is kept, counted from the month it\n * describes. Thirteen: a full year of month-over-month comparison for a\n * workspace admin, plus the month in progress. A TTL policy on the month\n * document's `expiresAt` enforces it — see `aiUsageByUserExpiry`.\n */\nexport const AI_USAGE_BY_USER_RETENTION_MONTHS = 13\n\n/**\n * What an AI request was FOR, as the per-user rollup buckets it.\n *\n * `assist` is a console chat turn; `element`, `blog` and `section` are the\n * besigner's three assist modes; `image` is a picture made in the Media\n * library (AGL-3602); the rest are generation job kinds, named\n * exactly as the job document names them so a reader can join the two — or\n * a purpose another plugin named on the text-generation seam.\n */\nexport type AiUsageKind =\n  | 'assist'\n  | 'element'\n  | 'blog'\n  | 'section'\n  | 'image'\n  | AiJobKind\n  | PluginAiUsageKind\n\n/**\n * A purpose another plugin named on the core's text-generation seam\n * (AGL-3324): the plugin's id and a word, hyphenated — `outreach-curate` —\n * so its spend sits in the same `byKind` map as a job kind and a reader can\n * tell whose it was.\n */\nexport type PluginAiUsageKind = `${string}-${string}`\n\n/** One person's month, zero-filled — the shape every reader hands on. */\nexport interface AiUsageByUserMonth {\n  uid: string\n  month: string\n  /** Credits drawn, each request rounded up as the meter rounds. */\n  credits: number\n  /**\n   * The measured provider spend behind `credits`. Server-side only: no\n   * customer surface renders it, and `aiUsageShare` is how it becomes a\n   * figure a customer may see.\n   */\n  estCostUsd: number\n  requests: number\n  refusals: number\n  /** Credits by `AiUsageKind`. */\n  byKind: Record<string, number>\n  /** Credits by host id, for requests that named a site. */\n  byHost: Record<string, number>\n}\n\nconst MONTH_KEY = /^\\d{4}-(0[1-9]|1[0-2])$/\n\n/** Whether `value` is a `YYYY-MM` month key. */\nexport function isAiUsageMonthKey(value: unknown): value is string {\n  return typeof value === 'string' && MONTH_KEY.test(value)\n}\n\n/**\n * The month keys a reader may ask for, newest first: the month in progress\n * and the twelve before it — the retention window, so a picker built from\n * this list never names a month the TTL has reaped.\n */\nexport function aiUsageMonthKeys(\n  now: Date = new Date(),\n  count: number = AI_USAGE_BY_USER_RETENTION_MONTHS,\n): string[] {\n  const keys: string[] = []\n  for (let back = 0; back < count; back += 1) {\n    keys.push(\n      new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - back, 1))\n        .toISOString()\n        .slice(0, 7),\n    )\n  }\n  return keys\n}\n\n/** Whether `month` is inside the window `aiUsageMonthKeys` describes. */\nexport function aiUsageMonthWithinRetention(\n  month: string,\n  now: Date = new Date(),\n): boolean {\n  return isAiUsageMonthKey(month) && aiUsageMonthKeys(now).includes(month)\n}\n\n/**\n * When a month document expires: the first instant of the month that is\n * `AI_USAGE_BY_USER_RETENTION_MONTHS` after the one it describes has closed.\n *\n * A `Date`, not a number: the TTL policy keys on a Firestore Timestamp and\n * silently governs nothing when the field is a number. Deterministic per\n * month, so every increment into the document re-stamps the same value and\n * the policy never moves under a month that is still being written.\n */\nexport function aiUsageByUserExpiry(month: string): Date {\n  if (!isAiUsageMonthKey(month)) {\n    throw new Error(`not a month key: ${month}`)\n  }\n  const [year, monthOfYear] = month.split('-').map(Number)\n  return new Date(\n    Date.UTC(year, monthOfYear + AI_USAGE_BY_USER_RETENTION_MONTHS, 1),\n  )\n}\n\n/**\n * The kind an assist request was, read off the route it arrived on — for the\n * meters that carry a route and no kind of their own. The three besigner\n * modes name themselves in the path; everything else is a chat turn.\n */\nexport function aiUsageKindFromRoute(route: string | null | undefined): AiUsageKind {\n  const tail = String(route ?? '').split('/').filter(Boolean).pop() ?? ''\n  if (tail === 'element' || tail === 'blog' || tail === 'section') return tail\n  return 'assist'\n}\n\n/**\n * One person's share of the workspace's spend for the month, in `[0, 1]`.\n *\n * Measured on the dollar figures, never on credits: the org meter rounds the\n * month's spend up ONCE, while a person's credits round each request up, so\n * a roster's credits can sum to a little more than the pool they drew from.\n * The ratio of measured spends has no such drift. Clamped, because a month\n * document written a moment after the org rollup is still a fraction, not a\n * percentage over one hundred — and rounded to a basis point, which is finer\n * than any surface renders and coarser than floating-point noise.\n */\nexport function aiUsageShare(\n  userEstCostUsd: number,\n  orgEstCostUsd: number,\n): number {\n  const user = Number(userEstCostUsd)\n  const org = Number(orgEstCostUsd)\n  if (!Number.isFinite(user) || user <= 0) return 0\n  if (!Number.isFinite(org) || org <= 0) return 0\n  return Math.min(1, Math.round((user / org) * 10_000) / 10_000)\n}\n\nconst finite = (value: unknown): number => {\n  const parsed = Number(value ?? 0)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\nconst creditMap = (raw: unknown): Record<string, number> => {\n  const out: Record<string, number> = {}\n  for (const [key, value] of Object.entries(\n    (raw ?? {}) as Record<string, unknown>,\n  )) {\n    const credits = Math.floor(finite(value))\n    if (credits > 0) out[key] = credits\n  }\n  return out\n}\n\n/**\n * A month document as a complete record. Absent and malformed fields read as\n * zero; a `credits` the writer never set is derived from the spend, so a\n * document written before the field existed still ranks.\n */\nexport function aiUsageByUserMonthFrom(\n  raw: Record<string, unknown> | null | undefined,\n  uid: string,\n  month: string,\n): AiUsageByUserMonth {\n  const estCostUsd = finite(raw?.['estCostUsd'])\n  const stored = Math.floor(finite(raw?.['credits']))\n  return {\n    uid,\n    month,\n    credits: stored > 0 ? stored : assistCreditsFromUsd(estCostUsd),\n    estCostUsd,\n    requests: Math.floor(finite(raw?.['requests'])),\n    refusals: Math.floor(finite(raw?.['refusals'])),\n    byKind: creditMap(raw?.['byKind']),\n    byHost: creditMap(raw?.['byHost']),\n  }\n}\n\n/** The kinds a person drew the most credits on, dearest first. */\nexport function topAiUsageKinds(\n  byKind: Record<string, number>,\n  limit = 3,\n): Array<{ kind: string; credits: number }> {\n  return Object.entries(byKind)\n    .map(([kind, credits]) => ({ kind, credits }))\n    .sort((a, b) => b.credits - a.credits || a.kind.localeCompare(b.kind))\n    .slice(0, limit)\n}\n\n/** Two month documents for one person, summed — the roster column's figure. */\nexport function sumAiUsageCredits(months: readonly AiUsageByUserMonth[]): number {\n  return months.reduce((sum, entry) => sum + entry.credits, 0)\n}\n"],"names":["assistCreditsFromUsd","AI_USAGE_BY_USER_COLLECTION","AI_USAGE_BY_USER_MONTHS_COLLECTION","AI_USAGE_BY_USER_RETENTION_MONTHS","MONTH_KEY","isAiUsageMonthKey","value","test","aiUsageMonthKeys","now","Date","count","keys","back","push","UTC","getUTCFullYear","getUTCMonth","toISOString","slice","aiUsageMonthWithinRetention","month","includes","aiUsageByUserExpiry","Error","year","monthOfYear","split","map","Number","aiUsageKindFromRoute","route","String","tail","filter","Boolean","pop","aiUsageShare","userEstCostUsd","orgEstCostUsd","user","org","isFinite","Math","min","round","finite","parsed","creditMap","raw","out","key","Object","entries","credits","floor","aiUsageByUserMonthFrom","uid","estCostUsd","stored","requests","refusals","byKind","byHost","topAiUsageKinds","limit","kind","sort","a","b","localeCompare","sumAiUsageCredits","months","reduce","sum","entry"],"mappings":"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"}

package/src/lib/model/ai-workflow-job.d.ts

@@ -20,7 +20,7 @@ import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-bi
  * 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:
+ * One kind, four modes, because the four 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.
  *
@@ -32,17 +32,44 @@ import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-bi
  *    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.
+ *  - `revise` reads a saved ACTION and a change asked of it — "fix it", or
+ *    "also tag them" — and writes the action as it would be after the change
+ *    as a NEW draft, OFF, through the same draft writer and vocabulary as
+ *    `draft`. The saved action is never written: the person compares the two,
+ *    switches the new one on and the old one off. An action that holds what
+ *    the vocabulary cannot write (an on-page step, a page event, a filter
+ *    expression) is refused rather than revised without it.
  *
- * Nothing in any mode switches an automation on, runs one, or changes one.
+ * `draft` has a second scope (AGL-3603): `scope: 'org'` drafts one of the
+ * WORKSPACE's automations — the ones the workflows plugin's Org automations
+ * section places on several sites — with no site named. Its vocabulary is
+ * the narrower one that section's zone hands the widget (`triggers` and
+ * `steps`, each a comma-separated list, intersected here with the drafting
+ * vocabulary below), its records are the workspace's, and nothing is written:
+ * the automation rides on an `orgAutomation` output as a proposal that the
+ * section's editor opens unsaved, switched off, where the person picks its
+ * sites and saves it through that section's own route.
+ *
+ * Nothing in any mode switches an automation on, runs one, or changes a saved
+ * one.
  */
-export declare const AI_WORKFLOW_JOB_MODES: readonly ["draft", "explain", "diagnose"];
+export declare const AI_WORKFLOW_JOB_MODES: readonly ["draft", "explain", "diagnose", "revise"];
 export type AiWorkflowJobMode = (typeof AI_WORKFLOW_JOB_MODES)[number];
 /** What an explained automation is: an action, or a workflow of function calls. */
 export declare const AI_WORKFLOW_TARGET_TYPES: readonly ["action", "workflow"];
 export type AiWorkflowTargetType = (typeof AI_WORKFLOW_TARGET_TYPES)[number];
+/** What an org automation may start on and do, as the zone that asks for one says. */
+export interface AiOrgAutomationVocabulary {
+    triggers: HostEventType[];
+    steps: AiAutomationStepType[];
+}
 export type AiWorkflowJobInputs = {
     mode: 'draft';
-} | {
+    scope?: 'site';
+} | ({
+    mode: 'draft';
+    scope: 'org';
+} & AiOrgAutomationVocabulary) | {
     mode: 'explain';
     targetType: AiWorkflowTargetType;
     targetId: string;
@@ -51,9 +78,25 @@ export type AiWorkflowJobInputs = {
     targetType: AiWorkflowTargetType;
     targetId: string;
     runId: string;
+} | {
+    mode: 'revise';
+    targetType: 'action';
+    targetId: string;
 };
 /** A job's inputs read into its mode, or the sentence that says what is wrong with them. */
 export declare function parseAiWorkflowJobInputs(inputs: Readonly<Record<string, unknown>> | null | undefined): AiWorkflowJobInputs | string;
+/**
+ * An org automation's vocabulary from a job's inputs: the triggers and steps
+ * the zone named that the drafting vocabulary also has, or `null` when that
+ * leaves no trigger or no step. The zone can only narrow what is drafted;
+ * the section's save route holds what is saved to its own rules.
+ */
+export declare function readAiOrgAutomationVocabulary(inputs: Readonly<Record<string, unknown>> | null | undefined): AiOrgAutomationVocabulary | null;
+/** An org automation's vocabulary as a job's inputs carry it. */
+export declare function aiOrgAutomationInputs(vocabulary: {
+    triggers: readonly string[];
+    steps: readonly string[];
+}): Record<string, string>;
 /** A part of the platform some triggers and steps need beyond the actions builder itself. */
 export type AiAutomationNeed = 'crm' | 'webhooks' | 'bookings';
 export type AiAutomationCapabilities = Readonly<Record<AiAutomationNeed, boolean>>;
@@ -107,3 +150,48 @@ export declare const AI_WORKFLOW_RUN_NOT_FAILED_COPY = "That run did not fail, s
 export declare 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 declare const AI_WORKFLOW_NO_EXPLANATION_COPY = "The AI could not explain this automation. Try again.";
 export declare const AI_WORKFLOW_SAVE_FAILURE_COPY = "The automation was drafted but could not be saved. Try the job again.";
+export declare const AI_ORG_AUTOMATION_NO_VOCABULARY_COPY = "Open Org automations to draft one: the page says what an org automation can start on and do.";
+export declare const AI_ORG_AUTOMATION_UNAVAILABLE_COPY = "Turn on Automation for this workspace before drafting an org automation.";
+export declare const AI_ORG_AUTOMATION_PLAN_COPY = "Org automations are built from the actions builder, which this workspace\u2019s plan does not include. Upgrade in Billing to build them.";
+/**
+ * The output resource an org automation's proposal rides on (AGL-3603): never
+ * a document — the Org automations editor opens it unsaved.
+ */
+export declare const AI_ORG_AUTOMATION_RESOURCE = "orgAutomation";
+/** The automation an `orgAutomation` output proposes, as the editor opens it. */
+export interface AiOrgAutomationProposal {
+    name: string;
+    trigger: {
+        event: string;
+        conditions?: Array<{
+            field: string;
+            op: string;
+            value?: string;
+        }>;
+        combinator?: 'and' | 'or';
+    };
+    steps: Array<Record<string, unknown> & {
+        type: string;
+    }>;
+}
+/** An output's proposal read back, or `null` for one that is not an org automation. */
+export declare function readAiOrgAutomationProposal(value: unknown): AiOrgAutomationProposal | null;
+export declare const AI_WORKFLOW_REVISE_WORKFLOW_COPY = "Only an action can be changed with AI. A workflow can be explained, and edited in its own editor.";
+/** Why a saved action cannot be revised, each with the sentence a person reads. */
+export declare const AI_WORKFLOW_REVISE_BLOCKERS: readonly ["page-event", "page-step", "filter"];
+export type AiWorkflowReviseBlocker = (typeof AI_WORKFLOW_REVISE_BLOCKERS)[number];
+export declare const AI_WORKFLOW_REVISE_BLOCKER_COPY: Readonly<Record<AiWorkflowReviseBlocker, string>>;
+/**
+ * Why a saved action cannot be revised, or `null` when every part of it is
+ * one the drafting vocabulary writes — so the revised draft can hold the
+ * whole action and lose nothing the person did not ask to change.
+ */
+export declare function aiActionReviseBlocker(action: {
+    trigger?: {
+        event?: unknown;
+        filter?: unknown;
+    } | null;
+    steps?: ReadonlyArray<{
+        type?: unknown;
+    } | null | undefined> | null;
+}): AiWorkflowReviseBlocker | null;