@wibly/sdk 0.1.0

package/src/consent.ts

@@ -0,0 +1,78 @@
+/**
+ * Consent contract surfaced by the SDK to the Player shell.
+ *
+ * Per Vibecode Dev Plan §B7 ("`consent.ts` — surface a
+ * `consent_required` callback when Persona memory access is rejected
+ * for missing consent (B3); the player shell (B6) renders the dialog")
+ * and Platform Spec §9.4.
+ *
+ * **Wire shape.** The Persona Service (chunk B3) returns
+ * `{ ok: false, kind: 'consent_required', personaId, playerId }` when
+ * a player-scope memory read is rejected for missing consent. The
+ * Runtime (chunk B8a) translates that into a server-emitted protocol
+ * `event` with `eventType: 'consent_required'` and a payload matching
+ * `ConsentRequiredPayload`. The SDK's `useEvent('consent_required',
+ * …)` hook (see `events.ts`) surfaces the payload to the Player shell;
+ * the shell renders `<ConsentPrompt>` (chunk B6's
+ * `apps-shells/player-web/src/components/consent-prompt.tsx`).
+ *
+ * **Persistence path.** When the player accepts, the shell calls
+ * `session.requestConsent(...)` which forwards to the User Portal's
+ * consent endpoint (chunk B17a). Until B17a lands the endpoint, the
+ * verb returns `Result.err({ kind: 'consent_persistence_not_wired' })`
+ * — the prompt callback still fires; only the grant-write is deferred.
+ *
+ * **Trap discipline** (chunk B7): the consent management surface lives
+ * in `apps/portal` (B17a), not here. The SDK exposes the mid-Session
+ * prompt verbs only — `requestConsent` (grant a fresh consent),
+ * surfaces via `useEvent('consent_required')`. Revoke / list lives on
+ * the User Portal Settings page.
+ *
+ * **Stable contract.** This module is consumed by the Player shell's
+ * `consent-flow.ts` reducer (chunk B6) — the type names + payload
+ * shape must stay stable across protocol-minor bumps. A breaking
+ * change here is a PROTOCOL_VERSION bump.
+ */
+
+/**
+ * Payload the SDK surfaces on a `consent_required` callback. Mirrors
+ * the shape the Persona Service emits (chunk B3) when `readMemoryEntry`
+ * rejects on missing player consent:
+ *
+ *   - `personaId`           — the Persona requesting memory access.
+ *   - `personaDisplayName`  — operator-friendly Persona name for the
+ *                             prompt copy.
+ *   - `scope`               — `session | group | player` per the
+ *                             `player_consent_scope` enum.
+ */
+export type ConsentRequiredPayload = {
+  readonly personaId: string;
+  readonly personaDisplayName: string;
+  readonly scope: 'session' | 'group' | 'player';
+};
+
+/**
+ * The decision the player makes in the prompt. `accepted` triggers the
+ * SDK to call `requestConsent` (which forwards to the User Portal
+ * endpoint); `declined` records intent locally and emits a lifecycle
+ * frame so the Host surface can surface the rejection if it cares.
+ */
+export type ConsentDecision = 'accepted' | 'declined';
+
+/**
+ * The SDK callback signature the Player shell binds against. The
+ * component resolves the returned promise; the SDK forwards the
+ * decision to the persistence path (B17a) on accept.
+ */
+export type ConsentRequiredCallback = (
+  payload: ConsentRequiredPayload,
+) => Promise<ConsentDecision>;
+
+/**
+ * Predicate used by the SDK's event multiplexer to recognise a wire
+ * event as a consent prompt. Exported so the player shell's bridge
+ * (B6 `session-consent-bridge.tsx`) can reuse the constant when
+ * registering its `useEvent` handler.
+ */
+export const CONSENT_REQUIRED_EVENT_TYPE = 'consent_required' as const;
+export type ConsentRequiredEventType = typeof CONSENT_REQUIRED_EVENT_TYPE;

package/src/control.ts

