@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/jobs/ai-job-component-step.js

@@ -0,0 +1,262 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { duplicateResource } from "@aglyn/tenant-data-admin/server/duplicate-resource";
+import { AI_STEP_TIERS } from "../providers/catalog.js";
+import { AI_ROUTING_TABLE, aiModelForStep } from "../providers/routing.js";
+import { runValidatedGeneration } from "../runtime/ai-doctrine.js";
+import { readSiteInventory } from "../runtime/site-inventory.js";
+import { AI_COMPONENT_TOOL_NAME, aiComponentPropKindWords, aiComponentTool } from "../tools/ai-component-tool.js";
+import { registerAiJobAdmission } from "./ai-job-admission.js";
+import { aiJobStepBudget } from "./ai-job-budget.js";
+import { aiComponentCheck } from "./ai-job-component-checks.js";
+import { aiJobDraftId } from "./ai-job-draft-ids.js";
+import { aiDraftAdmissionRefusal, aiDraftAllowanceRefusal, aiSiteSubdomain, readAiDraft, writeAiDraft } from "./ai-job-drafts.js";
+import { aiBracketedFactsNote, aiConfirmedPlan, aiDoctrineReview, aiGenerationSpent, aiJobBriefLine, aiLimitReview, aiPlanCreation, aiPlanReferenceLines, aiUnspentOutcome } from "./ai-job-generation.js";
+import { registerAiJobStep } from "./ai-jobs.js";
+/**
+ * The component step (AGL-2908): the generation step of a `component` job,
+ * run once a member confirmed the job's plan.
+ *
+ * It builds ONE reusable component from the brief — its tree, and the typed
+ * properties each page that places it fills in — through
+ * `runValidatedGeneration('component', …)`, so every building rule holds on
+ * the tree before it is kept. The tree binds each property with
+ * `{{prop.<name>}}`; the palette validator keeps those tokens as written
+ * (`definesComponent`), and the step's own check, through `extend`, holds
+ * each binding to what the Properties dialog and the Attributes panel allow
+ * (`ai-job-component-checks.ts`).
+ *
+ * The component lands as a new draft (`ai-job-drafts.ts`) that no page
+ * places, and gets its first version when a member opens it, as every
+ * component created outside the besigner does. A plan that starts from a copy
+ * of a component the site has gets that copy, through the platform's
+ * duplicate module, and nothing generated.
+ *
+ * A generation step runs on the job beat, never at an inline door: it
+ * registers the least time its lookup rounds, its answer and its re-ask need
+ * (AGL-3035), runs without extended thinking, and asks for no more of the
+ * ceiling the layout and template steps keep than fits that time on the model
+ * it runs. The step's spec measures the request and the answer against it.
+ */ /** The longest answer a component may run to; the tree is held to the component budget either way. */ export const AI_JOB_COMPONENT_MAX_TOKENS = AI_ROUTING_TABLE['job.component'].maxTokens;
+/**
+ * The component step's time (AGL-3035, AGL-3036): its two inventory-lookup
+ * rounds, its answer and its re-ask at the routing table's ceiling on the tier
+ * `job.component` is served from, fitted to what a beat can give a step.
+ */ export const AI_JOB_COMPONENT_STEP_BUDGET = aiJobStepBudget({
+    tier: AI_STEP_TIERS['job.component'],
+    maxTokens: AI_JOB_COMPONENT_MAX_TOKENS
+});
+/** The least time one component step needs before it starts. */ export const AI_JOB_COMPONENT_STEP_MINIMUM_MS = AI_JOB_COMPONENT_STEP_BUDGET.minimumMs;
+/** A component's name when the plan names none. */ export const AI_JOB_COMPONENT_DEFAULT_NAME = 'Component';
+/** The component step's own instructions, cached after the doctrine and before the catalog. */ export const AI_JOB_COMPONENT_INSTRUCTIONS = [
+    {
+        text: [
+            `You build one reusable component for a website: a block the site places on many pages, each placement filling in its own values. Answer with ${AI_COMPONENT_TOOL_NAME}: the component’s tree as one flat node map, and the properties it declares.`,
+            'The root is the document wrapper holding the component. A component is placed inside a page section, which opens with its own h2: it carries no main landmark, its headings are h3 or below, and its colors, spacing and type come from the theme.',
+            'Every value that should differ from one placement to the next is a property, bound in the tree with its token {{prop.<name>}}. Declare every property the tree binds, and bind every property you declare.',
+            `Property kinds, as type (the name a page reads): ${aiComponentPropKindWords()}.`,
+            'A property binds only to a field that holds its kind of value:',
+            '- text, richText and number: copy, such as a Typography’s text, an Image’s alt or a Button’s label, as the whole value or inside a sentence.',
+            '- image: an Image’s src, as the whole value.',
+            '- href: a screenId or an href, as the whole value.',
+            '- icon: an Icon element’s iconId, as the whole value.',
+            '- boolean: a switch setting such as a Button’s fullWidth, or hideIf on the part it hides, as the whole value.',
+            '- choice: a setting with fixed options such as a Button’s variant, as the whole value, with every answer’s value one that setting lists.',
+            'An optional part, such as a photo, a badge or a second button, gets a boolean property labeled "Hide <the part>" whose default is "false", and the part’s own element carries "hideIf": "{{prop.<name>}}". Never hide the whole component.',
+            'A default is what the component shows until a page sets it: copy in the site’s voice from the brief, with a fact the brief does not give in square brackets; for href a screen id from the site inventory, or ""; for image "", for an upload; for icon "", for the site owner to pick; for choice one of its answers’ values.'
+        ].join('\n')
+    }
+];
+/** The component job as the generation's user turn: the name, the brief, the confirmed plan. */ export function aiJobComponentPrompt(job, plan, name) {
+    return [
+        `Component name: ${name}`,
+        aiJobBriefLine(job),
+        ...aiPlanReferenceLines(plan)
+    ].join('\n');
+}
+/** A component job is admitted for a site of the job's own org whose plan includes reusable components. */ export const aiComponentJobAdmission = (context)=>aiDraftAdmissionRefusal(context.firestore, {
+        orgId: context.orgId,
+        hostId: context.hostId,
+        kind: 'component',
+        org: context.org
+    });
+export function createAiJobComponentStep(deps = {}) {
+    var _deps_readInventory, _deps_duplicate;
+    const readInventory = (_deps_readInventory = deps.readInventory) != null ? _deps_readInventory : readSiteInventory;
+    const duplicate = (_deps_duplicate = deps.duplicate) != null ? _deps_duplicate : duplicateResource;
+    return async ({ job, now, signal, firestore, modelFor })=>{
+        var _ref, _orgSnapshot_data;
+        const hostId = job.hostId;
+        if (!hostId) throw new Error('a component job names no site, and its admission refuses one');
+        const output = (draft, load, note)=>_extends({
+                resource: 'reusableComponent',
+                id: draft.id,
+                versionId: draft.versionId,
+                hostId,
+                hostSubdomain: draft.hostSubdomain,
+                label: draft.name
+            }, load ? {
+                load
+            } : {}, note ? {
+                note
+            } : {});
+        // The switch's answer for this job, else the routing table's (AGL-2942).
+        const model = (_ref = modelFor == null ? void 0 : modelFor('job.component')) != null ? _ref : aiModelForStep('job.component');
+        // A run cut off after its draft was written reports that draft, found by the id the job recorded.
+        const draftId = aiJobDraftId(job, 'component');
+        const written = await readAiDraft(firestore, {
+            kind: 'component',
+            hostId,
+            id: draftId
+        });
+        if (written) return aiUnspentOutcome(model, {
+            outputs: [
+                output(written)
+            ]
+        });
+        const [inventory, orgSnapshot] = await Promise.all([
+            readInventory(job.orgId, hostId, {
+                firestore
+            }),
+            firestore.collection('orgs').doc(job.orgId).get()
+        ]);
+        const org = (_orgSnapshot_data = orgSnapshot.data()) != null ? _orgSnapshot_data : null;
+        const plan = aiConfirmedPlan(job);
+        const creation = aiPlanCreation(plan, 'component');
+        const name = (creation == null ? void 0 : creation.name) || AI_JOB_COMPONENT_DEFAULT_NAME;
+        // The plan starts from a copy of a component the site has (rule 15): the
+        // copy is the draft, and nothing is generated. A source gone since the
+        // plan was made is built from the brief instead.
+        if ((creation == null ? void 0 : creation.duplicateOf) && inventory.components.some((component)=>component.id === creation.duplicateOf)) {
+            const copy = await duplicate('component', {
+                orgId: job.orgId,
+                hostId,
+                sourceId: creation.duplicateOf,
+                name,
+                uid: job.createdBy,
+                org: org
+            });
+            if (copy.ok) {
+                var _copy_versionId;
+                const hostSubdomain = await aiSiteSubdomain(firestore, hostId);
+                return aiUnspentOutcome(model, {
+                    outputs: [
+                        output({
+                            id: copy.id,
+                            versionId: (_copy_versionId = copy.versionId) != null ? _copy_versionId : null,
+                            name: copy.name,
+                            hostSubdomain
+                        })
+                    ]
+                });
+            }
+            if (copy.ok === false && copy.status === 403) {
+                return aiUnspentOutcome(model, {
+                    review: aiLimitReview(copy.error)
+                });
+            }
+        }
+        const allowance = await aiDraftAllowanceRefusal(firestore, {
+            kind: 'component',
+            hostId,
+            org
+        });
+        if (allowance) return aiUnspentOutcome(model, {
+            review: aiLimitReview(allowance)
+        });
+        let props = [];
+        const result = await runValidatedGeneration('component', _extends({
+            step: 'job.component',
+            model,
+            instructions: AI_JOB_COMPONENT_INSTRUCTIONS,
+            inventory,
+            messages: [
+                {
+                    role: 'user',
+                    content: aiJobComponentPrompt(job, plan, name)
+                }
+            ],
+            tool: aiComponentTool(),
+            maxTokens: AI_JOB_COMPONENT_STEP_BUDGET.maxTokens(model)
+        }, AI_ROUTING_TABLE['job.component'].thinking ? {
+            thinking: AI_ROUTING_TABLE['job.component'].thinking
+        } : {}, AI_ROUTING_TABLE['job.component'].effort ? {
+            effort: AI_ROUTING_TABLE['job.component'].effort
+        } : {}, {
+            context: {
+                definesComponent: true
+            },
+            extend: aiComponentCheck({
+                inventory,
+                plan,
+                onProps: (declared)=>{
+                    props = declared;
+                }
+            })
+        }, signal ? {
+            signal
+        } : {}));
+        const spent = aiGenerationSpent(result);
+        if (result.status === 'refused') return _extends({}, spent, {
+            refused: true
+        });
+        if (result.status === 'needs_input') return _extends({}, spent, {
+            review: aiDoctrineReview(result)
+        });
+        const draft = await writeAiDraft(firestore, {
+            kind: 'component',
+            hostId,
+            id: draftId,
+            uid: job.createdBy,
+            org,
+            name,
+            nodes: result.value.nodes,
+            rootId: result.value.rootId,
+            props,
+            now
+        });
+        if (draft.ok === false) {
+            if (draft.status === 404) throw new Error(`site ${hostId} vanished while its component was generated`);
+            return _extends({}, spent, {
+                review: aiLimitReview(draft.error)
+            });
+        }
+        // The facts the brief did not give, in the tree or the defaults a page shows (AGL-3056).
+        const note = aiBracketedFactsNote({
+            tree: {
+                rootId: result.value.rootId,
+                nodes: result.value.nodes
+            },
+            inventory,
+            copy: props.map((prop)=>typeof prop.defaultValue === 'string' ? prop.defaultValue : '')
+        });
+        return _extends({}, spent, {
+            outputs: [
+                output(draft, result.value.load, note)
+            ]
+        });
+    };
+}
+export const runAiJobComponentStep = createAiJobComponentStep();
+/** Registers the component step and the check a component job passes before it is created or resumed. */ export function registerAiComponentJob() {
+    registerAiJobStep('component', runAiJobComponentStep, {
+        minimumMs: AI_JOB_COMPONENT_STEP_MINIMUM_MS
+    });
+    registerAiJobAdmission('component', aiComponentJobAdmission);
+}
+
+//# sourceMappingURL=ai-job-component-step.js.map

