@runtypelabs/persona 4.17.1 → 4.18.0

package/src/internal/history-provider.ts

@@ -0,0 +1,150 @@
+/**
+ * History provider seam (`docs/visitor-history-implementation-plan.md` D9).
+ * Session/UI history code depends on this interface, never on
+ * `AgentWidgetClient`.
+ *
+ * The module stays under `internal/` but its contract is public: `index-core.ts`
+ * re-exports these declarations so integrators can implement
+ * `features.history.provider`. The provider REGISTRY beside it stays private.
+ */
+
+import type {
+  AgentWidgetMessage,
+  HistoryConversationPatch,
+  HistoryConversationSummary,
+  HistoryIdentityStatus,
+  HistoryScope,
+} from "../types";
+
+// Row/patch shapes are declared in `types.ts` (one declaration, two importers).
+export type { HistoryConversationPatch, HistoryConversationSummary };
+
+/** Fixed for the lifetime of one opened history view/action chain. */
+export interface HistoryOperationContext {
+  scope: HistoryScope;
+}
+
+/**
+ * An authorized-but-not-yet-applied conversation activation. The provider must
+ * not mutate the active chat until `commit()`.
+ */
+export interface PreparedHistoryActivation {
+  conversationId: string;
+  conversationRevision: string;
+  /** Apply the already-authorized provider-specific transport/session binding. */
+  commit(): void | Promise<void>;
+  /** Idempotently abandon a stale/superseded activation without changing chat. */
+  discard(): void;
+}
+
+export interface HistoryListOptions {
+  cursor?: string;
+  limit?: number;
+  targetId?: string;
+  context: HistoryOperationContext;
+}
+
+export interface HistoryListResult {
+  items: HistoryConversationSummary[];
+  nextCursor: string | null;
+}
+
+export interface HistoryPageOptions {
+  cursor?: string;
+  /** Lets the provider synthesize stable timestamps across page boundaries. */
+  beforeCreatedAt?: string;
+  context: HistoryOperationContext;
+}
+
+export interface HistoryPageResult {
+  summary: HistoryConversationSummary;
+  /** Already mapped; the visitor-visible projection lives in `content`. */
+  messages: AgentWidgetMessage[];
+  conversationRevision: string;
+  /** Follow for the next older page. `null` at the start of the transcript. */
+  nextCursor: string | null;
+}
+
+export interface HistoryDeleteAllOptions {
+  /** Absent means the whole authorized scope, never the UI default. */
+  targetId?: string;
+  context: HistoryOperationContext;
+}
+
+/** The contract a `features.history.provider` implementation satisfies. */
+export interface HistoryProvider {
+  readonly capabilities: {
+    scopes: readonly HistoryScope[];
+  };
+  getIdentityStatus(): HistoryIdentityStatus;
+  subscribeIdentityStatus(
+    callback: (status: HistoryIdentityStatus) => void
+  ): () => void;
+  list(opts: HistoryListOptions): Promise<HistoryListResult>;
+  getPage(id: string, opts: HistoryPageOptions): Promise<HistoryPageResult>;
+  prepareOpen(
+    id: string,
+    opts: { context: HistoryOperationContext }
+  ): Promise<PreparedHistoryActivation>;
+  prepareStartNew(opts: {
+    context: HistoryOperationContext;
+  }): Promise<PreparedHistoryActivation>;
+  delete(id: string, opts: { context: HistoryOperationContext }): Promise<void>;
+  deleteAll(opts: HistoryDeleteAllOptions): Promise<{ deleted: number }>;
+  /**
+   * Optional capability: visitor-scoped rename/star. Absence hides every
+   * update affordance (star glyphs, built-in title-menu actions). A user-set
+   * title pins: the provider must never let a later auto-generated title
+   * overwrite one set through this call.
+   */
+  update?(
+    id: string,
+    patch: HistoryConversationPatch,
+    opts: { context: HistoryOperationContext }
+  ): Promise<HistoryConversationSummary>;
+  /**
+   * Optional capability. Absence hides "forget this device". Resolves (never
+   * rejects) on remote failure; credentials are cleared in `finally` either way.
+   */
+  resetDevice?(): Promise<{ remoteRevocationConfirmed: boolean }>;
+  subscribeAvailability?(callback: (available: boolean) => void): () => void;
+}
+
+/**
+ * The one domain-error vocabulary for provider failures. HTTP strings and
+ * status codes never reach the view. Branch on `code`, never on message text.
+ */
+export type HistoryProviderErrorCode =
+  | "not_found"
+  | "rate_limited"
+  | "authentication_failed"
+  | "authentication_required"
+  | "identity_provider_failed"
+  | "proof_not_admitted"
+  | "unsupported_scope"
+  | "unavailable";
+
+export class HistoryProviderError extends Error {
+  public readonly code: HistoryProviderErrorCode;
+  /** Meaningful only for `rate_limited`. */
+  public readonly retryAfterSeconds?: number;
+
+  constructor(
+    code: HistoryProviderErrorCode,
+    message: string,
+    options?: { retryAfterSeconds?: number }
+  ) {
+    super(message);
+    this.name = "HistoryProviderError";
+    this.code = code;
+    if (options?.retryAfterSeconds !== undefined) {
+      this.retryAfterSeconds = options.retryAfterSeconds;
+    }
+  }
+}
+
+export function isHistoryProviderError(
+  value: unknown
+): value is HistoryProviderError {
+  return value instanceof HistoryProviderError;
+}

