@avocadostudio-ai/orchestrator-core 0.22.0 → 0.24.0

package/dist/agents/edit-safety-resolve.js

@@ -0,0 +1,195 @@
+import { getDurableStore } from "../durable/durable-store-singleton.js";
+import { consoleLogger } from "../logger.js";
+import { applyOpsAtomically, toErrorDetail } from "../ops/ops-engine.js";
+import { restoreSnapshot } from "../http/history-actions.js";
+import { bumpVersion, getPage, pushUndo, pushVersionEntry, schedulePersistState } from "../state/session-state.js";
+import { isStillAsEditLeftIt, revertFor } from "./edit-safety.js";
+import { EDIT_SAFETY_AGENT } from "./edit-safety-runner.js";
+import { recordOutcome } from "./learning.js";
+function alertPayload(item) {
+    const payload = item.payload;
+    if (!payload || !Array.isArray(payload.issues))
+        return null;
+    return payload;
+}
+/** A page's content, without the timestamp every write restamps. */
+export function contentHash(page) {
+    if (!page)
+        return "null";
+    const { updatedAt: _updatedAt, ...content } = page;
+    return JSON.stringify(content);
+}
+async function applyReverts(scopeKey, issues, by) {
+    const outcome = { applied: 0, changedSince: 0, failed: [] };
+    const appliedOps = [];
+    const touched = new Map();
+    let lastSlug;
+    for (const issue of issues) {
+        if (!issue.revert)
+            continue;
+        const slug = "pageSlug" in issue.revert ? String(issue.revert.pageSlug) : issue.slug;
+        const page = getPage(scopeKey, slug);
+        if (!isStillAsEditLeftIt(issue, page)) {
+            outcome.changedSince += 1;
+            continue;
+        }
+        try {
+            const before = page ? structuredClone(page) : null;
+            const op = revertFor(issue, page);
+            await applyOpsAtomically(scopeKey, [op]);
+            if (!touched.has(slug))
+                touched.set(slug, before);
+            appliedOps.push(op);
+            outcome.applied += 1;
+            lastSlug = slug;
+        }
+        catch (error) {
+            outcome.failed.push({
+                ...(issue.path ? { path: issue.path } : {}),
+                ...(issue.blockId ? { blockId: issue.blockId } : {}),
+                error: toErrorDetail(error)
+            });
+        }
+    }
+    if (appliedOps.length === 0 || !lastSlug)
+        return { outcome, pages: {} };
+    // One undo step per page for the whole revert, taken before its first op.
+    for (const [slug, snapshot] of touched)
+        pushUndo(scopeKey, slug, snapshot);
+    const previewVersion = bumpVersion(scopeKey);
+    const snapshot = getPage(scopeKey, lastSlug);
+    pushVersionEntry(scopeKey, {
+        version: previewVersion,
+        slug: lastSlug,
+        summary: `Edit safety: put back ${appliedOps.length} ${appliedOps.length === 1 ? "change" : "changes"}`,
+        opTypes: appliedOps.map((op) => op.op),
+        opCount: appliedOps.length,
+        source: "direct",
+        actor: { kind: "user", ...(by ? { id: by } : {}) },
+        snapshot: snapshot ? structuredClone(snapshot) : null
+    });
+    outcome.previewVersion = previewVersion;
+    const pages = {};
+    for (const [slug, before] of touched)
+        pages[slug] = { before, afterHash: contentHash(getPage(scopeKey, slug)) };
+    return { outcome, pages };
+}
+export async function resolveEditSafetyAlert(args) {
+    const store = getDurableStore();
+    const item = await store.getInboxItem(args.itemId);
+    // Another site's item is reported exactly like a missing one.
+    if (!item || item.scopeKey !== args.scopeKey || item.agent !== EDIT_SAFETY_AGENT) {
+        return { ok: false, code: 404, error: "alert not found" };
+    }
+    if (item.status !== "open")
+        return { ok: false, code: 409, error: "alert already resolved" };
+    const payload = alertPayload(item);
+    if (!payload)
+        return { ok: false, code: 422, error: "alert has no issues to act on" };
+    let revert;
+    let revertedPages;
+    if (args.decision === "revert") {
+        const result = await applyReverts(args.scopeKey, payload.issues, args.resolvedBy);
+        revert = result.outcome;
+        revertedPages = result.pages;
+        if (revert.applied > 0)
+            schedulePersistState(args.log ?? consoleLogger());
+    }
+    const resolved = await store.resolveInboxItem(item.id, {
+        resolution: args.decision === "revert" ? "reverted" : "intended",
+        ...(args.resolvedBy ? { resolvedBy: args.resolvedBy } : {}),
+        ...(revert ? { payload: { revert, revertedPages } } : {})
+    });
+    // Somebody else answered between our read and our write. Their answer stands.
+    if (!resolved)
+        return { ok: false, code: 409, error: "alert already resolved" };
+    await recordOutcome({
+        scopeKey: args.scopeKey,
+        traceId: payload.traceId ?? item.id,
+        slug: item.slugs[0],
+        request: payload.request ?? item.title,
+        proposed: payload.issues.flatMap((issue) => (issue.revert ? [issue.revert] : [])),
+        // The edit was the proposal: reverting its damage undoes it, "it was
+        // meant" accepts it as it stands.
+        outcome: args.decision === "revert" ? "undone" : "accepted",
+        log: args.log
+    });
+    return { ok: true, item: withoutPages(resolved), ...(revert ? { revert } : {}) };
+}
+/** The stored page snapshots are the server's business; the editor never needs them. */
+export function withoutPages(item) {
+    if (!item.payload || !("revertedPages" in item.payload))
+        return item;
+    const { revertedPages: _pages, ...payload } = item.payload;
+    return { ...item, payload };
+}
+/**
+ * Undo "Put it back": the pages go back to what the edit left, and the alert
+ * reopens — the damage is back, so is the publish hold, and the person can
+ * decide again (site-ops-agents.md SO-08, "Undo everywhere").
+ *
+ * All or nothing, and only while every page the revert touched is exactly as
+ * the revert left it. A page somebody has edited since is not rolled back
+ * under them; the answer names it and points at History instead.
+ */
+export async function undoRevert(args) {
+    const store = getDurableStore();
+    const item = await store.getInboxItem(args.itemId);
+    if (!item || item.scopeKey !== args.scopeKey || item.agent !== EDIT_SAFETY_AGENT) {
+        return { ok: false, code: 404, error: "alert not found" };
+    }
+    const pages = item.payload?.revertedPages;
+    if (item.status !== "resolved" || item.resolution !== "reverted" || !pages || Object.keys(pages).length === 0) {
+        return { ok: false, code: 409, error: "only a revert that changed something can be undone" };
+    }
+    const changedSlugs = Object.entries(pages)
+        .filter(([slug, page]) => contentHash(getPage(args.scopeKey, slug)) !== page.afterHash)
+        .map(([slug]) => slug);
+    if (changedSlugs.length > 0) {
+        return {
+            ok: false,
+            code: 409,
+            error: `The page changed after the revert (${changedSlugs.join(", ")}); use History to go back instead.`,
+            changedSlugs
+        };
+    }
+    const slugs = Object.keys(pages);
+    for (const [slug, { before }] of Object.entries(pages)) {
+        if (!before)
+            continue;
+        pushUndo(args.scopeKey, slug, getPage(args.scopeKey, slug));
+        // Restamped by restoreSnapshot, so the preview accepts it as newer.
+        restoreSnapshot(args.scopeKey, before, { types: new Set(), mode: "keep-current" });
+    }
+    const previewVersion = bumpVersion(args.scopeKey);
+    const last = slugs[slugs.length - 1];
+    const snapshot = getPage(args.scopeKey, last);
+    pushVersionEntry(args.scopeKey, {
+        version: previewVersion,
+        slug: last,
+        summary: "Undid an Edit safety revert",
+        opTypes: [],
+        opCount: 0,
+        source: "restore",
+        actor: { kind: "user", ...(args.by ? { id: args.by } : {}) },
+        snapshot: snapshot ? structuredClone(snapshot) : null
+    });
+    schedulePersistState(args.log ?? consoleLogger());
+    const reopened = await store.reopenInboxItem(item.id, {
+        payload: { revertedPages: undefined, undoneRevert: { at: Date.now(), ...(args.by ? { by: args.by } : {}) } }
+    });
+    if (!reopened)
+        return { ok: false, code: 409, error: "alert changed while undoing" };
+    // The revert was recorded as the edit being undone; taking it back accepts the edit.
+    const payload = alertPayload(item);
+    await recordOutcome({
+        scopeKey: args.scopeKey,
+        traceId: payload?.traceId ?? item.id,
+        slug: item.slugs[0],
+        request: `Undid the revert of: ${payload?.request ?? item.title}`,
+        proposed: [],
+        outcome: "accepted",
+        log: args.log
+    });
+    return { ok: true, item: withoutPages(reopened), previewVersion, slugs };
+}

