@aglyn/plugins-ai 1.0.0-beta.228 → 1.0.0-beta.230

package/src/lib/jobs/ai-jobs.js

@@ -27,7 +27,6 @@ import { AI_JOB_PLAN_STEP, AI_JOB_TERMINAL_STATUSES } from "../model/ai-jobs.typ
 import { resolveEffectivePlan } from "@aglyn/aglyn/app-utils/plan-entitlements";
 import { aiOverageReservationRefusal } from "../billing/ai-overage-gate.js";
 import { aiAllotmentRefusalText } from "../model/ai-allotments.js";
-import { aiJobPlanCreditEstimate } from "../model/ai-site-job.js";
 import { AI_OFF_FOR_SITE_COPY, isAiOffForSite } from "../model/ai-site-switch.js";
 import { resolveAiModelChoice } from "../providers/model-choice.js";
 import { aiOutputTargetType } from "../activity/ai-activity-actions.js";
@@ -40,9 +39,12 @@ import { AI_JOB_TEXT_STEP_MINIMUM_MS, runAiJobTextStep } from "./ai-job-text-ste
 import { AI_JOB_SEO_STEP_MINIMUM_MS } from "./ai-job-seo-budget.js";
 import { AI_JOB_THEME_STEP_MINIMUM_MS } from "./ai-job-theme-budget.js";
 import { assistExchangeExpiry, assistUsageDay, assistUsageMonth, recordAssistCost, releaseAssistMessage, reserveAssistMessage } from "../usage/assist-usage.js";
-import { aiJobRefundCredits, refundJobCredits } from "../usage/assist-job-refund.js";
+import { aiJobItemRefundKey, aiJobRefundCredits, refundJobCredits } from "../usage/assist-job-refund.js";
+import { aiBuildSettlement, aiBuildUnits, aiBuildRetryLedger, aiBuildCreditEstimate, aiLedgerUnits, aiJobCreditEstimate } from "../model/ai-build-job.js";
 import { freeAssistAccount } from "../usage/assist-free-taste.js";
 import { aiJobAutoConfirms } from "./ai-job-auto-confirm.js";
+import { AI_SITE_GUIDED_BUILD_FAILED_COPY } from "../model/ai-job-failure-copy.js";
+import { aiSiteStartInputsOf } from "../model/ai-site-start.js";
 import { addAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit-write";
 /**
  * AI generation jobs — the Firestore state machine (AGL-2904).
@@ -151,7 +153,8 @@ export { AI_JOB_PLAN_STEP };
     'layout',
     'template',
     'form',
-    'email'
+    'email',
+    'build'
 ];
 const stepRunners = new Map();
 const stepMinimums = new Map();
@@ -426,12 +429,35 @@ export async function getAiJob(firestore, orgId, jobId) {
         ...options.statuses
     ]);
     else if (options.hostId) query = query.where('hostId', '==', options.hostId);
-    const snapshot = await query.orderBy('createdAt', 'desc').limit(limit).get();
-    return snapshot.docs.map((doc)=>jobFrom(doc)).filter((job)=>job !== null);
+    const read = async (from, count)=>(await from.orderBy('createdAt', 'desc').limit(count).get()).docs.map((doc)=>jobFrom(doc)).filter((job)=>job !== null);
+    try {
+        return await read(query, limit);
+    } catch (error) {
+        var _options_statuses1;
+        // A site's list while its (hostId, createdAt) index is still building
+        // (AGL-3596): Firestore refuses the query with FAILED_PRECONDITION until
+        // the index is ready, which answered the site's AI jobs page with a 500.
+        // The org's own newest jobs — the index every org list already uses —
+        // filtered to the site in memory stand in, bounded to
+        // `AI_JOBS_HOST_FALLBACK_SCAN` jobs, so a site whose jobs are older than
+        // that lists fewer until the index is ready rather than none.
+        if (!options.hostId || options.status || ((_options_statuses1 = options.statuses) == null ? void 0 : _options_statuses1.length) || !isFailedPrecondition(error)) throw error;
+        console.warn('ai jobs: host index not ready; listing from the org', {
+            orgId,
+            hostId: options.hostId
+        });
+        const recent = await read(jobsCollection(firestore, orgId), AI_JOBS_HOST_FALLBACK_SCAN);
+        return recent.filter((job)=>job.hostId === options.hostId).slice(0, limit);
+    }
+}
+/** The most of an org's newest jobs a site's list scans while its index builds (AGL-3596). */ export const AI_JOBS_HOST_FALLBACK_SCAN = 300;
+/** Firestore's "this query needs an index that is not ready" (gRPC 9). */ function isFailedPrecondition(error) {
+    const code = error == null ? void 0 : error.code;
+    return code === 9 || code === 'failed-precondition' || code === 'FAILED_PRECONDITION';
 }
 /** The wire form. `running` is the lease, read against `now`. */ export function aiJobSummary(job, now = new Date()) {
     var _job_hostId, _job_steps, _job_outputs, _job_creditsReserved, _job_creditsSpent, _job_refundedCredits, _toIso, _toIso1, _job_error, _job_plan_labels, _job_plan_confirmedBy, _job_review, _job_applied_versions, _job_applied_staged;
-    var _job_lease, _job_inputs;
+    var _job_lease, _job_inputs, _job_items, _job_inputs1;
     const leaseUntil = toMillis((_job_lease = job.lease) == null ? void 0 : _job_lease.until);
     return _extends({
         id: job.$id,
@@ -476,6 +502,14 @@ export async function getAiJob(firestore, orgId, jobId) {
         } : null
     }, job.sitePublish ? {
         sitePublish: job.sitePublish
+    } : {}, job.kind === 'site' ? {
+        siteInputs: aiSiteStartInputsOf(job.inputs)
+    } : {}, ((_job_items = job.items) == null ? void 0 : _job_items.length) ? {
+        items: job.items
+    } : {}, job.orchestration ? {
+        orchestration: job.orchestration
+    } : {}, job.kind === 'build' && ((_job_inputs1 = job.inputs) == null ? void 0 : _job_inputs1['publish']) === true ? {
+        publishAsked: true
     } : {});
 }
 function leaseIsLive(job, owner, nowMs) {
@@ -595,6 +629,38 @@ function nextStepIndex(job) {
         });
     });
 }
