@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/durable/types.d.ts

@@ -0,0 +1,265 @@
+import type { Operation } from "@avocadostudio-ai/shared";
+export type FindingSeverity = "error" | "warning" | "info";
+/**
+ * `open` → a live problem. `fixed` is set by reconciliation, never by a rule.
+ * `dismissed` and `snoozed` are the user's decision and must survive every
+ * subsequent run — a checker whose dismissals evaporate is a checker people
+ * turn off in week two.
+ *
+ * The two are not synonyms, and the difference is a clock: `dismissed` means
+ * *never show me this again*, `snoozed` means *not this week*. A snooze without
+ * an expiry is a second word for dismiss, so a snoozed record carries
+ * `snoozedUntil` and `wakeSnoozedFindings` reopens it when that passes.
+ */
+export type FindingStatus = "open" | "snoozed" | "dismissed" | "fixed";
+export type FindingEvidence = {
+    source: "draft" | "rendered" | "model";
+    blockId?: string;
+    /**
+     * Carried so a client can select the block without a lookup. The editor's
+     * property panel collapses to its page-level fallback when it is handed an
+     * id with no type, so a finding that knows the block but not its type sends
+     * the user to a panel that cannot show them the field.
+     */
+    blockType?: string;
+    /**
+     * The block's own heading, for telling two blocks of one type apart. A page
+     * with three Card Grids yields three findings that all read
+     * `cards[0].imageAlt`; without this the panel cannot say which is which and
+     * the reader has to press "Go to" on each to find out.
+     */
+    blockLabel?: string;
+    /** Editable path into the block props, e.g. `meta.description`. */
+    path?: string;
+    excerpt?: string;
+};
+export type FindingInput = {
+    /** Stable across runs. Excludes the offending *value* — see `fingerprint`. */
+    fingerprint: string;
+    scopeKey: string;
+    slug: string;
+    ruleId: string;
+    agent: string;
+    severity: FindingSeverity;
+    /**
+     * Severity × how much the page matters, 0–1. See `finding-impact.ts`.
+     *
+     * Recomputed by every run rather than fixed at first sight, because the page
+     * weight it derives from moves: link a page from the nav and its findings
+     * become more important than they were this morning, without anything about
+     * the findings themselves having changed.
+     *
+     * Optional on the way in — a caller that has not scored its pages should get
+     * the neutral fallback rather than a made-up number.
+     */
+    impact?: number;
+    title: string;
+    detail?: string;
+    evidence?: FindingEvidence;
+    /** Ops that would resolve the finding. Applied only through the normal gate. */
+    proposedOps?: Operation[];
+};
+export type FindingRecord = FindingInput & {
+    id: string;
+    /** Always present on a record; `fallbackImpact` fills it for unscored rows. */
+    impact: number;
+    status: FindingStatus;
+    /** The run that most recently emitted this finding. Reconciliation reads it. */
+    lastRunId: string;
+    firstSeenAt: number;
+    lastSeenAt: number;
+    resolvedAt?: number;
+    /** When a `snoozed` record becomes `open` again. Set only for that status. */
+    snoozedUntil?: number;
+};
+export type FindingQuery = {
+    scopeKey: string;
+    slug?: string;
+    agent?: string;
+    status?: FindingStatus | FindingStatus[];
+    severity?: FindingSeverity;
+    limit?: number;
+};
+export type CheckRunTrigger = "manual" | "on_apply" | "on_publish" | "scheduled" | "webhook";
+export type CheckRunInput = {
+    id: string;
+    scopeKey: string;
+    agent: string;
+    trigger: CheckRunTrigger;
+    startedAt: number;
+};
+export type CheckRunRecord = CheckRunInput & {
+    finishedAt?: number;
+    pagesScanned: number;
+    findingsOpened: number;
+    findingsClosed: number;
+    /** Model spend for the judgement tier. Cost invisible is cost unbounded. */
+    costUsd: number;
+    error?: string;
+};
+export type CheckRunPatch = Partial<Omit<CheckRunRecord, keyof CheckRunInput>>;
+export type MemoryScope = "site" | "session" | "page";
+export type MemoryKind = "fact" | "preference" | "decision" | "glossary";
+export type MemorySource = "user" | "inferred" | "agent" | "import";
+export type MemoryStatus = "active" | "superseded" | "rejected";
+export type MemoryInput = {
+    scope: MemoryScope;
+    scopeKey: string;
+    kind: MemoryKind;
+    /** Namespaced, unique per (scope, scopeKey, kind). A new value supersedes. */
+    key: string;
+    value: string;
+    source: MemorySource;
+    /** traceId, findingId or run id — whatever lets a human audit the claim. */
+    sourceRef?: string;
+    /** 0–1. `inferred` should enter low; a wrong remembered fact steers silently. */
+    confidence?: number;
+};
+export type MemoryRecord = Required<Pick<MemoryInput, "confidence">> & MemoryInput & {
+    id: string;
+    status: MemoryStatus;
+    supersedesId?: string;
+    createdAt: number;
+    lastUsedAt?: number;
+    useCount: number;
+};
+export type MemoryQuery = {
+    scopeKey?: string;
+    scope?: MemoryScope;
+    kind?: MemoryKind | MemoryKind[];
+    status?: MemoryStatus;
+    limit?: number;
+};
+export type CorrectionOutcome = "accepted" | "edited" | "rejected" | "undone";
+export type CorrectionInput = {
+    traceId: string;
+    scopeKey: string;
+    slug?: string;
+    request: string;
+    proposed: Operation[];
+    outcome: CorrectionOutcome;
+    /** What actually landed, when the human edited rather than accepted. */
+    applied?: Operation[];
+};
+export type CorrectionRecord = CorrectionInput & {
+    id: string;
+    at: number;
+};
+export type CorrectionQuery = {
+    scopeKey?: string;
+    outcome?: CorrectionOutcome;
+    since?: number;
+    limit?: number;
+};
+export type ProposalStatus = "pending" | "approved" | "discarded" | "expired";
+/**
+ * `pendingApprovalPlanBySession` is an in-memory Map, not persisted, evicted by
+ * age. That is fine for "you typed a sentence and approved it ten seconds
+ * later" and useless for an agent that runs at 03:00: the plan it produced has
+ * nowhere to live until morning.
+ */
+export type ProposalInput = {
+    id: string;
+    scopeKey: string;
+    /** Which agent or chat turn produced it. */
+    origin: string;
+    summary: string;
+    ops: Operation[];
+    slugs: string[];
+    /** The finding this proposal resolves, when it came from one. */
+    findingId?: string;
+    /**
+     * Opaque to this store: whatever the producer needs to reconstruct its own
+     * richer object. The chat pipeline's `PendingApprovalPlan` carries a prompt
+     * hash, a model key, pending image ops and the destructive-gate reasons, none
+     * of which belong in a generic proposals table — and all of which have to
+     * survive a restart, or rehydration hands back a plan the approval path
+     * cannot execute.
+     *
+     * `ops`/`slugs`/`summary` stay typed so a consumer that only wants to show or
+     * apply the plan never has to know what produced it.
+     */
+    payload?: Record<string, unknown>;
+    createdAt: number;
+    expiresAt?: number;
+};
+export type ProposalRecord = ProposalInput & {
+    status: ProposalStatus;
+    resolvedAt?: number;
+};
+export type ProposalQuery = {
+    scopeKey: string;
+    status?: ProposalStatus;
+    limit?: number;
+};
+export interface DurableStore {
+    /**
+     * Upsert by fingerprint. An existing record keeps its `firstSeenAt` and — the
+     * part that matters — its `status`, so a dismissal survives every re-run. A
+     * record previously reconciled to `fixed` reopens.
+     *
+     * Returns counts, not records, because the caller is a run loop that wants a
+     * ledger line and not a page of rows.
+     */
+    recordFindings(runId: string, findings: FindingInput[]): Promise<{
+        opened: number;
+        updated: number;
+    }>;
+    /**
+     * Close every `open` or `snoozed` finding in scope that this run did not
+     * re-emit. The absence *is* the signal — nothing has to notice a problem went
+     * away.
+     *
+     * Snoozed rows are included because a snooze postpones the *report*, not the
+     * problem: leave them out and a finding somebody deferred on Monday, then
+     * fixed on Tuesday, comes back on Friday as an open finding about a page that
+     * is fine.
+     *
+     * `slugs` bounds it to what the run actually scanned: a run over two pages
+     * must not close findings on the other forty-three.
+     */
+    reconcileFindings(args: {
+        runId: string;
+        scopeKey: string;
+        slugs: string[];
+        agent?: string;
+        at?: number;
+    }): Promise<{
+        closed: number;
+    }>;
+    listFindings(query: FindingQuery): Promise<FindingRecord[]>;
+    getFinding(id: string): Promise<FindingRecord | null>;
+    /**
+     * `snoozed` derives its own `snoozedUntil` from `at` plus `SNOOZE_WINDOW_MS`
+     * rather than taking one, so every caller and every implementation agree on
+     * what a snooze is worth. Nothing else may set it.
+     */
+    setFindingStatus(id: string, status: FindingStatus, at?: number): Promise<void>;
+    /**
+     * Reopen snoozed findings whose window has passed. The read paths call it, so
+     * a snooze ends without anything having to be scheduled — the same shape as
+     * `expireProposals`, and for the same reason: there is no cron here.
+     */
+    wakeSnoozedFindings(scopeKey: string, now?: number): Promise<{
+        woken: number;
+    }>;
+    startCheckRun(run: CheckRunInput): Promise<CheckRunRecord>;
+    finishCheckRun(id: string, patch: CheckRunPatch): Promise<void>;
+    listCheckRuns(scopeKey: string, limit?: number): Promise<CheckRunRecord[]>;
+    /** Supersedes the active record with the same (scope, scopeKey, kind, key). */
+    putMemory(input: MemoryInput, at?: number): Promise<MemoryRecord>;
+    listMemory(query: MemoryQuery): Promise<MemoryRecord[]>;
+    /** Bump `lastUsedAt`/`useCount` for records that were actually sent to a model. */
+    touchMemory(ids: string[], at?: number): Promise<void>;
+    setMemoryStatus(id: string, status: MemoryStatus): Promise<void>;
+    recordCorrection(input: CorrectionInput, at?: number): Promise<CorrectionRecord>;
+    listCorrections(query?: CorrectionQuery): Promise<CorrectionRecord[]>;
+    putProposal(input: ProposalInput): Promise<ProposalRecord>;
+    getProposal(id: string): Promise<ProposalRecord | null>;
+    listProposals(query: ProposalQuery): Promise<ProposalRecord[]>;
+    setProposalStatus(id: string, status: ProposalStatus, at?: number): Promise<void>;
+    /** Sweep proposals past `expiresAt`. Returns how many were expired. */
+    expireProposals(now?: number): Promise<{
+        expired: number;
+    }>;
+}

package/dist/durable/types.js

@@ -0,0 +1 @@
+export {};

package/dist/handler/create-orchestrator.d.ts

@@ -167,6 +167,10 @@ export interface CreateOrchestratorConfig {
      *
      * Omit it if you render Avocado's blocks (a scaffolded site does). The
      * declaration is exclusive: nothing outside the list is offered or accepted.
+     *
+     * Pass the same list to `createEditorApiHandler`. That handler serves
+     * `/api/editor/blocks`, the manifest the editor reads, and it is routinely
+     * asked for it before anything has caused this module to be evaluated.
      */
     blockTypes?: readonly string[];
     /**