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

package/src/lib/jobs/ai-job-overlay-copy.js

@@ -0,0 +1,178 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { AI_OVERLAY_COPY_TASK, AI_OVERLAY_CURRENT_MAX_CHARS, aiOverlayCopyText, aiOverlayKind, aiOverlayLimits, aiOverlayTriggerRanges, checkAiOverlayCopy } from "../model/ai-overlay-copy.js";
+import { AI_ROUTING_TABLE } from "../providers/routing.js";
+import { AI_ACCEPTABLE_USE_BLOCK, runAiRequest } from "../runtime/ai-runtime.js";
+import { AI_OVERLAY_TOOL_NAME, aiOverlayTool, parseAiOverlayCopy } from "../tools/ai-overlay-tool.js";
+/**
+ * Overlay copy (AGL-3603): the `text` step asked, by `inputs.task: 'overlay'`,
+ * for an announcement bar's or a popup's copy as fields rather than prose.
+ *
+ * A text job rather than a kind of its own because it IS a text job — a brief
+ * in, a short piece of copy out, one request at the `job.text` route's model
+ * and ceiling — so it runs inline in the create door, is metered as any text
+ * job is and needs no plan. Only the answer's shape differs: one strict tool
+ * call, held by `checkAiOverlayCopy` to the limits and the triggers the
+ * request named.
+ *
+ * ## Nothing is written
+ *
+ * The answer is a proposal on the job's output. The overlay is the marketing
+ * plugin's; its editor fills its fields from the proposal unsaved, or its list
+ * writes a new overlay switched off, and in both a person decides what goes
+ * live. No link, schedule, page targeting or on-switch is ever proposed.
+ *
+ * ## What reaches the model
+ *
+ * The brief, what the overlay is (a bar or a popup), the triggers the site
+ * offers, and — when a person asked from an overlay that has copy — that copy
+ * as the editor holds it. Nothing about the site's visitors or its figures.
+ */ /** The job's failure when the answer could not be used. */ export const AI_OVERLAY_NO_COPY_COPY = 'The AI did not write copy that fits this overlay. Try the brief in different words.';
+/** The job's failure when the inputs name no overlay kind. */ export const AI_OVERLAY_NO_KIND_COPY = 'Say whether the copy is for an announcement bar or a popup.';
+/** The rules, static and byte-identical for every workspace, so they cache. */ export const AI_OVERLAY_RULES = [
+    'You write copy for the announcement bars and popups on a small business’s website. A bar is one short line across the top of every page; a popup is a headline, a short body and an optional button, shown once as the visitor reads.',
+    `Call ${AI_OVERLAY_TOOL_NAME} once.`,
+    '- Lead with what the visitor gets: the offer, the news or the reason to act. One idea per overlay.',
+    '- Keep inside every length the tool states. Shorter is better: a bar is read in a glance.',
+    '- A button label is a few words that start with a verb.',
+    '- For a popup, choose when it opens only from the triggers the request lists, and a value inside the range it gives: a short delay for an announcement, a scroll depth for something a reader earns, exit intent for a last offer. Answer `none` to leave it as it is.',
+    '- Write plain text: no HTML, no markdown, no links, no emoji, no fences.',
+    '- Never invent a fact, a price, a discount, a deadline, a name or a guarantee the brief or the current copy did not give you; where one is missing, leave a clearly marked placeholder in square brackets.',
+    '- Write in the language of the brief.'
+].join('\n');
+export const AI_OVERLAY_SYSTEM = [
+    {
+        text: `${AI_OVERLAY_RULES}\n\n${AI_ACCEPTABLE_USE_BLOCK}`,
+        cacheBreakpoint: true
+    }
+];
+const str = (value)=>typeof value === 'string' ? value.trim() : '';
+const TRIGGER_WORDS = {
+    delay: (range)=>`delay (seconds after the page loads${range ? `, ${range.min} to ${range.max}` : ''})`,
+    scroll: (range)=>`scroll (percent of the page scrolled${range ? `, ${range.min} to ${range.max}` : ''})`,
+    exit: ()=>'exit (as the visitor moves to leave)'
+};
+/** The user turn: the brief, the overlay, its triggers and its copy as it stands. */ export function aiOverlayCopyPrompt(input) {
+    const lines = [
+        `Brief: ${input.brief}`,
+        `Write the copy for ${input.kind === 'bar' ? 'an announcement bar' : 'a popup'}.`
+    ];
+    if (input.kind === 'popup') {
+        lines.push(input.triggers.size ? `Triggers the site offers: ${[
+            ...input.triggers
+        ].map(([id, range])=>TRIGGER_WORDS[id](range)).join('; ')}.` : 'Leave when it opens as it is: answer `none`.');
+    }
+    if (input.current) lines.push('', 'The copy as it stands:', input.current);
+    return lines.join('\n');
+}
+/** A checked proposal as the job's output: shown as text, carried as fields. */ export function aiOverlayCopyOutput(job, proposal) {
+    var _job_hostId;
+    var _job_inputs;
+    return {
+        resource: 'text',
+        id: 'draft',
+        hostId: (_job_hostId = job.hostId) != null ? _job_hostId : null,
+        hostSubdomain: str((_job_inputs = job.inputs) == null ? void 0 : _job_inputs['hostSubdomain']) || null,
+        label: proposal.kind === 'bar' ? 'Announcement bar copy' : 'Popup copy',
+        text: aiOverlayCopyText(proposal),
+        proposal: _extends({
+            task: AI_OVERLAY_COPY_TASK
+        }, proposal),
+        note: 'Put this into the overlay editor to use it; nothing has been changed on the site.'
+    };
+}
+/** The overlay task of the text step: one strict tool call, checked, never written. */ export async function runAiOverlayCopy(input) {
+    var _job_inputs, _result_toolUse_find;
+    const { job, model } = input;
+    const kind = aiOverlayKind(job.inputs);
+    if (!kind) {
+        return {
+            outputs: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                cacheWriteTokens: 0
+            },
+            estCostUsd: 0,
+            model,
+            stopReason: null,
+            failure: AI_OVERLAY_NO_KIND_COPY
+        };
+    }
+    const limits = aiOverlayLimits(job.inputs);
+    const triggers = aiOverlayTriggerRanges(job.inputs);
+    const result = await runAiRequest(_extends({
+        model,
+        system: AI_OVERLAY_SYSTEM,
+        messages: [
+            {
+                role: 'user',
+                content: aiOverlayCopyPrompt({
+                    brief: job.brief,
+                    kind,
+                    triggers,
+                    current: str((_job_inputs = job.inputs) == null ? void 0 : _job_inputs['current']).slice(0, AI_OVERLAY_CURRENT_MAX_CHARS)
+                })
+            }
+        ],
+        tools: [
+            aiOverlayTool(kind, limits, [
+                ...triggers.keys()
+            ])
+        ],
+        maxTokens: input.maxTokens
+    }, AI_ROUTING_TABLE['job.text'].thinking ? {
+        thinking: AI_ROUTING_TABLE['job.text'].thinking
+    } : {}, AI_ROUTING_TABLE['job.text'].effort ? {
+        effort: AI_ROUTING_TABLE['job.text'].effort
+    } : {}, {
+        stream: false
+    }, input.signal ? {
+        signal: input.signal
+    } : {}));
+    const spent = {
+        usage: result.usage,
+        estCostUsd: result.estCostUsd,
+        model,
+        stopReason: result.stopReason
+    };
+    if (result.kind === 'refusal') return _extends({
+        outputs: []
+    }, spent, {
+        refused: true
+    });
+    const checked = checkAiOverlayCopy(parseAiOverlayCopy((_result_toolUse_find = result.toolUse.find((use)=>use.name === AI_OVERLAY_TOOL_NAME)) == null ? void 0 : _result_toolUse_find.input), kind, limits, triggers);
+    if (!checked) return _extends({
+        outputs: []
+    }, spent, {
+        failure: AI_OVERLAY_NO_COPY_COPY
+    });
+    if (checked.findings.length) {
+        console.info('ai overlay copy held to its limits', {
+            jobId: job.$id,
+            findings: checked.findings
+        });
+    }
+    return _extends({
+        outputs: [
+            aiOverlayCopyOutput(job, checked.proposal)
+        ]
+    }, spent);
+}
+
+//# sourceMappingURL=ai-job-overlay-copy.js.map

