@sogni-ai/sogni-client 5.2.0 → 5.3.1

package/src/Chat/_hostedToolsManifest.generated.ts

@@ -12,7 +12,7 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
       "type": "function",
       "function": {
         "name": "generate_image",
-        "description": "Generate a new image from a text description. Usually this is text-only: do NOT use this tool when the user expects an existing image to be reused or preserved in the result. That includes (a) people from My Personas, and (b) uploaded assets such as logos, brand marks, mascots, product shots, photos, screenshots, sketches, character designs, or other reference images they want carried through. Use edit_image with sourceImageIndex=-1 (or the appropriate generated index) instead. Exception: when the user explicitly requests Z-image, Z Image, or Z-image Turbo for an uploaded-image enhancement/image-to-image request, use this tool with model=\"z-turbo\" or model=\"z-image\", sourceImageIndex=-1, and starting_image_strength because edit_image does not expose Z-image models.",
+        "description": "Generate a new image from a text description. Usually this is text-only: do NOT use this tool when the user expects an existing image to be reused or preserved in the result. That includes (a) people from My Personas, and (b) uploaded assets such as logos, brand marks, mascots, product shots, photos, screenshots, sketches, character designs, or other reference images they want carried through. Use edit_image with sourceImageIndex=-1 (or the appropriate generated index) instead. Exception: when the user explicitly requests Z-image, Z Image, Z-image Turbo, or Krea 2 Turbo for an uploaded-image enhancement/image-to-image request, use this tool with model=\"z-turbo\", model=\"z-image\", or model=\"krea-2-turbo\", sourceImageIndex=-1, and starting_image_strength because edit_image does not expose those base image-to-image models.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -27,7 +27,10 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
                 "z-turbo",
                 "z-image",
                 "krea-2-turbo",
+                "dark-beast-krea2",
+                "dark-beast-z-turbo",
                 "chroma-v46-flash",
+                "chroma1-hd",
                 "chroma-detail",
                 "flux1-krea",
                 "flux2",
@@ -36,6 +39,7 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
                 "qwen-2512-lightning",
                 "albedo-xl",
                 "animagine-xl",
+                "one-obsession-v22",
                 "anima-pencil-xl",
                 "art-universe-xl",
                 "hyphoria-real",
@@ -47,15 +51,15 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
                 "pony-faetality",
                 "dreamshaper-xl"
               ],