+/**
+ * A build's ledger with one pass applied (AGL-3616): the pass's credits on
+ * the item's row, its status, failure, note and outputs, and what was given
+ * back for it. Pure; the machine applies it inside `recordStep`.
+ */ export function aiApplyJobItemRecord(ledger, record, credits) {
+    return ledger.map((row)=>{
+        var _row_creditsSpent, _row_attemptCredits, _row_creditsRefunded, _record_creditsRefunded, _row_outputs, _record_outputs;
+        var _record_degradedBy;
+        return row.slot !== record.slot ? row : _extends({}, row, {
+            status: record.status,
+            creditsSpent: ((_row_creditsSpent = row.creditsSpent) != null ? _row_creditsSpent : 0) + credits,
+            attemptCredits: ((_row_attemptCredits = row.attemptCredits) != null ? _row_attemptCredits : 0) + credits,
+            creditsRefunded: ((_row_creditsRefunded = row.creditsRefunded) != null ? _row_creditsRefunded : 0) + ((_record_creditsRefunded = record.creditsRefunded) != null ? _record_creditsRefunded : 0)
+        }, record.refundKey ? {
+            refundKey: record.refundKey
+        } : {}, record.failure !== undefined ? {
+            failure: record.failure
+        } : {}, record.note !== undefined ? {
+            note: record.note
+        } : {}, ((_record_degradedBy = record.degradedBy) == null ? void 0 : _record_degradedBy.length) ? {
+            degradedBy: record.degradedBy
+        } : {}, {
+            outputs: [
+                ...(_row_outputs = row.outputs) != null ? _row_outputs : [],
+                ...((_record_outputs = record.outputs) != null ? _record_outputs : []).filter((id)=>{
+                    var _row_outputs;
+                    return !((_row_outputs = row.outputs) != null ? _row_outputs : []).includes(id);
+                })
+            ]
+        });
+    });
+}
 /**
  * The runs whose stop reasons a step's record keeps (AGL-3042), newest last.
  * A page job that builds a layout, a form and a component, then five sections
@@ -652,8 +718,8 @@ function nextStepIndex(job) {
  */ export async function recordStep(firestore, orgId, jobId, owner, stepIndex, input, now = new Date()) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
     const recorded = await firestore.runTransaction(async (tx)=>{
-        var _job_outputs, _input_outputs, _job_creditsSpent, _job_creditsReserved, _job_creditsReserved1;
-        var _job_lease;
+        var _ref, _input_items, _job_outputs, _input_outputs, _job_creditsSpent, _job_creditsReserved, _job_creditsReserved1, _job_refundedCredits;
+        var _job_lease, _input_item;
         const job = jobFrom(await tx.get(ref));
         if (!job) throw new Error(`ai job ${orgId}/${jobId} vanished`);
         const steps = job.steps.map((step, index)=>{
@@ -671,6 +737,9 @@ function nextStepIndex(job) {
             } : {}) : step;
         });
         const remaining = steps.filter((step)=>step.status === 'pending' || step.status === 'running').length;
+        // A build's item ledger moves with its spend, in this one write (AGL-3616).
+        const ledger = (_ref = (_input_items = input.items) != null ? _input_items : job.items) != null ? _ref : null;
+        const items = ledger && input.item ? aiApplyJobItemRecord(ledger, input.item, input.creditsSpent) : input.items ? ledger : null;
         const settled = input.status !== 'pending';
         const ownsLease = ((_job_lease = job.lease) == null ? void 0 : _job_lease.owner) === owner;
         const parksForReview = Boolean(input.review) && !isAiJobTerminal(job.status);
@@ -693,6 +762,10 @@ function nextStepIndex(job) {
             plan: input.plan
         } : {}, input.sitePublish ? {
             sitePublish: input.sitePublish
+        } : {}, items ? {
+            items
+        } : {}, ((_input_item = input.item) == null ? void 0 : _input_item.creditsRefunded) ? {
+            refundedCredits: ((_job_refundedCredits = job.refundedCredits) != null ? _job_refundedCredits : 0) + input.item.creditsRefunded
         } : {}, parksForReview && input.review ? {
             review: input.review,
             error: input.review.reason === 'plan' ? null : input.review.message
@@ -707,10 +780,11 @@ function nextStepIndex(job) {
             parked: parksForReview && job.status !== 'needs_review'
         };
     });
