@avocadostudio-ai/orchestrator-core 0.22.0 → 0.23.0

package/dist/agents/inbox.d.ts

@@ -0,0 +1,141 @@
+import type { FindingRecord, InboxItemKind, InboxItemRecord, InboxItemStatus } from "../durable/types.ts";
+import { type Logger } from "../logger.ts";
+import { type FixDeps } from "./fix-writer.ts";
+import { type SiteAgents } from "./settings.ts";
+export type InboxEntryKind = InboxItemKind | "finding";
+export type InboxEntry = {
+    /** `item:<id>` or `findings:<ruleId>` — stable across reads. */
+    id: string;
+    source: "item" | "findings";
+    kind: InboxEntryKind;
+    agent: string;
+    object: string;
+    verb: string;
+    title: string;
+    summary?: string;
+    slugs: string[];
+    impact: number;
+    status: InboxItemStatus;
+    createdAt: number;
+    updatedAt: number;
+    revision?: number;
+    assignee?: string;
+    blocksPublish?: boolean;
+    payload?: Record<string, unknown>;
+    resolution?: string;
+    resolvedBy?: string;
+    resolvedAt?: number;
+    note?: string;
+    /** For a findings group: every finding in it, highest impact first. */
+    findings?: FindingRecord[];
+    /** For a findings group: how many carry ops that fix them — a rule's own, or a written fix. */
+    fixable?: number;
+    /** For a findings group: how many a fix could be written for and has not been yet. */
+    writable?: number;
+    /** A reverted alert whose revert can still be taken back from the Inbox. */
+    undoable?: boolean;
+};
+export type InboxView = {
+    entries: InboxEntry[];
+    counts: {
+        needsYou: number;
+        done: number;
+    };
+    /** Open alerts holding publish, by slug. The publish dialog reads this. */
+    blocking: Array<{
+        id: string;
+        slugs: string[];
+        title: string;
+    }>;
+    agents: SiteAgents;
+    /** Pass back as `since` to learn whether anything changed. */
+    cursor: number;
+};
+/** How many closed items the Done tab shows. */
+export declare const DONE_TAB_LIMIT = 50;
+/** One card per rule, over every open finding of an enabled agent. */
+/** The agent a finding answers to: a custom agent by its own id, a draft rule by its job. */
+export declare function agentOfFinding(finding: Pick<FindingRecord, "agent" | "ruleId">): string;
+export declare function groupFindings(findings: FindingRecord[], enabled: (agent: string) => boolean): InboxEntry[];
+export declare function buildInboxView(scopeKey: string, now?: number): Promise<InboxView>;
+/**
+ * Open alerts that hold publishing any of `slugs`. With no slugs, every open
+ * hold for the site — a whole-site publish ships every page.
+ */
+export declare function publishHolds(scopeKey: string, slugs?: string[]): Promise<InboxItemRecord[]>;
+export type FindingDecisionOutcome = {
+    applied: string[];
+    /** Re-checked on approve and no longer present — closed, nothing applied. */
+    alreadyFixed: string[];
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+    previewVersion?: number;
+};
+/**
+ * Approve the fixes of one or more findings.
+ *
+ * A finding's ops were written when the checker last ran, and the page may
+ * have changed since. So approving re-runs the rule over the page first
+ * (rules are free and instant) and applies the ops the rule proposes *now*:
+ * if the problem is gone the finding closes as already fixed, and if it is
+ * still there the fix is written against the page as it is (SO-17).
+ */
+export declare function approveFindings(args: {
+    scopeKey: string;
+    ids: string[];
+    by?: string;
+    /** A written fix's text as the person edited it, by finding id. */
+    edits?: Record<string, string>;
+    log?: Logger;
+}): Promise<FindingDecisionOutcome>;
+export type WriteFixesOutcome = {
+    written: Array<{
+        id: string;
+        text: string;
+    }>;
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+};
+/** How many fixes one request may write: each is a model call. */
+export declare const WRITE_FIXES_MAX = 20;
+/**
+ * Write fixes for open findings, on request (agents/fix-writer.ts). Nothing
+ * is applied: each fix is stored on its finding for a person to approve,
+ * edit or reject. Site facts go to the model with every request, so a fix
+ * follows the site's own rules about wording.
+ */
+export declare function writeFixes(args: {
+    scopeKey: string;
+    ids: string[];
+    deps?: FixDeps;
+    log?: Logger;
+}): Promise<WriteFixesOutcome>;
+/**
+ * Reject findings, with the reason a person gave. Recorded as a correction so
+ * the rule's track record counts it; the finding is dismissed, and a dismissal
+ * survives every re-run.
+ */
+export declare function rejectFindings(args: {
+    scopeKey: string;
+    ids: string[];
+    reason: string;
+    by?: string;
+    log?: Logger;
+}): Promise<FindingDecisionOutcome>;
+/**
+ * The publish gate (site-ops-agents.md SO-18): an open Edit safety alert on a
+ * page that is about to ship refuses the publish, with no override flag. The
+ * way through is one click in the alert — revert, or say it was meant — so the
+ * one moment every change is guaranteed to be looked at is not skippable.
+ *
+ * Returns the 409 to send, or null when nothing holds. With no selection the
+ * whole draft ships, so any hold on the site counts.
+ */
+export declare function publishHoldResponse(scopeKey: string, selectedSlugs?: string[] | null, log?: Logger): Promise<{
+    code: 409;
+    body: Record<string, unknown>;
+} | null>;

