@avocadostudio-ai/orchestrator-core 0.22.0 → 0.23.0

package/dist/agents/mention.js

@@ -0,0 +1,161 @@
+import { getDurableStore } from "../durable/durable-store-singleton.js";
+import { getSessionDraft } from "../state/session-state.js";
+import { agentOfFinding } from "./inbox.js";
+import { runAgentSpec } from "./run-spec.js";
+import { resolveSiteAgents } from "./settings.js";
+import { CUSTOM_AGENT_PREFIX } from "./spec.js";
+const WEEK = 7 * 24 * 3_600_000;
+const TOP = 3;
+/** An agent's handle in chat: its id, without the `custom:` prefix. */
+export function handleOf(agentId) {
+    return agentId.startsWith(CUSTOM_AGENT_PREFIX) ? agentId.slice(CUSTOM_AGENT_PREFIX.length) : agentId;
+}
+/** English and German keywords, matched on whole words. Order is priority. */
+const INTENTS = [
+    ["help", /\b(help|hilfe|what can you do|was kannst du)\b/i],
+    ["pause", /\b(pause|stop|mute|switch off|turn off|pausier\w*|anhalten|ausschalten|stopp)\b/i],
+    ["resume", /\b(resume|switch on|turn on|unpause|start again|einschalten|fortsetzen|weitermachen)\b/i],
+    ["week", /\b(this week|last week|changed|did you do|diese woche|letzte woche|geändert|gemacht)\b/i],
+    ["report", /\b(found|findings|status|report|what have you|anything|gefunden|meldungen|bericht)\b/i],
+    ["run", /\b(check|run|scan|look at|go|now|prüf\w*|lauf\w*|schau)\b/i]
+];
+export function parseIntent(rest, all) {
+    for (const [intent, pattern] of INTENTS)
+        if (pattern.test(rest))
+            return intent;
+    // "@agents" alone lists them; "@search-health" alone runs it.
+    return all ? "list" : rest.trim() ? "help" : "run";
+}
+/** The first `/path` in the message that is a page on this site. */
+export function pageIn(rest, pages) {
+    const match = /(^|\s)(\/[\w\-/.~%]*)/.exec(rest);
+    if (!match)
+        return {};
+    const wanted = match[2].replace(/[.,!?]+$/, "");
+    const normalized = wanted.length > 1 ? wanted.replace(/\/+$/, "") : wanted;
+    const page = pages.find((p) => p.slug === normalized);
+    return page ? { slug: page.slug } : { unknown: normalized };
+}
+function topFindings(findings) {
+    return [...findings]
+        .sort((a, b) => b.impact - a.impact)
+        .slice(0, TOP)
+        .map((f) => ({ slug: f.slug, title: f.title }));
+}
+async function openFor(scopeKey, agentId, store) {
+    const open = await store.listFindings({ scopeKey, status: "open" });
+    return open.filter((f) => agentOfFinding(f) === agentId);
+}
+export async function handleMention(args) {
+    const head = /^\s*@([a-z0-9][a-z0-9:-]*)\b(.*)$/is.exec(args.message);
+    if (!head)
+        return { handled: false };
+    const handle = head[1].toLowerCase();
+    const rest = head[2] ?? "";
+    const store = args.store ?? getDurableStore();
+    const site = await resolveSiteAgents(args.scopeKey, store);
+    const all = handle === "agents" || handle === "agenten";
+    const agent = all
+        ? undefined
+        : site.agents.find((a) => handleOf(a.agentId) === handle || a.agentId === handle);
+    if (!all && !agent)
+        return { handled: false };
+    const intent = parseIntent(rest, all);
+    const handles = site.agents.map((a) => handleOf(a.agentId));
+    if (all) {
+        if (intent === "week")
+            return weekSummary(args.scopeKey, site.agents, store, args.now ?? Date.now());
+        if (intent === "help")
+            return { handled: true, kind: "help", handles };
+        const open = await store.listFindings({ scopeKey: args.scopeKey, status: "open" });
+        return {
+            handled: true,
+            kind: "list",
+            agents: site.agents.map((a) => ({
+                agentId: a.agentId,
+                handle: handleOf(a.agentId),
+                enabled: a.enabled,
+                open: open.filter((f) => agentOfFinding(f) === a.agentId).length
+            }))
+        };
+    }
+    const target = agent;
+    switch (intent) {
+        case "help":
+            return { handled: true, kind: "help", agentId: target.agentId, handles };
+        case "week":
+            return weekSummary(args.scopeKey, [target], store, args.now ?? Date.now());
+        case "report": {
+            const open = await openFor(args.scopeKey, target.agentId, store);
+            return { handled: true, kind: "report", agentId: target.agentId, open: open.length, top: topFindings(open) };
+        }
+        case "pause": {
+            if (!target.enabled)
+                return { handled: true, kind: "already", agentId: target.agentId, enabled: false };
+            await store.putAgentSetting({ scopeKey: args.scopeKey, agentId: target.agentId, enabled: false, ...(target.owner ? { owner: target.owner } : {}) });
+            return { handled: true, kind: "paused", agentId: target.agentId, enabled: false };
+        }
+        case "resume": {
+            if (target.enabled)
+                return { handled: true, kind: "already", agentId: target.agentId, enabled: true };
+            // Switched on only for the owner it already has: naming someone is the Agents page's job.
+            if (!target.owner)
+                return { handled: true, kind: "refused", agentId: target.agentId, reason: "needs_owner" };
+            await store.putAgentSetting({ scopeKey: args.scopeKey, agentId: target.agentId, enabled: true, owner: target.owner });
+            return { handled: true, kind: "resumed", agentId: target.agentId, enabled: true };
+        }
+        case "run":
+        case "list": {
+            if (!target.enabled)
+                return { handled: true, kind: "refused", agentId: target.agentId, reason: "off" };
+            if (target.agentId === "edit-safety")
+                return { handled: true, kind: "refused", agentId: target.agentId, reason: "not_runnable" };
+            const page = pageIn(rest, [...getSessionDraft(args.scopeKey).values()]);
+            if (page.unknown)
+                return { handled: true, kind: "refused", agentId: target.agentId, reason: "unknown_page", slug: page.unknown };
+            // A page named in the message narrows this one run; the agent's own scope is unchanged.
+            const spec = page.slug ? { ...target.spec, scope: { ...target.spec.scope, slugs: [page.slug] } } : target.spec;
+            const run = await runAgentSpec({ scopeKey: args.scopeKey, spec, trigger: "manual", store });
+            const open = (await openFor(args.scopeKey, target.agentId, store)).filter((f) => !page.slug || f.slug === page.slug);
+            return {
+                handled: true,
+                kind: "ran",
+                agentId: target.agentId,
+                ...(page.slug ? { slug: page.slug } : {}),
+                opened: run.findingsOpened,
+                closed: run.findingsClosed,
+                open: open.length,
+                top: topFindings(open)
+            };
+        }
+    }
+}
+/** The last seven days, rolling: what each agent found and fixed, and what Edit safety caught. */
+async function weekSummary(scopeKey, agents, store, now) {
+    const since = now - WEEK;
+    const ids = new Set(agents.map((a) => a.agentId));
+    const lines = new Map(agents.map((a) => [a.agentId, { agentId: a.agentId, found: 0, fixed: 0, open: 0 }]));
+    for (const finding of await store.listFindings({ scopeKey })) {
+        const line = lines.get(agentOfFinding(finding));
+        if (!line)
+            continue;
+        if (finding.firstSeenAt >= since)
+            line.found += 1;
+        if (finding.status === "fixed" && (finding.resolvedAt ?? 0) >= since)
+            line.fixed += 1;
+        if (finding.status === "open")
+            line.open += 1;
+    }
+    let caught = 0;
+    let reverted = 0;
+    if (ids.has("edit-safety")) {
+        for (const alert of await store.listInboxItems({ scopeKey, kind: "alert", agent: "edit-safety" })) {
+            if (alert.createdAt < since)
+                continue;
+            caught += 1;
+            if (alert.resolution === "reverted")
+                reverted += 1;
+        }
+    }
+    return { handled: true, kind: "week", since, agents: [...lines.values()], caught, reverted };
+}