-              "description": "DO NOT SET THIS PARAMETER unless the user names a specific model, asks for a very complex image render, asks for a video storyboard/storyboard sheet/contact sheet/panel layout image, or explicitly asks for Z-image/Z-image Turbo image-to-image. The app auto-selects based on quality settings. Set \"gpt-image-2\" when the user asks for a ChatGPT, OpenAI, GPT, GPT-2, GPT Image, or gpt-image-2 image/model, when they explicitly request very strong text rendering, or by default for complex single-image renders that need dense labels, crisp typography, multi-panel composition, timing notes, foley notes, professional storyboard-sheet layout, or a comprehensive character/mascot/model sheet with turnarounds, expressions, accessories, palette swatches, and brand notes. Set \"z-turbo\" when the user asks for Z-image Turbo; set \"z-image\" when they ask for Z-image without Turbo. If the user names another image model, honor that requested model instead. A model preference usually does not change which tool to use; the Z-image image-to-image exception uses sourceImageIndex plus starting_image_strength on this tool. NSFW rule: \"gpt-image-2\"/\"flux2\"/\"flux1-krea\" CANNOT do nudity — use \"pony-v7\", \"chroma-detail\", \"chroma-v46-flash\", or \"z-turbo\" instead."
+              "description": "DO NOT SET THIS PARAMETER unless the user names a specific model, asks for a very complex image render, asks for a video storyboard/storyboard sheet/contact sheet/panel layout image, asks for anime without naming a model, requests permitted NSFW/nudity content, or explicitly asks for Z-image/Z-image Turbo/Krea 2 Turbo image-to-image. The app auto-selects based on quality settings. Set \"gpt-image-2\" when the user asks for a ChatGPT, OpenAI, GPT, GPT-2, GPT Image, or gpt-image-2 image/model, when they explicitly request very strong text rendering, or by default for complex single-image renders that need dense labels, crisp typography, multi-panel composition, timing notes, foley notes, professional storyboard-sheet layout, or a comprehensive character/mascot/model sheet with turnarounds, expressions, accessories, palette swatches, and brand notes. Set \"one-obsession-v22\" when the user asks for an anime or anime-style image and has not named a specific image model. Set \"z-turbo\" when the user asks for Z-image Turbo; set \"z-image\" when they ask for Z-image without Turbo. Set \"krea-2-turbo\" when the user asks for Krea 2 Turbo. If the user names another image model, honor that requested model instead. A model preference usually does not change which tool to use; the Z-image and Krea 2 Turbo image-to-image exception uses sourceImageIndex plus starting_image_strength on this tool. NSFW rule: \"gpt-image-2\"/\"flux2\"/\"flux1-krea\"/Qwen image models CANNOT do nudity. For permitted NSFW/nudity content, prefer \"dark-beast-krea2\", then \"dark-beast-z-turbo\"; \"chroma1-hd\", \"pony-v7\", \"chroma-detail\", \"chroma-v46-flash\", and \"z-turbo\" are compatible fallbacks."
             },
             "width": {
               "type": "number",
-              "description": "Output image width in pixels. Default: 1024. Supported range is 256-2560 for default Z/Qwen/Flux.2 image models and 256-2048 for legacy/specialized image models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a width, exact pixel dimensions, or a named resolution (e.g., \"1280 wide\", \"1280x720\", \"720p\", \"1080x1920\", \"3840x2160\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds, so do not ask the user to adjust by a few pixels."
+              "description": "Output image width in pixels. Default: 1024. Supported bounds depend on the selected image model: Z-Image/Z-Image Turbo, Dark Beast Z-Image Turbo, Chroma, and legacy/specialized image models support 256-2048 on either edge; Krea 2 Turbo, Dark Beast KREA 2, and Qwen image models support 256-2560 on either edge; One Obsession v22 supports 256-1920 on either edge; Flux.2 uses a 2048x2048 total pixel budget (4,194,304 pixels) with non-square edges up to 2816, such as 1408x2816; GPT Image 2 supports flexible dimensions up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400. Set when the user specifies a width, exact pixel dimensions, or a named resolution (e.g., \"1280 wide\", \"1280x720\", \"720p\", \"1080x1920\", \"3840x2160\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels."
             },
             "height": {
               "type": "number",
-              "description": "Output image height in pixels. Default: 1024. Supported range is 256-2560 for default Z/Qwen/Flux.2 image models and 256-2048 for legacy/specialized image models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a height, exact pixel dimensions, or a named resolution (e.g., \"720 high\", \"1280x720\", \"720p\", \"1080x1920\", \"2160x3840\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds, so do not ask the user to adjust by a few pixels."
+              "description": "Output image height in pixels. Default: 1024. Supported bounds depend on the selected image model: Z-Image/Z-Image Turbo, Dark Beast Z-Image Turbo, Chroma, and legacy/specialized image models support 256-2048 on either edge; Krea 2 Turbo, Dark Beast KREA 2, and Qwen image models support 256-2560 on either edge; One Obsession v22 supports 256-1920 on either edge; Flux.2 uses a 2048x2048 total pixel budget (4,194,304 pixels) with non-square edges up to 2816, such as 1408x2816; GPT Image 2 supports flexible dimensions up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400. Set when the user specifies a height, exact pixel dimensions, or a named resolution (e.g., \"720 high\", \"1280x720\", \"720p\", \"1080x1920\", \"2160x3840\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels."
             },
             "numberOfVariations": {
               "type": "number",
@@ -69,7 +73,7 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
             },
             "starting_image_strength": {
               "type": "number",
-              "description": "Image-to-image strength (0.0-1.0). Only used when a source image is available and model supports img2img. Higher values = more deviation from the source image. 0.35 = conservative enhancement, 0.5 = balanced, 0.8 = creative. Set this with sourceImageIndex when the user explicitly requests Z-image/Z-image Turbo enhancement or any supported img2img starting-image workflow."
+              "description": "Image-to-image source guidance strength (0.0-1.0). Only set when a source image is available and the model supports img2img. For Z-Image/Z-Image Turbo, Krea 2 Turbo, or source-preserving enhancement requests, use 0.75 with sourceImageIndex so the source image remains a strong guide while allowing higher-resolution reconstruction. Use lower values only when the user explicitly asks for a lighter guide/subtle variation; higher values are more creative and can deviate further from the source."
             },
             "sourceImageIndex": {
               "type": "number",
@@ -282,7 +286,7 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
       "type": "function",
       "function": {
         "name": "edit_image",
-        "description": "Generate images guided by reference photos. Supports GPT Image 2 up to 16 images, Flux.2 up to 6 images, and Qwen up to 3 images. Best for style-guided generation, combining elements from multiple images, ANY persona image creation, and any uploaded brand asset reuse — logos, brand marks, mascots, product shots, photos, screenshots, sketches, or character designs the user expects to appear in or guide the result. ALWAYS use this (never generate_image) when persona photos OR uploaded image assets meant for reuse are in context — even if a specific model is requested. Exception: explicit Z-image/Z-image Turbo uploaded-image enhancement uses generate_image with sourceImageIndex and starting_image_strength because edit_image does not expose Z-image models. If a previous edit_image attempt did not preserve the uploaded asset well, stay on edit_image and tighten the prompt or switch model — do not fall back to generate_image, which has no access to the upload at all. For direct edits (remove objects, enhance), use restore_photo or refine_result unless the user explicitly requested Z-image.",
+        "description": "Generate images guided by reference photos. Supports GPT Image 2 up to 16 images, Flux.2 up to 6 images, Qwen up to 3 images, and Krea 2 Identity Edit / Dark Beast Krea 2 Identity Edit up to 2 images. Best for style-guided generation, combining elements from multiple images, ANY persona image creation, identity-preserving Krea edits, and any uploaded brand asset reuse — logos, brand marks, mascots, product shots, photos, screenshots, sketches, or character designs the user expects to appear in or guide the result. ALWAYS use this (never generate_image) when persona photos OR uploaded image assets meant for reuse are in context — even if a specific edit model is requested. Exception: explicit Z-image/Z-image Turbo/Krea 2 Turbo uploaded-image enhancement uses generate_image with sourceImageIndex and starting_image_strength because those base image-to-image models are not edit_image models. If a previous edit_image attempt did not preserve the uploaded asset well, stay on edit_image and tighten the prompt or switch model; generate_image has no access to the upload.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -296,9 +300,11 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
                 "gpt-image-2",
                 "qwen-lightning",
                 "qwen",
-                "flux2"
+                "flux2",
+                "krea-identity-edit",
+                "dark-beast-krea2-identity-edit"
               ],
-              "description": "DO NOT SET THIS PARAMETER unless the user names a specific edit model, asks for a very complex reference-guided image render, or asks for a video storyboard/storyboard sheet/contact sheet/panel layout image using references. The app auto-selects based on quality settings. Set \"gpt-image-2\" when the user asks for a ChatGPT, OpenAI, GPT, GPT-2, GPT Image, or gpt-image-2 reference-guided image/edit/model, or by default for complex single-image renders that need dense labels, crisp typography, multi-panel composition, timing notes, foley notes, professional storyboard-sheet layout, or a comprehensive character/mascot/model sheet with turnarounds, expressions, accessories, palette swatches, and brand notes. Z-image and Z-image Turbo are not edit_image models; route those explicit uploaded-image enhancement requests to generate_image with sourceImageIndex and starting_image_strength. If the user names another edit/image model, honor that requested model instead. GPT Image 2 always processes input images at high fidelity; do not set input_fidelity."
+              "description": "The app auto-selects Fast→Qwen Lightning, HQ→full Qwen, and Pro→Flux.2 only for ordinary identity-neutral edits. REQUIRED IDENTITY DEFAULT: set \"krea-identity-edit\" whenever an edit of a referenced person or character must keep likeness or character identity while changing clothing, hair or makeup, pose or position, face/head/body, background, lighting, or visual style. Infer that semantic intent in any language; never route from keyword or regex matching. Also use it for a non-Pro single-character sheet. This default applies even when the user did not name Krea; an explicitly requested model always wins. Set \"dark-beast-krea2-identity-edit\" only when the user explicitly requests that model, its uncensored/community variant, or dark_beast_krea2_identity_edit_v1_2. Set \"gpt-image-2\" when the user explicitly names GPT/OpenAI/ChatGPT Image, or when precise typography, dense labels, or a professional multi-panel layout is the primary requirement; Pro character sheets may retain GPT Image 2. If GPT Image 2 is unavailable for detail-critical layout work, fall back to full \"qwen\", never \"qwen-lightning\". Krea identity edit models require at least one reference image, accept up to two context images, and work best at 512-2048px. Let the model tier and worker choose current steps, guidance, sampler, scheduler, grounding, and reference-boost defaults; do not send a negative prompt. When Krea is selected, override the generic prompt-length guidance with a concise 1-4 sentence delta instruction; name only the requested change and details that must remain fixed. Put the base scene/image first and an optional person/detail reference second. Z-image, Z-image Turbo, and base Krea 2 Turbo are generate_image img2img models, not edit_image selectors. If the user names another edit/image model, honor it. GPT Image 2 always processes input images at high fidelity; do not set input_fidelity."
             },
             "sourceImageIndex": {
               "type": "number",
@@ -312,11 +318,11 @@ export const SOGNI_HOSTED_TOOLS_MANIFEST: unknown = {
             },
             "width": {
               "type": "number",
-              "description": "Output image width in pixels. Defaults to the context image width. Supported range is 256-2560 for Qwen/Flux.2 edit models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a width, exact pixel dimensions, or a named resolution (e.g., \"1280 wide\", \"1280x720\", \"720p\", \"3840x2160\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels."
+              "description": "Output image width in pixels. Defaults to the context image width. Supported bounds depend on the selected edit model: Qwen edit models support 256-2560 on either edge; Krea 2 Identity Edit and Dark Beast Krea 2 Identity Edit work best from 512-2048 on either edge; Flux.2 uses a 2048x2048 total pixel budget (4,194,304 pixels) with non-square edges up to 2816, such as 1408x2816; GPT Image 2 supports flexible dimensions up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400. Set when the user specifies a width, exact pixel dimensions, or a named resolution (e.g., \"1280 wide\", \"1280x720\", \"720p\", \"3840x2160\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels."
             },
             "height": {
               "type": "number",
-              "description": "Output image height in pixels. Defaults to the context image height. Supported range is 256-2560 for Qwen/Flux.2 edit models. For gpt-image-2, dimensions are flexible up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400; the renderer snaps to the nearest valid multiple-of-16 size. Set when the user specifies a height, exact pixel dimensions, or a named resolution (e.g., \"720 high\", \"1280x720\", \"720p\", \"2160x3840\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels."
+              "description": "Output image height in pixels. Defaults to the context image height. Supported bounds depend on the selected edit model: Qwen edit models support 256-2560 on either edge; Krea 2 Identity Edit and Dark Beast Krea 2 Identity Edit work best from 512-2048 on either edge; Flux.2 uses a 2048x2048 total pixel budget (4,194,304 pixels) with non-square edges up to 2816, such as 1408x2816; GPT Image 2 supports flexible dimensions up to 3840px on either edge with max 3:1 aspect ratio and a total pixel budget from 655,360 to 8,294,400. Set when the user specifies a height, exact pixel dimensions, or a named resolution (e.g., \"720 high\", \"1280x720\", \"720p\", \"2160x3840\"). If the user gives only one dimension, set only that dimension and preserve/infer the sensible aspect ratio. User-requested dimensions override the default media quality, including Pro. Non-multiple-of-16 values are accepted when in bounds; the renderer snaps to the nearest supported size internally, so do not ask the user to adjust by a few pixels."
             },
             "aspectRatio": {
               "type": "string",

package/src/Chat/index.ts

@@ -34,6 +34,8 @@ import {
 import getUUID from '../lib/getUUID.js';
 import type ProjectsApi from '../Projects/index.js';
 import { mediaInputToInlineDataUri } from '../lib/mediaValidation.js';
+import { workloadAttributionToWireFields } from '../lib/attribution.js';
+import type { WorkloadAttributionInput } from '../types/attribution.js';
 
 const MAX_VISION_IMAGE_COUNT = 20;
 const MAX_VISION_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -510,13 +512,15 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     const normalizedMessages = await normalizeVisionMessages(params.messages);
     const chatTemplateKwargs =
       params.chat_template_kwargs ?? this.buildChatTemplateKwargs(params.think);
+    const appSource = params.app_source ?? params.appSource ?? this.client.appSource;
+    const attributionHeaders = this.attributionHeaders(appSource, params.attribution, getUUID());
     try {
       return await this.client.rest.post<HostedChatCompletionResult>(
         '/v1/chat/completions',
         {
           model: params.model,
           messages: normalizedMessages,
-          app_source: params.app_source ?? params.appSource ?? this.client.appSource,
+          app_source: appSource,
           max_tokens: params.max_tokens,
           temperature: params.temperature,
           top_p: params.top_p,
@@ -541,7 +545,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
           ...(chatTemplateKwargs && { chat_template_kwargs: chatTemplateKwargs }),
           ...(params.response_format && { response_format: params.response_format })
         },
-        { timeoutMs: 300000 }
+        { timeoutMs: 300000, headers: attributionHeaders }
       );
     } catch (error) {
       // Re-throw recognized chat-job error bodies (e.g. subscription
@@ -569,18 +573,22 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
   private async executeHostedTool(
     params: HostedToolExecutionParams
   ): Promise<HostedToolExecutionResult> {
+    const appSource = params.app_source ?? params.appSource ?? this.client.appSource;
     return this.client.rest.post<HostedToolExecutionResult>(
       '/v1/creative-agent/tools/execute',
       {
         tool: params.tool,
         arguments: params.arguments,
-        app_source: params.app_source ?? params.appSource ?? this.client.appSource,
+        app_source: appSource,
         token_type: params.token_type ?? params.tokenType,
         ...(params.safe_content_filter !== undefined || params.safeContentFilter !== undefined
           ? { safe_content_filter: params.safe_content_filter ?? params.safeContentFilter }
           : {})
       },
-      { timeoutMs: 300000 }
+      {
+        timeoutMs: 300000,
+        headers: this.attributionHeaders(appSource, params.attribution, getUUID())
+      }
     );
   }
 
@@ -633,6 +641,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
   private async createChatRun(params: StartChatRunParams): Promise<ChatRunRecord> {
     assertChatRunUsesExternalMedia(params);
     const appSource = params.appSource ?? this.client.appSource;
+    const operationId = getUUID();
     const body: Record<string, unknown> = {
       messages: params.messages,
       ...(params.tools ? { tools: params.tools } : {}),
@@ -652,7 +661,10 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       ...(appSource ? { app_source: appSource } : {}),
       ...(params.runtimeConfig ? { runtime_config: params.runtimeConfig } : {})
     };
-    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.attributionHeaders(appSource, params.attribution, operationId)
+    };
     if (params.idempotencyKey) headers['Idempotency-Key'] = params.idempotencyKey;
     const response = await this.chatRunJson<{
       status: string;
@@ -828,7 +840,8 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       sogni_tool_execution: params.sogni_tool_execution,
       taskProfile: params.taskProfile,
       ...(chatTemplateKwargs && { chat_template_kwargs: chatTemplateKwargs }),
-      ...(params.response_format && { response_format: params.response_format })
+      ...(params.response_format && { response_format: params.response_format }),
+      ...workloadAttributionToWireFields(this.resolveWorkloadAttribution(params.attribution, jobID))
     };
 
     const stream = new ChatStream(jobID);
@@ -891,13 +904,18 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     const maxRounds = params.maxToolRounds || 5;
     const toolHistory: ToolHistoryEntry[] = [];
     let messages = [...params.messages];
+    const logicalOperation = this.resolveWorkloadAttribution(params.attribution, getUUID());
+    const autoToolChildAttribution = this.createAutoToolChildAttribution(logicalOperation);
 
     for (let round = 0; round < maxRounds; round++) {
       const result = (await this.createSingleCompletion({
         ...params,
         messages,
         stream: false,
-        autoExecuteTools: false
+        autoExecuteTools: false,
+        // The first LLM admission represents the logical auto-tool request.
+        // Later rounds and tool/media work are compute children of that root.
+        attribution: round === 0 ? logicalOperation : autoToolChildAttribution
       })) as ChatCompletionResult;
 
       // If model didn't request tools, return final result
@@ -911,6 +929,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       // Execute tool calls
       const toolResults = await this.tools.executeAll(result.tool_calls, {
         tokenType: params.tokenType,
+        attribution: autoToolChildAttribution,
         onToolCall: params.onToolCall,
         onToolProgress: params.onToolProgress
       });
@@ -942,6 +961,26 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     throw new Error(`Max tool calling rounds (${maxRounds}) exceeded`);
   }
 
+  /**
+   * Build attribution for compute spawned by one logical auto-tool operation.
+   * Each child receives its own transport operation ID while retaining the
+   * logical operation as its immediate parent.
+   */
+  private createAutoToolChildAttribution(
+    attribution: WorkloadAttributionInput | undefined
+  ): WorkloadAttributionInput | undefined {
+    const logicalOperation = this.resolveWorkloadAttribution(attribution, getUUID());
+    if (!logicalOperation?.operationId) return undefined;
+    const rootOperationId = logicalOperation.rootOperationId ?? logicalOperation.operationId;
+    return {
+      ...logicalOperation,
+      operationScope: 'child',
+      operationId: undefined,
+      rootOperationId,
+      parentOperationId: logicalOperation.operationId
+    };
+  }
+
   private handleJobTokens(data: JobTokensData): void {
     const stream = this.activeStreams.get(data.jobID);
     if (!stream) return;

package/src/Chat/types.ts

@@ -1,4 +1,5 @@
 import type { BillingMode } from '../Projects/types/index.js';
+import type { WorkloadAttributionInput } from '../types/attribution.js';
 
 export interface ToolFunction {
   name: string;
@@ -96,6 +97,8 @@ export interface ChatCompletionParams {
   messages: ChatMessage[];
   /** Optional source label for this request. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   max_tokens?: number;
   temperature?: number;
   top_p?: number;
@@ -181,7 +184,7 @@ export interface ChatCompletionParams {
   maxToolRounds?: number;
 }
 
-export interface ChatRequestMessage {
+export interface ChatRequestMessage extends WorkloadAttributionInput {
   jobID: string;
   type: 'llm';
   model: string;
@@ -295,6 +298,8 @@ export interface HostedToolExecutionParams {
   app_source?: string;
   /** camelCase alias for {@link HostedToolExecutionParams.app_source}. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** Token type to use for hosted REST billing. */
   token_type?: 'sogni' | 'spark' | 'auto';
   /** camelCase alias for {@link HostedToolExecutionParams.token_type}. */
@@ -457,6 +462,8 @@ export interface StartChatRunParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** Idempotency key (also accepted via `Idempotency-Key` header). */
   idempotencyKey?: string;
   /**
@@ -647,6 +654,8 @@ export interface ToolExecutionOptions {
   network?: 'fast' | 'relaxed';
   /** Number of media items to generate per tool call. Default: 1. */
   numberOfMedia?: number;
+  /** Optional workload attribution for media projects executed by the tool. */
+  attribution?: WorkloadAttributionInput;
   /** Progress callback fired during media generation. */
   onProgress?: (progress: ToolExecutionProgress) => void;
   /**

package/src/CreativeWorkflows/index.ts

@@ -16,6 +16,7 @@ import {
   StartCreativeWorkflowParams,
   StreamCreativeWorkflowEventsOptions
 } from './types.js';
+import getUUID from '../lib/getUUID.js';
 
 interface CreativeWorkflowEnvelope {
   workflow?: CreativeWorkflowRecord;
@@ -187,7 +188,8 @@ class CreativeWorkflowsApi extends ApiGroup {
     if (mediaReferences !== undefined) body.media_references = mediaReferences;
 
     const headers: Record<string, string> = {
-      'Content-Type': 'application/json'
+      'Content-Type': 'application/json',
+      ...this.attributionHeaders(appSource, params.attribution, getUUID())
     };
     if (idempotencyKey) {
       headers['Idempotency-Key'] = idempotencyKey;
@@ -226,7 +228,10 @@ class CreativeWorkflowsApi extends ApiGroup {
       `/v1/creative-agent/workflows/${encodeURIComponent(workflowId)}/resume`,
       {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.attributionHeaders(appSource, params.attribution, getUUID())
+        },
         body: JSON.stringify(body),
         signal: options.signal
       }
@@ -261,7 +266,10 @@ class CreativeWorkflowsApi extends ApiGroup {
       `/v1/creative-agent/workflows/${encodeURIComponent(workflowId)}/reseed`,
       {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.attributionHeaders(appSource, params.attribution, getUUID())
+        },
         body: JSON.stringify(body),
         signal: options.signal
       }

package/src/CreativeWorkflows/types.ts

@@ -1,5 +1,6 @@
 import { TokenType } from '../types/token.js';
 import type { BillingMode } from '../Projects/types/index.js';
+import type { WorkloadAttributionInput } from '../types/attribution.js';
 
 export type CreativeWorkflowStatus =
   | 'queued'
@@ -144,6 +145,8 @@ export interface StartCreativeWorkflowParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   idempotencyKey?: string;
   /** Durable workflows require uploaded HTTP(S) URLs, not inline data URIs. */
   mediaReferences?: unknown[];
@@ -174,6 +177,8 @@ export interface ResumeCreativeWorkflowParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** @internal Undocumented compatibility alias. Use tokenType. */
   token_type?: TokenType;
   /** @internal Undocumented compatibility alias. Use billingMode. */
@@ -203,6 +208,8 @@ export interface ReseedCreativeWorkflowParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** @internal Undocumented compatibility alias. Use seedOverrides. */
   seed_overrides?: Record<string, number>;
   /** @internal Undocumented compatibility alias. Use tokenType. */

package/src/Projects/createJobRequestMessage.ts

@@ -43,6 +43,7 @@ import {
   ModelOptions,
   VideoModelOptions
 } from './types/ModelOptions.js';
+import { workloadAttributionToWireFields } from '../lib/attribution.js';
 
 /**
  * Validate that the provided assets match the workflow requirements.
@@ -735,7 +736,9 @@ function createJobRequestMessage(id: string, params: ProjectParams, options: Mod
     tokenType: params.tokenType,
     billingMode: params.billingMode,
     outputFormat:
-      params.outputFormat || (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png')
+      params.outputFormat ||
+      (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png'),
+    ...workloadAttributionToWireFields(params.attribution)
   };
 
   if (params.network) {

package/src/Projects/index.ts

@@ -667,7 +667,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     const modelOptions = await this.getModelOptions(data.modelId);
     const requestParams = {
       ...data,
-      appSource: data.appSource || this.client.appSource
+      appSource: data.appSource || this.client.appSource,
+      attribution: this.resolveWorkloadAttribution(data.attribution, project.id)
     } as ProjectParams;
     const request = createJobRequestMessage(project.id, requestParams, modelOptions);
 

package/src/Projects/types/index.ts

@@ -1,6 +1,7 @@
 import { SupernetType } from '../../ApiClient/WebSocketClient/types.js';
 import { ControlNetParams, VideoControlNetParams } from './ControlNetParams.js';
 import { TokenType } from '../../types/token.js';
+import type { WorkloadAttributionInput } from '../../types/attribution.js';
 
 export interface SupportedModel {
   id: string;
@@ -99,6 +100,11 @@ export interface BaseProjectParams {
    * Optional client app/source label to attach to the project request for server-side attribution.
    */
   appSource?: string;
+  /**
+   * Optional workload attribution for this project. Fields override the
+   * immutable defaults configured on SogniClient.
+   */
+  attribution?: WorkloadAttributionInput;
   /**
    * LoRA IDs to apply, in the order they should be chained.
    *

package/src/index.ts

@@ -176,6 +176,20 @@ import {
   TokenAuthManager
 } from './lib/AuthManager/index.js';
 import { MeData } from './Account/types.js';
+import type {
+  AgentAttributionMetadata,
+  AgentSurface,
+  ConnectionAttribution,
+  ExecutionMode,
+  InteractionKind,
+  OperationLineage,
+  OperationScope,
+  SogniAttributionConfig,
+  WorkloadAttribution,
+  WorkloadAttributionDefaults,
+  WorkloadAttributionInput,
+  WorkloadKind
+} from './types/attribution.js';
 
 export type {
   AudioFormat,
@@ -313,7 +327,19 @@ export type {
   RawProject,
   ToastMessage,
   DataEntity,
-  InputMedia
+  InputMedia,
+  AgentAttributionMetadata,
+  AgentSurface,
+  ConnectionAttribution,
+  ExecutionMode,
+  InteractionKind,
+  OperationLineage,
+  OperationScope,
+  SogniAttributionConfig,
+  WorkloadAttribution,
+  WorkloadAttributionDefaults,
+  WorkloadAttributionInput,
+  WorkloadKind
 };
 
 export {
@@ -346,6 +372,13 @@ export interface SogniClientConfig {
    * The socket server uses this as the default source for project and chat requests from this client.
    */
   appSource?: string;
+  /**
+   * Optional immutable connection and per-workload attribution defaults.
+   *
+   * Individual project, chat, tool, and workflow calls can override workload
+   * fields without mutating other concurrent requests.
+   */
+  attribution?: SogniAttributionConfig;
   /**
    * Initial WebSocket event subscriptions for this connection.
    *
@@ -538,6 +571,7 @@ export class SogniClient {
       socketUrl: socketEndpoint,
       appId: config.appId,
       appSource: config.appSource,
+      attribution: config.attribution,
       socketEventSubscriptions: config.socketEventSubscriptions,
       networkType: network,
       logger,

package/src/lib/RestClient.ts

@@ -8,6 +8,11 @@ interface RestRequestInit extends RequestInit {
   timeoutMs?: number;
 }
 
+interface RestPostOptions {
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+}
+
 class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
   readonly baseUrl: string;
   protected _auth: AuthManager;
@@ -120,15 +125,17 @@ class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
   post<T = JSONValue>(
     path: string,
     body: Record<string, unknown> = {},
-    options: Pick<RestRequestInit, 'timeoutMs'> = {}
+    options: RestPostOptions = {}
   ): Promise<T> {
+    const { headers = {}, ...requestOptions } = options;
     return this.request<T>(this.formatUrl(path), {
       method: 'POST',
       headers: {
-        'Content-Type': 'application/json'
+        'Content-Type': 'application/json',
+        ...headers
       },
       body: JSON.stringify(body),
-      ...options
+      ...requestOptions
     });
   }
 }