@sogni-ai/sogni-client 5.2.0 → 5.3.1

package/dist-esm/lib/RestClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"RestClient.js","sourceRoot":"","sources":["../../src/lib/RestClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RestClient.js","sourceRoot":"","sources":["../../src/lib/RestClient.ts"],"names":[],"mappings":"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"}

package/dist-esm/lib/attribution.js

@@ -0,0 +1,257 @@
+const MAX_METADATA_LENGTH = 128;
+const MAX_VERSION_LENGTH = 32;
+const MAX_OPERATION_ID_LENGTH = 128;
+const UNSAFE_HEADER_CHARACTER = /[\u0000-\u001f\u007f]/;
+const VERSION_PATTERN = /^[0-9][0-9A-Za-z.+_-]*$/;
+const OPERATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const INTERACTION_KINDS = new Set([
+    'human_ui',
+    'external_agent',
+    'service',
+    'unknown'
+]);
+const WORKLOAD_KINDS = new Set(['direct', 'agent_mediated', 'service', 'unknown']);
+const OPERATION_SCOPES = new Set(['top_level', 'child', 'unknown']);
+const AGENT_SURFACES = new Set([
+    'native_web',
+    'native_mobile',
+    'native_desktop',
+    'plugin',
+    'personal_skill',
+    'mcp',
+    'cli',
+    'sdk',
+    'openai_compatible',
+    'direct_api',
+    'unknown'
+]);
+const EXECUTION_MODES = new Set(['browser', 'durable', 'server', 'unknown']);
+function normalizeEnum(value, allowed) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return allowed.has(normalized) ? normalized : undefined;
+}
+function normalizeBoundedString(value, maxLength) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    if (normalized.length === 0 ||
+        normalized.length > maxLength ||
+        UNSAFE_HEADER_CHARACTER.test(normalized)) {
+        return undefined;
+    }
+    return normalized;
+}
+function normalizeVersion(value) {
+    const normalized = normalizeBoundedString(value, MAX_VERSION_LENGTH);
+    return normalized && VERSION_PATTERN.test(normalized) ? normalized : undefined;
+}
+function normalizeOperationId(value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > MAX_OPERATION_ID_LENGTH ||
+        value.trim() !== value ||
+        UNSAFE_HEADER_CHARACTER.test(value) ||
+        !OPERATION_ID_PATTERN.test(value)) {
+        return undefined;
+    }
+    return value;
+}
+function normalizeAgentMetadata(input) {
+    if (!input || typeof input !== 'object')
+        return {};
+    const result = {};
+    const agentFramework = normalizeBoundedString(input.agentFramework, MAX_METADATA_LENGTH);
+    const agentFrameworkVersion = normalizeVersion(input.agentFrameworkVersion);
+    const agentSurface = normalizeEnum(input.agentSurface, AGENT_SURFACES);
+    const agentSurfaceVersion = normalizeVersion(input.agentSurfaceVersion);
+    const executionMode = normalizeEnum(input.executionMode, EXECUTION_MODES);
+    if (agentFramework)
+        result.agentFramework = agentFramework;
+    if (agentFrameworkVersion)
+        result.agentFrameworkVersion = agentFrameworkVersion;
+    if (agentSurface)
+        result.agentSurface = agentSurface;
+    if (agentSurfaceVersion)
+        result.agentSurfaceVersion = agentSurfaceVersion;
+    if (executionMode)
+        result.executionMode = executionMode;
+    return result;
+}
+function mergeDefined(defaults, overrides) {
+    const merged = Object.assign({}, (defaults !== null && defaults !== void 0 ? defaults : {}));
+    if (overrides && typeof overrides === 'object') {
+        const defaultValues = (defaults !== null && defaults !== void 0 ? defaults : {});
+        const overrideValues = overrides;
+        for (const [key, value] of Object.entries(overrides)) {
+            if (value !== undefined)
+                merged[key] = value;
+        }
+        // A version belongs to its framework/surface. Do not accidentally retain
+        // one default's version when a request changes the corresponding identity.
+        if (overrideValues.agentFramework !== undefined &&
+            overrideValues.agentFramework !== defaultValues.agentFramework &&
+            overrideValues.agentFrameworkVersion === undefined) {
+            delete merged.agentFrameworkVersion;
+        }
+        if (overrideValues.agentSurface !== undefined &&
+            overrideValues.agentSurface !== defaultValues.agentSurface &&
+            overrideValues.agentSurfaceVersion === undefined) {
+            delete merged.agentSurfaceVersion;
+        }
+    }
+    return merged;
+}
+function hasValues(value) {
+    return Object.keys(value).length > 0;
+}
+export function normalizeConnectionAttribution(input) {
+    if (!input || typeof input !== 'object')
+        return undefined;
+    const result = normalizeAgentMetadata(input);
+    const interactionKind = normalizeEnum(input.interactionKind, INTERACTION_KINDS);
+    if (interactionKind)
+        result.interactionKind = interactionKind;
+    return hasValues(result) ? result : undefined;
+}
+/**
+ * Merge immutable client defaults with one operation's overrides and add
+ * lineage derived from the underlying request ID. Invalid runtime values are
+ * dropped instead of rejecting an otherwise valid inference request.
+ */
+export function resolveWorkloadAttribution(defaults, overrides, fallbackOperationId) {
+    if (!defaults && !overrides)
+        return undefined;
+    const merged = mergeDefined(defaults, overrides);
+    const result = normalizeAgentMetadata(merged);
+    const workloadKind = normalizeEnum(merged.workloadKind, WORKLOAD_KINDS);
+    const operationScope = normalizeEnum(merged.operationScope, OPERATION_SCOPES);
+    const operationId = normalizeOperationId(merged.operationId);
+    const rootOperationId = normalizeOperationId(merged.rootOperationId);
+    const parentOperationId = normalizeOperationId(merged.parentOperationId);
+    if (workloadKind)
+        result.workloadKind = workloadKind;
+    if (operationScope)
+        result.operationScope = operationScope;
+    if (operationId)
+        result.operationId = operationId;
+    if (rootOperationId)
+        result.rootOperationId = rootOperationId;
+    if (parentOperationId)
+        result.parentOperationId = parentOperationId;
+    if (result.workloadKind && result.workloadKind !== 'agent_mediated') {
+        delete result.agentFramework;
+        delete result.agentFrameworkVersion;
+    }
+    // Do not turn an empty/invalid attribution object into attributed traffic
+    // solely because the transport happens to have a request ID.
+    if (!hasValues(result))
+        return undefined;
+    if (!result.operationId) {
+        const fallback = normalizeOperationId(fallbackOperationId);
+        if (fallback)
+            result.operationId = fallback;
+    }
+    if (result.operationId && !result.operationScope) {
+        result.operationScope =
+            result.parentOperationId ||
+                (result.rootOperationId && result.rootOperationId !== result.operationId)
+                ? 'child'
+                : 'top_level';
+    }
+    if (result.operationScope === 'child' && result.rootOperationId && !result.parentOperationId) {
+        result.parentOperationId = result.rootOperationId;
+    }
+    if (result.operationScope === 'top_level' && result.operationId) {
+        result.rootOperationId = result.operationId;
+        delete result.parentOperationId;
+    }
+    return result;
+}
+/** Add flat camelCase connection attribution fields to a WebSocket URL. */
+export function appendConnectionAttributionQuery(url, attribution) {
+    if (!attribution)
+        return;
+    const fields = [
+        'interactionKind',
+        'agentFramework',
+        'agentFrameworkVersion',
+        'agentSurface',
+        'agentSurfaceVersion',
+        'executionMode'
+    ];
+    for (const field of fields) {
+        const value = attribution[field];
+        if (typeof value === 'string')
+            url.searchParams.set(field, value);
+    }
+}
+/** Return flat camelCase workload fields for socket request payloads. */
+export function workloadAttributionToWireFields(attribution) {
+    if (!attribution)
+        return {};
+    const result = {};
+    for (const field of [
+        'workloadKind',
+        'agentFramework',
+        'agentFrameworkVersion',
+        'agentSurface',
+        'agentSurfaceVersion',
+        'executionMode',
+        'operationScope',
+        'operationId',
+        'rootOperationId',
+        'parentOperationId'
+    ]) {
+        const value = attribution[field];
+        if (typeof value === 'string')
+            result[field] = value;
+    }
+    return result;
+}
+/**
+ * Build headers only for requests whose caller has already established that
+ * the destination is a Sogni-owned endpoint.
+ */
+export function buildSogniAttributionHeaders({ appSource, connection, workload }) {
+    const headers = {};
+    const normalizedAppSource = normalizeBoundedString(appSource, MAX_METADATA_LENGTH);
+    if (normalizedAppSource)
+        headers['X-App-Source'] = normalizedAppSource;
+    if (connection === null || connection === void 0 ? void 0 : connection.interactionKind) {
+        headers['X-Sogni-Interaction-Kind'] = connection.interactionKind;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.workloadKind) {
+        headers['X-Sogni-Workload-Kind'] = workload.workloadKind;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.agentFramework) {
+        headers['X-Sogni-Agent-Framework'] = workload.agentFramework;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.agentFrameworkVersion) {
+        headers['X-Sogni-Agent-Framework-Version'] = workload.agentFrameworkVersion;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.agentSurface) {
+        headers['X-Sogni-Agent-Surface'] = workload.agentSurface;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.agentSurfaceVersion) {
+        headers['X-Sogni-Agent-Surface-Version'] = workload.agentSurfaceVersion;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.executionMode) {
+        headers['X-Sogni-Execution-Mode'] = workload.executionMode;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.operationScope) {
+        headers['X-Sogni-Operation-Scope'] = workload.operationScope;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.operationId) {
+        headers['X-Sogni-Operation-Id'] = workload.operationId;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.rootOperationId) {
+        headers['X-Sogni-Root-Operation-Id'] = workload.rootOperationId;
+    }
+    if (workload === null || workload === void 0 ? void 0 : workload.parentOperationId) {
+        headers['X-Sogni-Parent-Operation-Id'] = workload.parentOperationId;
+    }
+    return headers;
+}
+//# sourceMappingURL=attribution.js.map

