@exellix/ai-skills 6.3.3 → 6.4.0

package/README.md

@@ -14,6 +14,7 @@ Foundational skill execution layer for the exellix ecosystem: templates live in
 | Per-package log level (`AI_SKILLS_LOGS_LEVEL`) | **[Logging](#logging-aiskills--x12ilogxer)** below · [Logxer integration checklist](docs/LOGXER_INTEGRATION_CHECKLIST.md) · [@x12i/logxer on npm](https://www.npmjs.com/package/@x12i/logxer) |
 | Gateway templates (v4), `invoke()` vs `invokeChat()`, `templateRendering` | **[docs/GATEWAY_TEMPLATE_PROTOCOL_V4.md](docs/GATEWAY_TEMPLATE_PROTOCOL_V4.md)** |
 | This package: `workingMemory`, `templateRenderOptions`, client `templateRendering` | **[docs/AI_SKILLS_GATEWAY_TEMPLATES.md](docs/AI_SKILLS_GATEWAY_TEMPLATES.md)** |
+| **Upgrading to `@x12i/ai-gateway` 10.x** (billing, required fields, removed behaviors) | **[docs/UPGRADING_AI_GATEWAY_10.md](docs/UPGRADING_AI_GATEWAY_10.md)** |
 | Invoke execution metadata (`provider`, `modelUsed`, `effectiveModelConfig`, …) | **[docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md](docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md)** |
 | Wire model on `runSkill()` (required; no alias / no gateway default) | **[docs/MODEL_INVOKE_CONTRACT.md](docs/MODEL_INVOKE_CONTRACT.md)** |
 | Host invoke contract (`reasoningEffort`, no caller `maxTokens`) | **[Host responsibilities](#host-responsibilities-orchestrator--main)** · [MODEL_INVOKE_CONTRACT.md](docs/MODEL_INVOKE_CONTRACT.md) |
@@ -45,7 +46,7 @@ npm install @exellix/ai-skills
 
 This package depends on **`@x12i/ai-gateway`**, **`@x12i/catalox`**, **`@x12i/logxer`**, **`@x12i/env`**, **`@x12i/rendrix`**, and **`firebase-admin`** (for Firestore-backed Catalox). **`@x12i/catalox` ≥ 4.0** expects **Node 20+**. Align **`firebase-admin`** / **`@x12i/catalox`** versions with your app if you share a Firebase app instance.
 
-**`@x12i/ai-gateway` ≥ 10.0.6** (see `package.json`) with **`@x12i/activix` ^8** is required: every invoke needs an explicit wire **`model`** and **`maxTokens`** (this package supplies **`maxTokens`** via **`@x12i/optimixer`** before `gateway.invoke()`). Invoke **`metadata`** includes routing fields (≥9.1.1), rejection **`metadata`** on failures (≥9.1.2), and normalized billing (**`costUsd`**, **`cost`**, **`costStatus: priced | unpriced`**, optional **`costBreakdown`**) on success (≥9.3; ai-tools catalog pricing in gateway ≥10.0.6). **This package does not use `@x12i/ai-tools` directly** — cost is resolved by the gateway. See **`docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md`**. Every **`runSkill`** call must include **`agentId`**, **`jobTypeId`**, and **`taskTypeId`** (Activix linkage — no package defaults).
+**`@x12i/ai-gateway` ≥ 10.0.6** (see `package.json`) with **`@x12i/activix` ^8** is required: every invoke needs an explicit wire **`model`** and **`maxTokens`** (this package supplies **`maxTokens`** via **`@x12i/optimixer`** before `gateway.invoke()`). Invoke **`metadata`** includes routing fields (≥9.1.1), rejection **`metadata`** on failures (≥9.1.2), and normalized billing (**`costUsd`**, **`cost`**, **`costStatus: priced | unpriced`**, optional **`costBreakdown`**) on success (≥9.3; ai-tools catalog pricing in gateway ≥10.0.6). **This package does not use `@x12i/ai-tools` directly** — cost is resolved by the gateway. See **`docs/UPGRADING_AI_GATEWAY_10.md`** and **`docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md`**. Every **`runSkill`** call must include **`agentId`**, **`jobTypeId`**, and **`taskTypeId`** (Activix linkage — no package defaults).
 
 **CI:** `npm run test:ci` runs **`npm run build`** and **`npm run test:unit`** (no live Firestore or real LLM). Full **`npm test`** still runs **`test:integration`**, which may append live catalog tests when env enables them.
 
@@ -256,10 +257,10 @@ Studio / graph Run Analysis expects activities and responses to explain billing
 
 Gateway **`invoke()`** metadata (≥ **9.3**, ai-tools catalog in gateway ≥ **10.0.6**) uses **`costUsd`** / **`cost`** when priced and **`costStatus: "priced" | "unpriced"`**. Optional **`costBreakdown`** (prompt/completion USD) is forwarded when the gateway catalog pricing includes it. **This SDK never calculates cost locally** — it normalizes gateway metadata only. Priced runs expose **`costUsd` only** (gateway **`"priced"`** status is not echoed). When usage exists but no USD total is known, **`costStatus: "unpriced"`** is set (gateway explicit flag or SDK fallback).
 
-| Gateway / router situation | Gateway `metadata` | On `RunSkillResponse.metadata` | Activix record (gateway `completeRecord` + SDK patch) |
+| Gateway / router situation | Gateway `metadata` | On `RunSkillResponse.metadata` | Activix record (gateway `logSuccess` + SDK patch) |
 |----------------------------|-------------------|-------------------------------|------------------------------------------------------|
-| Priced (router or ai-tools catalog) | `costUsd`, `cost`, `costStatus: "priced"`, optional `costBreakdown` | `costUsd`, optional `costBreakdown` (no `costStatus`) | Top-level `cost`, `costStatus: "priced"`, `outer.metadata` billing slice, `outer.cost.usd` |
-| Usage, no price | `costStatus: "unpriced"` | `costStatus: "unpriced"` | `costStatus: "unpriced"` + token usage on `outer.metadata` / `response.metadata` |
+| Priced (router or ai-tools catalog) | `costUsd`, `cost`, `costStatus: "priced"`, optional `costBreakdown` | `costUsd`, optional `costBreakdown` (no `costStatus`) | Root `cost` / `costUsd` / `costStatus: "priced"`, **`outer.cost.usd`**; prefer these over `outer.metadata` for billing |
+| Usage, no price | `costStatus: "unpriced"` | `costStatus: "unpriced"` | Root `costStatus: "unpriced"` + token usage on root `metadata` / `response.metadata` |
 | Legacy async pricing | `costStatus: "deferred"` (older gateways) | `costStatus: "deferred"` | same |
 
 Gateway **`logSuccess`** writes billing on the activity row during **`invoke()`** when **`enableActivityTracking`** is on (default). **`patchActivixActivityAfterSkill`** then merges the same billing slice plus **`outputContract`** **`parsed`** fields so Run Analysis and Activix queries stay aligned with **`RunSkillResponse.metadata`**.
@@ -655,14 +656,17 @@ Details and caveats: **[docs/FLEX_MD_AND_TESTING.md](docs/FLEX_MD_AND_TESTING.md
 
 - **Node.js 20+** (see `package.json` **`engines`**; aligns with **`@x12i/catalox`**)
 - **`@x12i/catalox`** **≥ 4** and **Firebase** access for the **`ai-skills`** native catalog (see **`createCataloxFromEnv`** and [Environment (Firebase & Catalox v4)](#environment-firebase--catalox-v4))
-- **`@x12i/ai-gateway`** **^10.0.2** (see `package.json`; shares **`@x12i/activix` ^8** with this package)
-- **`@x12i/activix`** **^8.0.5** (direct dependency for activity-row enrichment types/patches)
+- **`@x12i/ai-gateway`** **^10.0.7** (see `package.json`; shares **`@x12i/activix` ^8** with this package)
+- **`@x12i/activix`** **^8.5.0** (direct dependency for activity-row enrichment types/patches)
 - At least one LLM provider key when using the default constructed gateway
+
+**Downstream orchestrators:** `@exellix/ai-tasks` **≥ 8.6.7** depends on this package (**≥ 6.3.7**) for MAIN execution and inherits the gateway 10.x contract — see **[docs/UPGRADING_AI_GATEWAY_10.md](docs/UPGRADING_AI_GATEWAY_10.md)**.
+
 ## Related runtime packages
 
 Task and graph orchestration live in sibling packages, not in **`@exellix/ai-skills`**:
 
-- **`@exellix/ai-tasks`** — task orchestration and task-level runtime wiring
+- **`@exellix/ai-tasks`** — task orchestration and task-level runtime wiring (**≥ 8.6.7** pins **`@exellix/ai-skills` ≥ 6.3.7**; gateway 10.x billing and invoke rules apply to MAIN via this package)
 - **`@exellix/graph-engine`** — graph execution and graph-level runtime wiring; forward each node’s **`inputs.outputContract`** on **`runSkill`** when Run Analysis or downstream validation require structured **`parsed`** fields
 - **`@exellix/exellix-runtime`** — root runtime composition (for example loading composed `runtimeObjects` for debug tooling)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/ai-skills",
-  "version": "6.3.3",
+  "version": "6.4.0",
   "description": "Foundational skill execution layer for exellix ecosystem using @x12i/ai-gateway with FlexMD 2.0 support and Catalox as the catalog store",
   "type": "module",
   "main": "dist/index.js",
@@ -57,9 +57,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@x12i/activix": "^8.5.0",
-    "@x12i/ai-gateway": "^10.0.6",
-    "@x12i/ai-profiles": "^2.1.1",
+    "@x12i/activix": "^8.6.0",
+    "@x12i/ai-gateway": "^10.1.0",
+    "@x12i/ai-profiles": "^3.0.0",
     "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
     "@x12i/execution-memory-manager": "^1.2.0",