@aglyn/plugins-ai 1.0.0-beta.225 → 1.0.0-beta.227

package/src/lib/jobs/ai-job-text-step.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-job-text-step.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types'\nimport type {\n  AiJob,\n  AiJobOutput,\n  AiJobPlan,\n  AiJobReview,\n} from '../model/ai-jobs.types'\nimport { AI_STEP_TIERS, type AiStepKind } from '../providers/catalog'\nimport { AI_ROUTING_TABLE, aiModelForStep } from '../providers/routing'\nimport { runAiRequest, type AiEffort, type AiSystemBlock } from '../runtime/ai-runtime'\nimport type { AssistTokenUsage } from '../usage/assist-usage'\nimport { aiJobStepBudget } from './ai-job-budget'\n\n/**\n * The `text` step (AGL-2904): a brief in, a short piece of copy out.\n *\n * The one step kind this issue ships for real, so the state machine — the\n * lease, the reservation, the record, the beat — is exercised end to end by\n * something that spends tokens, rather than by a stub that could pass with\n * the meter unplugged. Every other kind refuses until its own issue lands.\n *\n * The balanced tier with adaptive thinking: a brief is open-ended in a way the copy\n * assistant's element mode is not, and the cost is one call per job. The\n * static system block is cached; the brief rides in the user turn, so no\n * per-org byte sits inside the cached prefix (AGL-2352, enforced by the\n * runtime before the request leaves).\n */\n\n/** The model the text step runs on: the routing table's answer for `job.text`. */\nexport function aiJobTextModel(): string {\n  return aiModelForStep('job.text')\n}\n\n/** The text step's answer ceiling, from the routing table. */\nexport const AI_JOB_TEXT_MAX_TOKENS = AI_ROUTING_TABLE['job.text'].maxTokens\n\n/**\n * The text step's time (AGL-3035): ONE request — no re-ask, and no site\n * inventory to look anything up in — at the routing table's ceiling on the\n * tier `job.text` is served from, with the step's reads and writes. That fits\n * an inline door's budget, so a door runs a text job where it is asked for,\n * and the least time is the helper's worst case rather than a figure anyone\n * chose; a slower tier asks less so its worst case still fits.\n */\nexport const AI_JOB_TEXT_STEP_BUDGET = aiJobStepBudget({\n  tier: AI_STEP_TIERS['job.text'],\n  maxTokens: AI_JOB_TEXT_MAX_TOKENS,\n  attempts: 1,\n  lookups: 0,\n})\n\n/** The least time one text step needs before it starts. */\nexport const AI_JOB_TEXT_STEP_MINIMUM_MS = AI_JOB_TEXT_STEP_BUDGET.minimumMs\n\n/** How much of a brief is sent. Past this a brief is a document, not a brief. */\nexport const AI_JOB_BRIEF_MAX_CHARS = 4_000\n\n/**\n * What a step hands back to the machine. The machine meters `usage` at\n * `model`'s rates, records the step and appends the outputs; a step never\n * touches the job document or the meter itself.\n */\nexport interface AiJobStepOutcome {\n  outputs: AiJobOutput[]\n  /**\n   * The step made progress and has more of the same work to do (AGL-2910):\n   * a site audit works through its pages a batch at a time. The machine\n   * records this pass — its spend and its outputs — and hands the SAME step\n   * back to run again, so every pass is one reservation and one provider\n   * exchange, and the job document says how far it got.\n   */\n  continue?: boolean\n  usage: AssistTokenUsage\n  estCostUsd: number\n  model: string\n  stopReason: string | null\n  /**\n   * The thinking effort the request asked for, recorded on the step\n   * (AGL-2937); absent or `null` when the request named none.\n   */\n  effort?: AiEffort | null\n  /** The model declined the brief (`stop_reason: 'refusal'`). Tokens were spent. */\n  refused?: boolean\n  /**\n   * The model answered and nothing usable came of it — no structured answer\n   * even after the step's own re-ask, say (AGL-2938). Tokens were spent, so\n   * the machine meters the step before it fails the job with this sentence,\n   * which is customer-safe and the only thing a customer reads.\n   */\n  failure?: string\n  /** The plan the plan step proposed, which the machine keeps on the job (AGL-2935). */\n  plan?: AiJobPlan\n  /**\n   * The step stopped for a person (AGL-2935). The machine records what it\n   * spent and parks the job `needs_review`: a `plan` review completes the\n   * step, so confirming runs the next one; a `doctrine` review hands the\n   * step back, so trying again runs the same one.\n   */\n  review?: AiJobReview\n}\n\nexport interface AiJobStepContext {\n  job: AiJob\n  stepIndex: number\n  now: Date\n  /** Aborts the provider call when the runner's budget ends. */\n  signal?: AbortSignal\n  /**\n   * The Admin SDK handle the machine runs on, for a step that reads what it\n   * builds from — a site's theme, say — or writes a draft. A step never\n   * writes the job document, the meter or the lease through it.\n   */\n  firestore: FirebaseFirestore.Firestore\n  /** The org document the machine read for the step's reservation. */\n  org?: Partial<AglynOrgBilling> | null\n  /**\n   * The model a step of this kind runs on for THIS job (AGL-2942): the\n   * creator's pick where the plan and the allotment allowlists allow it,\n   * the routing table otherwise. Absent, a runner asks the table itself.\n   */\n  modelFor?: (kind: AiStepKind) => string | undefined\n}\n\nexport type AiJobStepRunner = (\n  context: AiJobStepContext,\n) => Promise<AiJobStepOutcome>\n\n/**\n * The static block, byte-identical on every request so it caches. The\n * customer's brief and the org's inputs never enter it.\n */\nexport const AI_JOB_TEXT_SYSTEM: AiSystemBlock[] = [\n  {\n    text:\n      'You write short, publishable copy for a website builder. You are ' +\n      'given a brief from the person who owns the site. Answer with the ' +\n      'copy only: no preamble, no headings unless the brief asks for them, ' +\n      'no closing remarks, no markdown fences. Keep to the length the brief ' +\n      'implies; when it implies none, write under 150 words. Write in the ' +\n      'language of the brief. Never invent facts, prices, names or claims ' +\n      'the brief did not give you; where a detail is missing, leave a ' +\n      'clearly marked placeholder in square brackets.',\n    cacheBreakpoint: true,\n  },\n]\n\n/** The brief as the user turn, with the kind-specific inputs stated plainly. */\nexport function aiJobTextPrompt(job: Pick<AiJob, 'brief' | 'inputs'>): string {\n  const brief = job.brief.slice(0, AI_JOB_BRIEF_MAX_CHARS)\n  const tone = typeof job.inputs?.['tone'] === 'string' ? job.inputs['tone'] : ''\n  const audience =\n    typeof job.inputs?.['audience'] === 'string' ? job.inputs['audience'] : ''\n  const lines = [`Brief: ${brief}`]\n  if (tone) lines.push(`Tone: ${tone}`)\n  if (audience) lines.push(`Audience: ${audience}`)\n  return lines.join('\\n')\n}\n\nexport const runAiJobTextStep: AiJobStepRunner = async ({ job, signal, modelFor }) => {\n  const model = modelFor?.('job.text') ?? aiJobTextModel()\n  const result = await runAiRequest({\n    model,\n    system: AI_JOB_TEXT_SYSTEM,\n    messages: [{ role: 'user', content: aiJobTextPrompt(job) }],\n    // The routing ceiling, lowered on a tier too slow to answer it inside the\n    // least time the step registered.\n    maxTokens: AI_JOB_TEXT_STEP_BUDGET.maxTokens(model),\n    ...(AI_ROUTING_TABLE['job.text'].thinking ? { thinking: AI_ROUTING_TABLE['job.text'].thinking } : {}),\n    ...(AI_ROUTING_TABLE['job.text'].effort ? { effort: AI_ROUTING_TABLE['job.text'].effort } : {}),\n    stream: false,\n    ...(signal ? { signal } : {}),\n  })\n  if (result.kind === 'refusal') {\n    return {\n      outputs: [],\n      usage: result.usage,\n      estCostUsd: result.estCostUsd,\n      model,\n      stopReason: result.stopReason,\n      refused: true,\n    }\n  }\n  const text = result.text.trim()\n  return {\n    outputs: text\n      ? [\n          {\n            resource: 'text',\n            // A text output has no document of its own; the id names the\n            // step within the job so a later step can address it.\n            id: 'draft',\n            hostId: job.hostId ?? null,\n            label: 'Draft copy',\n            text,\n          },\n        ]\n      : [],\n    usage: result.usage,\n    estCostUsd: result.estCostUsd,\n    model,\n    stopReason: result.stopReason,\n  }\n}\n"],"names":["AI_STEP_TIERS","AI_ROUTING_TABLE","aiModelForStep","runAiRequest","aiJobStepBudget","aiJobTextModel","AI_JOB_TEXT_MAX_TOKENS","maxTokens","AI_JOB_TEXT_STEP_BUDGET","tier","attempts","lookups","AI_JOB_TEXT_STEP_MINIMUM_MS","minimumMs","AI_JOB_BRIEF_MAX_CHARS","AI_JOB_TEXT_SYSTEM","text","cacheBreakpoint","aiJobTextPrompt","job","brief","slice","tone","inputs","audience","lines","push","join","runAiJobTextStep","signal","modelFor","model","result","system","messages","role","content","thinking","effort","stream","kind","outputs","usage","estCostUsd","stopReason","refused","trim","resource","id","hostId","label"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-job-text-step.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types'\nimport type {\n  AiJob,\n  AiJobOutput,\n  AiJobPlan,\n  AiJobReview,\n} from '../model/ai-jobs.types'\nimport { AI_STEP_TIERS, type AiStepKind } from '../providers/catalog'\nimport { AI_ROUTING_TABLE, aiModelForStep } from '../providers/routing'\nimport { runAiRequest, type AiEffort, type AiSystemBlock } from '../runtime/ai-runtime'\nimport type { AssistTokenUsage } from '../usage/assist-usage'\nimport { aiJobStepBudget } from './ai-job-budget'\n\n/**\n * The `text` step (AGL-2904): a brief in, a short piece of copy out.\n *\n * The one step kind this issue ships for real, so the state machine — the\n * lease, the reservation, the record, the beat — is exercised end to end by\n * something that spends tokens, rather than by a stub that could pass with\n * the meter unplugged. Every other kind refuses until its own issue lands.\n *\n * The balanced tier with adaptive thinking: a brief is open-ended in a way the copy\n * assistant's element mode is not, and the cost is one call per job. The\n * static system block is cached; the brief rides in the user turn, so no\n * per-org byte sits inside the cached prefix (AGL-2352, enforced by the\n * runtime before the request leaves).\n */\n\n/** The model the text step runs on: the routing table's answer for `job.text`. */\nexport function aiJobTextModel(): string {\n  return aiModelForStep('job.text')\n}\n\n/** The text step's answer ceiling, from the routing table. */\nexport const AI_JOB_TEXT_MAX_TOKENS = AI_ROUTING_TABLE['job.text'].maxTokens\n\n/**\n * The text step's time (AGL-3035): ONE request — no re-ask, and no site\n * inventory to look anything up in — at the routing table's ceiling on the\n * tier `job.text` is served from, with the step's reads and writes. That fits\n * an inline door's budget, so a door runs a text job where it is asked for,\n * and the least time is the helper's worst case rather than a figure anyone\n * chose; a slower tier asks less so its worst case still fits.\n */\nexport const AI_JOB_TEXT_STEP_BUDGET = aiJobStepBudget({\n  tier: AI_STEP_TIERS['job.text'],\n  maxTokens: AI_JOB_TEXT_MAX_TOKENS,\n  attempts: 1,\n  lookups: 0,\n})\n\n/** The least time one text step needs before it starts. */\nexport const AI_JOB_TEXT_STEP_MINIMUM_MS = AI_JOB_TEXT_STEP_BUDGET.minimumMs\n\n/** How much of a brief is sent. Past this a brief is a document, not a brief. */\nexport const AI_JOB_BRIEF_MAX_CHARS = 4_000\n\n/**\n * What a step hands back to the machine. The machine meters `usage` at\n * `model`'s rates, records the step and appends the outputs; a step never\n * touches the job document or the meter itself.\n */\nexport interface AiJobStepOutcome {\n  outputs: AiJobOutput[]\n  /**\n   * The step made progress and has more of the same work to do (AGL-2910):\n   * a site audit works through its pages a batch at a time. The machine\n   * records this pass — its spend and its outputs — and hands the SAME step\n   * back to run again, so every pass is one reservation and one provider\n   * exchange, and the job document says how far it got.\n   */\n  continue?: boolean\n  usage: AssistTokenUsage\n  estCostUsd: number\n  model: string\n  stopReason: string | null\n  /**\n   * The thinking effort the request asked for, recorded on the step\n   * (AGL-2937); absent or `null` when the request named none.\n   */\n  effort?: AiEffort | null\n  /** The model declined the brief (`stop_reason: 'refusal'`). Tokens were spent. */\n  refused?: boolean\n  /**\n   * The model answered and nothing usable came of it — no structured answer\n   * even after the step's own re-ask, say (AGL-2938). Tokens were spent, so\n   * the machine meters the step before it fails the job with this sentence,\n   * which is customer-safe and the only thing a customer reads.\n   */\n  failure?: string\n  /** The plan the plan step proposed, which the machine keeps on the job (AGL-2935). */\n  plan?: AiJobPlan\n  /**\n   * The step stopped for a person (AGL-2935). The machine records what it\n   * spent and parks the job `needs_review`: a `plan` review completes the\n   * step, so confirming runs the next one; a `doctrine` review hands the\n   * step back, so trying again runs the same one.\n   */\n  review?: AiJobReview\n  /**\n   * The answer was refused by the platform's own checks, not the model's\n   * (AGL-3594): the machine meters the step as any other and then gives the\n   * job's credits back to the meters it was charged to (`refundJobCredits`),\n   * a bounded number of times a day.\n   */\n  uncredited?: boolean\n}\n\nexport interface AiJobStepContext {\n  job: AiJob\n  stepIndex: number\n  now: Date\n  /** Aborts the provider call when the runner's budget ends. */\n  signal?: AbortSignal\n  /**\n   * The Admin SDK handle the machine runs on, for a step that reads what it\n   * builds from — a site's theme, say — or writes a draft. A step never\n   * writes the job document, the meter or the lease through it.\n   */\n  firestore: FirebaseFirestore.Firestore\n  /** The org document the machine read for the step's reservation. */\n  org?: Partial<AglynOrgBilling> | null\n  /**\n   * The model a step of this kind runs on for THIS job (AGL-2942): the\n   * creator's pick where the plan and the allotment allowlists allow it,\n   * the routing table otherwise. Absent, a runner asks the table itself.\n   */\n  modelFor?: (kind: AiStepKind) => string | undefined\n}\n\nexport type AiJobStepRunner = (\n  context: AiJobStepContext,\n) => Promise<AiJobStepOutcome>\n\n/**\n * The static block, byte-identical on every request so it caches. The\n * customer's brief and the org's inputs never enter it.\n */\nexport const AI_JOB_TEXT_SYSTEM: AiSystemBlock[] = [\n  {\n    text:\n      'You write short, publishable copy for a website builder. You are ' +\n      'given a brief from the person who owns the site. Answer with the ' +\n      'copy only: no preamble, no headings unless the brief asks for them, ' +\n      'no closing remarks, no markdown fences. Keep to the length the brief ' +\n      'implies; when it implies none, write under 150 words. Write in the ' +\n      'language of the brief. Never invent facts, prices, names or claims ' +\n      'the brief did not give you; where a detail is missing, leave a ' +\n      'clearly marked placeholder in square brackets.',\n    cacheBreakpoint: true,\n  },\n]\n\n/** The brief as the user turn, with the kind-specific inputs stated plainly. */\nexport function aiJobTextPrompt(job: Pick<AiJob, 'brief' | 'inputs'>): string {\n  const brief = job.brief.slice(0, AI_JOB_BRIEF_MAX_CHARS)\n  const tone = typeof job.inputs?.['tone'] === 'string' ? job.inputs['tone'] : ''\n  const audience =\n    typeof job.inputs?.['audience'] === 'string' ? job.inputs['audience'] : ''\n  const lines = [`Brief: ${brief}`]\n  if (tone) lines.push(`Tone: ${tone}`)\n  if (audience) lines.push(`Audience: ${audience}`)\n  return lines.join('\\n')\n}\n\nexport const runAiJobTextStep: AiJobStepRunner = async ({ job, signal, modelFor }) => {\n  const model = modelFor?.('job.text') ?? aiJobTextModel()\n  const result = await runAiRequest({\n    model,\n    system: AI_JOB_TEXT_SYSTEM,\n    messages: [{ role: 'user', content: aiJobTextPrompt(job) }],\n    // The routing ceiling, lowered on a tier too slow to answer it inside the\n    // least time the step registered.\n    maxTokens: AI_JOB_TEXT_STEP_BUDGET.maxTokens(model),\n    ...(AI_ROUTING_TABLE['job.text'].thinking ? { thinking: AI_ROUTING_TABLE['job.text'].thinking } : {}),\n    ...(AI_ROUTING_TABLE['job.text'].effort ? { effort: AI_ROUTING_TABLE['job.text'].effort } : {}),\n    stream: false,\n    ...(signal ? { signal } : {}),\n  })\n  if (result.kind === 'refusal') {\n    return {\n      outputs: [],\n      usage: result.usage,\n      estCostUsd: result.estCostUsd,\n      model,\n      stopReason: result.stopReason,\n      refused: true,\n    }\n  }\n  const text = result.text.trim()\n  return {\n    outputs: text\n      ? [\n          {\n            resource: 'text',\n            // A text output has no document of its own; the id names the\n            // step within the job so a later step can address it.\n            id: 'draft',\n            hostId: job.hostId ?? null,\n            label: 'Draft copy',\n            text,\n          },\n        ]\n      : [],\n    usage: result.usage,\n    estCostUsd: result.estCostUsd,\n    model,\n    stopReason: result.stopReason,\n  }\n}\n"],"names":["AI_STEP_TIERS","AI_ROUTING_TABLE","aiModelForStep","runAiRequest","aiJobStepBudget","aiJobTextModel","AI_JOB_TEXT_MAX_TOKENS","maxTokens","AI_JOB_TEXT_STEP_BUDGET","tier","attempts","lookups","AI_JOB_TEXT_STEP_MINIMUM_MS","minimumMs","AI_JOB_BRIEF_MAX_CHARS","AI_JOB_TEXT_SYSTEM","text","cacheBreakpoint","aiJobTextPrompt","job","brief","slice","tone","inputs","audience","lines","push","join","runAiJobTextStep","signal","modelFor","model","result","system","messages","role","content","thinking","effort","stream","kind","outputs","usage","estCostUsd","stopReason","refused","trim","resource","id","hostId","label"],"mappings":"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"}

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

@@ -0,0 +1,37 @@
+/**
+ * @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 { notifyUsers } from '@aglyn/tenant-data-admin/server/notifications';
+import { type AiJobTransitionListener } from './ai-jobs';
+/**
+ * The person who started an AI job is told when it needs them, when it
+ * finishes and when it stops (AGL-3593), through the console's notifications
+ * — the bell, and the generic notification email for a person who switched
+ * that channel on for the category. No other channel: there is no push.
+ *
+ * The machine calls this where the job's state changes, once per change
+ * (`registerAiJobTransitionListener`): the request that ran a step inline,
+ * or the beat that ran it with nobody watching — which is exactly when a
+ * person needs telling. The recipient is the job's creator, whose job it is
+ * and who alone confirms its plan; a teammate is not told about someone
+ * else's draft.
+ *
+ * `notifyUsers` never throws, and honors the person's per-category,
+ * per-workspace and per-site preferences.
+ */
+export declare function aiJobTransitionNotifier(notify?: typeof notifyUsers): AiJobTransitionListener;
+/** Registers the notifier the jobs machine tells about each change. */
+export declare function registerAiJobsNotify(): void;

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

@@ -0,0 +1,51 @@
+/**
+ * @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 { notifyUsers } from "@aglyn/tenant-data-admin/server/notifications";
+import { aiJobNotice } from "../model/ai-job-notice.js";
+import { aiJobAutoConfirms } from "./ai-job-auto-confirm.js";
+import { registerAiJobTransitionListener } from "./ai-jobs.js";
+/**
+ * The person who started an AI job is told when it needs them, when it
+ * finishes and when it stops (AGL-3593), through the console's notifications
+ * — the bell, and the generic notification email for a person who switched
+ * that channel on for the category. No other channel: there is no push.
+ *
+ * The machine calls this where the job's state changes, once per change
+ * (`registerAiJobTransitionListener`): the request that ran a step inline,
+ * or the beat that ran it with nobody watching — which is exactly when a
+ * person needs telling. The recipient is the job's creator, whose job it is
+ * and who alone confirms its plan; a teammate is not told about someone
+ * else's draft.
+ *
+ * `notifyUsers` never throws, and honors the person's per-category,
+ * per-workspace and per-site preferences.
+ */ export function aiJobTransitionNotifier(notify = notifyUsers) {
+    return async ({ job, to })=>{
+        var _job_review;
+        if (!job.createdBy) return;
+        // A guided site start's plan is confirmed for it the moment it is kept
+        // (AGL-3594): there is nothing for the person to confirm.
+        if (to === 'needs-review' && ((_job_review = job.review) == null ? void 0 : _job_review.reason) === 'plan' && aiJobAutoConfirms(job)) return;
+        await notify([
+            job.createdBy
+        ], aiJobNotice(job, to));
+    };
+}
+/** Registers the notifier the jobs machine tells about each change. */ export function registerAiJobsNotify() {
+    registerAiJobTransitionListener(aiJobTransitionNotifier());
+}
+
+//# sourceMappingURL=ai-jobs-notify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/jobs/ai-jobs-notify.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { notifyUsers } from '@aglyn/tenant-data-admin/server/notifications'\nimport { aiJobNotice } from '../model/ai-job-notice'\nimport { aiJobAutoConfirms } from './ai-job-auto-confirm'\nimport { registerAiJobTransitionListener, type AiJobTransitionListener } from './ai-jobs'\n\n/**\n * The person who started an AI job is told when it needs them, when it\n * finishes and when it stops (AGL-3593), through the console's notifications\n * — the bell, and the generic notification email for a person who switched\n * that channel on for the category. No other channel: there is no push.\n *\n * The machine calls this where the job's state changes, once per change\n * (`registerAiJobTransitionListener`): the request that ran a step inline,\n * or the beat that ran it with nobody watching — which is exactly when a\n * person needs telling. The recipient is the job's creator, whose job it is\n * and who alone confirms its plan; a teammate is not told about someone\n * else's draft.\n *\n * `notifyUsers` never throws, and honors the person's per-category,\n * per-workspace and per-site preferences.\n */\nexport function aiJobTransitionNotifier(\n  notify: typeof notifyUsers = notifyUsers,\n): AiJobTransitionListener {\n  return async ({ job, to }) => {\n    if (!job.createdBy) return\n    // A guided site start's plan is confirmed for it the moment it is kept\n    // (AGL-3594): there is nothing for the person to confirm.\n    if (to === 'needs-review' && job.review?.reason === 'plan' && aiJobAutoConfirms(job)) return\n    await notify([job.createdBy], aiJobNotice(job, to))\n  }\n}\n\n/** Registers the notifier the jobs machine tells about each change. */\nexport function registerAiJobsNotify(): void {\n  registerAiJobTransitionListener(aiJobTransitionNotifier())\n}\n"],"names":["notifyUsers","aiJobNotice","aiJobAutoConfirms","registerAiJobTransitionListener","aiJobTransitionNotifier","notify","job","to","createdBy","review","reason","registerAiJobsNotify"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,WAAW,QAAQ,gDAA+C;AAC3E,SAASC,WAAW,QAAQ,4BAAwB;AACpD,SAASC,iBAAiB,QAAQ,2BAAuB;AACzD,SAASC,+BAA+B,QAAsC,eAAW;AAEzF;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,wBACdC,SAA6BL,WAAW;IAExC,OAAO,OAAO,EAAEM,GAAG,EAAEC,EAAE,EAAE;YAIMD;QAH7B,IAAI,CAACA,IAAIE,SAAS,EAAE;QACpB,uEAAuE;QACvE,0DAA0D;QAC1D,IAAID,OAAO,kBAAkBD,EAAAA,cAAAA,IAAIG,MAAM,qBAAVH,YAAYI,MAAM,MAAK,UAAUR,kBAAkBI,MAAM;QACtF,MAAMD,OAAO;YAACC,IAAIE,SAAS;SAAC,EAAEP,YAAYK,KAAKC;IACjD;AACF;AAEA,qEAAqE,GACrE,OAAO,SAASI;IACdR,gCAAgCC;AAClC"}

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

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type AiJob, type AiJobApplied, type AiJobKind, type AiJobOutput, type AiJobPlan, type AiJobReview, type AiJobStatus, type AiJobStepTokens, type AiJobSummary } from '../model/ai-jobs.types';
+import { AI_JOB_PLAN_STEP, type AiJob, type AiJobApplied, type AiJobKind, type AiJobOutput, type AiJobPlan, type AiJobReview, type AiJobStatus, type AiJobStepTokens, type AiJobSummary } from '../model/ai-jobs.types';
 import type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types';
 import { type AiActivityActor } from '../activity/ai-activity';
 import { type AiEffort, type AiUsage } from '../runtime/ai-runtime';
@@ -107,8 +107,7 @@ export declare const AI_JOB_NOT_AVAILABLE_COPY = "This kind of AI job is not ava
 export declare const AI_JOB_REFUSED_COPY = "The model declined this brief. Try rephrasing it.";
 type Firestore = FirebaseFirestore.Firestore;
 export declare function isAiJobTerminal(status: AiJobStatus): boolean;
-/** The step a planned kind runs first (AGL-2935). */
-export declare const AI_JOB_PLAN_STEP = "plan";
+export { AI_JOB_PLAN_STEP };
 /**
  * The kinds that build site structure, and so plan before they generate
  * (AGL-2935): the plan their first step proposes is what their generation
@@ -196,6 +195,26 @@ export type AiJobPauseReader = (input: {
  * runs every job, as a process with no lockdown carrier would.
  */
 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.
+ */
+export type AiJobTransition = 'needs-review' | 'done' | 'failed';
+export type AiJobTransitionListener = (input: {
+    job: AiJob;
+    to: AiJobTransition;
+}) => Promise<void> | void;
+/**
+ * The listener told each time a job ENTERS `needs_review`, `done` or `failed`
+ * — 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
+ * pause reader is, so this machine never loads the notification fan-out.
+ * `null` unregisters it.
+ */
+export declare function registerAiJobTransitionListener(listener: AiJobTransitionListener | null): void;
+/** Whether a transition listener is registered: what a surface that runs jobs must have. */
+export declare function aiJobTransitionListenerRegistered(): boolean;
 /** Whether a pause reader is registered: what a surface that runs jobs must have. */
 export declare function aiJobPauseReaderRegistered(): boolean;
 /** The runner for one step of one job: the plan step by its name, else the kind's own. */
@@ -230,9 +249,17 @@ export declare function createAiJob(firestore: Firestore, input: CreateAiJobInpu
 export declare function getAiJob(firestore: Firestore, orgId: string, jobId: string): Promise<AiJob | null>;
 export interface ListAiJobsOptions {
     status?: AiJobStatus;
+    /**
+     * Any of these statuses (AGL-3593): the console's indicator asks for every
+     * job not yet settled in one read. Ignored when `status` is given.
+     */
+    statuses?: readonly AiJobStatus[];
     limit?: number;
 }
-/** Newest first. Needs the (status, createdAt) index when filtered. */
+/**
+ * Newest first. Needs the (status, createdAt) index when filtered, which
+ * answers an `in` over statuses as it answers one status.
+ */
 export declare function listAiJobs(firestore: Firestore, orgId: string, options?: ListAiJobsOptions): Promise<AiJob[]>;
 /** The wire form. `running` is the lease, read against `now`. */
 export declare function aiJobSummary(job: AiJob, now?: Date): AiJobSummary;

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

@@ -23,7 +23,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { createResourceUid } from "@aglyn/aglyn/app-utils/create-resource-uid";
 import { checkEntitlement } from "@aglyn/aglyn/server";
 import { assistCreditsFromUsd, assistFreeTasteRefusalText, assistHardCapRefusalText, assistRefusedByHardCap } from "../usage/assist-credits.js";
-import { AI_JOB_TERMINAL_STATUSES } from "../model/ai-jobs.types.js";
+import { AI_JOB_PLAN_STEP, AI_JOB_TERMINAL_STATUSES } from "../model/ai-jobs.types.js";
 import { resolveEffectivePlan } from "@aglyn/aglyn/app-utils/plan-entitlements";
 import { aiOverageReservationRefusal } from "../billing/ai-overage-gate.js";
 import { aiAllotmentRefusalText } from "../model/ai-allotments.js";
@@ -39,7 +39,10 @@ import { aiMintJobDraftIds } from "./ai-job-draft-ids.js";
 import { AI_JOB_TEXT_STEP_MINIMUM_MS, runAiJobTextStep } from "./ai-job-text-step.js";
 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, recordAssistCost, releaseAssistMessage, reserveAssistMessage } from "../usage/assist-usage.js";
+import { assistExchangeExpiry, assistUsageDay, assistUsageMonth, recordAssistCost, releaseAssistMessage, reserveAssistMessage } from "../usage/assist-usage.js";
+import { aiJobRefundCredits, refundJobCredits } from "../usage/assist-job-refund.js";
+import { freeAssistAccount } from "../usage/assist-free-taste.js";
+import { aiJobAutoConfirms } from "./ai-job-auto-confirm.js";
 import { addAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit-write";
 /**
  * AI generation jobs — the Firestore state machine (AGL-2904).
@@ -134,7 +137,9 @@ export function isAiJobTerminal(status) {
     return AI_JOB_TERMINAL_STATUSES.includes(status);
 }
 // ── The step runner registry ──────────────────────────────────────────────
-/** The step a planned kind runs first (AGL-2935). */ export const AI_JOB_PLAN_STEP = 'plan';
+// The step a planned kind runs first (AGL-2935), named in the model so the
+// console reads a job's phase off its steps without loading this machine.
+export { AI_JOB_PLAN_STEP };
 /**
  * The kinds that build site structure, and so plan before they generate
  * (AGL-2935): the plan their first step proposes is what their generation
@@ -232,6 +237,36 @@ let pauseReader = null;
  */ export function registerAiJobPauseReader(reader) {
     pauseReader = reader;
 }
+let transitionListener = null;
+/**
+ * The listener told each time a job ENTERS `needs_review`, `done` or `failed`
+ * — 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
+ * pause reader is, so this machine never loads the notification fan-out.
+ * `null` unregisters it.
+ */ export function registerAiJobTransitionListener(listener) {
+    transitionListener = listener;
+}
+/** 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) {
+    if (!transitionListener) return;
+    try {
+        await transitionListener({
+            job,
+            to
+        });
+    } catch (error) {
+        console.error('ai job transition listener failed', {
+            orgId: job.orgId,
+            jobId: job.$id,
+            to,
+            error
+        });
+    }
+}
 /** Whether a pause reader is registered: what a surface that runs jobs must have. */ export function aiJobPauseReaderRegistered() {
     return pauseReader !== null;
 }
@@ -378,16 +413,23 @@ function jobFrom(snapshot) {
 export async function getAiJob(firestore, orgId, jobId) {
     return jobFrom(await jobsCollection(firestore, orgId).doc(jobId).get());
 }
-/** Newest first. Needs the (status, createdAt) index when filtered. */ export async function listAiJobs(firestore, orgId, options = {}) {
+/**
+ * Newest first. Needs the (status, createdAt) index when filtered, which
+ * answers an `in` over statuses as it answers one status.
+ */ export async function listAiJobs(firestore, orgId, options = {}) {
     var _options_limit;
+    var _options_statuses;
     const limit = Math.min(Math.max(1, Math.floor((_options_limit = options.limit) != null ? _options_limit : 20)), 100);
     let query = jobsCollection(firestore, orgId);
     if (options.status) query = query.where('status', '==', options.status);
+    else if ((_options_statuses = options.statuses) == null ? void 0 : _options_statuses.length) query = query.where('status', 'in', [
+        ...options.statuses
+    ]);
     const snapshot = await query.orderBy('createdAt', 'desc').limit(limit).get();
     return snapshot.docs.map((doc)=>jobFrom(doc)).filter((job)=>job !== null);
 }
 /** 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, _toIso, _toIso1, _job_error, _job_plan_labels, _job_plan_confirmedBy, _job_review, _job_applied_versions, _job_applied_staged;
+    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;
     const leaseUntil = toMillis((_job_lease = job.lease) == null ? void 0 : _job_lease.until);
     return {
@@ -412,6 +454,7 @@ export async function getAiJob(firestore, orgId, jobId) {
         outputs: (_job_outputs = job.outputs) != null ? _job_outputs : [],
         creditsReserved: (_job_creditsReserved = job.creditsReserved) != null ? _job_creditsReserved : 0,
         creditsSpent: (_job_creditsSpent = job.creditsSpent) != null ? _job_creditsSpent : 0,
+        refundedCredits: (_job_refundedCredits = job.refundedCredits) != null ? _job_refundedCredits : 0,
         createdBy: job.createdBy,
         createdAt: (_toIso = toIso(job.createdAt)) != null ? _toIso : new Date(0).toISOString(),
         updatedAt: (_toIso1 = toIso(job.updatedAt)) != null ? _toIso1 : new Date(0).toISOString(),
@@ -605,7 +648,7 @@ function nextStepIndex(job) {
  * in the same transaction, so no beat can claim the next step in between.
  */ export async function recordStep(firestore, orgId, jobId, owner, stepIndex, input, now = new Date()) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
-    return firestore.runTransaction(async (tx)=>{
+    const recorded = await firestore.runTransaction(async (tx)=>{
         var _job_outputs, _input_outputs, _job_creditsSpent, _job_creditsReserved, _job_creditsReserved1;
         var _job_lease;
         const job = jobFrom(await tx.get(ref));
@@ -654,9 +697,16 @@ function nextStepIndex(job) {
         });
         return {
             job: _extends({}, job, patch),
-            remaining
+            remaining,
+            // Entered `needs_review` in this write, rather than parked again.
+            parked: parksForReview && job.status !== 'needs_review'
         };
     });
+    if (recorded.parked) await announceAiJobTransition(recorded.job, 'needs-review');
+    return {
+        job: recorded.job,
+        remaining: recorded.remaining
+    };
 }
 async function transition(firestore, orgId, jobId, apply) {
     const ref = jobsCollection(firestore, orgId).doc(jobId);
@@ -678,13 +728,14 @@ async function transition(firestore, orgId, jobId, apply) {
     });
 }
 /** Every step done: the job is `done` and holds nothing. */ export async function completeAiJob(firestore, orgId, jobId, now = new Date()) {
-    const { job } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
+    const { job, changed } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
             status: 'done',
             creditsReserved: 0,
             lease: null,
             error: null,
             updatedAt: now
         });
+    if (changed) await announceAiJobTransition(job, 'done');
     return job;
 }
 /**
@@ -699,7 +750,7 @@ async function transition(firestore, orgId, jobId, apply) {
         stepIndex: (_ref = detail == null ? void 0 : detail.stepIndex) != null ? _ref : null,
         error: (detail == null ? void 0 : detail.error) instanceof Error ? detail.error.message : (_ref1 = detail == null ? void 0 : detail.error) != null ? _ref1 : null
     });
-    const { job } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
+    const { job, changed } = await transition(firestore, orgId, jobId, (current)=>isAiJobTerminal(current.status) ? null : {
             status: 'failed',
             error: message,
             creditsReserved: 0,
@@ -711,6 +762,7 @@ async function transition(firestore, orgId, jobId, apply) {
                 }) : step),
             updatedAt: now
         });
+    if (changed) await announceAiJobTransition(job, 'failed');
     return job;
 }
 /**
@@ -760,6 +812,57 @@ async function transition(firestore, orgId, jobId, apply) {
     }
     return result;
 }
+/**
+ * Gives back what a job spent when it failed on our side (AGL-3594), and
+ * records the give-back on the job — `refundedCredits`, `refundReason` and
+ * the count its next key is numbered by. Everything the job spent and has not
+ * given back where it delivered nothing; the failing step's own spend where
+ * it delivered drafts, which it keeps. `assist-job-refund.ts` has the rule
+ * and the bound. Never throws: a give-back that cannot be made leaves the job
+ * as the failure left it, metered as every other step.
+ */ async function refundOurFailure(firestore, orgId, job, input) {
+    try {
+        var _job_outputs, _job_creditsSpent, _job_refundedCredits, _data, _job_refunds;
+        const delivered = ((_job_outputs = job.outputs) != null ? _job_outputs : []).some((output)=>output.resource !== 'seo');
+        const credits = aiJobRefundCredits({
+            delivered,
+            jobCredits: (_job_creditsSpent = job.creditsSpent) != null ? _job_creditsSpent : 0,
+            stepCredits: input.stepCredits,
+            alreadyRefunded: (_job_refundedCredits = job.refundedCredits) != null ? _job_refundedCredits : 0
+        });
+        if (credits <= 0) return job;
+        const free = input.free !== undefined ? input.free : freeAssistAccount((_data = (await firestore.collection('orgs').doc(orgId).get()).data()) != null ? _data : {});
+        const ordinal = (_job_refunds = job.refunds) != null ? _job_refunds : 0;
+        const refund = await refundJobCredits(firestore, {
+            orgId,
+            free,
+            jobId: job.$id,
+            ordinal,
+            credits,
+            month: assistUsageMonth(input.now),
+            day: assistUsageDay(input.now),
+            reason: input.reason
+        });
+        if (refund.status !== 'returned') return job;
+        const { job: refunded } = await transition(firestore, orgId, job.$id, (current)=>{
+            var _current_refundedCredits, _current_refunds;
+            return {
+                refundedCredits: ((_current_refundedCredits = current.refundedCredits) != null ? _current_refundedCredits : 0) + credits,
+                refundReason: input.reason,
+                refunds: ((_current_refunds = current.refunds) != null ? _current_refunds : 0) + 1,
+                updatedAt: input.now
+            };
+        });
+        return refunded;
+    } catch (error) {
+        console.error('ai job refund failed', {
+            orgId,
+            jobId: job.$id,
+            error
+        });
+        return 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,
@@ -938,22 +1041,32 @@ 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 failAiJob(firestore, orgId, jobId, AI_JOB_NOT_AVAILABLE_COPY, {
-                stepIndex,
-                error: `no runner registered for kind ${job.kind}`
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'unavailable',
+                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 failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
-                stepIndex,
-                error: `step ${step.name} exhausted ${AI_JOB_STEP_MAX_ATTEMPTS} attempts`
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'timeout',
+                stepCredits: 0,
+                now
+            })
         };
     }
     const org = (_options_org = options.org) != null ? _options_org : (_data = (await firestore.collection('orgs').doc(orgId).get()).data()) != null ? _data : {};
@@ -1058,6 +1171,7 @@ async function transition(firestore, orgId, jobId, apply) {
             modelFor
         });
     } catch (error) {
+        var _reservation_free;
         // The provider refused the request or the budget ended before it
         // answered: no usage came back, so nothing is metered and the message
         // goes back to the org. The provider's own words are already in the
@@ -1078,12 +1192,18 @@ 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 failAiJob(firestore, orgId, jobId, AI_UPSTREAM_FAILURE_COPY, {
-                stepIndex,
-                error
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'provider',
+                stepCredits: 0,
+                free: (_reservation_free = reservation.free) != null ? _reservation_free : null,
+                now
+            })
         };
     }
     const latencyMs = Math.max(0, Date.now() - runStarted);
