@firststep-studio/sdk 0.17.0 → 0.18.0

package/dist/index.d.mts

@@ -285,743 +285,814 @@ declare function classifyWithUCP(endpoint: string, messages: ChatMessage[], opti
 }): Promise<ClassificationResult>;
 
 /**
- * Render Markers
- *
- * Utilities for building render markers that FirstStep Studio's frontend
- * can parse and display as rich UI components (cards, alerts, forms, etc.).
+ * Platform Client
  *
- * This module is the single source of truth for render marker specs.
- * - Handlers (producers) use the builder functions to emit markers
- * - Studio frontend (consumer) uses the types and MARKER_TYPES constants to parse them
+ * SDK client for handlers to call back to FirstStep Studio.
+ * Enables handlers to query platform data (chatbot list, etc.)
+ * using the same API token used for request signature verification.
  *
  * @example
  * ```typescript
- * import { renderMarkers } from '@firststep-studio/sdk';
+ * import { createPlatformClient } from '@firststep-studio/sdk';
  *
- * // In your handleStream():
- * yield {
- *   type: 'text',
- *   content: renderMarkers.helplineCard({
- *     helplines: [{ name: '988 Lifeline', phoneNumber: '988', categories: ['crisis'], status: 'open', statusLabel: 'Available' }],
- *   }),
- * };
+ * const client = createPlatformClient({
+ *   studioUrl: 'https://studio-api.example.com',
+ *   token: process.env.FIRSTSTEP_TOKEN,
+ * });
+ *
+ * const chatbots = await client.listChatbots();
+ * // [{ id: '...', name: 'Safety Navigator', configSlug: 'safety-nav' }, ...]
  * ```
  */
