Documentation
Documentation/Integrations

Automation SDK

Lightweight reporting on existing automations without execution ownership; current SDK limits and separate native worker mode.

sdktypescriptexternal runsnative bridgetelemetrylightweight monitoringobservation-only
View Markdown
On this page

BernOps adds lightweight visibility to existing automations: live logs, observed steps, progress, metrics and outcomes. External monitoring does not replace or execute the automation. Its existing scheduler, CI system, service or script stays in control.

The private TypeScript SDK covers external Node.js reporting and separately selected BernOps-managed Playwright jobs. This guide describes 0.1.0-internal.3, a private UNLICENSED artifact, not a public registry package. External consumers install the exact retained bundle; native jobs use their worker operator's provisioned artifact.

Lightweight external monitoring contract

  • Keep existing commands, startup, scheduling, business retries, cancellation, signals, exit status and errors unchanged.
  • Report observations at existing event boundaries. SDK delivery retries concern telemetry only, never re-execution of business work.
  • Use bounded reporting overhead/buffering and explicit loss/degradation. A reporting heartbeat is not proof that business work is healthy.
  • Do not add a command launcher, process supervisor, replacement scheduler or durable recovery framework merely to add eyes to an automation.
Goal versus current SDK behavior

client.run() awaits remote run creation before invoking its callback. startRun() also awaits opening; configuration, authentication and opening failures can throw even with failurePolicy: 'diagnostic'. Neither API alone guarantees passive startup. Do not put the sole business invocation inside an SDK callback or behind awaited reporting initialization. Missing non-gating support is an SDK/product gap to qualify and fix, not a reason to replace the automation with a large monitoring framework. This documentation changes no runtime behavior.

Native jobs deliberately dispatched to BernOps workers remain a separate execution mode; their worker/Playwright owns execution and final status. External observation grants no such authority.

Prerequisites and installation

  • Use Node.js 22 or 24 for external automations and local native-job authoring. Node.js 24 is recommended.
  • For an external automation or local type-checking, ask your BernOps release owner for the matching .tgz, .tgz.sha256, and .manifest.json files. Keep the three files together.
  • Import only from @bernops/automation. ESM, CommonJS, and TypeScript consumers are supported; deep imports are not.

Verify the checksum before installing the artifact into an external automation or local authoring project:

Terminal
export SDK_ARTIFACT_DIR=/absolute/path/to/retained-candidate
export SDK_TARBALL="$SDK_ARTIFACT_DIR/bernops-automation-0.1.0-internal.3.tgz"
 
cd "$SDK_ARTIFACT_DIR"
sha256sum --check "$(basename "$SDK_TARBALL").sha256"
 
cd /absolute/path/to/your-automation
npm install --offline --ignore-scripts --no-audit --no-fund \
  --registry=https://registry.invalid/ "$SDK_TARBALL"
npm ls @bernops/automation

The SHA-256 sidecar must come from the same trusted release as the manifest. A release owner with the matching BernOps source revision can run the complete manifest, package-content, declaration, and clean-consumer gate:

Terminal
cd /absolute/path/to/bernops/sdk/typescript
npm run artifact:verify -- --manifest \
  "$SDK_ARTIFACT_DIR/bernops-automation-0.1.0-internal.3.manifest.json"
Use one exact artifact

For external and local projects, do not replace the tarball with a workspace link, source-directory install, mutable alias, deep import, or public registry fallback. A deployed native job does not use your local node_modules; its worker provisions the package. If either artifact version differs from this guide, use the matching documentation and compatibility policy instead of assuming compatibility.

Choose a transport

Where the automation runsTransportCredentialReporting record / business execution owner
Existing CI, scheduler, service or scriptexternalJob-scoped ingest-runner API keySDK reports the record; existing automation owner executes work
Playwright job deliberately dispatched by BernOpsnativeWorker-injected loopback token; no API keyWorker/Playwright owns the dispatched execution and record

Select the transport explicitly with BernOps.fromEnv({ transport: 'external' }) or BernOps.fromEnv({ transport: 'native' }). Use auto only when the deployment guarantees exactly one complete configuration. Selection fails closed and never falls back after authentication, TLS, identity, or capability errors. For external observation, this closes the reporting channel—not the existing business process; isolate/report unavailability without weakening security or taking execution ownership.

External quick start

