@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/server/ai-assist-prompts.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @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 AiSystemBlock, type AiTool } from '../runtime/ai-runtime';
+import type { AiResult } from '../providers/contract';
+/**
+ * The copy assistant's prompts and its section tool (AGL-2937), by their own
+ * module so a spec can read them without a Firestore, an ID token or a
+ * provider — the handler beside them needs all three.
+ *
+ * ── Why the section mode answers through a tool ───────────────────────────
+ *
+ * It asked for "ONLY a JSON object, no prose or code fences" and then parsed
+ * whatever came back, stripping a fence if it found one. When that parse
+ * failed the handler answered 502 and the tokens were already spent: the
+ * whole request, prompt and answer, bought nothing, and the member's next
+ * move is to press the button again and spend it twice. A strict tool is the
+ * cheaper shape for exactly that reason — the answer arrives as validated
+ * arguments rather than as text that has to be guessed at — and it is what
+ * AGL-2937 asks of every door.
+ *
+ * The parse stays as a fallback. A provider whose adapter has no tool
+ * support, or a model that answers in prose anyway, still gets read rather
+ * than refused: the tool is how the answer is asked for, not the only way it
+ * can arrive.
+ *
+ * ── Why the flat node list ────────────────────────────────────────────────
+ *
+ * A strict schema forbids additional properties, so a map keyed by node id
+ * cannot be described in one: every key would have to be a declared
+ * property. The tool therefore takes a LIST of nodes, each naming its own id
+ * and its children by id, and `readAssistSection` rebuilds the map the
+ * besigner consumer already reads. The same reason `assistEditTool` takes
+ * name/value pairs rather than a props object.
+ *
+ * ── Caching ───────────────────────────────────────────────────────────────
+ *
+ * Each mode's static text carries a breakpoint. None of the three is long
+ * enough for its model to cache today — `runtime/ai-prompt-cache.spec.ts`
+ * measures all three against their minimums and records the verdict — so the
+ * marker is a statement about the block rather than a saving. It costs
+ * nothing, it is correct if a mode is ever served by a model with a lower
+ * minimum, and the ledger is what says whether it pays.
+ */
+export type AiAssistMode = 'element' | 'blog' | 'section';
+/**
+ * One mode's system blocks: the acceptable-use rules ahead of the mode's own
+ * prompt (AGL-2925), as one cached block with no per-org byte in it.
+ */
+export declare function assistModeSystemBlocks(mode: AiAssistMode): AiSystemBlock[];
+export declare const ASSIST_SECTION_TOOL_NAME = "submit_section";
+/**
+ * The strict tool a generated section arrives through. `componentId` is an
+ * enum of the marketplace allowlist — the same list the sanitizer holds the
+ * answer to afterward — so an unpublishable component is refused by the
+ * schema before it costs a re-ask.
+ */
+export declare function assistSectionTool(): AiTool;
+/** The sanitized section, in the shape the besigner consumer already reads. */
+export interface AssistSection {
+    rootId: string;
+    nodes: Record<string, unknown>;
+}
+/**
+ * What reading a section answer came to. Discriminated by a string rather
+ * than a boolean, like every other result in the plugin: this tree compiles
+ * without `strictNullChecks`, where a `true`/`false` discriminant does not
+ * narrow.
+ */
+export type AssistSectionRead = {
+    status: 'ok';
+    section: AssistSection;
+}
+/** Neither a tool call nor JSON: nothing could be read out of the answer. */
+ | {
+    status: 'unreadable';
+    error: string;
+}
+/** Read, and refused by the sanitizer every marketplace install passes. */
+ | {
+    status: 'rejected';
+    error: string;
+};
+/**
+ * Read a section answer: the tool call first, the text parse behind it, then
+ * the marketplace sanitizer every generated subtree has always passed before
+ * it reaches a canvas.
+ */
+export declare function readAssistSection(result: AiResult): AssistSectionRead;