-    if (recorded.parked) await announceAiJobTransition(recorded.job, 'needs-review');
+    if (recorded.parked && !input.quiet) await announceAiJobTransition(recorded.job, 'needs-review');
     return {
         job: recorded.job,
-        remaining: recorded.remaining
+        remaining: recorded.remaining,
+        parked: recorded.parked
     };
 }
 async function transition(firestore, orgId, jobId, apply) {
@@ -868,6 +942,291 @@ async function transition(firestore, orgId, jobId, apply) {
         return job;
     }
 }
+/**
+ * A failure on our side, given back BEFORE the job is failed (AGL-3596): the
+ * failed state is the last one a follower of the job reads and the one its
+ * notice is written from, so it already carries `refundedCredits`. A job that
+ * ended meanwhile — a person's cancel, which pays for what ran — is left as it
+ * ended and given nothing back.
+ */ async function failOurFailure(firestore, orgId, jobId, message, detail, refund, now) {
+    var _current_items;
+    const current = await getAiJob(firestore, orgId, jobId);
+    // A build that got as far as its items settles item by item (AGL-3616):
+    // what it delivered stands, and what it did not is given back per item.
+    if (current && aiJobSettlesByItem(current.kind) && ((_current_items = current.items) == null ? void 0 : _current_items.length) && !isAiJobTerminal(current.status)) {
+        var _detail_stepIndex;
+        console.error('ai build stopped', {
+            orgId,
+            jobId,
+            stepIndex: (_detail_stepIndex = detail.stepIndex) != null ? _detail_stepIndex : null,
+            error: detail.error
+        });
+        return settleAiBuildJob(firestore, orgId, jobId, {
+            now,
+            free: refund.free,
+            stopped: {
+                message,
+                reason: refund.reason
+            }
+        });
+    }
+    if (current && !isAiJobTerminal(current.status)) {
+        await refundOurFailure(firestore, orgId, current, _extends({}, refund, {
+            now
+        }));
+    }
+    return failAiJob(firestore, orgId, jobId, message, detail, now);
+}
+// ── A build's settlement (AGL-3616) ──────────────────────────────────────
+/**
+ * The kinds settled item by item (AGL-3616): a build, and a site scaffold,
+ * which is the build's preset. Their step writes an item ledger; a failed
+ * item gives back its own spend and the rest goes on.
+ */ export function aiJobSettlesByItem(kind) {
+    return kind === 'build' || kind === 'site';
+}
+/**
+ * Whether Try again may run a job's failed items: a finished build, done or
+ * failed; a site scaffold that delivered part of its site — one that built
+ * nothing starts over from its own answers instead.
+ */ export function aiBuildRetryable(job) {
+    if (job.kind === 'build') return job.status === 'done' || job.status === 'failed';
+    return job.kind === 'site' && job.status === 'done';
+}
+/** What a build that delivered nothing says; its planning was given back too. */ export const AI_BUILD_NOTHING_BUILT_COPY = 'Nothing in this request could be built. Try again, or ask for less at once.';
+/** What an item the build never reached says when the build stopped early. */ export const AI_BUILD_NOT_REACHED_COPY = 'Not built: the build stopped before it reached this.';
+/**
+ * Gives back one build item's spend, or its planning's (`slot: 'plan'`),
+ * under the item key (job, slot, attempt), so a replayed pass gives back once
+ * and a later attempt is a give-back of its own. The credits given back and
+ * the key, or `null` when nothing was. Never throws.
+ */ async function refundBuildCredits(firestore, orgId, job, input) {
+    const credits = Math.max(0, Math.floor(input.credits));
+    if (credits <= 0) return null;
+    try {
+        var _data;
+        const free = input.free !== undefined ? input.free : freeAssistAccount((_data = (await firestore.collection('orgs').doc(orgId).get()).data()) != null ? _data : {});
+        const created = toMillis(job.createdAt);
+        const jobDay = assistUsageDay(created === null ? input.now : new Date(created));
+        const refund = await refundJobCredits(firestore, {
+            orgId,
+            free,
+            jobId: job.$id,
+            ordinal: 0,
+            credits,
+            month: assistUsageMonth(input.now),
+            day: assistUsageDay(input.now),
+            reason: input.reason,
+            item: {
+                slot: input.slot,
+                attempt: input.attempt,
+                jobDay
+            }
+        });
+        // A key the month already holds was given back by an earlier run of this pass.
+        if (refund.status !== 'returned' && refund.status !== 'duplicate') return null;
+        return {
+            credits,
+            key: aiJobItemRefundKey({
+                day: jobDay,
+                jobId: job.$id,
+                slot: input.slot,
+                attempt: input.attempt
+            })
+        };
+    } catch (error) {
+        console.error('ai build refund failed', {
+            orgId,
+            jobId: job.$id,
+            slot: input.slot,
+            error
+        });
+        return null;
+    }
+}
+/** What the build's plan step spent: its orchestration. */ function aiBuildPlanCredits(job) {
+    var _ref;
+    var _job_steps_find;
+    return (_ref = (_job_steps_find = job.steps.find((step)=>step.name === AI_JOB_PLAN_STEP)) == null ? void 0 : _job_steps_find.creditsSpent) != null ? _ref : 0;
+}
+/**
+ * Ends a build (AGL-3616), once nothing is left to build or the machine
+ * stopped it. A build that STOPPED — a provider failure, its attempts used up
+ * — fails the item it was on and gives back that attempt's spend, and leaves
+ * the items it never reached `skipped`. Then: anything delivered, and its
+ * planning is charged and the job is `done`, failed items and all; nothing
+ * delivered, and its planning is given back too and the job is `failed`.
+ */ export async function settleAiBuildJob(firestore, orgId, jobId, input) {
+    var _job_items, _job_items1, _job_items2, _ref, _ref1;
+    var _job_orchestration;
+    const { now } = input;
+    let job = await getAiJob(firestore, orgId, jobId);
+    if (!job || isAiJobTerminal(job.status)) return job;
+    const stopped = input.stopped;
+    if (stopped && ((_job_items = job.items) != null ? _job_items : []).some((row)=>row.status === 'pending' || row.status === 'running')) {
+        var _job_items3;
+        const refunds = new Map();
+        for (const row of (_job_items3 = job.items) != null ? _job_items3 : []){
+            var _row_attemptCredits;
+            if (row.status !== 'running') continue;
+            const refund = await refundBuildCredits(firestore, orgId, job, {
+                slot: row.slot,
+                attempt: row.attempt,
+                credits: (_row_attemptCredits = row.attemptCredits) != null ? _row_attemptCredits : 0,
+                reason: stopped.reason,
+                free: input.free,
+                now
+            });
+            if (refund) refunds.set(row.slot, refund);
+        }
+        job = (await transition(firestore, orgId, jobId, (current)=>{
+            var _current_items, _current_refundedCredits;
+            if (isAiJobTerminal(current.status)) return null;
+            let given = 0;
+            const items = ((_current_items = current.items) != null ? _current_items : []).map((row)=>{
+                if (row.status === 'running') {
+                    var _ref, _row_creditsRefunded, _ref1;
+                    const refund = refunds.get(row.slot);
+                    given += (_ref = refund == null ? void 0 : refund.credits) != null ? _ref : 0;
+                    return _extends({}, row, {
+                        status: 'failed',
+                        failure: {
+                            ours: true,
+                            reason: stopped.reason,
+                            message: stopped.message
+                        },
+                        creditsRefunded: ((_row_creditsRefunded = row.creditsRefunded) != null ? _row_creditsRefunded : 0) + ((_ref1 = refund == null ? void 0 : refund.credits) != null ? _ref1 : 0)
+                    }, refund ? {
+                        refundKey: refund.key
+                    } : {});
+                }
+                return row.status === 'pending' ? _extends({}, row, {
+                    status: 'skipped',
+                    note: AI_BUILD_NOT_REACHED_COPY
+                }) : row;
+            });
+            return {
+                items,
+                refundedCredits: ((_current_refundedCredits = current.refundedCredits) != null ? _current_refundedCredits : 0) + given,
+                updatedAt: now
+            };
+        })).job;
+    }
+    // A site is delivered when a page is (AGL-3616): a form alone is not a
+    // site. A scaffold that owed no page (a deployment without the page kind)
+    // is delivered by whatever it did build.
+    const sitePages = job.kind === 'site' ? ((_job_items1 = job.items) != null ? _job_items1 : []).filter((row)=>row.op === 'page') : [];
+    const delivered = sitePages.length ? sitePages.some((row)=>row.status === 'succeeded' || row.status === 'degraded') : aiBuildSettlement((_job_items2 = job.items) != null ? _job_items2 : []).delivered;
+    const planCredits = aiBuildPlanCredits(job);
+    if (delivered) {
+        await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
+                orchestration: {
+                    creditsSpent: planCredits,
+                    settled: 'charged'
+                },
+                updatedAt: now
+            });
+        return completeAiJob(firestore, orgId, jobId, now);
+    }
+    // A site that built no page gives back what its other parts cost too: it
+    // was not built, and its Try again starts over from its answers.
+    const parts = new Map();
+    if (job.kind === 'site') {
+        var _job_items4;
+        for (const row of (_job_items4 = job.items) != null ? _job_items4 : []){
+            var _row_creditsSpent, _row_creditsRefunded, _ref2;
+            const owed = Math.max(0, ((_row_creditsSpent = row.creditsSpent) != null ? _row_creditsSpent : 0) - ((_row_creditsRefunded = row.creditsRefunded) != null ? _row_creditsRefunded : 0));
+            if (owed <= 0 || row.status === 'failed') continue;
+            const given = await refundBuildCredits(firestore, orgId, job, {
+                slot: row.slot,
+                attempt: row.attempt,
+                credits: owed,
+                reason: (_ref2 = stopped == null ? void 0 : stopped.reason) != null ? _ref2 : 'step-failure',
+                free: input.free,
+                now
+            });
+            if (given) parts.set(row.slot, given);
+        }
+    }
+    const refund = ((_job_orchestration = job.orchestration) == null ? void 0 : _job_orchestration.settled) === 'refunded' ? null : await refundBuildCredits(firestore, orgId, job, {
+        slot: 'plan',
+        attempt: 1,
+        credits: planCredits,
+        reason: (_ref = stopped == null ? void 0 : stopped.reason) != null ? _ref : 'step-failure',
+        free: input.free,
+        now
+    });
+    await transition(firestore, orgId, jobId, (current)=>{
+        var _current_refundedCredits, _ref, _ref1, _current_items;
+        var _current_orchestration;
+        return isAiJobTerminal(current.status) ? null : _extends({
+            orchestration: {
+                creditsSpent: planCredits,
+                settled: refund || ((_current_orchestration = current.orchestration) == null ? void 0 : _current_orchestration.settled) === 'refunded' ? 'refunded' : 'charged'
+            }
+        }, refund || parts.size ? {
+            refundedCredits: ((_current_refundedCredits = current.refundedCredits) != null ? _current_refundedCredits : 0) + ((_ref = refund == null ? void 0 : refund.credits) != null ? _ref : 0) + [
+                ...parts.values()
+            ].reduce((total, part)=>total + part.credits, 0),
+            refundReason: (_ref1 = stopped == null ? void 0 : stopped.reason) != null ? _ref1 : 'step-failure'
+        } : {}, parts.size ? {
+            items: ((_current_items = current.items) != null ? _current_items : []).map((row)=>{
+                var _row_creditsRefunded;
+                const part = parts.get(row.slot);
+                return part ? _extends({}, row, {
+                    creditsRefunded: ((_row_creditsRefunded = row.creditsRefunded) != null ? _row_creditsRefunded : 0) + part.credits,
+                    refundKey: part.key
+                }) : row;
+            })
+        } : {}, {
+            updatedAt: now
+        });
+    });
+    const nothing = job.kind === 'site' ? AI_SITE_GUIDED_BUILD_FAILED_COPY : AI_BUILD_NOTHING_BUILT_COPY;
+    return failAiJob(firestore, orgId, jobId, (_ref1 = stopped == null ? void 0 : stopped.message) != null ? _ref1 : nothing, {
+        error: 'build delivered nothing'
+    }, now);
+}
+/**
+ * Try again on a build (AGL-3616): its failed items back to pending on their
+ * next attempt, with what they left unbuilt (`aiBuildRetryLedger`), and its
+ * generation step queued again. Never re-runs an item that succeeded, never
+ * re-asks the plan. Held at what the retried items are estimated to cost.
+ * `changed: false` for a job that is not a finished build, or has nothing to
+ * try again.
+ */ export async function retryAiBuildJob(firestore, orgId, jobId, now = new Date()) {
+    let retried = [];
+    const result = await transition(firestore, orgId, jobId, (current)=>{
+        var _current_plan, _current_items;
+        if (!aiBuildRetryable(current)) return null;
+        const plan = ((_current_plan = current.plan) == null ? void 0 : _current_plan.status) === 'confirmed' ? current.plan : null;
+        if (!plan || !((_current_items = current.items) == null ? void 0 : _current_items.length)) return null;
+        const next = aiBuildRetryLedger(current.items, current.kind === 'site' ? aiLedgerUnits(current.items) : aiBuildUnits(plan));
+        if (!next.ledger.some((row)=>row.status === 'pending')) return null;
+        retried = next.retried;
+        return {
+            status: 'queued',
+            items: next.ledger,
+            steps: current.steps.map((step)=>step.name === AI_JOB_PLAN_STEP ? step : _extends({}, step, {
+                    status: 'pending',
+                    attempts: 0,
+                    passes: 0,
+                    endedAt: null,
+                    error: null
+                })),
+            review: null,
+            error: null,
+            lease: null,
+            creditsReserved: Math.max(AI_JOB_STEP_RESERVE_CREDITS, current.kind === 'site' ? next.retried.length * AI_JOB_STEP_RESERVE_CREDITS : aiBuildCreditEstimate(plan, {
+                slots: new Set(next.retried)
+            })),
+            updatedAt: now
+        };
+    });
+    return _extends({}, result, {
+        retried: result.changed ? retried : []
+    });
+}
 /**
  * Resume a job that stopped for a person (AGL-2935): confirm its plan, or
  * try again the step whose answer broke a building rule. One transaction,
@@ -878,9 +1237,9 @@ async function transition(firestore, orgId, jobId, apply) {
  * it queues are held at the nominal figure again, which the park released —
  * and a confirmed plan is held at what the whole job is estimated to cost
  * (AGL-3031), creations included, where that is more.
- */ export async function resumeAiJob(firestore, orgId, jobId, actor, now = new Date()) {
+ */ export async function resumeAiJob(firestore, orgId, jobId, actor, now = new Date(), options = {}) {
     return transition(firestore, orgId, jobId, (current)=>{
-        var _current_review;
+        var _current_review, _current_inputs;
         if (current.status !== 'needs_review') return null;
         const steps = current.steps.map((step)=>step.status === 'pending' ? _extends({}, step, {
                 attempts: 0
@@ -895,13 +1254,18 @@ async function transition(firestore, orgId, jobId, apply) {
                 confirmedBy: actor.uid
             })
         } : {};
+        const publish = confirming && current.kind === 'build' && options.publishConfirmed && ((_current_inputs = current.inputs) == null ? void 0 : _current_inputs['publish']) === true ? {
+            inputs: _extends({}, current.inputs, {
+                publishConfirmed: true
+            })
+        } : {};
         return _extends({
             status: pending ? 'queued' : 'done',
             steps,
             review: null,
             error: null
-        }, confirmed, {
-            creditsReserved: pending ? Math.max(outstanding * AI_JOB_STEP_RESERVE_CREDITS, confirming ? aiJobPlanCreditEstimate(current.kind, confirming) : 0) : 0,
+        }, confirmed, publish, {
+            creditsReserved: pending ? Math.max(outstanding * AI_JOB_STEP_RESERVE_CREDITS, confirming ? aiJobCreditEstimate(current.kind, confirming) : 0) : 0,
             updatedAt: now
         });
     });
@@ -1005,7 +1369,7 @@ async function transition(firestore, orgId, jobId, apply) {
  * round.
  */ export async function runAiJobStep(firestore, orgId, jobId, options) {
     var _options_now, _step_attempts, _options_org, _data, _ref, _ref1, _outcome_effort, _step_passes, _options_actor;
-    var _reservation_allotment, _reservation_allotment1;
+    var _reservation_allotment, _reservation_allotment1, _outcome_review, _itemRecord_failure, _recorded_job_items;
     const now = (_options_now = options.now) != null ? _options_now : new Date();
     // A reservation the caller took before the job existed is a message
     // counted against the org; a step that fails before the provider is
@@ -1046,32 +1410,28 @@ async function transition(firestore, orgId, jobId, apply) {
     const runner = aiJobRunnerForStep(job.kind, step.name);
     if (!runner) {
         await releaseHeld();
-        const failed = await failAiJob(firestore, orgId, jobId, AI_JOB_NOT_AVAILABLE_COPY, {
-            stepIndex,
-            error: `no runner registered for kind ${job.kind}`
-        }, now);
         return {
             outcome: 'failed',
-            job: await refundOurFailure(firestore, orgId, failed, {
+            job: await failOurFailure(firestore, orgId, jobId, AI_JOB_NOT_AVAILABLE_COPY, {
+                stepIndex,
+                error: `no runner registered for kind ${job.kind}`
+            }, {
                 reason: 'unavailable',
-                stepCredits: 0,
-                now
-            })
+                stepCredits: 0
+            }, now)
         };
     }
     if (((_step_attempts = step.attempts) != null ? _step_attempts : 0) > AI_JOB_STEP_MAX_ATTEMPTS) {
         await releaseHeld();
-        const failed = await failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
-            stepIndex,
-            error: `step ${step.name} exhausted ${AI_JOB_STEP_MAX_ATTEMPTS} attempts`
-        }, now);
         return {
             outcome: 'failed',
-            job: await refundOurFailure(firestore, orgId, failed, {
+            job: await failOurFailure(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
+                stepIndex,
+                error: `step ${step.name} exhausted ${AI_JOB_STEP_MAX_ATTEMPTS} attempts`
+            }, {
                 reason: 'timeout',
-                stepCredits: 0,
-                now
-            })
+                stepCredits: 0
+            }, now)
         };
     }
     const org = (_options_org = options.org) != null ? _options_org : (_data = (await firestore.collection('orgs').doc(orgId).get()).data()) != null ? _data : {};
@@ -1197,18 +1557,16 @@ async function transition(firestore, orgId, jobId, apply) {
                 job: requeued
             };
         }
-        const failed = await failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
-            stepIndex,
-            error
-        }, now);
         return {
             outcome: 'failed',
-            job: await refundOurFailure(firestore, orgId, failed, {
+            job: await failOurFailure(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
+                stepIndex,
+                error
+            }, {
                 reason: 'provider',
                 stepCredits: 0,
-                free: (_reservation_free = reservation.free) != null ? _reservation_free : null,
-                now
-            })
+                free: (_reservation_free = reservation.free) != null ? _reservation_free : null
+            }, now)
         };
     }
     const latencyMs = Math.max(0, Date.now() - runStarted);