package/dist/agents/inbox.js

@@ -0,0 +1,360 @@
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { evaluateDraftChecks } from "../checks/run-checks.js";
+import { getDurableStore } from "../durable/durable-store-singleton.js";
+import { consoleLogger } from "../logger.js";
+import { applyOpsAtomically, toErrorDetail } from "../ops/ops-engine.js";
+import { bumpVersion, getPage, getSessionDraft, getSiteConfig, pushUndo, pushVersionEntry, schedulePersistState } from "../state/session-state.js";
+import { getSiteAssets } from "../state/site-assets.js";
+import { agentForRule } from "./builtins.js";
+import { isCustomAgentId } from "./spec.js";
+import { withoutPages } from "./edit-safety-resolve.js";
+import { currentValue, fixFieldFor, fixOps, writeFix } from "./fix-writer.js";
+import { listSiteFacts, recordOutcome } from "./learning.js";
+import { resolveSiteAgents } from "./settings.js";
+/** How many closed items the Done tab shows. */
+export const DONE_TAB_LIMIT = 50;
+function entryFromItem(stored) {
+    const item = withoutPages(stored);
+    const pages = stored.payload?.revertedPages;
+    const undoable = stored.status === "resolved" && stored.resolution === "reverted" && !!pages && Object.keys(pages).length > 0;
+    return {
+        ...(undoable ? { undoable: true } : {}),
+        id: `item:${item.id}`,
+        source: "item",
+        kind: item.kind,
+        agent: item.agent,
+        object: item.object,
+        verb: item.verb,
+        title: item.title,
+        ...(item.summary ? { summary: item.summary } : {}),
+        slugs: item.slugs,
+        impact: item.impact ?? 0,
+        status: item.status,
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+        revision: item.revision,
+        ...(item.assignee ? { assignee: item.assignee } : {}),
+        ...(item.blocksPublish ? { blocksPublish: true } : {}),
+        ...(item.payload ? { payload: item.payload } : {}),
+        ...(item.resolution ? { resolution: item.resolution } : {}),
+        ...(item.resolvedBy ? { resolvedBy: item.resolvedBy } : {}),
+        ...(item.resolvedAt != null ? { resolvedAt: item.resolvedAt } : {}),
+        ...(item.note ? { note: item.note } : {})
+    };
+}
+function pagesLabel(slugs) {
+    return slugs.length === 1 ? slugs[0] : `${slugs.length} pages`;
+}
+/** One card per rule, over every open finding of an enabled agent. */
+/** The agent a finding answers to: a custom agent by its own id, a draft rule by its job. */
+export function agentOfFinding(finding) {
+    return isCustomAgentId(finding.agent) ? finding.agent : agentForRule(finding.ruleId);
+}
+export function groupFindings(findings, enabled) {
+    const byRule = new Map();
+    for (const finding of findings) {
+        if (finding.status !== "open")
+            continue;
+        if (!enabled(agentOfFinding(finding)))
+            continue;
+        const list = byRule.get(finding.ruleId) ?? [];
+        list.push(finding);
+        byRule.set(finding.ruleId, list);
+    }
+    const out = [];
+    for (const [ruleId, list] of byRule) {
+        list.sort((a, b) => b.impact - a.impact);
+        const first = list[0];
+        const slugs = [...new Set(list.map((f) => f.slug))];
+        const fixable = list.filter((f) => (f.proposedOps?.length ?? 0) > 0 || (f.fix?.ops.length ?? 0) > 0).length;
+        const writable = list.filter((f) => fixFieldFor(f.ruleId) && !f.fix).length;
+        const agent = agentOfFinding(first);
+        out.push({
+            id: `findings:${ruleId}`,
+            source: "findings",
+            kind: "finding",
+            agent,
+            object: pagesLabel(slugs),
+            verb: list.length === 1 ? `found: ${first.title}` : `found ${list.length} like: ${first.title}`,
+            title: list.length === 1
+                ? `${first.title} on ${first.slug}`
+                : `${first.title} — and ${list.length - 1} more like it on ${pagesLabel(slugs)}`,
+            ...(first.detail ? { summary: first.detail } : {}),
+            slugs,
+            impact: first.impact,
+            status: "open",
+            createdAt: Math.min(...list.map((f) => f.firstSeenAt)),
+            updatedAt: Math.max(...list.map((f) => f.lastSeenAt)),
+            findings: list,
+            fixable,
+            ...(writable > 0 ? { writable } : {})
+        });
+    }
+    return out;
+}
+export async function buildInboxView(scopeKey, now = Date.now()) {
+    const store = getDurableStore();
+    const agents = await resolveSiteAgents(scopeKey, store);
+    const isOn = (agentId) => agents.agents.find((a) => a.agentId === agentId)?.enabled ?? false;
+    await store.wakeSnoozedFindings(scopeKey, now);
+    const [openItems, closedItems, findings] = await Promise.all([
+        store.listInboxItems({ scopeKey, status: "open", limit: 500 }),
+        store.listInboxItems({ scopeKey, status: ["resolved", "expired"], limit: DONE_TAB_LIMIT }),
+        store.listFindings({ scopeKey, status: "open" })
+    ]);
+    // Held back while it is still in front of the person in the chat turn —
+    // but it holds publish from the first second regardless.
+    const visibleOpen = openItems.filter((item) => item.visibleFrom == null || item.visibleFrom <= now);
+    const entries = [
+        ...visibleOpen.map(entryFromItem),
+        ...groupFindings(findings, isOn),
+        ...closedItems.map(entryFromItem)
+    ];
+    entries.sort((a, b) => {
+        if (a.status === "open" && b.status !== "open")
+            return -1;
+        if (b.status === "open" && a.status !== "open")
+            return 1;
+        if (a.status === "open")
+            return b.impact - a.impact || b.updatedAt - a.updatedAt;
+        return (b.resolvedAt ?? b.updatedAt) - (a.resolvedAt ?? a.updatedAt);
+    });
+    return {
+        entries,
+        counts: {
+            needsYou: entries.filter((e) => e.status === "open").length,
+            done: entries.filter((e) => e.status !== "open").length
+        },
+        blocking: openItems
+            .filter((item) => item.blocksPublish)
+            .map((item) => ({ id: item.id, slugs: item.slugs, title: item.title })),
+        agents,
+        cursor: now
+    };
+}
+/**
+ * Open alerts that hold publishing any of `slugs`. With no slugs, every open
+ * hold for the site — a whole-site publish ships every page.
+ */
+export async function publishHolds(scopeKey, slugs) {
+    const open = await getDurableStore().listInboxItems({ scopeKey, status: "open", limit: 500 });
+    const wanted = slugs && slugs.length > 0 ? new Set(slugs) : null;
+    return open.filter((item) => item.blocksPublish && (!wanted || item.slugs.some((slug) => wanted.has(slug))));
+}
+async function freshFindings(scopeKey, slugs) {
+    const assets = await getSiteAssets();
+    return evaluateDraftChecks({
+        scopeKey,
+        pages: [...getSessionDraft(scopeKey).values()],
+        manifest: buildBlockManifest(),
+        siteConfig: getSiteConfig(scopeKey),
+        slugs,
+        ...(assets ? { assets } : {})
+    }).findings;
+}
+/**
+ * Approve the fixes of one or more findings.
+ *
+ * A finding's ops were written when the checker last ran, and the page may
+ * have changed since. So approving re-runs the rule over the page first
+ * (rules are free and instant) and applies the ops the rule proposes *now*:
+ * if the problem is gone the finding closes as already fixed, and if it is
+ * still there the fix is written against the page as it is (SO-17).
+ */
+export async function approveFindings(args) {
+    const store = getDurableStore();
+    const outcome = { applied: [], alreadyFixed: [], failed: [] };
+    const records = [];
+    for (const id of args.ids) {
+        const record = await store.getFinding(id);
+        if (!record || record.scopeKey !== args.scopeKey) {
+            outcome.failed.push({ id, error: "finding not found" });
+            continue;
+        }
+        if (record.status !== "open") {
+            outcome.failed.push({ id, error: `finding is ${record.status}` });
+            continue;
+        }
+        records.push(record);
+    }
+    if (records.length === 0)
+        return outcome;
+    const fresh = new Map((await freshFindings(args.scopeKey, [...new Set(records.map((r) => r.slug))])).map((f) => [f.fingerprint, f]));
+    const touched = new Map();
+    const appliedOps = [];
+    let lastSlug;
+    for (const record of records) {
+        const current = fresh.get(record.fingerprint);
+        if (!current) {
+            await store.setFindingStatus(record.id, "fixed");
+            outcome.alreadyFixed.push(record.id);
+            continue;
+        }
+        const page = getPage(args.scopeKey, record.slug);
+        let ops = current.proposedOps ?? [];
+        let edited = false;
+        if (ops.length === 0 && record.fix) {
+            // A written fix is applied only to the value it was written against
+            // (SO-17). Somebody changed the field since: the fix is stale, and is
+            // dropped rather than laid over their change.
+            if (!page || currentValue(record, page) !== record.fix.base) {
+                await store.setFindingFix(record.id, null);
+                outcome.failed.push({ id: record.id, error: "the page changed since this fix was written — write it again" });
+                continue;
+            }
+            const edit = args.edits?.[record.id]?.replace(/\s+/g, " ").trim();
+            edited = !!edit && edit !== record.fix.text;
+            ops = edited ? fixOps(record, edit) : record.fix.ops;
+        }
+        if (ops.length === 0) {
+            outcome.failed.push({ id: record.id, error: "this finding has no fix to apply" });
+            continue;
+        }
+        try {
+            const before = page ? structuredClone(page) : null;
+            await applyOpsAtomically(args.scopeKey, ops);
+            if (!touched.has(record.slug))
+                touched.set(record.slug, before);
+            appliedOps.push(...ops);
+            lastSlug = record.slug;
+            await store.setFindingStatus(record.id, "fixed");
+            outcome.applied.push(record.id);
+            await recordOutcome({
+                scopeKey: args.scopeKey,
+                traceId: record.id,
+                slug: record.slug,
+                request: record.title,
+                proposed: edited && record.fix ? record.fix.ops : ops,
+                outcome: edited ? "edited" : "accepted",
+                applied: ops,
+                log: args.log
+            });
+        }
+        catch (error) {
+            outcome.failed.push({ id: record.id, error: toErrorDetail(error) });
+        }
+    }
+    if (appliedOps.length > 0 && lastSlug) {
+        for (const [slug, snapshot] of touched)
+            pushUndo(args.scopeKey, slug, snapshot);
+        const previewVersion = bumpVersion(args.scopeKey);
+        const snapshot = getPage(args.scopeKey, lastSlug);
+        pushVersionEntry(args.scopeKey, {
+            version: previewVersion,
+            slug: lastSlug,
+            summary: `Approved ${outcome.applied.length} ${outcome.applied.length === 1 ? "fix" : "fixes"} from the Inbox`,
+            opTypes: appliedOps.map((op) => op.op),
+            opCount: appliedOps.length,
+            source: "direct",
+            actor: { kind: "user", ...(args.by ? { id: args.by } : {}) },
+            snapshot: snapshot ? structuredClone(snapshot) : null
+        });
+        schedulePersistState(args.log ?? consoleLogger());
+        outcome.previewVersion = previewVersion;
+    }
+    return outcome;
+}
+/** How many fixes one request may write: each is a model call. */
+export const WRITE_FIXES_MAX = 20;
+/**
+ * Write fixes for open findings, on request (agents/fix-writer.ts). Nothing
+ * is applied: each fix is stored on its finding for a person to approve,
+ * edit or reject. Site facts go to the model with every request, so a fix
+ * follows the site's own rules about wording.
+ */
+export async function writeFixes(args) {
+    const store = getDurableStore();
+    const outcome = { written: [], failed: [] };
+    const facts = args.deps?.facts ?? (await listSiteFacts(args.scopeKey)).map((fact) => fact.value);
+    for (const id of args.ids.slice(0, WRITE_FIXES_MAX)) {
+        const record = await store.getFinding(id);
+        if (!record || record.scopeKey !== args.scopeKey) {
+            outcome.failed.push({ id, error: "finding not found" });
+            continue;
+        }
+        if (record.status !== "open") {
+            outcome.failed.push({ id, error: `finding is ${record.status}` });
+            continue;
+        }
+        const page = getPage(args.scopeKey, record.slug);
+        if (!page) {
+            outcome.failed.push({ id, error: `no page ${record.slug}` });
+            continue;
+        }
+        try {
+            const result = await writeFix(record, page, { ...args.deps, facts });
+            if (!result.ok) {
+                outcome.failed.push({ id, error: result.error });
+                continue;
+            }
+            await store.setFindingFix(id, result.fix);
+            outcome.written.push({ id, text: result.fix.text });
+        }
+        catch (error) {
+            args.log?.warn({ err: String(error), id }, "[inbox] writing a fix failed");
+            outcome.failed.push({ id, error: toErrorDetail(error) });
+        }
+    }
+    return outcome;
+}
+/**
+ * Reject findings, with the reason a person gave. Recorded as a correction so
+ * the rule's track record counts it; the finding is dismissed, and a dismissal
+ * survives every re-run.
+ */
+export async function rejectFindings(args) {
+    const store = getDurableStore();
+    const outcome = { applied: [], alreadyFixed: [], failed: [] };
+    for (const id of args.ids) {
+        const record = await store.getFinding(id);
+        if (!record || record.scopeKey !== args.scopeKey) {
+            outcome.failed.push({ id, error: "finding not found" });
+            continue;
+        }
+        await store.setFindingStatus(id, "dismissed");
+        outcome.applied.push(id);
+        await recordOutcome({
+            scopeKey: args.scopeKey,
+            traceId: record.id,
+            slug: record.slug,
+            request: `${record.ruleId}: ${record.title} — rejected${args.by ? ` by ${args.by}` : ""}: ${args.reason}`,
+            proposed: record.proposedOps ?? [],
+            outcome: "rejected",
+            log: args.log
+        });
+    }
+    return outcome;
+}
+/**
+ * The publish gate (site-ops-agents.md SO-18): an open Edit safety alert on a
+ * page that is about to ship refuses the publish, with no override flag. The
+ * way through is one click in the alert — revert, or say it was meant — so the
+ * one moment every change is guaranteed to be looked at is not skippable.
+ *
+ * Returns the 409 to send, or null when nothing holds. With no selection the
+ * whole draft ships, so any hold on the site counts.
+ */
+export async function publishHoldResponse(scopeKey, selectedSlugs, log) {
+    let holds;
+    try {
+        holds = await publishHolds(scopeKey, selectedSlugs ?? undefined);
+    }
+    catch (error) {
+        // A store that cannot be read holds nothing: the gate must not become a
+        // way for a database outage to stop every publish.
+        log?.warn({ err: error }, "[inbox] publish holds unavailable; publishing without the Edit safety gate");
+        return null;
+    }
+    if (holds.length === 0)
+        return null;
+    const slugs = [...new Set(holds.flatMap((hold) => hold.slugs))];
+    return {
+        code: 409,
+        body: {
+            status: "failed",
+            error: `Publishing is held: Edit safety found damage on ${slugs.join(", ")} that nobody has decided on yet. Revert it or mark it intended, then publish.`,
+            errorCode: "edit_safety_hold",
+            holds: holds.map((hold) => ({ id: hold.id, slugs: hold.slugs, title: hold.title }))
+        }
+    };
+}

