@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,198 @@
+/**
+ * @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 { duplicateResource } from '@aglyn/tenant-data-admin/server/duplicate-resource';
+import { type AiBuildPlanScreen } from '../model/ai-build-plan';
+import type { AiJob, AiJobPlan, AiJobReview } from '../model/ai-jobs.types';
+import { generateSeoFields } from '../runtime/seo-fields';
+import { readSiteInventory } from '../runtime/site-inventory';
+import { type AiJobAdmission } from './ai-job-admission';
+import { AI_JOB_PAGE_SECTION_MAX_TOKENS, AI_JOB_PAGE_SECTION_TOKENS, AI_JOB_PAGE_STEP_BUDGET, AI_JOB_PAGE_STEP_MINIMUM_MS, aiJobPageSectionMaxTokens } from './ai-job-page-budget';
+import { type AiSiteUnit } from './ai-job-site-step';
+import type { AiJobStepRunner } from './ai-job-text-step';
+import { aiJobStepRunnerFor } from './ai-jobs';
+/**
+ * The page step (AGL-2907): the generation step of a `page` job, run once a
+ * member confirmed the job's plan. It builds ONE screen, section by section,
+ * from what the site already has, and leaves it an unpublished draft.
+ *
+ * ── Why a page is built in passes ────────────────────────────────────────
+ *
+ * A page is far larger than one answer the job beat can wait for: the beat
+ * gives a step what is left of its budget, and a whole page, answered and re-asked,
+ * takes several times that. The confirmed plan already names the page's
+ * sections, so the step builds one section per pass and asks the machine to
+ * continue. Every pass is one reservation and one generation — the section's
+ * lookup rounds, its answer and, when it breaks a rule, its one re-ask — sized
+ * so that worst case fits `AI_JOB_PAGE_STEP_MINIMUM_MS`, which the step
+ * registers as the least time a section pass needs before it starts.
+ *
+ *  - The first pass builds the top section, which holds the page's h1, and
+ *    writes the draft screen and its first version.
+ *  - Each later pass builds the next section and adds it to that version.
+ *  - The last pass generates no tree: it holds the whole page to the
+ *    doctrine, writes the search title and description, and reports the
+ *    draft with its measured weight and a navigation proposal.
+ *
+ * How a section is asked for and held to the rules as part of the page is
+ * `ai-job-page-sections.ts`.
+ *
+ * ── What the plan creates comes first (AGL-3031) ─────────────────────────
+ *
+ * A plan that creates a layout, forms or components is built in the same job,
+ * before its page, one creation a pass, through the site scaffold's unit
+ * machinery: each creation is handed to the step that builds that kind, under
+ * a job derived from this one, and lands as the draft that step writes. Where
+ * the job stands is read from its outputs, so nothing is kept anywhere else.
+ * Once every creation is built, the page's passes run on the plan with each
+ * `new:<name>` resolved to the record that was built, which the site's
+ * inventory now lists — so the page places the new component and binds the new
+ * form by id, and renders inside the new layout, exactly as it would one the
+ * site always had. A pass that builds a creation needs the time the step that
+ * builds it registers, not a section's (`aiPageJobRunMinimumMs`, AGL-3035), so
+ * neither the beat nor a door starts it with only a section's time left.
+ *
+ * ── Never published ──────────────────────────────────────────────────────
+ *
+ * The draft is written the way `/api/hosts/resources` and
+ * `/api/hosts/versions` write a screen and its first version, and nothing
+ * else is touched: not the host document, whose routing map is what the live
+ * site serves, and no collection, store, layout or navigation pointer
+ * (`ai-job-drafts.ts`). A screen the routing map does not name serves nothing
+ * until a member publishes it.
+ */
+/**
+ * A section pass's time, and the ceiling each pass asks on each model, are
+ * declared apart from the step (`ai-job-page-budget.ts`): the site scaffold
+ * builds its pages through this step and reads them without loading it.
+ */
+export { AI_JOB_PAGE_SECTION_MAX_TOKENS, AI_JOB_PAGE_SECTION_TOKENS, AI_JOB_PAGE_STEP_BUDGET, AI_JOB_PAGE_STEP_MINIMUM_MS, aiJobPageSectionMaxTokens, };
+/**
+ * Tokens one element takes in a section's answer, ESTIMATED: the tree as JSON
+ * text inside the tool call, at four characters a token. Measured on the ten
+ * golden pages at a median of 38 and a most of 43 over their 39 sections, and
+ * `ai-job-page-evals.spec.ts` holds every golden section under it.
+ */
+export declare const AI_JOB_PAGE_TOKENS_PER_ELEMENT = 45;
+/**
+ * Real tokens to every token estimated at four characters (AGL-3042). A
+ * section's ceiling is counted by the provider in its own tokens, which run
+ * above that estimate. MEASURED on the first live document run on a Free
+ * workspace (AGL-3024, test-org, 2026-09-16), as the cache read of a request
+ * over the estimate of the same cached prefix: 4,059 over 2,825 for the page
+ * plan and 6,649 over 4,310 for the layout, the higher of the two, 1.5427 —
+ * the ratio `ai-job-free-page.spec.ts` prices a Free page at. It is measured on
+ * prompt text; an answer's own is read off a recorded pass, whose output
+ * tokens the step's record keeps (`lastRuns`), beside the section it stored.
+ */
+export declare const AI_JOB_PAGE_REAL_TOKENS_PER_ESTIMATED: number;
+/**
+ * Real tokens one element takes in a section's answer: the estimate at its
+ * golden most, in real tokens, rounded up — 45 × 1.5427 → 70 (AGL-3042).
+ */
+export declare const AI_JOB_PAGE_REAL_TOKENS_PER_ELEMENT: number;
+/**
+ * The most elements a section's request asks it to keep under at an answer
+ * ceiling: 15 at the balanced tier's 1,050 (AGL-3042). Counted in real
+ * tokens, because the ceiling is: counted in the estimate, the budget is 23
+ * elements, which a section of the goldens' largest elements fills at 1,597
+ * real tokens — half as much again as the ceiling that cuts it off.
+ */
+export declare function aiJobPageSectionMaxElements(maxTokens: number): number;
+/** A page's name when the plan names none. */
+export declare const AI_JOB_PAGE_DEFAULT_NAME = "New page";
+export declare const AI_JOB_PAGE_NO_PLAN_COPY = "This page job has no confirmed plan to build.";
+export declare const AI_JOB_PAGE_DELETED_COPY = "The draft page was deleted while it was being built.";
+/** A creation the plan names that this deployment has no step to build. */
+export declare const AI_JOB_PAGE_CREATION_UNAVAILABLE_COPY = "This page needs something that cannot be built here yet. Describe the page again.";
+/** A creation that finished without reporting what it built; the page cannot place it. */
+export declare const AI_JOB_PAGE_CREATION_EMPTY_COPY = "Part of this page could not be built. Describe the page again.";
+/**
+ * What a page refused on its last pass tells the member beside the rules it
+ * broke (AGL-3143). The draft is reported with the review, and mending what
+ * the findings name in it is what lets the next pass finish the job.
+ */
+export declare const AI_JOB_PAGE_REFUSED_DRAFT_COPY = "The draft is yours to open: mend what these name in it, then try again.";
+/**
+ * The most passes a page job may take (AGL-3031): every creation the plan
+ * limits admit, every section they admit, and the last pass that reports the
+ * draft. A creation's step builds it in one pass, and a page one section a
+ * pass, so a runner that never finishes is still bounded while a real page is
+ * not.
+ */
+export declare const AI_JOB_PAGE_MAX_PASSES: number;
+/**
+ * The units a plan's creations are built as, in the order a scaffold builds
+ * them: the layout, then the forms, then the components. Each is addressed by
+ * its place in the plan, so a unit run again finds its own draft.
+ */
+export declare function aiPageJobUnits(plan: Pick<AiJobPlan, 'create'>): AiSiteUnit[];
+/**
+ * The least time this page job's next pass needs (AGL-3035). A pass that
+ * builds a creation hands it to the step registered for that kind, under the
+ * job derived for it, so it needs what that step registers for that job — a
+ * layout's time, not a section's. Every other pass — a section, the last one —
+ * needs a section pass's.
+ */
+export declare function aiPageJobRunMinimumMs(job: AiJob): number;
+/** The one-segment address a draft asks for, from the plan's slug. */
+export declare function aiPageDraftSlug(screen: Pick<AiBuildPlanScreen, 'slug'>): string;
+/**
+ * The counts the confirmed plan's sections promised, against the page a COPY
+ * actually produced (AGL-3024); `null` when the copy keeps the plan, or when
+ * the plan promised no count to keep.
+ *
+ * The same hole the layout copy had (`aiCopiedLayoutReview`), on the kind the
+ * defect was measured on. This branch generates nothing, so no model ever
+ * answers for the plan: a plan reading "start from the Services page, one
+ * card per practice area" gets the Services page and whatever IT had, and
+ * until now reported `Done` — the one report that tells a customer there is
+ * no reason to re-read the page.
+ *
+ * A copy that cannot be read back settles nothing, and a promise this step
+ * cannot settle is reviewed by a person rather than reported as kept.
+ */
+export declare function aiCopiedPageReview(firestore: FirebaseFirestore.Firestore, input: {
+    hostId: string;
+    id: string;
+    name: string;
+    screen: Pick<AiBuildPlanScreen, 'sections'>;
+}): Promise<AiJobReview | null>;
+/**
+ * A page job is admitted with inputs that read, for a site of the job's own
+ * org with a screen to spare; and confirmed only for a plan it can build —
+ * one screen, whose creations are ones a page job builds, this deployment has
+ * a step for, and this workspace may still make on this site (AGL-3031).
+ */
+export declare const aiPageJobAdmission: AiJobAdmission;
+export interface AiJobPageStepDeps {
+    /** The inventory reader; specs hand in a fake. */
+    readInventory?: typeof readSiteInventory;
+    /** The platform's duplicate module, for a plan that starts from a copy. */
+    duplicate?: typeof duplicateResource;
+    /** The listing generator (AGL-2910). */
+    seoFields?: typeof generateSeoFields;
+    /** The runners a plan's creations are built by (AGL-3031); the registry's otherwise. */
+    runnerFor?: typeof aiJobStepRunnerFor;
+}
+export declare function createAiJobPageStep(deps?: AiJobPageStepDeps): AiJobStepRunner;
+export declare const runAiJobPageStep: AiJobStepRunner;
+/**
+ * Registers the page step with the least time a section pass needs and the
+ * time its next pass needs, the passes a page with its creations may take, and
+ * the check a page job passes when it is created or its plan is confirmed.
+ */
+export declare function registerAiPageJob(): void;