package/dist/agents/run-spec.d.ts

@@ -0,0 +1,27 @@
+import { type PageDoc } from "@avocadostudio-ai/shared";
+import type { CheckRunRecord, CheckRunTrigger, DurableStore, FindingInput } from "../durable/types.ts";
+import type { Logger } from "../logger.ts";
+import type { AgentSpec } from "./spec.ts";
+/** The pages a spec looks at: `scope.slugs` if given, minus `scope.exclude`. */
+export declare function slugsInScope(pages: PageDoc[], scope: AgentSpec["scope"]): string[];
+/** Run a spec now and record what it finds. Throws on a spec with nothing the checker can run. */
+export declare function runAgentSpec(args: {
+    scopeKey: string;
+    spec: AgentSpec;
+    trigger: CheckRunTrigger;
+    store?: DurableStore;
+    /** The run's clock. A scheduled run is stamped with its tick's time, which is what the next tick reads. */
+    now?: () => number;
+}): Promise<CheckRunRecord>;
+/** What a spec would find today, writing nothing — the backtest (SO-09). */
+export declare function evaluateAgentSpec(scopeKey: string, spec: AgentSpec): Promise<FindingInput[]>;
+/**
+ * The custom agents switched on for an event. Built-ins are not here: the
+ * draft checker already runs their rules on the same triggers, and Edit
+ * safety runs inside the edit itself.
+ */
+export declare function runCustomAgentsOn(args: {
+    scopeKey: string;
+    on: "apply" | "publish";
+    log?: Logger;
+}): Promise<void>;