@@ -1228,18 +1586,16 @@ async function transition(firestore, orgId, jobId, apply) {
             creditsSpent: 0,
             error: outcome.failure
         }, now);
-        const failed = await failAiJob(firestore, orgId, jobId, outcome.failure, {
-            stepIndex,
-            error: `step failure before the provider: ${outcome.failure}`
-        }, now);
         return {
             outcome: 'failed',
-            job: await refundOurFailure(firestore, orgId, failed, {
+            job: await failOurFailure(firestore, orgId, jobId, outcome.failure, {
+                stepIndex,
+                error: `step failure before the provider: ${outcome.failure}`
+            }, {
                 reason: 'step-failure',
                 stepCredits: 0,
-                free: (_reservation_free1 = reservation.free) != null ? _reservation_free1 : null,
-                now
-            })
+                free: (_reservation_free1 = reservation.free) != null ? _reservation_free1 : null
+            }, now)
         };
     }
     const tokens = {
@@ -1303,19 +1659,45 @@ async function transition(firestore, orgId, jobId, apply) {
             error: message,
             tokens
         }, now);
-        const failed = await failAiJob(firestore, orgId, jobId, message, {
+        const detail = {
             stepIndex,
             error: outcome.refused ? 'stop_reason refusal' : `step failure: ${message}`
-        }, now);
+        };
         // A model declining the brief is not our failure; a step's own is (AGL-3594).
         return {
             outcome: 'failed',
-            job: outcome.refused ? failed : await refundOurFailure(firestore, orgId, failed, {
+            job: outcome.refused ? await failAiJob(firestore, orgId, jobId, message, detail, now) : await failOurFailure(firestore, orgId, jobId, message, detail, {
                 reason: 'step-failure',
                 stepCredits: credits,
-                free: (_reservation_free3 = reservation.free) != null ? _reservation_free3 : null,
-                now
-            })
+                free: (_reservation_free3 = reservation.free) != null ? _reservation_free3 : null
+            }, now)
+        };
+    }
+    // A guided site start whose step broke a building rule after its re-ask
+    // fails, given back whole (AGL-3596): the person never saw the plan, so a
+    // review asking them to look at it again is a review of nothing. The rule
+    // and its findings go to the log for staff; the person reads one sentence,
+    // and Try again starts a fresh job.
+    if (((_outcome_review = outcome.review) == null ? void 0 : _outcome_review.reason) === 'doctrine' && aiJobAutoConfirms(job) && step.name !== AI_JOB_PLAN_STEP) {
+        var _outcome_review_findings, _outcome_review_message, _reservation_free4;
+        await recordStep(firestore, orgId, jobId, options.owner, stepIndex, _extends({
+            status: 'failed',
+            creditsSpent: credits,
+            error: AI_SITE_GUIDED_BUILD_FAILED_COPY,
+            outputs: outcome.outputs
+        }, spentNothing ? {} : {
+            tokens
+        }), now);
+        return {
+            outcome: 'failed',
+            job: await failOurFailure(firestore, orgId, jobId, AI_SITE_GUIDED_BUILD_FAILED_COPY, {
+                stepIndex,
+                error: `doctrine refusal after the re-ask: ${JSON.stringify((_outcome_review_findings = outcome.review.findings) != null ? _outcome_review_findings : [])} ${(_outcome_review_message = outcome.review.message) != null ? _outcome_review_message : ''}`
+            }, {
+                reason: 'doctrine-refused',
+                stepCredits: credits,
+                free: (_reservation_free4 = reservation.free) != null ? _reservation_free4 : null
+            }, now)
         };
     }
     // A step that stopped for a person parks the job in the same write that
