@avocadostudio-ai/orchestrator-core 0.22.0 → 0.23.0

package/dist/checks/run-checks.js

@@ -16,16 +16,19 @@ import { DRAFT_RULES } from "./rules-draft.js";
 export function fingerprintFor(scopeKey, slug, ruleId, key = "") {
     return createHash("sha256").update([scopeKey, slug, ruleId, key].join("\u0000")).digest("hex").slice(0, 32);
 }
-export async function runDraftChecks(args) {
-    const store = args.store ?? getDurableStore();
-    const now = args.now ?? Date.now;
+/**
+ * The rules over a site, with no store and no run ledger — pure in-memory work
+ * over the pages given. `runDraftChecks` records what this returns; the first
+ * run's backtest and the re-check before a fix is applied use it directly,
+ * because neither may write a finding.
+ */
+export function evaluateDraftChecks(args) {
     const rules = args.rules ?? DRAFT_RULES;
-    const runId = args.runId ?? randomUUID();
-    const startedAt = now();
     const site = {
         slugs: args.pages.map((p) => p.slug),
         pages: args.pages.map((p) => ({ slug: p.slug, title: p.title, ...(p.meta ? { meta: p.meta } : {}) })),
         config: args.siteConfig ?? {},
+        page: (slug) => args.pages.find((p) => p.slug === slug),
         // Present only when the caller could enumerate the site's documents.
         // Passing `[]` where it could not would make every file link report broken.
         ...(args.assets ? { assets: args.assets } : {})
@@ -50,73 +53,85 @@ export async function runDraftChecks(args) {
         linksBySlug.set(page.slug, walkPageLinks(page, args.manifest));
     }
     const weights = computePageWeights({ pages: site.pages, fieldsBySlug, config: site.config });
+    const findings = [];
+    const seen = new Set();
+    let error;
+    for (const page of scanned) {
+        const pageWeight = weights.get(page.slug)?.weight ?? NEUTRAL_PAGE_WEIGHT;
+        const ctx = {
+            scopeKey: args.scopeKey,
+            page,
+            site,
+            manifest: args.manifest,
+            fields: fieldsBySlug.get(page.slug) ?? [],
+            links: linksBySlug.get(page.slug) ?? []
+        };
+        for (const rule of rules) {
+            // One rule throwing must not cost the run every other rule's findings —
+            // a checker that goes dark because a custom block had an unexpected
+            // prop shape is worse than one that reports twelve of thirteen rules.
+            let produced;
+            try {
+                produced = rule.run(ctx);
+            }
+            catch (err) {
+                error ??= `${rule.id}: ${err instanceof Error ? err.message : String(err)}`;
+                continue;
+            }
+            for (const finding of produced) {
+                const fingerprint = fingerprintFor(args.scopeKey, page.slug, rule.id, finding.key);
+                /*
+                 * Two findings from one rule sharing a key are one finding as far as
+                 * the store is concerned — the second upsert overwrites the first.
+                 * Collapsing them here instead keeps the ledger honest (the second
+                 * was being counted as an `updated` row) and makes which one survives
+                 * a decision rather than an accident of iteration order.
+                 */
+                if (seen.has(fingerprint))
+                    continue;
+                seen.add(fingerprint);
+                const severity = finding.severity ?? rule.severity;
+                findings.push({
+                    fingerprint,
+                    scopeKey: args.scopeKey,
+                    slug: page.slug,
+                    ruleId: rule.id,
+                    agent: rule.agent,
+                    severity,
+                    impact: impactFor(severity, pageWeight),
+                    title: finding.title,
+                    ...(finding.detail ? { detail: finding.detail } : {}),
+                    ...(finding.evidence ? { evidence: finding.evidence } : {}),
+                    ...(finding.proposedOps ? { proposedOps: finding.proposedOps } : {})
+                });
+            }
+        }
+    }
+    return { findings, scannedSlugs: scanned.map((p) => p.slug), ...(error ? { error } : {}) };
+}
+export async function runDraftChecks(args) {
+    const store = args.store ?? getDurableStore();
+    const now = args.now ?? Date.now;
+    const rules = args.rules ?? DRAFT_RULES;
+    const runId = args.runId ?? randomUUID();
+    const startedAt = now();
     await store.startCheckRun({
         id: runId,
         scopeKey: args.scopeKey,
-        agent: rules.length === 1 ? rules[0].agent : "checks",
+        agent: args.agent ?? (rules.length === 1 ? rules[0].agent : "checks"),
         trigger: args.trigger ?? "manual",
         startedAt
     });
-    const findings = [];
-    const seen = new Set();
     let error;
     try {
-        for (const page of scanned) {
-            const pageWeight = weights.get(page.slug)?.weight ?? NEUTRAL_PAGE_WEIGHT;
-            const ctx = {
-                scopeKey: args.scopeKey,
-                page,
-                site,
-                manifest: args.manifest,
-                fields: fieldsBySlug.get(page.slug) ?? [],
-                links: linksBySlug.get(page.slug) ?? []
-            };
-            for (const rule of rules) {
-                // One rule throwing must not cost the run every other rule's findings —
-                // a checker that goes dark because a custom block had an unexpected
-                // prop shape is worse than one that reports twelve of thirteen rules.
-                let produced;
-                try {
-                    produced = rule.run(ctx);
-                }
-                catch (err) {
-                    error ??= `${rule.id}: ${err instanceof Error ? err.message : String(err)}`;
-                    continue;
-                }
-                for (const finding of produced) {
-                    const fingerprint = fingerprintFor(args.scopeKey, page.slug, rule.id, finding.key);
-                    /*
-                     * Two findings from one rule sharing a key are one finding as far as
-                     * the store is concerned — the second upsert overwrites the first.
-                     * Collapsing them here instead keeps the ledger honest (the second
-                     * was being counted as an `updated` row) and makes which one survives
-                     * a decision rather than an accident of iteration order.
-                     */
-                    if (seen.has(fingerprint))
-                        continue;
-                    seen.add(fingerprint);
-                    const severity = finding.severity ?? rule.severity;
-                    findings.push({
-                        fingerprint,
-                        scopeKey: args.scopeKey,
-                        slug: page.slug,
-                        ruleId: rule.id,
-                        agent: rule.agent,
-                        severity,
-                        impact: impactFor(severity, pageWeight),
-                        title: finding.title,
-                        ...(finding.detail ? { detail: finding.detail } : {}),
-                        ...(finding.evidence ? { evidence: finding.evidence } : {}),
-                        ...(finding.proposedOps ? { proposedOps: finding.proposedOps } : {})
-                    });
-                }
-            }
-        }
+        const evaluated = evaluateDraftChecks(args);
+        const findings = evaluated.findings;
+        error = evaluated.error;
         const { opened } = await store.recordFindings(runId, findings);
         // Reconcile per agent, not once for the whole run. A run of only the SEO
         // rules that closed everything in scope would mark this morning's
         // accessibility findings fixed without having looked at them.
-        const scannedSlugs = scanned.map((p) => p.slug);
+        const scannedSlugs = evaluated.scannedSlugs;
         let closed = 0;
         for (const agent of new Set(rules.map((r) => r.agent))) {
             const result = await store.reconcileFindings({
@@ -131,11 +146,11 @@ export async function runDraftChecks(args) {
         const record = {
             id: runId,
             scopeKey: args.scopeKey,
-            agent: rules.length === 1 ? rules[0].agent : "checks",
+            agent: args.agent ?? (rules.length === 1 ? rules[0].agent : "checks"),
             trigger: args.trigger ?? "manual",
             startedAt,
             finishedAt: now(),
-            pagesScanned: scanned.length,
+            pagesScanned: scannedSlugs.length,
             findingsOpened: opened,
             findingsClosed: closed,
             costUsd: 0,
@@ -153,7 +168,9 @@ export async function runDraftChecks(args) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        await store.finishCheckRun(runId, { finishedAt: now(), pagesScanned: scanned.length, error: reason });
+        const wanted = args.slugs ? new Set(args.slugs) : null;
+        const pagesScanned = args.pages.filter((p) => (wanted ? wanted.has(p.slug) : true)).length;
+        await store.finishCheckRun(runId, { finishedAt: now(), pagesScanned, error: reason });
         throw err;
     }
 }

package/dist/checks/session-runner.js

@@ -54,6 +54,13 @@ function enabled(flag) {
     return process.env.CHECKS_ON_PUBLISH !== "0";
 }
 function runInBackground(scopeKey, trigger, log) {
+    // Custom agents switched on for this event run after the draft checker,
+    // on the same engine (agents/run-spec.ts). Imported lazily: the agents
+    // module reads settings from the durable store, which the checker alone
+    // never needs.
+    void import("../agents/run-spec.js")
+        .then(({ runCustomAgentsOn }) => runCustomAgentsOn({ scopeKey, on: trigger === "on_apply" ? "apply" : "publish", ...(log ? { log } : {}) }))
+        .catch((err) => log?.error({ err: String(err), scopeKey, trigger }, "agent runs failed"));
     void runChecksForSession({ scopeKey, trigger })
         .then((run) => {
         log?.info({ scopeKey, trigger, opened: run.findingsOpened, closed: run.findingsClosed }, "checks run complete");

package/dist/checks/types.d.ts

@@ -60,6 +60,12 @@ export type SiteView = {
         meta?: PageDoc["meta"];
     }>;
     config: SiteConfig;
+    /**
+     * Another page in full, by slug. Most rules need only titles; the
+     * translation rules compare a page with its source-language counterpart
+     * block by block. Absent where a caller built a SiteView by hand.
+     */
+    page?: (slug: string) => PageDoc | undefined;
     /**
      * The documents the site holds, when it can enumerate them.
      *

package/dist/durable/in-memory-durable-store.d.ts

@@ -1,4 +1,4 @@
-import type { CheckRunInput, CheckRunPatch, CorrectionInput, CorrectionQuery, DurableStore, FindingInput, FindingQuery, FindingSeverity, FindingStatus, MemoryInput, MemoryQuery, MemoryStatus, ProposalInput, ProposalQuery, ProposalStatus } from "./types.ts";
+import type { CheckRunInput, CheckRunPatch, CorrectionInput, CorrectionQuery, DurableStore, FindingFix, FindingInput, FindingQuery, FindingSeverity, FindingStatus, MemoryInput, MemoryQuery, MemoryStatus, ProposalInput, ProposalQuery, ProposalStatus, InboxItemInput, InboxItemQuery, InboxItemRecord, InboxItemResolution, AgentSettingInput } from "./types.ts";
 export type InMemoryDurableStoreOptions = {
     now?: () => number;
 };
@@ -10,6 +10,8 @@ export declare class InMemoryDurableStore implements DurableStore {
     private readonly memory;
     private readonly corrections;
     private readonly proposals;
+    private readonly inbox;
+    private readonly agents;
     private readonly now;
     constructor(options?: InMemoryDurableStoreOptions);
     /** Keep the newest `cap` rows per scope, matching the SQLite store's trim. */
@@ -40,6 +42,7 @@ export declare class InMemoryDurableStore implements DurableStore {
         evidence?: import("./types.ts").FindingEvidence;
         proposedOps?: import("@avocadostudio-ai/shared").Operation[];
         id: string;
+        fix?: FindingFix;
         status: FindingStatus;
         lastRunId: string;
         firstSeenAt: number;
@@ -60,6 +63,7 @@ export declare class InMemoryDurableStore implements DurableStore {
         evidence?: import("./types.ts").FindingEvidence;
         proposedOps?: import("@avocadostudio-ai/shared").Operation[];
         id: string;
+        fix?: FindingFix;
         status: FindingStatus;
         lastRunId: string;
         firstSeenAt: number;
@@ -67,6 +71,7 @@ export declare class InMemoryDurableStore implements DurableStore {
         resolvedAt?: number;
         snoozedUntil?: number;
     } | null>;
+    setFindingFix(id: string, fix: FindingFix | null): Promise<void>;
     setFindingStatus(id: string, status: FindingStatus, at?: number): Promise<void>;
     wakeSnoozedFindings(scopeKey: string, now?: number): Promise<{
         woken: number;
@@ -200,4 +205,32 @@ export declare class InMemoryDurableStore implements DurableStore {
     expireProposals(now?: number): Promise<{
         expired: number;
     }>;
+    putInboxItem(input: InboxItemInput): Promise<InboxItemRecord>;
+    getInboxItem(id: string): Promise<InboxItemRecord | null>;
+    listInboxItems(query: InboxItemQuery): Promise<InboxItemRecord[]>;
+    resolveInboxItem(id: string, resolution: InboxItemResolution): Promise<InboxItemRecord | null>;
+    reopenInboxItem(id: string, change?: {
+        payload?: Record<string, unknown>;
+        at?: number;
+    }): Promise<InboxItemRecord | null>;
+    putAgentSetting(input: AgentSettingInput, at?: number): Promise<{
+        scopeKey: string;
+        agentId: string;
+        enabled: boolean;
+        owner?: string;
+        spec?: Record<string, unknown>;
+        createdAt: number;
+        updatedAt: number;
+    }>;
+    deleteAgentSetting(scopeKey: string, agentId: string): Promise<boolean>;
+    listAgentScopes(): Promise<string[]>;
+    listAgentSettings(scopeKey: string): Promise<{
+        scopeKey: string;
+        agentId: string;
+        enabled: boolean;
+        owner?: string;
+        spec?: Record<string, unknown>;
+        createdAt: number;
+        updatedAt: number;
+    }[]>;
 }

package/dist/durable/in-memory-durable-store.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { CHECK_RUN_CAP, CORRECTION_CAP, PROPOSAL_CAP, SNOOZE_WINDOW_MS } from "./sqlite-durable-store.js";
+import { CHECK_RUN_CAP, CORRECTION_CAP, INBOX_RESOLVED_CAP, PROPOSAL_CAP, SNOOZE_WINDOW_MS } from "./sqlite-durable-store.js";
 import { fallbackImpact } from "./finding-impact.js";
 /*
  * In-memory `DurableStore`. Two jobs, both real.
@@ -28,6 +28,8 @@ export class InMemoryDurableStore {
     memory = new Map();
     corrections = [];
     proposals = new Map();
+    inbox = new Map();
+    agents = new Map();
     now;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
@@ -154,6 +156,17 @@ export class InMemoryDurableStore {
         const record = this.findings.get(id);
         return record ? { ...record } : null;
     }
+    async setFindingFix(id, fix) {
+        const record = this.findings.get(id);
+        if (!record)
+            return;
+        const next = { ...record };
+        if (fix)
+            next.fix = structuredClone(fix);
+        else
+            delete next.fix;
+        this.findings.set(id, next);
+    }
     async setFindingStatus(id, status, at) {
         const record = this.findings.get(id);
         if (!record)
@@ -360,4 +373,112 @@ export class InMemoryDurableStore {
         }
         return { expired };
     }
+    // Inbox items ------------------------------------------------------------
+    async putInboxItem(input) {
+        const at = this.now();
+        const existing = this.inbox.get(input.id);
+        const record = existing
+            ? {
+                ...input,
+                createdAt: existing.createdAt,
+                scopeKey: existing.scopeKey,
+                status: existing.status,
+                revision: existing.revision + 1,
+                updatedAt: at,
+                ...(existing.resolvedAt != null ? { resolvedAt: existing.resolvedAt } : {}),
+                ...(existing.resolution != null ? { resolution: existing.resolution } : {}),
+                ...(existing.resolvedBy != null ? { resolvedBy: existing.resolvedBy } : {}),
+                ...(existing.note != null ? { note: existing.note } : {})
+            }
+            : { ...input, status: "open", revision: 1, updatedAt: at };
+        this.inbox.set(input.id, record);
+        const closed = [...this.inbox.values()]
+            .filter((row) => row.scopeKey === record.scopeKey && row.status !== "open")
+            .sort((a, b) => b.createdAt - a.createdAt);
+        closed.slice(INBOX_RESOLVED_CAP).forEach((row) => this.inbox.delete(row.id));
+        return structuredClone(record);
+    }
+    async getInboxItem(id) {
+        const record = this.inbox.get(id);
+        return record ? structuredClone(record) : null;
+    }
+    async listInboxItems(query) {
+        const statuses = query.status ? (Array.isArray(query.status) ? query.status : [query.status]) : null;
+        const limit = Math.max(1, Math.min(query.limit ?? 200, 1000));
+        return [...this.inbox.values()]
+            .filter((row) => row.scopeKey === query.scopeKey)
+            .filter((row) => (statuses ? statuses.includes(row.status) : true))
+            .filter((row) => (query.kind ? row.kind === query.kind : true))
+            .filter((row) => (query.agent ? row.agent === query.agent : true))
+            .filter((row) => (query.updatedSince != null ? row.updatedAt > query.updatedSince : true))
+            .sort((a, b) => b.createdAt - a.createdAt)
+            .slice(0, limit)
+            .map((row) => structuredClone(row));
+    }
+    async resolveInboxItem(id, resolution) {
+        const current = this.inbox.get(id);
+        if (!current || current.status !== "open")
+            return null;
+        const at = resolution.at ?? this.now();
+        const payload = resolution.payload ? { ...(current.payload ?? {}), ...resolution.payload } : current.payload;
+        const next = {
+            ...current,
+            status: "resolved",
+            resolvedAt: at,
+            resolution: resolution.resolution,
+            revision: current.revision + 1,
+            updatedAt: at,
+            ...(payload ? { payload } : {}),
+            ...(resolution.resolvedBy != null ? { resolvedBy: resolution.resolvedBy } : {}),
+            ...(resolution.note != null ? { note: resolution.note } : {})
+        };
+        this.inbox.set(id, next);
+        return structuredClone(next);
+    }
+    async reopenInboxItem(id, change = {}) {
+        const current = this.inbox.get(id);
+        if (!current || current.status !== "resolved")
+            return null;
+        const at = change.at ?? this.now();
+        const payload = change.payload ? { ...(current.payload ?? {}), ...change.payload } : current.payload;
+        const { resolvedAt: _r, resolution: _s, resolvedBy: _b, note: _n, ...rest } = current;
+        const next = {
+            ...rest,
+            status: "open",
+            revision: current.revision + 1,
+            updatedAt: at,
+            ...(payload ? { payload } : {})
+        };
+        this.inbox.set(id, next);
+        return structuredClone(next);
+    }
+    // Agent settings ---------------------------------------------------------
+    async putAgentSetting(input, at) {
+        const now = at ?? this.now();
+        const key = `${input.scopeKey}\0${input.agentId}`;
+        const existing = this.agents.get(key);
+        const record = {
+            scopeKey: input.scopeKey,
+            agentId: input.agentId,
+            enabled: input.enabled,
+            ...(input.owner != null ? { owner: input.owner } : {}),
+            ...(input.spec ? { spec: structuredClone(input.spec) } : existing?.spec ? { spec: existing.spec } : {}),
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now
+        };
+        this.agents.set(key, record);
+        return { ...record };
+    }
+    async deleteAgentSetting(scopeKey, agentId) {
+        return this.agents.delete(`${scopeKey}\0${agentId}`);
+    }
+    async listAgentScopes() {
+        return [...new Set([...this.agents.values()].map((row) => row.scopeKey))].sort();
+    }
+    async listAgentSettings(scopeKey) {
+        return [...this.agents.values()]
+            .filter((row) => row.scopeKey === scopeKey)
+            .sort((a, b) => a.agentId.localeCompare(b.agentId))
+            .map((row) => ({ ...row }));
+    }
 }

package/dist/durable/index.d.ts

@@ -2,4 +2,4 @@ export { getDurableStore, resetDurableStore, setDurableStore, durableStoreIsEphe
 export { loadPendingPlan, savePendingPlan, clearPendingPlan, peekPendingPlan } from "./pending-plan-store.ts";
 export { SqliteDurableStore, type SqliteDurableStoreOptions } from "./sqlite-durable-store.ts";
 export { InMemoryDurableStore, type InMemoryDurableStoreOptions } from "./in-memory-durable-store.ts";
-export type { DurableStore, FindingInput, FindingRecord, FindingQuery, FindingSeverity, FindingStatus, FindingEvidence, CheckRunInput, CheckRunRecord, CheckRunPatch, CheckRunTrigger, MemoryInput, MemoryRecord, MemoryQuery, MemoryScope, MemoryKind, MemorySource, MemoryStatus, CorrectionInput, CorrectionRecord, CorrectionQuery, CorrectionOutcome, ProposalInput, ProposalRecord, ProposalQuery, ProposalStatus } from "./types.ts";
+export type { DurableStore, FindingInput, FindingRecord, FindingQuery, FindingSeverity, FindingStatus, FindingEvidence, CheckRunInput, CheckRunRecord, CheckRunPatch, CheckRunTrigger, MemoryInput, MemoryRecord, MemoryQuery, MemoryScope, MemoryKind, MemorySource, MemoryStatus, CorrectionInput, CorrectionRecord, CorrectionQuery, CorrectionOutcome, ProposalInput, ProposalRecord, ProposalQuery, ProposalStatus, InboxItemKind, InboxItemStatus, InboxItemInput, InboxItemRecord, InboxItemQuery, InboxItemResolution, AgentSettingInput, AgentSettingRecord } from "./types.ts";

package/dist/durable/sqlite-durable-store.d.ts

@@ -1,8 +1,13 @@
 import type { Database as BetterSqliteDatabase } from "better-sqlite3";
-import type { CheckRunInput, CheckRunPatch, CheckRunRecord, CorrectionInput, CorrectionQuery, CorrectionRecord, DurableStore, FindingInput, FindingQuery, FindingRecord, FindingStatus, MemoryInput, MemoryQuery, MemoryRecord, MemoryStatus, ProposalInput, ProposalQuery, ProposalRecord, ProposalStatus } from "./types.ts";
+import type { CheckRunInput, CheckRunPatch, CheckRunRecord, CorrectionInput, CorrectionQuery, CorrectionRecord, DurableStore, FindingFix, FindingInput, FindingQuery, FindingRecord, FindingStatus, MemoryInput, MemoryQuery, MemoryRecord, MemoryStatus, ProposalInput, ProposalQuery, ProposalRecord, ProposalStatus, InboxItemInput, InboxItemQuery, InboxItemRecord, InboxItemResolution, AgentSettingInput, AgentSettingRecord } from "./types.ts";
 export declare const PROPOSAL_CAP = 200;
 export declare const CORRECTION_CAP = 500;
 export declare const CHECK_RUN_CAP = 200;
+/**
+ * Only closed items count against it: an open item is somebody's decision still
+ * to make, and trimming it would silently lift a publish hold.
+ */
+export declare const INBOX_RESOLVED_CAP = 500;
 /**
  * How long a snooze lasts.
  *
@@ -38,6 +43,7 @@ export declare class SqliteDurableStore implements DurableStore {
     }>;
     listFindings(query: FindingQuery): Promise<FindingRecord[]>;
     getFinding(id: string): Promise<FindingRecord | null>;
+    setFindingFix(id: string, fix: FindingFix | null): Promise<void>;
     setFindingStatus(id: string, status: FindingStatus, at?: number): Promise<void>;
     wakeSnoozedFindings(scopeKey: string, now?: number): Promise<{
         woken: number;
@@ -68,4 +74,16 @@ export declare class SqliteDurableStore implements DurableStore {
     expireProposals(now?: number): Promise<{
         expired: number;
     }>;
+    putInboxItem(input: InboxItemInput): Promise<InboxItemRecord>;
+    getInboxItem(id: string): Promise<InboxItemRecord | null>;
+    listInboxItems(query: InboxItemQuery): Promise<InboxItemRecord[]>;
+    resolveInboxItem(id: string, resolution: InboxItemResolution): Promise<InboxItemRecord | null>;
+    reopenInboxItem(id: string, change?: {
+        payload?: Record<string, unknown>;
+        at?: number;
+    }): Promise<InboxItemRecord | null>;
+    putAgentSetting(input: AgentSettingInput, at?: number): Promise<AgentSettingRecord>;
+    deleteAgentSetting(scopeKey: string, agentId: string): Promise<boolean>;
+    listAgentScopes(): Promise<string[]>;
+    listAgentSettings(scopeKey: string): Promise<AgentSettingRecord[]>;
 }