package/dist/agents/run-spec.js

@@ -0,0 +1,82 @@
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { evaluateDraftChecks, runDraftChecks } from "../checks/run-checks.js";
+import { getSessionDraft, getSiteConfig } from "../state/session-state.js";
+import { getSiteAssets } from "../state/site-assets.js";
+import { resolveSiteAgents } from "./settings.js";
+import { compileSpec } from "./templates.js";
+/*
+ * One runner for every agent spec (site-ops-agents.md SO-04): a spec is
+ * compiled into check rules and run on the draft checker's engine, so a
+ * custom agent's findings land in the same table, reconcile the same way,
+ * and reach the Inbox grouped per rule like any other.
+ *
+ * Page scope is applied here; block-type scope is applied by `compileSpec`.
+ */
+/** The pages a spec looks at: `scope.slugs` if given, minus `scope.exclude`. */
+export function slugsInScope(pages, scope) {
+    const only = scope.slugs?.length ? new Set(scope.slugs) : null;
+    const never = new Set(scope.exclude ?? []);
+    return pages.map((page) => page.slug).filter((slug) => (only ? only.has(slug) : true) && !never.has(slug));
+}
+async function inputs(scopeKey) {
+    const assets = await getSiteAssets();
+    return {
+        pages: [...getSessionDraft(scopeKey).values()],
+        manifest: buildBlockManifest(),
+        siteConfig: getSiteConfig(scopeKey),
+        ...(assets ? { assets } : {})
+    };
+}
+/** Run a spec now and record what it finds. Throws on a spec with nothing the checker can run. */
+export async function runAgentSpec(args) {
+    const rules = compileSpec(args.spec);
+    if (rules.length === 0)
+        throw new Error(`${args.spec.name} does not run on a check: it acts on each edit instead`);
+    const base = await inputs(args.scopeKey);
+    const slugs = slugsInScope(base.pages, args.spec.scope);
+    return runDraftChecks({
+        scopeKey: args.scopeKey,
+        ...base,
+        rules,
+        slugs,
+        agent: args.spec.id,
+        trigger: args.trigger,
+        ...(args.store ? { store: args.store } : {}),
+        ...(args.now ? { now: args.now } : {})
+    });
+}
+/** What a spec would find today, writing nothing — the backtest (SO-09). */
+export async function evaluateAgentSpec(scopeKey, spec) {
+    const rules = compileSpec(spec);
+    if (rules.length === 0)
+        return [];
+    const base = await inputs(scopeKey);
+    return evaluateDraftChecks({ scopeKey, ...base, rules, slugs: slugsInScope(base.pages, spec.scope) }).findings;
+}
+/**
+ * The custom agents switched on for an event. Built-ins are not here: the
+ * draft checker already runs their rules on the same triggers, and Edit
+ * safety runs inside the edit itself.
+ */
+export async function runCustomAgentsOn(args) {
+    const site = await resolveSiteAgents(args.scopeKey);
+    for (const agent of site.agents) {
+        if (agent.builtin || !agent.enabled)
+            continue;
+        const trigger = agent.spec.trigger;
+        if (trigger.kind !== "event" || trigger.on !== args.on)
+            continue;
+        try {
+            const run = await runAgentSpec({
+                scopeKey: args.scopeKey,
+                spec: agent.spec,
+                trigger: args.on === "apply" ? "on_apply" : "on_publish"
+            });
+            args.log?.info({ agentId: agent.agentId, opened: run.findingsOpened, closed: run.findingsClosed }, "agent run complete");
+        }
+        catch (error) {
+            // One agent failing must not stop the others, or the edit that woke them.
+            args.log?.error({ err: String(error), agentId: agent.agentId }, "agent run failed");
+        }
+    }
+}