@@ -1329,6 +1711,26 @@ async function transition(firestore, orgId, jobId, apply) {
     // for a person never continues: the review is what it waits on. The pass
     // cap is what stops a runner that never finishes: past it the pass is
     // recorded as the step's last, and what it produced stands.
+    // A build item that failed on our side gives back its own attempt's spend
+    // before its row is written (AGL-3616), so the row records what was given.
+    let itemRecord = aiJobSettlesByItem(job.kind) ? outcome.item : undefined;
+    if ((itemRecord == null ? void 0 : itemRecord.status) === 'failed' && ((_itemRecord_failure = itemRecord.failure) == null ? void 0 : _itemRecord_failure.ours)) {
+        var _ref2, _outcome_items, _ref3, _ref4, _reservation_free5;
+        const slot = itemRecord.slot;
+        const row = ((_ref2 = (_outcome_items = outcome.items) != null ? _outcome_items : job.items) != null ? _ref2 : []).find((one)=>one.slot === slot);
+        const refund = await refundBuildCredits(firestore, orgId, job, {
+            slot,
+            attempt: (_ref3 = row == null ? void 0 : row.attempt) != null ? _ref3 : 1,
+            credits: ((_ref4 = row == null ? void 0 : row.attemptCredits) != null ? _ref4 : 0) + credits,
+            reason: itemRecord.failure.reason,
+            free: (_reservation_free5 = reservation.free) != null ? _reservation_free5 : null,
+            now
+        });
+        if (refund) itemRecord = _extends({}, itemRecord, {
+            creditsRefunded: refund.credits,
+            refundKey: refund.key
+        });
+    }
     const review = outcome.review;
     const continuing = !review && Boolean(outcome.continue) && ((_step_passes = step.passes) != null ? _step_passes : 0) + 1 < aiJobStepMaxPasses(job.kind);
     if (!review && outcome.continue && !continuing) {
@@ -1354,6 +1756,12 @@ async function transition(firestore, orgId, jobId, apply) {
         review
     } : {}, outcome.sitePublish ? {
         sitePublish: outcome.sitePublish
+    } : {}, aiJobSettlesByItem(job.kind) && outcome.items ? {
+        items: outcome.items
+    } : {}, itemRecord ? {
+        item: itemRecord
+    } : {}, review ? {
+        quiet: true
     } : {}), now);
     const actor = (_options_actor = options.actor) != null ? _options_actor : {
         uid: job.createdBy
@@ -1410,7 +1818,7 @@ async function transition(firestore, orgId, jobId, apply) {
         };
     }
     if (review && recorded.job.status === 'needs_review') {
-        var _reservation_free4;
+        var _reservation_free6;
         // Nobody parked the job but its own step, so the row names no actor, as
         // the meter's park does.
         await logAiJobNeedsInput(orgId, {
@@ -1420,15 +1828,22 @@ async function transition(firestore, orgId, jobId, apply) {
             kind: job.kind,
             reason: review.reason
         });
-        // A plan the plan rules still refused is our failure (AGL-3594).
+        // A plan the plan rules still refused, and a step that still broke a
+        // building rule after its re-ask, are our failures (AGL-3594, AGL-3596):
+        // given back before the person is told, so the notice can say so. Trying
+        // again spends anew, and a second refusal gives back again, within the
+        // day's bound.
+        const ours = outcome.uncredited ? 'plan-refused' : review.reason === 'doctrine' ? 'doctrine-refused' : null;
+        const parked = ours ? await refundOurFailure(firestore, orgId, recorded.job, {
+            reason: ours,
+            stepCredits: credits,
+            free: (_reservation_free6 = reservation.free) != null ? _reservation_free6 : null,
+            now
+        }) : recorded.job;
+        if (recorded.parked) await announceAiJobTransition(parked, 'needs-review');
         return {
             outcome: 'needs_review',
-            job: outcome.uncredited ? await refundOurFailure(firestore, orgId, recorded.job, {
-                reason: 'plan-refused',
-                stepCredits: credits,
-                free: (_reservation_free4 = reservation.free) != null ? _reservation_free4 : null,
-                now
-            }) : recorded.job
+            job: parked
         };
     }
     if (recorded.remaining > 0 || isAiJobTerminal(recorded.job.status)) {
@@ -1437,6 +1852,25 @@ async function transition(firestore, orgId, jobId, apply) {
             job: recorded.job
         };
     }
+    // A build ends by its items (AGL-3616): done when anything was delivered.
+    if (aiJobSettlesByItem(job.kind) && step.name !== AI_JOB_PLAN_STEP && ((_recorded_job_items = recorded.job.items) == null ? void 0 : _recorded_job_items.length)) {
+        var _recorded_job_items1, _reservation_free7;
+        // Items still open here are ones the pass cap cut off: the build stopped.
+        const open = aiBuildSettlement((_recorded_job_items1 = recorded.job.items) != null ? _recorded_job_items1 : []).open;
+        const settled = await settleAiBuildJob(firestore, orgId, jobId, _extends({
+            now,
+            free: (_reservation_free7 = reservation.free) != null ? _reservation_free7 : null
+        }, open ? {
+            stopped: {
+                message: AI_UPSTREAM_FAILURE_COPY,
+                reason: 'timeout'
+            }
+        } : {}));
+        return {
+            outcome: settled.status === 'failed' ? 'failed' : 'done',
+            job: settled
+        };
+    }
     return {
         outcome: 'done',
         job: await completeAiJob(firestore, orgId, jobId, now)