Create an external job and an ingest-runner key, then store the plaintext key in the process secret manager. The minimal writer scopes are runs:write, runs:finish, logs:write, steps:write, metrics:write, progress:write, and attachments:write. Read and admin scopes are not required by the SDK writer.

Terminal
export BERNOPS_BASE_URL=https://bernops.example
export BERNOPS_API_KEY='job-scoped-secret'
export BERNOPS_EXTERNAL_JOB_ID='external-job-uuid'
export AUTOMATION_RUN_ID='scheduler-attempt-123'

Set AUTOMATION_RUN_ID from a durable scheduler, CI-system, or business-attempt ID. Reuse that value when the same attempt is retried; do not generate a new ID on each process start.

Construct BernOps.fromEnv({ transport: 'external', failurePolicy: 'diagnostic' }) inside a reporting-only boundary. Acquiring a handle through startRun() still awaits remote opening and can reject; it must not be a prerequisite for starting the existing automation. Managed client.run()/callback steps remain explicitly coupled API conveniences, not the passive external default.

This live-event example accepts an already-open reporting handle. It runs no business work, changes no process handling and returns queue admission—not persistence. Establishing that handle independently of startup still needs a qualified integration; this is not an invented passive adapter.

ts
import { type RunHandle } from '@bernops/automation';
 
export function reportObservedProgress(
  record: RunHandle,
  processed: number,
  total: number,
): boolean {
  try {
    return [
      record.log.info('Progress observed'),
      record.metric.gauge('records.processed', processed, { unit: 'items' }),
      record.progress({ current: processed, total, stage: 'importing' }),
    ].every(result => result.accepted);
  } catch {
    return false; // Report degradation through an existing bounded diagnostic sink.
  }
}

BERNOPS_EXTERNAL_JOB_ID identifies the saved reporting job; externalRunId identifies the existing scheduler/CI/business attempt. Reuse that identity for supported telemetry retries. Never create or replay business work because reporting failed or its record was finalized.

Explicit startStep()/step end() and external complete()/fail() report boundaries/outcomes observed from the existing owner. Their reporting promises can reject. Isolate them and bounded client.shutdown() from business errors and process control; report unknown/degraded telemetry honestly rather than inventing success/failure. SDK interruption may attempt failure finalization of its record; it is not authoritative business cancellation. See CI/CD monitoring.

CI/CD live SDK monitoring

The broad prototype remains retired. Optional source wiring covers the repository's eight workflows and sixteen job definitions, including matrix variants, using the same reporting-only SDK process. It never launches commands, intercepts stdout/stderr, retries work or forwards signals. SDK initialization cannot gate business startup; no SDK runtime change is required. Backend retains its three diagnostic stages; other jobs initially report a job-level open observation, fixed safe messages and indeterminate progress, not invented per-step percentages.

Expanded activation requires reviewed, preinstalled observer files in BERNOPS_CI_REPORTER_DIRECTORY, the exact approved SDK in BERNOPS_CI_SDK_DIRECTORY, HTTPS BERNOPS_CI_BASE_URL, and BERNOPS_CI_OBSERVATION_ENABLED=true. Each static profile has a job-bound writer and job ID; backend retains BERNOPS_CI_BACKEND_JOB_ID / BERNOPS_CI_BACKEND_API_KEY. An existing Node 22/24 is required; BERNOPS_CI_NODE optionally selects it. Matrix variants and GitHub run attempts have distinct identities.

Writers must be protected-environment secrets, never repository/organization secrets available to PR workflows. An if: main condition alone is not a security boundary against changed PR YAML. Verify server-side exact-main deployment restrictions and exclude PR merge refs, other branches and tags before provisioning. Preserve existing protected release/staging environments and approvals. If safe admission is unavailable, use webhook-only coverage. Backend remains push-main-only; other registered trusted jobs can observe their existing main/manual or authorized controller runs. PRs receive no writer. The existing repository-level backend writer needs a coordinated replacement/revocation cutover; source wiring alone does not perform it.

A private nonblocking FIFO carries only bounded observations. Missing readers/full queues drop observations, not business work. Requests have a five-second/one-attempt ceiling; flush/shutdown one second each; post-business cleanup waits at most ten seconds. Same-UID separation is not isolation. The pinned SDK cannot faithfully finalize a cancelled run: the reporters leave that record explicitly incomplete rather than inventing failure/success. Signed GitHub check observations retain native cancellation/skipped/neutral states and authoritative completed-job outcomes, including post-job cleanup. Source wiring is not production qualification: verify actual live visibility after approved activation. GitHub owns job results; CI success or NOT_CONFIRMED is not deployment proof.