-declare const MARKER_TYPES: {
-    readonly HELPLINE_CARD: "RENDER_HELPLINE_CARD";
-    readonly EMERGENCY: "RENDER_EMERGENCY";
-    readonly RESOURCE_CARD: "RENDER_RESOURCE_CARD";
-    readonly PROVIDER_CARD: "RENDER_PROVIDER_CARD";
-    readonly SAFETY_PLAN: "RENDER_SAFETY_PLAN";
-    readonly REPORT_CARD: "RENDER_REPORT_CARD";
-};
-type MarkerType = typeof MARKER_TYPES[keyof typeof MARKER_TYPES];
-/**
- * Helpline card payload.
- * Renders a carousel of helpline cards with contact buttons (call, text, chat, WhatsApp).
- */
-interface HelplineCardPayload {
-    helplines: HelplineCardItem[];
-    type?: 'throughline' | 'throughline_fallback' | 'stage';
-    fallback?: {
-        message: string;
-        linkText?: string;
-        linkUrl?: string;
-        icon?: string;
-        topic?: string;
-        topics?: string[];
-    };
+interface PlatformClientConfig {
+    /** Studio backend API URL (e.g. https://studio-api.example.com) */
+    studioUrl: string;
+    /** API token (same as FIRSTSTEP_TOKEN used for signature verification) */
+    token: string;
+    /** Request timeout in ms (default: 10000) */
+    timeout?: number;
 }
-interface HelplineCardItem {
-    /**
-     * Stable helpline id from the throughline API. Lets consumers count
-     * distinct helplines across display/click events; name-keyed tracking
-     * cannot. Optional: older producers omit it.
-     */
-    id?: string;
+interface PlatformOrganization {
+    /** Studio organization ID */
+    id: string;
+    /** Display name (null if the organization record has been deleted) */
+    name: string | null;
+    /** URL-safe slug */
+    slug: string | null;
+}
+interface PlatformTokenInfo {
+    /** API token ID */
+    id: string;
+    /** Human-friendly token label */
+    name: string;
+    /** Authorized scopes */
+    scopes: string[];
+    /** Project IDs this token is scoped to (null = full org access) */
+    projectIds: string[] | null;
+}
+interface PlatformIdentity {
+    organization: PlatformOrganization;
+    token: PlatformTokenInfo;
+}
+interface PlatformChatbotRegisterInput {
+    /** Stable handler-side identifier used to upsert (e.g. handler config ID). */
+    externalId: string;
+    /** Display name shown in Studio's chatbot list. */
     name: string;
+    /** Optional human description. */
     description?: string;
-    categories: string[];
-    status: 'open' | 'closed';
-    statusLabel: string;
-    statusBadge?: string;
-    hoursText?: string;
-    supportTypes?: string;
-    smsNumber?: string;
-    phoneNumber?: string;
-    website?: string;
-    webchat?: string;
-    whatsapp?: string;
-    specialties?: string[];
-    highlightedTag?: string;
-    verified?: boolean;
+    /** Public URL where Studio should send protocol requests. */
+    handlerUrl: string;
+    /** Slug for multi-config routing on the handler side. */
+    configSlug?: string;
+    /** Optional capability flags advertised to Studio. */
+    capabilities?: {
+        streaming?: boolean;
+        formQuestions?: boolean;
+        knowledgeActions?: boolean;
+        integrations?: boolean;
+        [key: string]: unknown;
+    };
 }
-/**
- * Emergency number payload.
- * Renders a prominent alert card with a large call button.
- */
-interface EmergencyPayload {
-    number: string;
-    countryName?: string;
-    countryCode?: string;
+interface PlatformChatbotRegistration {
+    /** Studio chatbot MongoDB ID (immutable across re-registrations). */
+    id: string;
+    /** Echoes back the externalId used as upsert key. */
+    externalId: string;
+    /** Resolved name as stored in Studio. */
+    name: string;
+    protocolConfig: Record<string, unknown>;
 }
-/**
- * Resource card payload.
- * Renders a carousel of resource cards with video thumbnails, tags, and visit buttons.
- */
-interface ResourceCardPayload {
-    resources: ResourceCardItem[];
+interface PlatformChatbot {
+    /** Studio chatbot MongoDB ID */
+    id: string;
+    /** Chatbot display name */
+    name: string;
+    /** Handler URL (if external handler configured) */
+    handlerUrl?: string;
+    /** Config slug for multi-config routing */
+    configSlug?: string;
+    /** Handler type */
+    handlerType?: 'builtin' | 'external';
 }
-interface ResourceCardItem {
+interface PlatformKnowledgeSummary {
+    /** Studio knowledge MongoDB ID */
+    id: string;
+    /** Knowledge name */
     name: string;
-    url?: string;
+    /** Optional description */
     description?: string;
-    video_url?: string;
+    /** Knowledge type (e.g. 'text', 'database') */
     type?: string;
-    tags?: string[];
-    highlightedTag?: string;
+    /** Owning organization ID. Null for org-less system documents. */
+    organizationId: string | null;
+    /**
+     * True for handler-managed documents created through the protocol
+     * write API. System-owned knowledge is hidden from every Studio UI
+     * surface and only appears in `list` when `includeSystemOwned` is set.
+     */
+    isSystemOwned?: boolean;
+    /** Whether semantic search (record embedding) is enabled. */
+    ragEnabled?: boolean;
+    /** Timestamps */
+    createdAt?: number | string;
+    updatedAt?: number | string;
 }
 /**
- * Provider card payload.
- * Renders a carousel of provider directory cards with specialty/language tags and contact info.
+ * Full knowledge document (shape mirrors the underlying mongoose doc).
+ * Kept loose because the schema is large and varies by knowledge `type`;
+ * narrow types can be added incrementally as callers need them.
  */
-interface ProviderCardPayload {
-    providers: ProviderCardItem[];
+type PlatformKnowledge = PlatformKnowledgeSummary & Record<string, unknown>;
+interface ListKnowledgeOptions {
+    /**
+     * Target organization to list knowledge from. If omitted, defaults to
+     * the org associated with the SDK token. Use this to read from a
+     * different org (e.g. a platform-operated shared library marked
+     * `publicReadable` in Studio).
+     */
+    orgId?: string;
+    /**
+     * Include system-owned (handler-managed) knowledge in the listing.
+     * Only honored when listing the token's own org; other orgs never
+     * expose their system-owned documents.
+     */
+    includeSystemOwned?: boolean;
+    /**
+     * 'system' lists ORG-LESS platform documents instead of org
+     * knowledge. orgId and includeSystemOwned are ignored in that mode.
+     */
+    scope?: 'system';
 }
-interface ProviderCardItem {
+/** Sheet definition for `knowledge.create`. */
+interface CreateKnowledgeSheet {
+    /** Stable sheet id, referenced later by record writes and search. */
     id: string;
     name: string;
-    type?: string;
-    specialty: string[];
-    language: string[];
     description?: string;
-    location?: string;
-    open_hours?: string;
-    contact_phone?: string;
-    contact_email?: string;
-    address?: string;
-    website?: string;
+    /**
+     * Column definitions ({ id, name, type, ... }). Loose-typed; the
+     * Studio schema validates `type` against its column-type enum.
+     */
+    columns?: Array<Record<string, unknown>>;
 }
-/**
- * Safety plan payload.
- * Renders a multi-section table with expandable sections and save/export actions.
- */
-interface SafetyPlanPayload {
-    sections: SafetyPlanSection[];
-    helplines?: Array<{
-        name: string;
-        phone?: string;
-    }>;
-    actions?: {
-        savePng?: boolean;
-        saveTxt?: boolean;
-        copy?: boolean;
-    };
+interface CreateKnowledgeOptions {
+    description?: string;
+    /**
+     * Enable semantic search at creation time. Defaults to false; can be
+     * flipped later with `setRagEnabled` (which also backfills embeddings
+     * for records inserted while the flag was off).
+     */
+    ragEnabled?: boolean;
+    /**
+     * Create the knowledge as an ORG-LESS platform document: no
+     * organizationId at all, structurally invisible to every org-scoped
+     * Studio surface. This is the home for handler-managed data. Without
+     * it the document is created under the token's org (hidden from the
+     * UI by isSystemOwned, but org-bound).
+     */
+    system?: boolean;
 }
-interface SafetyPlanSection {
+/** A raw record as returned by the protocol record-write endpoints. */
+interface PlatformKnowledgeRecord {
     id: string;
-    title: string;
-    items: Array<string | {
-        name: string;
-        phone?: string;
-        description?: string;
-    }>;
-}
-/**
- * Report card payload.
- * Renders a summary card of collected report data with a submit button.
- */
-interface ReportCardPayload {
-    topic: string;
-    location?: string;
-    description?: string;
-    perpetrator_known?: boolean;
-    contact_mode?: string;
-    contact_value?: string;
-    submitEndpoint?: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    createdAt?: number | string;
+    updatedAt?: number | string;
 }
-/**
- * The marker families that constitute a *recommendation*: the handler put
- * something in front of the user and expects them to act on it. Safety plans
- * and report cards are excluded: they summarise what the user already said
- * rather than recommending anything, so rating their "satisfaction" would
- * measure a different thing and drag the average with it.
- */
-type RecommendationKind = 'helpline' | 'resource' | 'provider' | 'emergency';
-/**
- * One recommended thing, flattened out of a card carousel.
- *
- * A single marker usually carries several of these (a helpline carousel is
- * one marker, five helplines), and each one is separately good or bad for the
- * user in front of it, so the unit here is the item, not the card.
- */
-interface RecommendedItem {
-    kind: RecommendationKind;
-    /**
-     * Stable producer-side id when there is one. Lets a consumer tally the same
-     * helpline or provider across sessions; label-keyed tallies cannot, because
-     * two helplines can share a display name across countries.
-     */
-    id?: string;
-    /** The card's headline, as the user reads it. */
-    label: string;
+interface KnowledgeSearchOptions {
+    /** Max records to return (server-side clamped to 1..50, default 10). */
+    limit?: number;
     /**
-     * One line of gist for a consumer that never sees the rendered card: an
-     * evaluator, a log, a transcript export.
+     * Optional sheet filter. Pass a sheet id (from the knowledge document)
+     * to restrict the search to that sheet. Omit to search across all
+     * sheets in the knowledge.
      */
-    detail?: string;
+    sheetId?: string;
 }
 /**
- * Pull one marker's JSON payload out of a message.
- *
- * Tolerates whitespace and newlines between the tags and the payload, because
- * producers differ on that: the SDK builders emit no padding, the Studio
- * frontend's own helpline blocks emit `\n`.
- */
-declare function parseMarkerPayload<T = unknown>(content: string, type: string): T | null;
-/**
- * Normalise every recommendation marker in an assistant message into a flat
- * list of recommended items.
- *
- * This is the read side of the builders above, and it lives here for the same
- * reason they do: the marker spec should have one owner. Consumers that want
- * to know "what did this turn recommend" (evaluators, analytics, transcript
- * exporters) otherwise each grow their own regex, and they drift. One reads
- * `payload.title` off a resource card that has never had one.
- */
-declare function extractRecommendedItems(content: string): RecommendedItem[];
-/**
- * Render marker builder functions.
- *
- * Each function takes a typed payload and returns a render marker string
- * that can be yielded as a `text` chunk in handleStream().
- *
- * @example
- * ```typescript
- * // Emit helpline cards
- * yield { type: 'text', content: renderMarkers.helplineCard({ helplines: [...] }) };
- *
- * // Emit emergency number
- * yield { type: 'text', content: renderMarkers.emergency({ number: '911', countryName: 'United States' }) };
- * ```
+ * A single hit from `client.knowledge.search`. `score` is the Atlas
+ * vector similarity score (cosine in our setup, so higher is closer).
+ * `data` mirrors the underlying record fields (column id -> value).
  */
-declare const renderMarkers: {
-    /** Build a helpline card carousel marker */
-    helplineCard: (payload: HelplineCardPayload) => string;
-    /** Build an emergency number alert marker */
-    emergency: (payload: EmergencyPayload) => string;
-    /** Build a resource card carousel marker */
-    resourceCard: (payload: ResourceCardPayload) => string;
-    /** Build a provider card carousel marker */
-    providerCard: (payload: ProviderCardPayload) => string;
-    /** Build a safety plan artifact marker */
-    safetyPlan: (payload: SafetyPlanPayload) => string;
-    /** Build a report draft card marker */
-    reportCard: (payload: ReportCardPayload) => string;
-};
-
+interface PlatformKnowledgeSearchHit {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    score: number;
+    createdAt?: number | string;
+    updatedAt?: number | string;
+}
 /**
- * Stream Metadata Builders
- *
- * Utilities for building typed metadata stream chunks that FirstStep Studio's
- * proxy persists to MongoDB for Dashboard features (Form Insights, Session
- * History, Routing Logs, Agent Transitions).
- *
- * Each function returns a ready-to-yield ProtocolStreamChunk. No need to
- * construct the `{ type, content }` wrapper manually.
- *
- * @example
- * ```typescript
- * import { streamMetadata } from '@firststep-studio/sdk';
- *
- * // In your handleStream():
- *
- * // 1. Welcome path: declare your schema once
- * yield streamMetadata.declareSchema({
- *   agents: [{ id: 'intake', title: 'Intake', order: 0 }],
- *   questions: [{ id: 'name', agentId: 'intake', title: 'Name', type: 'text' }],
- * });
- *
- * // 2. After each turn: send collected field values
- * yield streamMetadata.formDataUpdate({ name: 'Alice', age: '28' });
- *
- * // 3. On stage change: signal an agent transition
- * yield streamMetadata.agentTransition({ id: 'support', title: 'Support' });
- *
- * // 4. On classification: send routing result
- * yield streamMetadata.routingResult({
- *   decision: 'classified',
- *   reason: 'User mentioned self-harm',
- *   category: 'crisis',
- *   level: 'high',
- *   score: 92,
- * });
- * ```
+ * Helplines query params — passed verbatim to Throughline. Loose-typed
+ * so the SDK stays compatible with new Throughline query keys without
+ * a release. Required by Throughline today: `country_code`. Common
+ * optional keys: `topic`, `contact_method`, `limit`.
  */
-
-declare const streamMetadata: {
-    /**
-     * Declare the form schema (agents + questions) for Dashboard Form Insights.
-     *
-     * Yield this once during session initialization (welcome message).
-     * The Studio proxy stores it in `chatbot.externalSchema` so that
-     * Dashboard Form Insights can display question-level analytics.
-     *
-     * @param schema - Agents and questions your handler uses
-     * @returns A metadata stream chunk ready to yield or queue.push
-     */
-    declareSchema(schema: SchemaDeclarationPayload): ProtocolStreamChunk;
+type ThroughlineHelplinesQuery = Record<string, string | number | boolean | undefined>;
+/** Query contract for Throughline GET /v2/helplines. */
+interface ThroughlineV2HelplinesQuery {
+    countryCode: string;
+    topic?: string;
+    specialty?: string;
+    contactMethod?: 'phone' | 'sms' | 'onlineChat' | 'whatsapp' | 'tty' | 'reportingForm';
+    limit?: number;
+    priorityOnly?: boolean;
+}
+interface ThroughlineV2Description {
+    language: string;
+    fullDescription: string;
+    shortDescription?: string | null;
+}
+interface ThroughlineV2Country {
+    name: string;
+    code: string;
+    emergencyNumber?: string;
+}
+interface ThroughlineV2OpeningSpan {
+    localDayOfWeek: 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';
+    open: string;
+    close: string;
+}
+interface ThroughlineV2ContactMethod {
+    type: 'phone' | 'sms' | 'onlineChat' | 'whatsapp' | 'tty' | 'reportingForm';
+    value: string;
+    accessibilityNotes?: string | null;
+    alwaysOpen: boolean;
+    /** null when the application's API tier does not expose opening hours. */
+    openingHours: ThroughlineV2OpeningSpan[] | null;
+}
+interface ThroughlineV2Helpline {
+    id: string;
+    name: string;
+    descriptions: ThroughlineV2Description[];
+    website?: string;
+    country: ThroughlineV2Country;
+    timezone: string;
+    primaryTopics: string[];
+    secondaryTopics: string[];
+    supportedLanguages: string[];
+    specialties: string[];
+    /** Omitted on API tiers that do not expose support types. */
+    supportTypes?: string[];
+    interpretationServiceProvided: boolean;
+    membershipOrganizations: string[];
+    contactMethods: ThroughlineV2ContactMethod[];
+}
+interface ThroughlineV2HelplinesResponse {
+    helplines: ThroughlineV2Helpline[];
+}
+declare class PlatformError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+declare class PlatformClient {
+    private studioUrl;
+    private token;
+    private timeout;
+    constructor(config: PlatformClientConfig);
+    private request;
     /**
-     * Send collected form field values for Dashboard persistence.
-     *
-     * Call this after each turn when new fields are captured.
-     * Values are incrementally merged into `ChatSession.formData`.
-     *
-     * @param fields - Key-value pairs of field IDs to their collected values
-     * @returns A metadata stream chunk ready to yield or queue.push
+     * Resolve the organization and token metadata for the configured token.
+     * Useful for connection state UI ("Connected to {orgName}") and audit.
      */
-    formDataUpdate(fields: Record<string, string | number>): ProtocolStreamChunk;
+    getMe(): Promise<PlatformIdentity>;
     /**
-     * Signal an agent/stage transition for routing logs.
-     *
-     * The Studio proxy records this in `ChatSession.routingLogs` so
-     * the Dashboard can show the conversation's agent flow.
-     *
-     * @param agent - The agent/stage being transitioned to
-     * @returns A metadata stream chunk ready to yield or queue.push
+     * List chatbots accessible to this handler's organization.
+     * Studio resolves the organization from the API token.
      */
-    agentTransition(agent: AgentTransitionPayload): ProtocolStreamChunk;
+    listChatbots(): Promise<PlatformChatbot[]>;
     /**
-     * Send a routing/classification result for routing logs.
-     *
-     * The Studio proxy records this in `ChatSession.routingLogs` as a
-     * classification event with category, level, and confidence score.
-     *
-     * @param result - Classification/routing decision details
-     * @returns A metadata stream chunk ready to yield or queue.push
+     * Register or update an external-handler chatbot under the token's
+     * organization. Idempotent: identified by `externalId`, so handlers
+     * can call this on every config save without creating duplicates.
      */
-    routingResult(result: RoutingClassificationPayload): ProtocolStreamChunk;
+    registerChatbot(input: PlatformChatbotRegisterInput): Promise<PlatformChatbotRegistration>;
     /**
-     * Request a handoff to another chatbot.
-     *
-     * The Studio proxy pushes a handoff stack entry and routes subsequent
-     * user messages to the target handler. If `options.consent` is set,
-     * Studio stores the request as a pending offer instead.
-     *
-     * @param payload - Handoff target, reason, context, and options
-     * @returns A metadata stream chunk ready to yield or queue.push
+     * Mark the chatbot identified by `externalId` as disconnected.
+     * The Studio record is preserved (history, analytics survive).
      */
-    handoffRequest(payload: HandoffRequestPayload): ProtocolStreamChunk;
+    unregisterChatbot(externalId: string): Promise<{
+        ok: boolean;
+        modified: number;
+    }>;
     /**
-     * Return from a handoff back to the parent handler.
+     * Knowledge / resource surface.
      *
-     * The Studio proxy pops the handoff stack and delivers the return
-     * result to the parent handler on the next user message.
+     * Reads are allowed when the SDK token's org matches the target org,
+     * OR when the target org has `publicReadable: true` on the Studio side.
      *
-     * @param payload - Summary and artifacts from the completed handoff
-     * @returns A metadata stream chunk ready to yield or queue.push
+     * Writes target system-owned (handler-managed) knowledge only: the
+     * protocol API stamps everything created here `isSystemOwned: true`,
+     * which keeps it out of every Studio UI surface — Studio acts as a
+     * plain storage + RAG layer for it. UI-managed knowledge cannot be
+     * modified through this surface.
      */
-    handoffReturn(payload: HandoffReturnPayload): ProtocolStreamChunk;
+    knowledge: {
+        /**
+         * List knowledge items for an organization.
+         * Defaults to the SDK token's own org if `orgId` is omitted.
+         */
+        list: (options?: ListKnowledgeOptions) => Promise<PlatformKnowledgeSummary[]>;
+        /**
+         * Fetch a single knowledge item by its Studio ID. The caller must
+         * have read access to the knowledge's owning org (same-org or
+         * publicReadable).
+         */
+        get: (id: string) => Promise<PlatformKnowledge>;
+        /**
+         * Semantic search over a knowledge's records. Studio embeds the
+         * query server-side (Gemini gemini-embedding-001) and runs Atlas
+         * Vector Search against the `vector_index` on `knowledge_records`.
+         *
+         * Same read access rules as `get` — same-org or publicReadable.
+         *
+         * Returns an empty array (not an error) when the Atlas index is
+         * absent or when nothing matches, so handler code can treat
+         * "no hits" and "RAG not configured yet" identically.
+         */
+        search: (id: string, query: string, options?: KnowledgeSearchOptions) => Promise<PlatformKnowledgeSearchHit[]>;
+        /**
+         * Turn semantic search on or off for a knowledge.
+         *
+         * Writes are strictly same-org — `publicReadable` does NOT confer
+         * write access. Flipping `false -> true` schedules a background
+         * backfill of existing records on the Studio side; this call
+         * returns as soon as the flag is persisted, not when the backfill
+         * finishes.
+         *
+         * Idempotent: setting the flag to its current value is a no-op
+         * (`backfillTriggered` will be `false`).
+         */
+        setRagEnabled: (id: string, enabled: boolean) => Promise<{
+            id: string;
+            ragEnabled: boolean;
+            backfillTriggered: boolean;
+        }>;
+        /**
+         * Create a system-owned database knowledge under the token's org.
+         *
+         * 409 (surfaced as an error) means a knowledge of the same name
+         * already exists in the org. Idempotent callers should recover by
+         * listing with `includeSystemOwned: true` and matching on name.
+         */
+        create: (name: string, sheets: CreateKnowledgeSheet[], options?: CreateKnowledgeOptions) => Promise<PlatformKnowledge>;
+        /**
+         * Delete a system-owned knowledge and all of its records.
+         * Refused (403) for UI-managed knowledge.
+         */
+        delete: (id: string) => Promise<{
+            deletedRecords: number;
+        }>;
+        /**
+         * List a sheet's records (newest first). Full-list surfaces (admin
+         * tables, exact name matching) where semantic search is the wrong
+         * tool. `limit` defaults to 500 (server max 2000).
+         */
+        listRecords: (id: string, sheetId: string, options?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            records: PlatformKnowledgeRecord[];
+            total: number;
+        }>;
+        /**
+         * Append one record to a sheet. Embeds async when ragEnabled.
+         */
+        addRecord: (id: string, sheetId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /**
+         * Replace a record's data payload. Re-embeds async when ragEnabled.
+         */
+        updateRecord: (id: string, recordId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /** Delete one record. */
+        deleteRecord: (id: string, recordId: string) => Promise<void>;
+        /**
+         * Bulk-insert records into one sheet (each array entry becomes one
+         * record's `data`). With `replace: true` the sheet's existing
+         * records are deleted first — the full-resync primitive backfills
+         * use. Server caps a single call at 5000 records.
+         */
+        bulkRecords: (id: string, sheetId: string, records: Array<Record<string, unknown>>, options?: {
+            replace?: boolean;
+        }) => Promise<{
+            insertedCount: number;
+            deletedCount: number;
+        }>;
+    };
     /**
-     * Offer a handoff with user consent required.
+     * Throughline (find-a-helpline) surface.
      *
-     * Studio stores this as a pending offer, sends an SSE event to the
-     * frontend, and waits for the user to accept or decline before
-     * executing the handoff.
+     * Handlers used to call api.throughlinecare.com directly, which meant
+     * each handler had to hold OAuth client credentials and re-implement
+     * token caching. Studio holds the per-org credentials on
+     * `Organization.throughline.{clientId,clientSecret}` and proxies the
+     * Throughline endpoints; the SDK token identifies the org server-side
+     * so callers never see the secret.
      *
-     * @param payload - Offer display info and the pending handoff request
-     * @returns A metadata stream chunk ready to yield or queue.push
+     * Responses are returned as parsed JSON. Studio does not reshape the
+     * Throughline body — these surfaces stay compatible with future
+     * Throughline API additions without a Studio or SDK release.
+     *
+     * Caching (24h on countries + topics, none on helplines) is server-
+     * side; the SDK is stateless.
      */
-    handoffOffer(payload: HandoffOfferPayload): ProtocolStreamChunk;
-};
+    throughline: {
+        /**
+         * GET /v1/countries — Throughline's country catalog (codes,
+         * names, emergency numbers). Cached 24h server-side.
+         */
+        getCountries: () => Promise<unknown>;
+        /**
+         * GET /v1/topics — Throughline's topic taxonomy used to filter
+         * helpline searches. Cached 24h server-side.
+         */
+        getTopics: () => Promise<unknown>;
+        /**
+         * GET /v1/helplines?country_code=...&topic=...&... — live search,
+         * not cached. The query object is forwarded verbatim to Throughline,
+         * so any new key Throughline adds will work without an SDK change.
+         * Required by Throughline today: `country_code`.
+         */
+        getHelplines: (query: ThroughlineHelplinesQuery) => Promise<unknown>;
+        /**
+         * GET /v2/helplines through Studio's platform-held credential.
+         * This is opt-in and does not replace the organization-configured v1
+         * integration exposed by getHelplines().
+         */
+        getHelplinesV2: (query: ThroughlineV2HelplinesQuery) => Promise<ThroughlineV2HelplinesResponse>;
+    };
+}
+/**
+ * Create a PlatformClient for calling back to FirstStep Studio.
+ */
+declare function createPlatformClient(config: PlatformClientConfig): PlatformClient;
 
 /**
- * Platform Client
+ * Render Markers
  *
- * SDK client for handlers to call back to FirstStep Studio.
- * Enables handlers to query platform data (chatbot list, etc.)
- * using the same API token used for request signature verification.
+ * Utilities for building render markers that FirstStep Studio's frontend
+ * can parse and display as rich UI components (cards, alerts, forms, etc.).
+ *
+ * This module is the single source of truth for render marker specs.
+ * - Handlers (producers) use the builder functions to emit markers
+ * - Studio frontend (consumer) uses the types and MARKER_TYPES constants to parse them
  *
  * @example
  * ```typescript
- * import { createPlatformClient } from '@firststep-studio/sdk';
- *
- * const client = createPlatformClient({
- *   studioUrl: 'https://studio-api.example.com',
- *   token: process.env.FIRSTSTEP_TOKEN,
- * });
+ * import { renderMarkers } from '@firststep-studio/sdk';
  *
- * const chatbots = await client.listChatbots();
- * // [{ id: '...', name: 'Safety Navigator', configSlug: 'safety-nav' }, ...]
+ * // In your handleStream():
+ * yield {
+ *   type: 'text',
+ *   content: renderMarkers.helplineCard({
+ *     helplines: [{ name: '988 Lifeline', phoneNumber: '988', categories: ['crisis'], status: 'open', statusLabel: 'Available' }],
+ *   }),
+ * };
  * ```
  */
-interface PlatformClientConfig {
-    /** Studio backend API URL (e.g. https://studio-api.example.com) */
-    studioUrl: string;
-    /** API token (same as FIRSTSTEP_TOKEN used for signature verification) */
-    token: string;
-    /** Request timeout in ms (default: 10000) */
-    timeout?: number;
-}
-interface PlatformOrganization {
-    /** Studio organization ID */
-    id: string;
-    /** Display name (null if the organization record has been deleted) */
-    name: string | null;
-    /** URL-safe slug */
-    slug: string | null;
-}
-interface PlatformTokenInfo {
-    /** API token ID */
-    id: string;
-    /** Human-friendly token label */
-    name: string;
-    /** Authorized scopes */
-    scopes: string[];
-    /** Project IDs this token is scoped to (null = full org access) */
-    projectIds: string[] | null;
-}
-interface PlatformIdentity {
-    organization: PlatformOrganization;
-    token: PlatformTokenInfo;
-}
-interface PlatformChatbotRegisterInput {
-    /** Stable handler-side identifier used to upsert (e.g. handler config ID). */
-    externalId: string;
-    /** Display name shown in Studio's chatbot list. */
-    name: string;
-    /** Optional human description. */
-    description?: string;
-    /** Public URL where Studio should send protocol requests. */
-    handlerUrl: string;
-    /** Slug for multi-config routing on the handler side. */
-    configSlug?: string;
-    /** Optional capability flags advertised to Studio. */
-    capabilities?: {
-        streaming?: boolean;
-        formQuestions?: boolean;
-        knowledgeActions?: boolean;
-        integrations?: boolean;
-        [key: string]: unknown;
+declare const MARKER_TYPES: {
+    readonly HELPLINE_CARD: "RENDER_HELPLINE_CARD";
+    readonly HELPLINE_CARD_V2: "RENDER_HELPLINE_CARD_V2";
+    readonly EMERGENCY: "RENDER_EMERGENCY";
+    readonly RESOURCE_CARD: "RENDER_RESOURCE_CARD";
+    readonly PROVIDER_CARD: "RENDER_PROVIDER_CARD";
+    readonly SAFETY_PLAN: "RENDER_SAFETY_PLAN";
+    readonly REPORT_CARD: "RENDER_REPORT_CARD";
+};
+type MarkerType = typeof MARKER_TYPES[keyof typeof MARKER_TYPES];
+/**
+ * Helpline card payload.
+ * Renders a carousel of helpline cards with contact buttons (call, text, chat, WhatsApp).
+ */
+interface HelplineCardPayload {
+    helplines: HelplineCardItem[];
+    type?: 'throughline' | 'throughline_fallback' | 'stage';
+    fallback?: {
+        message: string;
+        linkText?: string;
+        linkUrl?: string;
+        icon?: string;
+        topic?: string;
+        topics?: string[];
     };
 }
-interface PlatformChatbotRegistration {
-    /** Studio chatbot MongoDB ID (immutable across re-registrations). */
-    id: string;
-    /** Echoes back the externalId used as upsert key. */
-    externalId: string;
-    /** Resolved name as stored in Studio. */
+interface HelplineCardItem {
+    /**
+     * Stable helpline id from the throughline API. Lets consumers count
+     * distinct helplines across display/click events; name-keyed tracking
+     * cannot. Optional: older producers omit it.
+     */
+    id?: string;
     name: string;
-    protocolConfig: Record<string, unknown>;
+    description?: string;
+    categories: string[];
+    status: 'open' | 'closed';
+    statusLabel: string;
+    statusBadge?: string;
+    hoursText?: string;
+    supportTypes?: string;
+    smsNumber?: string;
+    phoneNumber?: string;
+    website?: string;
+    webchat?: string;
+    whatsapp?: string;
+    specialties?: string[];
+    highlightedTag?: string;
+    verified?: boolean;
 }
-interface PlatformChatbot {
-    /** Studio chatbot MongoDB ID */
-    id: string;
-    /** Chatbot display name */
-    name: string;
-    /** Handler URL (if external handler configured) */
-    handlerUrl?: string;
-    /** Config slug for multi-config routing */
-    configSlug?: string;
-    /** Handler type */
-    handlerType?: 'builtin' | 'external';
+
+/** Raw Throughline v2 card contract plus handler presentation metadata. */
+interface HelplineCardV2Payload {
+    helplines: HelplineCardV2Item[];
+    type?: 'throughline' | 'stage';
 }
-interface PlatformKnowledgeSummary {
-    /** Studio knowledge MongoDB ID */
-    id: string;
-    /** Knowledge name */
+interface HelplineCardV2Item extends ThroughlineV2Helpline {
+    isTopMatch?: boolean;
+    matchReason?: string | null;
+}
+/**
+ * Emergency number payload.
+ * Renders a prominent alert card with a large call button.
+ */
+interface EmergencyPayload {
+    number: string;
+    countryName?: string;
+    countryCode?: string;
+}
+/**
+ * Resource card payload.
+ * Renders a carousel of resource cards with video thumbnails, tags, and visit buttons.
+ */
+interface ResourceCardPayload {
+    resources: ResourceCardItem[];
+}
+interface ResourceCardItem {
     name: string;
-    /** Optional description */
+    url?: string;
     description?: string;
-    /** Knowledge type (e.g. 'text', 'database') */
+    video_url?: string;
     type?: string;
-    /** Owning organization ID. Null for org-less system documents. */
-    organizationId: string | null;
-    /**
-     * True for handler-managed documents created through the protocol
-     * write API. System-owned knowledge is hidden from every Studio UI
-     * surface and only appears in `list` when `includeSystemOwned` is set.
-     */
-    isSystemOwned?: boolean;
-    /** Whether semantic search (record embedding) is enabled. */
-    ragEnabled?: boolean;
-    /** Timestamps */
-    createdAt?: number | string;
-    updatedAt?: number | string;
+    tags?: string[];
+    highlightedTag?: string;
 }
 /**
- * Full knowledge document (shape mirrors the underlying mongoose doc).
- * Kept loose because the schema is large and varies by knowledge `type`;
- * narrow types can be added incrementally as callers need them.
+ * Provider card payload.
+ * Renders a carousel of provider directory cards with specialty/language tags and contact info.
  */
-type PlatformKnowledge = PlatformKnowledgeSummary & Record<string, unknown>;
-interface ListKnowledgeOptions {
-    /**
-     * Target organization to list knowledge from. If omitted, defaults to
-     * the org associated with the SDK token. Use this to read from a
-     * different org (e.g. a platform-operated shared library marked
-     * `publicReadable` in Studio).
-     */
-    orgId?: string;
-    /**
-     * Include system-owned (handler-managed) knowledge in the listing.
-     * Only honored when listing the token's own org; other orgs never
-     * expose their system-owned documents.
-     */
-    includeSystemOwned?: boolean;
-    /**
-     * 'system' lists ORG-LESS platform documents instead of org
-     * knowledge. orgId and includeSystemOwned are ignored in that mode.
-     */
-    scope?: 'system';
+interface ProviderCardPayload {
+    providers: ProviderCardItem[];
 }
-/** Sheet definition for `knowledge.create`. */
-interface CreateKnowledgeSheet {
-    /** Stable sheet id, referenced later by record writes and search. */
+interface ProviderCardItem {
     id: string;
     name: string;
+    type?: string;
+    specialty: string[];
+    language: string[];
     description?: string;
-    /**
-     * Column definitions ({ id, name, type, ... }). Loose-typed; the
-     * Studio schema validates `type` against its column-type enum.
-     */
-    columns?: Array<Record<string, unknown>>;
+    location?: string;
+    open_hours?: string;
+    contact_phone?: string;
+    contact_email?: string;
+    address?: string;
+    website?: string;
 }
-interface CreateKnowledgeOptions {
-    description?: string;
-    /**
-     * Enable semantic search at creation time. Defaults to false; can be
-     * flipped later with `setRagEnabled` (which also backfills embeddings
-     * for records inserted while the flag was off).
-     */
-    ragEnabled?: boolean;
-    /**
-     * Create the knowledge as an ORG-LESS platform document: no
-     * organizationId at all, structurally invisible to every org-scoped
-     * Studio surface. This is the home for handler-managed data. Without
-     * it the document is created under the token's org (hidden from the
-     * UI by isSystemOwned, but org-bound).
-     */
-    system?: boolean;
+/**
+ * Safety plan payload.
+ * Renders a multi-section table with expandable sections and save/export actions.
+ */
+interface SafetyPlanPayload {
+    sections: SafetyPlanSection[];
+    helplines?: Array<{
+        name: string;
+        phone?: string;
+    }>;
+    actions?: {
+        savePng?: boolean;
+        saveTxt?: boolean;
+        copy?: boolean;
+    };
 }
-/** A raw record as returned by the protocol record-write endpoints. */
-interface PlatformKnowledgeRecord {
+interface SafetyPlanSection {
     id: string;
-    knowledgeId: string;
-    sheetId: string;
-    data: Record<string, unknown>;
-    createdAt?: number | string;
-    updatedAt?: number | string;
+    title: string;
+    items: Array<string | {
+        name: string;
+        phone?: string;
+        description?: string;
+    }>;
 }
-interface KnowledgeSearchOptions {
-    /** Max records to return (server-side clamped to 1..50, default 10). */
-    limit?: number;
+/**
+ * Report card payload.
+ * Renders a summary card of collected report data with a submit button.
+ */
+interface ReportCardPayload {
+    topic: string;
+    location?: string;
+    description?: string;
+    perpetrator_known?: boolean;
+    contact_mode?: string;
+    contact_value?: string;
+    submitEndpoint?: string;
+}
+/**
+ * The marker families that constitute a *recommendation*: the handler put
+ * something in front of the user and expects them to act on it. Safety plans
+ * and report cards are excluded: they summarise what the user already said
+ * rather than recommending anything, so rating their "satisfaction" would
+ * measure a different thing and drag the average with it.
+ */
+type RecommendationKind = 'helpline' | 'resource' | 'provider' | 'emergency';
+/**
+ * One recommended thing, flattened out of a card carousel.
+ *
+ * A single marker usually carries several of these (a helpline carousel is
+ * one marker, five helplines), and each one is separately good or bad for the
+ * user in front of it, so the unit here is the item, not the card.
+ */
+interface RecommendedItem {
+    kind: RecommendationKind;
     /**
-     * Optional sheet filter. Pass a sheet id (from the knowledge document)
-     * to restrict the search to that sheet. Omit to search across all
-     * sheets in the knowledge.
+     * Stable producer-side id when there is one. Lets a consumer tally the same
+     * helpline or provider across sessions; label-keyed tallies cannot, because
+     * two helplines can share a display name across countries.
      */
-    sheetId?: string;
+    id?: string;
+    /** The card's headline, as the user reads it. */
+    label: string;
+    /**
+     * One line of gist for a consumer that never sees the rendered card: an
+     * evaluator, a log, a transcript export.
+     */
+    detail?: string;
 }
 /**
- * A single hit from `client.knowledge.search`. `score` is the Atlas
- * vector similarity score (cosine in our setup, so higher is closer).
- * `data` mirrors the underlying record fields (column id -> value).
+ * Pull one marker's JSON payload out of a message.
+ *
+ * Tolerates whitespace and newlines between the tags and the payload, because
+ * producers differ on that: the SDK builders emit no padding, the Studio
+ * frontend's own helpline blocks emit `\n`.
  */
-interface PlatformKnowledgeSearchHit {
-    id: string;
-    knowledgeId: string;
-    sheetId: string;
-    data: Record<string, unknown>;
-    score: number;
-    createdAt?: number | string;
-    updatedAt?: number | string;
-}
+declare function parseMarkerPayload<T = unknown>(content: string, type: string): T | null;
 /**
- * Helplines query params — passed verbatim to Throughline. Loose-typed
- * so the SDK stays compatible with new Throughline query keys without
- * a release. Required by Throughline today: `country_code`. Common
- * optional keys: `topic`, `contact_method`, `limit`.
+ * Normalise every recommendation marker in an assistant message into a flat
+ * list of recommended items.
+ *
+ * This is the read side of the builders above, and it lives here for the same
+ * reason they do: the marker spec should have one owner. Consumers that want
+ * to know "what did this turn recommend" (evaluators, analytics, transcript
+ * exporters) otherwise each grow their own regex, and they drift. One reads
+ * `payload.title` off a resource card that has never had one.
+ */
+declare function extractRecommendedItems(content: string): RecommendedItem[];
+/**
+ * Render marker builder functions.
+ *
+ * Each function takes a typed payload and returns a render marker string
+ * that can be yielded as a `text` chunk in handleStream().
+ *
+ * @example
+ * ```typescript
+ * // Emit helpline cards
+ * yield { type: 'text', content: renderMarkers.helplineCard({ helplines: [...] }) };
+ *
+ * // Emit emergency number
+ * yield { type: 'text', content: renderMarkers.emergency({ number: '911', countryName: 'United States' }) };
+ * ```
+ */
+declare const renderMarkers: {
+    /** Build a helpline card carousel marker */
+    helplineCard: (payload: HelplineCardPayload) => string;
+    /** Build a Throughline v2 helpline card carousel marker. */
+    helplineCardV2: (payload: HelplineCardV2Payload) => string;
+    /** Build an emergency number alert marker */
+    emergency: (payload: EmergencyPayload) => string;
+    /** Build a resource card carousel marker */
+    resourceCard: (payload: ResourceCardPayload) => string;
+    /** Build a provider card carousel marker */
+    providerCard: (payload: ProviderCardPayload) => string;
+    /** Build a safety plan artifact marker */
+    safetyPlan: (payload: SafetyPlanPayload) => string;
+    /** Build a report draft card marker */
+    reportCard: (payload: ReportCardPayload) => string;
+};
+
+/**
+ * Stream Metadata Builders
+ *
+ * Utilities for building typed metadata stream chunks that FirstStep Studio's
+ * proxy persists to MongoDB for Dashboard features (Form Insights, Session
+ * History, Routing Logs, Agent Transitions).
+ *
+ * Each function returns a ready-to-yield ProtocolStreamChunk. No need to
+ * construct the `{ type, content }` wrapper manually.
+ *
+ * @example
+ * ```typescript
+ * import { streamMetadata } from '@firststep-studio/sdk';
+ *
+ * // In your handleStream():
+ *
+ * // 1. Welcome path: declare your schema once
+ * yield streamMetadata.declareSchema({
+ *   agents: [{ id: 'intake', title: 'Intake', order: 0 }],
+ *   questions: [{ id: 'name', agentId: 'intake', title: 'Name', type: 'text' }],
+ * });
+ *
+ * // 2. After each turn: send collected field values
+ * yield streamMetadata.formDataUpdate({ name: 'Alice', age: '28' });
+ *
+ * // 3. On stage change: signal an agent transition
+ * yield streamMetadata.agentTransition({ id: 'support', title: 'Support' });
+ *
+ * // 4. On classification: send routing result
+ * yield streamMetadata.routingResult({
+ *   decision: 'classified',
+ *   reason: 'User mentioned self-harm',
+ *   category: 'crisis',
+ *   level: 'high',
+ *   score: 92,
+ * });
+ * ```
  */
-type ThroughlineHelplinesQuery = Record<string, string | number | boolean | undefined>;
-declare class PlatformError extends Error {
-    status: number;
-    constructor(message: string, status: number);
-}
-declare class PlatformClient {
-    private studioUrl;
-    private token;
-    private timeout;
-    constructor(config: PlatformClientConfig);
-    private request;
+
+declare const streamMetadata: {
     /**
-     * Resolve the organization and token metadata for the configured token.
-     * Useful for connection state UI ("Connected to {orgName}") and audit.
+     * Declare the form schema (agents + questions) for Dashboard Form Insights.
+     *
+     * Yield this once during session initialization (welcome message).
+     * The Studio proxy stores it in `chatbot.externalSchema` so that
+     * Dashboard Form Insights can display question-level analytics.
+     *
+     * @param schema - Agents and questions your handler uses
+     * @returns A metadata stream chunk ready to yield or queue.push
      */
-    getMe(): Promise<PlatformIdentity>;
+    declareSchema(schema: SchemaDeclarationPayload): ProtocolStreamChunk;
     /**
-     * List chatbots accessible to this handler's organization.
-     * Studio resolves the organization from the API token.
+     * Send collected form field values for Dashboard persistence.
+     *
+     * Call this after each turn when new fields are captured.
+     * Values are incrementally merged into `ChatSession.formData`.
+     *
+     * @param fields - Key-value pairs of field IDs to their collected values
+     * @returns A metadata stream chunk ready to yield or queue.push
      */
-    listChatbots(): Promise<PlatformChatbot[]>;
+    formDataUpdate(fields: Record<string, string | number>): ProtocolStreamChunk;
     /**
-     * Register or update an external-handler chatbot under the token's
-     * organization. Idempotent: identified by `externalId`, so handlers
-     * can call this on every config save without creating duplicates.
+     * Signal an agent/stage transition for routing logs.
+     *
+     * The Studio proxy records this in `ChatSession.routingLogs` so
+     * the Dashboard can show the conversation's agent flow.
+     *
+     * @param agent - The agent/stage being transitioned to
+     * @returns A metadata stream chunk ready to yield or queue.push
      */
-    registerChatbot(input: PlatformChatbotRegisterInput): Promise<PlatformChatbotRegistration>;
+    agentTransition(agent: AgentTransitionPayload): ProtocolStreamChunk;
     /**
-     * Mark the chatbot identified by `externalId` as disconnected.
-     * The Studio record is preserved (history, analytics survive).
+     * Send a routing/classification result for routing logs.
+     *
+     * The Studio proxy records this in `ChatSession.routingLogs` as a
+     * classification event with category, level, and confidence score.
+     *
+     * @param result - Classification/routing decision details
+     * @returns A metadata stream chunk ready to yield or queue.push
      */
-    unregisterChatbot(externalId: string): Promise<{
-        ok: boolean;
-        modified: number;
-    }>;
+    routingResult(result: RoutingClassificationPayload): ProtocolStreamChunk;
     /**
-     * Knowledge / resource surface.
+     * Request a handoff to another chatbot.
      *
-     * Reads are allowed when the SDK token's org matches the target org,
-     * OR when the target org has `publicReadable: true` on the Studio side.
+     * The Studio proxy pushes a handoff stack entry and routes subsequent
+     * user messages to the target handler. If `options.consent` is set,
+     * Studio stores the request as a pending offer instead.
      *
-     * Writes target system-owned (handler-managed) knowledge only: the
-     * protocol API stamps everything created here `isSystemOwned: true`,
-     * which keeps it out of every Studio UI surface — Studio acts as a
-     * plain storage + RAG layer for it. UI-managed knowledge cannot be
-     * modified through this surface.
+     * @param payload - Handoff target, reason, context, and options
+     * @returns A metadata stream chunk ready to yield or queue.push
      */
-    knowledge: {
-        /**
-         * List knowledge items for an organization.
-         * Defaults to the SDK token's own org if `orgId` is omitted.
-         */
-        list: (options?: ListKnowledgeOptions) => Promise<PlatformKnowledgeSummary[]>;
-        /**
-         * Fetch a single knowledge item by its Studio ID. The caller must
-         * have read access to the knowledge's owning org (same-org or
-         * publicReadable).
-         */
-        get: (id: string) => Promise<PlatformKnowledge>;
-        /**
-         * Semantic search over a knowledge's records. Studio embeds the
-         * query server-side (Gemini gemini-embedding-001) and runs Atlas
-         * Vector Search against the `vector_index` on `knowledge_records`.
-         *
-         * Same read access rules as `get` — same-org or publicReadable.
-         *
-         * Returns an empty array (not an error) when the Atlas index is
-         * absent or when nothing matches, so handler code can treat
-         * "no hits" and "RAG not configured yet" identically.
-         */
-        search: (id: string, query: string, options?: KnowledgeSearchOptions) => Promise<PlatformKnowledgeSearchHit[]>;
-        /**
-         * Turn semantic search on or off for a knowledge.
-         *
-         * Writes are strictly same-org — `publicReadable` does NOT confer
-         * write access. Flipping `false -> true` schedules a background
-         * backfill of existing records on the Studio side; this call
-         * returns as soon as the flag is persisted, not when the backfill
-         * finishes.
-         *
-         * Idempotent: setting the flag to its current value is a no-op
-         * (`backfillTriggered` will be `false`).
-         */
-        setRagEnabled: (id: string, enabled: boolean) => Promise<{
-            id: string;
-            ragEnabled: boolean;
-            backfillTriggered: boolean;
-        }>;
-        /**
-         * Create a system-owned database knowledge under the token's org.
-         *
-         * 409 (surfaced as an error) means a knowledge of the same name
-         * already exists in the org. Idempotent callers should recover by
-         * listing with `includeSystemOwned: true` and matching on name.
-         */
-        create: (name: string, sheets: CreateKnowledgeSheet[], options?: CreateKnowledgeOptions) => Promise<PlatformKnowledge>;
-        /**
-         * Delete a system-owned knowledge and all of its records.
-         * Refused (403) for UI-managed knowledge.
-         */
-        delete: (id: string) => Promise<{
-            deletedRecords: number;
-        }>;
-        /**
-         * List a sheet's records (newest first). Full-list surfaces (admin
-         * tables, exact name matching) where semantic search is the wrong
-         * tool. `limit` defaults to 500 (server max 2000).
-         */
-        listRecords: (id: string, sheetId: string, options?: {
-            limit?: number;
-            offset?: number;
-        }) => Promise<{
-            records: PlatformKnowledgeRecord[];
-            total: number;
-        }>;
-        /**
-         * Append one record to a sheet. Embeds async when ragEnabled.
-         */
-        addRecord: (id: string, sheetId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
-        /**
-         * Replace a record's data payload. Re-embeds async when ragEnabled.
-         */
-        updateRecord: (id: string, recordId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
-        /** Delete one record. */
-        deleteRecord: (id: string, recordId: string) => Promise<void>;
-        /**
-         * Bulk-insert records into one sheet (each array entry becomes one
-         * record's `data`). With `replace: true` the sheet's existing
-         * records are deleted first — the full-resync primitive backfills
-         * use. Server caps a single call at 5000 records.
-         */
-        bulkRecords: (id: string, sheetId: string, records: Array<Record<string, unknown>>, options?: {
-            replace?: boolean;
-        }) => Promise<{
-            insertedCount: number;
-            deletedCount: number;
-        }>;
-    };
+    handoffRequest(payload: HandoffRequestPayload): ProtocolStreamChunk;
     /**
-     * Throughline (find-a-helpline) surface.
+     * Return from a handoff back to the parent handler.
      *
-     * Handlers used to call api.throughlinecare.com directly, which meant
-     * each handler had to hold OAuth client credentials and re-implement
-     * token caching. Studio holds the per-org credentials on
-     * `Organization.throughline.{clientId,clientSecret}` and proxies the
-     * Throughline endpoints; the SDK token identifies the org server-side
-     * so callers never see the secret.
+     * The Studio proxy pops the handoff stack and delivers the return
+     * result to the parent handler on the next user message.
      *
-     * Responses are returned as parsed JSON. Studio does not reshape the
-     * Throughline body — these surfaces stay compatible with future
-     * Throughline API additions without a Studio or SDK release.
+     * @param payload - Summary and artifacts from the completed handoff
+     * @returns A metadata stream chunk ready to yield or queue.push
+     */
+    handoffReturn(payload: HandoffReturnPayload): ProtocolStreamChunk;
+    /**
+     * Offer a handoff with user consent required.
      *
-     * Caching (24h on countries + topics, none on helplines) is server-
-     * side; the SDK is stateless.
+     * Studio stores this as a pending offer, sends an SSE event to the
+     * frontend, and waits for the user to accept or decline before
+     * executing the handoff.
+     *
+     * @param payload - Offer display info and the pending handoff request
+     * @returns A metadata stream chunk ready to yield or queue.push
      */
-    throughline: {
-        /**
-         * GET /v1/countries — Throughline's country catalog (codes,
-         * names, emergency numbers). Cached 24h server-side.
-         */
-        getCountries: () => Promise<unknown>;
-        /**
-         * GET /v1/topics — Throughline's topic taxonomy used to filter
-         * helpline searches. Cached 24h server-side.
-         */
-        getTopics: () => Promise<unknown>;
-        /**
-         * GET /v1/helplines?country_code=...&topic=...&... — live search,
-         * not cached. The query object is forwarded verbatim to Throughline,
-         * so any new key Throughline adds will work without an SDK change.
-         * Required by Throughline today: `country_code`.
-         */
-        getHelplines: (query: ThroughlineHelplinesQuery) => Promise<unknown>;
-    };
-}
-/**
- * Create a PlatformClient for calling back to FirstStep Studio.
- */
-declare function createPlatformClient(config: PlatformClientConfig): PlatformClient;
+    handoffOffer(payload: HandoffOfferPayload): ProtocolStreamChunk;
+};
 
 /**
  * Verify an HMAC-SHA256 request signature.
@@ -1290,4 +1361,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type RecommendationKind, type RecommendedItem, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, extractRecommendedItems, isValidToken, parseMarkerPayload, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type HelplineCardV2Item, type HelplineCardV2Payload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type RecommendationKind, type RecommendedItem, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type ThroughlineV2ContactMethod, type ThroughlineV2Country, type ThroughlineV2Description, type ThroughlineV2Helpline, type ThroughlineV2HelplinesQuery, type ThroughlineV2HelplinesResponse, type ThroughlineV2OpeningSpan, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, extractRecommendedItems, isValidToken, parseMarkerPayload, renderMarkers, streamMetadata, verifyRequestSignature };