package/src/lib/jobs/ai-job-overlay-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-job-overlay-copy.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  AI_OVERLAY_COPY_TASK,\n  AI_OVERLAY_CURRENT_MAX_CHARS,\n  aiOverlayCopyText,\n  aiOverlayKind,\n  aiOverlayLimits,\n  aiOverlayTriggerRanges,\n  checkAiOverlayCopy,\n  type AiOverlayCopyProposal,\n  type AiOverlayKind,\n  type AiOverlayTrigger,\n} from '../model/ai-overlay-copy'\nimport type { AiJob, AiJobOutput } from '../model/ai-jobs.types'\nimport { AI_ROUTING_TABLE } from '../providers/routing'\nimport {\n  AI_ACCEPTABLE_USE_BLOCK,\n  runAiRequest,\n  type AiSystemBlock,\n} from '../runtime/ai-runtime'\nimport { AI_OVERLAY_TOOL_NAME, aiOverlayTool, parseAiOverlayCopy } from '../tools/ai-overlay-tool'\nimport type { AiJobStepOutcome } from './ai-job-text-step'\n\n/**\n * Overlay copy (AGL-3603): the `text` step asked, by `inputs.task: 'overlay'`,\n * for an announcement bar's or a popup's copy as fields rather than prose.\n *\n * A text job rather than a kind of its own because it IS a text job — a brief\n * in, a short piece of copy out, one request at the `job.text` route's model\n * and ceiling — so it runs inline in the create door, is metered as any text\n * job is and needs no plan. Only the answer's shape differs: one strict tool\n * call, held by `checkAiOverlayCopy` to the limits and the triggers the\n * request named.\n *\n * ## Nothing is written\n *\n * The answer is a proposal on the job's output. The overlay is the marketing\n * plugin's; its editor fills its fields from the proposal unsaved, or its list\n * writes a new overlay switched off, and in both a person decides what goes\n * live. No link, schedule, page targeting or on-switch is ever proposed.\n *\n * ## What reaches the model\n *\n * The brief, what the overlay is (a bar or a popup), the triggers the site\n * offers, and — when a person asked from an overlay that has copy — that copy\n * as the editor holds it. Nothing about the site's visitors or its figures.\n */\n\n/** The job's failure when the answer could not be used. */\nexport const AI_OVERLAY_NO_COPY_COPY =\n  'The AI did not write copy that fits this overlay. Try the brief in different words.'\n\n/** The job's failure when the inputs name no overlay kind. */\nexport const AI_OVERLAY_NO_KIND_COPY = 'Say whether the copy is for an announcement bar or a popup.'\n\n/** The rules, static and byte-identical for every workspace, so they cache. */\nexport const AI_OVERLAY_RULES = [\n  'You write copy for the announcement bars and popups on a small business’s website. A bar is one short line across the top of every page; a popup is a headline, a short body and an optional button, shown once as the visitor reads.',\n  `Call ${AI_OVERLAY_TOOL_NAME} once.`,\n  '- Lead with what the visitor gets: the offer, the news or the reason to act. One idea per overlay.',\n  '- Keep inside every length the tool states. Shorter is better: a bar is read in a glance.',\n  '- A button label is a few words that start with a verb.',\n  '- For a popup, choose when it opens only from the triggers the request lists, and a value inside the range it gives: a short delay for an announcement, a scroll depth for something a reader earns, exit intent for a last offer. Answer `none` to leave it as it is.',\n  '- Write plain text: no HTML, no markdown, no links, no emoji, no fences.',\n  '- Never invent a fact, a price, a discount, a deadline, a name or a guarantee the brief or the current copy did not give you; where one is missing, leave a clearly marked placeholder in square brackets.',\n  '- Write in the language of the brief.',\n].join('\\n')\n\nexport const AI_OVERLAY_SYSTEM: AiSystemBlock[] = [\n  { text: `${AI_OVERLAY_RULES}\\n\\n${AI_ACCEPTABLE_USE_BLOCK}`, cacheBreakpoint: true },\n]\n\nconst str = (value: unknown): string => (typeof value === 'string' ? value.trim() : '')\n\nconst TRIGGER_WORDS: Record<AiOverlayTrigger, (range: { min: number; max: number } | null) => string> = {\n  delay: (range) => `delay (seconds after the page loads${range ? `, ${range.min} to ${range.max}` : ''})`,\n  scroll: (range) => `scroll (percent of the page scrolled${range ? `, ${range.min} to ${range.max}` : ''})`,\n  exit: () => 'exit (as the visitor moves to leave)',\n}\n\n/** The user turn: the brief, the overlay, its triggers and its copy as it stands. */\nexport function aiOverlayCopyPrompt(input: {\n  brief: string\n  kind: AiOverlayKind\n  triggers: ReadonlyMap<AiOverlayTrigger, { min: number; max: number } | null>\n  current: string\n}): string {\n  const lines = [`Brief: ${input.brief}`, `Write the copy for ${input.kind === 'bar' ? 'an announcement bar' : 'a popup'}.`]\n  if (input.kind === 'popup') {\n    lines.push(\n      input.triggers.size\n        ? `Triggers the site offers: ${[...input.triggers].map(([id, range]) => TRIGGER_WORDS[id](range)).join('; ')}.`\n        : 'Leave when it opens as it is: answer `none`.',\n    )\n  }\n  if (input.current) lines.push('', 'The copy as it stands:', input.current)\n  return lines.join('\\n')\n}\n\n/** A checked proposal as the job's output: shown as text, carried as fields. */\nexport function aiOverlayCopyOutput(\n  job: Pick<AiJob, 'hostId' | 'inputs'>,\n  proposal: AiOverlayCopyProposal,\n): AiJobOutput {\n  return {\n    resource: 'text',\n    id: 'draft',\n    hostId: job.hostId ?? null,\n    hostSubdomain: str(job.inputs?.['hostSubdomain']) || null,\n    label: proposal.kind === 'bar' ? 'Announcement bar copy' : 'Popup copy',\n    text: aiOverlayCopyText(proposal),\n    proposal: { task: AI_OVERLAY_COPY_TASK, ...proposal },\n    note: 'Put this into the overlay editor to use it; nothing has been changed on the site.',\n  }\n}\n\n/** The overlay task of the text step: one strict tool call, checked, never written. */\nexport async function runAiOverlayCopy(input: {\n  job: Pick<AiJob, '$id' | 'brief' | 'hostId' | 'inputs'>\n  model: string\n  maxTokens: number\n  signal?: AbortSignal\n}): Promise<AiJobStepOutcome> {\n  const { job, model } = input\n  const kind = aiOverlayKind(job.inputs)\n  if (!kind) {\n    return {\n      outputs: [],\n      usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 },\n      estCostUsd: 0,\n      model,\n      stopReason: null,\n      failure: AI_OVERLAY_NO_KIND_COPY,\n    }\n  }\n  const limits = aiOverlayLimits(job.inputs)\n  const triggers = aiOverlayTriggerRanges(job.inputs)\n  const result = await runAiRequest({\n    model,\n    system: AI_OVERLAY_SYSTEM,\n    messages: [\n      {\n        role: 'user',\n        content: aiOverlayCopyPrompt({\n          brief: job.brief,\n          kind,\n          triggers,\n          current: str(job.inputs?.['current']).slice(0, AI_OVERLAY_CURRENT_MAX_CHARS),\n        }),\n      },\n    ],\n    tools: [aiOverlayTool(kind, limits, [...triggers.keys()])],\n    maxTokens: input.maxTokens,\n    ...(AI_ROUTING_TABLE['job.text'].thinking ? { thinking: AI_ROUTING_TABLE['job.text'].thinking } : {}),\n    ...(AI_ROUTING_TABLE['job.text'].effort ? { effort: AI_ROUTING_TABLE['job.text'].effort } : {}),\n    stream: false,\n    ...(input.signal ? { signal: input.signal } : {}),\n  })\n  const spent = {\n    usage: result.usage,\n    estCostUsd: result.estCostUsd,\n    model,\n    stopReason: result.stopReason,\n  }\n  if (result.kind === 'refusal') return { outputs: [], ...spent, refused: true }\n  const checked = checkAiOverlayCopy(\n    parseAiOverlayCopy(result.toolUse.find((use) => use.name === AI_OVERLAY_TOOL_NAME)?.input),\n    kind,\n    limits,\n    triggers,\n  )\n  if (!checked) return { outputs: [], ...spent, failure: AI_OVERLAY_NO_COPY_COPY }\n  if (checked.findings.length) {\n    console.info('ai overlay copy held to its limits', { jobId: job.$id, findings: checked.findings })\n  }\n  return { outputs: [aiOverlayCopyOutput(job, checked.proposal)], ...spent }\n}\n"],"names":["AI_OVERLAY_COPY_TASK","AI_OVERLAY_CURRENT_MAX_CHARS","aiOverlayCopyText","aiOverlayKind","aiOverlayLimits","aiOverlayTriggerRanges","checkAiOverlayCopy","AI_ROUTING_TABLE","AI_ACCEPTABLE_USE_BLOCK","runAiRequest","AI_OVERLAY_TOOL_NAME","aiOverlayTool","parseAiOverlayCopy","AI_OVERLAY_NO_COPY_COPY","AI_OVERLAY_NO_KIND_COPY","AI_OVERLAY_RULES","join","AI_OVERLAY_SYSTEM","text","cacheBreakpoint","str","value","trim","TRIGGER_WORDS","delay","range","min","max","scroll","exit","aiOverlayCopyPrompt","input","lines","brief","kind","push","triggers","size","map","id","current","aiOverlayCopyOutput","job","proposal","resource","hostId","hostSubdomain","inputs","label","task","note","runAiOverlayCopy","result","model","outputs","usage","inputTokens","outputTokens","cacheReadTokens","cacheWriteTokens","estCostUsd","stopReason","failure","limits","system","messages","role","content","slice","tools","keys","maxTokens","thinking","effort","stream","signal","spent","refused","checked","toolUse","find","use","name","findings","length","console","info","jobId","$id"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,oBAAoB,EACpBC,4BAA4B,EAC5BC,iBAAiB,EACjBC,aAAa,EACbC,eAAe,EACfC,sBAAsB,EACtBC,kBAAkB,QAIb,8BAA0B;AAEjC,SAASC,gBAAgB,QAAQ,0BAAsB;AACvD,SACEC,uBAAuB,EACvBC,YAAY,QAEP,2BAAuB;AAC9B,SAASC,oBAAoB,EAAEC,aAAa,EAAEC,kBAAkB,QAAQ,8BAA0B;AAGlG;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAED,yDAAyD,GACzD,OAAO,MAAMC,0BACX,sFAAqF;AAEvF,4DAA4D,GAC5D,OAAO,MAAMC,0BAA0B,8DAA6D;AAEpG,6EAA6E,GAC7E,OAAO,MAAMC,mBAAmB;IAC9B;IACA,CAAC,KAAK,EAAEL,qBAAqB,MAAM,CAAC;IACpC;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAACM,IAAI,CAAC,MAAK;AAEZ,OAAO,MAAMC,oBAAqC;IAChD;QAAEC,MAAM,GAAGH,iBAAiB,IAAI,EAAEP,yBAAyB;QAAEW,iBAAiB;IAAK;CACpF,CAAA;AAED,MAAMC,MAAM,CAACC,QAA4B,OAAOA,UAAU,WAAWA,MAAMC,IAAI,KAAK;AAEpF,MAAMC,gBAAkG;IACtGC,OAAO,CAACC,QAAU,CAAC,mCAAmC,EAAEA,QAAQ,CAAC,EAAE,EAAEA,MAAMC,GAAG,CAAC,IAAI,EAAED,MAAME,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC;IACxGC,QAAQ,CAACH,QAAU,CAAC,oCAAoC,EAAEA,QAAQ,CAAC,EAAE,EAAEA,MAAMC,GAAG,CAAC,IAAI,EAAED,MAAME,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC;IAC1GE,MAAM,IAAM;AACd;AAEA,mFAAmF,GACnF,OAAO,SAASC,oBAAoBC,KAKnC;IACC,MAAMC,QAAQ;QAAC,CAAC,OAAO,EAAED,MAAME,KAAK,EAAE;QAAE,CAAC,mBAAmB,EAAEF,MAAMG,IAAI,KAAK,QAAQ,wBAAwB,UAAU,CAAC,CAAC;KAAC;IAC1H,IAAIH,MAAMG,IAAI,KAAK,SAAS;QAC1BF,MAAMG,IAAI,CACRJ,MAAMK,QAAQ,CAACC,IAAI,GACf,CAAC,0BAA0B,EAAE;eAAIN,MAAMK,QAAQ;SAAC,CAACE,GAAG,CAAC,CAAC,CAACC,IAAId,MAAM,GAAKF,aAAa,CAACgB,GAAG,CAACd,QAAQT,IAAI,CAAC,MAAM,CAAC,CAAC,GAC7G;IAER;IACA,IAAIe,MAAMS,OAAO,EAAER,MAAMG,IAAI,CAAC,IAAI,0BAA0BJ,MAAMS,OAAO;IACzE,OAAOR,MAAMhB,IAAI,CAAC;AACpB;AAEA,8EAA8E,GAC9E,OAAO,SAASyB,oBACdC,GAAqC,EACrCC,QAA+B;QAKrBD;QACWA;IAJrB,OAAO;QACLE,UAAU;QACVL,IAAI;QACJM,MAAM,GAAEH,cAAAA,IAAIG,MAAM,YAAVH,cAAc;QACtBI,eAAe1B,KAAIsB,cAAAA,IAAIK,MAAM,qBAAVL,WAAY,CAAC,gBAAgB,KAAK;QACrDM,OAAOL,SAAST,IAAI,KAAK,QAAQ,0BAA0B;QAC3DhB,MAAMhB,kBAAkByC;QACxBA,UAAU;YAAEM,MAAMjD;WAAyB2C;QAC3CO,MAAM;IACR;AACF;AAEA,qFAAqF,GACrF,OAAO,eAAeC,iBAAiBpB,KAKtC;QAyBsBW,aAmBAU;IA3CrB,MAAM,EAAEV,GAAG,EAAEW,KAAK,EAAE,GAAGtB;IACvB,MAAMG,OAAO/B,cAAcuC,IAAIK,MAAM;IACrC,IAAI,CAACb,MAAM;QACT,OAAO;YACLoB,SAAS,EAAE;YACXC,OAAO;gBAAEC,aAAa;gBAAGC,cAAc;gBAAGC,iBAAiB;gBAAGC,kBAAkB;YAAE;YAClFC,YAAY;YACZP;YACAQ,YAAY;YACZC,SAAShD;QACX;IACF;IACA,MAAMiD,SAAS3D,gBAAgBsC,IAAIK,MAAM;IACzC,MAAMX,WAAW/B,uBAAuBqC,IAAIK,MAAM;IAClD,MAAMK,SAAS,MAAM3C,aAAa;QAChC4C;QACAW,QAAQ/C;QACRgD,UAAU;YACR;gBACEC,MAAM;gBACNC,SAASrC,oBAAoB;oBAC3BG,OAAOS,IAAIT,KAAK;oBAChBC;oBACAE;oBACAI,SAASpB,KAAIsB,cAAAA,IAAIK,MAAM,qBAAVL,WAAY,CAAC,UAAU,EAAE0B,KAAK,CAAC,GAAGnE;gBACjD;YACF;SACD;QACDoE,OAAO;YAAC1D,cAAcuB,MAAM6B,QAAQ;mBAAI3B,SAASkC,IAAI;aAAG;SAAE;QAC1DC,WAAWxC,MAAMwC,SAAS;OACtBhE,gBAAgB,CAAC,WAAW,CAACiE,QAAQ,GAAG;QAAEA,UAAUjE,gBAAgB,CAAC,WAAW,CAACiE,QAAQ;IAAC,IAAI,CAAC,GAC/FjE,gBAAgB,CAAC,WAAW,CAACkE,MAAM,GAAG;QAAEA,QAAQlE,gBAAgB,CAAC,WAAW,CAACkE,MAAM;IAAC,IAAI,CAAC;QAC7FC,QAAQ;OACJ3C,MAAM4C,MAAM,GAAG;QAAEA,QAAQ5C,MAAM4C,MAAM;IAAC,IAAI,CAAC;IAEjD,MAAMC,QAAQ;QACZrB,OAAOH,OAAOG,KAAK;QACnBK,YAAYR,OAAOQ,UAAU;QAC7BP;QACAQ,YAAYT,OAAOS,UAAU;IAC/B;IACA,IAAIT,OAAOlB,IAAI,KAAK,WAAW,OAAO;QAAEoB,SAAS,EAAE;OAAKsB;QAAOC,SAAS;;IACxE,MAAMC,UAAUxE,mBACdM,oBAAmBwC,uBAAAA,OAAO2B,OAAO,CAACC,IAAI,CAAC,CAACC,MAAQA,IAAIC,IAAI,KAAKxE,0CAA1C0C,qBAAiErB,KAAK,GACzFG,MACA6B,QACA3B;IAEF,IAAI,CAAC0C,SAAS,OAAO;QAAExB,SAAS,EAAE;OAAKsB;QAAOd,SAASjD;;IACvD,IAAIiE,QAAQK,QAAQ,CAACC,MAAM,EAAE;QAC3BC,QAAQC,IAAI,CAAC,sCAAsC;YAAEC,OAAO7C,IAAI8C,GAAG;YAAEL,UAAUL,QAAQK,QAAQ;QAAC;IAClG;IACA,OAAO;QAAE7B,SAAS;YAACb,oBAAoBC,KAAKoC,QAAQnC,QAAQ;SAAE;OAAKiC;AACrE"}

