@exellix/ai-skills 5.8.0

package/dist/types.d.ts

@@ -0,0 +1,534 @@
+import type { AIGateway, GatewayInvokeRejectionMetadata, SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from "@x12i/ai-gateway";
+import { JobHistory, TaskHistory } from "@x12i/execution-memory-manager";
+import type { Catalox } from "@x12i/catalox";
+import type { RuntimeIdentity } from "@x12i/logxer";
+import type { AiEngineCatalogItemId } from "./catalox/ai-engines-catalog.js";
+import type { OutputContract } from "./utils/normalize-output-parsed.js";
+export type { AiEngineCatalogItemId };
+export type { SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from "@x12i/ai-gateway";
+/**
+ * Graph-engine / ai-tasks execution-scoped template buckets (graph-engine 5.13+ compile contract).
+ * Job scope: {@link SkillExecutionMemory.jobVariables} (also mirrored in {@link RunSkillRequest.variables}).
+ * Node scope: {@link SkillExecutionMemory.taskVariables} only — never folded into `variables`.
+ */
+export interface SkillExecutionMemory {
+    jobVariables?: Record<string, unknown>;
+    taskVariables?: Record<string, unknown>;
+}
+/**
+ * Mirrors `@x12i/ai-gateway` invoke `diagnostics` shape (the gateway tarball types include it but the package root does not re-export it).
+ */
+export type GatewayInvokeDiagnosticsMode = "none" | "trace";
+export interface GatewayInvokeDiagnosticsOptions {
+    mode?: GatewayInvokeDiagnosticsMode;
+    /** When true, implementations must size-cap any raw payload included. */
+    includeRawProviderPayload?: boolean;
+    /** When false, Activix activity completion may omit large provider blobs. */
+    includeFullProviderResponseInActivity?: boolean;
+    /** Max serialized length for `fullResponse` on activity records when included. */
+    activityFullResponseMaxChars?: number;
+}
+export type { RuntimeIdentity };
+/**
+ * Matches gateway `templateTokens`: highest-priority values merged into short-term memory before render.
+ */
+export type GatewayTemplateTokens = {
+    [key: string]: string | number | boolean | object | object[];
+};
+/**
+ * Short skill id matching Catalox native catalog `data.skillKey` for app `ai-skills`.
+ * Prefer {@link listAiSkillsCatalogItems} (or your own Catalox query) for the authoritative list.
+ */
+export type CatalogSkillKey = string;
+export interface SkillMetadata {
+    id: CatalogSkillKey;
+    version: string;
+    type: "primary";
+    outputType: string;
+    requiredVariables: string[];
+    optionalVariables: string[];
+    outputSchema: Record<string, any>;
+}
+/**
+ * Model configuration for skill execution.
+ *
+ * Controls which model is used and how it generates responses.
+ * This configuration is passed through to the gateway for model selection and parameter control.
+ */
+export interface ModelConfig {
+    /**
+     * Model identifier (e.g., "gpt-4-turbo", "claude-3-opus", "gpt-3.5-turbo")
+     * If not specified, uses gateway/router default
+     */
+    model?: string;
+    /**
+     * Model ID (alternative to model name, for provider-specific model IDs)
+     */
+    modelId?: string;
+    /**
+     * Provider name (e.g., "openai", "anthropic")
+     * If not specified, uses client default provider
+     */
+    provider?: string;
+    /**
+     * Temperature for generation (0.0 to 2.0)
+     * Controls randomness in responses
+     */
+    temperature?: number;
+    /**
+     * Maximum tokens to generate
+     */
+    maxTokens?: number;
+    /**
+     * Top-p (nucleus) sampling parameter (0.0 to 1.0)
+     */
+    topP?: number;
+    /**
+     * Frequency penalty (-2.0 to 2.0)
+     */
+    frequencyPenalty?: number;
+    /**
+     * Presence penalty (-2.0 to 2.0)
+     */
+    presencePenalty?: number;
+    /**
+     * Stop sequences (array of strings)
+     * Generation stops when any stop sequence is encountered
+     */
+    stop?: string[];
+    /**
+     * Additional provider-specific parameters
+     */
+    [key: string]: any;
+}
+/**
+ * Allowlisted slice from `@x12i/ai-gateway` **`metadata.effectiveModelConfig`** (≥9.1.1), produced by
+ * **`pickEffectiveModelConfigForMetadata(mergedConfig)`** — not a full merged config dump.
+ */
+export type EffectiveModelConfigSlice = Partial<Pick<ModelConfig, "model" | "modelId" | "provider" | "temperature" | "maxTokens" | "topP">>;
+/** Skill invocation diagnostics: default = no trace payload. */
+export type ExecutionMode = "default" | "trace";
+/**
+ * Per-request diagnostics switches. Trace payloads are only built when
+ * {@link RunSkillRequest.executionMode} is `"trace"` or {@link SkillDiagnosticsInputOptions.includeDebugTrace} is true.
+ */
+export interface SkillDiagnosticsInputOptions {
+    /**
+     * Alternative to `executionMode: "trace"` (orchestrators may send either).
+     * When true, same effect as `executionMode: "trace"`.
+     */
+    includeDebugTrace?: boolean;
+    /**
+     * Separate opt-in for a small, size-capped raw provider payload snippet on the trace object.
+     * Default: no raw payload.
+     */
+    includeRawProviderPayload?: boolean;
+}
+/** Stable routing slice for a gateway/provider LLM call. */
+export interface SkillTraceRouting {
+    provider: string;
+    region?: string;
+    retryCount: number;
+    fallbackCount?: number;
+    /** Stable keys for correlation (gateway vs provider request ids when available). */
+    requestIds: {
+        gatewayAiRequestId?: string;
+        routerRequestId?: string;
+        providerActivityRequestId?: string;
+        [key: string]: string | undefined;
+    };
+}
+/**
+ * Why USD `costUsd` is absent on {@link RunSkillResponse.metadata} when usage exists.
+ * Gateway ≥9.3 uses `metadata.costStatus: "priced" | "unpriced"`; this SDK maps `priced` → `costUsd` only.
+ */
+export type SkillCostStatus = "unpriced" | "deferred";
+/** Normalized usage for an LLM call. */
+export interface SkillTraceUsage {
+    maxTokensRequested?: number;
+    tokensPrompt: number;
+    tokensCompletion: number;
+    tokensTotal: number;
+    cachedTokensPrompt?: number;
+    cachedTokensTotal?: number;
+}
+export interface SkillTraceStepIdentity {
+    /** e.g. `"main"` for the skill gateway call. */
+    phase: string;
+    /** e.g. `"runSkill"`, `"gatewayExecute"`. */
+    type: string;
+    /** Stable id, e.g. `skills:gateway`. */
+    stepId: string;
+}
+/** One ordered unit of work (retry, fallback chain hop, or single successful call). */
+export interface SkillTraceAttempt {
+    step: SkillTraceStepIdentity;
+    timing: {
+        startedAt: string;
+        endedAt: string;
+        durationMs: number;
+    };
+    routing: SkillTraceRouting;
+    usage: SkillTraceUsage;
+    costUsd?: number;
+    /** Present when {@link costUsd} is absent but usage exists or gateway marked async pricing. */
+    costStatus?: SkillCostStatus;
+    /** Effective model after routing/defaults (empty string if unknown). */
+    modelUsed: string;
+    ok: boolean;
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Caller-supplied slice of the gateway `invoke` request reflected into traces (trace mode only).
+ * Lets operators see exactly what was forwarded (e.g. `modelConfig.maxTokens`, `temperature`) without the original request object.
+ */
+export interface SkillDiagnosticsInvokeRequest {
+    /** Verbatim {@link RunSkillRequest.modelConfig} when set on the request. */
+    modelConfig?: ModelConfig;
+    /** Same as {@link RunSkillRequest.timeoutMs} when set (gateway `exec.timeoutMs`). */
+    timeoutMs?: number;
+    /** Gateway `invoke` classification (this SDK uses `skill` for {@link RunSkillRequest}). */
+    actionType?: "skill" | "preSkill" | "postSkill";
+    /** Same as {@link RunSkillRequest.skillKey} on `actionRef` for this client path. */
+    actionRef?: string;
+    /** Resolved {@link RunSkillRequest.aiEngineId} (always **`ai-gateway`** in this package). */
+    aiEngineId?: AiEngineCatalogItemId;
+    /** Echo {@link RunSkillRequest.smartInput} when set (gateway Rendrix shorthand). */
+    smartInput?: SmartInputConfig;
+    /** Echo {@link RunSkillRequest.smartInputRenderOptions} when set. */
+    smartInputRenderOptions?: SmartInputRenderOptions;
+}
+/**
+ * Structured trace for one gateway-backed skill execution.
+ * Present only when trace mode is enabled on the request.
+ */
+export interface SkillDiagnosticsTrace {
+    step: SkillTraceStepIdentity;
+    timing: {
+        startedAt: string;
+        endedAt: string;
+        durationMs: number;
+    };
+    routing: SkillTraceRouting;
+    usage: SkillTraceUsage;
+    costUsd?: number;
+    costStatus?: SkillCostStatus;
+    modelUsed: string;
+    ok: boolean;
+    error?: {
+        name: string;
+        message: string;
+    };
+    /** Ordered attempts (retries, fallbacks); includes the successful unit last when applicable. */
+    attempts: SkillTraceAttempt[];
+    /**
+     * Alias of {@link SkillDiagnosticsTrace.attempts} for orchestrators mapping `debugTrace.tasks`.
+     * Same array reference as `attempts`.
+     */
+    tasks: SkillTraceAttempt[];
+    /** Present only when {@link SkillDiagnosticsInputOptions.includeRawProviderPayload} is true. */
+    rawProviderPayload?: string;
+    /** Echo of invoke-time args this SDK sent toward the gateway (when any are present). */
+    invokeRequest?: SkillDiagnosticsInvokeRequest;
+    /**
+     * When **`ok === false`**, normalized **`GatewayInvokeRejectionMetadata`** from the thrown gateway error
+     * (`@x12i/ai-gateway` ≥9.1.2), if present — same contract as **`(error as Error & { metadata?: ... }).metadata`**.
+     */
+    invokeRejection?: GatewayInvokeRejectionMetadata;
+}
+export interface RunSkillDiagnostics {
+    trace: SkillDiagnosticsTrace;
+}
+export interface RunSkillRequest {
+    /**
+     * Catalox **`ai-skills`** catalog path (e.g. `skills/professional-answer`). Used **only** in this SDK to
+     * load template bodies from Firestore and for logging / correlation. It is **not** sent to
+     * `gateway.invoke()` as `instructions` or `prompt`; those fields receive **full template text** from Catalox
+     * (after `ensureGatewayTreatsAsTemplateText`), never the skill key as a registry lookup token.
+     * **`AIGateway` does not and must not resolve skill keys** for this client; key handling stays here + Catalox.
+     */
+    skillKey: string;
+    /**
+     * Catalox **`ai-engines`** catalog item id (listed for discovery; only **`ai-gateway`** is supported).
+     * Omitted, blank, or **`ai-gateway`** → **`@x12i/ai-gateway`** `invoke` with inline Catalox templates (Rendrix in the gateway).
+     */
+    aiEngineId?: AiEngineCatalogItemId;
+    input: Record<string, any> | string;
+    /**
+     * **Runtime** correlation envelope for this invoke only (from your app / upstream at request time).
+     * This is **not** {@link ExellixSkillsClientOptions client constructor configuration}, not static
+     * package or deployment metadata, and not derived from `.env` unless **you** put those values here.
+     *
+     * **Naming vs Activix:** On `gateway.invoke()` the field is **`identity`** (see `@x12i/ai-gateway` `ActivityIdentity`).
+     * When activities are persisted, Activix v5+ stores the **same** envelope under BSON **`runContext`** — the gateway
+     * performs that mapping. Do **not** rename this property to `runContext` here; pass **`identity`** on requests and
+     * read **`identity`** (or resolved metadata) on responses unless downstream explicitly documents otherwise.
+     *
+     * **`{@link RunSkillRequest.agentId}`**, **`{@link RunSkillRequest.jobTypeId}`**, and **`{@link RunSkillRequest.taskTypeId}`**
+     * are mandatory on every {@link RunSkillRequest}; this SDK forwards them on `gateway.invoke` and merges them into `identity` for Activix.
+     * Activix-oriented: receive from upstream and forward; flat work-scope fields
+     * (`jobId`, `taskId`, `skillId`, graph ids, …) should accumulate and stay stable.
+     * **Correlation:** {@link jobId} and {@link taskId} are required on every {@link RunSkillRequest}; they are
+     * sent on the gateway invoke payload as top-level fields and **always** merged into `identity` so
+     * `@x12i/ai-gateway` v9+ can validate Activix linkage (`identity.jobId` / `identity.taskId` are authoritative there)
+     * and classifies each `invoke()` with mandatory **`actionType`** / **`actionRef`** (this SDK sends `skill` + {@link RunSkillRequest.skillKey}).
+     * Baseline for correlation is typically `sessionId` (see session-id contract); `instance`
+     * is optional. When you omit `identity`, this SDK still sends at least `{ jobId, taskId, agentId, jobTypeId, taskTypeId }`
+     * (plus gateway enrichment) to the gateway; when you pass `identity`, fields are shallow-merged with resolved
+     * `jobId` / `taskId` and mandatory linkage ids from the request winning. It may set
+     * `skillId` on the clone if absent—never mints `sessionId` or overwrites ids you supplied.
+     * Top-level {@link sessionId} must match `identity.sessionId` when both are set.
+     */
+    identity?: Record<string, any>;
+    /**
+     * **Runtime** logical run / session id for Activix and related correlation (upstream-owned).
+     * Forwarded as a top-level gateway field when set; never generated by this SDK.
+     * If `identity.sessionId` is also set, both values must agree.
+     */
+    sessionId?: string;
+    /**
+     * Job / graph-scope template variables from upstream compile (`RunTaskRequest.variables` passthrough).
+     * Rendrix paths `variables.*` resolve here only. Node-scope values belong in
+     * {@link executionMemory.taskVariables}, not this bag.
+     */
+    variables?: Record<string, any>;
+    /**
+     * Execution-scoped template buckets from graph-engine 5.13+ / ai-tasks `RunTaskRequest.executionMemory`.
+     * Merged into gateway `workingMemory` as a non-flattened root `{ executionMemory: … }`. Template paths
+     * `executionMemory.jobVariables.*` and `executionMemory.taskVariables.*` resolve here.
+     */
+    executionMemory?: SkillExecutionMemory;
+    context?: Record<string, any> | string;
+    knowledge?: Record<string, any>;
+    jobMemory?: JobHistory;
+    taskMemory?: TaskHistory;
+    /**
+     * Upstream job correlation id. Required on every invoke; forwarded as gateway top-level `jobId`
+     * for Activix (this SDK never generates a value when omitted or blank — use {@link identity} only
+     * if your pipeline already stores ids there; resolution for the gateway prefers these top-level fields).
+     */
+    jobId: string;
+    /**
+     * Upstream task correlation id within the job. Required on every invoke; forwarded as gateway
+     * top-level `taskId` for Activix. Never auto-generated here.
+     */
+    taskId: string;
+    /**
+     * Agent identifier for Activix / gateway top-level `agentId` (and gateway defaults for `identity.instance`).
+     * Mandatory on every invoke; forwarded verbatim from the upstream skills request — this SDK does **not**
+     * substitute a package or deployment id when omitted.
+     */
+    agentId: string;
+    skillId?: string;
+    masterSkillId?: string;
+    masterSkillActivityId?: string;
+    /**
+     * Graph execution context: Identifier for the graph execution context.
+     * Automatically mapped to identity.graphId in activity tracking.
+     * Alternative to masterSkillId for graph-based workflows.
+     */
+    graphId?: string;
+    /**
+     * Graph execution context: Identifier for the specific node being executed.
+     * Automatically mapped to identity.nodeId in activity tracking.
+     * Alternative to skillId or coreSkillId for graph-based workflows.
+     */
+    nodeId?: string;
+    /**
+     * Graph execution context: Alternative node identifier for graph execution.
+     * Automatically mapped to identity.nodeId in activity tracking.
+     * Priority: skillId > coreSkillId > nodeId
+     */
+    coreSkillId?: string;
+    /**
+     * Graph execution context: Previous node identifier for flow tracking.
+     * Automatically mapped to identity.prevNodeId in activity tracking.
+     * Used to track the execution flow between nodes in a graph.
+     */
+    prevNodeId?: string;
+    /**
+     * Graph execution context: Alternative field name for previous node identifier.
+     * Automatically mapped to identity.prevNodeId in activity tracking.
+     * Alias for {@link RunSkillRequest.prevNodeId}.
+     */
+    previousNodeId?: string;
+    timeoutMs?: number;
+    /**
+     * Forwarded **verbatim** on `gateway.invoke({ modelConfig })` when set (single object assignment—no field stripping).
+     * Use per call for dynamic values (e.g. `maxTokens`, `temperature`, `model`). Omitted fields are left to `@x12i/ai-gateway` / provider defaults.
+     */
+    modelConfig?: ModelConfig;
+    /**
+     * Per-invocation overrides for `@x12i/rendrix` (merged on gateway defaults). See {@link TemplateRenderOptions}.
+     */
+    templateRenderOptions?: TemplateRenderOptions;
+    /**
+     * Smart Input paths for Rendrix `{{smartInput}}` (gateway request shorthand).
+     * Merged after gateway `templateRendering` and before {@link RunSkillRequest.templateRenderOptions}; nested
+     * `templateRenderOptions.smartInput` wins when both are set (same as `@x12i/ai-gateway`).
+     */
+    smartInput?: SmartInputConfig;
+    /**
+     * Rendering controls for Smart Input markdown (gateway request shorthand).
+     * Merged the same way as {@link smartInput}; nested `templateRenderOptions.smartInputRenderOptions` wins when both are set.
+     */
+    smartInputRenderOptions?: SmartInputRenderOptions;
+    /**
+     * Optional tokens with highest overlay priority during template render (gateway merges into short-term memory).
+     */
+    templateTokens?: GatewayTemplateTokens;
+    /**
+     * When `"trace"`, the client may attach {@link RunSkillResponse.diagnostics} with structured LLM diagnostics.
+     * Default / omitted: same behavior and payload size as non-trace invokes (no trace object).
+     */
+    executionMode?: ExecutionMode;
+    /**
+     * Optional diagnostics flags (trace mode). See {@link SkillDiagnosticsInputOptions}.
+     * Controls **this SDK’s** structured {@link RunSkillResponse.diagnostics} / `debugTrace` payloads only.
+     */
+    diagnostics?: SkillDiagnosticsInputOptions;
+    /**
+     * Recurring job type id (gateway top-level `jobTypeId` and Activix `identity.jobTypeId` / runContext).
+     * Mandatory on every invoke; forwarded verbatim on `gateway.invoke`.
+     */
+    jobTypeId: string;
+    /**
+     * Recurring task type id (gateway top-level `taskTypeId` and Activix `identity.taskTypeId` / runContext).
+     * Mandatory on every invoke; forwarded verbatim on `gateway.invoke`.
+     */
+    taskTypeId: string;
+    /**
+     * Gateway agent classification (`agentType` on invoke); optional passthrough to `@x12i/ai-gateway`.
+     */
+    agentType?: "chat" | "ai-reasoner" | "ai-auditor" | "ai-scoper" | "ai-discovery" | "ai-planner" | "ai-executor";
+    /**
+     * Gateway-native diagnostics (storage / provider payload gates on the gateway).
+     * Distinct from {@link diagnostics}: when trace mode is on, this SDK merges defaults
+     * (`mode: 'trace'`, raw payload flag aligned with {@link SkillDiagnosticsInputOptions.includeRawProviderPayload})
+     * unless you override them here.
+     */
+    gatewayDiagnostics?: GatewayInvokeDiagnosticsOptions;
+    /**
+     * Graph / studio output contract: keys expected on `parsed` / `outer.output.parsed`
+     * (e.g. `shortAnswer`, `fullAnswer`). When set, this SDK fills missing keys from FlexMD payloads
+     * and markdown section headings before returning and patching the Activix activity row.
+     */
+    outputContract?: OutputContract;
+}
+export interface RunSkillResponse<TParsed = any> {
+    /** Same catalog path as the request’s {@link RunSkillRequest.skillKey}; for app correlation, not gateway template payload. */
+    skillKey: string;
+    rawText: string;
+    flexMd: {
+        frame: string;
+        payloads: Record<string, string>;
+    };
+    parsed: TParsed;
+    /**
+     * **Runtime** gateway/downstream correlation envelope after this invoke (if any)—the live
+     * **`identity`** object for chaining (Activix-persisted twin is **`runContext`** in stored records only).
+     * Prefer forwarding this whole object to later steps so `sessionId`, `instance`, and extensions stay aligned.
+     * Omitted when downstream does not supply it.
+     */
+    identity?: Record<string, any>;
+    metadata: {
+        /** Gateway / activity metadata when present—not the Catalox skill key used as `instructions`. */
+        instructionVersion?: string;
+        activityId?: string;
+        /** USD total when gateway metadata includes `cost` (same source as {@link SkillDiagnosticsTrace.costUsd}). */
+        costUsd?: number;
+        /**
+         * When usage exists but no price is available, `"unpriced"` (from gateway metadata or SDK fallback).
+         * Legacy/async: `"deferred"`. Gateway `costStatus: "priced"` is never echoed — use {@link costUsd} instead.
+         */
+        costStatus?: SkillCostStatus;
+        /** Token counts from gateway metadata (same normalization as {@link SkillDiagnosticsTrace.usage}). */
+        usage?: SkillTraceUsage;
+        /**
+         * Model id that served the response when router/gateway expose it (`metadata.modelUsed` preferred over `metadata.model`).
+         */
+        modelUsed?: string;
+        /** LLM provider/engine when router/gateway expose `metadata.provider`. */
+        provider?: string;
+        /** Effective max-token cap applied for this invoke when router/gateway expose `metadata.maxTokensRequested`. */
+        effectiveMaxTokens?: number;
+        /** Provider region hint when present on gateway metadata. */
+        region?: string;
+        /** Echo of {@link RunSkillRequest.modelConfig} when the caller supplied it (requested overlay, not merged defaults). */
+        requestedModelConfig?: ModelConfig;
+        /**
+         * Merged generation parameters applied by the gateway (`metadata.effectiveModelConfig`, ≥9.1.1).
+         * Same allowlist as upstream **`pickEffectiveModelConfigForMetadata`**. Older gateway metadata may expose **`mergedModelConfig`**; it is considered when populating this slice.
+         */
+        effectiveModelConfig?: EffectiveModelConfigSlice;
+        /** Echo of gateway `exec.timeoutMs` from {@link RunSkillRequest.timeoutMs} when set. */
+        invokeExec?: {
+            timeoutMs?: number;
+        };
+    };
+    /**
+     * Structured trace for the gateway LLM call. Omitted unless the request used trace mode.
+     */
+    diagnostics?: RunSkillDiagnostics;
+    /**
+     * Alias of `diagnostics.trace` for orchestrators (same object reference).
+     */
+    debugTrace?: SkillDiagnosticsTrace;
+}
+export interface ExellixSkillsClientOptions {
+    /**
+     * Catalox client used to load `instructionsText` / `promptText` from the native `ai-skills` catalog.
+     * Required for every construction path (including when passing an external `gateway`).
+     */
+    catalox: Catalox;
+    /** Overrides `appId` passed into Catalox for skill discovery (default: `ai-skills`). */
+    cataloxAppId?: string;
+    packageName?: string;
+    enableActivityTracking?: boolean;
+    gateway?: AIGateway;
+    /** Passed through to the gateway when you inject a custom `gateway` (not used for Catalox template loading). */
+    forceLocal?: boolean;
+    /** Force creation of root directory structure for local development */
+    forceCreateRootDirectory?: boolean;
+    /**
+     * Auto-load `.env` from the working directory via **`@x12i/env`** `loadDotenv` (default: true).
+     * Set to false if you want to control environment loading yourself.
+     */
+    autoLoadDotenv?: boolean;
+    /**
+     * Default `TemplateRenderOptions` for every `gateway.invoke()` from this client (merged with gateway packaged defaults).
+     * Per-request {@link RunSkillRequest.templateRenderOptions} merges on top.
+     */
+    templateRendering?: TemplateRenderOptions;
+    /**
+     * Test-mode lifecycle guardrails.
+     * When enabled, the client avoids starting long-lived infrastructure unless explicitly requested.
+     * Defaults to `true` when `NODE_ENV === "test"` and to `false` otherwise.
+     */
+    testMode?: boolean;
+    /**
+     * In test mode, disable gateway activity tracking by default to reduce open handles.
+     * Defaults to `true` in test mode.
+     */
+    disableActivityTrackingInTests?: boolean;
+    /**
+     * Shallow-merged into `@x12i/logxer` {@link LoggingConfig.runtimeIdentity} after library defaults
+     * (`service` from {@link packageName}, semver from this package, `env`, `host`, `pid`).
+     */
+    logxerRuntimeIdentity?: Partial<RuntimeIdentity>;
+}
+export type ExellixSkillsErrorCode = 'SKILL_NOT_FOUND' | 'MISSING_REQUIRED_VARIABLES' | 'GATEWAY_INVOKE_FAILED' | 'FLEXMD_PARSE_FAILED' | 'OUTPUT_SCHEMA_VALIDATION_FAILED' | 'CONFIG_ERROR';
+/**
+ * Runtime Objects Observability Contract (expose-only)
+ *
+ * Packages may expose official, queryable Activix/Logxer clients for debug tooling.
+ * If a client does not implement the official query methods, the package must leave
+ * the field undefined (no local adapters).
+ *
+ * Shapes match `@x12i/ai-gateway` `runtime-objects` (re-exported here for a single import surface).
+ */
+export type { ActivixQueryableClient, LogxerQueryableClient, PackageRuntimeObjects, RuntimeObjects, } from "@x12i/ai-gateway";
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

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

package/dist/utils/build-activix-billing-patch.d.ts

@@ -0,0 +1,24 @@
+import type { NormalizedSkillBilling } from "./normalize-billing-metadata.js";
+/** Activix / gateway activity row billing status (distinct from SDK {@link SkillCostStatus}). */
+export type ActivixRecordCostStatus = "priced" | "unpriced" | "deferred";
+export type ActivixBillingPatchContext = {
+    provider?: string;
+    region?: string;
+    effectiveModelConfig?: Record<string, unknown>;
+};
+export type ActivixBillingPatch = {
+    /** Top-level Activix fields (`completeRecord` / `patchRecord`). */
+    topLevel: Record<string, unknown>;
+    /** Merged into `outer.metadata` (same slice as gateway `pickActivixCompletionRoutingMetadata`). */
+    outerMetadata: Record<string, unknown>;
+    /** Activix v7 `outer.cost` shape when priced. */
+    outerCost?: Record<string, unknown>;
+    /** Merged into `response.metadata` when a response object exists. */
+    responseMetadata: Record<string, unknown>;
+};
+/**
+ * Builds Activix patch fields for billing so persisted rows match gateway `logSuccess` / invoke metadata.
+ * SDK {@link RunSkillResponse.metadata} omits `costStatus: "priced"`; Activix records use gateway vocabulary.
+ */
+export declare function buildActivixBillingPatch(billing: NormalizedSkillBilling, ctx?: ActivixBillingPatchContext): ActivixBillingPatch;
+//# sourceMappingURL=build-activix-billing-patch.d.ts.map

package/dist/utils/build-activix-billing-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-activix-billing-patch.d.ts","sourceRoot":"","sources":["../../src/utils/build-activix-billing-patch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAG9E,iGAAiG;AACjG,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAEzE,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,mGAAmG;IACnG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,CAAC;AA4BF;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,sBAAsB,EAC/B,GAAG,CAAC,EAAE,0BAA0B,GAC/B,mBAAmB,CA+CrB"}

package/dist/utils/build-activix-billing-patch.js

@@ -0,0 +1,70 @@
+function usageTokensMetadata(usage) {
+    const tokens = {
+        prompt: usage.tokensPrompt,
+        completion: usage.tokensCompletion,
+        total: usage.tokensTotal,
+    };
+    return {
+        tokens,
+        usage,
+        ...(usage.maxTokensRequested !== undefined ? { maxTokensRequested: usage.maxTokensRequested } : {}),
+    };
+}
+function routingMetadataSlice(billing, ctx) {
+    return {
+        ...usageTokensMetadata(billing.usage),
+        ...(billing.modelUsed !== undefined ? { modelUsed: billing.modelUsed, model: billing.modelUsed } : {}),
+        ...(ctx?.provider !== undefined ? { provider: ctx.provider } : {}),
+        ...(ctx?.region !== undefined ? { region: ctx.region } : {}),
+        ...(ctx?.effectiveModelConfig !== undefined ? { effectiveModelConfig: ctx.effectiveModelConfig } : {}),
+    };
+}
+/**
+ * Builds Activix patch fields for billing so persisted rows match gateway `logSuccess` / invoke metadata.
+ * SDK {@link RunSkillResponse.metadata} omits `costStatus: "priced"`; Activix records use gateway vocabulary.
+ */
+export function buildActivixBillingPatch(billing, ctx) {
+    const routing = routingMetadataSlice(billing, ctx);
+    if (billing.costUsd !== undefined) {
+        const cost = billing.costUsd;
+        return {
+            topLevel: { cost, costStatus: "priced" },
+            outerMetadata: {
+                ...routing,
+                cost,
+                costUsd: cost,
+                costStatus: "priced",
+            },
+            outerCost: {
+                usd: cost,
+                unit: "USD",
+                tokens: {
+                    input: billing.usage.tokensPrompt,
+                    output: billing.usage.tokensCompletion,
+                    total: billing.usage.tokensTotal,
+                },
+                ...(billing.modelUsed !== undefined ? { model: billing.modelUsed } : {}),
+                ...(ctx?.provider !== undefined ? { provider: ctx.provider } : {}),
+            },
+            responseMetadata: {
+                ...routing,
+                cost,
+                costUsd: cost,
+                costStatus: "priced",
+            },
+        };
+    }
+    const activixStatus = billing.costStatus === "deferred" ? "deferred" : "unpriced";
+    return {
+        topLevel: { costStatus: activixStatus },
+        outerMetadata: {
+            ...routing,
+            costStatus: activixStatus,
+        },
+        responseMetadata: {
+            ...routing,
+            costStatus: activixStatus,
+        },
+    };
+}
+//# sourceMappingURL=build-activix-billing-patch.js.map

package/dist/utils/build-activix-billing-patch.js.map

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