@firststep-studio/sdk 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DCrYoOfK.js';
-export { M as AnalyticsContext, z as ChatbotInfo, B as ClassifierConfig, D as DeploymentInfo, F as FormData, T as FormFieldDefinition, U as FormFieldType, E as FormFieldValue, Q as FormSchema, n as HandlerInfo, Y as HandoffContext, f as HandoffInboundContext, Z as HandoffOptions, v as Helpline, u as HelplineResult, t as HelplineSearchOptions, I as IntegrationContext, s as IntegrationResult, N as InteractionEvent, O as InteractionEventType, K as KnowledgeContext, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, V as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, y as RoutingDecision, G as RoutingLog, W as SchemaAgent, X as SchemaQuestion, p as SessionContext, J as SessionMetadata, q as SessionState, e as SessionStatus, w as StorageContext, x as StorageSetOptions } from './types-DCrYoOfK.js';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-GoTI_c14.js';
+export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-GoTI_c14.js';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -66,6 +66,12 @@ interface UCPErrorResponse {
 }
 /**
  * UCP Classifier Info Response
+ *
+ * Returned by `GET /classifiers/:id/info`. Carries enough metadata for a
+ * caller to evaluate routing conditions (level severity comparisons,
+ * category lookups) without having to read the classifier definition out
+ * of the underlying datastore. Platform-internal handlers should treat
+ * this endpoint as the canonical source of classifier shape.
  */
 interface UCPInfoResponse {
     /** Classifier name */
@@ -92,6 +98,49 @@ interface UCPInfoResponse {
         pricePerRequest?: number;
         currency?: string;
     };
+    /**
+     * Classifier id. Useful when the caller has only a URL and wants to
+     * round-trip the id through the response (some UCP servers serve
+     * multiple classifiers behind one base URL).
+     */
+    id?: string;
+    /**
+     * Classifier kind. Lets callers branch on type-specific quirks (e.g.
+     * rubric-based classifiers expose `factors`; case-based don't).
+     */
+    type?: 'case-based' | 'rubric-based' | 'reference' | 'lightweight' | 'custom';
+    /**
+     * Ordered list of severity levels emitted by the classifier. Order is
+     * the canonical priority order (`position` ascending). Routing-condition
+     * evaluators compare a classification result's `level` against this list
+     * to honor `>=` / `<=` operators on level labels.
+     */
+    levels?: Array<{
+        id: string;
+        position: number;
+        label: string;
+        threshold?: number;
+        description?: string;
+        color?: string;
+    }>;
+    /**
+     * Categories the classifier emits. Mostly used for UI / display, but
+     * surfaced here so handlers can present category labels without a
+     * second metadata lookup.
+     */
+    categories?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        position?: number;
+        emoji?: string;
+    }>;
+    /**
+     * Default conversation-turn window the classifier uses. Useful when a
+     * caller needs to truncate history before classifying (mirrors the
+     * Studio classifier model's `conversationTurns` field).
+     */
+    conversationTurns?: number;
 }
 /**
  * UCP Client configuration
@@ -557,6 +606,57 @@ interface PlatformClientConfig {
     /** 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;
+    };
+}
+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>;
+}
 interface PlatformChatbot {
     /** Studio chatbot MongoDB ID */
     id: string;