package/dist/agents/learning.d.ts

@@ -0,0 +1,32 @@
+import type { Operation } from "@avocadostudio-ai/shared";
+import type { CorrectionOutcome, MemoryRecord } from "../durable/types.ts";
+import type { Logger } from "../logger.ts";
+/**
+ * Record what a person did with something an agent or the planner proposed:
+ * approved it, edited it first, rejected it, or undid it. Best-effort — a
+ * store failure is logged and never fails the action that produced it.
+ */
+export declare function recordOutcome(args: {
+    scopeKey: string;
+    traceId: string;
+    slug?: string;
+    request: string;
+    proposed: Operation[];
+    outcome: CorrectionOutcome;
+    applied?: Operation[];
+    log?: Logger;
+}): Promise<void>;
+/** The kinds a person can state about their site. `decision` is an agent's to write. */
+export declare const SITE_FACT_KINDS: readonly ["fact", "preference", "glossary"];
+export type SiteFactKind = (typeof SITE_FACT_KINDS)[number];
+export declare function isSiteFactKind(value: unknown): value is SiteFactKind;
+/** How many facts reach the planner. The rest stay visible in the editor. */
+export declare const SITE_FACTS_IN_PROMPT = 40;
+/** Longer than this and a "fact" is a document; it belongs in the site's content. */
+export declare const SITE_FACT_MAX_CHARS = 280;
+export declare function listSiteFacts(scopeKey: string, limit?: number): Promise<MemoryRecord[]>;
+/**
+ * The lines the planner is given. Never throws — a planner turn does not fail
+ * because memory could not be read; it plans without it, as it did before.
+ */
+export declare function siteFactsForPlanner(scopeKey: string, log?: Logger): Promise<string[]>;