Qualify this boundary as well as the SDK's existing lifecycle fixtures:

  1. Existing work starts even if reporting initialization is unavailable; commands, retries, signals, errors and exit status stay unchanged.
  2. Real logs, an open observed step and progress appear in the browser before business completion, without relying on final flush to make them visible.
  3. Reporting overhead/buffering stays bounded, loss is explicit, and reconnect recovers persisted observations without duplicating or replaying business work.

The current npm run integration:live fixture uses one exact BERNOPS_SDK_ARTIFACT_MANIFEST on dev-acceptance. Its warmed local ≤2-second target is not a hosted SLA; the backend cases separately check live visibility, unchanged business exits and unavailable ingestion. Report any missing SDK capability as a product gap instead of adding another orchestration layer. This guide grants no production activation, installer/service or deployment authority.

After authorized docs publication (local generation is not deployment):

Terminal
bernops docs search "lightweight automation monitoring"
bernops docs get automation-sdk#monitoring-contract
bernops docs get automation-sdk#cicd-live-monitoring

Native Playwright quick start

Do not add a tarball or package installation command to a saved BernOps Playwright job. With the approved private bootstrap installed, run bernops setup and choose 3 (automation worker) or 4 (both); the menu defaults to auth-only. Unified worker setup obtains a signed immutable release with the exact private SDK already bundled, checks real SDK/browser readiness, and requires separate workspace approval for native_bridge_v1 plus a confirmed worker connection. No source checkout build, public SDK install, or artifact mount is part of that flow. A local package installation is useful for authoring and type-checking only; it does not provision the deployed worker. Existing legacy workers are not silently upgraded. Ask the operator to check release availability and approved capabilities if the package import or native capability is unavailable.

The BernOps worker injects the bridge configuration for each execution. Do not set or copy AB_LOG_URL, BERNOPS_BRIDGE_TOKEN, BERNOPS_RUN_ID, or BERNOPS_PROJECT_ID, and do not add a BERNOPS_API_KEY to the job.

ts
import { test, expect } from '@playwright/test';
import { BernOps } from '@bernops/automation';
 
test('checkout', async ({ page }) => {
  const client = BernOps.fromEnv({
    transport: 'native',
    onDiagnostic(diagnostic) {
      console.warn(`[bernops:${diagnostic.code}] ${diagnostic.message}`);
    },
  });
 
  try {
    const capabilities = await client.capabilities();
    expect(capabilities.lifecycleOwner).toBe('worker');
 
    await client.run({ name: 'checkout' }, async (run) => {
      run.log.info('opening checkout');
      await run.step('submit order', async () => {
        await page.goto('/checkout');
      });
    });
  } finally {
    await client.shutdown();
  }
});

The worker and Playwright own start, heartbeat, and terminal status. run.complete() and run.fail() exist on the shared type but reject in native mode with BernOpsCapabilityError and code === 'lifecycle_owned_by_worker'. Call capabilities() before optional behavior: native persistent attachments are available only when persistentAttachments is true, and the returned size limits are authoritative.

Telemetry, progress, and attachments

APIBehavior
run.log.debug/info/warn/errorCaptures a structured log and returns queue admission immediately.
run.step / run.startStepCreates callback-managed or manually ended steps. Pass a real parent step handle for detached work.
run.metric.gauge/count/rate/durationCaptures low-cardinality metrics. Durations are milliseconds.
run.progressReports count, percent, or indeterminate advisory progress.
run.attachHashes, uploads, and persistently acknowledges one replayable attachment. Always await it.
run.flushWaits for accepted work through the current watermark and leaves the run writable.

Progress may coalesce while pending, so sequence gaps are valid. It never determines pass/fail and BernOps does not fabricate 100 percent for a running execution. Keep metric names and tags low-cardinality: do not use email addresses, user IDs, request IDs, timestamps, full URLs, or free-form values as names or tags.

An attachment must use exactly one replayable source: path, Uint8Array or Blob data, or an open factory that returns a fresh unread stream for every delivery attempt.