package/dist/agents/schedule.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const scheduleTriggerSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"schedule">;
+    every: z.ZodEnum<{
+        day: "day";
+        week: "week";
+    }>;
+    hour: z.ZodDefault<z.ZodNumber>;
+    weekday: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScheduleTrigger = z.infer<typeof scheduleTriggerSchema>;
+/** The most recent moment at or before `now` that the schedule names. */
+export declare function latestSlot(trigger: ScheduleTrigger, now: number): number;
+/** The next moment after `now` that the schedule names. */
+export declare function nextSlot(trigger: ScheduleTrigger, now: number): number;
+/**
+ * Whether an agent should run now. `since` is the later of its last scheduled
+ * run and the moment it was created or last switched on — so a new agent
+ * waits for its first slot instead of firing on the next tick, and an agent
+ * that was off over its slot does not run the moment it is switched back on.
+ */
+export declare function isDue(trigger: ScheduleTrigger, since: number, now: number): boolean;

package/dist/agents/schedule.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/*
+ * When a scheduled agent is due (site-ops-agents.md §8 item 6).
+ *
+ * There is no cron in here. Something calls POST /agents/tick — a timer in the
+ * standalone server, or an outside scheduler in library mode, where there is
+ * no process between requests — and the tick asks each agent one question:
+ * has a slot of your schedule passed since you last ran?
+ *
+ * Asking it that way makes the tick's own cadence irrelevant to correctness.
+ * A tick every minute runs a daily agent once a day; a tick that did not fire
+ * for three days runs it once, not three times; two ticks racing each other
+ * are harmless because the second finds the run the first recorded.
+ *
+ * Times are UTC. A site's time zone is not known yet, and a schedule that
+ * silently meant the server's zone would move when the server did.
+ */
+export const scheduleTriggerSchema = z.object({
+    kind: z.literal("schedule"),
+    every: z.enum(["day", "week"]),
+    /** Hour of the day, UTC. */
+    hour: z.number().int().min(0).max(23).default(6),
+    /** For `every: "week"`: 0 = Sunday … 6 = Saturday. Ignored for a daily agent. */
+    weekday: z.number().int().min(0).max(6).default(1)
+});
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+/** The most recent moment at or before `now` that the schedule names. */
+export function latestSlot(trigger, now) {
+    const d = new Date(now);
+    let slot = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), trigger.hour);
+    if (slot > now)
+        slot -= DAY;
+    if (trigger.every === "week") {
+        const back = (new Date(slot).getUTCDay() - trigger.weekday + 7) % 7;
+        slot -= back * DAY;
+    }
+    return slot;
+}
+/** The next moment after `now` that the schedule names. */
+export function nextSlot(trigger, now) {
+    return latestSlot(trigger, now) + (trigger.every === "week" ? 7 : 1) * DAY;
+}
+/**
+ * Whether an agent should run now. `since` is the later of its last scheduled
+ * run and the moment it was created or last switched on — so a new agent
+ * waits for its first slot instead of firing on the next tick, and an agent
+ * that was off over its slot does not run the moment it is switched back on.
+ */
+export function isDue(trigger, since, now) {
+    const slot = latestSlot(trigger, now);
+    return since < slot && slot <= now;
+}