package/dist/agents/learning.js

@@ -0,0 +1,71 @@
+import { getDurableStore, noteDurableFailure } from "../durable/durable-store-singleton.js";
+/*
+ * Memory and corrections, wired in (site-ops-agents.md SO-10, SO-11).
+ *
+ * Both tables shipped with the durable store and had no caller outside it.
+ * This module is the only way the rest of the brain reaches them, so each
+ * answer a person gives is recorded one way, and each read the planner makes
+ * is fenced the same way.
+ */
+/**
+ * Record what a person did with something an agent or the planner proposed:
+ * approved it, edited it first, rejected it, or undid it. Best-effort — a
+ * store failure is logged and never fails the action that produced it.
+ */
+export async function recordOutcome(args) {
+    try {
+        await getDurableStore().recordCorrection({
+            traceId: args.traceId,
+            scopeKey: args.scopeKey,
+            ...(args.slug ? { slug: args.slug } : {}),
+            request: args.request.slice(0, 2_000),
+            proposed: args.proposed,
+            outcome: args.outcome,
+            ...(args.applied ? { applied: args.applied } : {})
+        });
+    }
+    catch (error) {
+        noteDurableFailure(error instanceof Error ? error.message : String(error));
+        args.log?.warn({ err: error, traceId: args.traceId }, "[learning] correction not recorded");
+    }
+}
+// ---------------------------------------------------------------------------
+// Site facts
+// ---------------------------------------------------------------------------
+/** The kinds a person can state about their site. `decision` is an agent's to write. */
+export const SITE_FACT_KINDS = ["fact", "preference", "glossary"];
+export function isSiteFactKind(value) {
+    return typeof value === "string" && SITE_FACT_KINDS.includes(value);
+}
+/** How many facts reach the planner. The rest stay visible in the editor. */
+export const SITE_FACTS_IN_PROMPT = 40;
+/** Longer than this and a "fact" is a document; it belongs in the site's content. */
+export const SITE_FACT_MAX_CHARS = 280;
+export async function listSiteFacts(scopeKey, limit = 200) {
+    return getDurableStore().listMemory({
+        scopeKey,
+        scope: "site",
+        kind: [...SITE_FACT_KINDS],
+        status: "active",
+        limit
+    });
+}
+/**
+ * The lines the planner is given. Never throws — a planner turn does not fail
+ * because memory could not be read; it plans without it, as it did before.
+ */
+export async function siteFactsForPlanner(scopeKey, log) {
+    try {
+        const facts = await listSiteFacts(scopeKey, SITE_FACTS_IN_PROMPT);
+        if (facts.length === 0)
+            return [];
+        void getDurableStore()
+            .touchMemory(facts.map((fact) => fact.id))
+            .catch(() => { });
+        return facts.map((fact) => fact.value);
+    }
+    catch (error) {
+        log?.warn({ err: error }, "[learning] site facts unavailable; planning without them");
+        return [];
+    }
+}

