@avocadostudio-ai/orchestrator-core 0.22.0 → 0.24.0

package/dist/agents/edit-safety.js

@@ -0,0 +1,425 @@
+import { fieldText } from "../checks/field-walk.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a value holds something a reader would miss.
+ *
+ * Booleans never count: `false` is a setting, not an absence. Objects count
+ * when any string or number inside them does, so an image `{ src: "" }` is
+ * empty and a rich-text document with one word is not.
+ */
+export function hasContent(value) {
+    if (value == null)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value === "boolean")
+        return false;
+    if (Array.isArray(value))
+        return value.some((entry) => hasContent(entry) || isRecord(entry));
+    if (isRecord(value)) {
+        if (fieldText(value).trim().length > 0)
+            return true;
+        return Object.entries(value).some(([key, entry]) => key !== "id" && key !== "type" && hasContent(entry));
+    }
+    return false;
+}
+function shapeOf(value) {
+    if (typeof value === "string")
+        return "text";
+    if (typeof value === "number")
+        return "number";
+    if (Array.isArray(value))
+        return "list";
+    if (isRecord(value))
+        return "object";
+    return "other";
+}
+function definitionFor(manifest, type) {
+    return manifest.blocks.find((b) => b.type === type);
+}
+const BLOCK_LABEL_MAX = 48;
+/** What a reader calls a block: its first non-empty text field. Mirrors field-walk. */
+function labelFor(block, definition) {
+    const props = isRecord(block.props) ? block.props : {};
+    const keys = definition
+        ? Object.entries(definition.fields ?? {})
+            .filter(([, meta]) => meta.kind === "text")
+            .map(([key]) => key)
+        : Object.keys(props);
+    for (const key of keys) {
+        const value = props[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed || /^https?:\/\//.test(trimmed))
+            continue;
+        return trimmed.length > BLOCK_LABEL_MAX ? `${trimmed.slice(0, BLOCK_LABEL_MAX - 1)}…` : trimmed;
+    }
+    return undefined;
+}
+function itemFieldsFor(list, item) {
+    const merged = (list.itemFields ?? {});
+    if (!list.discriminator || !list.itemFieldsByType || !isRecord(item))
+        return merged;
+    const branch = item[list.discriminator];
+    if (typeof branch !== "string")
+        return merged;
+    return list.itemFieldsByType[branch] ?? merged;
+}
+/**
+ * Pair a list's items before and after the edit.
+ *
+ * By `id` when every item has one — the only pairing that survives an insert
+ * or a reorder. By position only when the list kept its length; otherwise a
+ * removed item would pair every later item with its neighbour and report
+ * fields as emptied that simply moved up.
+ */
+function pairItems(before, after) {
+    const idOf = (item) => (isRecord(item) && typeof item.id === "string" && item.id ? item.id : undefined);
+    const allHaveIds = before.every((item) => idOf(item)) && after.every((item) => idOf(item));
+    if (allHaveIds) {
+        const afterIndexById = new Map(after.map((item, index) => [idOf(item), index]));
+        const out = [];
+        for (const item of before) {
+            const id = idOf(item);
+            const index = afterIndexById.get(id);
+            if (index === undefined)
+                continue;
+            out.push({ before: item, after: after[index], afterIndex: index, itemId: id });
+        }
+        return out;
+    }
+    if (before.length !== after.length)
+        return [];
+    return before.map((item, index) => ({ before: item, after: after[index], afterIndex: index }));
+}
+function fieldChange(before, after, kind) {
+    if (!hasContent(before))
+        return null;
+    if (!hasContent(after))
+        return "emptied";
+    if (kind === "richtext")
+        return null;
+    const from = shapeOf(before);
+    const to = shapeOf(after);
+    if (from === to)
+        return null;
+    // Only a change a reader would notice: a list or an object collapsing into a
+    // scalar, or the reverse. A number stored as text is the same value.
+    const structural = (shape) => shape === "list" || shape === "object";
+    return structural(from) !== structural(to) ? "type_changed" : null;
+}
+function blockIssues(slug, before, after, manifest, ops) {
+    const definition = definitionFor(manifest, after.type) ?? definitionFor(manifest, before.type);
+    const beforeProps = isRecord(before.props) ? before.props : {};
+    const afterProps = isRecord(after.props) ? after.props : {};
+    const blockLabel = labelFor(before, definition);
+    const located = {
+        slug,
+        blockId: after.id,
+        blockType: after.type,
+        ...(blockLabel ? { blockLabel } : {})
+    };
+    const out = [];
+    const topLevel = definition
+        ? Object.entries(definition.fields ?? {}).map(([key, meta]) => [key, meta])
+        : Object.keys(beforeProps)
+            .filter((key) => key !== "id")
+            .map((key) => [key, undefined]);
+    const listKeys = new Set(Object.keys(definition?.listFields ?? {}));
+    for (const [key, meta] of topLevel) {
+        if (listKeys.has(key))
+            continue;
+        const change = fieldChange(beforeProps[key], afterProps[key], meta?.kind);
+        if (!change)
+            continue;
+        out.push({
+            kind: change,
+            ...located,
+            path: key,
+            ...(meta?.label ? { label: meta.label } : {}),
+            before: beforeProps[key],
+            after: afterProps[key] ?? null,
+            revert: { op: "update_props", pageSlug: slug, blockId: after.id, patch: { [key]: beforeProps[key] } }
+        });
+    }
+    for (const [listKey, list] of Object.entries(definition?.listFields ?? {})) {
+        const beforeItems = beforeProps[listKey];
+        const afterItems = afterProps[listKey];
+        if (!Array.isArray(beforeItems) || beforeItems.length === 0)
+            continue;
+        if (!Array.isArray(afterItems) || afterItems.length === 0) {
+            // The whole list went. One finding for it, not one per field inside it.
+            out.push({
+                kind: Array.isArray(afterItems) || afterItems == null ? "emptied" : "type_changed",
+                ...located,
+                path: listKey,
+                ...(list.label ? { label: list.label } : {}),
+                before: beforeItems,
+                after: afterItems ?? null,
+                revert: { op: "update_props", pageSlug: slug, blockId: after.id, patch: { [listKey]: beforeItems } }
+            });
+            continue;
+        }
+        out.push(...droppedItems(slug, located, listKey, list.label, beforeItems, afterItems, ops));
+        for (const pair of pairItems(beforeItems, afterItems)) {
+            if (!isRecord(pair.before))
+                continue;
+            const afterItem = isRecord(pair.after) ? pair.after : {};
+            for (const [itemKey, meta] of Object.entries(itemFieldsFor(list, pair.before))) {
+                const change = fieldChange(pair.before[itemKey], afterItem[itemKey], meta.kind);
+                if (!change)
+                    continue;
+                out.push({
+                    kind: change,
+                    ...located,
+                    path: `${listKey}[${pair.afterIndex}].${itemKey}`,
+                    ...(meta.label ? { label: meta.label } : {}),
+                    before: pair.before[itemKey],
+                    after: afterItem[itemKey] ?? null,
+                    revert: {
+                        op: "update_item",
+                        pageSlug: slug,
+                        blockId: after.id,
+                        listKey,
+                        ...(pair.itemId ? { itemId: pair.itemId } : { index: pair.afterIndex }),
+                        patch: { [itemKey]: pair.before[itemKey] }
+                    }
+                });
+            }
+        }
+    }
+    return out;
+}
+function itemIdOf(item) {
+    return isRecord(item) && typeof item.id === "string" && item.id ? item.id : undefined;
+}
+/**
+ * Entries that left a list without anyone removing them. Only reported when
+ * every entry carries an id — without ids a removal and a reorder cannot be
+ * told apart — and never for a list the batch explicitly removed from.
+ */
+function droppedItems(slug, located, listKey, listLabel, beforeItems, afterItems, ops) {
+    const removedOnPurpose = ops.some((op) => op.op === "remove_item" && op.pageSlug === slug && op.blockId === located.blockId && op.listKey === listKey);
+    if (removedOnPurpose)
+        return [];
+    if (!beforeItems.every(itemIdOf) || !afterItems.every(itemIdOf))
+        return [];
+    const surviving = new Set(afterItems.map((item) => itemIdOf(item)));
+    const out = [];
+    beforeItems.forEach((item, index) => {
+        const itemId = itemIdOf(item);
+        if (surviving.has(itemId) || !hasContent(item))
+            return;
+        const anchors = beforeItems
+            .slice(0, index)
+            .reverse()
+            .map((earlier) => itemIdOf(earlier));
+        const anchor = anchors.find((id) => surviving.has(id));
+        out.push({
+            kind: "item_dropped",
+            ...located,
+            path: `${listKey}[${index}]`,
+            ...(listLabel ? { label: listLabel } : {}),
+            listKey,
+            itemId,
+            before: item,
+            after: null,
+            anchors,
+            revert: {
+                op: "add_item",
+                pageSlug: located.slug,
+                blockId: located.blockId,
+                listKey,
+                item: structuredClone(item),
+                ...(anchor ? { afterItemId: anchor } : {})
+            }
+        });
+    });
+    return out;
+}
+const PAGE_META_FIELDS = ["title", "description", "ogImage"];
+/**
+ * Everything an edit did to one page that nobody asked for.
+ *
+ * `ops` is the batch that produced `after`: a block removed by a
+ * `remove_block` naming it was asked for and is not reported. A page created
+ * or deleted by the batch is not this agent's business — `before` or `after`
+ * is null and the answer is empty; deleting a page already goes through the
+ * destructive-action gate.
+ */
+export function detectEditDamage(args) {
+    const { slug, before, after, ops, manifest } = args;
+    if (!before || !after)
+        return [];
+    const out = [];
+    const beforeMeta = isRecord(before.meta) ? before.meta : {};
+    const afterMeta = isRecord(after.meta) ? after.meta : {};
+    for (const key of PAGE_META_FIELDS) {
+        if (!hasContent(beforeMeta[key]) || hasContent(afterMeta[key]))
+            continue;
+        out.push({
+            kind: "emptied",
+            slug,
+            path: `meta.${key}`,
+            before: beforeMeta[key],
+            after: afterMeta[key] ?? null,
+            revert: { op: "update_page_meta", pageSlug: after.slug, patch: { [key]: beforeMeta[key] } }
+        });
+    }
+    const removedOnPurpose = new Set(ops.flatMap((op) => (op.op === "remove_block" && op.pageSlug === slug ? [op.blockId] : [])));
+    const afterById = new Map(after.blocks.map((block) => [block.id, block]));
+    before.blocks.forEach((block, index) => {
+        const survivor = afterById.get(block.id);
+        if (survivor) {
+            out.push(...blockIssues(after.slug, block, survivor, manifest, ops));
+            return;
+        }
+        if (removedOnPurpose.has(block.id))
+            return;
+        // Put it back after the nearest earlier block that is still on the page,
+        // so it returns to where it was rather than to the end.
+        const anchors = before.blocks
+            .slice(0, index)
+            .reverse()
+            .map((candidate) => candidate.id);
+        const anchor = anchors.find((id) => afterById.has(id));
+        const blockLabel = labelFor(block, definitionFor(manifest, block.type));
+        out.push({
+            kind: "block_dropped",
+            slug,
+            blockId: block.id,
+            blockType: block.type,
+            ...(blockLabel ? { blockLabel } : {}),
+            before: block,
+            after: null,
+            anchors,
+            revert: {
+                op: "add_block",
+                pageSlug: after.slug,
+                ...(anchor ? { afterBlockId: anchor } : {}),
+                block: structuredClone(block)
+            }
+        });
+    });
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Reading a value back — for the stale check before a revert
+// ---------------------------------------------------------------------------
+const PATH_SEGMENT = /([^.[\]]+)|\[(\d+)\]/g;
+/** The value at an editable-target path inside `root`, or undefined. */
+export function valueAtPath(root, path) {
+    let current = root;
+    for (const match of path.matchAll(PATH_SEGMENT)) {
+        if (current == null)
+            return undefined;
+        if (match[2] !== undefined) {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[Number(match[2])];
+        }
+        else {
+            if (!isRecord(current))
+                return undefined;
+            current = current[match[1]];
+        }
+    }
+    return current;
+}
+/**
+ * What the issue's location holds on `page` now, in the same form `after` was
+ * recorded in. For a dropped block, the block if it is back; otherwise null.
+ */
+export function currentValueFor(issue, page) {
+    if (!page)
+        return undefined;
+    if (issue.kind === "block_dropped")
+        return page.blocks.find((b) => b.id === issue.blockId) ?? null;
+    if (!issue.path)
+        return undefined;
+    if (!issue.blockId)
+        return valueAtPath(page, issue.path) ?? null;
+    const block = page.blocks.find((b) => b.id === issue.blockId);
+    if (!block)
+        return undefined;
+    if (issue.kind === "item_dropped") {
+        const list = isRecord(block.props) ? block.props[issue.listKey ?? ""] : undefined;
+        if (!Array.isArray(list))
+            return undefined;
+        return list.find((item) => itemIdOf(item) === issue.itemId) ?? null;
+    }
+    return valueAtPath(block.props, issue.path) ?? null;
+}
+function stable(value) {
+    return JSON.stringify(value ?? null);
+}
+/**
+ * True while the location still holds exactly what the edit left there — the
+ * only state in which putting the old value back restores the edit's damage
+ * and nothing else.
+ */
+export function isStillAsEditLeftIt(issue, page) {
+    const current = currentValueFor(issue, page);
+    if (current === undefined)
+        return false;
+    if (issue.kind === "block_dropped" || issue.kind === "item_dropped")
+        return current === null;
+    return stable(current) === stable(issue.after);
+}
+export function countIssues(issues) {
+    return {
+        emptied: issues.filter((i) => i.kind === "emptied").length,
+        blocksDropped: issues.filter((i) => i.kind === "block_dropped").length,
+        itemsDropped: issues.filter((i) => i.kind === "item_dropped").length,
+        typeChanged: issues.filter((i) => i.kind === "type_changed").length
+    };
+}
+/** One English line for logs, the Inbox row and anything outside the editor. */
+export function describeIssues(issues) {
+    const counts = countIssues(issues);
+    const parts = [];
+    if (counts.emptied)
+        parts.push(`emptied ${counts.emptied} ${counts.emptied === 1 ? "field" : "fields"}`);
+    if (counts.blocksDropped) {
+        parts.push(`dropped ${counts.blocksDropped} ${counts.blocksDropped === 1 ? "block" : "blocks"}`);
+    }
+    if (counts.itemsDropped) {
+        parts.push(`dropped ${counts.itemsDropped} list ${counts.itemsDropped === 1 ? "entry" : "entries"}`);
+    }
+    if (counts.typeChanged) {
+        parts.push(`changed the shape of ${counts.typeChanged} ${counts.typeChanged === 1 ? "field" : "fields"}`);
+    }
+    if (parts.length <= 1)
+        return parts[0] ?? "";
+    return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+/**
+ * The revert op for `issue`, re-anchored against `page` as it is now. For a
+ * dropped block or entry, the anchor is the nearest earlier neighbour that is
+ * on the page at this moment; every other revert is returned unchanged.
+ */
+export function revertFor(issue, page) {
+    const op = issue.revert;
+    if (!op || !issue.anchors || !page)
+        return op;
+    if (op.op === "add_block") {
+        const present = new Set(page.blocks.map((block) => block.id));
+        const anchor = issue.anchors.find((id) => present.has(id));
+        const { afterBlockId: _previous, ...rest } = op;
+        return anchor ? { ...rest, afterBlockId: anchor } : rest;
+    }
+    if (op.op === "add_item") {
+        const block = page.blocks.find((b) => b.id === op.blockId);
+        const list = block && isRecord(block.props) ? block.props[op.listKey] : undefined;
+        const present = new Set(Array.isArray(list) ? list.map(itemIdOf).filter(Boolean) : []);
+        const anchor = issue.anchors.find((id) => present.has(id));
+        const { afterItemId: _previous, ...rest } = op;
+        return anchor ? { ...rest, afterItemId: anchor } : rest;
+    }
+    return op;
+}

package/dist/agents/enabled.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Site ops agents — Edit safety, the Inbox, scheduled and custom agents, site
+ * facts, @mentions — are pre-alpha, and off unless `SITE_OPS_AGENTS=1`.
+ *
+ * Off has to mean off on the server, not just hidden tabs: Edit safety alerts
+ * hold publishing (409) until someone resolves them in the Inbox, so an editor
+ * that hides the Inbox while the server still raises alerts leaves publish
+ * stuck with no screen that can unstick it. Each entry point checks this:
+ * Edit safety raises nothing, nothing holds publish, the planner is given no
+ * site facts, a tick runs nothing, and an @handle goes to the planner. The
+ * editor reads it from `/status/planner` (`features.siteOpsAgents`) and hides
+ * Inbox, Agents and @-agent routing.
+ *
+ * Read per call, like every flag here, so a test or a library-mode host can set
+ * it after import. The hermetic test runner switches it on; the tests that pin
+ * the default delete it.
+ */
+export declare function siteOpsAgentsEnabled(): boolean;

package/dist/agents/enabled.js

@@ -0,0 +1,21 @@
+import { envFlag } from "../env-flags.js";
+/**
+ * Site ops agents — Edit safety, the Inbox, scheduled and custom agents, site
+ * facts, @mentions — are pre-alpha, and off unless `SITE_OPS_AGENTS=1`.
+ *
+ * Off has to mean off on the server, not just hidden tabs: Edit safety alerts
+ * hold publishing (409) until someone resolves them in the Inbox, so an editor
+ * that hides the Inbox while the server still raises alerts leaves publish
+ * stuck with no screen that can unstick it. Each entry point checks this:
+ * Edit safety raises nothing, nothing holds publish, the planner is given no
+ * site facts, a tick runs nothing, and an @handle goes to the planner. The
+ * editor reads it from `/status/planner` (`features.siteOpsAgents`) and hides
+ * Inbox, Agents and @-agent routing.
+ *
+ * Read per call, like every flag here, so a test or a library-mode host can set
+ * it after import. The hermetic test runner switches it on; the tests that pin
+ * the default delete it.
+ */
+export function siteOpsAgentsEnabled() {
+    return envFlag("SITE_OPS_AGENTS", false);
+}

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

@@ -0,0 +1,38 @@
+import { type Operation, type PageDoc } from "@avocadostudio-ai/shared";
+import type { FindingFix, FindingRecord } from "../durable/types.ts";
+import type { DraftClient } from "./draft-spec.ts";
+export type FixField = FindingFix["field"];
+/** The rules a fix can be written for, and which field each one fixes. */
+export declare const FIXABLE_RULES: Record<string, FixField>;
+export declare function fixFieldFor(ruleId: string): FixField | undefined;
+export type FixDeps = {
+    /** Text model for titles and descriptions. */
+    client?: DraftClient;
+    model?: string;
+    /** Vision alt text; defaults to the editor's own generator. */
+    altText?: (imageUrl: string) => Promise<string | null>;
+    /** Site facts, one per line: words to avoid, product names, tone. */
+    facts?: string[];
+};
+export type WriteFixResult = {
+    ok: true;
+    fix: FindingFix;
+} | {
+    ok: false;
+    error: string;
+};
+/** The value a fix for this finding replaces, read off the page as it is now. */
+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[];
+/** 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;
+/**
+ * Write a fix for one finding against the page as it is. A title or
+ * description outside its length is retried once with the count; a second
+ * miss is refused rather than stored, because the fix would reopen the very
+ * finding it was written for.
+ */
+export declare function writeFix(finding: FindingRecord, page: PageDoc, deps?: FixDeps): Promise<WriteFixResult>;
+/** "German" for "de": the model is told a language, not a code. */
+export declare function languageName(code: string): string;