@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/ops/ops-engine.d.ts

@@ -22,7 +22,18 @@ export declare function isNoEffectiveChangeError(reason: string): boolean;
  */
 export declare function isAlreadyCurrentError(reason: string): boolean;
 export declare function classifyGuardrailError(reason: string): GuardrailErrorCategory;
-export declare function formatValidationError(reason: string): string;
+/**
+ * `category` is the one the failure was actually thrown with, for callers that
+ * still hold it. Without it this falls back to reading the category back out of
+ * the message, which is a guess — see `isRepairEligibleCategory`.
+ */
+export declare function formatValidationError(reason: string, category?: GuardrailErrorCategory): string;
+/**
+ * The deterministic repair pass exists for plans that are structurally wrong
+ * but fixable — a bad prop name, an id that clashes. Anything else is either
+ * hopeless or not the planner's fault, and re-prompting it wastes a model call.
+ */
+export declare function isRepairEligibleCategory(category: GuardrailErrorCategory): category is "schema_violation";
 export declare function isDeterministicRepairEligible(reason: string): boolean;
 /**
  * Extracts structured fields from a planner schema_violation reason so the

package/dist/ops/ops-engine.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { blockSchemas, operationSchema, validateBlockProps, findManifestSchemaIssue, isChrome, isInBlockCatalogue, catalogueBlockTypes, mapSemanticThemeTokens, generateItemId, isRichTextDoc, fromMarkdown, mergeRichTextDoc } from "@avocadostudio-ai/shared";
+import { blockSchemas, operationSchema, validateBlockProps, findManifestSchemaIssue, isChrome, getMediaFields, isInBlockCatalogue, catalogueBlockTypes, mapSemanticThemeTokens, generateItemId, isRichTextDoc, fromMarkdown, mergeRichTextDoc } from "@avocadostudio-ai/shared";
 import { normalizeRouteCandidate } from "../nlp/intent-helpers.js";
 import { pageIdFromSlug, pageTitleFromSlug } from "../nlp/plan-normalizer.js";
 import { OperationError, toErrorDetail as _unifiedToErrorDetail } from "../errors.js";
@@ -88,7 +88,17 @@ function remapRouteReference(value, fromSlug, toSlug) {
     }
     return value;
 }
-function rewriteRouteLinksInValue(input, fromSlug, toSlug) {
+/**
+ * Rewrite every route reference under `input` from `fromSlug` to `toSlug`.
+ *
+ * The walk is permissive by design — it remaps any string that starts with the
+ * old slug, whatever prop holds it — because a custom block ships no field
+ * metadata and its links still have to survive a rename. `mediaKeys` is the one
+ * exception: props that address a *resource* rather than a page. Renaming
+ * `/pricing` to `/plans` does not move `/pricing/demo.mp4`, and before this the
+ * walker rewrote that path too, quietly breaking the asset.
+ */
+function rewriteRouteLinksInValue(input, fromSlug, toSlug, mediaKeys) {
     if (typeof input === "string") {
         const mapped = remapRouteReference(input, fromSlug, toSlug);
         return { value: mapped, changed: mapped !== input };
@@ -96,7 +106,7 @@ function rewriteRouteLinksInValue(input, fromSlug, toSlug) {
     if (Array.isArray(input)) {
         let changed = false;
         const next = input.map((item) => {
-            const mapped = rewriteRouteLinksInValue(item, fromSlug, toSlug);
+            const mapped = rewriteRouteLinksInValue(item, fromSlug, toSlug, mediaKeys);
             if (mapped.changed)
                 changed = true;
             return mapped.value;
@@ -109,11 +119,8 @@ function rewriteRouteLinksInValue(input, fromSlug, toSlug) {
     let changed = false;
     const next = {};
     for (const [key, value] of Object.entries(source)) {
-        if (typeof value === "string" && key.toLowerCase().includes("href")) {
-            const mapped = remapRouteReference(value, fromSlug, toSlug);
-            if (mapped !== value)
-                changed = true;
-            next[key] = mapped;
+        if (mediaKeys.has(key)) {
+            next[key] = value;
             continue;
         }
         if (typeof value === "string" && key === "body") {
@@ -128,7 +135,7 @@ function rewriteRouteLinksInValue(input, fromSlug, toSlug) {
             next[key] = rewritten;
             continue;
         }
-        const mapped = rewriteRouteLinksInValue(value, fromSlug, toSlug);
+        const mapped = rewriteRouteLinksInValue(value, fromSlug, toSlug, mediaKeys);
         if (mapped.changed)
             changed = true;
         next[key] = mapped.value;
@@ -138,7 +145,7 @@ function rewriteRouteLinksInValue(input, fromSlug, toSlug) {
 function rewriteLinksToRenamedPage(page, fromSlug, toSlug) {
     let changed = false;
     const nextBlocks = page.blocks.map((block) => {
-        const mapped = rewriteRouteLinksInValue(block.props, fromSlug, toSlug);
+        const mapped = rewriteRouteLinksInValue(block.props, fromSlug, toSlug, getMediaFields(block.type));
         if (!mapped.changed)
             return block;
         changed = true;
@@ -208,16 +215,36 @@ export function classifyGuardrailError(reason) {
         lower.includes("required") ||
         lower.includes("unknown props") ||
         lower.includes("out of range") ||
-        lower.includes("must be")) {
+        lower.includes("must be") ||
+        // Every "already exists" this engine raises — a duplicate block id, a page
+        // slug that is taken — it raises *as* a schema_violation. This list did not
+        // know the word, so a plan one renamed id away from applying classified as
+        // `internal_error`, which the repair pass refuses to touch. Callers holding
+        // the thrown error should prefer its `category` over this function; the
+        // keyword is here for the paths that only ever had the string.
+        lower.includes("already exists")) {
         return "schema_violation";
     }
     return "internal_error";
 }
-export function formatValidationError(reason) {
-    return `${classifyGuardrailError(reason)}: ${reason}`;
+/**
+ * `category` is the one the failure was actually thrown with, for callers that
+ * still hold it. Without it this falls back to reading the category back out of
+ * the message, which is a guess — see `isRepairEligibleCategory`.
+ */
+export function formatValidationError(reason, category) {
+    return `${category ?? classifyGuardrailError(reason)}: ${reason}`;
+}
+/**
+ * The deterministic repair pass exists for plans that are structurally wrong
+ * but fixable — a bad prop name, an id that clashes. Anything else is either
+ * hopeless or not the planner's fault, and re-prompting it wastes a model call.
+ */
+export function isRepairEligibleCategory(category) {
+    return category === "schema_violation";
 }
 export function isDeterministicRepairEligible(reason) {
-    return classifyGuardrailError(reason) === "schema_violation";
+    return isRepairEligibleCategory(classifyGuardrailError(reason));
 }
 /**
  * Extracts structured fields from a planner schema_violation reason so the

package/dist/publish/publish-helpers.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from "../logger.ts";
-import { type PageDoc } from "@avocadostudio-ai/shared";
+import { type PageDoc, type SiteConfig } from "@avocadostudio-ai/shared";
 import { type PublishTracker } from "../state/session-state.ts";
 export declare function deploymentIdFromAny(input: string): string | undefined;
 export declare function refreshPublishStatusFromVercel(current: PublishTracker): Promise<PublishTracker>;
@@ -44,7 +44,17 @@ export declare function collectInlineAssets(pages: PageDoc[], generatedImageDir:
  * Best-effort: failures are silently ignored.
  */
 export declare function recordPublishSnapshot(session: string, pages: PageDoc[], log?: Logger, siteConfig?: Record<string, unknown>): Promise<string | undefined>;
-export declare function publishViaGit(session: string): Promise<{
+/**
+ * `content` is what the route decided to publish. It defaults to the whole
+ * session draft, which is what this read for itself before the argument
+ * existed and what a full publish still computes. A partial publish passes the
+ * merged set instead — live site plus the selected pages — and re-reading the
+ * draft here would quietly publish everything anyway.
+ */
+export declare function publishViaGit(session: string, content?: {
+    pages: PageDoc[];
+    siteConfig: SiteConfig;
+}): Promise<{
     status: "failed";
     session: string;
     slugs: string[];

package/dist/publish/publish-helpers.js

@@ -392,13 +392,20 @@ function sanitizeBranch(input) {
     const trimmed = input.trim();
     return trimmed.length > 0 ? trimmed : "main";
 }
-export async function publishViaGit(session) {
+/**
+ * `content` is what the route decided to publish. It defaults to the whole
+ * session draft, which is what this read for itself before the argument
+ * existed and what a full publish still computes. A partial publish passes the
+ * merged set instead — live site plus the selected pages — and re-reading the
+ * draft here would quietly publish everything anyway.
+ */
+export async function publishViaGit(session, content) {
     const repoRoot = resolve(process.cwd(), "../..");
     const targetPath = "apps/site/lib/published-content.json";
     const absoluteTargetPath = resolve(repoRoot, targetPath);
     const branch = sanitizeBranch(process.env.PUBLISH_GIT_BRANCH ?? "main");
     const strict = process.env.PUBLISH_GIT_STRICT === "1";
-    let pages = getSessionPages(session);
+    let pages = content?.pages ?? getSessionPages(session);
     const slugs = pages.map((page) => page.slug);
     // Rewrite localhost image URLs → relative paths and copy files into public/
     const imageUrlMap = findLocalhostImageUrls(pages);
@@ -421,7 +428,7 @@ export async function publishViaGit(session) {
         }
         pages = rewriteImageUrlsInPages(pages, imageUrlMap);
     }
-    const siteConfig = getSiteConfig(session);
+    const siteConfig = content?.siteConfig ?? getSiteConfig(session);
     const payload = `${JSON.stringify({ pages, siteConfig }, null, 2)}\n`;
     await writeFile(absoluteTargetPath, payload, "utf8");
     const statusRaw = await runGit(["status", "--porcelain"], repoRoot);

package/dist/publish/publish-selection.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Publishing some of the draft rather than all of it.
+ *
+ * The editor's publish dialog lists every changed page and lets the user tick
+ * the ones to ship. Turning that tick list into something a publish target can
+ * receive is not filtering, and the difference is the whole point of this file.
+ *
+ * `PublishContext.pages` is a snapshot: "make the site be this". Every
+ * built-in target reads it that way — the git target serialises it to
+ * `published-content.json`, the site-contract target POSTs it to
+ * `/api/editor/publish`, a CMS adapter diffs it against what it read. Handing
+ * any of them the four pages the user ticked would not publish four pages; it
+ * would publish a four-page site and take the other fifty-six down. That is
+ * the same class of bug as the three in b4b58a5f — content destroyed by an
+ * edit that was only ever asked to change part of it.
+ *
+ * So a subset publish is a *merge*: start from what is live, overwrite the
+ * selected slugs with their draft versions, and leave every other page exactly
+ * as the live site already has it. A diffing adapter then finds changes only
+ * in the selected pages, because the rest are byte-identical to the baseline
+ * it read. A snapshot target writes a site that differs from the current one
+ * only in the selected pages. Both contracts come out right, and neither
+ * target needs to know a subset was requested.
+ *
+ * It follows that a subset publish is impossible without knowing what is live.
+ * `selectPagesForPublish` says so rather than guessing — the caller refuses
+ * the publish instead of shipping a site assembled from a baseline it does not
+ * have.
+ */
+import type { PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+export type PublishSelection = {
+    /**
+     * Slugs to publish. `undefined` means "publish everything", which is the
+     * old behaviour and skips this module entirely.
+     */
+    slugs?: readonly string[];
+    /**
+     * Whether the site-wide config (header, nav, footer chrome) ships too. It
+     * is one more tick box in the dialog and lives outside the page tree, so it
+     * is selected separately. Defaults to true, matching a full publish.
+     */
+    includeSiteConfig?: boolean;
+};
+export type SelectedPublish = {
+    /** The merged page set to hand a publish target. */
+    pages: PageDoc[];
+    /** The config to hand it — draft or published, per `includeSiteConfig`. */
+    siteConfig: SiteConfig;
+    /** Slugs whose content this publish actually changes. */
+    selectedSlugs: string[];
+    /** Selected slugs that are live now and are being taken down. */
+    removedSlugs: string[];
+};
+export type SelectionFailure = {
+    error: string;
+};
+export type SelectionResult = SelectedPublish | SelectionFailure;
+export declare function isSelectionFailure(result: SelectionResult): result is SelectionFailure;
+/**
+ * Normalise what the client sent.
+ *
+ * Sending the field at all is the request for a subset; its length is not. An
+ * empty array means "no pages", which is a real thing to ask for — the publish
+ * dialog can have every page unticked and the site header ticked — and the two
+ * mistakes are not symmetrical: reading `[]` as "everything" ships pages the
+ * user just unticked, while reading it as "no pages" republishes what is
+ * already live and changes nothing. Only an absent or malformed field means
+ * the whole draft, which is what every caller meant before this existed.
+ */
+export declare function parseSelectionSlugs(raw: unknown): string[] | undefined;
+/**
+ * Build the page set and config for a publish that covers only `slugs`.
+ *
+ * `published` is what the live site currently holds. `null`/`undefined` means
+ * the caller could not find out, which is a refusal rather than an empty site
+ * — see the note at the top of this file.
+ */
+export declare function selectPagesForPublish(opts: {
+    draft: readonly PageDoc[];
+    published: readonly PageDoc[] | null | undefined;
+    draftSiteConfig: SiteConfig;
+    publishedSiteConfig?: SiteConfig | null;
+    selection: PublishSelection;
+}): SelectionResult;

package/dist/publish/publish-selection.js

@@ -0,0 +1,113 @@
+/**
+ * Publishing some of the draft rather than all of it.
+ *
+ * The editor's publish dialog lists every changed page and lets the user tick
+ * the ones to ship. Turning that tick list into something a publish target can
+ * receive is not filtering, and the difference is the whole point of this file.
+ *
+ * `PublishContext.pages` is a snapshot: "make the site be this". Every
+ * built-in target reads it that way — the git target serialises it to
+ * `published-content.json`, the site-contract target POSTs it to
+ * `/api/editor/publish`, a CMS adapter diffs it against what it read. Handing
+ * any of them the four pages the user ticked would not publish four pages; it
+ * would publish a four-page site and take the other fifty-six down. That is
+ * the same class of bug as the three in b4b58a5f — content destroyed by an
+ * edit that was only ever asked to change part of it.
+ *
+ * So a subset publish is a *merge*: start from what is live, overwrite the
+ * selected slugs with their draft versions, and leave every other page exactly
+ * as the live site already has it. A diffing adapter then finds changes only
+ * in the selected pages, because the rest are byte-identical to the baseline
+ * it read. A snapshot target writes a site that differs from the current one
+ * only in the selected pages. Both contracts come out right, and neither
+ * target needs to know a subset was requested.
+ *
+ * It follows that a subset publish is impossible without knowing what is live.
+ * `selectPagesForPublish` says so rather than guessing — the caller refuses
+ * the publish instead of shipping a site assembled from a baseline it does not
+ * have.
+ */
+export function isSelectionFailure(result) {
+    return "error" in result;
+}
+/**
+ * Normalise what the client sent.
+ *
+ * Sending the field at all is the request for a subset; its length is not. An
+ * empty array means "no pages", which is a real thing to ask for — the publish
+ * dialog can have every page unticked and the site header ticked — and the two
+ * mistakes are not symmetrical: reading `[]` as "everything" ships pages the
+ * user just unticked, while reading it as "no pages" republishes what is
+ * already live and changes nothing. Only an absent or malformed field means
+ * the whole draft, which is what every caller meant before this existed.
+ */
+export function parseSelectionSlugs(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const slugs = raw.filter((s) => typeof s === "string" && s.trim().length > 0).map((s) => s.trim());
+    return Array.from(new Set(slugs));
+}
+/**
+ * Build the page set and config for a publish that covers only `slugs`.
+ *
+ * `published` is what the live site currently holds. `null`/`undefined` means
+ * the caller could not find out, which is a refusal rather than an empty site
+ * — see the note at the top of this file.
+ */
+export function selectPagesForPublish(opts) {
+    const { draft, published, draftSiteConfig, publishedSiteConfig, selection } = opts;
+    const slugs = selection.slugs;
+    // No subset asked for: the full draft, unchanged, exactly as before.
+    if (!slugs) {
+        return { pages: [...draft], siteConfig: draftSiteConfig, selectedSlugs: draft.map((p) => p.slug), removedSlugs: [] };
+    }
+    if (!published) {
+        return {
+            error: "Cannot publish selected pages without knowing what is currently live. " +
+                "Publish everything, or retry once the published site is reachable."
+        };
+    }
+    const draftBySlug = new Map(draft.map((page) => [page.slug, page]));
+    const publishedBySlug = new Map(published.map((page) => [page.slug, page]));
+    const unknown = slugs.filter((slug) => !draftBySlug.has(slug) && !publishedBySlug.has(slug));
+    if (unknown.length > 0) {
+        return { error: `Unknown page${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}` };
+    }
+    const selected = new Set(slugs);
+    const pages = [];
+    const removedSlugs = [];
+    /*
+     * Live pages first, in the order the live site has them, so an unselected
+     * page keeps its position as well as its content. A selected page that the
+     * draft no longer has is a deletion the user ticked: drop it here and record
+     * it, so the summary can say a page came down rather than silently omitting
+     * it.
+     */
+    for (const page of published) {
+        if (!selected.has(page.slug)) {
+            pages.push(page);
+            continue;
+        }
+        const draftPage = draftBySlug.get(page.slug);
+        if (draftPage)
+            pages.push(draftPage);
+        else
+            removedSlugs.push(page.slug);
+    }
+    // Selected pages the live site does not have yet, in draft order.
+    for (const page of draft) {
+        if (!selected.has(page.slug))
+            continue;
+        if (publishedBySlug.has(page.slug))
+            continue;
+        pages.push(page);
+    }
+    /*
+     * Leaving the header out has to mean shipping the header that is live, not
+     * shipping nothing: the targets take a config, and an absent one reads as
+     * "clear the site chrome". When the published config is unknown the draft's
+     * is the only one there is — the same value a full publish would send.
+     */
+    const siteConfig = selection.includeSiteConfig === false ? publishedSiteConfig ?? draftSiteConfig : draftSiteConfig;
+    return { pages, siteConfig, selectedSlugs: [...slugs], removedSlugs };
+}

package/dist/publish/publish-target-registry.js

@@ -10,7 +10,7 @@ import { DeployHookPublishTarget } from "./targets/deploy-hook.js";
  * handling requests:
  *
  * ```ts
- * import { registerPublishTarget } from "./publish/publish-target-registry.js"
+ * import { registerPublishTarget } from "@avocadostudio-ai/orchestrator-core"
  * registerPublishTarget(new S3PublishTarget())
  * ```
  *

package/dist/publish/publish-target.d.ts

@@ -6,7 +6,7 @@ import type { PublishTracker } from "../state/session-state.ts";
  * up writing content. Built-ins cover git + Vercel, a site-contract POST, and
  * a raw Vercel deploy hook. Third parties (S3, GitLab Pages, custom CI, etc.)
  * implement {@link PublishTarget} and register via
- * {@link registerPublishTarget} from `./publish-target-registry.js`.
+ * {@link registerPublishTarget} from `@avocadostudio-ai/orchestrator-core`.
  *
  * The route handler's job shrinks to: build {@link PublishContext}, call
  * {@link selectPublishTarget}, invoke `target.publish(ctx)`, save the returned

package/dist/publish/targets/git.js

@@ -10,8 +10,8 @@ import { publishViaGit } from "../publish-helpers.js";
 export class GitPublishTarget {
     name = "git";
     async publish(ctx) {
-        const { session, scopedSession, slugs } = ctx;
-        const result = await publishViaGit(scopedSession);
+        const { session, scopedSession, slugs, pages, siteConfig } = ctx;
+        const result = await publishViaGit(scopedSession, { pages, siteConfig });
         const now = new Date().toISOString();
         const tracker = {
             session,

package/dist/state/session-state.js

@@ -3,6 +3,7 @@ import { dirname, resolve } from "node:path";
 import { demoPublishedPages, demoSiteConfig, ensureItemIds, IMAGE_PLACEHOLDER } from "@avocadostudio-ai/shared";
 import { toErrorDetail as _unifiedToErrorDetail } from "../errors.js";
 import { archiveMigratedJson, getStore, notePersistenceFailure, notePersistenceSuccess, readLegacyJson, resolveDbFile, resolveJsonMigrationTtlDays, sweepStaleMigrations, } from "./sqlite-store-singleton.js";
+import { discardPendingProposalsForSession, sweepExpiredProposals } from "../durable/durable-store-singleton.js";
 // Re-exported so callers that already depend on this module for state can ask
 // whether that state is actually being kept, without a second import path.
 export { persistenceHealth, persistenceWarning } from "./sqlite-store-singleton.js";
@@ -173,6 +174,9 @@ export function forgetSession(sessionKey) {
     pendingClarificationBySession.delete(sessionKey);
     chatHistoryBySession.delete(sessionKey);
     pendingApprovalPlanBySession.delete(sessionKey);
+    // Session ids are caller-supplied and routinely reused, so a pending proposal
+    // left behind here would rehydrate into the *next* session with this id.
+    discardPendingProposalsForSession(sessionKey);
     imageSourcePreferenceBySession.delete(sessionKey);
     publishStatusBySession.delete(sessionKey);
     capabilitiesBySession.delete(sessionKey);
@@ -1091,12 +1095,15 @@ const EPHEMERAL_MAP_CAP = 500; // max entries for maps without timestamps
  */
 export function evictStaleEphemeralMaps() {
     const now = Date.now();
-    // pendingApprovalPlanBySession: has createdAt — evict by age
+    // pendingApprovalPlanBySession: has createdAt — evict by age. The durable
+    // mirror carries the same TTL as `expiresAt`, so both halves age out together
+    // rather than the Map forgetting a plan the store would hand straight back.
     for (const [key, plan] of pendingApprovalPlanBySession) {
         if (now - new Date(plan.createdAt).getTime() > APPROVAL_PLAN_TTL_MS) {
             pendingApprovalPlanBySession.delete(key);
         }
     }
+    sweepExpiredProposals();
     // publishStatusBySession: has updatedAt — evict by age
     for (const [key, tracker] of publishStatusBySession) {
         if (now - new Date(tracker.updatedAt).getTime() > PUBLISH_STATUS_TTL_MS) {

package/dist/state/site-assets.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The documents this site holds, for the parts of the process that cannot ask.
+ *
+ * The list comes from `CmsAdapter.getMedia`, and getting it is IO. Two very
+ * different consumers need it and neither has an adapter in scope:
+ *
+ *   - `content.file-link-unknown`, which turns a hand-typed PDF path into
+ *     something verifiable, and which is a pure function by construction;
+ *   - the planner's site context, so "link the winter menu" can resolve to a
+ *     path that exists instead of a plausible-looking invention.
+ *
+ * So it is registered once per process, which is what an adapter already is:
+ * `createOrchestrator` sets it when the host implements `getMedia`, and the
+ * standalone multi-site orchestrator — which wires no adapter — never does.
+ *
+ * Unregistered answers `undefined`, and that is load-bearing everywhere it is
+ * read. `undefined` is "this site cannot list its documents", under which no
+ * rule may call a link broken; `[]` is "it listed them and has none", under
+ * which every document link really is broken. Collapsing the two would report
+ * every document on every site without a media library as missing.
+ */
+export type SiteAssetRecord = {
+    path: string;
+    name?: string;
+    contentType?: string;
+    size?: number;
+};
+type AssetLister = () => Promise<SiteAssetRecord[]>;
+/** Registered by `createOrchestrator` when the site's adapter can list files. */
+export declare function setSiteAssetLister(lister: AssetLister | null): void;
+/** Drop the cache — called after an upload, so a new file is visible at once. */
+export declare function invalidateSiteAssets(): void;
+/**
+ * The site's documents, or `undefined` if it cannot say.
+ *
+ * A lister that throws also answers `undefined`: a media library that is *down*
+ * must not read as a media library that is *empty*, or one outage becomes a
+ * finding on every document link on the site.
+ */
+export declare function getSiteAssets(now?: () => number): Promise<SiteAssetRecord[] | undefined>;
+export {};

package/dist/state/site-assets.js

@@ -0,0 +1,40 @@
+let listSiteAssets = null;
+/** Registered by `createOrchestrator` when the site's adapter can list files. */
+export function setSiteAssetLister(lister) {
+    listSiteAssets = lister;
+    cache = null;
+}
+/*
+ * A publish fans out one check run and an apply debounces into another, and a
+ * chat turn asks as well; going to the CMS three times in ten seconds is waste
+ * the site pays for. Short enough that a document uploaded mid-session is
+ * picked up almost immediately — and an upload clears it outright, so the file
+ * somebody just added is linkable in the same breath.
+ */
+const CACHE_MS = 30_000;
+let cache = null;
+/** Drop the cache — called after an upload, so a new file is visible at once. */
+export function invalidateSiteAssets() {
+    cache = null;
+}
+/**
+ * The site's documents, or `undefined` if it cannot say.
+ *
+ * A lister that throws also answers `undefined`: a media library that is *down*
+ * must not read as a media library that is *empty*, or one outage becomes a
+ * finding on every document link on the site.
+ */
+export async function getSiteAssets(now = Date.now) {
+    if (!listSiteAssets)
+        return undefined;
+    if (cache && now() - cache.at < CACHE_MS)
+        return cache.assets;
+    try {
+        const assets = await listSiteAssets();
+        cache = { at: now(), assets };
+        return assets;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -23,8 +23,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "^0.3.2",
-    "@avocadostudio-ai/shared": "^0.3.2"
+    "@avocadostudio-ai/migration-sdk": "^0.4.0",
+    "@avocadostudio-ai/shared": "^0.4.0"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",