package/dist/agents/mention.d.ts

@@ -0,0 +1,76 @@
+import type { PageDoc } from "@avocadostudio-ai/shared";
+import type { DurableStore } from "../durable/types.ts";
+export type MentionIntent = "run" | "report" | "pause" | "resume" | "week" | "list" | "help";
+export type MentionFinding = {
+    slug: string;
+    title: string;
+};
+export type MentionResult = {
+    handled: false;
+} | {
+    handled: true;
+    kind: "ran";
+    agentId: string;
+    slug?: string;
+    opened: number;
+    closed: number;
+    open: number;
+    top: MentionFinding[];
+} | {
+    handled: true;
+    kind: "report";
+    agentId: string;
+    open: number;
+    top: MentionFinding[];
+} | {
+    handled: true;
+    kind: "paused" | "resumed" | "already";
+    agentId: string;
+    enabled: boolean;
+} | {
+    handled: true;
+    kind: "week";
+    since: number;
+    agents: Array<{
+        agentId: string;
+        found: number;
+        fixed: number;
+        open: number;
+    }>;
+    caught: number;
+    reverted: number;
+} | {
+    handled: true;
+    kind: "list";
+    agents: Array<{
+        agentId: string;
+        handle: string;
+        enabled: boolean;
+        open: number;
+    }>;
+} | {
+    handled: true;
+    kind: "help";
+    agentId?: string;
+    handles: string[];
+} | {
+    handled: true;
+    kind: "refused";
+    agentId: string;
+    reason: "not_runnable" | "off" | "needs_owner" | "unknown_page";
+    slug?: string;
+};
+/** An agent's handle in chat: its id, without the `custom:` prefix. */
+export declare function handleOf(agentId: string): string;
+export declare function parseIntent(rest: string, all: boolean): MentionIntent;
+/** The first `/path` in the message that is a page on this site. */
+export declare function pageIn(rest: string, pages: PageDoc[]): {
+    slug?: string;
+    unknown?: string;
+};
+export declare function handleMention(args: {
+    scopeKey: string;
+    message: string;
+    store?: DurableStore;
+    now?: number;
+}): Promise<MentionResult>;