@holostaff/sdk

The Holostaff runtime for your app: the autopilot offer, the handover loop, and the safety envelope, in the user's own session. A workflow autopilot is a computer-use agent that lives inside your product; this SDK is the part that lives in the page. It also carries lifetime identity, stage detection, and custom signal probes.

Install

npm install @holostaff/sdk

Usage

import { holostaff } from '@holostaff/sdk'

// Once at app startup — the deploy PR adds this for you.
holostaff.init({
  sourceId: 'cli-source-abc',
  tenantId: 'your-tenant-id',
})

// At journey-stage boundaries (placed by the deploy PR's agent).
holostaff.markStageEntry('adoption')

// On sign-in completion.
holostaff.identify(user.id)

// On logout.
holostaff.clearIdentity()

// On host-app events the scan detected as worth observing.
holostaff.emitSignal('first_resource_created', { kind: 'project' })

Calls made before init() queue and replay once it runs, so import order is not load-bearing. All methods are fail-soft — they never throw into your code. Errors route to the optional onError callback you pass to init().

The autopilot layer

When a workflow is enabled and certified, the SDK renders everything the user sees of its autopilot:

• The offer card on the workflow, carrying the task's name (or the display name your team set). Nothing happens unless the user accepts: handover is always the user's explicit act.
• The intent overlay: the few specifics the task needs, collected at handover.
• The run itself: one small action at a time, in the user's own session and tab, with every target highlighted before anything happens.
• Questions anchored beside the field they concern, never a modal over the form.
• The Allow pill on consequential clicks (pay, delete, submit, send, sign). No answer means no.
• The progress panel with an always-visible Stop.

The safety envelope

Enforced in the executor and the server, never only in a prompt:

• The autopilot runs with the user's own auth and permissions, same origin only. No credentials ever pass through Holostaff.
• Password, payment, and code fields are hard-refused: the autopilot points, the user types.
• Any keystroke from the user pauses the run. Per-workflow step budgets cap every run.

What this SDK also does

• Mint and persist a lifetime device id (localStorage + first-party cookie).
• Open / close a session bound to page lifecycle.
• POST identity / stage / signal / outcome events to the Holostaff runtime.
• Track the current SPA route and last-user-activity time, and forward them to the runtime on route changes plus a low-frequency heartbeat.
• Record the page structure and visible text so the autopilot can act from what is on screen, and batch it to the runtime. Password / email / tel inputs are always masked; mark rendered PII with the holostaff-mask (text) or holostaff-block (region) CSS classes; opt out entirely with init({ observe: { enabled: false } }). Data handling: holostaff.ai/security.

What it does on the page

• Nothing is sent before the first interaction. init() only mints ids and attaches listeners. The session opens, the command channel connects, the route signal and heartbeat start, and the autopilot catalog is fetched on the first trusted click, key press, scroll or touch. Bots and bounces that never interact send nothing, and no session is closed that never opened.
• The recorder loads on that first interaction, not at page load. It ships as a separate lazy chunk; the main import stays small. Calls to markStageEntry, emitSignal, identify and reportOutcome made before then queue and replay in order.
• Voice and the Theater are off by default. Enable them with init({ voice: { enabled: true }, theater: { enabled: true } }); their code loads lazily only when enabled, after the first interaction.
• Evaluation runs (window.__HS_EVAL__) open the gate immediately, since a synthetic driver never produces trusted input.

Changelog

0.13.0

• Default import is the lean core: presence chip, note, autopilot, route signals. Entry chunk about half the size of 0.12.
• Nothing is sent to Holostaff before the first trusted user interaction. Pre-interaction API calls queue and replay in order.
• The session recorder loads lazily on that first interaction (record-only build, about half the bytes it used to pull).
• Breaking: voice.enabled and theater.enabled now default to false. Hosts that relied on the defaults must opt in explicitly.

References

• docs.holostaff.ai
• What a workflow autopilot is
• The safety envelope