package/src/lib/server/ai-assist-prompts.js

@@ -0,0 +1,207 @@
+/**
+ * @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 { MARKETPLACE_COMPONENT_ID_ALLOWLIST, sanitizeMarketplaceDefinition } from "@aglyn/aglyn/app-utils/node-definition-sanitizer";
+import { AI_PALETTE } from "../runtime/ai-palette.generated.js";
+import { AI_ACCEPTABLE_USE_BLOCK } from "../runtime/ai-runtime.js";
+/** The mode prompts. Static text: no byte of any workspace is in one. */ const MODE_PROMPT = {
+    element: 'You write website copy inside a site builder. Reply with ONLY the final text for the element — no quotes, preamble, or markdown. Keep roughly the same length and role as the current text unless the instruction says otherwise.',
+    blog: 'You write blog posts inside a site builder. Reply with ONLY the post body in markdown-lite: **bold**, *italic*, ## headings, - lists, [links](https://url). No front matter, title line, or preamble — the title renders separately.',
+    section: 'You design one website section inside a site builder. Answer by calling ' + `${'submit_section'} exactly once, with a flat list of nodes: each node ` + 'names its own id, the component it is, its parent (empty for the root) ' + 'and its children by id, and fills props as name/value pairs. Useful ' + 'props — muiStack: direction (row|column), spacing, justifyContent, ' + 'alignItems; muiTypography: children, variant (h1..h6, body1, ' + 'subtitle1); muiButton: children, variant (contained|outlined), color; ' + 'image: src, alt; muiContainer: maxWidth (sm|md|lg). Keep it small: 4-12 ' + 'nodes, one root container. Leave image src empty. Write real copy, not ' + 'lorem ipsum.'
+};
+/**
+ * One mode's system blocks: the acceptable-use rules ahead of the mode's own
+ * prompt (AGL-2925), as one cached block with no per-org byte in it.
+ */ export function assistModeSystemBlocks(mode) {
+    return [
+        {
+            text: `${AI_ACCEPTABLE_USE_BLOCK}\n\n${MODE_PROMPT[mode]}`,
+            cacheBreakpoint: true
+        }
+    ];
+}
+export const ASSIST_SECTION_TOOL_NAME = 'submit_section';
+const STRING = {
+    type: 'string'
+};
+const strictObject = (properties)=>({
+        type: 'object',
+        properties,
+        required: Object.keys(properties),
+        additionalProperties: false
+    });
+/**
+ * The strict tool a generated section arrives through. `componentId` is an
+ * enum of the marketplace allowlist — the same list the sanitizer holds the
+ * answer to afterward — so an unpublishable component is refused by the
+ * schema before it costs a re-ask.
+ */ export function assistSectionTool() {
+    const pair = strictObject({
+        name: STRING,
+        value: STRING
+    });
+    const node = strictObject({
+        id: STRING,
+        componentId: {
+            type: 'string',
+            enum: [
+                ...MARKETPLACE_COMPONENT_ID_ALLOWLIST
+            ]
+        },
+        parentId: STRING,
+        children: {
+            type: 'array',
+            items: STRING
+        },
+        props: {
+            type: 'array',
+            items: pair
+        }
+    });
+    return {
+        name: ASSIST_SECTION_TOOL_NAME,
+        description: 'Submit the section you designed, as a flat list of nodes. The first ' + 'node with an empty parentId is the root. The member reviews the ' + 'section and places it, or discards it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                nodes: {
+                    type: 'array',
+                    items: node
+                }
+            },
+            required: [
+                'nodes'
+            ],
+            additionalProperties: false
+        },
+        strict: true
+    };
+}
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * A pair's value in the type the component's own schema declares for that
+ * prop, since a strict tool can only carry strings. `children` stays text
+ * whatever a schema says: a number in it is copy a visitor reads, not a
+ * count.
+ */ function propValue(componentId, name, value) {
+    var _AI_PALETTE_componentId_propsSchema_properties, _AI_PALETTE_componentId_propsSchema, _AI_PALETTE_componentId;
+    if (name === 'children') return value;
+    const declared = (_AI_PALETTE_componentId = AI_PALETTE[componentId]) == null ? void 0 : (_AI_PALETTE_componentId_propsSchema = _AI_PALETTE_componentId.propsSchema) == null ? void 0 : (_AI_PALETTE_componentId_propsSchema_properties = _AI_PALETTE_componentId_propsSchema.properties) == null ? void 0 : _AI_PALETTE_componentId_propsSchema_properties[name];
+    const type = declared == null ? void 0 : declared.type;
+    if (type === 'boolean') return value === 'true';
+    if (type === 'number' || type === 'integer') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : value;
+    }
+    if (type) return value;
+    // No schema for this prop: a bare number is read as one, so `spacing: "2"`
+    // does not reach the canvas as text. The palette's own typing wins above,
+    // which is why muiStack's string-typed `spacing` stays a string.
+    const parsed = Number(value);
+    return value.trim() !== '' && Number.isFinite(parsed) ? parsed : value;
+}
+/** The flat node list as the stored map: `{ $id, componentId, parentId, props, nodes }`. */ function definitionFromNodes(nodes) {
+    var _ref;
+    const ids = new Set(nodes.map((node)=>node.id));
+    const root = nodes.find((node)=>!node.parentId || !ids.has(node.parentId));
+    const map = {};
+    for (const node of nodes){
+        const props = {};
+        for (const { name, value } of node.props){
+            if (name) props[name] = propValue(node.componentId, name, value);
+        }
+        map[node.id] = {
+            $id: node.id,
+            componentId: node.componentId,
+            parentId: node === root ? null : node.parentId,
+            props,
+            nodes: node.children.filter((child)=>ids.has(child))
+        };
+    }
+    return {
+        rootId: (_ref = root == null ? void 0 : root.id) != null ? _ref : '',
+        nodes: map
+    };
+}
+/** A tool call's arguments as nodes, or `null` when the shape is not one. */ function nodesFromToolUse(input) {
+    const raw = input['nodes'];
+    if (!Array.isArray(raw) || !raw.length) return null;
+    const nodes = [];
+    for (const entry of raw){
+        var _entry_id, _entry_componentId, _entry_parentId;
+        if (!isRecord(entry)) return null;
+        const id = String((_entry_id = entry['id']) != null ? _entry_id : '');
+        const componentId = String((_entry_componentId = entry['componentId']) != null ? _entry_componentId : '');
+        if (!id || !componentId) return null;
+        const props = Array.isArray(entry['props']) ? entry['props'] : [];
+        nodes.push({
+            id,
+            componentId,
+            parentId: String((_entry_parentId = entry['parentId']) != null ? _entry_parentId : ''),
+            children: (Array.isArray(entry['children']) ? entry['children'] : []).map(String),
+            props: props.filter(isRecord).map((pair)=>{
+                var _pair_name, _pair_value;
+                return {
+                    name: String((_pair_name = pair['name']) != null ? _pair_name : ''),
+                    value: String((_pair_value = pair['value']) != null ? _pair_value : '')
+                };
+            })
+        });
+    }
+    return nodes;
+}
+/** The old shape: a JSON object of `{ rootId, nodes }`, possibly fenced. */ function definitionFromText(text) {
+    var _parsed_rootId;
+    const raw = text.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (unused) {
+        return null;
+    }
+    if (!isRecord(parsed)) return null;
+    return {
+        rootId: String((_parsed_rootId = parsed['rootId']) != null ? _parsed_rootId : ''),
+        nodes: isRecord(parsed['nodes']) ? parsed['nodes'] : {}
+    };
+}
+/**
+ * Read a section answer: the tool call first, the text parse behind it, then
+ * the marketplace sanitizer every generated subtree has always passed before
+ * it reaches a canvas.
+ */ export function readAssistSection(result) {
+    const call = result.kind === 'completion' ? result.toolUse.find((use)=>use.name === ASSIST_SECTION_TOOL_NAME) : undefined;
+    const nodes = call ? nodesFromToolUse(call.input) : null;
+    const definition = nodes ? definitionFromNodes(nodes) : definitionFromText(result.kind === 'completion' ? result.text : '');
+    if (!definition) return {
+        status: 'unreadable',
+        error: 'AI returned invalid JSON'
+    };
+    const sanitized = sanitizeMarketplaceDefinition(definition);
+    // `=== false`, not `!`: see `AssistSectionRead`.
+    if (sanitized.ok === false) return {
+        status: 'rejected',
+        error: sanitized.error
+    };
+    return {
+        status: 'ok',
+        section: {
+            rootId: sanitized.rootId,
+            nodes: sanitized.nodes
+        }
+    };
+}
+
+//# sourceMappingURL=ai-assist-prompts.js.map

