@avocadostudio-ai/orchestrator-core 0.22.0 → 0.24.0

package/dist/agents/fix-writer.js

@@ -0,0 +1,197 @@
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { fieldText, walkPageFields } from "../checks/field-walk.js";
+import { DESCRIPTION_MAX, DESCRIPTION_MIN, effectiveTitle, TITLE_MAX, TITLE_MIN } from "../checks/rules-draft.js";
+import { getAnthropicClient } from "../chat/anthropic-planner.js";
+import { defaultModelLookup } from "../chat/model-defaults.js";
+import { generateAltTextFromVision } from "../chat/vision-alt-generator.js";
+/** The rules a fix can be written for, and which field each one fixes. */
+export const FIXABLE_RULES = {
+    "seo.title-missing": "title",
+    "seo.title-length": "title",
+    "seo.description-missing": "description",
+    "seo.description-length": "description",
+    "a11y.alt-missing": "alt",
+    "i18n.untranslated": "translation"
+};
+export function fixFieldFor(ruleId) {
+    return FIXABLE_RULES[ruleId];
+}
+const LIMITS = {
+    title: [TITLE_MIN, TITLE_MAX],
+    description: [DESCRIPTION_MIN, DESCRIPTION_MAX]
+};
+/** The value a fix for this finding replaces, read off the page as it is now. */
+export function currentValue(finding, page) {
+    const field = fixFieldFor(finding.ruleId);
+    if (field === "title")
+        return effectiveTitle(page);
+    if (field === "description")
+        return (page.meta?.description ?? "").trim();
+    if (field === "alt" || field === "translation") {
+        const { blockId, path } = finding.evidence ?? {};
+        if (!blockId || !path)
+            return undefined;
+        const entry = walkPageFields(page, buildBlockManifest()).find((f) => f.blockId === blockId && f.path === path);
+        return entry ? fieldText(entry.value).trim() : undefined;
+    }
+    return undefined;
+}
+/** The ops that put `text` in place — the same ops whether the text was written or edited. */
+export function fixOps(finding, text) {
+    const field = fixFieldFor(finding.ruleId);
+    if (field === "title")
+        return [{ op: "update_page_meta", pageSlug: finding.slug, patch: { title: text } }];
+    if (field === "description")
+        return [{ op: "update_page_meta", pageSlug: finding.slug, patch: { description: text } }];
+    const { blockId, path } = finding.evidence ?? {};
+    if ((field === "alt" || field === "translation") && blockId && path) {
+        return [{ op: "update_props", pageSlug: finding.slug, blockId, patch: { [path]: text } }];
+    }
+    return [];
+}
+/** What the page says, compactly: headings and the first sentences of its text, for the model to summarise. */
+export function pageDigest(page, maxChars = 2500) {
+    const lines = [];
+    for (const entry of walkPageFields(page, buildBlockManifest())) {
+        if (entry.kind !== "text" && entry.kind !== "richtext")
+            continue;
+        const text = fieldText(entry.value).replace(/\s+/g, " ").trim();
+        if (text.length < 3 || /^https?:\/\//.test(text))
+            continue;
+        lines.push(`${entry.blockType}.${entry.path}: ${text.slice(0, 300)}`);
+    }
+    return lines.join("\n").slice(0, maxChars);
+}
+function systemPrompt(field) {
+    const [min, max] = LIMITS[field];
+    const what = field === "title"
+        ? `the page's title for search results and the browser tab`
+        : `the page's meta description for search results and link previews`;
+    return [
+        `You write ${what}.`,
+        `Length: between ${min} and ${max} characters. Count carefully; this is checked.`,
+        "Write in the language the page's content is written in.",
+        "Say what the page is about, specifically, using the page's own words and facts. Never invent a claim, a price, an offer or a date the page does not state.",
+        field === "title"
+            ? "No quotes. Put the most specific words first. You may end with the site's name after a separator if it fits."
+            : "One or two plain sentences. No quotes, no emoji, no calls to action the page does not make.",
+        "The site facts you are given are rules about the site's wording — follow them (words to avoid, product names, spelling).",
+        'Reply with JSON: {"text": "..."}.'
+    ].join("\n");
+}
+const TEXT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["text"],
+    properties: { text: { type: "string" } }
+};
+async function writeText(field, page, deps, retryNote) {
+    const client = deps.client ?? getAnthropicClient();
+    const model = deps.model ?? defaultModelLookup().anthropic.balanced;
+    const user = {
+        slug: page.slug,
+        currentTitle: effectiveTitle(page) || null,
+        currentDescription: (page.meta?.description ?? "").trim() || null,
+        siteFacts: deps.facts ?? [],
+        content: pageDigest(page),
+        ...(retryNote ? { previousAttempt: retryNote } : {})
+    };
+    const response = await client.messages.create({
+        model,
+        max_tokens: 400,
+        system: systemPrompt(field),
+        output_config: { format: { type: "json_schema", schema: TEXT_SCHEMA } },
+        messages: [{ role: "user", content: JSON.stringify(user) }]
+    }, { signal: AbortSignal.timeout(60_000) });
+    const raw = response.content.find((block) => block.type === "text")?.text ?? "";
+    const text = String(JSON.parse(raw || "{}").text ?? "");
+    return text.replace(/\s+/g, " ").trim().replace(/^["“„']+|["”']+$/g, "");
+}
+/**
+ * Write a fix for one finding against the page as it is. A title or
+ * description outside its length is retried once with the count; a second
+ * miss is refused rather than stored, because the fix would reopen the very
+ * finding it was written for.
+ */
+export async function writeFix(finding, page, deps = {}) {
+    const field = fixFieldFor(finding.ruleId);
+    if (!field)
+        return { ok: false, error: "no fix can be written for this kind of finding" };
+    const base = currentValue(finding, page);
+    if (base === undefined)
+        return { ok: false, error: "the field this finding is about is no longer on the page" };
+    if (field === "alt") {
+        const imageUrl = finding.evidence?.imageUrl;
+        if (!imageUrl)
+            return { ok: false, error: "the finding does not say which image it is about" };
+        const generate = deps.altText ?? ((url) => generateAltTextFromVision({ imageUrl: url, preferredProvider: "anthropic" }));
+        const text = (await generate(imageUrl))?.trim();
+        if (!text)
+            return { ok: false, error: "the image could not be described" };
+        return { ok: true, fix: { field, text, base, ops: fixOps(finding, text), by: "vision", at: Date.now() } };
+    }
+    if (field === "translation")
+        return writeTranslation(finding, page, base, deps);
+    const [min, max] = LIMITS[field];
+    let text = await writeText(field, page, deps);
+    if (text.length < min || text.length > max) {
+        text = await writeText(field, page, deps, `"${text}" is ${text.length} characters; it must be ${min}–${max}.`);
+    }
+    if (text.length < min || text.length > max) {
+        return { ok: false, error: `the ${field} came back ${text.length} characters, outside ${min}–${max}` };
+    }
+    return {
+        ok: true,
+        fix: { field, text, base, ops: fixOps(finding, text), by: deps.model ?? defaultModelLookup().anthropic.balanced, at: Date.now() }
+    };
+}
+/** "German" for "de": the model is told a language, not a code. */
+export function languageName(code) {
+    try {
+        return new Intl.DisplayNames(["en"], { type: "language" }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}
+/**
+ * Translate a field a translated page left in the source language. Plain text
+ * only: a rich-text field would lose its formatting as a string, and is left
+ * to the chat, which translates documents block by block.
+ */
+async function writeTranslation(finding, page, base, deps) {
+    const locale = finding.evidence?.locale;
+    if (!locale)
+        return { ok: false, error: "the finding does not say which language the page is in" };
+    const raw = rawValue(finding, page);
+    if (typeof raw !== "string")
+        return { ok: false, error: "rich text is translated in the chat, where its formatting survives" };
+    const client = deps.client ?? getAnthropicClient();
+    const model = deps.model ?? defaultModelLookup().anthropic.balanced;
+    const language = languageName(locale);
+    const response = await client.messages.create({
+        model,
+        max_tokens: 1200,
+        system: [
+            `You translate website copy into ${language}.`,
+            "Keep the meaning, the tone and the length close to the original. Keep names, product names and numbers as they are.",
+            "The site facts you are given are rules about the site's wording, including its glossary — follow them.",
+            'Reply with JSON: {"text": "..."}.'
+        ].join("\n"),
+        output_config: { format: { type: "json_schema", schema: TEXT_SCHEMA } },
+        messages: [{ role: "user", content: JSON.stringify({ language, text: finding.evidence?.sourceText ?? base, siteFacts: deps.facts ?? [] }) }]
+    }, { signal: AbortSignal.timeout(60_000) });
+    const out = String(JSON.parse(response.content.find((b) => b.type === "text")?.text || "{}").text ?? "").trim();
+    if (!out)
+        return { ok: false, error: "the translation came back empty" };
+    if (out === base)
+        return { ok: false, error: "the translation came back unchanged" };
+    return { ok: true, fix: { field: "translation", text: out, base, ops: fixOps(finding, out), by: model, at: Date.now() } };
+}
+/** The field's stored value, untouched — to tell plain text from a rich-text document. */
+function rawValue(finding, page) {
+    const { blockId, path } = finding.evidence ?? {};
+    if (!blockId || !path)
+        return undefined;
+    return walkPageFields(page, buildBlockManifest()).find((f) => f.blockId === blockId && f.path === path)?.value;
+}

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>;