package/dist/agents/edit-safety-runner.d.ts

@@ -0,0 +1,68 @@
+import { type Operation, type PageDoc } from "@avocadostudio-ai/shared";
+import type { Logger } from "../logger.ts";
+import { type EditSafetyCounts, type EditSafetyIssue } from "./edit-safety.ts";
+/** How long a chat-turn alert waits in the chat before it also lands in the Inbox. */
+export declare const CHAT_ALERT_GRACE_MS: number;
+export type EditSafetySource = "chat" | "mcp";
+export type EditSafetyReport = {
+    itemId: string;
+    slugs: string[];
+    counts: EditSafetyCounts;
+    issues: EditSafetyIssue[];
+};
+/** What an alert's `payload` holds. Read back by the resolve path and the editor. */
+export type EditSafetyAlertPayload = {
+    issues: EditSafetyIssue[];
+    counts: EditSafetyCounts;
+    source: EditSafetySource;
+    /** The sentence that produced the edit, when there was one. */
+    request?: string;
+    traceId?: string;
+};
+export declare const EDIT_SAFETY_AGENT = "edit-safety";
+/**
+ * Every page a batch of ops names, as it stands before the batch — the
+ * `before` checkEditSafety diffs against.
+ *
+ * A chat turn used to keep only the page it was about, so a plan that also
+ * edited a second page (a shared nav label, a translated copy) was never
+ * checked there. `also` adds pages the caller knows about that an op may not
+ * name. A page an op creates is recorded as null; detectEditDamage skips it.
+ */
+export declare function pagesBefore(ops: Operation[], getPage: (slug: string) => PageDoc | null | undefined, also?: string[]): Map<string, PageDoc | null>;
+/**
+ * Check one applied batch. Never throws and never blocks the edit: a failure
+ * here is logged and the edit stands as it would have without this agent.
+ */
+export declare function checkEditSafety(args: {
+    scopeKey: string;
+    /** Every page the batch touched, as it stood before. `null` for one it created. */
+    before: Map<string, PageDoc | null>;
+    /** The page as it stands now, by the slug it had before the batch. */
+    afterOf: (slug: string) => PageDoc | null;
+    ops: Operation[];
+    source: EditSafetySource;
+    request?: string;
+    traceId?: string;
+    log?: Logger;
+    now?: number;
+}): Promise<EditSafetyReport | null>;
+/** What travels to the editor with a chat turn: enough to name each issue, no whole blocks. */
+export type EditSafetySummaryIssue = {
+    kind: EditSafetyIssue["kind"];
+    slug: string;
+    blockId?: string;
+    blockType?: string;
+    blockLabel?: string;
+    path?: string;
+    label?: string;
+    /** What was lost, as text: the old value, or a dropped entry's first text. */
+    before?: string;
+};
+export type EditSafetySummary = {
+    itemId: string;
+    slugs: string[];
+    counts: EditSafetyCounts;
+    issues: EditSafetySummaryIssue[];
+};
+export declare function summarizeReport(report: EditSafetyReport): EditSafetySummary;

