@x12i/ai-gateway 9.0.9 → 9.1.1

package/dist/activity-manager.js

@@ -4,7 +4,7 @@
  * Manages activity tracking for LLM requests.
  * Wraps the ActivityTracker and provides convenience methods.
  */
-import { Activix, activixActivityIo, activixOuterTier } from '@x12i/activix';
+import { Activix, activixActivityIo, activixOuterTier, resolveActivixLogsDatabaseName, resolveActivixMongoUriFromEnv } from '@x12i/activix';
 import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 function readAiRequestIdFromRequest(request) {
@@ -161,6 +161,17 @@ function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
     merged.aiRequestId = aiRequestId;
     merged.jobId = upstreamJobId;
     merged.taskId = upstreamTaskId;
+    // gateway.invoke (AIInvokeRequest): request root is canonical for Activix runContext.
+    if ('actionType' in request && 'actionRef' in request) {
+        const inv = request;
+        if (inv.actionType) {
+            merged.actionType = inv.actionType;
+        }
+        const ref = typeof inv.actionRef === 'string' ? inv.actionRef.trim() : '';
+        if (ref) {
+            merged.actionRef = ref;
+        }
+    }
     return merged;
 }
 /**
@@ -259,12 +270,37 @@ export class ActivityManager {
                         }
                     }
                 });
-                this.initPromise = this.activix.init().catch((error) => {
-                    // MongoDB config not available - log warning but don't throw.
-                    // This allows tests and development to work without MongoDB.
-                    this.logger.warn('Activity tracking enabled but MongoDB configuration not available. Activity records will not be persisted.', {
+                this.initPromise = this.activix
+                    .init()
+                    .then(() => {
+                    const ax = this.activix;
+                    if (!ax) {
+                        return;
+                    }
+                    const backend = ax.storageBackend;
+                    const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
+                    const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
+                    this.logger.info('Activity tracking persistence backend ready', {
+                        storageBackend: backend,
+                        mongoDatabase: mongoDb,
+                        mongoUriConfigured,
+                        mainCollection: collectionName,
+                        badRequestsCollection: badRequestsCollectionName,
+                        skillExecutionsCollection: this.skillExecutionsCollectionName,
+                        ...(backend === 'local'
+                            ? {
+                                note: 'Activix is using local playground storage, not MongoDB. The ai-actions collection will not appear in Mongo until URI is set (MONGO_URI or MONGO_LOGS_URI), Activix can ping the database, and at least one activity is written.'
+                            }
+                            : {
+                                note: 'MongoDB stores one document per activity; the ai-actions collection is created on first insert (empty collections may be hidden in some tools until then).'
+                            })
+                    });
+                })
+                    .catch((error) => {
+                    // Init threw — disable tracker so requests are not blocked.
+                    this.logger.warn('Activity tracking enabled but Activix init failed. Activity records will not be persisted.', {
                         error: error instanceof Error ? error.message : String(error),
-                        hint: 'Set MONGO_URI and MONGO_LOGS_DB (or MONGO_DB) environment variables to enable activity tracking persistence'
+                        hint: 'Set MONGO_URI or MONGO_LOGS_URI and a database name (MONGO_LOGS_DB, MONGO_DB, MONGO_AI_LOGS_DB, or ACTIVIX_DB_NAME). See README: Activity tracking / persistence troubleshooting.'
                     });
                     this.activix = undefined;
                 });
@@ -343,6 +379,8 @@ export class ActivityManager {
             startTime,
             status: 'started',
             activityType: 'gateway-invocation',
+            ...(identity.actionType !== undefined && { actionType: identity.actionType }),
+            ...(identity.actionRef !== undefined && identity.actionRef !== '' && { actionRef: identity.actionRef }),
             // Activix v5+: correlation BSON field is `runContext` (same object as `request.identity`)
             runContext: identity
             // Removed root-level fields per v2.3.2:
@@ -557,6 +595,8 @@ export class ActivityManager {
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',
+            ...(identity.actionType !== undefined && { actionType: identity.actionType }),
+            ...(identity.actionRef !== undefined && identity.actionRef !== '' && { actionRef: identity.actionRef }),
             runContext: identity,
             ...(instructionMetadata.key && { instructionKey: instructionMetadata.key }),
             ...(instructionMetadata.version && { instructionVersion: instructionMetadata.version }),

package/dist/config/activity-tracking-config.d.ts

@@ -1,6 +1,7 @@
 /**
  * Centralized activity tracking configuration.
- * Single source of truth for package-level collection names.
+ * Package-level Mongo collection names are fixed literals here (no env override).
+ * Main gateway rows: `ai-actions`; bad requests: `bad-requests` (see constants below).
  */
 export interface ActivityTrackingConfig {
     mongoUri: string;

package/dist/config/activity-tracking-config.js

@@ -1,8 +1,9 @@
 /**
  * Centralized activity tracking configuration.
- * Single source of truth for package-level collection names.
+ * Package-level Mongo collection names are fixed literals here (no env override).
+ * Main gateway rows: `ai-actions`; bad requests: `bad-requests` (see constants below).
  */
-const ACTIVITY_COLLECTION_NAME = 'ai-activities';
+const ACTIVITY_COLLECTION_NAME = 'ai-actions';
 const BAD_REQUESTS_COLLECTION_NAME = 'bad-requests';
 export function resolveActivityTrackingConfig() {
     // Collection names are intentionally hardcoded at package level.

package/dist/gateway-memory.d.ts

@@ -10,7 +10,6 @@ type Request = ChatRequest | AIRequest;
  * Merges existing workingMemory (from request or memory component) with request metadata
  *
  * Implements tiered token resolution:
- * - Tier 1 (highest): templateTokens (handled in resolveTemplateParams, merged into shortTermMemory)
  * - Tier 2: workingMemory (this method) - checks existing workingMemory first
  * - Tier 3: derived from request fields or other memories (fallback)
  */
@@ -27,7 +26,7 @@ export declare function buildWorkingMemory(request: Request, existingWorkingMemo
 }): unknown;
 /**
  * Resolves template parameters with smart fallback logic
- * Priority: Request args (tier 1) -> Memory component (tier 2) -> Gateway config (tier 3) -> defaults
+ * Priority: request.workingMemory -> memoryManager resolution -> buildWorkingMemory merge
  */
 export declare function resolveTemplateParams(request: Request, config: GatewayConfig, logger: Logxer): Promise<{
     workingMemory: unknown;

package/dist/gateway-memory.js

@@ -14,7 +14,6 @@ function isAIRequest(request) {
  * Merges existing workingMemory (from request or memory component) with request metadata
  *
  * Implements tiered token resolution:
- * - Tier 1 (highest): templateTokens (handled in resolveTemplateParams, merged into shortTermMemory)
  * - Tier 2: workingMemory (this method) - checks existing workingMemory first
  * - Tier 3: derived from request fields or other memories (fallback)
  */
@@ -34,7 +33,6 @@ export function buildWorkingMemory(request, existingWorkingMemory, otherMemories
     }
     /**
      * Token Resolution with Tiered Fallback
-     * Tier 1: templateTokens (handled in resolveTemplateParams, merged into shortTermMemory)
      * Tier 2: workingMemory (check existing workingMemory first)
      * Tier 3: derive from request fields or other memories
      */
@@ -138,7 +136,7 @@ export function buildWorkingMemory(request, existingWorkingMemory, otherMemories
 }
 /**
  * Resolves template parameters with smart fallback logic
- * Priority: Request args (tier 1) -> Memory component (tier 2) -> Gateway config (tier 3) -> defaults
+ * Priority: request.workingMemory -> memoryManager resolution -> buildWorkingMemory merge
  */
 export async function resolveTemplateParams(request, config, logger) {
     // Tier 1: Request args (highest priority)
@@ -189,19 +187,7 @@ export async function resolveTemplateParams(request, config, logger) {
     // Build proper workingMemory structure (merge with request fields if needed)
     // This implements tiered token resolution: tier 2 (workingMemory) and tier 3 (derive from request fields)
     const finalWorkingMemory = buildWorkingMemory(request, workingMemory);
-    // Merge templateTokens (tier 1 - highest priority) into shortTermMemory AFTER memory resolution
-    // This ensures templateTokens override everything (workingMemory and other memories)
-    // Rendrix priority: shortTermMemory > workingMemory > experienceMemory > knowledgeMemory
-    if (request.templateTokens && Object.keys(request.templateTokens).length > 0) {
-        logger?.debug('Merged templateTokens into shortTermMemory (tier 1 - highest priority)', {
-            jobId: request.identity.jobId,
-            tokenKeys: Object.keys(request.templateTokens)
-        });
-    }
-    // Note: taskConfig removed - Rendrix 3.0.0+ no longer accepts it
-    // taskConfig is deprecated and no longer used
     return {
         workingMemory: finalWorkingMemory
-        // taskConfig removed - Rendrix 3.0.0+ no longer uses it
     };
 }

package/dist/gateway-meta.js

@@ -27,8 +27,11 @@ export async function testInstructions(instructions, testInput, expectedSchema,
     const testRequest = {
         aiRequestId,
         agentId,
+        actionType: 'skill',
+        actionRef: 'gateway-meta/test-instructions',
         instructions,
         identity: runtimeIdentity,
+        prompt: '{{input}}',
         workingMemory: { input: testInput },
         config: {
             model,

package/dist/gateway-utils.d.ts

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { ChatRequest, GatewayConfig } from './types.js';
+import type { ChatRequest, GatewayConfig, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -21,7 +21,7 @@ export declare function mergeConfig(request: ChatRequest & {
 }, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;
 /**
  * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
- * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, Responses-style input/output tokens, and missing total (sum prompt+completion).
  */
 export declare function normalizeRouterUsageTokens(usage: unknown): {
     prompt: number;
@@ -30,6 +30,7 @@ export declare function normalizeRouterUsageTokens(usage: unknown): {
 } | undefined;
 /**
  * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ * Prefers the raw/provider body (`rawResponse` / `raw`) when it carries non-zero usage before re-reading the outer envelope.
  */
 export declare function extractTokenUsageFromRouterResponse(routerResponse: unknown): {
     prompt: number;
@@ -42,3 +43,24 @@ export declare function extractTokenUsageFromRouterResponse(routerResponse: unkn
  * Does not compute cost from tokens — adapters must populate normalized fields or raw usage.cost-style keys.
  */
 export declare function extractCostUsdFromRouterResponse(routerResponse: unknown): number | undefined;
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+export declare function pickInvokeRoutingMetadataSlice(routerResponse: unknown, mergedConfig: unknown): Partial<{
+    provider: string;
+    modelUsed: string;
+    maxTokensRequested: number;
+    region: string;
+}>;
+/**
+ * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
+ */
+export declare function pickEffectiveModelConfigForMetadata(mergedConfig: unknown): Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>> | undefined;
+/** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
+export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
+/**
+ * Size-cap a provider/router payload before storing on an activity record.
+ * Non-serializable values become a small marker object instead of throwing.
+ */
+export declare function capActivityFullResponsePayload(payload: unknown, maxChars?: number): unknown;

package/dist/gateway-utils.js

@@ -183,53 +183,90 @@ function firstFiniteNumber(...vals) {
     for (const v of vals) {
         if (typeof v === 'number' && Number.isFinite(v))
             return v;
+        if (typeof v === 'string' && v.trim() !== '') {
+            const n = Number(v);
+            if (Number.isFinite(n))
+                return n;
+        }
     }
     return undefined;
 }
+function isNonZeroTokenCount(n) {
+    return !!(n.prompt || n.completion || n.total);
+}
 /**
  * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
- * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, Responses-style input/output tokens, and missing total (sum prompt+completion).
  */
 export function normalizeRouterUsageTokens(usage) {
     if (usage == null || typeof usage !== 'object')
         return undefined;
     const u = usage;
-    const prompt = firstFiniteNumber(u.promptTokens, u.inputTokens, u.prompt, u.prompt_tokens) ?? 0;
-    const completion = firstFiniteNumber(u.completionTokens, u.outputTokens, u.completion, u.completion_tokens) ?? 0;
-    let total = firstFiniteNumber(u.totalTokens, u.total_tokens) ?? 0;
+    const prompt = firstFiniteNumber(u.promptTokens, u.inputTokens, u.input_tokens, u.prompt, u.prompt_tokens) ?? 0;
+    const completion = firstFiniteNumber(u.completionTokens, u.outputTokens, u.output_tokens, u.completion, u.completion_tokens) ?? 0;
+    let total = firstFiniteNumber(u.totalTokens, u.total_tokens, u.total) ?? 0;
     if (!total && (prompt || completion))
         total = prompt + completion;
     return { prompt, completion, total };
 }
 /**
- * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ * Collect usage from one router/provider envelope (single object).
+ * When followRaw is true, also reads `(rawResponse ?? raw).usage` on that envelope.
  */
-export function extractTokenUsageFromRouterResponse(routerResponse) {
-    if (routerResponse == null || typeof routerResponse !== 'object') {
-        return { prompt: 0, completion: 0, total: 0 };
-    }
-    const r = routerResponse;
-    const meta = r.metadata != null && typeof r.metadata === 'object'
-        ? r.metadata
+function collectUsageBucketsFromRoot(root, followRaw) {
+    const meta = root.metadata != null && typeof root.metadata === 'object'
+        ? root.metadata
         : undefined;
-    const buckets = [r.usage];
+    const buckets = [root.usage];
     if (meta) {
         buckets.push(meta.usage);
+        buckets.push(meta.tokens);
         const nested = meta['ai-activities-response'];
         if (nested != null && typeof nested === 'object') {
             buckets.push(nested.usage);
         }
     }
-    const raw = r.rawResponse ?? r.raw;
-    if (raw != null && typeof raw === 'object') {
-        buckets.push(raw.usage);
+    if (followRaw) {
+        const raw = root.rawResponse ?? root.raw;
+        if (raw != null && typeof raw === 'object') {
+            buckets.push(raw.usage);
+        }
     }
+    return buckets;
+}
+function firstNonZeroUsageFromBuckets(buckets) {
     for (const b of buckets) {
         const n = normalizeRouterUsageTokens(b);
-        if (n && (n.prompt || n.completion || n.total))
+        if (n && isNonZeroTokenCount(n))
             return n;
     }
-    return { prompt: 0, completion: 0, total: 0 };
+    return undefined;
+}
+/**
+ * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ * Prefers the raw/provider body (`rawResponse` / `raw`) when it carries non-zero usage before re-reading the outer envelope.
+ */
+export function extractTokenUsageFromRouterResponse(routerResponse) {
+    const zeros = { prompt: 0, completion: 0, total: 0 };
+    if (routerResponse == null || typeof routerResponse !== 'object') {
+        return zeros;
+    }
+    const r = routerResponse;
+    const raw = r.rawResponse ?? r.raw;
+    const inner = raw != null && typeof raw === 'object' ? raw : undefined;
+    const roots = inner != null && inner !== r
+        ? [
+            { root: inner, followRaw: false },
+            { root: r, followRaw: true }
+        ]
+        : [{ root: r, followRaw: true }];
+    for (const { root, followRaw } of roots) {
+        const buckets = collectUsageBucketsFromRoot(root, followRaw);
+        const found = firstNonZeroUsageFromBuckets(buckets);
+        if (found)
+            return found;
+    }
+    return zeros;
 }
 /**
  * Best-effort USD cost from router/sync AIResponse shape: metadata.costUsd (preferred),
@@ -278,3 +315,70 @@ export function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+export function pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig) {
+    const rr = routerResponse != null && typeof routerResponse === 'object' ? routerResponse : {};
+    const meta = rr.metadata != null && typeof rr.metadata === 'object' ? rr.metadata : {};
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object' ? mergedConfig : {};
+    const provider = meta.provider || rr.provider || cfg.provider;
+    const modelUsed = meta.modelUsed || meta.model || rr.model || cfg.model;
+    const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
+        ? meta.maxTokensRequested
+        : typeof cfg.maxTokens === 'number'
+            ? cfg.maxTokens
+            : undefined;
+    const region = typeof meta.region === 'string' ? meta.region : undefined;
+    const out = {};
+    if (provider !== undefined && provider !== null)
+        out.provider = provider;
+    if (modelUsed !== undefined && modelUsed !== null)
+        out.modelUsed = modelUsed;
+    if (maxTokensRequested !== undefined)
+        out.maxTokensRequested = maxTokensRequested;
+    if (region !== undefined)
+        out.region = region;
+    return out;
+}
+/**
+ * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
+ */
+export function pickEffectiveModelConfigForMetadata(mergedConfig) {
+    if (mergedConfig == null || typeof mergedConfig !== 'object')
+        return undefined;
+    const c = mergedConfig;
+    const keys = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+    const out = {};
+    for (const k of keys) {
+        const v = c[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
+export const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512_000;
+/**
+ * Size-cap a provider/router payload before storing on an activity record.
+ * Non-serializable values become a small marker object instead of throwing.
+ */
+export function capActivityFullResponsePayload(payload, maxChars = DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS) {
+    if (payload == null)
+        return payload;
+    let serialized;
+    try {
+        serialized = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    }
+    catch {
+        return { _truncated: true, _reason: 'not_serializable' };
+    }
+    if (serialized.length <= maxChars)
+        return payload;
+    return {
+        _truncated: true,
+        _originalCharLength: serialized.length,
+        _preview: serialized.slice(0, maxChars)
+    };
+}

package/dist/gateway-validation.d.ts

@@ -2,12 +2,12 @@
  * Gateway Validation Module
  * Basic validation for clean proxy implementation
  */
-import type { ChatRequest, AIRequest } from './types.js';
+import type { ChatRequest, AIInvokeRequest } from './types.js';
 /**
  * Validates ChatRequest has required fields
  */
 export declare function validateChatRequest(request: ChatRequest): void;
 /**
- * Validates AIRequest has required fields
+ * Validates AIInvokeRequest has required fields
  */
-export declare function validateAIRequest(request: AIRequest): void;
+export declare function validateAIRequest(request: AIInvokeRequest): void;

package/dist/gateway-validation.js

@@ -32,8 +32,9 @@ export function validateChatRequest(request) {
         throw err;
     }
 }
+const GATEWAY_ACTION_TYPES = ['skill', 'preSkill', 'postSkill'];
 /**
- * Validates AIRequest has required fields
+ * Validates AIInvokeRequest has required fields
  */
 export function validateAIRequest(request) {
     if (!request.aiRequestId) {
@@ -43,6 +44,14 @@ export function validateAIRequest(request) {
         throw new Error('agentId is required for AI requests');
     }
     validateMandatoryRuntimeIdentity(request);
+    if (!request.actionType ||
+        !GATEWAY_ACTION_TYPES.includes(request.actionType)) {
+        throw new Error(`actionType is required and must be one of: ${GATEWAY_ACTION_TYPES.join(', ')}`);
+    }
+    const ref = typeof request.actionRef === 'string' ? request.actionRef.trim() : '';
+    if (!ref) {
+        throw new Error('actionRef is required and must be a non-empty string');
+    }
     // Reject input field - it has been removed
     if ('input' in request && request.input !== undefined) {
         const err = new Error(`The 'input' field has been removed. Use workingMemory.input instead for template rendering. Prompt templates should contain {{input}} which will be resolved from workingMemory.input.`);

package/dist/gateway.d.ts

@@ -4,7 +4,7 @@
  * Simplified AI Gateway - Clean proxy implementation
  */
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
-import type { GatewayConfig, ChatRequest, AIRequest, EnhancedLLMResponse } from './types.js';
+import type { GatewayConfig, ChatRequest, AIInvokeRequest, EnhancedLLMResponse } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { ActivityManager } from './activity-manager.js';
 /**
@@ -25,7 +25,7 @@ export declare class AIGateway {
     /**
      * Invoke AI request (with structured output support)
      */
-    invoke<TContent = unknown>(request: AIRequest): Promise<EnhancedLLMResponse<TContent>>;
+    invoke<TContent = unknown>(request: AIInvokeRequest): Promise<EnhancedLLMResponse<TContent>>;
     /**
      * Build simple messages from request (instructions and prompt as literal template text; no registry).
      */

package/dist/gateway.js

@@ -8,7 +8,7 @@ import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
-import { extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig } from './gateway-utils.js';
+import { capActivityFullResponsePayload, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice } from './gateway-utils.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
@@ -513,9 +513,19 @@ export class AIGateway {
             }
             contentType = 'structured';
             parsingMethod = 'flex-md';
-            const tokens = extractTokenUsageFromRouterResponse(routerResponse);
+            let tokens = extractTokenUsageFromRouterResponse(routerResponse);
+            if (!(tokens.prompt || tokens.completion || tokens.total)) {
+                const alt = routerResponse?.rawResponse ?? routerResponse?.raw;
+                if (alt != null && typeof alt === 'object' && alt !== routerResponse) {
+                    const second = extractTokenUsageFromRouterResponse(alt);
+                    if (second.prompt || second.completion || second.total)
+                        tokens = second;
+                }
+            }
             const resolvedCostUsd = extractCostUsdFromRouterResponse(routerResponse);
             const routerMetaForCost = routerResponse?.metadata || {};
+            const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+            const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -528,6 +538,8 @@ export class AIGateway {
                     agentType: 'ai',
                     contentType,
                     parsingMethod,
+                    ...routingMetadataSlice,
+                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
                     ...(typeof resolvedCostUsd === 'number'
                         ? {
                             costUsd: resolvedCostUsd,
@@ -537,38 +549,32 @@ export class AIGateway {
                         }
                         : {}),
                     ...(traceEnabled
-                        ? (() => {
-                            const meta = routerResponse?.metadata || {};
-                            const provider = meta.provider || routerResponse?.provider || mergedConfig?.provider;
-                            const region = typeof meta.region === 'string' ? meta.region : undefined;
-                            const modelUsed = meta.modelUsed || meta.model || routerResponse?.model || mergedConfig?.model;
-                            const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
-                                ? meta.maxTokensRequested
-                                : typeof mergedConfig?.maxTokens === 'number'
-                                    ? mergedConfig.maxTokens
-                                    : undefined;
-                            return {
-                                provider,
-                                region,
-                                modelUsed,
-                                maxTokensRequested,
-                                requestIds: traceRequestIds,
-                                retryCount: traceRetryCount,
-                                fallbackCount: traceFallbackCount,
-                                attempts: traceAttempts
-                            };
-                        })()
+                        ? {
+                            requestIds: traceRequestIds,
+                            retryCount: traceRetryCount,
+                            fallbackCount: traceFallbackCount,
+                            attempts: traceAttempts
+                        }
                         : {})
                 }
             };
             // Track activity success if activity was started
             if (activity) {
                 try {
+                    const diag = request.diagnostics;
+                    const includeFullProviderBlob = diag?.includeFullProviderResponseInActivity !== false;
+                    const maxFullChars = typeof diag?.activityFullResponseMaxChars === 'number' && diag.activityFullResponseMaxChars > 0
+                        ? diag.activityFullResponseMaxChars
+                        : DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS;
+                    const rawFull = routerResponse.rawResponse || routerResponse;
+                    const fullResponseForActivity = includeFullProviderBlob
+                        ? capActivityFullResponsePayload(rawFull, maxFullChars)
+                        : undefined;
                     // Create activity response with proper structure for ActivityTracker
                     const activityResponse = {
                         content: {
                             rawContent: content, // Store the actual response content as rawContent
-                            fullResponse: routerResponse.rawResponse || routerResponse // Include full router response
+                            ...(fullResponseForActivity !== undefined ? { fullResponse: fullResponseForActivity } : {})
                         },
                         parsed: parsedContent, // Include parsed content in activity record
                         metadata: enhancedResponse.metadata,

package/dist/index.d.ts

@@ -16,11 +16,11 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIRequest, EnhancedLLMResponse, InstructionMetadata, ValidationRule, ResponseTransformationConfig, TemplateRenderOptions } from './types.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions } from './types.js';
 export { mergeTemplateRenderOptions } from './template-render-merge.js';
 export type { UsageTier } from './types.js';
 export { Activix } from '@x12i/activix';
-export type { ActivixRunContext, FindByRunContextCriteria } from '@x12i/activix';
+export type { ActivixRunContext, FindByRunContextCriteria, GetJobActivitiesInput, GetJobActivitiesResult } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';

package/dist/instruction-optimizer.js

@@ -139,8 +139,11 @@ export async function optimizeInstructions(gateway, originalInstructions, option
     const optimizationRequest = {
         aiRequestId,
         agentId,
+        actionType: 'skill',
+        actionRef: 'internal/instruction-optimizer',
         instructions: INSTRUCTION_OPTIMIZER_INSTRUCTIONS + additionalContext,
         identity,
+        prompt: '{{input}}',
         workingMemory: { input: originalInstructions },
         config: {
             model,

package/dist/runtime-objects.d.ts

@@ -1,17 +1,6 @@
 import type { Logxer } from '@x12i/logxer';
-import type { Activix } from '@x12i/activix';
-export type ActivixQueryableClient = {
-    getJobActivities(input: {
-        jobId: string;
-        graphId?: string;
-        nodeId?: string;
-        limit?: number;
-    }): Promise<{
-        jobId: string;
-        graphRun?: unknown;
-        activities: unknown[];
-    }>;
-};
+import type { Activix, ActivixQueryableClient } from '@x12i/activix';
+export type { ActivixQueryableClient } from '@x12i/activix';
 export type LogxerQueryableClient = {
     getJobLogs(input: {
         jobId: string;

package/dist/troubleshooting-helper.d.ts

@@ -57,9 +57,6 @@ export interface DiagnosticInfo {
         validationErrors?: string[];
     };
 }
-/**
- * Validates AIRequest structure
- */
 export declare function validateAIRequest(request: Partial<AIRequest>): ValidationResult;
 /**
  * Validates JSON string