Migration from vendored SDK

There are two migration paths, depending on where your project is today:

Vendored src/lib/scenaro-sdk/ folder → published @scenaro/sdk package
Pre-0.3 API (useScenarioSession + AgentListener) → useScenaroSession

Both end at the same place: one provider, one hook, no transport wiring.

Before and after

Vendored	@scenaro/sdk 0.1–0.2	@scenaro/sdk 0.3
`ScenarioPlayer` monolith	`useScenarioSession` + `AgentListener` + `RoomContext`	`useScenaroSession` (all-in-one)
`generateToken()` one-shot	`identifyUser()` + `startSession()`	Handled by `start()`
`window.__` event bus	`useScenaroEvents()` scoped bus	`useScenaroEvents()` (unchanged)
Copied protocol files	`@scenaro/sdk/protocol`	`@scenaro/sdk/protocol` (unchanged)
8 divergent copies	One npm package	One npm package

Migration steps

Install the package

pnpm add @scenaro/sdk livekit-client @livekit/components-react

Replace API client

// Before (vendored)
import { scenariosAPI } from './lib/scenaro-sdk/api/scenarios';

// After
import { createScenaroClient } from '@scenaro/sdk/client';
export const scenaroClient = createScenaroClient({
  apiUrl: import.meta.env.VITE_SCENARO_API_URL,
  apiPathPrefix: '/v1',
});

Replace provider

// Before (vendored)
import { SdkSessionProvider } from './lib/scenaro-sdk/SdkSessionProvider';

// After
import { ScenaroProvider, FeatureProvider } from '@scenaro/sdk/react';

Replace the session hook

// Before (vendored)
import useScenarioSession from './lib/scenaro-sdk/hooks/useScenarioSession';

// Before (0.1–0.2 — removed in 0.3.0)
import { useScenarioSession, AgentListener } from '@scenaro/sdk/react';

// After (0.3)
import { useScenaroSession } from '@scenaro/sdk/react';

const { status, start, end } = useScenaroSession({ scenario: PUBLICATION_UUID });

Remove AgentListener and RoomContext wiring

useScenaroSession handles the data channel, config handshake, tool RPC, and RoomContext injection internally. Delete these from your components:

// Before (0.1) — all of this goes away
<RoomContext.Provider value={room}>
  {isConnected && <AgentListener />}
  {/* ... */}
</RoomContext.Provider>

Update auth calls

Remove any generateToken usage. The hook runs identify + session start automatically on start().

Update event listeners

// Before (vendored)
window.__.on('config', handler);

// After
const events = useScenaroEvents();
events.on('config', handler);

Remove vendored copies

Delete duplicated AgentListener, protocol/, and auth/ files. Keep only feature components and your registry.

Pre-0.3 API mapping (historical)

These exports were removed in 0.3.0. If you still import them, upgrade to 0.3.

Removed (`useScenarioSession`)	Replacement (`useScenaroSession`)
`connect({ language })`	`start()` — pass `language` as a hook option
`disconnect()`	`end()`
`isConnected` / `isConnecting`	`status` (`'connected'`, `'connecting'`, …)
`error` (string)	`error` (`ScenaroError` with `code`)
`<AgentListener />`	Built in — remove it
`RoomContext.Provider`	Built in — remove it
`useConversationMessages()`	`messages` from the hook
`room`	`room` (advanced only — see Transport extensions)
`runtimeConfig`	`rawConfig` from the hook

What to keep locally

Keep in your app	Provided by @scenaro/sdk
Feature components	`ScenaroProvider`
Feature registry / local FeatureManager	`useScenaroSession`
Brand CSS	Data channel + session tool RPC
Collection API clients	Protocol types
Product templates	Session storage

Storage migration

Since @scenaro/sdk@0.1.1, legacy storage keys are migrated automatically on read. No manual migration needed for users with existing sessions.

Verify

pnpm build
# Test: start() → status 'connected' → config received → tool call → end()

​Before and after

​Migration steps

​Pre-0.3 API mapping (historical)

​What to keep locally

​Storage migration

​Verify

​Need help?