package/dist/agents/settings.d.ts

@@ -0,0 +1,30 @@
+import type { DurableStore } from "../durable/types.ts";
+import { type BuiltinAgentId } from "./builtins.ts";
+import { type AgentSpec } from "./spec.ts";
+export type AgentState = {
+    agentId: string;
+    builtin: boolean;
+    name: string;
+    enabled: boolean;
+    owner?: string;
+    spec: AgentSpec;
+};
+export type SiteAgents = {
+    /**
+     * False until someone has been through "Meet your agents" for this site.
+     * Every built-in then reports its default, and the editor offers the first
+     * run. A custom agent created through the API does not count: the built-ins
+     * have still not been looked at.
+     */
+    configured: boolean;
+    /** The built-ins first, in catalogue order, then custom agents by name. */
+    agents: AgentState[];
+};
+/** The state of every agent for one site: built-ins with defaults filled in, then custom ones. */
+export declare function resolveSiteAgents(scopeKey: string, store?: DurableStore): Promise<SiteAgents>;
+/**
+ * Whether one built-in is on. Never throws: an agent whose state cannot be
+ * read is treated as its default, because a store outage must not turn Edit
+ * safety on (and hold every publish) or turn the draft checker off.
+ */
+export declare function agentState(scopeKey: string, agentId: BuiltinAgentId): Promise<AgentState>;

package/dist/agents/settings.js