package/dist-esm/lib/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/lib/attribution.ts"],"names":[],"mappings":"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"}

package/dist-esm/types/attribution.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attribution.js.map

package/dist-esm/types/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/types/attribution.ts"],"names":[],"mappings":""}

package/dist-esm/version.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED by scripts/generate-version.mjs — do not edit.
 // Source of truth: package.json version.
-export const LIB_VERSION = '5.2.0';
+export const LIB_VERSION = '5.3.1';
 //# sourceMappingURL=version.js.map

package/llms-full.txt

@@ -254,6 +254,33 @@ const portal = await sogni.account.createSubscriptionPortalSession();
 
 `checkAuth()` is only for cookie-auth browser flows on permitted Sogni domains. API-key auth auto-authenticates during `createInstance()`. Username/password auth uses `sogni.account.login()`. Token auth can be resumed with `sogni.setTokens()`.
 
+AGENT ATTRIBUTION:
+
+Keep `appSource` as the stable product/integration identifier. Agent wrappers may add immutable `attribution.connection` and `attribution.workload` defaults:
+
+```typescript
+const sogni = await SogniClient.createInstance({
+  appId: 'my-agent',
+  appSource: 'my-agent-integration',
+  apiKey: process.env.SOGNI_API_KEY,
+  attribution: {
+    connection: {
+      interactionKind: 'external_agent',
+      agentFramework: 'codex',
+      agentSurface: 'plugin'
+    },
+    workload: {
+      workloadKind: 'agent_mediated',
+      agentFramework: 'codex',
+      agentSurface: 'plugin',
+      executionMode: 'server'
+    }
+  }
+});
+```
+
+Project, socket chat, hosted chat/tool, durable chat run, and creative workflow calls accept an optional per-operation `attribution` override. Standalone attributed requests default to `operationScope: 'top_level'` and use the underlying project/job request ID. For child work, pass `operationScope: 'child'`, a stable `rootOperationId`, and the immediate `parentOperationId`; omit `operationId` to use the request's generated ID. The exported attribution types include `native_desktop`. Invalid metadata is dropped, the server remains authoritative, and all new wire fields are omitted when attribution is not configured.
+
 NETWORK TYPES:
 
 - 'fast': High-end GPU workers. Faster, higher cost. REQUIRED for video.

