@holostaff/sdk 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,7 @@
 # @holostaff/sdk
 
-Lifetime identity, stage detection, and custom signal probes for the holostaff runtime.
+Lifetime identity, stage detection, custom signal probes, and the
+intervention widget for the Holostaff runtime.
 
 ## Install
 
@@ -19,8 +20,8 @@ holostaff.init({
   tenantId: 'your-tenant-id',
 })
 
-// At workflow boundaries (placed by the deploy PR's agent).
-holostaff.markStageEntry('selection')
+// At journey-stage boundaries (placed by the deploy PR's agent).
+holostaff.markStageEntry('adoption')
 
 // On sign-in completion.
 holostaff.identify(user.id)
@@ -30,25 +31,34 @@ holostaff.clearIdentity()
 
 // On host-app events the scan detected as worth observing.
 holostaff.emitSignal('first_resource_created', { kind: 'project' })
+
+// Only needed if you render interventions yourself — the built-in
+// widget reports outcomes automatically.
+holostaff.reportOutcome(interventionId, 'engaged')
 ```
 
-All methods are fail-soft — they never throw into your code.
-Errors route to the optional `onError` callback you pass to `init()`.
+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()`.
 
 ## What this SDK does (and doesn't)
 
 **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.
-- Open a server-sent-events channel for future intervention dispatch.
+- 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.
+- Hold a server-sent-events channel open and render `text` interventions
+  as a shadow-DOM pill (dismiss / engage / 30s auto-ignore), reporting
+  outcomes back automatically.
 
 **Does not (yet)**
-- Capture rrweb / DOM events — that lives in the existing holostaff widget.
-- Render interventions — Wave 4.
-- Manage idle-pause cadence — runtime-side concern.
+- Render non-text modalities (voice / email / sms / phone /
+  screen automation) — those events are surfaced to `onError` and skipped.
+- Capture rrweb / DOM events — that lives in the Holostaff widget script.
 
 ## References
 
-- [copilot-runtime-design.md](../documents/copilot-runtime-design.md) — runtime control loop + identity model.
-- [copilot-deploy-design.md](../documents/copilot-deploy-design.md) — how the deploy PR wires `holostaff.init(...)` + the instrumentation calls into customer code.
+- [docs.holostaff.ai](https://docs.holostaff.ai)

package/dist/transport.d.ts

@@ -31,10 +31,10 @@ export declare function postBeacon(cfg: TransportConfig, path: string, body: Rec
  * Open an SSE channel for intervention commands. Returns the
  * EventSource so the caller can attach listeners + close it.
  *
- * Wave 1c: the channel opens but the server doesn't dispatch any
- * `fire_intervention` events yet (Wave 4). We still establish it now
- * so customer apps wire it up once and reap commands automatically
- * when the firing engine lands.
+ * The server pushes `fire_intervention` events on this channel when a
+ * monitoring-agent decision passes suppression (Wave 3e). The widget
+ * subsystem subscribes and renders text interventions; other
+ * modalities are ignored client-side for now.
  */
 export declare function openCommandStream(cfg: TransportConfig, sessionId: string, tenantId: string, sourceId: string): EventSource | null;
 //# sourceMappingURL=transport.d.ts.map

package/dist/transport.js

@@ -89,10 +89,10 @@ export function postBeacon(cfg, path, body) {
  * Open an SSE channel for intervention commands. Returns the
  * EventSource so the caller can attach listeners + close it.
  *
- * Wave 1c: the channel opens but the server doesn't dispatch any
- * `fire_intervention` events yet (Wave 4). We still establish it now
- * so customer apps wire it up once and reap commands automatically
- * when the firing engine lands.
+ * The server pushes `fire_intervention` events on this channel when a
+ * monitoring-agent decision passes suppression (Wave 3e). The widget
+ * subsystem subscribes and renders text interventions; other
+ * modalities are ignored client-side for now.
  */
 export function openCommandStream(cfg, sessionId, tenantId, sourceId) {
     if (typeof EventSource === 'undefined')

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@holostaff/sdk",
-  "version": "0.3.0",
-  "description": "Holostaff SDK — lifetime identity, stage detection, and custom signal probes for the holostaff runtime.",
+  "version": "0.3.1",
+  "description": "Holostaff SDK — lifetime identity, stage detection, custom signal probes, and the intervention widget for the Holostaff runtime.",
+  "license": "Apache-2.0",
+  "homepage": "https://docs.holostaff.ai",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",