# Automation SDK

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

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:

```bash
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:

```bash
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 runs | Transport | Credential | Reporting record / business execution owner |
| --- | --- | --- | --- |
| Existing CI, scheduler, service or script | `external` | Job-scoped `ingest-runner` API key | SDK reports the record; existing automation owner executes work |
| Playwright job deliberately dispatched by BernOps | `native` | Worker-injected loopback token; no API key | Worker/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.

```bash
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](/docs/automation-sdk#cicd-live-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](/docs/github-integration#ci-check-observation) 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):

```bash
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](/docs/workers-and-pool#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

| API | Behavior |
| --- | --- |
| `run.log.debug/info/warn/error` | Captures a structured log and returns queue admission immediately. |
| `run.step` / `run.startStep` | Creates callback-managed or manually ended steps. Pass a real parent step handle for detached work. |
| `run.metric.gauge/count/rate/duration` | Captures low-cardinality metrics. Durations are milliseconds. |
| `run.progress` | Reports count, percent, or indeterminate advisory progress. |
| `run.attach` | Hashes, uploads, and persistently acknowledges one replayable attachment. Always await it. |
| `run.flush` | Waits 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:

| Error | Typical action |
| --- | --- |
| `BernOpsConfigurationError` | Fix incomplete or ambiguous transport, URL, credential, delivery, or redaction configuration. |
| `BernOpsAuthenticationError` | Rotate or correct the key, or investigate the current worker assignment. Do not retry unchanged credentials. |
| `BernOpsValidationError` | Correct unsupported or invalid telemetry, progress, metric, or attachment input. |
| `BernOpsCapabilityError` | Branch on negotiated capabilities and lifecycle ownership. |
| `BernOpsStateError` | Stop conflicting terminal or step calls and check for stale state. |
| `BernOpsTransportError` | Inspect `status`, `requestId`, `retryAfterMs`, and `retryable`. |
| `BernOpsDeliveryError` | Inspect the immutable `report` returned by a strict delivery boundary. |
| `BernOpsFinalizedRunError` | Treat 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

| Symptom | Check |
| --- | --- |
| Transport is incomplete or ambiguous | Select `external` or `native` explicitly and remove variables belonging to the other transport. |
| External URL is rejected | Use HTTPS. For a local test, use an explicit constructor with literal loopback and `allowInsecureLoopback: true`. |
| Authentication fails | Verify job/project binding and key rotation. Do not retry an unchanged rejected credential. |
| Native identity or capability fails | Create a new client inside the current worker assignment; never reuse copied bridge values. |
| A durable external run is finalized | Reuse 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 out | Inspect `onDiagnostic`, the report, and `droppedByReason`; fix transport and timeout causes before increasing queue bounds. |
| Attachment changes or cannot be reopened | Keep path/byte sources stable and return a new identical unread stream from each factory call. |
| The process does not exit | Await 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.

## Related references

- [API keys and scopes](/docs/api-keys-scopes)
- [Playwright jobs](/docs/playwright-jobs)
- [Runtime variables](/docs/runtime-variables)
- [Workers and execution](/docs/workers-execution)
- [REST API reference](/docs/api)

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.