package/llms.txt

@@ -140,6 +140,10 @@ const portal = await sogni.account.createSubscriptionPortalSession();
 
 Checkout and portal sessions require user authentication; API-key auth is rejected for those redirect operations.
 
+AGENT ATTRIBUTION:
+
+Keep `appSource` as the stable product/integration ID. Agent wrappers may additionally set immutable `attribution.connection` and `attribution.workload` defaults on `createInstance()`, then override `attribution` per project, socket/hosted/durable chat request, hosted tool, or creative workflow. Exported unions cover `interactionKind`, `workloadKind`, `agentSurface` (including `native_desktop`), `executionMode`, and operation lineage. Standalone attributed calls receive a top-level operation ID from the underlying job/request; child calls should provide `operationScope: 'child'`, `rootOperationId`, and `parentOperationId`. All fields are optional and omitted for legacy callers.
+
 ### Network Types
 
 - `fast` - High-end GPUs, faster, more expensive. **Required for video.**

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "5.2.0",
+  "version": "5.3.1",
   "engines": {
     "node": ">=22"
   },
@@ -61,6 +61,7 @@
     "prepublishOnly": "npm run build",
     "build": "npm run clean && npm run codegen && tsc --project tsconfig.json && tsc --project tsconfig.esm.json && node scripts/write-dist-esm-package-json.mjs",
     "test:chat-routing": "npm run build && node scripts/check-chat-model-routing.cjs",