@@ -1092,6 +1212,7 @@ async function transition(firestore, orgId, jobId, apply) {
     // back and nothing is metered, exactly as for a request the provider
     // refused.
     if (outcome.failure && aiJobStepSpentNothing(outcome)) {
+        var _reservation_free1;
         await releaseAssistMessage(firestore, orgId, reservation).catch((releaseError)=>console.error('ai job release failed', {
                 orgId,
                 jobId,
@@ -1102,12 +1223,18 @@ 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 failAiJob(firestore, orgId, jobId, outcome.failure, {
-                stepIndex,
-                error: `step failure before the provider: ${outcome.failure}`
-            }, now)
+            job: await refundOurFailure(firestore, orgId, failed, {
+                reason: 'step-failure',
+                stepCredits: 0,
+                free: (_reservation_free1 = reservation.free) != null ? _reservation_free1 : null,
+                now
+            })
         };
     }
     const tokens = {
@@ -1132,7 +1259,7 @@ async function transition(firestore, orgId, jobId, apply) {
         // Tokens were spent, so the bill is written first and its failure is a
         // log line, never a failed job — the same rule the chat route keeps.
         try {
-            var _job_hostId1, _reservation_free;
+            var _job_hostId1, _reservation_free2;
             await recordAssistCost(firestore, orgId, {
                 route: 'ai/jobs',
                 hostId: (_job_hostId1 = job.hostId) != null ? _job_hostId1 : null,
@@ -1145,7 +1272,7 @@ async function transition(firestore, orgId, jobId, apply) {
                 // The account this job drew on, as the reservation decided it
                 // (AGL-2925): a Free job lands on the owner's allowance and the
                 // platform's day; a paid one on neither.
-                free: (_reservation_free = reservation.free) != null ? _reservation_free : null,
+                free: (_reservation_free2 = reservation.free) != null ? _reservation_free2 : null,
                 // The step is the creator's spend, under the job's kind (AGL-2928).
                 uid: job.createdBy,
                 kind: job.kind
@@ -1163,6 +1290,7 @@ async function transition(firestore, orgId, jobId, apply) {
     // model's answer (AGL-2938), fails the job with its own sentence. The
     // tokens are already on the bill above.
     if (outcome.refused || outcome.failure) {
+        var _reservation_free3;
         const message = outcome.refused ? AI_JOB_REFUSED_COPY : outcome.failure;
         await recordStep(firestore, orgId, jobId, options.owner, stepIndex, {
             status: 'failed',
@@ -1170,12 +1298,19 @@ async function transition(firestore, orgId, jobId, apply) {
             error: message,
             tokens
         }, now);
+        const failed = await failAiJob(firestore, orgId, jobId, message, {
+            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: await failAiJob(firestore, orgId, jobId, message, {
-                stepIndex,
-                error: outcome.refused ? 'stop_reason refusal' : `step failure: ${message}`
-            }, now)
+            job: outcome.refused ? failed : await refundOurFailure(firestore, orgId, failed, {
+                reason: 'step-failure',
+                stepCredits: credits,
+                free: (_reservation_free3 = reservation.free) != null ? _reservation_free3 : null,
+                now
+            })
         };
     }
     // A step that stopped for a person parks the job in the same write that
@@ -1245,7 +1380,30 @@ async function transition(firestore, orgId, jobId, apply) {
             }
         });
     }
+    if ((review == null ? void 0 : review.reason) === 'plan' && recorded.job.status === 'needs_review' && aiJobAutoConfirms(job)) {
+        // A guided site start confirms its own plan (AGL-3594): the resume
+        // door's confirmation, by the job's creator, and the build queued.
+        const resumed = await resumeAiJob(firestore, orgId, jobId, {
+            uid: job.createdBy
+        }, now);
+        await writeAiJobAudit(firestore, {
+            action: 'ai.job.resume',
+            actorUid: job.createdBy,
+            orgId,
+            jobId,
+            after: {
+                status: resumed.job.status,
+                confirmedPlan: true,
+                autoConfirm: true
+            }
+        });
+        return {
+            outcome: 'done',
+            job: resumed.job
+        };
+    }
     if (review && recorded.job.status === 'needs_review') {
+        var _reservation_free4;
         // Nobody parked the job but its own step, so the row names no actor, as
         // the meter's park does.
         await logAiJobNeedsInput(orgId, {
@@ -1255,9 +1413,15 @@ 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).
         return {
             outcome: 'needs_review',
-            job: recorded.job
+            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
         };
     }
     if (recorded.remaining > 0 || isAiJobTerminal(recorded.job.status)) {