package/src/lib/server/ai-assist-prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-assist-prompts.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 {\n  MARKETPLACE_COMPONENT_ID_ALLOWLIST,\n  sanitizeMarketplaceDefinition,\n} from '@aglyn/aglyn/app-utils/node-definition-sanitizer'\nimport { AI_PALETTE } from '../runtime/ai-palette.generated'\nimport { AI_ACCEPTABLE_USE_BLOCK, type AiSystemBlock, type AiTool } from '../runtime/ai-runtime'\nimport type { AiResult } from '../providers/contract'\n\n/**\n * The copy assistant's prompts and its section tool (AGL-2937), by their own\n * module so a spec can read them without a Firestore, an ID token or a\n * provider — the handler beside them needs all three.\n *\n * ── Why the section mode answers through a tool ───────────────────────────\n *\n * It asked for \"ONLY a JSON object, no prose or code fences\" and then parsed\n * whatever came back, stripping a fence if it found one. When that parse\n * failed the handler answered 502 and the tokens were already spent: the\n * whole request, prompt and answer, bought nothing, and the member's next\n * move is to press the button again and spend it twice. A strict tool is the\n * cheaper shape for exactly that reason — the answer arrives as validated\n * arguments rather than as text that has to be guessed at — and it is what\n * AGL-2937 asks of every door.\n *\n * The parse stays as a fallback. A provider whose adapter has no tool\n * support, or a model that answers in prose anyway, still gets read rather\n * than refused: the tool is how the answer is asked for, not the only way it\n * can arrive.\n *\n * ── Why the flat node list ────────────────────────────────────────────────\n *\n * A strict schema forbids additional properties, so a map keyed by node id\n * cannot be described in one: every key would have to be a declared\n * property. The tool therefore takes a LIST of nodes, each naming its own id\n * and its children by id, and `readAssistSection` rebuilds the map the\n * besigner consumer already reads. The same reason `assistEditTool` takes\n * name/value pairs rather than a props object.\n *\n * ── Caching ───────────────────────────────────────────────────────────────\n *\n * Each mode's static text carries a breakpoint. None of the three is long\n * enough for its model to cache today — `runtime/ai-prompt-cache.spec.ts`\n * measures all three against their minimums and records the verdict — so the\n * marker is a statement about the block rather than a saving. It costs\n * nothing, it is correct if a mode is ever served by a model with a lower\n * minimum, and the ledger is what says whether it pays.\n */\n\nexport type AiAssistMode = 'element' | 'blog' | 'section'\n\n/** The mode prompts. Static text: no byte of any workspace is in one. */\nconst MODE_PROMPT: Readonly<Record<AiAssistMode, string>> = {\n  element:\n    'You write website copy inside a site builder. Reply with ONLY the final text for the element — no quotes, preamble, or markdown. Keep roughly the same length and role as the current text unless the instruction says otherwise.',\n  blog:\n    'You write blog posts inside a site builder. Reply with ONLY the post body in markdown-lite: **bold**, *italic*, ## headings, - lists, [links](https://url). No front matter, title line, or preamble — the title renders separately.',\n  section:\n    'You design one website section inside a site builder. Answer by calling ' +\n    `${'submit_section'} exactly once, with a flat list of nodes: each node ` +\n    'names its own id, the component it is, its parent (empty for the root) ' +\n    'and its children by id, and fills props as name/value pairs. Useful ' +\n    'props — muiStack: direction (row|column), spacing, justifyContent, ' +\n    'alignItems; muiTypography: children, variant (h1..h6, body1, ' +\n    'subtitle1); muiButton: children, variant (contained|outlined), color; ' +\n    'image: src, alt; muiContainer: maxWidth (sm|md|lg). Keep it small: 4-12 ' +\n    'nodes, one root container. Leave image src empty. Write real copy, not ' +\n    'lorem ipsum.',\n}\n\n/**\n * One mode's system blocks: the acceptable-use rules ahead of the mode's own\n * prompt (AGL-2925), as one cached block with no per-org byte in it.\n */\nexport function assistModeSystemBlocks(mode: AiAssistMode): AiSystemBlock[] {\n  return [{ text: `${AI_ACCEPTABLE_USE_BLOCK}\\n\\n${MODE_PROMPT[mode]}`, cacheBreakpoint: true }]\n}\n\nexport const ASSIST_SECTION_TOOL_NAME = 'submit_section'\n\nconst STRING = { type: 'string' } as const\n\nconst strictObject = (properties: Record<string, unknown>) => ({\n  type: 'object',\n  properties,\n  required: Object.keys(properties),\n  additionalProperties: false,\n})\n\n/**\n * The strict tool a generated section arrives through. `componentId` is an\n * enum of the marketplace allowlist — the same list the sanitizer holds the\n * answer to afterward — so an unpublishable component is refused by the\n * schema before it costs a re-ask.\n */\nexport function assistSectionTool(): AiTool {\n  const pair = strictObject({ name: STRING, value: STRING })\n  const node = strictObject({\n    id: STRING,\n    componentId: { type: 'string', enum: [...MARKETPLACE_COMPONENT_ID_ALLOWLIST] },\n    parentId: STRING,\n    children: { type: 'array', items: STRING },\n    props: { type: 'array', items: pair },\n  })\n  return {\n    name: ASSIST_SECTION_TOOL_NAME,\n    description:\n      'Submit the section you designed, as a flat list of nodes. The first ' +\n      'node with an empty parentId is the root. The member reviews the ' +\n      'section and places it, or discards it.',\n    inputSchema: {\n      type: 'object',\n      properties: { nodes: { type: 'array', items: node } },\n      required: ['nodes'],\n      additionalProperties: false,\n    },\n    strict: true,\n  }\n}\n\n/** The sanitized section, in the shape the besigner consumer already reads. */\nexport interface AssistSection {\n  rootId: string\n  nodes: Record<string, unknown>\n}\n\ninterface RawNode {\n  id: string\n  componentId: string\n  parentId: string\n  children: string[]\n  props: Array<{ name: string; value: string }>\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * A pair's value in the type the component's own schema declares for that\n * prop, since a strict tool can only carry strings. `children` stays text\n * whatever a schema says: a number in it is copy a visitor reads, not a\n * count.\n */\nfunction propValue(componentId: string, name: string, value: string): unknown {\n  if (name === 'children') return value\n  const declared = AI_PALETTE[componentId]?.propsSchema?.properties?.[name] as\n    | { type?: string }\n    | undefined\n  const type = declared?.type\n  if (type === 'boolean') return value === 'true'\n  if (type === 'number' || type === 'integer') {\n    const parsed = Number(value)\n    return Number.isFinite(parsed) ? parsed : value\n  }\n  if (type) return value\n  // No schema for this prop: a bare number is read as one, so `spacing: \"2\"`\n  // does not reach the canvas as text. The palette's own typing wins above,\n  // which is why muiStack's string-typed `spacing` stays a string.\n  const parsed = Number(value)\n  return value.trim() !== '' && Number.isFinite(parsed) ? parsed : value\n}\n\n/** The flat node list as the stored map: `{ $id, componentId, parentId, props, nodes }`. */\nfunction definitionFromNodes(nodes: readonly RawNode[]): {\n  rootId: string\n  nodes: Record<string, unknown>\n} {\n  const ids = new Set(nodes.map((node) => node.id))\n  const root = nodes.find((node) => !node.parentId || !ids.has(node.parentId))\n  const map: Record<string, unknown> = {}\n  for (const node of nodes) {\n    const props: Record<string, unknown> = {}\n    for (const { name, value } of node.props) {\n      if (name) props[name] = propValue(node.componentId, name, value)\n    }\n    map[node.id] = {\n      $id: node.id,\n      componentId: node.componentId,\n      parentId: node === root ? null : node.parentId,\n      props,\n      nodes: node.children.filter((child) => ids.has(child)),\n    }\n  }\n  return { rootId: root?.id ?? '', nodes: map }\n}\n\n/** A tool call's arguments as nodes, or `null` when the shape is not one. */\nfunction nodesFromToolUse(input: Record<string, unknown>): RawNode[] | null {\n  const raw = input['nodes']\n  if (!Array.isArray(raw) || !raw.length) return null\n  const nodes: RawNode[] = []\n  for (const entry of raw) {\n    if (!isRecord(entry)) return null\n    const id = String(entry['id'] ?? '')\n    const componentId = String(entry['componentId'] ?? '')\n    if (!id || !componentId) return null\n    const props = Array.isArray(entry['props']) ? entry['props'] : []\n    nodes.push({\n      id,\n      componentId,\n      parentId: String(entry['parentId'] ?? ''),\n      children: (Array.isArray(entry['children']) ? entry['children'] : []).map(String),\n      props: props.filter(isRecord).map((pair) => ({\n        name: String(pair['name'] ?? ''),\n        value: String(pair['value'] ?? ''),\n      })),\n    })\n  }\n  return nodes\n}\n\n/** The old shape: a JSON object of `{ rootId, nodes }`, possibly fenced. */\nfunction definitionFromText(text: string): { rootId: string; nodes: Record<string, unknown> } | null {\n  const raw = text\n    .trim()\n    .replace(/^```(?:json)?\\s*/i, '')\n    .replace(/\\s*```$/, '')\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(raw)\n  } catch {\n    return null\n  }\n  if (!isRecord(parsed)) return null\n  return {\n    rootId: String(parsed['rootId'] ?? ''),\n    nodes: isRecord(parsed['nodes']) ? parsed['nodes'] : {},\n  }\n}\n\n/**\n * What reading a section answer came to. Discriminated by a string rather\n * than a boolean, like every other result in the plugin: this tree compiles\n * without `strictNullChecks`, where a `true`/`false` discriminant does not\n * narrow.\n */\nexport type AssistSectionRead =\n  | { status: 'ok'; section: AssistSection }\n  /** Neither a tool call nor JSON: nothing could be read out of the answer. */\n  | { status: 'unreadable'; error: string }\n  /** Read, and refused by the sanitizer every marketplace install passes. */\n  | { status: 'rejected'; error: string }\n\n/**\n * Read a section answer: the tool call first, the text parse behind it, then\n * the marketplace sanitizer every generated subtree has always passed before\n * it reaches a canvas.\n */\nexport function readAssistSection(result: AiResult): AssistSectionRead {\n  const call =\n    result.kind === 'completion'\n      ? result.toolUse.find((use) => use.name === ASSIST_SECTION_TOOL_NAME)\n      : undefined\n  const nodes = call ? nodesFromToolUse(call.input) : null\n  const definition = nodes\n    ? definitionFromNodes(nodes)\n    : definitionFromText(result.kind === 'completion' ? result.text : '')\n  if (!definition) return { status: 'unreadable', error: 'AI returned invalid JSON' }\n  const sanitized = sanitizeMarketplaceDefinition(definition)\n  // `=== false`, not `!`: see `AssistSectionRead`.\n  if (sanitized.ok === false) return { status: 'rejected', error: sanitized.error }\n  return { status: 'ok', section: { rootId: sanitized.rootId, nodes: sanitized.nodes } }\n}\n"],"names":["MARKETPLACE_COMPONENT_ID_ALLOWLIST","sanitizeMarketplaceDefinition","AI_PALETTE","AI_ACCEPTABLE_USE_BLOCK","MODE_PROMPT","element","blog","section","assistModeSystemBlocks","mode","text","cacheBreakpoint","ASSIST_SECTION_TOOL_NAME","STRING","type","strictObject","properties","required","Object","keys","additionalProperties","assistSectionTool","pair","name","value","node","id","componentId","enum","parentId","children","items","props","description","inputSchema","nodes","strict","isRecord","Array","isArray","propValue","declared","propsSchema","parsed","Number","isFinite","trim","definitionFromNodes","ids","Set","map","root","find","has","$id","filter","child","rootId","nodesFromToolUse","input","raw","length","entry","String","push","definitionFromText","replace","JSON","parse","readAssistSection","result","call","kind","toolUse","use","undefined","definition","status","error","sanitized","ok"],"mappings":"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"}

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

@@ -0,0 +1,119 @@
+/**
+ * @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 PluginApiHandler } from '@aglyn/aglyn/server';
+import { type AiAssistMode } from './ai-assist-prompts';
+/**
+ * The model each mode is served by, through the routing table — tiered by
+ * what the mode actually asks for (AGL-2486), not one model for all three.
+ *
+ * - **element** → the fast tier (`copy.element`). Rewriting one button label
+ *   or one heading to an instruction is a short, bounded transformation with
+ *   the source text supplied: the least model-shaped work on this route and
+ *   the highest-volume (a user clicking "improve this" runs it repeatedly on
+ *   the same element).
+ * - **blog** → the balanced tier (`copy.blog`). A post body is real long-form
+ *   writing, and the difference between tiers is legible to the reader.
+ * - **section** → the balanced tier (`copy.section`). A constrained-JSON node
+ *   subtree over the published-component allowlist is a structured-generation
+ *   task with a schema the sanitizer will reject if it is got wrong, and a
+ *   rejected generation costs the whole request rather than part of it.
+ *
+ * ⚠️ NO PROMPT CACHING IS LOST BY THE FAST RUNG. Each mode's static text now
+ * carries a breakpoint (`assistModeSystemBlocks`), but none of the three is
+ * long enough for its model to cache: the catalog states each model's
+ * minimum and `runtime/ai-prompt-cache.spec.ts` measures every door against
+ * it. That is why the tier drop is free here and NOT free on
+ * `/api/assist/chat`, whose ~1,030-token prefix clears the balanced tier's
+ * minimum and would stop caching entirely on the fast tier's — cheaper per
+ * token, dearer per request, and invisible either way without that
+ * measurement. See the header of `assist-chat.ts`.
+ *
+ * The cost meter prices by model id, so the value returned here MUST be the
+ * one passed to `recordAssistCost` — same call, same variable. A tiering
+ * change that updates the request and not the meter reports one tier's money
+ * for another tier's tokens, which is the failure the by-model rate table
+ * exists to stop.
+ */
+export declare function assistModelForMode(mode: AiAssistMode): string;
+/** The routing table's step kind for each mode. */
+export declare function assistStepKindForMode(mode: AiAssistMode): 'copy.element' | 'copy.blog' | 'copy.section';
+/**
+ * AI assist (AGL-89/130/169), the besigner copy assistant's door — the
+ * section mode composes over the published-component allowlist and every
+ * generated subtree passes the node-definition sanitizer a marketplace
+ * install passes, before it reaches a canvas. `/api/ai/assist` is served by
+ * the plugin API dispatcher under the `ai` prefix. Gated on a ready provider,
+ * one registered with its key set (501 without, the same degrade pattern as
+ * Stripe); auth via Firebase ID token.
+ *
+ * The provider call is `runAiRequest`, the runtime every AI door shares
+ * (AGL-2903). This handler owns the ladder below and the response shapes;
+ * `ai-assist-prompts.ts` owns the three prompts and the section tool; the
+ * runtime owns the wire, the usage arithmetic and the error boundary. The
+ * request keeps the model per mode, the `max_tokens` and the absent
+ * `thinking` field it has always had — a fast-tier model rejects an explicit
+ * one, and the balanced modes keep the model default.
+ *
+ * A section arrives through a strict tool (AGL-2937). It used to be asked
+ * for as bare JSON and parsed: a parse that failed answered 502 with the
+ * tokens already spent, so the whole request bought nothing and the member's
+ * next move was to spend it again. The text parse is kept behind the tool,
+ * for a provider whose adapter has none.
+ *
+ * ── The spend ladder (AGL-2073) ────────────────────────────────────────────
+ *
+ * This route reached the provider behind nothing but an entitlement check. Free
+ * orgs could not get in, so the free tier was safe — but for any Pro org it
+ * had no rate limit, no quota, no per-org cost telemetry, and it resolved the
+ * org from the USER rather than the request, so someone with one paid org got
+ * assist charged against whichever org `getOrgForUser` happened to return. One
+ * subscription, unbounded and unmeasured provider spend.
+ *
+ * The ladder now, in order, each rung able to go red on its own:
+ * 405 → 501 no ready provider → 401 no token → 400 bad body (the request
+ * must NAME the org it is metered against) → 403 not a member of that org →
+ * 423 the workspace's AI pause → 403 the member's role lacks `ai.use`, or
+ * `ai.generate` for a section (AGL-2927; staff pass) → 403 no `aiAssist`
+ * entitlement → 423 org lockdown → 429 rate limit → 429 quota → the model
+ * call → meter.
+ *
+ * Two deliberate choices about which way each rung fails:
+ *
+ * - **The rate limiter fails SOFT and is not the spend bound.** It is a
+ *   per-instance in-memory window, so N serverless instances admit N × 20/min;
+ *   it smooths bursts and nothing more. Treating it as the cap would be the
+ *   fail-open this issue is about.
+ * - **The reservation fails CLOSED.** It is the only global, atomic bound on
+ *   provider spend, so a reservation that cannot be taken — a Firestore
+ *   outage, a contended transaction — refuses the request with 503 rather than
+ *   calling the provider uncapped. An unavailable meter must stop the spending,
+ *   not wave it through.
+ *
+ * The reservation is `reserveAssistMessage` — the same shared counter the
+ * console chat route moves (AGL-2057), not a second mechanism. That is what
+ * closes the "uncapped for paid" hole the earlier audit named: an entitled org
+ * carries the monthly runaway guard, and because both doors move the SAME
+ * counter, an org's monthly assist budget is shared across them rather than
+ * doubled by having two.
+ *
+ * Metering is `recordAssistCost`, the signal + rollup half of the assist
+ * meters WITHOUT the verbatim half: what a customer types here is their own
+ * site copy and blog bodies, and retaining that for 180 days is a data flow
+ * the published privacy disclosure does not describe. The margin question is
+ * answered by the signal alone.
+ */
+export declare const aiAssistHandler: PluginApiHandler;