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

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

@@ -0,0 +1,225 @@
+/**
+ * @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 { SCREEN_SEO_TEXT_FIELDS } from '@aglyn/aglyn/app-utils/screen-seo-fields';
+import { CanvasManager } from '@aglyn/aglyn/canvas-manager/canvas-manager';
+import type { NodesMap } from '@aglyn/aglyn/types/nodes';
+import { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations';
+import { type AiEditJobInputs, type AiEditPlacement, type AiEditTargetKind } from '../model/ai-edit-job';
+import type { AiJob, AiJobOutput } from '../model/ai-jobs.types';
+import { type AssistEditCanvasContext, type AssistEditOp, type AssistEditProposal, type AssistEditTarget } from '../model/assist-edit';
+import { type AiCustomGenerationInput } from '../runtime/ai-doctrine';
+import type { AiSystemBlock } from '../runtime/ai-runtime';
+import { type AiJobAdmission } from './ai-job-admission';
+import { type AiJobStepRunner } from './ai-job-text-step';
+/**
+ * The `edit` step (AGL-3616): a change to a page or a layout the site already
+ * has, from a description, made on the server with no editor open.
+ *
+ * It is the Assist edit rung, run as a job. The model is shown the stored
+ * document as the rung's outline and proposes through the rung's own tool;
+ * its answer is held to the rung's closed world and palette validators
+ * (`checkAssistEditAnswer`) and re-asked once, naming what was left out; and
+ * what survives lands through the canvas's own guarded mutators
+ * (`applyAssistEdit`), on a `CanvasManager` built headless from the stored
+ * nodes, inside the transaction that writes it.
+ *
+ * ── Where the change lands, decided before anything is spent ────────────
+ *
+ * Never on a version a visitor sees. With version history, a NEW version
+ * beside the one it started from — a copy of that version's stored fields with
+ * the changed nodes — which becomes the page's current version only when the
+ * page is not published; a published page's current version, and a layout's,
+ * never move. Without it, in place, on a version no visitor reaches: an
+ * unpublished page's, or one that is not the current version and no schedule
+ * will publish. Anything else is refused as a plan limit, charged nothing.
+ *
+ * ── What a job cannot do that the editor can ────────────────────────────
+ *
+ * The rung's chat door never offers saving part of a page as a reusable
+ * component, and neither does this. A page's search title and description
+ * live on the page itself, not on a version, so they are written only for a
+ * page that is not published; on a published page they are left out, and the
+ * output's note says so, as it says every change it left out.
+ *
+ * ── One version per job ──────────────────────────────────────────────────
+ *
+ * The new version is named by the job's id — a build's unit is named by its
+ * plan item's id — so a run asked again finds what it wrote and spends
+ * nothing. A change made in place stamps the version with the job's id for
+ * the same reason.
+ */
+/** The longest the step may take reading the page and writing it. */
+export declare const AI_EDIT_READS_MS = 2000;
+/** The step's time: its answer and its re-ask at the `job.edit` ceiling, with its own reads. */
+export declare const AI_JOB_EDIT_STEP_BUDGET: import("./ai-job-budget").AiJobStepBudget;
+export declare const AI_JOB_EDIT_STEP_MINIMUM_MS: number;
+export declare function aiJobEditModel(): string;
+/**
+ * The job's own rules, byte-identical on every request, ahead of the rung's
+ * protocol and catalog for the document's kind, which carries the breakpoint:
+ * both are the same for every site, so a kind's whole prefix caches once.
+ */
+export declare const AI_JOB_EDIT_RULES: AiSystemBlock;
+/** The system blocks for one kind of document. */
+export declare function aiJobEditInstructions(kind: AiEditTargetKind): AiSystemBlock[];
+/** What the change is asked from: the document's outline, then the request. */
+export declare function aiJobEditPrompt(input: {
+    brief: string;
+    context: AssistEditCanvasContext;
+}): string;
+/** The edit as the doctrine's loop runs it: the rung's tool, held to the rung's check. */
+export declare function aiJobEditGeneration(request: {
+    brief: string;
+    context: AssistEditCanvasContext;
+    target: AssistEditTarget;
+    model: string;
+    signal?: AbortSignal;
+}): AiCustomGenerationInput<AssistEditProposal>;
+/** A canvas over a stored node map, with the editor's own guarded mutators and no editor. */
+export declare function aiEditCanvas(nodes: NodesMap): CanvasManager;
+/**
+ * Lands a proposal on a stored node map, as the editor lands one on its open
+ * canvas: checked whole first, then one batch, all or nothing. The session is
+ * the version being written, which is never one a visitor sees; a page's
+ * search fields are captured into `seo` only where `seo` is given.
+ */
+export declare function aiApplyEditToNodes(nodes: NodesMap, proposal: AssistEditProposal, seo?: Partial<Record<(typeof SCREEN_SEO_TEXT_FIELDS)[number], string>>): {
+    ok: true;
+    nodes: NodesMap;
+} | {
+    ok: false;
+    reason: string;
+};
+type Firestore = FirebaseFirestore.Firestore;
+/** The page or layout an edit job changes, as it stands before anything is spent. */
+export interface AiEditTargetRead {
+    kind: AiEditTargetKind;
+    id: string;
+    name: string;
+    hostSubdomain: string | null;
+    /** The document's current version. */
+    pointerVersionId: string | null;
+    /** The version the change starts from. */
+    sourceVersionId: string;
+    nodes: NodesMap;
+    /** Whether visitors see the document's current version: a published page, a collection template, any layout. */
+    served: boolean;
+    /** The version a pending publish schedule will make current, if any. */
+    scheduledVersionId: string | null;
+    /** What this job already wrote, when a run of it got that far. */
+    written: {
+        versionId: string;
+        placement: AiEditPlacement;
+    } | null;
+}
+export interface AiEditTargetRefusal {
+    status: 400 | 404;
+    error: string;
+}
+/**
+ * The document an edit job changes, on the job's own site: the page or
+ * layout named, not deleted, not an email design, and the version it starts
+ * from with a document in it. A refusal names what is wrong.
+ */
+export declare function readAiEditTarget(firestore: Firestore, input: {
+    orgId: string;
+    hostId: string;
+    inputs: AiEditJobInputs;
+    /** The job's own version id, to find what a run of it wrote; `null` at the door, before there is one. */
+    jobId: string | null;
+}): Promise<AiEditTargetRead | AiEditTargetRefusal>;
+/**
+ * Where a change may land (see the module head), or `refused` when the only
+ * place is a version visitors see and the plan keeps no version history.
+ */
+export declare function aiEditPlacement(input: {
+    versioning: boolean;
+    served: boolean;
+    sourceIsPointer: boolean;
+    sourceScheduled: boolean;
+}): AiEditPlacement | 'refused';
+export interface AiEditWriteInput {
+    hostId: string;
+    kind: AiEditTargetKind;
+    id: string;
+    sourceVersionId: string;
+    /** The new version's id, which is the job's; also the stamp a change in place carries. */
+    jobVersionId: string;
+    versioning: boolean;
+    proposal: AssistEditProposal;
+    /** Whether the page's search fields may be written: a page no visitor reaches. */
+    writeSeo: boolean;
+    versionName: string;
+    uid: string;
+    /** The job the member started, stamped as `aiJobId` on a new version. */
+    aiJobId: string;
+    now: Date;
+}
+export type AiEditWrite = {
+    ok: true;
+    versionId: string;
+    placement: AiEditPlacement;
+    seoWritten: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The change written, in one transaction that reads the document as it is
+ * stored NOW — a member may have saved, published or changed plan's history
+ * since the read — decides where it lands again on that, and applies the
+ * proposal to the stored nodes through the canvas's guards. An element that
+ * changed since the model saw it refuses the whole change, as the editor does.
+ */
+export declare function writeAiEdit(firestore: Firestore, input: AiEditWriteInput): Promise<AiEditWrite>;
+export interface AiJobEditStepDeps {
+    readTarget?: typeof readAiEditTarget;
+    writeEdit?: typeof writeAiEdit;
+}
+/** What an edit wrote, as the job's output: a link into the Besigner on the version written. */
+export declare function aiEditOutput(read: Pick<AiEditTargetRead, 'kind' | 'id' | 'name' | 'hostSubdomain'>, hostId: string, written: {
+    versionId: string;
+    placement: AiEditPlacement;
+}, leftOut: readonly string[]): AiJobOutput;
+/** The new version's id: the job's own, which a build's unit takes from its plan item. */
+export declare function aiEditVersionId(job: Pick<AiJob, '$id'>): string;
+/**
+ * The ops a job may save, and why it left the rest out: never a component
+ * save, and a page's search fields only where no visitor reaches the page.
+ */
+export declare function aiEditJobOps(ops: readonly AssistEditOp[], options: {
+    seo: boolean;
+}): {
+    ops: AssistEditOp[];
+    leftOut: string[];
+};
+export declare function createAiJobEditStep(deps?: AiJobEditStepDeps): AiJobStepRunner;
+export declare const runAiJobEditStep: AiJobStepRunner;
+export interface AiEditJobAdmissionDeps {
+    readTarget?: typeof readAiEditTarget;
+    ownerOf?: typeof resolveOrgIdForHost;
+}
+/**
+ * An edit job is admitted for a page or layout of a site of its own org,
+ * and only where the change has somewhere to land that no visitor sees on
+ * this workspace's plan — refused in the plan's words before anything exists.
+ */
+export declare function createAiEditJobAdmission(deps?: AiEditJobAdmissionDeps): AiJobAdmission;
+export declare const aiEditJobAdmission: AiJobAdmission;
+/** Registers the edit step and the check an edit job passes before it is created or resumed. */
+export declare function registerAiEditJob(): void;
+export {};