@@ -0,0 +1,44 @@
+/**
+ * Control verbs (per chunk B7 build: "control.ts — host control
+ * actions: pause, resume, advance phase. Map to typed emits.").
+ *
+ * Host-only verbs are surfaced as a `session.host` namespace on the
+ * `Session` returned by `createSession`. The verbs translate to
+ * `emit` frames with reserved `eventType` strings; the Runtime
+ * applies host-gating server-side (chunk B8a wires the auth, the
+ * SDK is unprivileged about who calls them).
+ *
+ * Reserved event types:
+ *
+ *   - `host.pause`          — request a pause; the server emits a
+ *                             `lifecycle` `session.paused`.
+ *   - `host.resume`         — resume from pause.
+ *   - `host.advance_phase`  — request the next phase. The Runtime
+ *                             may reject if no transition matches.
+ *   - `host.reclaim`        — reclaim the host slot from a hung
+ *                             host (the player who fires this
+ *                             becomes the new host if allowed).
+ */
+
+import type { EmitPayload } from '@wibly/internal-protocol';
+
+export const HOST_EVENT_TYPES = {
+  pause: 'host.pause',
+  resume: 'host.resume',
+  advancePhase: 'host.advance_phase',
+  reclaim: 'host.reclaim',
+} as const;
+
+export type HostEventType =
+  (typeof HOST_EVENT_TYPES)[keyof typeof HOST_EVENT_TYPES];
+
+export const buildHostEmitPayload = (
+  sessionId: string,
+  eventType: HostEventType,
+  detail: unknown = {},
+): EmitPayload =>
+  ({
+    sessionId,
+    eventType,
+    data: detail,
+  }) as EmitPayload;

package/src/errors.ts

@@ -0,0 +1,88 @@
+/**
+ * Categorised SDK error type.
+ *
+ * The SDK boundary returns `Result<T, SdkError>` rather than throwing
+ * (per Vibecode Dev Plan §4.3 and chunk A1). Each kind is a documented
+ * recovery shape:
+ *
+ *   - `not_connected`           — the caller invoked a method that
+ *                                 requires an open WebSocket session
+ *                                 before `createSession`'s connection
+ *                                 settled (or after `close()`).
+ *   - `protocol`                — the codec rejected an outbound or
+ *                                 inbound frame; carries the underlying
+ *                                 `@platform/protocol` `ProtocolError`
+ *                                 kind for diagnostics.
+ *   - `submit_rejected`         — the Runtime returned a structured
+ *                                 `error` frame for a `submit` /
+ *                                 `emit`. Carries the server's `code`
+ *                                 and `message` verbatim.
+ *   - `consent_required`        — the in-Session prompt fired and the
+ *                                 caller is awaiting decision; the
+ *                                 player shell renders the dialog.
+ *   - `consent_persistence_not_wired` — the SDK forwards a granted
+ *                                 consent to the User Portal endpoint
+ *                                 (chunk B17a); MVP returns this until
+ *                                 B17a ships the route. The mid-Session
+ *                                 callback still fires so the shell
+ *                                 renders the prompt; this error is
+ *                                 returned from `session.requestConsent`
+ *                                 only.
+ *   - `runtime_not_wired`       — `inference.*` / `voice.*` are routed
+ *                                 through the Runtime (chunk B8a). Until
+ *                                 B8a binds the inference verbs, the
+ *                                 SDK returns this so callers can render
+ *                                 the honest-stub state.
+ *   - `timeout`                 — an awaited server reply did not land
+ *                                 inside the request's deadline.
+ */
+export type SdkErrorKind =
+  | 'not_connected'
+  | 'protocol'
+  | 'submit_rejected'
+  | 'consent_required'
+  | 'consent_persistence_not_wired'
+  | 'runtime_not_wired'
+  | 'timeout';
+
+export type SdkError =
+  | { readonly kind: 'not_connected' }
+  | {
+      readonly kind: 'protocol';
+      readonly cause: string;
+    }
+  | {
+      readonly kind: 'submit_rejected';
+      readonly code: string;
+      readonly message: string;
+      readonly causeMessageId?: string;
+    }
+  | { readonly kind: 'consent_required' }
+  | { readonly kind: 'consent_persistence_not_wired' }
+  | { readonly kind: 'runtime_not_wired' }
+  | { readonly kind: 'timeout' };
+
+/**
+ * Render an `SdkError` to a short string. Used by `formatSdkError`
+ * call-sites and as the `Result.unwrap` error message — never log the
+ * raw error object because the caller may have attached an inner
+ * `cause` from `fetch` that contains response bodies or auth headers.
+ */
+export const formatSdkError = (e: SdkError): string => {
+  switch (e.kind) {
+    case 'not_connected':
+      return 'sdk: not connected to a session';
+    case 'protocol':
+      return `sdk: protocol error: ${e.cause}`;
+    case 'submit_rejected':
+      return `sdk: server rejected submit (${e.code}: ${e.message})`;
+    case 'consent_required':
+      return 'sdk: consent required';
+    case 'consent_persistence_not_wired':
+      return 'sdk: consent persistence endpoint is not yet wired (chunk B17a)';
+    case 'runtime_not_wired':
+      return 'sdk: runtime endpoint is not yet wired (chunk B8a)';
+    case 'timeout':
+      return 'sdk: request timed out';
+  }
+};