package/src/lib/jobs/ai-job-page-language.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @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 { NodesMap } from '@aglyn/aglyn/types/nodes';
+import { type AiBuildPlanScreen } from '../model/ai-build-plan';
+import type { AiJob, AiJobPlan } from '../model/ai-jobs.types';
+import { type AiSiteInventory } from '../model/ai-site-inventory';
+import { type AiLayoutSection, type AiLayoutSettlement } from '../layout-language/ai-layout-language';
+import type { AiLayoutTargets } from '../layout-language/ai-layout-links';
+import { type AiGenerationCheck, type AiValidatedGeneration } from '../runtime/ai-doctrine';
+import { type AiDoctrineTreeContext } from '../runtime/ai-doctrine-validators';
+import type { AiLoadEstimate } from '../runtime/ai-palette';
+import type { AiSystemBlock } from '../runtime/ai-runtime';
+/**
+ * A page built in the compact layout language (AGL-3660): the page step's
+ * pass for a site's page units — a guided start's and a build's — in place of
+ * the raw-tree section passes.
+ *
+ * ONE answer a page: every planned section, in the language, through
+ * `submit_page`. The compiler writes the tree, the palette validator stores
+ * it as it stores any generated tree, and the doctrine checks the whole page.
+ * A section the answer left out or left empty is the one thing a re-ask asks
+ * for: the sections that read are kept, and the second answer fills only
+ * what is still missing. Then the page step's last pass runs as it always
+ * has — the whole page held to the doctrine again, its listing written, the
+ * draft reported — so the item ledger, the credits and Try again work exactly
+ * as they did.
+ */
+/** The unit input that says a page or a layout is built in the layout language. */
+export declare const AI_LAYOUT_LANGUAGE_INPUT = "layoutLanguage";
+/** The unit input naming the page of the site that places its form, where it is another page. */
+export declare const AI_LAYOUT_FORM_PAGE_INPUT = "layoutFormPage";
+/** Whether this job builds its page or its layout in the layout language. */
+export declare function aiJobUsesLayoutLanguage(job: Pick<AiJob, 'inputs'>): boolean;
+/**
+ * The most one page's answer asks for. A section in the language is about
+ * 120 to 250 tokens with its copy, so the largest page a plan admits — eight
+ * sections — fits with room; the compiler, not the ceiling, keeps a page small.
+ */
+export declare const AI_JOB_PAGE_LANGUAGE_TOKENS = 3000;
+/**
+ * The time a language page pass needs: its lookup rounds, its answer and its
+ * re-ask at `AI_JOB_PAGE_LANGUAGE_TOKENS` on the tier the page step is served
+ * from, with the step's reads and writes.
+ */
+/** The most the follow-up asking only for the sections an answer left out may run to. */
+export declare const AI_JOB_PAGE_LANGUAGE_FOLLOW_UP_TOKENS = 1500;
+export declare const AI_JOB_PAGE_LANGUAGE_BUDGET: import("./ai-job-budget").AiJobStepBudget;
+/** The doctrine scope the language doors are told: values the compiler checks itself. */
+export declare const AI_LAYOUT_PAGE_KIND = "layout-page";
+/** The language, as the page door's cached instructions. */
+export declare const AI_JOB_PAGE_LANGUAGE_INSTRUCTIONS: readonly AiSystemBlock[];
+/** The page of a site plan that places its form: the form the plan creates, or one the site has. */
+export declare function aiLayoutFormPageOfPlan(plan: Pick<AiJobPlan, 'create' | 'screens'>, formIds?: readonly string[]): string | null;
+/** Every word the job was given, which a page's contact details are held to. */
+export declare function aiLayoutFacts(job: Pick<AiJob, 'brief' | 'inputs'>): string;
+/** What a page's links resolve against: the site's pages, built and planned, its forms and components. */
+export declare function aiLayoutPageTargets(input: {
+    job: Pick<AiJob, 'brief' | 'inputs'>;
+    inventory: AiSiteInventory | null;
+    own: ReadonlyArray<string | null | undefined>;
+}): AiLayoutTargets;
+/** The page's user turn: the page, the brief, the plan, its sections and where its links may go. */
+export declare function aiLayoutPagePrompt(input: {
+    job: Pick<AiJob, 'brief' | 'inputs' | '$id'>;
+    plan: AiJobPlan;
+    screen: AiBuildPlanScreen;
+    targets: AiLayoutTargets;
+    reusableComponents: boolean;
+    /** The sections a re-ask still needs, by plan index; absent on the first ask. */
+    missing?: readonly number[];
+}): string;
+/** A validated language page, stored as the page keeps it. */
+export interface AiLayoutPageBuilt {
+    nodes: NodesMap;
+    load: AiLoadEstimate | null;
+    settled: AiLayoutSettlement[];
+    /** What the last answer's gaps took out of the page (`ai-layout-gaps.ts`). */
+    dropped: string[];
+}
+export interface AiLayoutPageCheckInput {
+    screen: AiBuildPlanScreen;
+    sectionIds: readonly string[];
+    targets: AiLayoutTargets;
+    context: AiDoctrineTreeContext;
+    reusableComponents: boolean;
+    /**
+     * What earlier answers gave, by plan index, shared between the page's
+     * generations: a follow-up asking only for missing sections fills the rest.
+     */
+    kept?: Array<AiLayoutSection | null>;
+    /** The plan indices this answer's sections fill, in order; absent, every section. */
+    only?: readonly number[];
+}
+/**
+ * The follow-up turn for the sections a page's answer left out (AGL-3660):
+ * the page as before, told which sections it already has, and asked for only
+ * the missing ones, in order — the one part of a page asked for again.
+ */
+export declare function aiLayoutMissingSectionsPrompt(input: {
+    base: string;
+    screen: AiBuildPlanScreen;
+    missing: readonly number[];
+}): string;
+/** The plan indices a page still lacks, after the answers so far. */
+export declare function aiLayoutMissingSections(kept: ReadonlyArray<AiLayoutSection | null>): number[];
+/** The violation a planned section the answer gave nothing usable for is named by. */
+export declare const AI_LAYOUT_SECTION_MISSING_CODE = "layout-section-missing";
+/**
+ * The check a language page answer is held to: each planned section read,
+ * the page compiled, stored and checked whole. Sections that read are kept
+ * across the re-ask, so the second answer is asked only for what was missing,
+ * and a section it sends again that already read is not taken twice.
+ */
+export declare function aiLayoutPageCheck(input: AiLayoutPageCheckInput): AiGenerationCheck<AiLayoutPageBuilt>;
+export interface AiLayoutPageRunInput {
+    job: Pick<AiJob, 'brief' | 'inputs' | '$id'>;
+    plan: AiJobPlan;
+    screen: AiBuildPlanScreen;
+    sectionIds: readonly string[];
+    targets: AiLayoutTargets;
+    context: AiDoctrineTreeContext;
+    reusableComponents: boolean;
+    inventory: AiSiteInventory | null;
+    model: string;
+    signal?: AbortSignal;
+    /** Wraps the check, for an eval that records each answer it reads. */
+    observe?: (check: AiGenerationCheck<AiLayoutPageBuilt>) => AiGenerationCheck<AiLayoutPageBuilt>;
+}
+/**
+ * A whole page in the layout language: one answer for every section, and,
+ * where that answer and its re-ask still left a section out, one follow-up
+ * asking for only those (AGL-3660). The sections that read are kept between
+ * them, so the page is compiled whole once every section is designed.
+ */
+export declare function aiRunLayoutPage(input: AiLayoutPageRunInput): Promise<AiValidatedGeneration<AiLayoutPageBuilt>>;