@sogni-ai/sogni-client 4.2.0-alpha.21 → 4.2.0-alpha.22

package/src/Chat/tools.ts

@@ -2,19 +2,41 @@ import hostedToolManifest from './sogniHostedTools.generated.json';
 import { ToolDefinition, ToolCall } from './types';
 import { filterVideoModelsByWorkflow, isEditImageModel, VideoWorkflow } from './modelRouting';
 
-type SogniHostedToolName =
-  | 'sogni_generate_image'
-  | 'sogni_edit_image'
-  | 'sogni_generate_video'
-  | 'sogni_sound_to_video'
-  | 'sogni_video_to_video'
-  | 'sogni_generate_music';
+/**
+ * Canonical hosted creative-tool names mirrored from
+ * `@sogni/creative-agent/src/backbone/openai-tools/{generation,composition}-tools.json`.
+ * The legacy `sogni_*` prefixed names were retired; tool names are now flat.
+ */
+export type SogniHostedToolName =
+  | 'generate_image'
+  | 'generate_video'
+  | 'generate_music'
+  | 'edit_image'
+  | 'apply_style'
+  | 'restore_photo'
+  | 'refine_result'
+  | 'animate_photo'
+  | 'change_angle'
+  | 'video_to_video'
+  | 'stitch_video'
+  | 'orbit_video'
+  | 'dance_montage'
+  | 'sound_to_video'
+  | 'extend_video'
+  | 'replace_video_segment'
+  | 'overlay_video'
+  | 'add_subtitles'
+  | 'enhance_prompt'
+  | 'compose_lyrics'
+  | 'compose_instrumental'
+  | 'compose_script';
 
 interface SogniHostedToolManifest {
   tools: ToolDefinition[];
 }
 
 const hostedTools = (hostedToolManifest as SogniHostedToolManifest).tools;