package/src/events.ts

@@ -0,0 +1,129 @@
+/**
+ * Event multiplexer for server-emitted `event` and `lifecycle` frames.
+ *
+ * The SDK keeps a single subscription table per session (chunk B7
+ * trap: "Don't let the AI inline state stores per call site"). The
+ * `client.createSession` factory binds the multiplexer to the
+ * transport's `onServerMessage` so handlers fire in source-of-truth
+ * order.
+ *
+ * Per chunk B7 build: "events.ts — typed subscriptions for server →
+ * client events. Auto-unsubscribe on session end."
+ */
+
+import type { EventPayload, LifecyclePayload } from '@wibly/internal-protocol';
+
+export type EventHandler<P> = (payload: P) => void;
+
+export type EventBusObserver = {
+  /** Number of currently-registered listeners for the given key. */
+  readonly listenerCount: (key: string) => number;
+};
+
+export type EventBus = {
+  readonly onEvent: <P = unknown>(
+    eventType: string,
+    handler: EventHandler<EventPayload & { data: P }>,
+  ) => () => void;
+  readonly onAnyEvent: (handler: EventHandler<EventPayload>) => () => void;
+  readonly onLifecycle: (
+    transition: string,
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+  readonly onAnyLifecycle: (
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+  /** Dispatched by the transport when an `event` frame arrives. */
+  readonly dispatchEvent: (payload: EventPayload) => void;
+  /** Dispatched by the transport when a `lifecycle` frame arrives. */
+  readonly dispatchLifecycle: (payload: LifecyclePayload) => void;
+  /** Drop all listeners — called on session close. */
+  readonly dispose: () => void;
+  readonly observer: EventBusObserver;
+};
+
+const EVENT_WILDCARD = '__any__' as const;
+
+export const createEventBus = (): EventBus => {
+  const eventListeners = new Map<string, Set<EventHandler<EventPayload>>>();
+  const lifecycleListeners = new Map<
+    string,
+    Set<EventHandler<LifecyclePayload>>
+  >();
+
+  const subscribe = <P>(
+    table: Map<string, Set<EventHandler<P>>>,
+    key: string,
+    handler: EventHandler<P>,
+  ): (() => void) => {
+    let bucket = table.get(key);
+    if (bucket === undefined) {
+      bucket = new Set();
+      table.set(key, bucket);
+    }
+    bucket.add(handler);
+    return () => {
+      const current = table.get(key);
+      if (current === undefined) return;
+      current.delete(handler);
+      if (current.size === 0) table.delete(key);
+    };
+  };
+
+  const dispatch = <P>(
+    table: Map<string, Set<EventHandler<P>>>,
+    key: string,
+    payload: P,
+  ): void => {
+    const exact = table.get(key);
+    if (exact !== undefined) {
+      for (const handler of Array.from(exact)) {
+        try {
+          handler(payload);
+        } catch {
+          // listeners must not throw; swallow to avoid cascading.
+        }
+      }
+    }
+    const wildcard = table.get(EVENT_WILDCARD);
+    if (wildcard !== undefined) {
+      for (const handler of Array.from(wildcard)) {
+        try {
+          handler(payload);
+        } catch {
+          // ignore
+        }
+      }
+    }
+  };
+
+  return {
+    onEvent: (eventType, handler) =>
+      subscribe(
+        eventListeners,
+        eventType,
+        handler as EventHandler<EventPayload>,
+      ),
+    onAnyEvent: (handler) =>
+      subscribe(eventListeners, EVENT_WILDCARD, handler),
+    onLifecycle: (transition, handler) =>
+      subscribe(lifecycleListeners, transition, handler),
+    onAnyLifecycle: (handler) =>
+      subscribe(lifecycleListeners, EVENT_WILDCARD, handler),
+    dispatchEvent: (payload) => {
+      dispatch(eventListeners, payload.eventType, payload);
+    },
+    dispatchLifecycle: (payload) => {
+      dispatch(lifecycleListeners, payload.transition, payload);
+    },
+    dispose: () => {
+      eventListeners.clear();
+      lifecycleListeners.clear();
+    },
+    observer: {
+      listenerCount: (key) =>
+        (eventListeners.get(key)?.size ?? 0) +
+        (lifecycleListeners.get(key)?.size ?? 0),
+    },
+  };
+};

package/src/index.ts

@@ -0,0 +1,121 @@
+/**
+ * `@platform/sdk` — Studio SDK (client side).
+ *
+ * Built in chunk B7; see `docs/chunks/B7.md` for the close note.
+ *
+ * Public entry points:
+ *
+ *   - `createSession(config)` — main factory returning a `Session`.
+ *     Player shell (chunk B6) + any future Studio SDK consumer wires
+ *     a single session per surface; the React provider mounts it
+ *     once.
+ *
+ *   - `@platform/sdk/react` — React provider + hooks
+ *     (`SessionProvider`, `useSession`, `useSessionState`,
+ *     `useConnectionState`, `useSessionEvent`, `useSessionLifecycle`,
+ *     `useConsentPrompt`). The `react` peer dependency is optional;
+ *     non-React consumers import only from the root entry.
+ *
+ * The SDK is published to npm as `@wibly/sdk` via
+ * `tools/scripts/release-sdk.ts` (chunk B7). The rewrite turns
+ * `@platform/*` deps into `@wibly/*` and bumps the SemVer.
+ */
+
+export {
+  createSession,
+  formatSdkError,
+  type Session,
+  type SessionConfig,
+  type SessionState,
+} from './client.js';
+
+export {
+  type SdkError,
+  type SdkErrorKind,
+} from './errors.js';
+
+export {
+  CONSENT_REQUIRED_EVENT_TYPE,
+  type ConsentDecision,
+  type ConsentRequiredCallback,
+  type ConsentRequiredEventType,
+  type ConsentRequiredPayload,
+} from './consent.js';
+
+export {
+  type ConnectionState,
+  type OptimisticProjection,
+  type SessionStore,
+  type SessionStoreSnapshot,
+  applyPatches,
+} from './store.js';
+
+export {
+  type EmitArgs,
+  type PendingSubmit,
+  type SubmitArgs,
+} from './submit.js';
+
+export {
+  HOST_EVENT_TYPES,
+  type HostEventType,
+} from './control.js';
+
+export {
+  INFERENCE_EVENT_PREFIX,
+  buildInferenceRequest,
+  type InferenceCallInput,
+  type InferenceCallSuccess,
+  type SdkCallKind,
+  type SdkQualityTier,
+  type SerialisedInferenceRequest,
+  type SessionInference,
+} from './inference.js';
+
+export {
+  VOICE_EVENT_PREFIX,
+  estimateAudioDurationMs,
+  type SessionVoice,
+  type SpeakInput,
+  type SpeakSuccess,
+} from './voice.js';
+
+export {
+  type EventBus,
+  type EventHandler,
+} from './events.js';
+
+export {
+  type LifecycleBindings,
+} from './lifecycle.js';
+
+export {
+  createServerTimeSource,
+  type RecordedEvent,
+  type ServerTimeSource,
+} from './time.js';
+
+export {
+  computeBackoffMs,
+  createTransport,
+  decideStateDiffAction,
+  type Transport,
+  type TransportConfig,
+  type TransportObserver,
+  type WebSocketFactory,
+  type WebSocketLike,
+} from './transport.js';
+
+export {
+  registerProjection,
+  type PendingProjectionHandle,
+} from './predictive.js';
+
+// Re-export the JSON-schema utilities from shared so consumers can
+// declare wire-shaped output schemas without pulling shared in directly.
+export {
+  jsonSchemaToZod,
+  zodToJsonSchema,
+  UnsupportedSchemaError,
+  type JsonSchema,
+} from '@wibly/internal-shared';

package/src/inference.ts

@@ -0,0 +1,140 @@
+/**
+ * Inference verbs (per chunk B7 build: "inference.ts — typed call
+ * helpers: session.inference.host(slots), .judge(slots),
+ * .classify(slots), etc. — calls the Gateway through the Runtime
+ * (the SDK never holds the gateway-auth key).").
+ *
+ * The chunk-B7 contract is:
+ *
+ *   1. The caller invokes `session.inference.<verb>({ slots, output,
+ *      qualityTier? })`.
+ *   2. The SDK serialises any caller-declared Zod output schema to
+ *      JSON Schema (via `@platform/shared/json-schema.ts`).
+ *   3. The SDK sends an `emit` frame with a reserved `inference.*`
+ *      event type. The Runtime (chunk B8a) receives it, signs the
+ *      request, forwards to the Gateway, and emits a follow-up
+ *      `event` frame with the result keyed by the original message
+ *      id.
+ *   4. The SDK matches the inbound event against the pending call's
+ *      id and resolves the typed result.
+ *
+ * **Why `emit` and not a new wire kind?** The protocol already
+ * carries `emit` for asynchronous client → server work; reserving an
+ * `inference.*` namespace on `eventType` keeps the surface compact
+ * and avoids a `PROTOCOL_VERSION` bump. The chunk-B8a Runtime is
+ * what enforces the gating + signing.
+ *
+ * Until chunk B8a wires the Runtime-side handler, the SDK's
+ * inference verbs return `Err({ kind: 'runtime_not_wired' })`. The
+ * SDK still serialises the schema + payload so the chunk-B7 surface
+ * is testable (the JSON Schema + outbound `emit` shape are
+ * regression-protected); the runtime-side roundtrip lights up with
+ * B8a.
+ */
+
+import type { z, ZodTypeAny } from 'zod';
+
+import { zodToJsonSchema, type JsonSchema } from '@wibly/internal-shared';
+import type { Result } from '@wibly/internal-shared';
+
+import type { SdkError } from './errors.js';
+
+/**
+ * Quality tier surfaced on the SDK boundary. Mirrors
+ * `QualityTierSchema` from `@wibly/internal-manifest` but kept as a string
+ * literal here so the SDK doesn't pull in the manifest's full Zod
+ * runtime (the manifest schemas are heavy; the SDK only needs the
+ * literal set).
+ */
+export type SdkQualityTier = 'preview' | 'standard' | 'high';
+
+/**
+ * Recognised call kinds. Matches `CallKindSchema`'s enum; duplicated
+ * here to keep the SDK type-only against the manifest package.
+ *
+ * `host_open_phase` / `narrate_event` / `judge_submissions` /
+ * `host_persona_response` / `classify` is the chunk-B2 set; chunk
+ * B12 extends it. The SDK accepts any string at runtime — the
+ * `CallKind` union exists as an authoring aid in TypeScript.
+ */
+export type SdkCallKind =
+  | 'host_open_phase'
+  | 'narrate_event'
+  | 'judge_submissions'
+  | 'host_persona_response'
+  | 'classify'
+  | (string & {});
+
+export type InferenceCallInput<TOutput extends ZodTypeAny> = {
+  readonly callKind: SdkCallKind;
+  readonly slots: Readonly<Record<string, unknown>>;
+  readonly output?: TOutput;
+  readonly qualityTier?: SdkQualityTier;
+  /**
+   * Optional idempotency key. The Runtime forwards it to the
+   * Gateway's `metadata.idempotencyKey`. Use case: a host that
+   * wants to retry without double-billing.
+   */
+  readonly idempotencyKey?: string;
+};
+
+export type InferenceCallSuccess<TOutput extends ZodTypeAny> = {
+  /** Raw model output (the Gateway's `output`). */
+  readonly output: string;
+  /** Parsed structured response. `null` if no schema was provided. */
+  readonly structured: TOutput extends ZodTypeAny ? z.infer<TOutput> | null : null;
+  /** Gateway usage block. Surface for debug; the operator-side
+   * dashboards use the audit ledger instead. */
+  readonly usage: {
+    readonly model: string;
+    readonly tokensIn: number;
+    readonly tokensOut: number;
+    readonly latencyMs: number;
+    readonly costUsd: number;
+  };
+};
+
+export type SerialisedInferenceRequest = {
+  readonly callKind: SdkCallKind;
+  readonly qualityTier: SdkQualityTier;
+  readonly slots: Readonly<Record<string, unknown>>;
+  readonly outputSchema: JsonSchema | undefined;
+  readonly idempotencyKey: string | undefined;
+};
+
+export const INFERENCE_EVENT_PREFIX = 'inference.' as const;
+
+/**
+ * Build the wire payload for an inference call. Surfaced as a pure
+ * helper so the testkit can assert the serialised shape without
+ * spinning a transport.
+ */
+export const buildInferenceRequest = <TOutput extends ZodTypeAny>(
+  input: InferenceCallInput<TOutput>,
+): SerialisedInferenceRequest => ({
+  callKind: input.callKind,
+  qualityTier: input.qualityTier ?? 'standard',
+  slots: input.slots,
+  outputSchema: input.output ? zodToJsonSchema(input.output) : undefined,
+  idempotencyKey: input.idempotencyKey,
+});
+
+/**
+ * The async `Session.inference` namespace. Each verb is bound by
+ * `client.ts` to the live transport; the Runtime wires up the
+ * server-side response under chunk B8a.
+ */
+export type SessionInference = {
+  readonly call: <TOutput extends ZodTypeAny = ZodTypeAny>(
+    input: InferenceCallInput<TOutput>,
+  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
+  readonly host: <TOutput extends ZodTypeAny = ZodTypeAny>(
+    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
+  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
+  readonly judge: <TOutput extends ZodTypeAny = ZodTypeAny>(
+    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
+  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
+  readonly classify: <TOutput extends ZodTypeAny = ZodTypeAny>(
+    input: Omit<InferenceCallInput<TOutput>, 'callKind'>,
+  ) => Promise<Result<InferenceCallSuccess<TOutput>, SdkError>>;
+};

package/src/lifecycle.ts

@@ -0,0 +1,72 @@
+/**
+ * Lifecycle hooks for the Studio SDK.
+ *
+ * Per chunk B7 build: "lifecycle.ts — hooks for session start, phase
+ * transitions, session end. Map to lifecycle frames from the
+ * server."
+ *
+ * Lifecycle frames carry a `transition` discriminant (e.g.
+ * `session.opened`, `phase.entered:<phaseId>`, `session.closed`) and
+ * a `detail` payload whose shape is per-transition. The SDK exposes
+ * a typed set of bindings here so a host shell can wire up the
+ * common transitions without reaching into the raw event bus.
+ *
+ * Unknown transitions still surface through `onAnyLifecycle`; the
+ * named helpers are convenience for the documented set.
+ */
+
+import type { LifecyclePayload } from '@wibly/internal-protocol';
+
+import type { EventBus, EventHandler } from './events.js';
+
+export type LifecycleBindings = {
+  /** `session.opened` — initial subscribe completed. */
+  readonly onSessionOpened: (
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+  /** `session.closed` — the Runtime declared the session terminated. */
+  readonly onSessionClosed: (
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+  /** `phase.entered:<id>` — a new phase began. */
+  readonly onPhaseEntered: (
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+  /** `phase.exited:<id>` — the active phase ended. */
+  readonly onPhaseExited: (
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+  /** `host.reclaimed` — the host slot was assigned to a new player. */
+  readonly onHostReclaimed: (
+    handler: EventHandler<LifecyclePayload>,
+  ) => () => void;
+};
+
+const PHASE_ENTERED_PREFIX = 'phase.entered';
+const PHASE_EXITED_PREFIX = 'phase.exited';
+
+export const createLifecycleBindings = (bus: EventBus): LifecycleBindings => ({
+  onSessionOpened: (handler) => bus.onLifecycle('session.opened', handler),
+  onSessionClosed: (handler) => bus.onLifecycle('session.closed', handler),
+  onPhaseEntered: (handler) => {
+    return bus.onAnyLifecycle((payload) => {
+      if (
+        payload.transition === PHASE_ENTERED_PREFIX ||
+        payload.transition.startsWith(`${PHASE_ENTERED_PREFIX}:`)
+      ) {
+        handler(payload);
+      }
+    });
+  },
+  onPhaseExited: (handler) => {
+    return bus.onAnyLifecycle((payload) => {
+      if (
+        payload.transition === PHASE_EXITED_PREFIX ||
+        payload.transition.startsWith(`${PHASE_EXITED_PREFIX}:`)
+      ) {
+        handler(payload);
+      }
+    });
+  },
+  onHostReclaimed: (handler) => bus.onLifecycle('host.reclaimed', handler),
+});