@aglyn/plugins-ai 1.0.0-beta.293 → 1.0.0

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

@@ -23,6 +23,8 @@ 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 { readAiSiteDatasets } from '../runtime/site-inventory';
+import { type AssistEditDataset, type AssistEditDatasetScope } from '../server/assist-edit';
 import { type AiJobAdmission } from './ai-job-admission';
 import { type AiJobStepRunner } from './ai-job-text-step';
 /**
@@ -39,13 +41,19 @@ import { type AiJobStepRunner } from './ai-job-text-step';
  *
  * ── 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.
+ * Never on a version a visitor sees. By default, on every plan, in the
+ * WORKING DRAFT of the version it started from (AGL-4116): the one document
+ * the Besigner saves to as an author works and offers with Open draft, which
+ * publishing moves into the version. The change is built on the draft the
+ * author already has, when the Besigner would still offer it, so their work
+ * in progress is never thrown away; otherwise on the version's own tree.
+ *
+ * Only when the request asks for a new version, and the plan keeps 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. Asked for without version
+ * history, the change goes into the draft and the output says why.
  *
  * ── What a job cannot do that the editor can ────────────────────────────
  *
@@ -59,8 +67,8 @@ import { type AiJobStepRunner } from './ai-job-text-step';
  *
  * 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.
+ * nothing. A draft the job writes is stamped 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;
@@ -76,11 +84,22 @@ export declare function aiJobEditModel(): string;
 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. */
+/**
+ * What the change is asked from: the document's outline, the site's datasets
+ * an element may show the records of (AGL-3616), then the request.
+ */
 export declare function aiJobEditPrompt(input: {
     brief: string;
     context: AssistEditCanvasContext;
+    datasets?: readonly AssistEditDataset[];
 }): string;
+/**
+ * The datasets an edit to this document knows (AGL-3616): every one the site
+ * holds, and the one whose record page the document is, if it is one.
+ */
+export declare function aiEditDatasetScope(datasets: ReadonlyArray<AssistEditDataset & {
+    recordScreenId?: string;
+}>, read: Pick<AiEditTargetRead, 'kind' | 'id'>): Required<AssistEditDatasetScope>;
 /** 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;
@@ -88,7 +107,7 @@ export declare function aiJobEditGeneration(request: {
     target: AssistEditTarget;
     model: string;
     signal?: AbortSignal;
-}): AiCustomGenerationInput<AssistEditProposal>;
+} & AssistEditDatasetScope): 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;
 /**
@@ -115,7 +134,16 @@ export interface AiEditTargetRead {
     pointerVersionId: string | null;
     /** The version the change starts from. */
     sourceVersionId: string;
+    /** The version's own tree. */
     nodes: NodesMap;
+    /**
+     * The version's working draft, when it has one the Besigner would still
+     * offer: an author's saved work in progress, which a change to the draft
+     * is built on. Null when there is none, or the version was saved since.
+     */
+    draft: {
+        nodes: NodesMap;
+    } | null;
     /** 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. */
@@ -152,14 +180,29 @@ export declare function aiEditPlacement(input: {
     sourceIsPointer: boolean;
     sourceScheduled: boolean;
 }): AiEditPlacement | 'refused';
+/**
+ * Where an edit job's change lands (AGL-4116): the version's working draft,
+ * unless the request asked for a new version and the plan keeps version
+ * history — then where {@link aiEditPlacement} puts a new one. Never refused:
+ * a draft is on every plan, and no visitor sees it.
+ */
+export declare function aiEditJobPlacement(input: {
+    newVersion: boolean;
+    versioning: boolean;
+    served: boolean;
+    sourceIsPointer: boolean;
+    sourceScheduled: boolean;
+}): AiEditPlacement;
 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. */
+    /** The new version's id, which is the job's; also the stamp a draft it writes carries. */
     jobVersionId: string;
     versioning: boolean;
+    /** The request asked for a new version (see {@link aiEditJobPlacement}). */
+    newVersion: boolean;
     proposal: AssistEditProposal;
     /** Whether the page's search fields may be written: a page no visitor reaches. */
     writeSeo: boolean;
@@ -189,12 +232,35 @@ export declare function writeAiEdit(firestore: Firestore, input: AiEditWriteInpu
 export interface AiJobEditStepDeps {
     readTarget?: typeof readAiEditTarget;
     writeEdit?: typeof writeAiEdit;
+    readDatasets?: typeof readAiSiteDatasets;
+    clearMirror?: typeof clearAiEditMirror;
 }
+/**
+ * Clears the co-edit mirror of the version whose draft a job just wrote
+ * (AGL-4116), as the Besigner's own Save draft does.
+ *
+ * The mirror holds unsaved canvas work and replays everything newer than the
+ * version's last save to whoever opens it. A draft write does not move the
+ * version's save, so without this the canvas of someone who had opened the
+ * older draft replays over the change the job just saved, and a room with
+ * replayed work offers no draft at all: the newer draft can only be reached by
+ * a Discard that deletes it. Best effort: a mirror that cannot be cleared
+ * leaves the draft saved, and the job reports what it wrote.
+ */
+export declare function clearAiEditMirror(input: {
+    orgId: string;
+    hostId: string;
+    kind: AiEditTargetKind;
+    id: string;
+    versionId: string;
+}): Promise<void>;
 /** 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;
+}, leftOut: readonly string[], options?: {
+    versionsUnavailable?: boolean;
+}): 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;
 /**
@@ -214,9 +280,9 @@ export interface AiEditJobAdmissionDeps {
     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.
+ * An edit job is admitted for a page or layout of a site of its own org that
+ * has a version to start from. Every plan has somewhere to put the change
+ * that no visitor sees — the version's draft — so no plan is refused.
  */
 export declare function createAiEditJobAdmission(deps?: AiEditJobAdmissionDeps): AiJobAdmission;
 export declare const aiEditJobAdmission: AiJobAdmission;