@@ -578,11 +678,31 @@ declare class PlatformClient {
     private token;
     private timeout;
     constructor(config: PlatformClientConfig);
+    private request;
+    /**
+     * Resolve the organization and token metadata for the configured token.
+     * Useful for connection state UI ("Connected to {orgName}") and audit.
+     */
+    getMe(): Promise<PlatformIdentity>;
     /**
      * List chatbots accessible to this handler's organization.
      * Studio resolves the organization from the API token.
      */
     listChatbots(): Promise<PlatformChatbot[]>;
+    /**
+     * 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.
+     */
+    registerChatbot(input: PlatformChatbotRegisterInput): Promise<PlatformChatbotRegistration>;
+    /**
+     * Mark the chatbot identified by `externalId` as disconnected.
+     * The Studio record is preserved (history, analytics survive).
+     */
+    unregisterChatbot(externalId: string): Promise<{
+        ok: boolean;
+        modified: number;
+    }>;
 }
 /**
  * Create a PlatformClient for calling back to FirstStep Studio.
@@ -653,4 +773,207 @@ declare function createAuthHeader(token: string): string;
  */
 declare function isValidToken(token: string): boolean;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+/**
+ * LLM Client
+ *
+ * SDK client for calling Studio's `/api/llm/*` proxy routes. Studio forwards
+ * the request body 1:1 to Google's Generative Language REST API, so the
+ * shapes here mirror Google's REST shape (NOT the @google/genai SDK shape).
+ *
+ * Reference: https://ai.google.dev/api/generate-content
+ *
+ * @example
+ * ```typescript
+ * import { createLLMClient } from '@firststep-studio/sdk';
+ *
+ * const llm = createLLMClient({
+ *   studioUrl: 'https://studio-api.example.com',
+ *   token: process.env.FIRSTSTEP_TOKEN!,
+ * });
+ *
+ * // Single-shot
+ * const res = await llm.generate({
+ *   model: 'gemini-3-flash-preview',
+ *   contents: [{ role: 'user', parts: [{ text: 'Hello' }] }],
+ *   generationConfig: { temperature: 0.7, maxOutputTokens: 500 },
+ * });
+ * console.log(res.candidates[0].content.parts[0].text);
+ *
+ * // Streaming
+ * for await (const chunk of llm.generateStream({
+ *   model: 'gemini-3-flash-preview',
+ *   contents: [{ role: 'user', parts: [{ text: 'Count to 5' }] }],
+ * })) {
+ *   process.stdout.write(chunk.candidates?.[0]?.content?.parts?.[0]?.text ?? '');
+ * }
+ *
+ * // Cache
+ * const cache = await llm.cache.create({
+ *   model: 'models/gemini-2.5-flash',
+ *   systemInstruction: { parts: [{ text: 'long system prompt...' }] },
+ *   ttl: '3600s',
+ * });
+ * await llm.cache.get(cache.name);
+ * await llm.cache.delete(cache.name);
+ * ```
+ */
+interface LLMClientConfig {
+    /** Studio backend API URL (e.g. https://studio-api.example.com) */
+    studioUrl: string;
+    /** API token (Bearer fst_<...>) */
+    token: string;
+    /** Request timeout in ms for non-streaming calls (default: 60000) */
+    timeout?: number;
+}
+interface LLMPart {
+    text?: string;
+    inlineData?: {
+        mimeType: string;
+        data: string;
+    };
+    [k: string]: unknown;
+}
+interface LLMContent {
+    role?: 'user' | 'model';
+    parts: LLMPart[];
+}
+interface LLMGenerationConfig {
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    topK?: number;
+    responseMimeType?: string;
+    responseSchema?: Record<string, unknown>;
+    thinkingConfig?: {
+        thinkingBudget?: number;
+        thinkingLevel?: 'minimal' | 'low' | 'medium' | 'high';
+        includeThoughts?: boolean;
+    };
+    stopSequences?: string[];
+    [k: string]: unknown;
+}
+interface LLMSafetySetting {
+    category: string;
+    threshold: string;
+}
+/**
+ * Request body for /api/llm/generate and /api/llm/generate/stream.
+ * Mirrors Google's `:generateContent` REST request, plus `model` at the top level
+ * so Studio can build the URL path.
+ */
+interface LLMGenerateRequest {
+    model: string;
+    contents: LLMContent[];
+    systemInstruction?: {
+        parts: LLMPart[];
+    };
+    generationConfig?: LLMGenerationConfig;
+    safetySettings?: LLMSafetySetting[];
+    /** Resource name of an explicit cache, e.g. "cachedContents/abc123" */
+    cachedContent?: string;
+    /** Function-calling tools (forwarded as-is) */
+    tools?: unknown[];
+    [k: string]: unknown;
+}
+interface LLMUsageMetadata {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    cachedContentTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+    [k: string]: unknown;
+}
+interface LLMCandidate {
+    content?: LLMContent;
+    finishReason?: string;
+    index?: number;
+    safetyRatings?: unknown[];
+    [k: string]: unknown;
+}
+interface LLMGenerateResponse {
+    candidates?: LLMCandidate[];
+    usageMetadata?: LLMUsageMetadata;
+    promptFeedback?: {
+        blockReason?: string;
+        [k: string]: unknown;
+    };
+    modelVersion?: string;
+    responseId?: string;
+    [k: string]: unknown;
+}
+interface LLMCacheCreateRequest {
+    model: string;
+    displayName?: string;
+    systemInstruction?: {
+        parts: LLMPart[];
+    };
+    contents?: LLMContent[];
+    /** Time-to-live, e.g. "3600s" */
+    ttl?: string;
+    [k: string]: unknown;
+}
+interface LLMCachedContent {
+    name: string;
+    model: string;
+    createTime?: string;
+    updateTime?: string;
+    expireTime?: string;
+    displayName?: string;
+    usageMetadata?: {
+        totalTokenCount?: number;
+    };
+    [k: string]: unknown;
+}
+declare class LLMError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare class LLMClient {
+    private studioUrl;
+    private token;
+    private timeout;
+    constructor(config: LLMClientConfig);
+    private headers;
+    /**
+     * Single-shot generation. Body is forwarded to Google's :generateContent
+     * unchanged. Response is Google's response shape unchanged.
+     */
+    generate(req: LLMGenerateRequest): Promise<LLMGenerateResponse>;
+    /**
+     * Streaming generation as an AsyncGenerator of partial responses.
+     * Each yielded chunk has the same shape as a non-streaming response (a
+     * `candidates[]` slice with the next text fragment, plus usageMetadata
+     * on the final chunk).
+     *
+     * Note: timeout option is not enforced for streams; consumer should
+     * abort externally if needed.
+     */
+    generateStream(req: LLMGenerateRequest): AsyncGenerator<LLMGenerateResponse>;
+    /**
+     * Explicit prompt cache surface. Maps to Google's `/cachedContents` REST API.
+     */
+    cache: {
+        /**
+         * Create an explicit cache. Returns the resource (use `cache.name` as the
+         * `cachedContent` field on a future generate() request).
+         */
+        create: (req: LLMCacheCreateRequest) => Promise<LLMCachedContent>;
+        /**
+         * Fetch a cache by resource name (e.g. "cachedContents/abc123").
+         * Returns null when the cache is not found (404), which is the common
+         * "expired" signal — callers can simply recreate.
+         */
+        get: (name: string) => Promise<LLMCachedContent | null>;
+        /**
+         * Delete a cache by resource name. Idempotent: 404 is treated as success.
+         */
+        delete: (name: string) => Promise<void>;
+    };
+}
+/**
+ * Create an LLMClient that talks to Studio's /api/llm/* proxy routes.
+ */
+declare function createLLMClient(config: LLMClientConfig): LLMClient;
+
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.js

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  LLMClient: () => LLMClient,
+  LLMError: () => LLMError,
   MARKER_TYPES: () => MARKER_TYPES,
   PlatformClient: () => PlatformClient,
   PlatformError: () => PlatformError,
