@avocadostudio-ai/orchestrator-core 0.3.3 → 0.4.0

package/dist/handler/create-orchestrator.js

@@ -30,7 +30,7 @@ import { runChatPipeline, collectMentionedSlugsFromOps } from "../chat/chat-pipe
 import { createChatTelemetryStore } from "../telemetry/chat-telemetry.js";
 import { createToolRuntime } from "../tools/runtime.js";
 import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState, normalizeSiteId, publishStatusBySession, pushPublishLogEntry, persistenceHealth, persistenceWarning } from "../state/session-state.js";
-import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction } from "../http/history-actions.js";
+import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction, historyDiscardAction } from "../http/history-actions.js";
 import { whoamiAction } from "../http/session-actions.js";
 import { blocksManifestAction } from "../http/blocks-actions.js";
 import { screenshotAction } from "../http/screenshot-actions.js";
@@ -41,6 +41,7 @@ import { formatVariationFrame, parseVariationRequest, scopeVariationSession, var
 import { opsDryRunAction, describeAppliedOps } from "../http/ops-actions.js";
 import { describeDraft } from "../http/draft-provenance.js";
 import { buildPublishSummary, publishDiffAction, publishLogAction, publishStatusAction } from "../http/publish-actions.js";
+import { isSelectionFailure, parseSelectionSlugs, selectPagesForPublish } from "../publish/publish-selection.js";
 import { restoreSnapshotApply, restoreSnapshotDelete, restoreSnapshotsList } from "../http/restore-actions.js";
 import { unsplashSearchAction } from "../http/unsplash-actions.js";
 import { telemetryFeedbackListAction, telemetryFeedbackSubmitAction } from "../http/telemetry-feedback-actions.js";
@@ -51,6 +52,7 @@ import { resolveCapabilities } from "../cms/adapter.js";
 import { mediaSourceFromUnknown } from "../cms/media-sources.js";
 import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../http/access-tokens.js";
 import { checkAuth, resolveAuth } from "./auth.js";
+import { setSiteAssetLister, invalidateSiteAssets } from "../state/site-assets.js";
 const defaultModelLookup = () => ({
     openai: {
         fast: process.env.OPENAI_MODEL_FAST ?? "gpt-4o-mini",
@@ -131,16 +133,70 @@ async function buildRuntime(config) {
      * forgotten, and `ensure()` still does its own fetch.
      */
     bootstrapCache.warm(config.adapter ?? null, log);
+    /*
+     * Tell the checker which documents this site has, if it can say.
+     *
+     * `content.file-link-unknown` is the rule that turns a hand-typed PDF path
+     * into something verifiable, and it needs the asset list. Registered here
+     * because this is the one place that holds the adapter and knows whether it
+     * implements the seam; a site with no `getMedia` registers nothing, and the
+     * rule stays silent rather than calling every document on the site missing.
+     */
+    const adapter = config.adapter ?? null;
+    if (typeof adapter?.getMedia === "function") {
+        const getMedia = adapter.getMedia.bind(adapter);
+        setSiteAssetLister(async () => {
+            const out = [];
+            /*
+             * Paged, and bounded. A media library can hold thousands of files, and a
+             * linter is not entitled to walk all of them on every publish — past the
+             * cap the rule sees a partial list, which is why it reports only links
+             * that match nothing *and* stops being useful rather than wrong: a file
+             * beyond the cap is simply not checked.
+             */
+            for (let page = 1; page <= ASSET_LIST_MAX_PAGES; page++) {
+                const result = await getMedia({ page, limit: ASSET_LIST_PAGE_SIZE, kind: "file" });
+                for (const item of result.items ?? []) {
+                    if ((item.kind ?? "image") !== "file")
+                        continue;
+                    const path = item.url ?? item.imageUrl;
+                    if (!path)
+                        continue;
+                    out.push({
+                        path,
+                        ...(item.name ? { name: item.name } : {}),
+                        ...(item.contentType ? { contentType: item.contentType } : {}),
+                        ...(item.size != null ? { size: item.size } : {})
+                    });
+                }
+                if (page >= (result.totalPages ?? 1))
+                    break;
+            }
+            return out;
+        });
+    }
+    else {
+        setSiteAssetLister(null);
+    }
     return {
         pipelineCtx,
         ready,
         resumableStore,
         log,
-        adapter: config.adapter ?? null,
+        adapter,
         capabilities,
         bootstrapCache
     };
 }
+/*
+ * A cap on one upload. Generous for a document — the largest PDF on the site
+ * that prompted this is 183KB — and small enough that a misdirected video does
+ * not sit in memory as a `Uint8Array` while the adapter decides what to do
+ * with it.
+ */
+const MEDIA_UPLOAD_MAX_BYTES = 25_000_000;
+const ASSET_LIST_PAGE_SIZE = 100;
+const ASSET_LIST_MAX_PAGES = 10;
 /*
  * Takes the *resolved* CORS map rather than the raw Origin header. It used to
  * echo the origin directly, which meant every SSE response granted a
@@ -224,6 +280,7 @@ const SUPPORTED_ROUTES = [
     "POST /history/undo",
     "POST /history/redo",
     "POST /history/restore",
+    "POST /history/discard",
     "GET /whoami",
     "GET /blocks/manifest",
     "GET /sites",
@@ -236,6 +293,7 @@ const SUPPORTED_ROUTES = [
     "DELETE /restore/snapshot",
     "GET /unsplash/search",
     "POST /media/cms",
+    "POST /media/upload",
     "GET+POST /telemetry/chat/feedback",
     "POST /preview/screenshot",
     "POST /audio/transcribe",
@@ -319,6 +377,15 @@ export function createOrchestrator(config = {}) {
     if (config.blockTypes)
         declareBlockCatalogue(config.blockTypes);
     const scope = (session, bodySiteId) => scopedSessionKey(session, effectiveSiteId ?? bodySiteId);
+    /*
+     * The same resolution, for an action that scopes the session itself.
+     *
+     * `scope()` answers with a key, which is what a route needs when it holds the
+     * key. An action given `{ session, siteId }` computes its own, and every
+     * caller that forgot to fill `siteId` in silently addressed a different
+     * session than the route beside it — see `/checks/run`.
+     */
+    const withSiteId = (params) => effectiveSiteId ? { ...params, siteId: effectiveSiteId } : params;
     const imageDir = config.imageDir ?? resolve(process.cwd(), ".data/generated-images");
     /*
      * Built on first use rather than at mount: the store opens an append-only
@@ -712,7 +779,48 @@ export function createOrchestrator(config = {}) {
              * publish (LM-04).
              */
             await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
-            const pages = getSessionPages(scopedSession);
+            /*
+             * Hand the adapter the baseline it needs to diff.
+             *
+             * `onPublish(pages)` alone is a snapshot contract, and a snapshot is not
+             * invertible: every CMS read is a projection, so writing the projection
+             * back replaces an asset reference with a URL and a document reference
+             * with a dead href. A publisher has to compare against what it read, and
+             * it cannot compare against nothing.
+             *
+             * This is the copy the bootstrap already took, not a fresh read — a
+             * second `getPages()` here is 45 sequential Sanity calls on the
+             * integration that motivated it. It used to be absent for the rest of a
+             * process's life after a restart that reloaded the draft from SQLite,
+             * which quietly disabled publishing for any adapter that refuses without
+             * a baseline; `ensure` now recovers it on the first request instead.
+             *
+             * It can still be undefined — the adapter read can fail, and baselines
+             * are evicted FIFO — so the contract is unchanged: treat undefined as
+             * "no baseline available" and never as "the site was empty".
+             */
+            const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
+            /*
+             * A publish of some pages is the live site with those pages replaced,
+             * never the ticked pages on their own — see `publish-selection.ts`. The
+             * baseline is doing double duty here: the adapter diffs against it, and
+             * the merge fills the unselected slots from it, so an unticked page is
+             * byte-identical to what the adapter read and produces no writes.
+             */
+            const selection = selectPagesForPublish({
+                draft: getSessionPages(scopedSession),
+                published,
+                draftSiteConfig: getSiteConfig(scopedSession),
+                publishedSiteConfig: undefined,
+                selection: {
+                    slugs: parseSelectionSlugs(body.slugs),
+                    includeSiteConfig: body.includeSiteConfig
+                }
+            });
+            if (isSelectionFailure(selection)) {
+                return jsonResponse({ ok: false, error: selection.error }, { status: 400, cors });
+            }
+            const pages = selection.pages;
             const slugs = pages.map((p) => p.slug);
             /*
              * Every exit below records what happened, because the alternative was a
@@ -772,28 +880,7 @@ export function createOrchestrator(config = {}) {
                 record(true, "Nothing written — the adapter has no onPublish");
                 return jsonResponse({ ok: true, written: false, count: pages.length, reason: "adapter has no onPublish; publish is a no-op" }, { status: 200, cors });
             }
-            const config = getSiteConfig(scopedSession);
-            /*
-             * Hand the adapter the baseline it needs to diff.
-             *
-             * `onPublish(pages)` alone is a snapshot contract, and a snapshot is not
-             * invertible: every CMS read is a projection, so writing the projection
-             * back replaces an asset reference with a URL and a document reference
-             * with a dead href. A publisher has to compare against what it read, and
-             * it cannot compare against nothing.
-             *
-             * This is the copy the bootstrap already took, not a fresh read — a
-             * second `getPages()` here is 45 sequential Sanity calls on the
-             * integration that motivated it. It used to be absent for the rest of a
-             * process's life after a restart that reloaded the draft from SQLite,
-             * which quietly disabled publishing for any adapter that refuses without
-             * a baseline; `ensure` now recovers it on the first request instead.
-             *
-             * It can still be undefined — the adapter read can fail, and baselines
-             * are evicted FIFO — so the contract is unchanged: treat undefined as
-             * "no baseline available" and never as "the site was empty".
-             */
-            const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
+            const config = selection.siteConfig;
             const context = body.assets || published
                 ? { ...(body.assets ? { assets: body.assets } : {}), ...(published ? { published } : {}) }
                 : undefined;
@@ -1201,19 +1288,30 @@ export function createOrchestrator(config = {}) {
             // would report every page as missing because there are none.
             const scoped = scope(body.session, body.siteId);
             await runtime.bootstrapCache.ensure(scoped, runtime.adapter, runtime.log);
-            return actionResponse(await runChecksAction(body, runtime.log), cors);
+            /*
+             * `siteId` has to be the *effective* one, not whatever the caller sent.
+             *
+             * The action scopes the session itself, and it was being handed a body
+             * with no `siteId` — so a library-mode site bootstrapped the right
+             * session here and then scanned `"<session>"` instead of
+             * `"<siteId>::<session>"`. That key holds the demo seed, so the checker
+             * reported on Avocado's own sample pages: a real tri-lingual site with
+             * sixty pages got findings for `/olives` and `/blueberries`, and none of
+             * its own content was ever examined.
+             */
+            return actionResponse(await runChecksAction(withSiteId(body), runtime.log), cors);
         }
         if (request.method === "GET" && path === "/checks/findings") {
             const runtime = await getRuntime();
             await runtime.ready;
             const query = Object.fromEntries(url.searchParams);
-            return actionResponse(await listFindingsAction(query, runtime.log), cors);
+            return actionResponse(await listFindingsAction(withSiteId(query), runtime.log), cors);
         }
         if (request.method === "GET" && path === "/checks/runs") {
             const runtime = await getRuntime();
             await runtime.ready;
             const query = Object.fromEntries(url.searchParams);
-            return actionResponse(await listCheckRunsAction(query), cors);
+            return actionResponse(await listCheckRunsAction(withSiteId(query)), cors);
         }
         if (request.method === "POST" && path === "/checks/findings/status") {
             const runtime = await getRuntime();
@@ -1225,7 +1323,7 @@ export function createOrchestrator(config = {}) {
             catch {
                 return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
             }
-            return actionResponse(await updateFindingAction((raw ?? {})), cors);
+            return actionResponse(await updateFindingAction(withSiteId((raw ?? {}))), cors);
         }
         if (request.method === "GET" && path === "/history/status") {
             const runtime = await getRuntime();
@@ -1239,7 +1337,7 @@ export function createOrchestrator(config = {}) {
             const query = Object.fromEntries(url.searchParams);
             return actionResponse(historyLog(query), cors);
         }
-        if (request.method === "POST" && (path === "/history/undo" || path === "/history/redo" || path === "/history/restore")) {
+        if (request.method === "POST" && (path === "/history/undo" || path === "/history/redo" || path === "/history/restore" || path === "/history/discard")) {
             const runtime = await getRuntime();
             await runtime.ready;
             let raw;
@@ -1259,6 +1357,8 @@ export function createOrchestrator(config = {}) {
                     : null;
             if (action)
                 return actionResponse(action(body, runtime.log), cors);
+            if (path === "/history/discard")
+                return actionResponse(historyDiscardAction(body, runtime.log), cors);
             return actionResponse(historyRestoreAction(body, runtime.log), cors);
         }
         /*
@@ -1553,6 +1653,7 @@ export function createOrchestrator(config = {}) {
             const query = typeof body.query === "string" ? body.query.trim() : "";
             const page = Math.max(1, Math.trunc(Number(body.page) || 1));
             const limit = Math.min(50, Math.max(1, Math.trunc(Number(body.limit) || 20)));
+            const kind = body.kind === "file" ? "file" : "image";
             const source = typeof runtime.adapter?.getMedia === "function"
                 ? runtime.adapter.getMedia.bind(runtime.adapter)
                 : mediaSourceFromUnknown(body.config);
@@ -1562,14 +1663,101 @@ export function createOrchestrator(config = {}) {
             if (!source)
                 return jsonResponse({ error: "CMS media not configured" }, { status: 404, cors });
             try {
-                const result = await source({ query: query || undefined, page, limit });
-                return jsonResponse(result, { cors });
+                const result = await source({ query: query || undefined, page, limit, kind });
+                /*
+                 * Filter by kind on the way out as well as asking for it on the way in.
+                 *
+                 * An adapter written before documents existed ignores `kind` and
+                 * returns its images to a request for files. Trusting the response
+                 * would offer those images as PDFs. Filtering here means such an
+                 * adapter degrades to an empty document tab — which is the truth about
+                 * it — instead of to a wrong one, and costs a correct adapter nothing.
+                 */
+                const items = (result.items ?? []).filter((item) => (item.kind ?? "image") === kind);
+                /*
+                 * Whether this site takes uploads rides back on the read.
+                 *
+                 * The editor asks for the file list before it can offer a link picker,
+                 * so answering "and you may add one" here costs no round trip — and it
+                 * keeps the control's existence tied to a method that exists, rather
+                 * than to an assumption the UI made.
+                 */
+                const canUpload = typeof runtime.adapter?.uploadMedia === "function";
+                return jsonResponse({ ...result, items, canUpload }, { cors });
             }
             catch (error) {
                 runtime.log.warn?.({ err: error }, "[avocado] CMS media read failed");
                 return jsonResponse({ items: [], totalPages: 0 }, { cors });
             }
         }
+        /*
+         * Adding a document (or an image) to the site's own media library.
+         *
+         * The counterpart of `/media/cms`. The site's adapter decides where the
+         * bytes go, because only it knows: a static site writes into `public/`, a
+         * Sanity site uploads an asset and gets back a CDN URL. Deliberately NOT
+         * routed through `/image/upload`, which writes to the orchestrator's local
+         * disk — that storage loses every file on an ephemeral redeploy, and
+         * putting documents on it would spread a known defect instead of leaving it
+         * contained to the one POC route that has it.
+         *
+         * No `uploadMedia` is 404, not 500: the editor asks once and hides the
+         * control, exactly as it does for the read side.
+         */
+        if (request.method === "POST" && path === "/media/upload") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const upload = runtime.adapter?.uploadMedia;
+            if (typeof upload !== "function") {
+                return jsonResponse({ error: "this site does not accept uploads" }, { status: 404, cors });
+            }
+            let form;
+            try {
+                form = await request.formData();
+            }
+            catch {
+                return jsonResponse({ error: "expected multipart/form-data" }, { status: 400, cors });
+            }
+            const file = form.get("file");
+            if (!(file instanceof File)) {
+                return jsonResponse({ error: "no file in the request" }, { status: 400, cors });
+            }
+            if (file.size > MEDIA_UPLOAD_MAX_BYTES) {
+                return jsonResponse({ error: `file is larger than ${Math.floor(MEDIA_UPLOAD_MAX_BYTES / 1_000_000)}MB` }, { status: 413, cors });
+            }
+            const rawKind = form.get("kind");
+            const kind = rawKind === "file" ? "file" : "image";
+            try {
+                const item = await upload.call(runtime.adapter, {
+                    // Untrusted, and passed on as such: the adapter is the only thing that
+                    // knows what a safe name is in its own store, and sanitising here
+                    // would be guessing on its behalf.
+                    filename: file.name,
+                    contentType: file.type || "",
+                    data: new Uint8Array(await file.arrayBuffer()),
+                    kind
+                });
+                /*
+                 * Drop the cached asset list, so the file somebody just added is
+                 * linkable in the same breath — by the picker, by the checker, and by
+                 * the planner's site context. Waiting out the 30-second cache would
+                 * make a fresh upload look like a broken link.
+                 */
+                invalidateSiteAssets();
+                return jsonResponse({ item }, { cors });
+            }
+            catch (error) {
+                /*
+                 * The adapter's message reaches the editor. A refusal is usually a
+                 * sentence a person needs to read — "we only accept PDFs", "a file of
+                 * that name already exists" — and swallowing it would leave the upload
+                 * control saying only that something went wrong.
+                 */
+                const reason = error instanceof Error ? error.message : String(error);
+                runtime.log.warn?.({ err: reason }, "[avocado] media upload refused");
+                return jsonResponse({ error: reason }, { status: 400, cors });
+            }
+        }
         /* The Unsplash tab of the image picker. Unconfigured answers 404, not an
          * empty result set — "no key" and "no matches" are different answers. */
         if (request.method === "GET" && path === "/unsplash/search") {

package/dist/http/history-actions.d.ts

@@ -56,3 +56,46 @@ export declare function historyRestoreAction(body: {
     siteId?: string;
     targetVersion?: number;
 }, log: Logger): ActionResult;
+/** One page rolled back, and how far. */
+export type DiscardedPage = {
+    slug: string;
+    /** The earliest selected version on this page — the change being undone. */
+    fromVersion: number;
+    /** The version whose snapshot the page now holds, or null if it went away. */
+    toVersion: number | null;
+    /**
+     * Entries on this page at or after `fromVersion` that the rollback also
+     * takes out. A page has one timeline, so discarding a change in the middle
+     * of it necessarily discards what was built on top.
+     */
+    alsoDiscarded: number[];
+};
+/** A selected entry that could not be rolled back, and why. */
+export type SkippedDiscard = {
+    version: number;
+    reason: string;
+};
+/**
+ * Throw away selected changes by rolling each affected page back to the state
+ * it held immediately before the earliest change selected on it.
+ *
+ * The version log is a per-page timeline, not a stack of independent patches:
+ * an entry records the page *after* the change, so "undo this one change and
+ * keep the later ones" is not a question the stored data can answer. What it
+ * can answer is "put this page back the way it was before change N", which is
+ * what discarding means here — and it is why the response names every later
+ * entry that goes with it. The caller shows that list before asking the user
+ * to confirm; this function reports it again for whatever actually happened.
+ *
+ * Selecting several entries on one page collapses to its earliest. Selecting
+ * entries across pages rolls each page back independently — untouched pages
+ * keep their edits.
+ *
+ * Like a restore, a discard is itself an edit: the current page goes onto the
+ * undo stack first, so a discard can be undone.
+ */
+export declare function historyDiscardAction(body: {
+    session?: string;
+    siteId?: string;
+    versions?: unknown;
+}, log: Logger): ActionResult;

package/dist/http/history-actions.js

@@ -167,3 +167,125 @@ export function historyRestoreAction(body, log) {
         }
     };
 }
+/**
+ * Throw away selected changes by rolling each affected page back to the state
+ * it held immediately before the earliest change selected on it.
+ *
+ * The version log is a per-page timeline, not a stack of independent patches:
+ * an entry records the page *after* the change, so "undo this one change and
+ * keep the later ones" is not a question the stored data can answer. What it
+ * can answer is "put this page back the way it was before change N", which is
+ * what discarding means here — and it is why the response names every later
+ * entry that goes with it. The caller shows that list before asking the user
+ * to confirm; this function reports it again for whatever actually happened.
+ *
+ * Selecting several entries on one page collapses to its earliest. Selecting
+ * entries across pages rolls each page back independently — untouched pages
+ * keep their edits.
+ *
+ * Like a restore, a discard is itself an edit: the current page goes onto the
+ * undo stack first, so a discard can be undone.
+ */
+export function historyDiscardAction(body, log) {
+    if (!body.session)
+        return badRequest("session is required");
+    const requested = Array.isArray(body.versions)
+        ? Array.from(new Set(body.versions.filter((v) => typeof v === "number" && Number.isFinite(v))))
+        : [];
+    if (requested.length === 0)
+        return badRequest("versions must be a non-empty array of version numbers");
+    const session = scopedSessionKey(body.session, body.siteId);
+    const entries = versionLog.get(session) ?? [];
+    const byVersion = new Map(entries.map((entry) => [entry.version, entry]));
+    const skipped = [];
+    /*
+     * Collapse to one rollback per page. A selection of three entries on the
+     * same page is one rollback to before the earliest of them; running three
+     * would have the second and third restore snapshots the first already
+     * invalidated.
+     */
+    const earliestBySlug = new Map();
+    for (const version of requested) {
+        const entry = byVersion.get(version);
+        if (!entry) {
+            skipped.push({ version, reason: "not in this session's version log" });
+            continue;
+        }
+        const current = earliestBySlug.get(entry.slug);
+        if (current === undefined || version < current)
+            earliestBySlug.set(entry.slug, version);
+    }
+    const discarded = [];
+    let previewVersion = versions.get(session) ?? 0;
+    let navigateToSlug;
+    for (const [slug, fromVersion] of earliestBySlug) {
+        /*
+         * The state before `fromVersion` is the snapshot of the newest earlier
+         * entry on the same page. An entry with no snapshot is a legacy row that
+         * cannot restore anything, so it does not count as the prior state.
+         */
+        const prior = entries
+            .filter((entry) => entry.slug === slug && entry.version < fromVersion && entry.snapshot !== undefined)
+            .at(-1);
+        if (!prior) {
+            /*
+             * Nothing recorded before this change — the log was capped, or this is
+             * the page's first entry. Guessing would mean inventing a state the
+             * page never had, so the entry stays and the caller is told why.
+             */
+            skipped.push({
+                version: fromVersion,
+                reason: "no recorded page state before this change"
+            });
+            continue;
+        }
+        const alsoDiscarded = entries
+            .filter((entry) => entry.slug === slug && entry.version >= fromVersion)
+            .map((entry) => entry.version)
+            .filter((version) => version !== fromVersion);
+        // Filtered above, so this only maps the impossible `undefined` onto the
+        // `null` that means "the page did not exist at this version".
+        const snapshot = prior.snapshot ?? null;
+        // pushUndo also clears redo, which is right: a discard starts a new branch.
+        pushUndo(session, slug, getPage(session, slug));
+        if (snapshot === null)
+            removePage(session, slug);
+        else
+            setPage(session, structuredClone(snapshot));
+        previewVersion = bumpVersion(session);
+        const count = alsoDiscarded.length + 1;
+        pushVersionEntry(session, {
+            version: previewVersion,
+            slug,
+            summary: `Discarded ${count} change${count === 1 ? "" : "s"} — back to v${prior.version}`,
+            opTypes: [],
+            opCount: 0,
+            source: "restore",
+            snapshot: snapshot === null ? null : structuredClone(snapshot)
+        });
+        discarded.push({ slug, fromVersion, toVersion: snapshot === null ? null : prior.version, alsoDiscarded });
+        navigateToSlug = slug;
+    }
+    if (discarded.length === 0) {
+        return {
+            code: 400,
+            body: { error: "nothing could be discarded", skipped }
+        };
+    }
+    schedulePersistState(log);
+    const touched = discarded[discarded.length - 1].slug;
+    const undoList = getHistoryMap(historyUndo, session).get(touched) ?? [];
+    const redoList = getHistoryMap(historyRedo, session).get(touched) ?? [];
+    return {
+        code: 200,
+        body: {
+            status: "applied",
+            previewVersion,
+            discarded,
+            skipped,
+            ...(navigateToSlug ? { navigateToSlug } : {}),
+            canUndo: undoList.length > 0,
+            canRedo: redoList.length > 0
+        }
+    };
+}

package/dist/http/publish-actions.d.ts

@@ -35,6 +35,16 @@ export type PublishedContent = {
     pages: PageDoc[];
     siteConfig?: SiteConfig | null;
 };
+/**
+ * Where the published side came from, in descending order of trust.
+ *
+ * A diff can be computed from any of them — a wrong diff only misreports. A
+ * *partial* publish cannot: it merges the unselected pages back out of this
+ * baseline and ships them, so a baseline that is really the startup demo seed
+ * would overwrite the live site with demo content. `"memory"` therefore
+ * disqualifies a subset publish; see `publish-selection.ts`.
+ */
+export type PublishedPagesSource = "site" | "file" | "memory";
 /**
  * Where the published side comes from. The monorepo answers it from the site
  * app; a library-mode consumer answers it from its CMS adapter, whose
@@ -65,6 +75,7 @@ export declare function loadPublishedForDiff(opts: {
 }): Promise<{
     pages: PageDoc[];
     siteConfig: SiteConfig | null;
+    source: PublishedPagesSource;
 }>;
 /**
  * The default source: the four-step monorepo chain above, unchanged, so the

package/dist/http/publish-actions.js

@@ -91,7 +91,7 @@ export async function loadPublishedForDiff(opts) {
     }
     // Hot path: remote returned both pages and siteConfig.
     if (remotePages && remoteSiteConfig) {
-        return { pages: remotePages, siteConfig: remoteSiteConfig };
+        return { pages: remotePages, siteConfig: remoteSiteConfig, source: "site" };
     }
     // Either the remote didn't run, didn't include siteConfig (older SDK or
     // site dev not yet restarted), or didn't include pages. Read the JSON file
@@ -101,9 +101,9 @@ export async function loadPublishedForDiff(opts) {
     const pages = remotePages ?? fromFile.pages;
     const siteConfig = remoteSiteConfig ?? fromFile.siteConfig;
     if (pages)
-        return { pages, siteConfig };
+        return { pages, siteConfig, source: remotePages ? "site" : "file" };
     logger.warn("publish/diff: falling back to in-memory publishedPages — diff may be inaccurate");
-    return { pages: Array.from(publishedPages.values()), siteConfig };
+    return { pages: Array.from(publishedPages.values()), siteConfig, source: "memory" };
 }
 /**
  * The default source: the four-step monorepo chain above, unchanged, so the

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { createOrchestrator, type CreateOrchestratorConfig, type OrchestratorHandler } from "./handler/create-orchestrator.ts";
 export type { OrchestratorAuth, AuthContext } from "./handler/auth.ts";
-export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, CmsMediaItem, CmsMediaPage, CmsMediaQuery, ResolvedCapabilities } from "./cms/adapter.ts";
-export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel, type JsonFileAdapterOptions, type EditorApiAdapterOptions, type CmsMediaSource, type CmsMediaSourceConfig } from "./cms/index.ts";
+export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, CmsMediaItem, CmsMediaPage, CmsMediaQuery, CmsMediaUpload, ResolvedCapabilities } from "./cms/adapter.ts";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel, type JsonFileAdapterOptions, type EditorApiAdapterOptions, type CmsMediaSource, type CmsMediaUploader, type CmsMediaSourceConfig } from "./cms/index.ts";
 export { registerPublishTarget, selectPublishTarget, getPublishTarget, listPublishTargets } from "./publish/publish-target-registry.ts";
 export type { PublishTarget, PublishContext, PublishOutcome, PublishStatus, PublishResult } from "./publish/publish-target.ts";
 export { SqliteDurableStore, InMemoryDurableStore, getDurableStore, resetDurableStore, setDurableStore, durableStoreIsEphemeral, type SqliteDurableStoreOptions, type InMemoryDurableStoreOptions, type DurableStore, type FindingInput, type FindingRecord, type FindingQuery, type FindingSeverity, type FindingStatus, type FindingEvidence, type CheckRunInput, type CheckRunRecord, type CheckRunPatch, type CheckRunTrigger, type MemoryInput, type MemoryRecord, type MemoryQuery, type MemoryScope, type MemoryKind, type MemorySource, type MemoryStatus, type CorrectionInput, type CorrectionRecord, type CorrectionQuery, type CorrectionOutcome, type ProposalInput, type ProposalRecord, type ProposalQuery, type ProposalStatus } from "./durable/index.ts";

package/dist/index.js

@@ -18,7 +18,7 @@
 //
 // The Fastify HTTP wrapper lives in apps/orchestrator and imports from here.
 export { createOrchestrator } from "./handler/create-orchestrator.js";
-export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "./cms/index.js";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel } from "./cms/index.js";
 // The publish-target plugin point. `docs-site/integration/publishing.mdx` has
 // documented this as the way to publish somewhere we do not ship a target for
 // since before the package had an export map, and told the reader to import it

package/dist/nlp/intent-detection.d.ts

@@ -282,12 +282,28 @@ export declare function adviceResponse(args: {
 };
 export declare function plannerMessageWithPendingContext(session: string, message: string): string;
 /** Build the site context lines without wrapping in a message. Returns null if empty. */
+/** How many documents ride along in a planner request. */
+export declare const SITE_CONTEXT_DOCUMENT_CAP = 60;
 export declare function buildSiteContextBlock(args?: {
     sitePurpose?: string;
     siteHosting?: string;
     businessContext?: ChatRequestBody["businessContext"];
     siteContext?: ChatRequestBody["siteContext"];
     pageDirectory?: string;
+    /**
+     * The site's downloadable documents, so the planner can link one.
+     *
+     * Without it, "link the winter menu" is unanswerable: the model has the
+     * page list and the block schemas and no idea the site holds fifteen PDFs,
+     * so it invents a plausible path — which is exactly how a link to a
+     * misspelled filename gets written in the first place. Listed by path and
+     * name, because the path is what goes in the link and the name is what the
+     * user said.
+     */
+    documents?: Array<{
+        path: string;
+        name?: string;
+    }>;
 }): string | null;
 export declare function withSiteContext(message: string, args?: {
     sitePurpose?: string;