@@ -0,0 +1,64 @@
+import { getDurableStore } from "../durable/durable-store-singleton.js";
+import { BUILTIN_AGENT_IDS, BUILTIN_SPECS, DEFAULT_ENABLED } from "./builtins.js";
+import { agentSpecSchema, isCustomAgentId } from "./spec.js";
+/** The state of every agent for one site: built-ins with defaults filled in, then custom ones. */
+export async function resolveSiteAgents(scopeKey, store = getDurableStore()) {
+    const rows = await store.listAgentSettings(scopeKey);
+    const byId = new Map(rows.map((row) => [row.agentId, row]));
+    const builtins = BUILTIN_AGENT_IDS.map((agentId) => {
+        const row = byId.get(agentId);
+        const spec = BUILTIN_SPECS[agentId];
+        return {
+            agentId,
+            builtin: true,
+            name: spec.name,
+            enabled: row ? row.enabled : DEFAULT_ENABLED[agentId],
+            ...(row?.owner ? { owner: row.owner } : {}),
+            spec
+        };
+    });
+    const customs = [];
+    for (const row of rows) {
+        if (!isCustomAgentId(row.agentId) || !row.spec)
+            continue;
+        // A stored spec that no longer parses (a field this build dropped) is left
+        // out rather than run half-understood.
+        const parsed = agentSpecSchema.safeParse(row.spec);
+        if (!parsed.success)
+            continue;
+        customs.push({
+            agentId: row.agentId,
+            builtin: false,
+            name: parsed.data.name,
+            enabled: row.enabled,
+            ...(row.owner ? { owner: row.owner } : {}),
+            spec: parsed.data
+        });
+    }
+    customs.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        configured: rows.some((row) => BUILTIN_AGENT_IDS.includes(row.agentId)),
+        agents: [...builtins, ...customs]
+    };
+}
+/**
+ * Whether one built-in is on. Never throws: an agent whose state cannot be
+ * read is treated as its default, because a store outage must not turn Edit
+ * safety on (and hold every publish) or turn the draft checker off.
+ */
+export async function agentState(scopeKey, agentId) {
+    const fallback = {
+        agentId,
+        builtin: true,
+        name: BUILTIN_SPECS[agentId].name,
+        enabled: DEFAULT_ENABLED[agentId],
+        spec: BUILTIN_SPECS[agentId]
+    };
+    try {
+        const site = await resolveSiteAgents(scopeKey);
+        return site.agents.find((a) => a.agentId === agentId) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/agents/spec.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+export declare const CUSTOM_AGENT_PREFIX = "custom:";
+export declare const detectStepSchema: z.ZodObject<{
+    template: z.ZodString;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const agentTriggerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"manual">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"event">;
+    on: z.ZodEnum<{
+        apply: "apply";
+        publish: "publish";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"schedule">;
+    every: z.ZodEnum<{
+        day: "day";
+        week: "week";
+    }>;
+    hour: z.ZodDefault<z.ZodNumber>;
+    weekday: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+export declare const agentScopeSchema: z.ZodDefault<z.ZodObject<{
+    slugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    blockTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>;
+export declare const agentSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    brief: z.ZodDefault<z.ZodString>;
+    origin: z.ZodEnum<{
+        custom: "custom";
+        builtin: "builtin";
+    }>;
+    trigger: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"manual">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"event">;
+        on: z.ZodEnum<{
+            apply: "apply";
+            publish: "publish";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"schedule">;
+        every: z.ZodEnum<{
+            day: "day";
+            week: "week";
+        }>;
+        hour: z.ZodDefault<z.ZodNumber>;
+        weekday: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>], "kind">;
+    scope: z.ZodDefault<z.ZodObject<{
+        slugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        blockTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    detect: z.ZodArray<z.ZodObject<{
+        template: z.ZodString;
+        params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    severity: z.ZodDefault<z.ZodEnum<{
+        info: "info";
+        error: "error";
+        warning: "warning";
+    }>>;
+}, z.core.$strip>;
+export type AgentSpec = z.infer<typeof agentSpecSchema>;
+export type DetectStep = z.infer<typeof detectStepSchema>;
+export declare function isCustomAgentId(value: unknown): value is string;
+/**
+ * Parse a custom spec sent by a caller. The id must be a `custom:` id, and
+ * `origin` is forced to "custom" — a caller cannot author a built-in.
+ * Template names and their params are checked separately, against the
+ * registry, by `compileSpec`.
+ */
+export declare function parseCustomSpec(raw: unknown): {
+    ok: true;
+    spec: AgentSpec;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/agents/spec.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { scheduleTriggerSchema } from "./schedule.js";
+/*
+ * An agent is data (docs/ideas/site-ops-agents.md §2, SO-03, SO-04).
+ *
+ * One record per agent per site. A built-in and a custom agent are the same
+ * shape with a different `origin`, so there is one runner, one test surface
+ * and one Agents page. What an agent notices is `detect`: a list of rule
+ * templates with parameters, each compiled into ordinary check rules — the
+ * same deterministic engine the draft checker runs, so an agent gives the same
+ * answer every time and can be backtested.
+ *
+ * The spec holds only what runs today. Not here yet, deliberately:
+ *  - `judge` steps (a model call) — §8 item 8 onward;
+ *  - `autonomy` and `budget` — nothing an agent does applies itself yet.
+ *
+ * A `schedule` trigger runs from POST /agents/tick (agents/schedule.ts).
+ */
+export const CUSTOM_AGENT_PREFIX = "custom:";
+const CUSTOM_ID = /^custom:[a-z0-9][a-z0-9-]{0,47}$/;
+export const detectStepSchema = z.object({
+    template: z.string().min(1).max(40),
+    params: z.record(z.string(), z.unknown()).default({})
+});
+export const agentTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("manual") }),
+    z.object({ kind: z.literal("event"), on: z.enum(["apply", "publish"]) }),
+    scheduleTriggerSchema
+]);
+export const agentScopeSchema = z
+    .object({
+    /** Only these pages. Absent: every page. */
+    slugs: z.array(z.string().min(1)).max(200).optional(),
+    /** Never these pages. */
+    exclude: z.array(z.string().min(1)).max(200).optional(),
+    /** Only fields of these block types. */
+    blockTypes: z.array(z.string().min(1)).max(50).optional()
+})
+    .default({});
+export const agentSpecSchema = z.object({
+    id: z.string().min(1).max(64),
+    name: z.string().trim().min(1).max(60),
+    /** The job in one sentence, as the person wrote it. Kept verbatim. */
+    brief: z.string().trim().max(500).default(""),
+    origin: z.enum(["builtin", "custom"]),
+    trigger: agentTriggerSchema,
+    scope: agentScopeSchema,
+    detect: z.array(detectStepSchema).min(1).max(10),
+    severity: z.enum(["error", "warning", "info"]).default("warning")
+});
+export function isCustomAgentId(value) {
+    return typeof value === "string" && CUSTOM_ID.test(value);
+}
+/**
+ * Parse a custom spec sent by a caller. The id must be a `custom:` id, and
+ * `origin` is forced to "custom" — a caller cannot author a built-in.
+ * Template names and their params are checked separately, against the
+ * registry, by `compileSpec`.
+ */
+export function parseCustomSpec(raw) {
+    const parsed = agentSpecSchema.safeParse({ ...raw, origin: "custom" });
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        return { ok: false, error: `invalid spec: ${issue?.path.join(".") || "spec"} — ${issue?.message ?? "invalid"}` };
+    }
+    if (!isCustomAgentId(parsed.data.id)) {
+        return { ok: false, error: 'a custom agent id is "custom:" followed by lowercase letters, digits and dashes' };
+    }
+    return { ok: true, spec: parsed.data };
+}

package/dist/agents/stats.d.ts

@@ -0,0 +1,15 @@
+import type { CheckRunRecord, DurableStore } from "../durable/types.ts";
+export type AgentStats = {
+    /** Findings raised, all time (as far as the store keeps them). */
+    found: number;
+    open: number;
+    fixed: number;
+    rejected: number;
+    /** Edit safety only. */
+    caught?: number;
+    reverted?: number;
+    intended?: number;
+    /** The most recent runs, newest first. */
+    runs: CheckRunRecord[];
+};
+export declare function agentStats(scopeKey: string, store?: DurableStore): Promise<Record<string, AgentStats>>;

package/dist/agents/stats.js

@@ -0,0 +1,48 @@
+import { getDurableStore } from "../durable/durable-store-singleton.js";
+import { BUILTIN_AGENT_IDS } from "./builtins.js";
+import { EDIT_SAFETY_AGENT } from "./edit-safety-runner.js";
+import { agentOfFinding } from "./inbox.js";
+import { isCustomAgentId } from "./spec.js";
+const RUNS_PER_AGENT = 10;
+function empty() {
+    return { found: 0, open: 0, fixed: 0, rejected: 0, runs: [] };
+}
+/**
+ * Which agent a check run belongs to. A custom agent's run carries its id; the
+ * draft checker's runs ("checks", or one rule's agent) are both built-in
+ * checker agents' runs, because they run those rules together.
+ */
+function runOwners(run) {
+    if (isCustomAgentId(run.agent) || BUILTIN_AGENT_IDS.includes(run.agent))
+        return [run.agent];
+    return ["search-health", "unfinished-work", "translation-drift"];
+}
+export async function agentStats(scopeKey, store = getDurableStore()) {
+    const out = {};
+    const of = (agentId) => (out[agentId] ??= empty());
+    const findings = await store.listFindings({ scopeKey, limit: 5000 });
+    for (const finding of findings) {
+        const stats = of(agentOfFinding(finding));
+        stats.found += 1;
+        if (finding.status === "open" || finding.status === "snoozed")
+            stats.open += 1;
+        else if (finding.status === "fixed")
+            stats.fixed += 1;
+        else if (finding.status === "dismissed")
+            stats.rejected += 1;
+    }
+    const alerts = await store.listInboxItems({ scopeKey, agent: EDIT_SAFETY_AGENT, limit: 1000 });
+    const edit = of(EDIT_SAFETY_AGENT);
+    edit.caught = alerts.length;
+    edit.reverted = alerts.filter((item) => item.resolution === "reverted").length;
+    edit.intended = alerts.filter((item) => item.resolution === "intended").length;
+    edit.open += alerts.filter((item) => item.status === "open").length;
+    for (const run of await store.listCheckRuns(scopeKey, 200)) {
+        for (const owner of runOwners(run)) {
+            const stats = of(owner);
+            if (stats.runs.length < RUNS_PER_AGENT)
+                stats.runs.push(run);
+        }
+    }
+    return out;
+}