@avocadostudio-ai/orchestrator-core 0.24.0 → 0.25.0

package/dist/agents/fix-writer.d.ts

@@ -25,6 +25,12 @@ export type WriteFixResult = {
 export declare function currentValue(finding: Pick<FindingRecord, "ruleId" | "evidence">, page: PageDoc): string | undefined;
 /** The ops that put `text` in place — the same ops whether the text was written or edited. */
 export declare function fixOps(finding: Pick<FindingRecord, "ruleId" | "slug" | "evidence">, text: string): Operation[];
+/**
+ * Whether a fix can be written *and* applied for this finding: a fixable rule,
+ * and — for a field on a block — a path `fieldWriteOp` can express. Counting a
+ * finding as writable that approve would then fail on is the bug this exists for.
+ */
+export declare function canWriteFix(finding: Pick<FindingRecord, "ruleId" | "evidence">): boolean;
 /** What the page says, compactly: headings and the first sentences of its text, for the model to summarise. */
 export declare function pageDigest(page: PageDoc, maxChars?: number): string;
 /**

package/dist/agents/fix-writer.js

@@ -1,5 +1,6 @@
 import { buildBlockManifest } from "@avocadostudio-ai/shared";
 import { fieldText, walkPageFields } from "../checks/field-walk.js";
+import { fieldWriteOp, isWritablePath } from "../checks/field-ops.js";
 import { DESCRIPTION_MAX, DESCRIPTION_MIN, effectiveTitle, TITLE_MAX, TITLE_MIN } from "../checks/rules-draft.js";
 import { getAnthropicClient } from "../chat/anthropic-planner.js";
 import { defaultModelLookup } from "../chat/model-defaults.js";
@@ -43,12 +44,27 @@ export function fixOps(finding, text) {
         return [{ op: "update_page_meta", pageSlug: finding.slug, patch: { title: text } }];
     if (field === "description")
         return [{ op: "update_page_meta", pageSlug: finding.slug, patch: { description: text } }];
-    const { blockId, path } = finding.evidence ?? {};
+    const { blockId, path, itemId } = finding.evidence ?? {};
     if ((field === "alt" || field === "translation") && blockId && path) {
-        return [{ op: "update_props", pageSlug: finding.slug, blockId, patch: { [path]: text } }];
+        const op = fieldWriteOp({ pageSlug: finding.slug, blockId, path, value: text, ...(itemId ? { itemId } : {}) });
+        return op ? [op] : [];
     }
     return [];
 }
+/**
+ * Whether a fix can be written *and* applied for this finding: a fixable rule,
+ * and — for a field on a block — a path `fieldWriteOp` can express. Counting a
+ * finding as writable that approve would then fail on is the bug this exists for.
+ */
+export function canWriteFix(finding) {
+    const field = fixFieldFor(finding.ruleId);
+    if (!field)
+        return false;
+    if (field === "title" || field === "description")
+        return true;
+    const path = finding.evidence?.path;
+    return typeof path === "string" && isWritablePath(path);
+}
 /** What the page says, compactly: headings and the first sentences of its text, for the model to summarise. */
 export function pageDigest(page, maxChars = 2500) {
     const lines = [];
@@ -117,6 +133,8 @@ export async function writeFix(finding, page, deps = {}) {
     const field = fixFieldFor(finding.ruleId);
     if (!field)
         return { ok: false, error: "no fix can be written for this kind of finding" };
+    if (!canWriteFix(finding))
+        return { ok: false, error: "this field sits too deep in its block for a fix to be applied" };
     const base = currentValue(finding, page);
     if (base === undefined)
         return { ok: false, error: "the field this finding is about is no longer on the page" };

package/dist/agents/inbox.js

@@ -8,7 +8,7 @@ import { getSiteAssets } from "../state/site-assets.js";
 import { agentForRule } from "./builtins.js";
 import { isCustomAgentId } from "./spec.js";
 import { withoutPages } from "./edit-safety-resolve.js";
-import { currentValue, fixFieldFor, fixOps, writeFix } from "./fix-writer.js";
+import { canWriteFix, currentValue, fixOps, writeFix } from "./fix-writer.js";
 import { listSiteFacts, recordOutcome } from "./learning.js";
 import { resolveSiteAgents } from "./settings.js";
 import { siteOpsAgentsEnabled } from "./enabled.js";
@@ -68,7 +68,7 @@ export function groupFindings(findings, enabled) {
         const first = list[0];
         const slugs = [...new Set(list.map((f) => f.slug))];
         const fixable = list.filter((f) => (f.proposedOps?.length ?? 0) > 0 || (f.fix?.ops.length ?? 0) > 0).length;
-        const writable = list.filter((f) => fixFieldFor(f.ruleId) && !f.fix).length;
+        const writable = list.filter((f) => canWriteFix(f) && !f.fix).length;
         const agent = agentOfFinding(first);
         out.push({
             id: `findings:${ruleId}`,

package/dist/chat/chat-pipeline.js

@@ -64,6 +64,7 @@ import { validateAndStripHallucinatedProps } from "./hallucination-validator.js"
 import { validateChangelogCoverage } from "./changelog-coverage-validator.js";
 import { generateAltTextFromVision, parseAltPathForOp } from "./vision-alt-generator.js";
 import { checkEditSafety, pagesBefore, summarizeReport } from "../agents/edit-safety-runner.js";
+import { scheduleChecksAfterApply } from "../checks/session-runner.js";
 import { recordOutcome, siteFactsForPlanner } from "../agents/learning.js";
 /**
  * Whether the CURRENT message plausibly depends on prior conversation turns — an
@@ -3020,6 +3021,10 @@ export async function runChatPipeline(ctx, body, options) {
                     log: ctx.log
                 })
                 : null;
+            // A chat turn is the commonest way content changes, so it schedules
+            // checks the same way /ops does: debounced, in the background, and only
+            // when apply checks are on (CHECKS_ON_APPLY, or Site ops agents).
+            scheduleChecksAfterApply(body.session, ctx.log);
             const focusBlockId = pickFocusBlockId(resolvedPlan.ops);
             const aiInsightChanges = buildAiInsightChanges({ plan: resolvedPlan, message: plannerMessage });
             const metaChangeLogEntries = buildMetaChangeLogEntries(resolvedPlan.ops);

package/dist/checks/field-ops.d.ts

@@ -0,0 +1,10 @@
+import type { Operation } from "@avocadostudio-ai/shared";
+export declare function fieldWriteOp(args: {
+    pageSlug: string;
+    blockId: string;
+    path: string;
+    value: unknown;
+    itemId?: string;
+}): Operation | null;
+/** Whether a path is one `fieldWriteOp` can write. */
+export declare function isWritablePath(path: string): boolean;

package/dist/checks/field-ops.js

@@ -0,0 +1,37 @@
+/*
+ * The op that writes one field, from the editable path the checks report.
+ *
+ * Field-walk reports a top-level prop as `title` and a list item's field as
+ * `cards[0].imageAlt`. `update_props` accepts only top-level prop names, so a
+ * fix that sent `{ "cards[0].imageAlt": "…" }` as a patch was refused as an
+ * unknown prop — every alt-text fix for a card grid or a gallery, which is where
+ * most images live, failed on approve. A list item's field is written with
+ * `update_item`, addressed by the item's id when it has one (stable across a
+ * reorder) and by its index otherwise.
+ *
+ * Field-walk goes one list deep, so those are the only two shapes. Anything
+ * else returns null: no fix is offered rather than one that fails.
+ */
+const PROP = /^[A-Za-z_$][\w$]*$/;
+const LIST_FIELD = /^([A-Za-z_$][\w$]*)\[(\d+)\]\.([A-Za-z_$][\w$]*)$/;
+export function fieldWriteOp(args) {
+    if (PROP.test(args.path)) {
+        return { op: "update_props", pageSlug: args.pageSlug, blockId: args.blockId, patch: { [args.path]: args.value } };
+    }
+    const match = LIST_FIELD.exec(args.path);
+    if (!match)
+        return null;
+    const [, listKey, index, field] = match;
+    return {
+        op: "update_item",
+        pageSlug: args.pageSlug,
+        blockId: args.blockId,
+        listKey: listKey,
+        ...(args.itemId ? { itemId: args.itemId } : { index: Number(index) }),
+        patch: { [field]: args.value }
+    };
+}
+/** Whether a path is one `fieldWriteOp` can write. */
+export function isWritablePath(path) {
+    return PROP.test(path) || LIST_FIELD.test(path);
+}

package/dist/checks/field-walk.js

@@ -95,7 +95,8 @@ function entriesForBlock(block, definition) {
                     kind: meta.kind,
                     ...(meta.label ? { label: meta.label } : {}),
                     value: isRecord(item) ? item[itemKey] : undefined,
-                    container
+                    container,
+                    ...(isRecord(item) && typeof item.id === "string" && item.id ? { itemId: item.id } : {})
                 });
             }
         });

package/dist/checks/rules-draft.js

@@ -1,6 +1,7 @@
 import { IMAGE_PLACEHOLDER, isKnownRoute, normalizeLinkPath, parseLink, toAltPath } from "@avocadostudio-ai/shared";
 import { fieldText, groupByBlock } from "./field-walk.js";
 import { I18N_RULES } from "./rules-i18n.js";
+import { fieldWriteOp } from "./field-ops.js";
 /*
  * The eleven-ish draft-tier rules. Each is a pure function; none does IO.
  *
@@ -31,6 +32,7 @@ function evidenceFor(field, excerpt) {
         blockType: field.blockType,
         ...(field.blockLabel ? { blockLabel: field.blockLabel } : {}),
         path: field.path,
+        ...(field.itemId ? { itemId: field.itemId } : {}),
         ...(excerpt ? { excerpt } : {})
     };
 }
@@ -200,13 +202,8 @@ const h1Count = {
             detail: `${h1s.length} blocks are set to heading level 1.`,
             evidence: evidenceFor(field),
             proposedOps: [
-                {
-                    op: "update_props",
-                    pageSlug: ctx.page.slug,
-                    blockId: field.blockId,
-                    patch: { [field.path]: 2 }
-                }
-            ]
+                fieldWriteOp({ pageSlug: ctx.page.slug, blockId: field.blockId, path: field.path, value: 2, ...(field.itemId ? { itemId: field.itemId } : {}) })
+            ].filter((op) => op !== null)
         }));
     }
 };

package/dist/checks/session-runner.d.ts

@@ -5,6 +5,8 @@ export declare function runChecksForSession(args: {
     trigger: CheckRunTrigger;
     slugs?: string[];
 }): Promise<CheckRunRecord>;
+/** Set the host's `waitUntil`. Called by `createOrchestrator`; last caller wins. */
+export declare function setChecksKeepAlive(fn: ((work: Promise<unknown>) => void) | null): void;
 /**
  * Queue a draft-tier run after an apply, coalescing a burst of edits into one.
  *

package/dist/checks/session-runner.js

@@ -2,6 +2,7 @@ import { buildBlockManifest } from "@avocadostudio-ai/shared";
 import { getSessionDraft, getSiteConfig } from "../state/session-state.js";
 import { runDraftChecks } from "./run-checks.js";
 import { getSiteAssets } from "../state/site-assets.js";
+import { siteOpsAgentsEnabled } from "../agents/enabled.js";
 /*
  * Binds the pure rules engine to session state.
  *
@@ -39,7 +40,10 @@ export async function runChecksForSession(args) {
  * `on_apply` is off by default, behind `CHECKS_ON_APPLY=1`. It is the one that
  * fires on every edit, and this repo has already paid once for a fan-out
  * nobody intended — an ambient linter should be something an operator turns on
- * having decided to, not something they discover in a CPU graph.
+ * having decided to, not something they discover in a CPU graph. Switching on
+ * Site ops agents (`SITE_OPS_AGENTS=1`) is that decision: a finding fixed by
+ * hand should close without anyone pressing "Run checks", so apply checks
+ * follow the agents flag unless `CHECKS_ON_APPLY=0` says otherwise.
  *
  * Both are inert under NODE_ENV=test: the hermetic suite must not have a
  * background task writing findings into a store its assertions are reading.
@@ -49,19 +53,52 @@ const pending = new Map();
 function enabled(flag) {
     if (process.env.NODE_ENV === "test")
         return false;
-    if (flag === "apply")
-        return process.env.CHECKS_ON_APPLY === "1";
+    if (flag === "apply") {
+        if (process.env.CHECKS_ON_APPLY === "1")
+            return true;
+        if (process.env.CHECKS_ON_APPLY === "0")
+            return false;
+        return siteOpsAgentsEnabled();
+    }
     return process.env.CHECKS_ON_PUBLISH !== "0";
 }
+/*
+ * Background work and serverless hosts.
+ *
+ * A check run starts after the response that triggered it has been sent. On a
+ * long-lived server that is free; on a serverless function the platform may
+ * freeze or kill the instance the moment the response is out, and the run —
+ * or the debounce timer in front of it — simply never happens. A host that can
+ * keep an invocation alive (Next's `after()`, Vercel's `waitUntil`) passes it
+ * as `createOrchestrator({ waitUntil })`, and every scheduled run is handed to
+ * it. Without one, runs stay fire-and-forget, which is exactly right on a
+ * long-lived host.
+ */
+let keepAlive = null;
+/** Set the host's `waitUntil`. Called by `createOrchestrator`; last caller wins. */
+export function setChecksKeepAlive(fn) {
+    keepAlive = fn;
+}
+function track(work) {
+    if (!keepAlive)
+        return;
+    try {
+        keepAlive(work.catch(() => { }));
+    }
+    catch {
+        // A host whose waitUntil refuses (called outside a request scope) loses
+        // nothing but the guarantee: the work is already running.
+    }
+}
 function runInBackground(scopeKey, trigger, log) {
     // Custom agents switched on for this event run after the draft checker,
     // on the same engine (agents/run-spec.ts). Imported lazily: the agents
     // module reads settings from the durable store, which the checker alone
     // never needs.
-    void import("../agents/run-spec.js")
+    const agents = import("../agents/run-spec.js")
         .then(({ runCustomAgentsOn }) => runCustomAgentsOn({ scopeKey, on: trigger === "on_apply" ? "apply" : "publish", ...(log ? { log } : {}) }))
         .catch((err) => log?.error({ err: String(err), scopeKey, trigger }, "agent runs failed"));
-    void runChecksForSession({ scopeKey, trigger })
+    const checks = runChecksForSession({ scopeKey, trigger })
         .then((run) => {
         log?.info({ scopeKey, trigger, opened: run.findingsOpened, closed: run.findingsClosed }, "checks run complete");
     })
@@ -70,6 +107,7 @@ function runInBackground(scopeKey, trigger, log) {
         // triggered it. It reports and stops.
         log?.error({ err: String(err), scopeKey, trigger }, "checks run failed");
     });
+    return Promise.all([agents, checks]).then(() => undefined);
 }
 /**
  * Queue a draft-tier run after an apply, coalescing a burst of edits into one.
@@ -82,25 +120,37 @@ export function scheduleChecksAfterApply(scopeKey, log) {
     if (!enabled("apply"))
         return;
     const existing = pending.get(scopeKey);
-    if (existing)
-        clearTimeout(existing);
+    if (existing) {
+        clearTimeout(existing.timer);
+        // The superseded wait resolves now: the run it promised moves to the new timer.
+        existing.settle();
+    }
+    let settle = () => { };
+    const done = new Promise((resolve) => {
+        settle = resolve;
+    });
     const timer = setTimeout(() => {
         pending.delete(scopeKey);
-        runInBackground(scopeKey, "on_apply", log);
+        void runInBackground(scopeKey, "on_apply", log).finally(settle);
     }, ON_APPLY_DEBOUNCE_MS);
-    // Do not hold the process open for a linter.
-    timer.unref?.();
-    pending.set(scopeKey, timer);
+    // Do not hold the process open for a linter — unless the host asked for
+    // background work to finish (waitUntil), which is exactly that request.
+    if (!keepAlive)
+        timer.unref?.();
+    pending.set(scopeKey, { timer, settle });
+    track(done);
 }
 /** Run the draft tier after a successful publish. */
 export function scheduleChecksAfterPublish(scopeKey, log) {
     if (!enabled("publish"))
         return;
-    runInBackground(scopeKey, "on_publish", log);
+    track(runInBackground(scopeKey, "on_publish", log));
 }
 /** Cancel any queued run. Tests, and graceful shutdown. */
 export function cancelScheduledChecks() {
-    for (const timer of pending.values())
-        clearTimeout(timer);
+    for (const entry of pending.values()) {
+        clearTimeout(entry.timer);
+        entry.settle();
+    }
     pending.clear();
 }

package/dist/checks/types.d.ts

@@ -21,6 +21,8 @@ export type FieldEntry = {
      * siblings, and the container is what makes "sibling" meaningful.
      */
     container: string;
+    /** A list item's own id, when it has one — addresses the item across a reorder. */
+    itemId?: string;
 };
 /**
  * One link on the page, wherever it was written.

package/dist/durable/types.d.ts

@@ -15,6 +15,8 @@ export type FindingStatus = "open" | "snoozed" | "dismissed" | "fixed";
 export type FindingEvidence = {
     source: "draft" | "rendered" | "model";
     blockId?: string;
+    /** For a field inside a list: the item's own id, so a fix still lands after a reorder. */
+    itemId?: string;
     /** For an image finding (alt text): the image, so a fix can be written from it. */
     imageUrl?: string;
     /** For a translation finding: the page's language, and the source text it should translate. */

package/dist/handler/create-orchestrator.d.ts

@@ -214,6 +214,17 @@ export interface CreateOrchestratorConfig {
      * offering the matching tools.
      */
     capabilities?: CmsCapabilities;
+    /**
+     * Keep background work alive after the response is sent: Next's `after()`,
+     * or Vercel's `waitUntil` from `@vercel/functions`.
+     *
+     * Checks run in the background after a publish and after edits, so they can
+     * never fail the request that triggered them. A long-lived server needs
+     * nothing here. On a serverless host the platform may stop the instance as
+     * soon as the response is out, and without this hook those runs are
+     * silently lost.
+     */
+    waitUntil?: (work: Promise<unknown>) => void;
 }
 /**
  * A handler returned by {@link createOrchestrator}. Callable like the bare

package/dist/handler/create-orchestrator.js

@@ -43,6 +43,7 @@ import { screenshotAction } from "../http/screenshot-actions.js";
 import { runChecksAction, listFindingsAction, listCheckRunsAction, updateFindingAction } from "../http/checks-actions.js";
 import { listInboxAction, resolveAlertAction, undoAlertAction, markReportReadAction, approveFindingsAction, writeFixesAction, rejectFindingsAction, listAgentsAction, agentStatsAction, updateAgentsAction, backtestAgentsAction, listTemplatesAction, saveAgentSpecAction, removeAgentSpecAction, runAgentAction, tickAgentsAction, draftAgentAction, mentionAction, listFactsAction, addFactAction, removeFactAction } from "../http/inbox-actions.js";
 import { publishHoldResponse } from "../agents/inbox.js";
+import { scheduleChecksAfterApply, scheduleChecksAfterPublish, setChecksKeepAlive } from "../checks/session-runner.js";
 import { siteOpsAgentsEnabled } from "../agents/enabled.js";
 import { fileImageStore, formatImageChatFrame, generateImageAction, imageChatAction, imageChatStreamAction, interpretImageAction, validateImageChatRequest } from "../http/image-generate-actions.js";
 import { transcribeAudioAction, transcriptionUnavailable, validateAudioInput } from "../http/audio-actions.js";
@@ -440,6 +441,8 @@ function publishEnvelope(session, slugs, message) {
  *     export const OPTIONS = handler
  */
 export function createOrchestrator(config = {}) {
+    if (config.waitUntil)
+        setChecksKeepAlive(config.waitUntil);
     const basePath = config.basePath ?? "/api/avocado";
     // When an adapter is configured, force-scope sessions so the orchestrator's
     // built-in demo-content seed path (triggered when a session key has no `::`)
@@ -1135,6 +1138,10 @@ export function createOrchestrator(config = {}) {
                 recordSiteBaseline(scopedSession, pages);
                 schedulePersistState(runtime.log);
             }
+            // The moment content ships is when anyone cares whether it is broken —
+            // and a dry run is a rehearsal of exactly that moment. Background work: a
+            // checker must never be able to fail the publish that triggered it.
+            scheduleChecksAfterPublish(scopedSession, runtime.log);
             return jsonResponse({
                 ...publishEnvelope(body.session, slugs, logged),
                 ok: true,
@@ -1633,6 +1640,9 @@ export function createOrchestrator(config = {}) {
                     ops: parsedOps.data,
                     log: runtime.log
                 });
+                // Same as the standalone server's /ops: debounced, so a streamed
+                // multi-op plan is checked once it has finished landing.
+                scheduleChecksAfterApply(scopedSession, runtime.log);
                 return jsonResponse({
                     status: "applied",
                     summary: "Applied operations.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -22,8 +22,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.35.4",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "^0.24.0",
-    "@avocadostudio-ai/shared": "^0.24.0"
+    "@avocadostudio-ai/migration-sdk": "^0.25.0",
+    "@avocadostudio-ai/shared": "^0.25.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",