@@ -27,6 +29,7 @@ __export(index_exports, {
   UCPError: () => UCPError,
   classifyWithUCP: () => classifyWithUCP,
   createAuthHeader: () => createAuthHeader,
+  createLLMClient: () => createLLMClient,
   createPlatformClient: () => createPlatformClient,
   createRequestSignature: () => createRequestSignature,
   createUCPClient: () => createUCPClient,
@@ -339,29 +342,64 @@ var PlatformClient = class {
     this.token = config.token;
     this.timeout = config.timeout || 1e4;
   }
-  /**
-   * List chatbots accessible to this handler's organization.
-   * Studio resolves the organization from the API token.
-   */
-  async listChatbots() {
-    const res = await fetch(`${this.studioUrl}/api/protocol/chatbots`, {
-      method: "GET",
+  async request(path, errorPrefix, init = {}) {
+    const res = await fetch(`${this.studioUrl}${path}`, {
+      method: init.method || "GET",
       headers: {
         "Authorization": `Bearer ${this.token}`,
         "Content-Type": "application/json"
       },
+      body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
       signal: AbortSignal.timeout(this.timeout)
     });
     if (!res.ok) {
       const body = await res.text().catch(() => "");
-      throw new PlatformError(
-        `Failed to list chatbots: ${res.status} ${body}`,
-        res.status
-      );
+      throw new PlatformError(`${errorPrefix}: ${res.status} ${body}`, res.status);
     }
-    const data = await res.json();
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  /**
+   * Resolve the organization and token metadata for the configured token.
+   * Useful for connection state UI ("Connected to {orgName}") and audit.
+   */
+  async getMe() {
+    return this.request("/api/protocol/me", "Failed to fetch identity");
+  }
+  /**
+   * List chatbots accessible to this handler's organization.
+   * Studio resolves the organization from the API token.
+   */
+  async listChatbots() {
+    const data = await this.request(
+      "/api/protocol/chatbots",
+      "Failed to list chatbots"
+    );
     return data.chatbots;
   }
+  /**
+   * 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.
+   */
+  async registerChatbot(input) {
+    return this.request(
+      "/api/protocol/chatbots",
+      "Failed to register chatbot",
+      { method: "POST", body: input }
+    );
+  }
+  /**
+   * Mark the chatbot identified by `externalId` as disconnected.
+   * The Studio record is preserved (history, analytics survive).
+   */
+  async unregisterChatbot(externalId) {
+    return this.request(
+      `/api/protocol/chatbots/${encodeURIComponent(externalId)}`,
+      "Failed to unregister chatbot",
+      { method: "DELETE" }
+    );
+  }
 };
 function createPlatformClient(config) {
   return new PlatformClient(config);
@@ -398,8 +436,193 @@ function createAuthHeader(token) {
 function isValidToken(token) {
   return typeof token === "string" && token.startsWith(TOKEN_PREFIX) && token.length === TOKEN_LENGTH;
 }
+
+// src/llm.ts
+var LLMError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = "LLMError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var LLMClient = class {
+  constructor(config) {
+    /**
+     * Explicit prompt cache surface. Maps to Google's `/cachedContents` REST API.
+     */
+    this.cache = {
+      /**
+       * Create an explicit cache. Returns the resource (use `cache.name` as the
+       * `cachedContent` field on a future generate() request).
+       */
+      create: async (req) => {
+        const res = await fetch(`${this.studioUrl}/api/llm/cache`, {
+          method: "POST",
+          headers: this.headers(),
+          body: JSON.stringify(req),
+          signal: AbortSignal.timeout(this.timeout)
+        });
+        const text = await res.text();
+        let body;
+        try {
+          body = text ? JSON.parse(text) : void 0;
+        } catch {
+          body = { raw: text };
+        }
+        if (!res.ok) {
+          throw new LLMError(`LLM cache.create failed: ${res.status}`, res.status, body);
+        }
+        return body;
+      },
+      /**
+       * Fetch a cache by resource name (e.g. "cachedContents/abc123").
+       * Returns null when the cache is not found (404), which is the common
+       * "expired" signal — callers can simply recreate.
+       */
+      get: async (name) => {
+        const res = await fetch(`${this.studioUrl}/api/llm/cache/${encodeURIComponent(name)}`, {
+          method: "GET",
+          headers: this.headers(),
+          signal: AbortSignal.timeout(this.timeout)
+        });
+        if (res.status === 404) return null;
+        const text = await res.text();
+        let body;
+        try {
+          body = text ? JSON.parse(text) : void 0;
+        } catch {
+          body = { raw: text };
+        }
+        if (!res.ok) {
+          throw new LLMError(`LLM cache.get failed: ${res.status}`, res.status, body);
+        }
+        return body;
+      },
+      /**
+       * Delete a cache by resource name. Idempotent: 404 is treated as success.
+       */
+      delete: async (name) => {
+        const res = await fetch(`${this.studioUrl}/api/llm/cache/${encodeURIComponent(name)}`, {
+          method: "DELETE",
+          headers: this.headers(),
+          signal: AbortSignal.timeout(this.timeout)
+        });
+        if (res.ok || res.status === 404) return;
+        const text = await res.text().catch(() => "");
+        let body;
+        try {
+          body = text ? JSON.parse(text) : void 0;
+        } catch {
+          body = { raw: text };
+        }
+        throw new LLMError(`LLM cache.delete failed: ${res.status}`, res.status, body);
+      }
+    };
+    this.studioUrl = config.studioUrl.replace(/\/+$/, "");
+    this.token = config.token;
+    this.timeout = config.timeout ?? 6e4;
+  }
+  headers() {
+    return {
+      "Authorization": `Bearer ${this.token}`,
+      "Content-Type": "application/json"
+    };
+  }
+  /**
+   * Single-shot generation. Body is forwarded to Google's :generateContent
+   * unchanged. Response is Google's response shape unchanged.
+   */
+  async generate(req) {
+    const res = await fetch(`${this.studioUrl}/api/llm/generate`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(req),
+      signal: AbortSignal.timeout(this.timeout)
+    });
+    const text = await res.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : void 0;
+    } catch {
+      body = { raw: text };
+    }
+    if (!res.ok) {
+      throw new LLMError(`LLM generate failed: ${res.status}`, res.status, body);
+    }
+    return body;
+  }
+  /**
+   * Streaming generation as an AsyncGenerator of partial responses.
+   * Each yielded chunk has the same shape as a non-streaming response (a
+   * `candidates[]` slice with the next text fragment, plus usageMetadata
+   * on the final chunk).
+   *
+   * Note: timeout option is not enforced for streams; consumer should
+   * abort externally if needed.
+   */
+  async *generateStream(req) {
+    const res = await fetch(`${this.studioUrl}/api/llm/generate/stream`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(req)
+    });
+    if (!res.ok || !res.body) {
+      const text = await res.text().catch(() => "");
+      let body;
+      try {
+        body = text ? JSON.parse(text) : void 0;
+      } catch {
+        body = { raw: text };
+      }
+      throw new LLMError(`LLM generateStream failed: ${res.status}`, res.status, body);
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const t2 = line.trim();
+          if (!t2.startsWith("data: ")) continue;
+          const payload = t2.slice(6);
+          if (payload === "[DONE]") continue;
+          try {
+            yield JSON.parse(payload);
+          } catch {
+          }
+        }
+      }
+      const t = buffer.trim();
+      if (t.startsWith("data: ")) {
+        const payload = t.slice(6);
+        if (payload && payload !== "[DONE]") {
+          try {
+            yield JSON.parse(payload);
+          } catch {
+          }
+        }
+      }
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+      }
+    }
+  }
+};
+function createLLMClient(config) {
+  return new LLMClient(config);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  LLMClient,
+  LLMError,
   MARKER_TYPES,
   PlatformClient,
   PlatformError,
@@ -407,6 +630,7 @@ function isValidToken(token) {
   UCPError,
   classifyWithUCP,
   createAuthHeader,
+  createLLMClient,
   createPlatformClient,
   createRequestSignature,
   createUCPClient,