+const HOSTED_TOOL_NAMES = new Set<string>(hostedTools.map((tool) => tool.function.name));
 
 function getHostedTool(name: SogniHostedToolName): ToolDefinition {
   const tool = hostedTools.find((candidate) => candidate.function.name === name);
@@ -47,17 +69,40 @@ function setModelEnum(
 /**
  * Built-in Sogni platform tool definitions for use with LLM tool calling.
  *
- * These definitions are generated from the shared
- * `@sogni/creative-agent` hosted tool backbone. The public SDK keeps a local
- * generated copy so consumers do not need access to the private package.
+ * Generated from the shared `@sogni/creative-agent` hosted tool backbone via
+ * `npm run sync:hosted-tools-manifest`. The public SDK keeps a local copy so
+ * consumers do not need the private creative-agent package at runtime.
  */
 
-export const generateImageTool: ToolDefinition = getHostedTool('sogni_generate_image');
-export const editImageTool: ToolDefinition = getHostedTool('sogni_edit_image');
-export const generateVideoTool: ToolDefinition = getHostedTool('sogni_generate_video');
-export const soundToVideoTool: ToolDefinition = getHostedTool('sogni_sound_to_video');
-export const videoToVideoTool: ToolDefinition = getHostedTool('sogni_video_to_video');
-export const generateMusicTool: ToolDefinition = getHostedTool('sogni_generate_music');
+// Generation tools (image / video / audio).
+export const generateImageTool: ToolDefinition = getHostedTool('generate_image');
+export const editImageTool: ToolDefinition = getHostedTool('edit_image');
+export const generateVideoTool: ToolDefinition = getHostedTool('generate_video');
+export const soundToVideoTool: ToolDefinition = getHostedTool('sound_to_video');
+export const videoToVideoTool: ToolDefinition = getHostedTool('video_to_video');
+export const generateMusicTool: ToolDefinition = getHostedTool('generate_music');
+
+// Image adapters (style / restore / refine / re-angle / animate).
+export const applyStyleTool: ToolDefinition = getHostedTool('apply_style');
+export const restorePhotoTool: ToolDefinition = getHostedTool('restore_photo');
+export const refineResultTool: ToolDefinition = getHostedTool('refine_result');
+export const changeAngleTool: ToolDefinition = getHostedTool('change_angle');
+export const animatePhotoTool: ToolDefinition = getHostedTool('animate_photo');
+
+// Video composition / post-production tools.
+export const stitchVideoTool: ToolDefinition = getHostedTool('stitch_video');
+export const orbitVideoTool: ToolDefinition = getHostedTool('orbit_video');
+export const danceMontageTool: ToolDefinition = getHostedTool('dance_montage');
+export const extendVideoTool: ToolDefinition = getHostedTool('extend_video');
+export const replaceVideoSegmentTool: ToolDefinition = getHostedTool('replace_video_segment');
+export const overlayVideoTool: ToolDefinition = getHostedTool('overlay_video');
+export const addSubtitlesTool: ToolDefinition = getHostedTool('add_subtitles');
+
+// Synchronous composition tools (text-only outputs).
+export const enhancePromptTool: ToolDefinition = getHostedTool('enhance_prompt');
+export const composeLyricsTool: ToolDefinition = getHostedTool('compose_lyrics');
+export const composeInstrumentalTool: ToolDefinition = getHostedTool('compose_instrumental');
+export const composeScriptTool: ToolDefinition = getHostedTool('compose_script');
 
 export const SogniTools = {
   generateImage: generateImageTool,
@@ -66,15 +111,30 @@ export const SogniTools = {
   soundToVideo: soundToVideoTool,
   videoToVideo: videoToVideoTool,
   generateMusic: generateMusicTool,
+  applyStyle: applyStyleTool,
+  restorePhoto: restorePhotoTool,
+  refineResult: refineResultTool,
+  changeAngle: changeAngleTool,
+  animatePhoto: animatePhotoTool,
+  stitchVideo: stitchVideoTool,
+  orbitVideo: orbitVideoTool,
+  danceMontage: danceMontageTool,
+  extendVideo: extendVideoTool,
+  replaceVideoSegment: replaceVideoSegmentTool,
+  overlayVideo: overlayVideoTool,
+  addSubtitles: addSubtitlesTool,
+  enhancePrompt: enhancePromptTool,
+  composeLyrics: composeLyricsTool,
+  composeInstrumental: composeInstrumentalTool,
+  composeScript: composeScriptTool,
+  /**
+   * Full canonical hosted creative-tools surface — generation tools, image
+   * adapters, video composition / post-production, and synchronous composition
+   * tools. Mirrored from `@sogni/creative-agent`. Route tool calls through
+   * `chat.hosted.create()` or `chat.runs.create()` for server-side execution.
+   */
   get all(): ToolDefinition[] {
-    return [
-      generateImageTool,
-      editImageTool,
-      generateVideoTool,
-      soundToVideoTool,
-      videoToVideoTool,
-      generateMusicTool
-    ];
+    return [...hostedTools];
   }
 };
 
@@ -102,30 +162,35 @@ export function buildSogniTools(
     .filter((model) => model.media === 'audio')
     .map((model) => model.id);
 
-  return [
-    setModelEnum(cloneTool(generateImageTool), imageModels, 'Image generation model to use.'),
-    setModelEnum(
-      cloneTool(editImageTool),
+  const modelEnumOverrides: Partial<Record<SogniHostedToolName, [string[], string]>> = {
+    generate_image: [imageModels, 'Image generation model to use.'],
+    edit_image: [
       editImageModels,
       'Image editing model to use. These models support reference-guided editing.'
-    ),
-    setModelEnum(
-      cloneTool(generateVideoTool),
+    ],
+    generate_video: [
       videoModels,
       'Video generation model to use. Prefer t2v models for text-only generation and i2v models when reference images are supplied.'
-    ),
-    setModelEnum(
-      cloneTool(soundToVideoTool),
-      soundToVideoModels,
-      'Audio-driven video model to use.'
-    ),
-    setModelEnum(cloneTool(videoToVideoTool), videoToVideoModels, 'Video-to-video model to use.'),
-    setModelEnum(cloneTool(generateMusicTool), audioModels, 'Music generation model to use.')
-  ];
+    ],
+    sound_to_video: [soundToVideoModels, 'Audio-driven video model to use.'],
+    video_to_video: [videoToVideoModels, 'Video-to-video model to use.'],
+    generate_music: [audioModels, 'Music generation model to use.']
+  };
+
+  return hostedTools.map((tool) => {
+    const override = modelEnumOverrides[tool.function.name as SogniHostedToolName];
+    if (!override) return tool;
+    return setModelEnum(cloneTool(tool), override[0], override[1]);
+  });
 }
 
+/**
+ * True if the tool call targets a canonical Sogni hosted creative tool.
+ * Replaces the legacy `sogni_` prefix check; tool names are now flat and
+ * verified against the manifest mirrored from `@sogni/creative-agent`.
+ */
 export function isSogniToolCall(toolCall: ToolCall): boolean {
-  return toolCall.function.name.startsWith('sogni_');
+  return HOSTED_TOOL_NAMES.has(toolCall.function.name);
 }
 
 export function parseToolCallArguments(toolCall: ToolCall): Record<string, unknown> {

package/src/Chat/types.ts

@@ -119,8 +119,8 @@ export interface ChatCompletionParams {
   sogni_tools?: SogniToolsMode;
   /**
    * When `sogni_tools` is enabled, ask the Sogni API to execute requested Sogni
-   * tools server-side before returning the chat response. This is separate from
-   * the SDK-local `autoExecuteTools` loop.
+   * tools server-side before returning the chat response. Independent of the
+   * SDK's client-side `autoExecuteTools` loop.
    */
   sogni_tool_execution?: boolean;
   /**
@@ -263,8 +263,18 @@ export type HostedChatCompletionParams = Omit<
   'stream' | 'autoExecuteTools' | 'onToolCall' | 'onToolProgress' | 'maxToolRounds'
 > & {
   stream?: false;
-  token_type?: 'sogni' | 'spark' | 'auto';
+  /** Optional source label for this hosted REST request. Defaults to the client appSource when configured. */
   app_source?: string;
+  /** camelCase alias for {@link HostedChatCompletionParams.app_source}. */
+  appSource?: string;
+  /** Token type to use for hosted REST billing. */
+  token_type?: 'sogni' | 'spark';
+  /** camelCase alias for {@link HostedChatCompletionParams.token_type}. */
+  tokenType?: 'sogni' | 'spark';
+  /** Hosted REST task profile hint. */
+  task_profile?: 'general' | 'coding' | 'reasoning';
+  /** camelCase alias for {@link HostedChatCompletionParams.task_profile}. */
+  taskProfile?: 'general' | 'coding' | 'reasoning';
   chat_template_kwargs?: Record<string, unknown>;
   media_references?: unknown[];
   mediaReferences?: unknown[];
@@ -272,6 +282,124 @@ export type HostedChatCompletionParams = Omit<
   apiMediaReferences?: unknown[];
 };
 
+/**
+ * Durable hosted chat run status.
+ *
+ * Mirrors the canonical state machine from
+ * `@sogni/creative-agent/backbone` `ChatRunStatus`. The duplicate
+ * declaration here keeps the SDK self-contained — the shared package is
+ * not a runtime SDK dependency.
+ */
+export type ChatRunStatus =
+  | 'queued'
+  | 'running'
+  | 'waiting_for_user'
+  | 'completed'
+  | 'partial_failure'
+  | 'failed'
+  | 'cancelled';
+
+export interface ChatRunEvent {
+  sequence: number;
+  type: string;
+  at: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface ChatRunRecord {
+  runId: string;
+  status: ChatRunStatus;
+  schemaVersion: string;
+  scope: {
+    ownerWalletAddress: string;
+    tokenType?: string;
+    appSource?: string;
+  };
+  request: {
+    sessionId?: string;
+    clientMessageId?: string;
+    model?: string;
+    messages: unknown[];
+    [key: string]: unknown;
+  };
+  messages: unknown[];
+  toolCalls: unknown[];
+  toolResults: unknown[];
+  mediaContext: {
+    images: string[];
+    videos: string[];
+    audio: string[];
+    uploadedImages?: string[];
+    uploadedVideos?: string[];
+    uploadedAudio?: string[];
+  };
+  artifacts: unknown[];
+  events: ChatRunEvent[];
+  finalResponse?: {
+    content?: string;
+    finishReason?: string;
+  };
+  waiting?: {
+    reason: string;
+    message?: string;
+    details?: Record<string, unknown>;
+  };
+  billingPreview?: unknown;
+  billingPreviews?: unknown[];
+  failureReason?: string;
+  cancellationReason?: string;
+  timestamps: {
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+  };
+}
+
+export interface StartChatRunParams {
+  /** OpenAI-style messages array. Required. */
+  messages: unknown[];
+  /** OpenAI-style tools array. */
+  tools?: unknown[];
+  /** OpenAI-style tool choice (`auto`, `none`, or specific tool). */
+  toolChoice?: unknown;
+  /** Model id requested for the run. */
+  model?: string;
+  /** Sampling defaults captured with the run for reproducibility. */
+  sampling?: Record<string, unknown>;
+  /** Inbound media references attached to the run. */
+  mediaReferences?: unknown[];
+  /** Full chat media context snapshot for generated + uploaded source indexing. */
+  mediaContext?: {
+    images: string[];
+    videos: string[];
+    audio: string[];
+    uploadedImages?: string[];
+    uploadedVideos?: string[];
+    uploadedAudio?: string[];
+  };
+  /** Cost ceiling for this run (capacity units). */
+  maxEstimatedCapacityUnits?: number;
+  /** Set true to confirm higher-cost work. */
+  confirmCost?: boolean;
+  /** Stable session id for browser-side rehydration queries. */
+  sessionId?: string;
+  /** Stable client message id for pairing with the assistant response. */
+  clientMessageId?: string;
+  /** Token type for billing. */
+  tokenType?: 'sogni' | 'spark';
+  /** App source label for attribution. */
+  appSource?: string;
+  /** Idempotency key (also accepted via `Idempotency-Key` header). */
+  idempotencyKey?: string;
+}
+
+export interface StreamChatRunEventsOptions {
+  /** Last event sequence id observed by the caller. */
+  lastEventId?: number;
+  /** Optional AbortSignal to terminate the stream. */
+  signal?: AbortSignal;
+}
+
 export interface ChatJobStateEvent {
   jobID: string;
   type: string;

package/src/CreativeWorkflows/index.ts

@@ -7,8 +7,6 @@ import {
   ListCreativeWorkflowOptions,
   StartCreativeWorkflowOptions,
   StartCreativeWorkflowParams,
-  StartHostedToolSequenceWorkflowInput,
-  StartImageToVideoWorkflowInput,
   StreamCreativeWorkflowEventsOptions
 } from './types';
 
@@ -107,58 +105,41 @@ class CreativeWorkflowsApi extends ApiGroup {
     params: StartCreativeWorkflowParams,
     options: StartCreativeWorkflowOptions = {}
   ): Promise<CreativeWorkflowRecord> {
+    const tokenType = params.tokenType ?? params.token_type;
+    const appSource = params.appSource ?? params.app_source;
+    const idempotencyKey = params.idempotencyKey ?? params.idempotency_key;
+    const mediaReferences = params.mediaReferences ?? params.media_references;
+    const maxEstimatedCapacityUnits =
+      params.maxEstimatedCapacityUnits ?? params.max_estimated_capacity_units;
+    const confirmCost = params.confirmCost ?? params.confirm_cost;
+
     const body: Record<string, unknown> = {
-      kind: params.kind,
       input: params.input
     };
-    const tokenType = params.token_type ?? params.tokenType;
-    if (tokenType) {
-      body.token_type = tokenType;
+    if (tokenType) body.token_type = tokenType;
+    if (appSource) body.app_source = appSource;
+    if (maxEstimatedCapacityUnits !== undefined) {
+      body.max_estimated_capacity_units = maxEstimatedCapacityUnits;
+    }
+    if (confirmCost !== undefined) body.confirm_cost = confirmCost;
+    if (mediaReferences !== undefined) body.media_references = mediaReferences;
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json'
+    };
+    if (idempotencyKey) {
+      headers['Idempotency-Key'] = idempotencyKey;
     }
 
     const response = await this.request<CreativeWorkflowEnvelope>('/v1/creative-agent/workflows', {
       method: 'POST',
-      headers: {
-        'Content-Type': 'application/json'
-      },
+      headers,
       body: JSON.stringify(body),
       signal: options.signal
     });
     return parseEnvelope<CreativeWorkflowRecord>(response, 'workflow');
   }
 
-  startImageToVideo(
-    input: StartImageToVideoWorkflowInput,
-    options: StartCreativeWorkflowOptions & {
-      tokenType?: StartCreativeWorkflowParams['tokenType'];
-    } = {}
-  ): Promise<CreativeWorkflowRecord> {
-    return this.start(
-      {
-        kind: 'image_to_video',
-        input,
-        tokenType: options.tokenType
-      },
-      options
-    );
-  }
-
-  startHostedToolSequence(
-    input: StartHostedToolSequenceWorkflowInput,
-    options: StartCreativeWorkflowOptions & {
-      tokenType?: StartCreativeWorkflowParams['tokenType'];
-    } = {}
-  ): Promise<CreativeWorkflowRecord> {
-    return this.start(
-      {
-        kind: 'hosted_tool_sequence',
-        input,
-        tokenType: options.tokenType
-      },
-      options
-    );
-  }
-
   async list(options: ListCreativeWorkflowOptions = {}): Promise<CreativeWorkflowRecord[]> {
     const response = await this.request<CreativeWorkflowEnvelope>(
       `/v1/creative-agent/workflows${toQuery({

package/src/CreativeWorkflows/types.ts

@@ -4,18 +4,41 @@ export type CreativeWorkflowStatus =
   | 'queued'
   | 'running'
   | 'completed'
+  | 'partial_failure'
+  | 'waiting_for_user'
   | 'failed'
   | 'cancelled'
   | string;
 
-export type CreativeWorkflowKind = 'image_to_video' | 'hosted_tool_sequence' | string;
 export type CreativeWorkflowHostedToolName =
-  | 'sogni_generate_image'
-  | 'sogni_edit_image'
-  | 'sogni_generate_video'
-  | 'sogni_sound_to_video'
-  | 'sogni_video_to_video'
-  | 'sogni_generate_music';
+  | 'generate_image'
+  | 'generate_video'
+  | 'generate_music'
+  | 'edit_image'
+  | 'apply_style'
+  | 'restore_photo'
+  | 'refine_result'
+  | 'animate_photo'
+  | 'change_angle'
+  | 'video_to_video'
+  | 'stitch_video'
+  | 'orbit_video'
+  | 'dance_montage'
+  | 'sound_to_video'
+  | 'extend_video'
+  | 'replace_video_segment'
+  | 'overlay_video'
+  | 'add_subtitles'
+  | 'analyze_image'
+  | 'analyze_video'
+  | 'extract_metadata'
+  | 'ask_clarifying_question'
+  | 'finalize_response'
+  | 'create_asset_manifest'
+  | 'inspect_asset'
+  | 'label_asset'
+  | 'map_assets_for_model'
+  | 'validate_asset_references';
 
 export interface CreativeWorkflowArtifact {
   id?: string;
@@ -42,7 +65,6 @@ export interface CreativeWorkflowEvent {
 
 export interface CreativeWorkflowRecord {
   workflowId: string;
-  kind?: CreativeWorkflowKind;
   title?: string;
   status?: CreativeWorkflowStatus;
   input?: Record<string, unknown>;
@@ -60,56 +82,61 @@ export interface CreativeWorkflowRecord {
   [key: string]: unknown;
 }
 
-export interface StartImageToVideoWorkflowInput {
-  prompt: string;
-  videoPrompt?: string;
-  negativePrompt?: string;
-  width?: number;
-  height?: number;
-  duration?: number;
-  imageModel?: string;
-  videoModel?: string;
-  numberOfMedia?: number;
-  seed?: number;
-  [key: string]: unknown;
-}
-
-export interface StartHostedToolSequenceWorkflowDependency {
+export interface StartCreativeWorkflowDependency {
   sourceStepId: string;
   targetArgument: string;
-  transform: 'artifact_url' | 'artifact_data_uri';
+  transform:
+    | 'artifact_url'
+    | 'artifact_data_uri'
+    | 'image_url'
+    | 'video_url'
+    | 'audio_url'
+    | 'image_index'
+    | 'video_index'
+    | 'audio_index'
+    | 'subtitle_cues'
+    | 'subtitle_srt'
+    | 'overlay_items'
+    | 'asset_ref';
   sourceArtifactId?: string;
   sourceArtifactIndex?: number;
   mediaType?: 'image' | 'video' | 'audio';
   required?: boolean;
 }
 
-export interface StartHostedToolSequenceWorkflowStep {
+export interface StartCreativeWorkflowStep {
   id?: string;
   toolName: CreativeWorkflowHostedToolName;
   arguments: Record<string, unknown>;
-  dependsOn?: StartHostedToolSequenceWorkflowDependency[];
+  dependsOn?: StartCreativeWorkflowDependency[];
 }
 
-export interface StartHostedToolSequenceWorkflowInput {
+export interface StartCreativeWorkflowInput {
   title?: string;
-  steps: StartHostedToolSequenceWorkflowStep[];
-  [key: string]: unknown;
+  steps: StartCreativeWorkflowStep[];
 }
 
-export type StartCreativeWorkflowParams =
-  | {
-      kind: 'image_to_video';
-      input: StartImageToVideoWorkflowInput;
-      tokenType?: TokenType;
-      token_type?: TokenType;
-    }
-  | {
-      kind: 'hosted_tool_sequence';
-      input: StartHostedToolSequenceWorkflowInput;
-      tokenType?: TokenType;
-      token_type?: TokenType;
-    };
+export interface StartCreativeWorkflowParams {
+  input: StartCreativeWorkflowInput;
+  tokenType?: TokenType;
+  appSource?: string;
+  idempotencyKey?: string;
+  mediaReferences?: unknown[];
+  maxEstimatedCapacityUnits?: number;
+  confirmCost?: boolean;
+  /** @internal Undocumented compatibility alias. Use tokenType. */
+  token_type?: TokenType;
+  /** @internal Undocumented compatibility alias. Use appSource. */
+  app_source?: string;
+  /** @internal Undocumented compatibility alias. Use idempotencyKey. */
+  idempotency_key?: string;
+  /** @internal Undocumented compatibility alias. Use mediaReferences. */
+  media_references?: unknown[];
+  /** @internal Undocumented compatibility alias. Use maxEstimatedCapacityUnits. */
+  max_estimated_capacity_units?: number;
+  /** @internal Undocumented compatibility alias. Use confirmCost. */
+  confirm_cost?: boolean;
+}
 
 export interface StartCreativeWorkflowOptions {
   signal?: AbortSignal;

package/src/index.ts

@@ -53,6 +53,11 @@ import {
   ChatCompletionResult,
   ChatJobStateEvent,
   ChatResponseFormat,
+  ChatRunEvent,
+  ChatRunRecord,
+  ChatRunStatus,
+  StartChatRunParams,
+  StreamChatRunEventsOptions,
   ContentPart,
   HostedChatCompletionParams,
   HostedChatCompletionResult,
@@ -85,7 +90,6 @@ import CreativeWorkflowsApi, { parseCreativeWorkflowSseChunk } from './CreativeW
 import {
   CreativeWorkflowArtifact,
   CreativeWorkflowEvent,
-  CreativeWorkflowKind,
   CreativeWorkflowRecord,
   CreativeWorkflowSseEvent,
   CreativeWorkflowStatus,
@@ -93,10 +97,9 @@ import {
   ListCreativeWorkflowOptions,
   StartCreativeWorkflowOptions,
   StartCreativeWorkflowParams,
-  StartHostedToolSequenceWorkflowDependency,
-  StartHostedToolSequenceWorkflowInput,
-  StartHostedToolSequenceWorkflowStep,
-  StartImageToVideoWorkflowInput,
+  StartCreativeWorkflowDependency,
+  StartCreativeWorkflowInput,
+  StartCreativeWorkflowStep,
   StreamCreativeWorkflowEventsOptions
 } from './CreativeWorkflows/types';
 // Stats API
@@ -123,7 +126,12 @@ export type {
   ChatJobStateEvent,
   ChatMessage,
   ChatResponseFormat,
+  ChatRunEvent,
+  ChatRunRecord,
+  ChatRunStatus,
   ChatTokenUsage,
+  StartChatRunParams,
+  StreamChatRunEventsOptions,
   ContentPart,
   HostedChatCompletionChoice,
   HostedChatCompletionMessage,
@@ -132,7 +140,6 @@ export type {
   HostedCreativeWorkflowReference,
   CreativeWorkflowArtifact,
   CreativeWorkflowEvent,
-  CreativeWorkflowKind,
   CreativeWorkflowRecord,
   CreativeWorkflowSseEvent,
   CreativeWorkflowStatus,
@@ -158,10 +165,9 @@ export type {
   CreativeWorkflowHostedToolName,
   StartCreativeWorkflowOptions,
   StartCreativeWorkflowParams,
-  StartHostedToolSequenceWorkflowDependency,
-  StartHostedToolSequenceWorkflowInput,
-  StartHostedToolSequenceWorkflowStep,
-  StartImageToVideoWorkflowInput,
+  StartCreativeWorkflowDependency,
+  StartCreativeWorkflowInput,
+  StartCreativeWorkflowStep,
   StreamCreativeWorkflowEventsOptions,
   SupernetType,
   TokenType,
@@ -292,8 +298,23 @@ export class SogniClient {
   account: AccountApi;
   projects: ProjectsApi;
   stats: StatsApi;
+  /**
+   * Chat surfaces.
+   * - `chat.completions.create` — socket-native chat completion.
+   * - `chat.hosted.create` — hosted REST chat completion (synchronous).
+   * - `chat.runs.{create, get, cancel, streamEvents}` — durable hosted
+   *   chat runs that survive client disconnect, browser close, network
+   *   drop, and API worker restart. See `/v1/chat/runs` REST surface.
+   * - `chat.tools.execute*` — execute Sogni platform tools surfaced by
+   *   the chat completion (image / video / music generation).
+   */
   chat: ChatApi;
-  creativeWorkflows: CreativeWorkflowsApi;
+  /**
+   * Durable creative workflows (`/v1/creative-agent/workflows`). Submit
+   * an explicit step sequence and follow its progress without keeping
+   * the client connected.
+   */
+  workflows: CreativeWorkflowsApi;
 
   apiClient: ApiClient;
 
@@ -302,7 +323,7 @@ export class SogniClient {
     this.projects = new ProjectsApi(config);
     this.stats = new StatsApi(config);
     this.chat = new ChatApi(config, this.projects);
-    this.creativeWorkflows = new CreativeWorkflowsApi(config);
+    this.workflows = new CreativeWorkflowsApi(config);
 
     this.apiClient = config.client;
   }