+    "test:attribution": "npm run build && node scripts/check-attribution-transport.cjs",
     "test:subscription-api": "npm run build && node scripts/check-subscription-api.cjs",
     "test:workflow-template-envelope": "npm run build && node scripts/check-workflow-template-envelope.cjs",
     "watch": "npm run clean && npm run codegen && tsc --watch --project tsconfig.json",
@@ -84,7 +85,7 @@
   "homepage": "https://github.com/Sogni-AI/sogni-client#readme",
   "dependencies": {
     "@lukeed/uuid": "^2.0.1",
-    "@sogni-ai/sogni-protocol": "1.0.0-alpha.9",
+    "@sogni-ai/sogni-protocol": "1.0.0-alpha.10",
     "@types/js-cookie": "^3.0.6",
     "@types/lodash": "^4.17.23",
     "@types/ws": "^8.5.13",

package/src/ApiClient/WebSocketClient/BrowserWebSocketClient/index.ts

@@ -14,6 +14,7 @@ import type {
   SocketEventSubscriptionInput,
   SocketEventSubscriptions
 } from '../eventSubscriptions.js';
+import type { NormalizedConnectionAttribution } from '../../../lib/attribution.js';
 
 interface SocketSend<T extends MessageType = MessageType> {
   type: 'socket-send';
@@ -114,7 +115,8 @@ class BrowserWebSocketClient extends RestClient<SocketEventMap> implements IWebS
     supernetType: SupernetType,
     logger: Logger,
     appSource?: string,
-    socketEventSubscriptions?: SocketEventSubscriptions
+    socketEventSubscriptions?: SocketEventSubscriptions,
+    connectionAttribution?: NormalizedConnectionAttribution
   ) {
     const socketClient = new WrappedClient(
       baseUrl,
@@ -123,7 +125,8 @@ class BrowserWebSocketClient extends RestClient<SocketEventMap> implements IWebS
       supernetType,
       logger,
       appSource,
-      socketEventSubscriptions
+      socketEventSubscriptions,
+      connectionAttribution
     );
     super(socketClient.baseUrl, auth, logger);
     this.socketClient = socketClient;

package/src/ApiClient/WebSocketClient/index.ts

@@ -16,6 +16,11 @@ import type {
   SocketEventSubscriptionInput,
   SocketEventSubscriptions
 } from './eventSubscriptions.js';
+import {
+  appendConnectionAttributionQuery,
+  normalizeConnectionAttribution,
+  type NormalizedConnectionAttribution
+} from '../../lib/attribution.js';
 
 const PROTOCOL_VERSION = '3.0.0';
 
@@ -24,6 +29,7 @@ const PING_INTERVAL = 15000;
 class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketClient {
   appId: string;
   appSource?: string;
+  connectionAttribution?: NormalizedConnectionAttribution;
   baseUrl: string;
   socketEventSubscriptions?: SocketEventSubscriptions;
   private socket: WebSocket | null = null;
@@ -37,7 +43,8 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     supernetType: SupernetType,
     logger: Logger,
     appSource?: string,
-    socketEventSubscriptions?: SocketEventSubscriptions
+    socketEventSubscriptions?: SocketEventSubscriptions,
+    connectionAttribution?: NormalizedConnectionAttribution
   ) {
     const _baseUrl = new URL(baseUrl);
     switch (_baseUrl.protocol) {
@@ -55,6 +62,7 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     super(_baseUrl.toString(), auth, logger);
     this.appId = appId;
     this.appSource = appSource?.trim() || undefined;
+    this.connectionAttribution = normalizeConnectionAttribution(connectionAttribution);
     this.socketEventSubscriptions = socketEventSubscriptions;
     this.baseUrl = _baseUrl.toString();
     this._supernetType = supernetType;
@@ -87,6 +95,7 @@ class WebSocketClient extends RestClient<SocketEventMap> implements IWebSocketCl
     if (this.appSource) {
       url.searchParams.set('appSource', this.appSource);
     }
+    appendConnectionAttributionQuery(url, this.connectionAttribution);
     const socketEventSubscriptions = serializeSocketEventSubscriptions(
       this.socketEventSubscriptions
     );

package/src/ApiClient/index.ts

@@ -16,6 +16,17 @@ import CookieAuthManager from '../lib/AuthManager/CookieAuthManager.js';
 import { AuthManager, TokenAuthManager } from '../lib/AuthManager/index.js';
 import isNodejs from '../lib/isNodejs.js';
 import BrowserWebSocketClient from './WebSocketClient/BrowserWebSocketClient/index.js';
+import {
+  buildSogniAttributionHeaders,
+  normalizeConnectionAttribution,
+  resolveWorkloadAttribution,
+  type NormalizedConnectionAttribution
+} from '../lib/attribution.js';
+import type {
+  SogniAttributionConfig,
+  WorkloadAttributionDefaults,
+  WorkloadAttributionInput
+} from '../types/attribution.js';
 
 const WS_RECONNECT_ATTEMPTS = 5;
 
@@ -46,6 +57,7 @@ export interface ApiClientOptions {
   socketUrl: string;
   appId: string;
   appSource?: string;
+  attribution?: SogniAttributionConfig;
   socketEventSubscriptions?: SocketEventSubscriptions;
   networkType: SupernetType;
   logger: Logger;
@@ -57,6 +69,10 @@ export interface ApiClientOptions {
 class ApiClient extends TypedEventEmitter<ApiClientEvents> {
   readonly appId: string;
   readonly appSource?: string;
+  readonly attribution: Readonly<{
+    connection?: Readonly<NormalizedConnectionAttribution>;
+    workload?: Readonly<WorkloadAttributionDefaults>;
+  }>;
   readonly logger: Logger;
   private _rest: RestClient;
   private _socket: IWebSocketClient;
@@ -69,6 +85,7 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
     socketUrl,
     appId,
     appSource,
+    attribution,
     socketEventSubscriptions,
     networkType,
     authType,
@@ -79,6 +96,11 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
     super();
     this.appId = appId;
     this.appSource = appSource?.trim() || undefined;
+    const connectionAttribution = normalizeConnectionAttribution(attribution?.connection);
+    this.attribution = Object.freeze({
+      ...(connectionAttribution ? { connection: Object.freeze(connectionAttribution) } : {}),
+      ...(attribution?.workload ? { workload: Object.freeze({ ...attribution.workload }) } : {})
+    });
     this.logger = logger;
     if (authType === 'apiKey') {
       this._auth = new ApiKeyAuthManager(logger);
@@ -98,7 +120,8 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
         networkType,
         logger,
         this.appSource,
-        socketEventSubscriptions
+        socketEventSubscriptions,
+        this.attribution.connection
       );
     } else {
       this._socket = new WebSocketClient(
@@ -108,7 +131,8 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
         networkType,
         logger,
         this.appSource,
-        socketEventSubscriptions
+        socketEventSubscriptions,
+        this.attribution.connection
       );
     }
     this._disableSocket = disableSocket;
@@ -137,6 +161,22 @@ class ApiClient extends TypedEventEmitter<ApiClientEvents> {
     return !this._disableSocket;
   }
 
+  resolveWorkloadAttribution(override?: WorkloadAttributionInput, fallbackOperationId?: string) {
+    return resolveWorkloadAttribution(this.attribution.workload, override, fallbackOperationId);
+  }
+
+  attributionHeaders(
+    appSource: string | undefined,
+    override?: WorkloadAttributionInput,
+    fallbackOperationId?: string
+  ): Record<string, string> {
+    return buildSogniAttributionHeaders({
+      appSource,
+      connection: this.attribution.connection,
+      workload: this.resolveWorkloadAttribution(override, fallbackOperationId)
+    });
+  }
+
   setSocketEventSubscriptions(update: SocketEventSubscriptionInput): Promise<void> {
     return this.socket.setSocketEventSubscriptions(update);
   }

package/src/ApiGroup.ts

@@ -1,6 +1,8 @@
 import ApiClient from './ApiClient/index.js';
 import EIP712Helper from './lib/EIP712Helper.js';
 import TypedEventEmitter, { EventMap } from './lib/TypedEventEmitter.js';
+import { buildSogniAttributionHeaders, resolveWorkloadAttribution } from './lib/attribution.js';
+import type { WorkloadAttributionInput } from './types/attribution.js';
 
 export interface ApiConfig {
   client: ApiClient;
@@ -16,6 +18,29 @@ abstract class ApiGroup<E extends EventMap = {}> extends TypedEventEmitter<E> {
     this.client = config.client;
     this.eip712 = config.eip712;
   }
+
+  protected resolveWorkloadAttribution(
+    override?: WorkloadAttributionInput,
+    fallbackOperationId?: string
+  ) {
+    return resolveWorkloadAttribution(
+      this.client.attribution?.workload,
+      override,
+      fallbackOperationId
+    );
+  }
+
+  protected attributionHeaders(
+    appSource: string | undefined,
+    override?: WorkloadAttributionInput,
+    fallbackOperationId?: string
+  ): Record<string, string> {
+    return buildSogniAttributionHeaders({
+      appSource,
+      connection: this.client.attribution?.connection,
+      workload: this.resolveWorkloadAttribution(override, fallbackOperationId)
+    });
+  }
 }
 
 export default ApiGroup;

package/src/Chat/ChatTools.ts

@@ -155,6 +155,7 @@ class ChatToolsApi {
           tokenType: options?.tokenType,
           network: options?.network,
           numberOfMedia: options?.numberOfMedia,
+          attribution: options?.attribution,
           timeout: options?.timeout,
           onProgress: options?.onToolProgress
             ? (progress: ToolExecutionProgress) => options.onToolProgress!(toolCall, progress)
@@ -213,7 +214,10 @@ class ChatToolsApi {
   ): Promise<ToolExecutionResult> {
     options?.onProgress?.({ status: 'creating', percent: 0 });
 
-    const project = await this.projects.create(projectParams as any);
+    const project = await this.projects.create({
+      ...projectParams,
+      ...(options?.attribution ? { attribution: options.attribution } : {})
+    } as any);
     const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
     let timeoutId: ReturnType<typeof setTimeout> | null = null;
     let jobsCompleted = 0;