package/src/internal/runtype-history-provider.test.ts

@@ -0,0 +1,313 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { AgentWidgetClient, HistoryClientError } from '../client';
+import { createVisitorStore, type VisitorStore } from '../utils/visitor-store';
+import type { AgentWidgetConfig, ClientSession, WidgetHistoryInternals } from '../types';
+import { HistoryProviderError, type HistoryOperationContext } from './history-provider';
+import { createRuntypeHistoryProvider } from './runtype-history-provider';
+
+const CLIENT_TOKEN = 'ct_provider_test';
+const API_URL = 'https://api.runtype.com';
+const BROWSER: HistoryOperationContext = { scope: 'browser' };
+
+const futureIso = () => new Date(Date.now() + 5 * 60_000).toISOString();
+
+const respond = (
+  status: number,
+  body: unknown,
+  headers: Record<string, string> = { 'X-History-Identity-Status': 'not_provided' }
+) => {
+  const lowered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) lowered[key.toLowerCase()] = value;
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: { get: (name: string) => lowered[name.toLowerCase()] ?? null },
+    json: async () => body,
+  };
+};
+
+const initOk = () =>
+  respond(200, {
+    sessionId: 'sess_1',
+    expiresAt: futureIso(),
+    flow: { id: 'flow_1', name: 'Flow', description: null },
+    conversationId: 'conv_1',
+    targetId: 'flow_1',
+    conversationRevision: 'rev_1',
+    config: { welcomeMessage: null, placeholder: '', theme: null },
+  });
+
+describe('createRuntypeHistoryProvider', () => {
+  let store: VisitorStore;
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let committed: ClientSession[];
+
+  const build = async (config: Partial<AgentWidgetConfig> = {}) => {
+    const internals: WidgetHistoryInternals = { visitorStore: store };
+    const client = new AgentWidgetClient(
+      {
+        clientToken: CLIENT_TOKEN,
+        apiUrl: API_URL,
+        features: { history: { enabled: true } },
+        ...config,
+      },
+      internals
+    );
+    const provider = createRuntypeHistoryProvider({
+      client,
+      getIdentityProofConfigured: () => Boolean(config.getIdentityProof),
+      onActivationCommitted: (session) => {
+        committed.push(session);
+      },
+    });
+    return { client, provider };
+  };
+
+  beforeEach(async () => {
+    window.localStorage.clear();
+    committed = [];
+    store = createVisitorStore(CLIENT_TOKEN, 'persona-', false);
+    await store.set('cvt_test');
+    fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+  });
+
+  afterEach(() => {
+    store.destroy();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('advertises verified-user only when an identity proof callback exists', async () => {
+    const browserOnly = await build();
+    expect(browserOnly.provider.capabilities.scopes).toEqual(['browser']);
+
+    const verified = await build({ getIdentityProof: () => 'rt_eu_token' });
+    expect(verified.provider.capabilities.scopes).toEqual([
+      'browser',
+      'verified-user',
+    ]);
+  });
+
+  it('fails locally with unsupported_scope instead of issuing a request', async () => {
+    const { provider } = await build();
+    fetchMock.mockImplementation(initOk);
+
+    await expect(
+      provider.list({ context: { scope: 'verified-user' } })
+    ).rejects.toMatchObject({ code: 'unsupported_scope' });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('passes targetId through on list and delete-all', async () => {
+    const { provider } = await build();
+    fetchMock.mockImplementation((url: string, init?: RequestInit) => {
+      if (url.includes('/v1/client/init')) return initOk();
+      if (init?.method === 'DELETE') return respond(200, { deleted: 3 });
+      return respond(200, { data: [], nextCursor: null });
+    });
+
+    await provider.list({ targetId: 'flow_1', limit: 10, context: BROWSER });
+    await provider.deleteAll({ targetId: 'flow_1', context: BROWSER });
+
+    const urls = fetchMock.mock.calls.map((call) => String(call[0]));
+    expect(urls.some((url) => url.includes('targetId=flow_1') && url.includes('limit=10'))).toBe(
+      true
+    );
+    const deleteCall = fetchMock.mock.calls.find(
+      (call) => (call[1] as RequestInit | undefined)?.method === 'DELETE'
+    );
+    expect(String(deleteCall?.[0])).toContain('targetId=flow_1');
+  });
+
+  it('maps wire messages with the display projection winning and dedupes by id', async () => {
+    const { provider } = await build();
+    fetchMock.mockImplementation((url: string) => {
+      if (url.includes('/v1/client/init')) return initOk();
+      return respond(200, {
+        conversation: {
+          id: 'conv_1',
+          title: 'Saved',
+          targetId: 'flow_1',
+          preview: 'Saved preview',
+          messageCount: 3,
+          createdAt: '2026-01-01T00:00:00.000Z',
+          updatedAt: '2026-01-01T00:02:00.000Z',
+        },
+        messages: [
+          {
+            id: 'm1',
+            role: 'user',
+            content: '{"intent":"order_status"}',
+            displayContent: 'Where is my order?',
+            displayAvailable: true,
+            timestamp: '2026-01-01T00:00:00.000Z',
+          },
+          {
+            id: 'm1',
+            role: 'user',
+            content: 'duplicate row from a cursor overlap',
+            displayContent: 'Where is my order?',
+            displayAvailable: true,
+            timestamp: '2026-01-01T00:00:00.000Z',
+          },
+          {
+            id: 'm2',
+            role: 'assistant',
+            displayAvailable: false,
+            timestamp: '2026-01-01T00:01:00.000Z',
+          },
+        ],
+        nextMessageCursor: 'cursor_older',
+        conversationRevision: 'rev_9',
+      });
+    });
+
+    const page = await provider.getPage('conv_1', { context: BROWSER });
+
+    expect(page.messages).toHaveLength(2);
+    expect(page.messages[0].content).toBe('Where is my order?');
+    expect(page.messages[0].llmContent).toBeUndefined();
+    expect(page.messages[1].content).toBe('');
+    expect(page.conversationRevision).toBe('rev_9');
+    expect(page.nextCursor).toBe('cursor_older');
+    expect(page.summary.targetId).toBe('flow_1');
+  });
+
+  it('forwards beforeCreatedAt so a prepended page stays earlier than the transcript', async () => {
+    const { provider } = await build();
+    fetchMock.mockImplementation((url: string) => {
+      if (url.includes('/v1/client/init')) return initOk();
+      return respond(200, {
+        conversation: { id: 'conv_1', title: 'Saved', targetId: null, messageCount: 1 },
+        // No timestamps: the mapper must synthesize them under the boundary.
+        messages: [{ id: 'old1', role: 'user', content: 'older', displayAvailable: true }],
+        nextMessageCursor: null,
+        conversationRevision: 'rev_2',
+      });
+    });
+
+    const page = await provider.getPage('conv_1', {
+      cursor: 'c1',
+      beforeCreatedAt: '2026-01-01T00:00:00.000Z',
+      context: BROWSER,
+    });
+
+    expect(new Date(page.messages[0].createdAt).getTime()).toBeLessThan(
+      new Date('2026-01-01T00:00:00.000Z').getTime()
+    );
+  });
+
+  it('commits a prepared open through the session binding, and discard changes nothing', async () => {
+    const { client, provider } = await build();
+    fetchMock.mockImplementation(initOk);
+
+    const prepared = await provider.prepareOpen('conv_1', { context: BROWSER });
+    expect(prepared.conversationId).toBe('conv_1');
+    expect(prepared.conversationRevision).toBe('rev_1');
+    expect(client.getClientSession()).toBeNull();
+    expect(committed).toHaveLength(0);
+
+    await prepared.commit();
+    expect(client.getClientSession()?.sessionId).toBe('sess_1');
+    expect(committed).toHaveLength(1);
+
+    // Settled once: a late discard cannot unwind a winning commit.
+    prepared.discard();
+    expect(client.getClientSession()?.sessionId).toBe('sess_1');
+
+    const superseded = await provider.prepareStartNew({ context: BROWSER });
+    superseded.discard();
+    await superseded.commit();
+    expect(committed).toHaveLength(1);
+  });
+
+  it('maps client errors onto the domain vocabulary without leaking HTTP text', async () => {
+    const { provider } = await build();
+    const cases: Array<[number, unknown, string, Record<string, string>]> = [
+      [404, { error: 'not_found' }, 'not_found', {}],
+      [429, { error: 'rate_limited' }, 'rate_limited', { 'Retry-After': '10' }],
+      [503, { error: 'identity_proof_not_admitted' }, 'proof_not_admitted', {}],
+      [500, { error: 'boom: upstream 500 at /v1/client/conversations' }, 'unavailable', {}],
+    ];
+
+    for (const [status, body, expected, headers] of cases) {
+      fetchMock.mockReset();
+      fetchMock.mockImplementation((url: string) => {
+        if (url.includes('/v1/client/init')) return initOk();
+        return respond(status, body, {
+          'X-History-Identity-Status': 'not_provided',
+          ...headers,
+        });
+      });
+      const error = await provider
+        .list({ context: BROWSER })
+        .catch((caught: unknown) => caught);
+      expect(error).toBeInstanceOf(HistoryProviderError);
+      const domain = error as HistoryProviderError;
+      expect(domain.code).toBe(expected);
+      expect(domain.message).not.toMatch(/\d{3}/);
+      expect(domain.message.toLowerCase()).not.toContain('http');
+      expect(domain.message).not.toContain('/v1/');
+      if (expected === 'rate_limited') {
+        expect(domain.retryAfterSeconds).toBe(10);
+      }
+    }
+  });
+
+  it('resolves resetDevice with remoteRevocationConfirmed false instead of rejecting', async () => {
+    const { client, provider } = await build();
+    const clearSpy = vi.spyOn(store, 'clear');
+    fetchMock.mockImplementation((url: string) => {
+      if (url.includes('/v1/client/init')) return initOk();
+      return respond(500, { error: 'reset failed' });
+    });
+
+    await expect(provider.resetDevice?.()).resolves.toEqual({
+      remoteRevocationConfirmed: false,
+    });
+    // The client clears credentials in its own `finally` regardless.
+    expect(clearSpy).toHaveBeenCalled();
+    expect(client.getHistoryIdentityStatus().state).toBe('browser_only');
+  });
+
+  it('bridges identity status and availability subscriptions', async () => {
+    const { client, provider } = await build();
+    const statuses: string[] = [];
+    const availability: boolean[] = [];
+    const unsubscribe = provider.subscribeIdentityStatus((status) =>
+      statuses.push(status.state)
+    );
+    provider.subscribeAvailability?.((available) => availability.push(available));
+
+    fetchMock.mockImplementation((url: string) => {
+      if (url.includes('/v1/client/init')) {
+        return respond(403, { error: 'visitor_history_disabled' });
+      }
+      return respond(200, { data: [], nextCursor: null });
+    });
+
+    await provider.list({ context: BROWSER }).catch(() => undefined);
+    expect(availability).toEqual([false]);
+    expect(statuses).toContain('unavailable');
+    expect(provider.getIdentityStatus()).toEqual(
+      client.getHistoryIdentityStatus()
+    );
+
+    unsubscribe();
+  });
+
+  it('never lets a raw HistoryClientError escape the seam', async () => {
+    const { provider } = await build();
+    fetchMock.mockImplementation(() => respond(404, { error: 'not_found' }));
+
+    const error = await provider
+      .getPage('missing', { context: BROWSER })
+      .catch((caught: unknown) => caught);
+    expect(error).toBeInstanceOf(HistoryProviderError);
+    expect(error).not.toBeInstanceOf(HistoryClientError);
+  });
+});

package/src/internal/runtype-history-provider.ts

@@ -0,0 +1,240 @@
+/**
+ * Runtype `HistoryProvider`: the only production provider in v1. Wraps the
+ * Phase 1 `AgentWidgetClient` history methods behind the generic seam
+ * (`docs/visitor-history-implementation-plan.md` D9).
+ *
+ * Credential-shaped concerns (visitor store, proofs, 401 recovery, claim, 403
+ * degrade, remote reset) stay inside `AgentWidgetClient`; this file only
+ * adapts shapes and maps HTTP/client errors onto the one domain vocabulary.
+ * No HTTP string or status code escapes into the view.
+ *
+ * Not public and not in any tsup entry or package export.
+ */
+
+import { HistoryClientError, type AgentWidgetClient } from "../client";
+import type { ClientSession, HistoryScope } from "../types";
+import {
+  mapWireMessages,
+  mergeWireMessagesById,
+} from "../utils/history-messages";
+import {
+  HistoryProviderError,
+  type HistoryConversationSummary,
+  type HistoryDeleteAllOptions,
+  type HistoryListOptions,
+  type HistoryListResult,
+  type HistoryPageOptions,
+  type HistoryPageResult,
+  type HistoryProvider,
+  type HistoryProviderErrorCode,
+  type PreparedHistoryActivation,
+} from "./history-provider";
+
+export interface RuntypeHistoryProviderOptions {
+  client: AgentWidgetClient;
+  /** Advertise `verified-user` only when the host supplies a proof callback. */
+  getIdentityProofConfigured: () => boolean;
+  /**
+   * Session-owned activation binding. Runs inside a winning `commit()`, after
+   * the prepared client session is installed and before the caller continues.
+   */
+  onActivationCommitted: (session: ClientSession) => void | Promise<void>;
+  /** Live client rebuilds hand the provider its replacement. */
+  getClient?: () => AgentWidgetClient;
+}
+
+/** Client error code -> domain code. Anything unmapped is `unavailable`. */
+const ERROR_CODE_MAP = new Map<string, HistoryProviderErrorCode>([
+  ["not_found", "not_found"],
+  ["conversation_deleted", "not_found"],
+  ["rate_limited", "rate_limited"],
+  ["authentication_required", "authentication_required"],
+  ["invalid_identity_proof", "authentication_required"],
+  ["visitor_identity_mismatch", "authentication_required"],
+  ["visitor_required", "authentication_required"],
+  ["identity_provider_failed", "identity_provider_failed"],
+  ["proof_not_admitted", "proof_not_admitted"],
+  ["identity_contract_violation", "proof_not_admitted"],
+  ["unauthorized", "authentication_failed"],
+  ["visitor_token_missing", "authentication_failed"],
+  ["conversation_credential_missing", "authentication_failed"],
+]);
+
+/** Secret-free, HTTP-free messages: the view branches on `code` anyway. */
+const DOMAIN_MESSAGE = new Map<HistoryProviderErrorCode, string>([
+  ["not_found", "That conversation is no longer available."],
+  ["rate_limited", "Too many history requests."],
+  ["authentication_failed", "History access was not authorized."],
+  ["authentication_required", "Sign in again to view account history."],
+  ["identity_provider_failed", "The identity provider did not respond."],
+  [
+    "proof_not_admitted",
+    "Account history is not available for this configuration.",
+  ],
+  ["unsupported_scope", "This history scope is not supported."],
+  ["unavailable", "Conversation history is unavailable right now."],
+]);
+
+const domainMessage = (code: HistoryProviderErrorCode): string =>
+  DOMAIN_MESSAGE.get(code) ?? "Conversation history is unavailable right now.";
+
+export function toHistoryProviderError(error: unknown): HistoryProviderError {
+  if (error instanceof HistoryProviderError) return error;
+  if (error instanceof HistoryClientError) {
+    const code = ERROR_CODE_MAP.get(error.code) ?? "unavailable";
+    return new HistoryProviderError(code, domainMessage(code), {
+      ...(error.retryAfterSeconds !== undefined
+        ? { retryAfterSeconds: error.retryAfterSeconds }
+        : {}),
+    });
+  }
+  return new HistoryProviderError("unavailable", domainMessage("unavailable"));
+}
+
+export function createRuntypeHistoryProvider(
+  options: RuntypeHistoryProviderOptions
+): HistoryProvider {
+  const client = (): AgentWidgetClient =>
+    options.getClient?.() ?? options.client;
+
+  const scopes: readonly HistoryScope[] = options.getIdentityProofConfigured()
+    ? ["browser", "verified-user"]
+    : ["browser"];
+  const capabilities = { scopes };
+
+  const assertScope = (scope: HistoryScope): void => {
+    if (!scopes.includes(scope)) {
+      throw new HistoryProviderError(
+        "unsupported_scope",
+        domainMessage("unsupported_scope")
+      );
+    }
+  };
+
+  const run = async <T>(scope: HistoryScope, fn: () => Promise<T>): Promise<T> => {
+    assertScope(scope);
+    try {
+      return await fn();
+    } catch (error) {
+      throw toHistoryProviderError(error);
+    }
+  };
+
+  /** Commit installs the client session, then runs the session binding. */
+  const wrap = (
+    prepared: { session: ClientSession; commit(): void; discard(): void }
+  ): PreparedHistoryActivation => {
+    let settled = false;
+    return {
+      conversationId: prepared.session.conversationId ?? "",
+      conversationRevision: prepared.session.conversationRevision ?? "",
+      async commit() {
+        if (settled) return;
+        settled = true;
+        prepared.commit();
+        await options.onActivationCommitted(prepared.session);
+      },
+      discard() {
+        if (settled) return;
+        settled = true;
+        prepared.discard();
+      },
+    };
+  };
+
+  return {
+    capabilities,
+
+    getIdentityStatus() {
+      return client().getHistoryIdentityStatus();
+    },
+
+    subscribeIdentityStatus(callback) {
+      return client().subscribeHistoryIdentityStatus(callback);
+    },
+
+    subscribeAvailability(callback) {
+      return client().subscribeHistoryAvailability(callback);
+    },
+
+    async list(opts: HistoryListOptions): Promise<HistoryListResult> {
+      return run(opts.context.scope, async () => {
+        const page = await client().listConversations({
+          ...(opts.cursor ? { cursor: opts.cursor } : {}),
+          ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+          ...(opts.targetId ? { targetId: opts.targetId } : {}),
+          scope: opts.context.scope,
+        });
+        return {
+          items: page.data as HistoryConversationSummary[],
+          nextCursor: page.nextCursor,
+        };
+      });
+    },
+
+    /**
+     * Newest page first; `beforeCreatedAt` is the transcript boundary the
+     * mapper needs to synthesize missing timestamps for a prepended page.
+     */
+    async getPage(id: string, opts: HistoryPageOptions): Promise<HistoryPageResult> {
+      return run(opts.context.scope, async () => {
+        const detail = await client().getConversation(id, {
+          ...(opts.cursor ? { messageCursor: opts.cursor } : {}),
+          scope: opts.context.scope,
+        });
+        const mapped = mapWireMessages(detail.messages, {
+          ...(opts.beforeCreatedAt
+            ? { beforeCreatedAt: opts.beforeCreatedAt }
+            : {}),
+        });
+        return {
+          summary: detail.summary as HistoryConversationSummary,
+          // Cursor overlap can repeat rows: dedupe by id before returning.
+          messages: mergeWireMessagesById([], mapped),
+          conversationRevision: detail.conversationRevision ?? "",
+          nextCursor: detail.nextMessageCursor,
+        };
+      });
+    },
+
+    async prepareOpen(id, opts) {
+      return run(opts.context.scope, async () =>
+        wrap(await client().prepareConversationSession(id))
+      );
+    },
+
+    async prepareStartNew(opts) {
+      return run(opts.context.scope, async () =>
+        wrap(await client().prepareNewConversationSession())
+      );
+    },
+
+    async delete(id, opts) {
+      await run(opts.context.scope, () =>
+        client().deleteConversation(id, { scope: opts.context.scope })
+      );
+    },
+
+    async deleteAll(opts: HistoryDeleteAllOptions) {
+      return run(opts.context.scope, () =>
+        client().deleteAllConversations({
+          ...(opts.targetId !== undefined ? { targetId: opts.targetId } : {}),
+          scope: opts.context.scope,
+        })
+      );
+    },
+
+    /**
+     * Never rejects on remote failure: the client clears credentials in its own
+     * `finally`, so an unconfirmed revocation still detaches this browser.
+     */
+    async resetDevice() {
+      try {
+        await client().resetVisitor();
+        return { remoteRevocationConfirmed: true };
+      } catch {
+        return { remoteRevocationConfirmed: false };
+      }
+    },
+  };
+}