package/dist/agents/edit-safety-runner.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { getDurableStore, noteDurableFailure } from "../durable/durable-store-singleton.js";
+import { agentState } from "./settings.js";
+import { countIssues, describeIssues, detectEditDamage } from "./edit-safety.js";
+import { siteOpsAgentsEnabled } from "./enabled.js";
+/*
+ * Binds the Edit safety diff to a real edit, and records what it found.
+ *
+ * Called after a batch has been applied, with the pages as they stood before
+ * it. Every path that writes a draft on somebody's behalf goes through here:
+ * the chat turn, and `/ops` when the caller is an MCP client. A person typing
+ * in the property panel also reaches `/ops`, and is not checked — emptying a
+ * field by hand is the edit, not damage done alongside one.
+ *
+ * What it produces is one Inbox alert per edit, holding publish for the pages
+ * it names until someone reverts it or says it was meant (SO-18). Where it
+ * shows up first depends on who is watching (SO-06 surface 2):
+ *
+ *  - a chat turn: the person who asked is looking at the chat, so the alert
+ *    rides back on the turn's result and stays out of the Inbox list for
+ *    `CHAT_ALERT_GRACE_MS`. Publish is held from the start either way.
+ *  - MCP, or anything else unattended: straight into the Inbox.
+ */
+/** How long a chat-turn alert waits in the chat before it also lands in the Inbox. */
+export const CHAT_ALERT_GRACE_MS = 15 * 60 * 1000;
+export const EDIT_SAFETY_AGENT = "edit-safety";
+/**
+ * Every page a batch of ops names, as it stands before the batch — the
+ * `before` checkEditSafety diffs against.
+ *
+ * A chat turn used to keep only the page it was about, so a plan that also
+ * edited a second page (a shared nav label, a translated copy) was never
+ * checked there. `also` adds pages the caller knows about that an op may not
+ * name. A page an op creates is recorded as null; detectEditDamage skips it.
+ */
+export function pagesBefore(ops, getPage, also = []) {
+    const slugs = new Set(also);
+    for (const op of ops) {
+        const slug = op.pageSlug;
+        if (typeof slug === "string" && slug)
+            slugs.add(slug);
+        if (op.op === "create_page")
+            slugs.add(op.page.slug);
+    }
+    const before = new Map();
+    for (const slug of slugs) {
+        const page = getPage(slug);
+        before.set(slug, page ? structuredClone(page) : null);
+    }
+    return before;
+}
+/**
+ * Check one applied batch. Never throws and never blocks the edit: a failure
+ * here is logged and the edit stands as it would have without this agent.
+ */
+export async function checkEditSafety(args) {
+    try {
+        if (args.before.size === 0 || !siteOpsAgentsEnabled())
+            return null;
+        const agent = await agentState(args.scopeKey, "edit-safety");
+        if (!agent.enabled)
+            return null;
+        const manifest = buildBlockManifest();
+        const issues = [];
+        for (const [slug, before] of args.before) {
+            issues.push(...detectEditDamage({ slug, before, after: args.afterOf(slug), ops: args.ops, manifest }));
+        }
+        if (issues.length === 0)
+            return null;
+        const at = args.now ?? Date.now();
+        const slugs = [...new Set(issues.map((issue) => issue.slug))];
+        const counts = countIssues(issues);
+        const itemId = `edit-safety:${randomUUID()}`;
+        const what = describeIssues(issues);
+        const origin = args.source === "chat" ? "An AI edit" : "An MCP edit";
+        const payload = {
+            issues,
+            counts,
+            source: args.source,
+            ...(args.request ? { request: args.request.slice(0, 500) } : {}),
+            ...(args.traceId ? { traceId: args.traceId } : {})
+        };
+        await getDurableStore().putInboxItem({
+            id: itemId,
+            scopeKey: args.scopeKey,
+            kind: "alert",
+            agent: EDIT_SAFETY_AGENT,
+            object: slugs.join(", "),
+            verb: `caught ${args.source === "chat" ? "an AI" : "an MCP"} edit that ${what}`,
+            title: `${origin} ${what} on ${slugs.join(", ")}`,
+            summary: args.request
+                ? `The request was “${args.request.slice(0, 200)}”. The edit also ${what}, which nobody asked for.`
+                : `The edit also ${what}, which nobody asked for.`,
+            slugs,
+            // Something broke: always at the top of the queue.
+            impact: 1,
+            ...(agent.owner ? { assignee: agent.owner } : {}),
+            ...(args.source === "chat" ? { visibleFrom: at + CHAT_ALERT_GRACE_MS } : {}),
+            blocksPublish: true,
+            payload: payload,
+            createdAt: at
+        });
+        args.log?.info({ scopeKey: args.scopeKey, itemId, slugs, counts }, "[edit-safety] edit damage held for review");
+        return { itemId, slugs, counts, issues };
+    }
+    catch (error) {
+        noteDurableFailure(error instanceof Error ? error.message : String(error));
+        args.log?.warn({ err: error }, "[edit-safety] check failed; the edit stands unchecked");
+        return null;
+    }
+}
+const SUMMARY_VALUE_MAX = 120;
+/** A dropped entry or block, named by its first piece of text ("Day pass"). */
+function nameOf(value, depth = 0) {
+    if (typeof value === "string")
+        return value.trim() || undefined;
+    if (typeof value === "number")
+        return String(value);
+    if (depth > 3 || value == null || typeof value !== "object")
+        return undefined;
+    const entries = Array.isArray(value) ? value.map((v) => ["", v]) : Object.entries(value);
+    for (const [key, entry] of entries) {
+        if (key === "id" || key === "type" || /url|href|src/i.test(key))
+            continue;
+        const found = nameOf(entry, depth + 1);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+function beforeText(issue) {
+    const source = issue.kind === "block_dropped" && issue.before && typeof issue.before === "object"
+        ? issue.before.props
+        : issue.before;
+    const text = typeof source === "string" ? source : issue.kind.endsWith("_dropped") ? nameOf(source) : undefined;
+    if (!text)
+        return undefined;
+    return text.length > SUMMARY_VALUE_MAX ? `${text.slice(0, SUMMARY_VALUE_MAX - 1)}…` : text;
+}
+export function summarizeReport(report) {
+    return {
+        itemId: report.itemId,
+        slugs: report.slugs,
+        counts: report.counts,
+        issues: report.issues.map((issue) => ({
+            kind: issue.kind,
+            slug: issue.slug,
+            ...(issue.blockId ? { blockId: issue.blockId } : {}),
+            ...(issue.blockType ? { blockType: issue.blockType } : {}),
+            ...(issue.blockLabel ? { blockLabel: issue.blockLabel } : {}),
+            ...(issue.path ? { path: issue.path } : {}),
+            ...(issue.label ? { label: issue.label } : {}),
+            ...(beforeText(issue) ? { before: beforeText(issue) } : {})
+        }))
+    };
+}

package/dist/agents/edit-safety.d.ts

@@ -0,0 +1,82 @@
+import type { BlockManifest, Operation, PageDoc } from "@avocadostudio-ai/shared";
+export type EditSafetyIssueKind = "emptied" | "block_dropped" | "item_dropped" | "type_changed";
+export type EditSafetyIssue = {
+    kind: EditSafetyIssueKind;
+    slug: string;
+    /** Absent for a page-level field (`meta.description`). */
+    blockId?: string;
+    blockType?: string;
+    blockLabel?: string;
+    /** Editable-target grammar against the page after the edit: `plans[1].price`. */
+    path?: string;
+    /** The field's label from the manifest, when it has one. */
+    label?: string;
+    /** For `item_dropped`: the list and the item's stable id. */
+    listKey?: string;
+    itemId?: string;
+    /** What was there: the field value, or the whole block or item for a drop. */
+    before: unknown;
+    /** What the edit left. `null` for a dropped block or item. */
+    after: unknown;
+    /** The op that restores `before`. Absent when there is no op that can. */
+    revert?: Operation;
+    /**
+     * For a drop: the ids that came before it on the page (or in the list),
+     * nearest first. The revert goes back after the first of them that exists
+     * when it runs — which may be one another revert of the same alert just
+     * put back, so several dropped entries return in their original order.
+     */
+    anchors?: string[];
+};
+/**
+ * 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 declare function hasContent(value: unknown): boolean;
+/**
+ * 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 declare function detectEditDamage(args: {
+    slug: string;
+    before: PageDoc | null;
+    after: PageDoc | null;
+    ops: Operation[];
+    manifest: BlockManifest;
+}): EditSafetyIssue[];
+/** The value at an editable-target path inside `root`, or undefined. */
+export declare function valueAtPath(root: unknown, path: string): unknown;
+/**
+ * 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 declare function currentValueFor(issue: EditSafetyIssue, page: PageDoc | null): unknown;
+/**
+ * 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 declare function isStillAsEditLeftIt(issue: EditSafetyIssue, page: PageDoc | null): boolean;
+export type EditSafetyCounts = {
+    emptied: number;
+    blocksDropped: number;
+    itemsDropped: number;
+    typeChanged: number;
+};
+export declare function countIssues(issues: EditSafetyIssue[]): EditSafetyCounts;
+/** One English line for logs, the Inbox row and anything outside the editor. */
+export declare function describeIssues(issues: EditSafetyIssue[]): string;
+/**
+ * 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 declare function revertFor(issue: EditSafetyIssue, page: PageDoc | null): Operation | undefined;