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

package/src/lib/jobs/ai-jobs.d.ts

@@ -200,15 +200,31 @@ export type AiJobPauseReader = (input: {
 export declare function registerAiJobPauseReader(reader: AiJobPauseReader | null): void;
 /**
  * A change a person is told about: the job's plan waits for them (or a step
- * stopped for their decision), the job finished, or it stopped.
+ * stopped for their decision), the job finished, it stopped, or it PAUSED
+ * because the meter refused its next step (AGL-3660) — out of credits, at a
+ * cap — which a person resolves by getting more and resuming the same job.
  */
-export type AiJobTransition = 'needs-review' | 'done' | 'failed';
+export type AiJobTransition = 'needs-review' | 'done' | 'failed' | 'paused';
+/**
+ * Why a job failed, for staff only (never shown to the customer): whether
+ * the failure was ours — a provider error, a step that produced nothing, a
+ * build that delivered nothing — rather than the model declining the brief
+ * or the site having AI switched off, and what the runner actually said.
+ */
+export interface AiJobFailureCause {
+    ours: boolean;
+    stepIndex: number | null;
+    error: string | null;
+}
 export type AiJobTransitionListener = (input: {
     job: AiJob;
     to: AiJobTransition;
+    /** Present on `failed` only. */
+    failure?: AiJobFailureCause;
 }) => Promise<void> | void;
 /**
- * The listener told each time a job ENTERS `needs_review`, `done` or `failed`
+ * The listener told each time a job ENTERS `needs_review`, `done` or `failed`,
+ * or is paused by the meter (`needs_input`, once per reason)
  * — once per entry, from the write that made it, so a stream that re-reads
  * the job or a beat that sees it again tells nobody twice. Registered by its
  * own module (`ai-jobs-notify.ts`) from the console's server surface, as the
@@ -418,6 +434,7 @@ export declare function completeAiJob(firestore: Firestore, orgId: string, jobId
 export declare function failAiJob(firestore: Firestore, orgId: string, jobId: string, message: string, detail?: {
     stepIndex?: number;
     error?: unknown;
+    ours?: boolean;
 }, now?: Date): Promise<AiJob>;
 /**
  * Park the job for something only the workspace can change. The running
@@ -487,7 +504,8 @@ export declare function retryAiBuildJob(firestore: Firestore, orgId: string, job
 }>;
 /**
  * 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,
+ * try again the step whose answer broke a building rule — or carry on a job
+ * the meter paused, from its paused step (AGL-3660). One transaction,
  * so two confirmations land once; anything but a `needs_review` job comes
  * back unchanged. The pending step's attempts start over — a person asking
  * again is not a provider failing again — and a confirmed plan with no step

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

@@ -242,7 +242,8 @@ let pauseReader = null;
 }
 let transitionListener = null;
 /**
- * The listener told each time a job ENTERS `needs_review`, `done` or `failed`
+ * The listener told each time a job ENTERS `needs_review`, `done` or `failed`,
+ * or is paused by the meter (`needs_input`, once per reason)
  * — once per entry, from the write that made it, so a stream that re-reads
  * the job or a beat that sees it again tells nobody twice. Registered by its
  * own module (`ai-jobs-notify.ts`) from the console's server surface, as the
@@ -254,10 +255,14 @@ let transitionListener = null;
 /** Whether a transition listener is registered: what a surface that runs jobs must have. */ export function aiJobTransitionListenerRegistered() {
     return transitionListener !== null;
 }
-/** Tells the listener; a listener that throws never fails the write it follows. */ async function announceAiJobTransition(job, to) {
+/** Tells the listener; a listener that throws never fails the write it follows. */ async function announceAiJobTransition(job, to, failure) {
     if (!transitionListener) return;
     try {
-        await transitionListener({
+        await transitionListener(failure ? {
+            job,
+            to,
+            failure
+        } : {
             job,
             to
         });
@@ -850,7 +855,14 @@ async function transition(firestore, orgId, jobId, apply) {
                 }) : step),
             updatedAt: now
         });
-    if (changed) await announceAiJobTransition(job, 'failed');
+    if (changed) {
+        var _ref2, _ref3;
+        await announceAiJobTransition(job, 'failed', {
+            ours: (_ref2 = detail == null ? void 0 : detail.ours) != null ? _ref2 : false,
+            stepIndex: (_ref3 = detail == null ? void 0 : detail.stepIndex) != null ? _ref3 : null,
+            error: (detail == null ? void 0 : detail.error) instanceof Error ? detail.error.message : (detail == null ? void 0 : detail.error) == null ? null : String(detail.error)
+        });
+    }
     return job;
 }
 /**
@@ -984,7 +996,9 @@ async function transition(firestore, orgId, jobId, apply) {
             now
         }));
     }
-    return failAiJob(firestore, orgId, jobId, message, detail, now);
+    return failAiJob(firestore, orgId, jobId, message, _extends({}, detail, {
+        ours: true
+    }), now);
 }
 // ── A build's settlement (AGL-3616) ──────────────────────────────────────
 /**
@@ -1066,16 +1080,16 @@ async function transition(firestore, orgId, jobId, apply) {
  * 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_items, _job_items1, _job_items2, _ref, _ref1, _job_items3;
     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;
+        var _job_items4;
         const refunds = new Map();
-        for (const row of (_job_items3 = job.items) != null ? _job_items3 : []){
+        for (const row of (_job_items4 = job.items) != null ? _job_items4 : []){
             var _row_attemptCredits;
             if (row.status !== 'running') continue;
             const refund = await refundBuildCredits(firestore, orgId, job, {
@@ -1141,8 +1155,8 @@ async function transition(firestore, orgId, jobId, apply) {
     // 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 _job_items5;
+        for (const row of (_job_items5 = job.items) != null ? _job_items5 : []){
             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;
@@ -1193,7 +1207,12 @@ async function transition(firestore, orgId, jobId, apply) {
     });
     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'
+        error: 'build delivered nothing',
+        // Ours unless every item that failed was the model declining (AGL-3616).
+        ours: Boolean(stopped) || ((_job_items3 = job.items) != null ? _job_items3 : []).some((row)=>{
+            var _row_failure;
+            return row.status === 'failed' && ((_row_failure = row.failure) == null ? void 0 : _row_failure.ours);
+        })
     }, now);
 }
 /**
@@ -1238,7 +1257,8 @@ async function transition(firestore, orgId, jobId, apply) {
 }
 /**
  * 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,
+ * try again the step whose answer broke a building rule — or carry on a job
+ * the meter paused, from its paused step (AGL-3660). One transaction,
  * so two confirmations land once; anything but a `needs_review` job comes
  * back unchanged. The pending step's attempts start over — a person asking
  * again is not a provider failing again — and a confirmed plan with no step
@@ -1249,6 +1269,18 @@ async function transition(firestore, orgId, jobId, apply) {
  */ export async function resumeAiJob(firestore, orgId, jobId, actor, now = new Date(), options = {}) {
     return transition(firestore, orgId, jobId, (current)=>{
         var _current_review, _current_inputs;
+        // A job the meter paused (AGL-3660) carries on from the step it paused
+        // on: that step is already pending, so it is queued again with nothing
+        // else changed. Whether the credits are there now is the reservation's
+        // to say, at the door and again at the step.
+        if (current.status === 'needs_input') {
+            return {
+                status: 'queued',
+                error: null,
+                lease: null,
+                updatedAt: now
+            };
+        }
         if (current.status !== 'needs_review') return null;
         const steps = current.steps.map((step)=>step.status === 'pending' ? _extends({}, step, {
                 attempts: 0
@@ -1510,6 +1542,9 @@ async function transition(firestore, orgId, jobId, apply) {
                 kind: job.kind,
                 reason: reservation.refusedBy
             });
+            // The person is told once per pause (AGL-3660), not once an hour: a
+            // job the beat re-queues and the meter refuses again keeps its reason.
+            await announceAiJobTransition(parked, 'paused');
         }
         return {
             outcome: 'needs_input',