ts
// `run` is an existing reporting handle; this does not execute business work.
const attachment = await run.attach({
  path: '/tmp/import-summary.json',
  fileName: 'import-summary.json',
  contentType: 'application/json',
});
 
console.log(attachment.attachmentId, attachment.sizeBytes, attachment.duplicate);

Supported content types are PNG, JPEG, WebP, plain text, JSON, CSV, and PDF. Do not change path or stream bytes until attach() settles. The acknowledgement represents a persistent metadata and storage commit, not queue admission.

Delivery, errors, and security

Log, metric, and progress methods return an EnqueueResult; accepted: true means only that the in-memory queue accepted the event. Network delivery is observed at flush(), external terminal methods, and shutdown() through a DeliveryReport containing delivered, duplicate, dropped, pending, failed, timedOut, and droppedByReason.

Default failurePolicy: 'diagnostic' handles background delivery/automatic-finalization degradation through diagnostics and delivery reports. It is not a universal non-gating guarantee: configuration, authentication, remote opening and explicit operations can reject, and failed client.run() opening prevents callback execution. Keep them inside the reporting boundary. strict explicitly couples telemetry failure to successful callback results and is not the observation-only default. The SDK preserves an original managed-callback error; that is narrower than preserving every independently owned automation path.

Branch on public error classes, code, retryable, and class-specific safe fields rather than matching message text:

ErrorTypical action
BernOpsConfigurationErrorFix incomplete or ambiguous transport, URL, credential, delivery, or redaction configuration.
BernOpsAuthenticationErrorRotate or correct the key, or investigate the current worker assignment. Do not retry unchanged credentials.
BernOpsValidationErrorCorrect unsupported or invalid telemetry, progress, metric, or attachment input.
BernOpsCapabilityErrorBranch on negotiated capabilities and lifecycle ownership.
BernOpsStateErrorStop conflicting terminal or step calls and check for stale state.
BernOpsTransportErrorInspect status, requestId, retryAfterMs, and retryable.
BernOpsDeliveryErrorInspect the immutable report returned by a strict delivery boundary.
BernOpsFinalizedRunErrorTreat the durable attempt as already terminal or intentionally use a new business-attempt ID.
  • External endpoints require HTTPS. Plain HTTP is accepted only for literal 127.0.0.1 or [::1] test URLs configured explicitly with allowInsecureLoopback: true; URL credentials and redirects are rejected.
  • Redaction is defense in depth. Never capture authorization headers, cookies, tokens, personal data, card data, or unrestricted request and response bodies.
  • Attachment bytes are not redacted. Scrub files before upload, avoid unnecessary screenshots, and apply suitable retention and access controls.
  • Queues and retries are bounded and in memory; they do not survive SIGKILL, OOM, host loss, or power loss.
  • SDK shutdown stops reporting, not the external process. Interrupting an active external callback (including wait-deadline expiry) can make client.run() reject with run_interrupted despite callback success under diagnostic policy. Handle bounded cleanup inside the reporting boundary; preserve the existing host's signal/exit policy. Imports install no signal handlers.

Troubleshooting

SymptomCheck
Transport is incomplete or ambiguousSelect external or native explicitly and remove variables belonging to the other transport.
External URL is rejectedUse HTTPS. For a local test, use an explicit constructor with literal loopback and allowInsecureLoopback: true.
Authentication failsVerify job/project binding and key rotation. Do not retry an unchanged rejected credential.
Native identity or capability failsCreate a new client inside the current worker assignment; never reuse copied bridge values.
A durable external run is finalizedReuse it only to observe the prior terminal result, or choose a new ID for a genuinely new business attempt.
Delivery is pending, dropped, failed, or timed outInspect onDiagnostic, the report, and droppedByReason; fix transport and timeout causes before increasing queue bounds.
Attachment changes or cannot be reopenedKeep path/byte sources stable and return a new identical unread stream from each factory call.
The process does not exitAwait attachments, flush or terminal boundaries, and client.shutdown(); then clean up host-owned timers and listeners.

Do not hide permanent failures with unbounded retries, broader scopes, disabled TLS, redirect following, raw response-body logging, or larger queues.

The installed artifact includes its matching README.md, CHANGELOG.md, COMPATIBILITY.md, UPGRADING.md, and TypeScript declarations. Use those versioned files and your IDE's package-root types for exact signatures; do not copy an API signature from a different SDK revision.