nexus-ai-pro 2.11.0 → 2.12.0

package/API_STABILITY.md

@@ -41,6 +41,50 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.12 stage (2.12.0)
+
+Everything 2.12 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/tracing/spool`: `spoolingExporter()`, `SpoolingExporter`, `SpoolingExporterOptions`,
+  `TraceBatchSender`, `SpoolStats`, and `SpoolDrainReport`;
+- `OtlpTraceExporter.send()`;
+- `RunManagerOptions.tracer` and `AgentServerOptions.tracer`, and `RunRecord.traceId`;
+- `Deployments.evaluationWorker()` and `DeploymentEvaluationWorkerOptions`; `RunEvaluationOptions`
+  gains `traces`, `operations`, `pollMs`, and the worker's options, and `RunEvaluationReport` gains
+  `failed`;
+- in `nexus-ai-pro/evaluate`: `traceEvidence()`, `mediaParts()`, `EvaluationTrace`, `MediaPart`,
+  `TraceToolCall`, `TraceRetrieval`, `TraceDocument`, `TraceModelCall`, `TraceMedia`, and
+  `EvaluationContext.trace`;
+- `OnlineEvaluationWorkerOptions.withTrace`, `onScored`, and `onError`, and `OnlineScored`;
+- `traceRetriever()`, `RetrieverLike`, and `Tracer.within()`;
+- `nexus-ai-pro/evaluate/automation`: `automationRules()`, `deploymentScores()`, `traceScores()`,
+  `memoryScores()`, `openReview()`, `sendWebhook()`, `markUnhealthy()`, `AutomationRule`,
+  `AutomationRules`, `AutomationRulesOptions`, `AutomationEvent`, `AutomationAction`,
+  `AutomationStatus`, `AutomationWebhookOptions`, `ScoreSample`, `ScoreSource`, `MemoryScoreSource`,
+  `ReviewOpener`, and `RuleStatistic`;
+- `Deployments.markUnhealthy()`, `markHealthy()`, and `scores()`, `RunScore`, the `health`
+  `DeploymentChange`, `DeploymentRecord.unhealthy`, `RevisionHealthMark`,
+  `DeploymentChangeRecord.revision` and `healthy`, and `CanaryDecision.unhealthy`;
+- `nexus-ai-pro/evaluate/media`: `mediaChecks()`, `mediaJudge()`, `mediaOf()`, `resolveMedia()`,
+  `MediaCheckOptions`, `MediaJudgeOptions`, `MediaResolveOptions`, `MediaSelection`, `MediaRange`,
+  `ResolvedMedia`, and `MediaSubjectKind`;
+- `nexus-ai-pro/media/catalog`: `mediaCatalog()`, `catalogedAssetStore()`, `MediaCatalog`,
+  `MediaCatalogOptions`, `MediaCatalogEntry`, `MediaCatalogQuery`, `MediaCatalogPage`,
+  `MediaCatalogStats`, `MediaCatalogRecordOptions`, `CatalogScore`, `CatalogMediaKind`, and
+  `CatalogedAssetStoreOptions`;
+- `nexus-ai-pro/tracing/otlp-grpc`: `OtlpGrpcTraceExporter`, `OtlpGrpcTraceExporterOptions`, and
+  `OtlpGrpcError`;
+- in `nexus-ai-pro/tracing/otlp`: `OtlpTraceExporterOptions.protocol`, `encodeOtlpTraceRequest()`,
+  `decodeOtlpTraceResponse()`, `OtlpExportRequest`, `OtlpKeyValue`, `OtlpAttributeValue`,
+  `OtlpPartialSuccess`, and `OtlpPartialSuccessError`.
+
+Changed: `DeploymentChange` gains a `health` action, so a `switch` over its actions that must be
+exhaustive needs a case for it.
+
+Changed: `Deployments.evaluate()` runs through the online-evaluation worker, scoring up to 4 runs at
+once rather than one, so evaluators that are not safe to call concurrently need `concurrency: 1`.
+
 ## 2.11 stage (2.11.0)
 
 Everything 2.11 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,121 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-10-18
+
+Observability that loses nothing, and media you can evaluate.
+
+### Added
+
+- **Spans that a collector being down cannot lose.** `spoolingExporter()`, on the new
+  `nexus-ai-pro/tracing/spool`, keeps each batch the collector refuses in an operation store (the
+  memory, Redis, Postgres, or SQLite one), retries it with backoff, and dead-letters it only once it is
+  too old or has failed too often, under a bound on what waits. Every replica on the store drains the
+  same spool, each batch once. `writeAhead` spools each batch before sending it. `stats()` reports
+  what was exported, retried, spooled, dropped, and dead-lettered, and the age of the oldest batch
+  waiting.
+- `OtlpTraceExporter.send()`: sends runs as one batch now, and rejects when the collector refuses
+  them.
+- **A deployment judged by what its runs did.** An agent server given a `tracer` makes each run the
+  root of a trace, with its input and output, and everything the assistant traces through the same
+  tracer beneath it; the run records the trace as `RunRecord.traceId`. `Deployments.evaluate()`
+  given those `traces` hands each evaluator the run's input and an `EvaluationTrace` of its tool
+  calls, retrievals, model calls, and media, read by the new `traceEvidence()`, which `mediaParts()`
+  backs. An assistant that traces itself is found by the run id it records.
+- `Deployments.evaluationWorker()`: the online-evaluation worker over a deployment's runs, to start
+  on every replica, scoring each run once between them as it finishes.
+- `onlineEvaluationWorker()` takes `withTrace`, which gives evaluators `context.trace`, and
+  `onScored`, which hears each run's scores once they are written, with `onError` for its failures.
+- `traceRetriever()`: every retrieval as a `retriever` run, with the query and the documents.
+- **Media you can evaluate.** On the new `nexus-ai-pro/evaluate/media`, `mediaChecks()` reads the
+  media an evaluation is about, from bytes, base64, a data URL, a URL it is allowed to fetch, a path,
+  or an asset store, and scores each check asked: the count, kind, MIME type, size, dimensions,
+  aspect ratio, and a WAV's duration. `mediaJudge()` shows them to a vision or audio model beside a
+  rubric and the brief, a stored asset sent as its bytes, and records the judge in an experiment.
+  `mediaOf()` finds the media in an output, or in what the run's trace says it produced, and
+  `resolveMedia()` reads one.
+- **Automation rules.** On the new `nexus-ai-pro/evaluate/automation`, `automationRules()` judges
+  a score over each revision's most recent runs, and when it falls below a threshold over enough
+  samples (optionally by the upper bound of a confidence interval), acts once, across every replica
+  sharing its `state`: `openReview()` sends the worst runs to people, `sendWebhook()` posts a signed
+  event, and `markUnhealthy()` marks the revision unhealthy, which rolls a canary back. Rules read
+  scores a deployment's run records hold (`deploymentScores()`), a trace store's
+  (`traceScores()`), or this process's (`memoryScores()`), and `observe()` judges them as an online
+  evaluation writes them. A rule fires once per fall, recovers, and can repeat.
+- **A revision's health.** `Deployments.markUnhealthy()` and `markHealthy()`: a `health` change in
+  the deployment's history, kept in `DeploymentRecord.unhealthy`. A canary marked unhealthy is rolled
+  back at once, and a canary guard rolls back any canary marked since it began, its `CanaryDecision`
+  carrying the mark. The studio shows each revision's health and marks one from the deployment view.
+  `Deployments.scores()` reads the scores of an assistant's runs.
+- **A catalog of every stored asset.** `mediaCatalog()`, on the new `nexus-ai-pro/media/catalog`,
+  keeps one record of each stored asset in any long-term store (Postgres, SQLite, Redis, or memory):
+  what it is, who made it, for which run, its tags, and its latest score per key, written by
+  compare-and-set. `catalogedAssetStore()` wraps any asset store so every asset stored through it is
+  recorded and every one deleted is forgotten, an entry expiring with its asset. `list()` finds
+  entries by kind, type, provider, model, run, store, tag, time, and score, a page at a time;
+  `attach()` scores the assets a run's output refers to; `stats()`, `purgeExpired()`, and
+  `reconcile()` keep account.
+- **OTLP over gRPC.** `OtlpGrpcTraceExporter`, on the new `nexus-ai-pro/tracing/otlp-grpc`, sends
+  spans to a collector's port 4317 with no gRPC library: the trace service's `Export` call framed by
+  hand over Node's HTTP/2 client, gzip-compressed, with metadata, a deadline, TLS options, one
+  connection kept and reopened, and a failed call rejecting with an `OtlpGrpcError` so a spool keeps
+  the batch. `OtlpTraceExporter` takes `protocol: 'http/protobuf'`, and both read a collector's
+  partial success into an `OtlpPartialSuccessError` for `onError`. `encodeOtlpTraceRequest()` and
+  `decodeOtlpTraceResponse()` are OTLP's protobuf encoding, written by hand, on any runtime.
+- `Tracer.within()`: runs a function with a run started by `startRun()` in scope.
+
+### Changed
+
+- `Deployments.evaluate()` runs through the online-evaluation worker, drained once, instead of beside
+  it. Replicas given one `operations` store score each run once between them, even calling at the
+  same moment, where before two calls could score a run twice; it takes the worker's budget, review
+  queue, and concurrency (4 at a time by default, one before), and `RunEvaluationReport` counts
+  `failed` evaluations. Which runs a `sampleRate` picks is unchanged.
+
+### Proof
+
+- `tests/trace-spool.test.ts`: a collector stopped for an hour while a span finishes every second,
+  and the process restarted halfway: every one of the 3,600 spans reaches it, once, on the memory,
+  SQLite, Postgres, and Redis operation stores. The bound, dead letters, two replicas on one spool,
+  and write-ahead through a process that dies mid-send. Without the spool, its bound, its claim, its
+  dead letters, write-ahead, or taking over a lapsed lease, a test fails.
+- `tests/media-evaluation.test.ts`: checks that read PNG, GIF, WAV, and PDF media from a store,
+  base64, a data URL, and a fetch only when allowed; a judge model shown a stored asset as its bytes
+  beside the rubric and the brief; media found through the trace; and an experiment over a target
+  that draws. Without the sniffing, the store, the wildcard, the tolerance, the duration, the size
+  limit, the count, the media shown, the brief, or the trace fallback, a test fails.
+- `tests/automation-rules.test.ts`: the proof that a canary is rolled back on a media evaluator's
+  score. A designer assistant's canary draws its banners square; two replicas score 80 runs with a
+  media judge shown each banner, and a rule on the judge's score marks the canary unhealthy, rolling
+  it back, opening review items for the five worst banners, and sending one signed webhook, once
+  between the replicas. The live revision is untouched, new runs go to it, and the media catalog
+  finds each of the canary's banners by its score. Then minimum samples, scopes, windows, the
+  confidence bound, the pass rate, recovery, repeats, filters, sources, failing actions, and a guard
+  rolling back a canary a rule only marked. Without the rollback, the guard's mark, the stale-mark
+  check, the claim, the minimum, the window, recovery, the bound, counting each run once, the
+  revision scope, the signature, or the repeat, a test fails.
+- `tests/media-catalog.test.ts`: on the memory, SQLite, Postgres, and Redis stores, forty assets of
+  five kinds, two providers, and two tenants, some deleted and some expiring: every page lists each
+  remaining asset once, every filter finds exactly its assets, expired ones are never read and are
+  purged with their assets, and ten evaluators scoring one asset at once keep all ten scores. An
+  asset deleted around the catalog is reconciled away, and one the catalog cannot record is not left
+  stored. Without the forgetting, the expiry, the purge, compare-and-set, the cursor, the filters,
+  the compensation, or the reconciliation, a test fails.
+- `tests/otlp-grpc.test.ts`: the OpenTelemetry Collector itself, in a container, takes spans over
+  gRPC and sends every one on as it came, ids, times, kinds, attributes, and status. Against a gRPC
+  server of the test's, with a protobuf reader written apart from the encoder: compression and
+  metadata, a refusal, a deadline, a partial success, a collector that is down, one that restarts
+  under a live connection, and a spool that keeps what is refused. Without the compressed flag, the
+  status, the deadline, the metadata, the parent span, the status message, typed values, the
+  reconnection, or the retry on a dropped connection, a test fails.
+- `tests/deployment-trace-evaluation.test.ts`: a traced server whose assistant retrieves a policy,
+  calls a tool, and asks a model about a photo; its evaluators see the input, the tool call, the
+  documents, the model call, and the photo once. Two replicas evaluating at once over one operation
+  store score each of 40 runs once, where queues of their own score runs twice. A worker scores runs
+  as they finish and hears each score once, and an assistant tracing itself is found. Without the
+  trace, the input, the run scope, the shared queue, the fallback, the media deduplication, or the
+  trace written before the run settles, a test fails.
+
 ## [2.11.0] - 2026-10-18
 
 Workspaces, and telephony in full.
@@ -2764,7 +2879,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.11.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.12.0...HEAD
+[2.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.11.0...v2.12.0
 [2.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.10.0...v2.11.0
 [2.10.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.9.0...v2.10.0
 [2.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.8.0...v2.9.0

package/README.md

@@ -303,14 +303,18 @@ Shipped so far:
 - 2.11 workspaces, and telephony in full: an agent's files apart from where its code runs, in memory,
   on disk, in any long-term store, read-only, or a composite of several; and a second phone provider,
   Telnyx, beside Twilio, both answering, transferring, conferencing, recording under a retention
-  policy, and sending and receiving messages.
+  policy, and sending and receiving messages;
+- 2.12 observability that loses nothing, and media you can evaluate: spans spooled through a collector
+  outage, OTLP over gRPC, deployment evaluation that reads each run's whole trace, evaluators that
+  read and judge images, documents, audio, and video, a catalog of every stored asset, and automation
+  rules that roll a canary back when a score falls.
 
 Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
 [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
-Next, 2.12 makes observability lose nothing, with spans spooled when the collector is down and
-deployment evaluation that reads the whole trace, and makes media something you can evaluate.
-Pinecone, images, the Gemini embedding batch tier, media understanding, video, Gemini Live, SIP, and
-both phone providers graduate once the live workflow passes against each. The
+Next, 2.13 runs agents across regions, keeps each tenant's requests and data in the region they
+require, and resolves provider keys per tenant from a secret manager. Pinecone, images, the Gemini
+embedding batch tier, media understanding, video, Gemini Live, SIP, and both phone providers graduate
+once the live workflow passes against each. The
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
 applications ask for it.
 

package/dist/evaluate/automation.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Automation rules: when a score falls below a threshold over enough samples, act. Open review items
+ * for people, send a webhook, or mark a deployment's revision unhealthy, which rolls a canary back.
+ *
+ * Rules read scores from a shared source, such as a deployment's run records, so every replica judges
+ * the same scores, and a firing is claimed in a shared store, so it acts once however many replicas
+ * see it.
+ */
+import type { OnlineScored } from './online.js';
+import type { Store } from '../types/store.js';
+import type { RunQuery, TraceStore } from '../types/tracing.js';
+/** One score, as automation rules judge them. */
+export interface ScoreSample {
+    /** The score's key. */
+    key: string;
+    /** The score. */
+    score: number;
+    /** Whether it passed, when its evaluator judged. */
+    passed?: boolean;
+    /** The run it was given to. */
+    runId: string;
+    /** ISO-8601 time it was given. */
+    at: string;
+    /** Who gave it. */
+    source?: string;
+    /** The assistant that ran. */
+    assistant?: string;
+    /** The revision that served the run. */
+    revision?: string;
+    /** The run's tenant. */
+    tenantId?: string;
+    /** What the run received, for a person reviewing it. */
+    inputs?: unknown;
+    /** What the run produced. */
+    output?: unknown;
+}
+/** Where rules read scores: any replica reading the same source judges the same scores. */
+export interface ScoreSource {
+    /** The most recent scores of one key, newest first, at most `limit`, and none older than `since`. */
+    samples(query: {
+        key: string;
+        since?: string;
+        limit: number;
+    }): Promise<ScoreSample[]> | ScoreSample[];
+}
+/** The scores of one assistant's runs, from its deployment's run records: shared by every replica. */
+export declare function deploymentScores(deployments: {
+    scores(assistant: string, options: {
+        key?: string;
+        since?: string;
+        limit?: number;
+    }): Promise<Array<Omit<ScoreSample, 'passed' | 'inputs'>>>;
+}, assistant: string): ScoreSource;
+/**
+ * The scores recorded on a trace store's runs, as an online evaluation writes them: shared by every
+ * replica that reads the store. `query` narrows the runs, such as `{ kind: 'image' }`.
+ */
+export declare function traceScores(traces: TraceStore, query?: RunQuery): ScoreSource;
+/** Scores held in this process, fed by `observe()` or `record()`: for one process, or a test. */
+export interface MemoryScoreSource extends ScoreSource {
+    /** Keeps one score. */
+    record(sample: ScoreSample): void;
+    /** Keeps a run's scores as an online evaluation's `onScored` hears them. */
+    observe(scored: OnlineScored): void;
+}
+/** A score source in this process, keeping the latest `max` scores (10,000). */
+export declare function memoryScores(options?: {
+    max?: number;
+}): MemoryScoreSource;
+/** What a rule judges a scope's samples by. */
+export type RuleStatistic = 'mean' | 'pass-rate';
+/** A rule: when `key` falls below `below` over enough samples, act. */
+export interface AutomationRule {
+    /** Names the rule in events, in the shared state, and as `rule:<name>` in a deployment's history. */
+    name: string;
+    /** The score key judged, such as `banner` from a media judge. */
+    key: string;
+    /** Fires when the statistic is below this. */
+    below: number;
+    /** The mean score, the default, or the share that passed: `passed`, or a score of at least 0.5. */
+    statistic?: RuleStatistic;
+    /** Samples a scope needs before it is judged, each run counted once. Defaults to 20. */
+    minSamples?: number;
+    /** The most recent runs judged per scope. Defaults to 100. */
+    window?: number;
+    /** Only samples this recent, in milliseconds. */
+    windowMs?: number;
+    /**
+     * Judges by an interval instead of the bare statistic: fires only when its upper bound at this
+     * confidence, such as 0.95, is below the threshold, so a few unlucky samples never fire it.
+     */
+    confidence?: number;
+    /** Only scores from this source. */
+    source?: string;
+    /** Narrows the samples further. */
+    where?: (sample: ScoreSample) => boolean;
+    /**
+     * What is judged on its own: each revision of each assistant, the default, so a canary is judged
+     * apart from the live revision; each assistant; everything as one; or a scope of your own.
+     */
+    by?: 'revision' | 'assistant' | 'all' | ((sample: ScoreSample) => string);
+    /** What it does when it fires, in order. */
+    actions: AutomationAction[];
+    /**
+     * Fires again after this long while a scope stays below, in milliseconds. Defaults to never: once
+     * per fall, again only after it recovers, which takes `minSamples` runs back at the threshold or
+     * above.
+     */
+    repeatAfterMs?: number;
+}
+/** A rule that fired, or recovered, for one scope. */
+export interface AutomationEvent {
+    /** `fired` when it fell below, `recovered` when it came back. */
+    type: 'fired' | 'recovered';
+    /** The rule. */
+    rule: string;
+    /** The scope, such as `designer@v2`. */
+    scope: string;
+    /** The score key. */
+    key: string;
+    /** How it was judged. */
+    statistic: RuleStatistic;
+    /** The statistic's value. */
+    value: number;
+    /** The interval at the rule's confidence, when it has one. */
+    interval?: [number, number];
+    /** The threshold. */
+    below: number;
+    /** Runs judged. */
+    samples: number;
+    /** The assistant, when the scope has one. */
+    assistant?: string;
+    /** The revision, when the scope has one. */
+    revision?: string;
+    /** The lowest samples, at most five, so an event points at runs to read. */
+    worst: ScoreSample[];
+    /** ISO-8601 time it was judged. */
+    at: string;
+    /** A sentence saying what happened. */
+    summary: string;
+}
+/** What a rule does when it fires. A failure goes to `onError`, and the rule's other actions still run. */
+export type AutomationAction = (event: AutomationEvent) => Promise<void> | void;
+/** Where a rule judged a scope, from `AutomationRules.status()`. */
+export interface AutomationStatus {
+    /** The rule. */
+    rule: string;
+    /** The scope. */
+    scope: string;
+    /** The statistic's value. */
+    value: number;
+    /** Runs judged. */
+    samples: number;
+    /** Whether it is below with enough samples. */
+    breached: boolean;
+    /** ISO-8601 time it last fired for this scope, while it stays below. */
+    firingSince?: string;
+}
+/** Options for `automationRules()`. */
+export interface AutomationRulesOptions {
+    /** The rules. */
+    rules: AutomationRule[];
+    /** Where scores are read. Defaults to `memoryScores()`, fed by `observe()`. */
+    scores?: ScoreSource;
+    /**
+     * Where firings are claimed, shared by every replica, so a rule acts once for a fall however many
+     * replicas judge it: a long-term store with `putIfVersion()`. Defaults to memory, for one process.
+     */
+    state?: Store;
+    /** The namespace firings are kept under. Defaults to `['nexus', 'automation']`. */
+    namespace?: readonly string[];
+    /** Most recent samples read per rule, across its scopes. Defaults to 5,000. */
+    scanLimit?: number;
+    /** Hears every event. */
+    onEvent?: (event: AutomationEvent) => void;
+    /** Hears failures of actions and reads, which never stop the rules. */
+    onError?: (error: unknown, event?: AutomationEvent) => void;
+    /** Replaces the system clock, for tests. */
+    now?: () => Date;
+}
+/** Running automation rules. */
+export interface AutomationRules {
+    /** Judges every rule now, acting on what fell, and resolves to the events. */
+    check(): Promise<AutomationEvent[]>;
+    /**
+     * Hears a run's scores, as an online evaluation's `onScored`: kept by a memory source, and judged
+     * at once by the rules on their keys.
+     */
+    observe(scored: OnlineScored): Promise<void>;
+    /** Where each rule stands for each scope. */
+    status(): Promise<AutomationStatus[]>;
+    /** Judges every `everyMs` (one minute) until `stop()`. */
+    start(options?: {
+        everyMs?: number;
+    }): void;
+    /** Stops `start()`. */
+    stop(): void;
+}
+/**
+ * Automation rules over scores: each rule judges the most recent runs of each scope (each revision by
+ * default) and acts when the statistic falls below its threshold over at least `minSamples` runs.
+ * A firing is claimed in `state` before it acts, so it acts once for a fall across every replica,
+ * and again only after the scope recovers, or after `repeatAfterMs`.
+ *
+ * ```ts
+ * const rules = automationRules({
+ *   scores: deploymentScores(deployments, 'designer'),
+ *   state: store,
+ *   rules: [{ name: 'banner quality', key: 'banner', below: 0.6, minSamples: 20,
+ *             actions: [markUnhealthy({ deployments }), openReview(queue), sendWebhook({ url })] }],
+ * });
+ * const worker = deployments.evaluationWorker('designer', { evaluators, operations, onScored: rules.observe });
+ * ```
+ */
+export declare function automationRules(options: AutomationRulesOptions): AutomationRules;
+/** Anything review items are opened in, such as an `AnnotationQueue`. */
+export interface ReviewOpener {
+    /** Opens one item. */
+    enqueue(subject: {
+        inputs?: unknown;
+        output?: unknown;
+        runId?: string;
+    }, metadata?: Record<string, unknown>): unknown;
+}
+/** Opens a review item for each of the lowest-scoring runs, at most `limit` (5), when a rule fires. */
+export declare function openReview(queue: ReviewOpener, options?: {
+    limit?: number;
+}): AutomationAction;
+/** Options for `sendWebhook()`. */
+export interface AutomationWebhookOptions {
+    /** Where the event is posted, as JSON. */
+    url: string;
+    /** Headers on the request, such as an authorization. */
+    headers?: Record<string, string>;
+    /**
+     * Signs the body with HMAC-SHA256 under this secret, in `x-nexus-signature: sha256=<hex>`, so the
+     * receiver knows it came from here.
+     */
+    secret?: string;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Posts the event to a webhook when a rule fires. A refusal rejects, which `onError` hears. */
+export declare function sendWebhook(options: AutomationWebhookOptions): AutomationAction;
+/** Marks the revision a rule fired for unhealthy, which rolls back a canary, as `Deployments.markUnhealthy()` does. */
+export declare function markUnhealthy(options: {
+    deployments: {
+        markUnhealthy(assistant: string, revision: string, options: {
+            reason: string;
+            by?: string;
+            rollback?: boolean;
+        }): Promise<unknown>;
+    };
+    /** Rolls a canary back at once. Defaults to true; false leaves it to a canary guard. */
+    rollback?: boolean;
+}): AutomationAction;