package/src/lib/jobs/ai-job-component-step.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-job-component-step.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 { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types'\nimport type { ReusableComponentProp } from '@aglyn/aglyn/foundation/definitions/platform.types'\nimport { duplicateResource } from '@aglyn/tenant-data-admin/server/duplicate-resource'\nimport type { AiJob, AiJobOutput, AiJobPlan } from '../model/ai-jobs.types'\nimport { AI_STEP_TIERS } from '../providers/catalog'\nimport { AI_ROUTING_TABLE, aiModelForStep } from '../providers/routing'\nimport { runValidatedGeneration } from '../runtime/ai-doctrine'\nimport type { AiDoctrineTree } from '../runtime/ai-doctrine-validators'\nimport type { AiLoadEstimate } from '../runtime/ai-palette'\nimport type { AiSystemBlock } from '../runtime/ai-runtime'\nimport { readSiteInventory } from '../runtime/site-inventory'\nimport {\n  AI_COMPONENT_TOOL_NAME,\n  aiComponentPropKindWords,\n  aiComponentTool,\n} from '../tools/ai-component-tool'\nimport { registerAiJobAdmission, type AiJobAdmission } from './ai-job-admission'\nimport { aiJobStepBudget } from './ai-job-budget'\nimport { aiComponentCheck } from './ai-job-component-checks'\nimport { aiJobDraftId } from './ai-job-draft-ids'\nimport {\n  aiDraftAdmissionRefusal,\n  aiDraftAllowanceRefusal,\n  aiSiteSubdomain,\n  readAiDraft,\n  writeAiDraft,\n  type AiDraftRecord,\n} from './ai-job-drafts'\nimport {\n  aiBracketedFactsNote,\n  aiConfirmedPlan,\n  aiDoctrineReview,\n  aiGenerationSpent,\n  aiJobBriefLine,\n  aiLimitReview,\n  aiPlanCreation,\n  aiPlanReferenceLines,\n  aiUnspentOutcome,\n} from './ai-job-generation'\nimport type { AiJobStepRunner } from './ai-job-text-step'\nimport { registerAiJobStep } from './ai-jobs'\n\n/**\n * The component step (AGL-2908): the generation step of a `component` job,\n * run once a member confirmed the job's plan.\n *\n * It builds ONE reusable component from the brief — its tree, and the typed\n * properties each page that places it fills in — through\n * `runValidatedGeneration('component', …)`, so every building rule holds on\n * the tree before it is kept. The tree binds each property with\n * `{{prop.<name>}}`; the palette validator keeps those tokens as written\n * (`definesComponent`), and the step's own check, through `extend`, holds\n * each binding to what the Properties dialog and the Attributes panel allow\n * (`ai-job-component-checks.ts`).\n *\n * The component lands as a new draft (`ai-job-drafts.ts`) that no page\n * places, and gets its first version when a member opens it, as every\n * component created outside the besigner does. A plan that starts from a copy\n * of a component the site has gets that copy, through the platform's\n * duplicate module, and nothing generated.\n *\n * A generation step runs on the job beat, never at an inline door: it\n * registers the least time its lookup rounds, its answer and its re-ask need\n * (AGL-3035), runs without extended thinking, and asks for no more of the\n * ceiling the layout and template steps keep than fits that time on the model\n * it runs. The step's spec measures the request and the answer against it.\n */\n\n/** The longest answer a component may run to; the tree is held to the component budget either way. */\nexport const AI_JOB_COMPONENT_MAX_TOKENS = AI_ROUTING_TABLE['job.component'].maxTokens\n\n/**\n * The component step's time (AGL-3035, AGL-3036): its two inventory-lookup\n * rounds, its answer and its re-ask at the routing table's ceiling on the tier\n * `job.component` is served from, fitted to what a beat can give a step.\n */\nexport const AI_JOB_COMPONENT_STEP_BUDGET = aiJobStepBudget({\n  tier: AI_STEP_TIERS['job.component'],\n  maxTokens: AI_JOB_COMPONENT_MAX_TOKENS,\n})\n\n/** The least time one component step needs before it starts. */\nexport const AI_JOB_COMPONENT_STEP_MINIMUM_MS = AI_JOB_COMPONENT_STEP_BUDGET.minimumMs\n\n/** A component's name when the plan names none. */\nexport const AI_JOB_COMPONENT_DEFAULT_NAME = 'Component'\n\n/** The component step's own instructions, cached after the doctrine and before the catalog. */\nexport const AI_JOB_COMPONENT_INSTRUCTIONS: readonly AiSystemBlock[] = [\n  {\n    text: [\n      `You build one reusable component for a website: a block the site places on many pages, each placement filling in its own values. Answer with ${AI_COMPONENT_TOOL_NAME}: the component’s tree as one flat node map, and the properties it declares.`,\n      'The root is the document wrapper holding the component. A component is placed inside a page section, which opens with its own h2: it carries no main landmark, its headings are h3 or below, and its colors, spacing and type come from the theme.',\n      'Every value that should differ from one placement to the next is a property, bound in the tree with its token {{prop.<name>}}. Declare every property the tree binds, and bind every property you declare.',\n      `Property kinds, as type (the name a page reads): ${aiComponentPropKindWords()}.`,\n      'A property binds only to a field that holds its kind of value:',\n      '- text, richText and number: copy, such as a Typography’s text, an Image’s alt or a Button’s label, as the whole value or inside a sentence.',\n      '- image: an Image’s src, as the whole value.',\n      '- href: a screenId or an href, as the whole value.',\n      '- icon: an Icon element’s iconId, as the whole value.',\n      '- boolean: a switch setting such as a Button’s fullWidth, or hideIf on the part it hides, as the whole value.',\n      '- choice: a setting with fixed options such as a Button’s variant, as the whole value, with every answer’s value one that setting lists.',\n      'An optional part, such as a photo, a badge or a second button, gets a boolean property labeled \"Hide <the part>\" whose default is \"false\", and the part’s own element carries \"hideIf\": \"{{prop.<name>}}\". Never hide the whole component.',\n      'A default is what the component shows until a page sets it: copy in the site’s voice from the brief, with a fact the brief does not give in square brackets; for href a screen id from the site inventory, or \"\"; for image \"\", for an upload; for icon \"\", for the site owner to pick; for choice one of its answers’ values.',\n    ].join('\\n'),\n  },\n]\n\n/** The component job as the generation's user turn: the name, the brief, the confirmed plan. */\nexport function aiJobComponentPrompt(\n  job: Pick<AiJob, 'brief'>,\n  plan: AiJobPlan | null,\n  name: string,\n): string {\n  return [`Component name: ${name}`, aiJobBriefLine(job), ...aiPlanReferenceLines(plan)].join('\\n')\n}\n\n/** A component job is admitted for a site of the job's own org whose plan includes reusable components. */\nexport const aiComponentJobAdmission: AiJobAdmission = (context) =>\n  aiDraftAdmissionRefusal(context.firestore, {\n    orgId: context.orgId,\n    hostId: context.hostId,\n    kind: 'component',\n    org: context.org,\n  })\n\nexport interface AiJobComponentStepDeps {\n  /** The inventory reader; specs hand in a fake. */\n  readInventory?: typeof readSiteInventory\n  /** The platform's duplicate module, for a plan that starts from a copy. */\n  duplicate?: typeof duplicateResource\n}\n\nexport function createAiJobComponentStep(deps: AiJobComponentStepDeps = {}): AiJobStepRunner {\n  const readInventory = deps.readInventory ?? readSiteInventory\n  const duplicate = deps.duplicate ?? duplicateResource\n  return async ({ job, now, signal, firestore, modelFor }) => {\n    const hostId = job.hostId\n    if (!hostId) throw new Error('a component job names no site, and its admission refuses one')\n    const output = (draft: AiDraftRecord, load?: AiLoadEstimate | null, note?: string | null): AiJobOutput => ({\n      resource: 'reusableComponent',\n      id: draft.id,\n      versionId: draft.versionId,\n      hostId,\n      hostSubdomain: draft.hostSubdomain,\n      label: draft.name,\n      ...(load ? { load } : {}),\n      ...(note ? { note } : {}),\n    })\n    // The switch's answer for this job, else the routing table's (AGL-2942).\n    const model = modelFor?.('job.component') ?? aiModelForStep('job.component')\n\n    // A run cut off after its draft was written reports that draft, found by the id the job recorded.\n    const draftId = aiJobDraftId(job, 'component')\n    const written = await readAiDraft(firestore, { kind: 'component', hostId, id: draftId })\n    if (written) return aiUnspentOutcome(model, { outputs: [output(written)] })\n\n    const [inventory, orgSnapshot] = await Promise.all([\n      readInventory(job.orgId, hostId, { firestore }),\n      firestore.collection('orgs').doc(job.orgId).get(),\n    ])\n    const org = (orgSnapshot.data() ?? null) as Partial<AglynOrgBilling> | null\n    const plan = aiConfirmedPlan(job)\n    const creation = aiPlanCreation(plan, 'component')\n    const name = creation?.name || AI_JOB_COMPONENT_DEFAULT_NAME\n\n    // The plan starts from a copy of a component the site has (rule 15): the\n    // copy is the draft, and nothing is generated. A source gone since the\n    // plan was made is built from the brief instead.\n    if (\n      creation?.duplicateOf &&\n      inventory.components.some((component) => component.id === creation.duplicateOf)\n    ) {\n      const copy = await duplicate('component', {\n        orgId: job.orgId,\n        hostId,\n        sourceId: creation.duplicateOf,\n        name,\n        uid: job.createdBy,\n        org: org as Record<string, unknown> | null,\n      })\n      if (copy.ok) {\n        const hostSubdomain = await aiSiteSubdomain(firestore, hostId)\n        return aiUnspentOutcome(model, {\n          outputs: [\n            output({ id: copy.id, versionId: copy.versionId ?? null, name: copy.name, hostSubdomain }),\n          ],\n        })\n      }\n      if (copy.ok === false && copy.status === 403) {\n        return aiUnspentOutcome(model, { review: aiLimitReview(copy.error) })\n      }\n    }\n\n    const allowance = await aiDraftAllowanceRefusal(firestore, { kind: 'component', hostId, org })\n    if (allowance) return aiUnspentOutcome(model, { review: aiLimitReview(allowance) })\n\n    let props: ReusableComponentProp[] = []\n    const result = await runValidatedGeneration('component', {\n      step: 'job.component',\n      model,\n      instructions: AI_JOB_COMPONENT_INSTRUCTIONS,\n      inventory,\n      messages: [{ role: 'user', content: aiJobComponentPrompt(job, plan, name) }],\n      tool: aiComponentTool(),\n      maxTokens: AI_JOB_COMPONENT_STEP_BUDGET.maxTokens(model),\n      ...(AI_ROUTING_TABLE['job.component'].thinking\n        ? { thinking: AI_ROUTING_TABLE['job.component'].thinking }\n        : {}),\n      ...(AI_ROUTING_TABLE['job.component'].effort\n        ? { effort: AI_ROUTING_TABLE['job.component'].effort }\n        : {}),\n      context: { definesComponent: true },\n      extend: aiComponentCheck({\n        inventory,\n        plan,\n        onProps: (declared) => {\n          props = declared\n        },\n      }),\n      ...(signal ? { signal } : {}),\n    })\n    const spent = aiGenerationSpent(result)\n    if (result.status === 'refused') return { ...spent, refused: true }\n    if (result.status === 'needs_input') return { ...spent, review: aiDoctrineReview(result) }\n\n    const draft = await writeAiDraft(firestore, {\n      kind: 'component',\n      hostId,\n      id: draftId,\n      uid: job.createdBy,\n      org,\n      name,\n      nodes: result.value.nodes,\n      rootId: result.value.rootId,\n      props,\n      now,\n    })\n    if (draft.ok === false) {\n      if (draft.status === 404) throw new Error(`site ${hostId} vanished while its component was generated`)\n      return { ...spent, review: aiLimitReview(draft.error) }\n    }\n    // The facts the brief did not give, in the tree or the defaults a page shows (AGL-3056).\n    const note = aiBracketedFactsNote({\n      tree: { rootId: result.value.rootId, nodes: result.value.nodes as unknown as AiDoctrineTree['nodes'] },\n      inventory,\n      copy: props.map((prop) => (typeof prop.defaultValue === 'string' ? prop.defaultValue : '')),\n    })\n    return { ...spent, outputs: [output(draft, result.value.load, note)] }\n  }\n}\n\nexport const runAiJobComponentStep = createAiJobComponentStep()\n\n/** Registers the component step and the check a component job passes before it is created or resumed. */\nexport function registerAiComponentJob(): void {\n  registerAiJobStep('component', runAiJobComponentStep, { minimumMs: AI_JOB_COMPONENT_STEP_MINIMUM_MS })\n  registerAiJobAdmission('component', aiComponentJobAdmission)\n}\n"],"names":["duplicateResource","AI_STEP_TIERS","AI_ROUTING_TABLE","aiModelForStep","runValidatedGeneration","readSiteInventory","AI_COMPONENT_TOOL_NAME","aiComponentPropKindWords","aiComponentTool","registerAiJobAdmission","aiJobStepBudget","aiComponentCheck","aiJobDraftId","aiDraftAdmissionRefusal","aiDraftAllowanceRefusal","aiSiteSubdomain","readAiDraft","writeAiDraft","aiBracketedFactsNote","aiConfirmedPlan","aiDoctrineReview","aiGenerationSpent","aiJobBriefLine","aiLimitReview","aiPlanCreation","aiPlanReferenceLines","aiUnspentOutcome","registerAiJobStep","AI_JOB_COMPONENT_MAX_TOKENS","maxTokens","AI_JOB_COMPONENT_STEP_BUDGET","tier","AI_JOB_COMPONENT_STEP_MINIMUM_MS","minimumMs","AI_JOB_COMPONENT_DEFAULT_NAME","AI_JOB_COMPONENT_INSTRUCTIONS","text","join","aiJobComponentPrompt","job","plan","name","aiComponentJobAdmission","context","firestore","orgId","hostId","kind","org","createAiJobComponentStep","deps","readInventory","duplicate","now","signal","modelFor","orgSnapshot","Error","output","draft","load","note","resource","id","versionId","hostSubdomain","label","model","draftId","written","outputs","inventory","Promise","all","collection","doc","get","data","creation","duplicateOf","components","some","component","copy","sourceId","uid","createdBy","ok","status","review","error","allowance","props","result","step","instructions","messages","role","content","tool","thinking","effort","definesComponent","extend","onProps","declared","spent","refused","nodes","value","rootId","tree","map","prop","defaultValue","runAiJobComponentStep","registerAiComponentJob"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAID,SAASA,iBAAiB,QAAQ,qDAAoD;AAEtF,SAASC,aAAa,QAAQ,0BAAsB;AACpD,SAASC,gBAAgB,EAAEC,cAAc,QAAQ,0BAAsB;AACvE,SAASC,sBAAsB,QAAQ,4BAAwB;AAI/D,SAASC,iBAAiB,QAAQ,+BAA2B;AAC7D,SACEC,sBAAsB,EACtBC,wBAAwB,EACxBC,eAAe,QACV,gCAA4B;AACnC,SAASC,sBAAsB,QAA6B,wBAAoB;AAChF,SAASC,eAAe,QAAQ,qBAAiB;AACjD,SAASC,gBAAgB,QAAQ,+BAA2B;AAC5D,SAASC,YAAY,QAAQ,wBAAoB;AACjD,SACEC,uBAAuB,EACvBC,uBAAuB,EACvBC,eAAe,EACfC,WAAW,EACXC,YAAY,QAEP,qBAAiB;AACxB,SACEC,oBAAoB,EACpBC,eAAe,EACfC,gBAAgB,EAChBC,iBAAiB,EACjBC,cAAc,EACdC,aAAa,EACbC,cAAc,EACdC,oBAAoB,EACpBC,gBAAgB,QACX,yBAAqB;AAE5B,SAASC,iBAAiB,QAAQ,eAAW;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GAED,oGAAoG,GACpG,OAAO,MAAMC,8BAA8B1B,gBAAgB,CAAC,gBAAgB,CAAC2B,SAAS,CAAA;AAEtF;;;;CAIC,GACD,OAAO,MAAMC,+BAA+BpB,gBAAgB;IAC1DqB,MAAM9B,aAAa,CAAC,gBAAgB;IACpC4B,WAAWD;AACb,GAAE;AAEF,8DAA8D,GAC9D,OAAO,MAAMI,mCAAmCF,6BAA6BG,SAAS,CAAA;AAEtF,iDAAiD,GACjD,OAAO,MAAMC,gCAAgC,YAAW;AAExD,6FAA6F,GAC7F,OAAO,MAAMC,gCAA0D;IACrE;QACEC,MAAM;YACJ,CAAC,6IAA6I,EAAE9B,uBAAuB,4EAA4E,CAAC;YACpP;YACA;YACA,CAAC,iDAAiD,EAAEC,2BAA2B,CAAC,CAAC;YACjF;YACA;YACA;YACA;YACA;YACA;YACA;YACA;YACA;SACD,CAAC8B,IAAI,CAAC;IACT;CACD,CAAA;AAED,8FAA8F,GAC9F,OAAO,SAASC,qBACdC,GAAyB,EACzBC,IAAsB,EACtBC,IAAY;IAEZ,OAAO;QAAC,CAAC,gBAAgB,EAAEA,MAAM;QAAEnB,eAAeiB;WAASd,qBAAqBe;KAAM,CAACH,IAAI,CAAC;AAC9F;AAEA,yGAAyG,GACzG,OAAO,MAAMK,0BAA0C,CAACC,UACtD9B,wBAAwB8B,QAAQC,SAAS,EAAE;QACzCC,OAAOF,QAAQE,KAAK;QACpBC,QAAQH,QAAQG,MAAM;QACtBC,MAAM;QACNC,KAAKL,QAAQK,GAAG;IAClB,GAAE;AASJ,OAAO,SAASC,yBAAyBC,OAA+B,CAAC,CAAC;QAClDA,qBACJA;IADlB,MAAMC,iBAAgBD,sBAAAA,KAAKC,aAAa,YAAlBD,sBAAsB7C;IAC5C,MAAM+C,aAAYF,kBAAAA,KAAKE,SAAS,YAAdF,kBAAkBlD;IACpC,OAAO,OAAO,EAAEuC,GAAG,EAAEc,GAAG,EAAEC,MAAM,EAAEV,SAAS,EAAEW,QAAQ,EAAE;kBAyBxCC;QAxBb,MAAMV,SAASP,IAAIO,MAAM;QACzB,IAAI,CAACA,QAAQ,MAAM,IAAIW,MAAM;QAC7B,MAAMC,SAAS,CAACC,OAAsBC,MAA8BC,OAAuC;gBACzGC,UAAU;gBACVC,IAAIJ,MAAMI,EAAE;gBACZC,WAAWL,MAAMK,SAAS;gBAC1BlB;gBACAmB,eAAeN,MAAMM,aAAa;gBAClCC,OAAOP,MAAMlB,IAAI;eACbmB,OAAO;gBAAEA;YAAK,IAAI,CAAC,GACnBC,OAAO;gBAAEA;YAAK,IAAI,CAAC;QAEzB,yEAAyE;QACzE,MAAMM,gBAAQZ,4BAAAA,SAAW,mCAAoBpD,eAAe;QAE5D,kGAAkG;QAClG,MAAMiE,UAAUxD,aAAa2B,KAAK;QAClC,MAAM8B,UAAU,MAAMrD,YAAY4B,WAAW;YAAEG,MAAM;YAAaD;YAAQiB,IAAIK;QAAQ;QACtF,IAAIC,SAAS,OAAO3C,iBAAiByC,OAAO;YAAEG,SAAS;gBAACZ,OAAOW;aAAS;QAAC;QAEzE,MAAM,CAACE,WAAWf,YAAY,GAAG,MAAMgB,QAAQC,GAAG,CAAC;YACjDtB,cAAcZ,IAAIM,KAAK,EAAEC,QAAQ;gBAAEF;YAAU;YAC7CA,UAAU8B,UAAU,CAAC,QAAQC,GAAG,CAACpC,IAAIM,KAAK,EAAE+B,GAAG;SAChD;QACD,MAAM5B,OAAOQ,oBAAAA,YAAYqB,IAAI,cAAhBrB,oBAAsB;QACnC,MAAMhB,OAAOrB,gBAAgBoB;QAC7B,MAAMuC,WAAWtD,eAAegB,MAAM;QACtC,MAAMC,OAAOqC,CAAAA,4BAAAA,SAAUrC,IAAI,KAAIP;QAE/B,yEAAyE;QACzE,uEAAuE;QACvE,iDAAiD;QACjD,IACE4C,CAAAA,4BAAAA,SAAUC,WAAW,KACrBR,UAAUS,UAAU,CAACC,IAAI,CAAC,CAACC,YAAcA,UAAUnB,EAAE,KAAKe,SAASC,WAAW,GAC9E;YACA,MAAMI,OAAO,MAAM/B,UAAU,aAAa;gBACxCP,OAAON,IAAIM,KAAK;gBAChBC;gBACAsC,UAAUN,SAASC,WAAW;gBAC9BtC;gBACA4C,KAAK9C,IAAI+C,SAAS;gBAClBtC,KAAKA;YACP;YACA,IAAImC,KAAKI,EAAE,EAAE;oBAI0BJ;gBAHrC,MAAMlB,gBAAgB,MAAMlD,gBAAgB6B,WAAWE;gBACvD,OAAOpB,iBAAiByC,OAAO;oBAC7BG,SAAS;wBACPZ,OAAO;4BAAEK,IAAIoB,KAAKpB,EAAE;4BAAEC,SAAS,GAAEmB,kBAAAA,KAAKnB,SAAS,YAAdmB,kBAAkB;4BAAM1C,MAAM0C,KAAK1C,IAAI;4BAAEwB;wBAAc;qBACzF;gBACH;YACF;YACA,IAAIkB,KAAKI,EAAE,KAAK,SAASJ,KAAKK,MAAM,KAAK,KAAK;gBAC5C,OAAO9D,iBAAiByC,OAAO;oBAAEsB,QAAQlE,cAAc4D,KAAKO,KAAK;gBAAE;YACrE;QACF;QAEA,MAAMC,YAAY,MAAM7E,wBAAwB8B,WAAW;YAAEG,MAAM;YAAaD;YAAQE;QAAI;QAC5F,IAAI2C,WAAW,OAAOjE,iBAAiByC,OAAO;YAAEsB,QAAQlE,cAAcoE;QAAW;QAEjF,IAAIC,QAAiC,EAAE;QACvC,MAAMC,SAAS,MAAMzF,uBAAuB,aAAa;YACvD0F,MAAM;YACN3B;YACA4B,cAAc5D;YACdoC;YACAyB,UAAU;gBAAC;oBAAEC,MAAM;oBAAQC,SAAS5D,qBAAqBC,KAAKC,MAAMC;gBAAM;aAAE;YAC5E0D,MAAM3F;YACNqB,WAAWC,6BAA6BD,SAAS,CAACsC;WAC9CjE,gBAAgB,CAAC,gBAAgB,CAACkG,QAAQ,GAC1C;YAAEA,UAAUlG,gBAAgB,CAAC,gBAAgB,CAACkG,QAAQ;QAAC,IACvD,CAAC,GACDlG,gBAAgB,CAAC,gBAAgB,CAACmG,MAAM,GACxC;YAAEA,QAAQnG,gBAAgB,CAAC,gBAAgB,CAACmG,MAAM;QAAC,IACnD,CAAC;YACL1D,SAAS;gBAAE2D,kBAAkB;YAAK;YAClCC,QAAQ5F,iBAAiB;gBACvB4D;gBACA/B;gBACAgE,SAAS,CAACC;oBACRb,QAAQa;gBACV;YACF;WACInD,SAAS;YAAEA;QAAO,IAAI,CAAC;QAE7B,MAAMoD,QAAQrF,kBAAkBwE;QAChC,IAAIA,OAAOL,MAAM,KAAK,WAAW,OAAO,aAAKkB;YAAOC,SAAS;;QAC7D,IAAId,OAAOL,MAAM,KAAK,eAAe,OAAO,aAAKkB;YAAOjB,QAAQrE,iBAAiByE;;QAEjF,MAAMlC,QAAQ,MAAM1C,aAAa2B,WAAW;YAC1CG,MAAM;YACND;YACAiB,IAAIK;YACJiB,KAAK9C,IAAI+C,SAAS;YAClBtC;YACAP;YACAmE,OAAOf,OAAOgB,KAAK,CAACD,KAAK;YACzBE,QAAQjB,OAAOgB,KAAK,CAACC,MAAM;YAC3BlB;YACAvC;QACF;QACA,IAAIM,MAAM4B,EAAE,KAAK,OAAO;YACtB,IAAI5B,MAAM6B,MAAM,KAAK,KAAK,MAAM,IAAI/B,MAAM,CAAC,KAAK,EAAEX,OAAO,2CAA2C,CAAC;YACrG,OAAO,aAAK4D;gBAAOjB,QAAQlE,cAAcoC,MAAM+B,KAAK;;QACtD;QACA,yFAAyF;QACzF,MAAM7B,OAAO3C,qBAAqB;YAChC6F,MAAM;gBAAED,QAAQjB,OAAOgB,KAAK,CAACC,MAAM;gBAAEF,OAAOf,OAAOgB,KAAK,CAACD,KAAK;YAAuC;YACrGrC;YACAY,MAAMS,MAAMoB,GAAG,CAAC,CAACC,OAAU,OAAOA,KAAKC,YAAY,KAAK,WAAWD,KAAKC,YAAY,GAAG;QACzF;QACA,OAAO,aAAKR;YAAOpC,SAAS;gBAACZ,OAAOC,OAAOkC,OAAOgB,KAAK,CAACjD,IAAI,EAAEC;aAAM;;IACtE;AACF;AAEA,OAAO,MAAMsD,wBAAwBlE,2BAA0B;AAE/D,uGAAuG,GACvG,OAAO,SAASmE;IACdzF,kBAAkB,aAAawF,uBAAuB;QAAElF,WAAWD;IAAiC;IACpGvB,uBAAuB,aAAaiC;AACtC"}

package/src/lib/jobs/ai-job-crm-step.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @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 AiCrmProposal, type AiCrmRecordKind, type AiCrmRecordProposal } from '../model/ai-crm';
+import type { AiTool } from '../providers/contract';
+import type { AiSystemBlock } from '../runtime/ai-runtime';
+import { type AiCrmImportField } from '../tools/ai-crm-tool';
+import { type AiCrmReaderLookup } from './ai-crm-access';
+import { type AiJobAdmission, type AiJobAdmissionRefusal } from './ai-job-admission';
+import type { AiJobStepRunner } from './ai-job-text-step';
+/**
+ * The `crm` step (AGL-2917): CRM by AI, as proposals.
+ *
+ * `inputs.task` says what the job is asked (`model/ai-crm.ts`):
+ *
+ * - `record` — one contact, company, deal or lead (`record`, `recordId`): a
+ *   summary, the next step as a task, a deal's stage, a lead's standing;
+ * - `email` — a draft for the CRM composer, from what the member asked for
+ *   (the brief) and the record's facts;
+ * - `mapping` — an import's columns (`collection`, `columns`) matched to the
+ *   fields the CRM's import fills.
+ *
+ * ## The CRM decides what is read
+ *
+ * The step never reads a CRM document. It asks the CRM's readers on the core's
+ * record-facts seam for the job's creator, and the CRM applies its own rules —
+ * the member's reach and `data.manage`, the plan, the record's visibility on
+ * the site — and reports the facts it chooses to. The admission below asks the
+ * same reader before the job exists, beside what an in-process call skips of
+ * the plugin API dispatcher: the CRM switched on and released where the job
+ * runs. A mapping sends the file's headers and each column's shape, never a
+ * cell.
+ *
+ * ## It writes no CRM record
+ *
+ * The CRM's task form, stage route, composer and import drawer are the
+ * writes, and a member makes each one. No email is sent by a job.
+ *
+ * ## The answer is kept apart from the job
+ *
+ * Every member of a workspace may read its jobs, and not every member may
+ * read every record. So a job's output names only the question — which
+ * record, which import — and the answer is kept at
+ * `orgs/{orgId}/aiCrmAnswers/{jobId}`, which no client may read, for two
+ * weeks (`AI_CRM_ANSWER_RETENTION_DAYS`). The answer door
+ * (`server/ai-crm-answer.ts`) serves it to a member the CRM still lets read
+ * the record, asking the same reader again.
+ *
+ * ## A summary is asked once per timeline
+ *
+ * A record answer is keyed on the whole request — the record, the site, the
+ * model, the rules, the tool and the facts as the CRM reported them — and a
+ * later job whose key matches a kept answer reuses it and spends nothing.
+ * The facts change exactly when something the model was told changes, so an
+ * unchanged record is never asked twice while its answer is kept.
+ */
+/**
+ * ASSUMED: the step's own round trips — the facts read (the record and its
+ * three windowed queries, in parallel), a record's reuse lookup, and the
+ * answer's write.
+ */
+export declare const AI_CRM_FACTS_READS_MS = 1500;
+/**
+ * The step's time (AGL-3035): one generation and its re-ask on the tier
+ * `job.crm` is served from, after the facts read, with no site inventory and
+ * so no lookup round. It fits an inline door's budget, so a member who asks on
+ * a record page is answered in the request.
+ */
+export declare const AI_JOB_CRM_STEP_BUDGET: import("./ai-job-budget").AiJobStepBudget;
+/** The least time one CRM step needs before it starts. */
+export declare const AI_JOB_CRM_STEP_MINIMUM_MS: number;
+/** Kept answers to one request a reuse lookup reads. */
+export declare const AI_CRM_REUSE_CANDIDATES = 20;
+/** How long a record answer stays reusable, beside its facts being unchanged: as long as it is kept. */
+export declare const AI_CRM_REUSE_WINDOW_MS: number;
+export declare const AI_CRM_FACTS_FAILURE_COPY = "The CRM record could not be read. Try again.";
+export declare const AI_CRM_KEEP_FAILURE_COPY = "The answer could not be kept. Try again.";
+/** The generation kinds the step asks under, which the doctrine states only its field rules to. */
+export declare const AI_CRM_GENERATION_KINDS: {
+    readonly record: "crm-record";
+    readonly email: "crm-email";
+    readonly mapping: "crm-mapping";
+};
+type Facts = Readonly<Record<string, unknown>>;
+/**
+ * The rules for a record of one kind. Each kind is sent the rules its tool can
+ * be refused for, and no others: on a model that caches no prompt this short,
+ * a rule a request cannot break is paid for on every request.
+ */
+export declare function aiCrmRecordInstructions(kind: AiCrmRecordKind): AiSystemBlock[];
+export declare const AI_CRM_EMAIL_INSTRUCTIONS: AiSystemBlock[];
+export declare const AI_CRM_MAPPING_INSTRUCTIONS: AiSystemBlock[];
+/**
+ * The facts as lines of text. Only the fields named here are written, whatever
+ * else a reader reports, so what reaches a prompt is decided in two places
+ * that both have to agree: the CRM's builders and this list.
+ */
+export declare function aiCrmFactsLines(kind: AiCrmRecordKind, facts: Facts): string[];
+/** The user turn for a record. */
+export declare function aiCrmRecordPrompt(kind: AiCrmRecordKind, facts: Facts): string;
+/** The user turn for an email draft. */
+export declare function aiCrmEmailPrompt(input: {
+    kind: AiCrmRecordKind;
+    facts: Facts;
+    request: string;
+}): string;
+/** The user turn for an import's columns. */
+export declare function aiCrmMappingPrompt(input: {
+    collection: string;
+    fields: readonly AiCrmImportField[];
+    columns: ReadonlyArray<{
+        header: string;
+        shape: string;
+    }>;
+}): string;
+/**
+ * A digest of the whole request a record answer is produced for. A hash of the
+ * request, never of the answer, and nothing of the facts is recoverable from
+ * it. The version tag strands every old key when what a key means changes.
+ */
+export declare function aiCrmRecordKey(input: {
+    kind: AiCrmRecordKind;
+    id: string;
+    hostId: string | null;
+    model: string;
+    prompt: string;
+    system: readonly AiSystemBlock[];
+    tool: AiTool;
+}): string;
+/** A kept answer about a record, as the reuse lookup reads it. */
+export interface AiCrmAnswerCandidate {
+    jobId: string;
+    hostId: string | null;
+    task: string;
+    key: string | null;
+    createdAtMs: number | null;
+    proposal: AiCrmProposal | null;
+}
+export type AiCrmAnswerFinder = (orgId: string, key: string, firestore?: FirebaseFirestore.Firestore) => Promise<AiCrmAnswerCandidate[]>;
+/**
+ * The finder the step uses in production: one equality on the request key
+ * inside the org's kept answers. Firestore's automatic single-field index
+ * answers it, so no composite index is deployed; the site and the window are
+ * applied in memory.
+ */
+export declare const findAiCrmAnswersByKey: AiCrmAnswerFinder;
+/** The newest answer another job kept for the same request, inside the window. */
+export declare function aiReusableCrmRecord(candidates: readonly AiCrmAnswerCandidate[], context: {
+    jobId: string;
+    hostId: string | null;
+    key: string;
+    now: Date;
+}): {
+    jobId: string;
+    proposal: AiCrmRecordProposal;
+} | null;
+export interface AiCrmAdmissionDeps {
+    readerFor?: AiCrmReaderLookup;
+    now?: () => Date;
+}
+/**
+ * Whether a `crm` job may start here for this member; `null` admits it: its
+ * inputs name a record or an import, and the CRM would let the member read it
+ * ({@link aiCrmAccessRefusal}). Asked at the create door before the job
+ * exists, so a refusal spends nothing. A door that names no member asks
+ * nothing of the reader.
+ */
+export declare function aiCrmAdmissionRefusal(context: Parameters<AiJobAdmission>[0], deps?: AiCrmAdmissionDeps): Promise<AiJobAdmissionRefusal | null>;
+export declare const aiCrmJobAdmission: AiJobAdmission;
+export interface AiJobCrmStepDeps {
+    readerFor?: AiCrmReaderLookup;
+    /** The reuse lookup; specs hand in a fake, and `null` turns reuse off. */
+    findAnswersByKey?: AiCrmAnswerFinder | null;
+}
+export declare function createAiJobCrmStep(deps?: AiJobCrmStepDeps): AiJobStepRunner;
+export declare const runAiJobCrmStep: AiJobStepRunner;
+/** Registers the CRM step and the check a `crm` job passes before it is created. */
+export declare function registerAiCrmJob(): void;
+export {};