Skip to main content

Documentation Index

Fetch the complete documentation index at: https://smithers.sh/llms.txt

Use this file to discover all available pages before exploring further.

Use alertPolicy when you want a workflow to carry operational alert metadata such as ownership, severity, runbooks, labels, and deterministic reactions. The API is declarative:
  • createSmithers(..., { alertPolicy }) defines module-level defaults.
  • smithers(..., { alertPolicy }) overrides those defaults for one workflow.
  • Smithers stores the merged policy on the workflow and exposes durable alert rows through the DB adapter and CLI.
  • deliver uses logical destination names such as oncall or author; transport clients live in your runtime integration.

​
Module Defaults

import {
  createSmithers,
  type SmithersAlertPolicy,
} from "smithers-orchestrator";
import { z } from "zod";

const platformAlerts: SmithersAlertPolicy = {
  defaults: {
    owner: "platform",
    severity: "warning",
    runbook: "https://internal/runbooks/smithers-workflows",
    labels: {
      service: "deploy-bot",
      env: "prod",
    },
  },
  reactions: {
    "notify-author": { kind: "deliver", destination: "author" },
    "notify-oncall": { kind: "deliver", destination: "oncall" },
  },
};

const { Workflow, Task, smithers, outputs } = createSmithers(
  {
    deployResult: z.object({
      ok: z.boolean(),
      revision: z.string(),
    }),
  },
  {
    alertPolicy: platformAlerts,
  },
);

​
Workflow Overrides

export default smithers(
  () => (
    <Workflow name="deploy">
      <Task id="deploy" output={outputs.deployResult} agent={deployAgent}>
        Deploy the release and report the final revision.
      </Task>
    </Workflow>
  ),
  {
    alertPolicy: {
      rules: {
        runFailed: {
          severity: "critical",
          reaction: "notify-oncall",
        },
        approvalWaitExceeded: {
          afterMs: 86_400_000,
          reaction: "notify-author",
        },
        tokenBudgetExceeded: {
          severity: "warning",
          reaction: { kind: "pause" },
        },
      },
    },
  },
);
The merged policy is stored on workflow.opts.alertPolicy. Rule names are policy keys for your integration; the core engine does not attach built-in behavior to those names in this release.

​
Merge Semantics

  • defaults merge shallowly.
  • defaults.labels merge by key.
  • rules merge by rule name, and workflow-level fields win when the same rule appears in both places.
  • reactions merge by reaction name, and workflow-level definitions replace module-level definitions with the same name.

​
Reaction Kinds

KindUse for
emit-onlyRecord the alert without pausing, cancelling, or external delivery.
pausePause the run for operator intervention.
cancelStop the run when continuing would be unsafe.
open-approvalEscalate into a human approval step.
deliverSend the alert to a logical destination handled by your runtime integration.
You can reference a named reaction from rules or inline a reaction object directly.

​
Runtime Surface

In 0.16, alertPolicy is workflow metadata plus a durable alert storage model. The core engine does not run built-in alert evaluators, poll approval age, execute delivery clients, or create pause/cancel/approval reactions automatically. Runtime integrations can:
  • Read the merged policy from workflow.opts.alertPolicy.
  • Persist alert instances with SmithersDb.insertAlert().
  • Query active alerts with SmithersDb.listAlerts().
  • Acknowledge, resolve, or silence alert rows with the DB adapter or CLI.

​
Durable Alert Instances

Alert rows live in _smithers_alerts. The row shape includes:
FieldPurpose
alertIdStable alert identifier.
runId, nodeId, iterationOptional workflow location.
policyNameRule or policy key that produced the alert.
severityinfo, warning, or critical.
statusfiring, acknowledged, silenced, or resolved.
fingerprintOptional dedupe key supplied by your integration.
owner, runbook, labelsJson, reactionJsonMaterialized policy metadata.
sourceEventTypeOptional source event name.
firstFiredAtMs, lastFiredAtMs, occurrenceCountRecurrence tracking.
silencedUntilMs, acknowledgedBy, resolvedByOperator state.

​
CLI

smithers alerts list
smithers alerts ack <alert-id>
smithers alerts resolve <alert-id>
smithers alerts silence <alert-id>
list returns active firing, acknowledged, and silenced alerts. Use --format json when another process needs to consume the rows.

​
Reactions and Delivery

Reaction objects are stored as data:
  • emit-only
  • pause
  • cancel
  • open-approval
  • deliver
Your runtime boundary decides how to interpret those reactions. For example, deliver can route to Slack, PagerDuty, email, or an internal incident feed, but Smithers does not bundle those transports.
  • Use alert policy for operational conditions such as failed runs, approval timeouts, or budget breaches.
  • Keep destinations logical and stable, for example oncall, author, or incident-feed.
  • Put transport details in your notifier boundary, not in workflow code.
  • Avoid using alert policy for every ordinary business notification.