@exellix/ai-tasks 9.0.2 → 9.0.5

package/documenations/sessions/2026-06-08-subnets-model-resolution/PROBLEM.md

@@ -0,0 +1,236 @@
+# Problem knowledge: `Unknown model "google/gemini-2.5-flash-lite"`
+
+**Session:** 2026-06-08  
+**Repro:** `worox-graphs-playground` — `graph:subnets-analysis`, `node:inbound-reachability`, `skillKey=professional-answer`  
+**Status:** **Resolved** in **`@x12i/funcx@4.9.5+`** (catalog gate via **`@x12i/ai-profiles`**). Ship **`@exellix/xynthesis@4.6.6+`** and **`@exellix/ai-tasks@9.0.5+`** with **`@x12i/funcx@^4.9.5`** declared in dependencies.
+
+---
+
+## 1. What we observed
+
+```json
+{
+  "nodeId": "node:inbound-reachability",
+  "error": {
+    "message": "runTask failed (skillKey=professional-answer nodeId=node:inbound-reachability graphId=graph:subnets-analysis): Unknown model \"google/gemini-2.5-flash-lite\". Pass a catalog-resolvable model slug (e.g. \"deepseek/deepseek-v4-flash\")."
+  }
+}
+```
+
+Stack (from consumer): `@exellix/graph-engine` → `@exellix/ai-tasks` `runTask` → … → `@x12i/funcx` `Client.ask()`.
+
+The exact substring `Pass a catalog-resolvable model slug` is thrown only by **`@x12i/funcx`** `requireCatalogModel()` (funcx ≥4.3). It is **not** from ai-gateway, ai-skills, or Catalox.
+
+---
+
+## 2. What we verified about input (runtime data)
+
+| Fact | Source |
+|------|--------|
+| Runtime model input was **`cheap/default`**, not a concrete slug in authoring | Operator check |
+| **Skill catalog (Catalox `ai-skills`) stores no model** for `professional-answer` or other skills — templates + Optimixer only | Operator check + mono-repo `AI_SKILLS_CATALOG_ITEMS` |
+| `cheap/default` → `google/gemini-2.5-flash-lite` is **correct** OpenRouter wire output for PRE/POST xynthesis | `@x12i/ai-profiles` bundled registry |
+
+**Important:** The error string shows a **resolved wire slug**, not what was typed in the graph. That slug is **invoke-time output**, not catalog-authored data.
+
+---
+
+## 3. Three different “catalog” meanings (do not mix)
+
+| Name | What it is | Role in this incident |
+|------|------------|------------------------|
+| **Catalox skill catalog** | Skill templates, Optimixer fields | **Not involved** — no models |
+| **Runtime orchestration data** | `RunTaskRequest.modelConfig`, graph `modelSelection`, per-unit slots | **Source of `cheap/default`** — correct |
+| **`@x12i/ai-tools` models catalog** | JSON bundled inside the **npm package**; used by funcx/gateway for slug lookup + pricing | **Where the error is thrown** — funcx asks “is this slug known?” |
+| **`@x12i/ai-profiles` registry** | Profile/choice → vendor SKU + OpenRouter invocation mapping | **Already used successfully** before funcx (see §4) |
+
+---
+
+## 4. End-to-end path today (what actually runs)
+
+### 4.1 Graph → ai-tasks
+
+For subnet-style nodes running `professional-answer` with PRE synthesis, a typical `RunTaskRequest` looks like:
+
+```json
+{
+  "skillKey": "professional-answer",
+  "modelConfig": {
+    "preActionModel": "cheap/default",
+    "skillModel": "<profile or concrete — MAIN, separate hop>",
+    "postActionModel": "cheap/default"
+  },
+  "taskConfiguration": {
+    "aiTaskStrategies": { "pre": "synthesis", ... }
+  }
+}
+```
+
+Graph-engine wraps any `runTask` failure with `skillKey=professional-answer` even when **PRE dies before MAIN** — misleading for operators.
+
+### 4.2 PRE synthesis — **first hop: ai-profiles** (already in use)
+
+1. ai-tasks `_runSynthesizedContextPreStep` reads `preActionModel` → `"cheap/default"`.
+2. Calls `@exellix/xynthesis` `executeXynthesisAction({ model: "cheap/default", ... })`.
+3. xynthesis `resolveXynthesisModel("cheap/default")` calls **`@x12i/ai-profiles`**:
+   - Profile `cheap`, choice `default`
+   - Vendor: `google` / `gemini-2.5-flash-lite`
+   - OpenRouter invocation: `google/gemini-2.5-flash-lite`
+4. xynthesis builds `modelResolution` snapshot and calls `FuncxInvoker` with:
+   - `model: "cheap/default"` (alias)
+   - `modelResolution.wireModelId: "google/gemini-2.5-flash-lite"`
+
+If step 3 fails, xynthesis throws **before** funcx — e.g. unknown profile/choice.  
+**We got past step 3** (otherwise the error message would be about alias resolution, not “Unknown model … slug”).
+
+### 4.3 PRE synthesis — **second hop: funcx + ai-tools** (where it breaks)
+
+5. `FuncxInvoker` → `client.ask(userPrompt, { model: "google/gemini-2.5-flash-lite", ... })`.
+6. funcx `resolveAskRuntime()` → `requireCatalogModel({ model, provider: "openrouter" })`.
+7. funcx `resolveModelSlug()` loads **`@x12i/ai-tools`** catalog via `getAiModelsCatalogClient().getAllModels()` and runs `createModelNameResolver(catalog).resolve(...)`.
+8. If `found: false` → throws:
+
+   ```text
+   Unknown model "google/gemini-2.5-flash-lite". Pass a catalog-resolvable model slug ...
+   ```
+
+funcx README (≥4.3) documents this split explicitly:
+
+- **Host (xynthesis):** resolve `profile/choice` with **ai-profiles**, pass **concrete slug** to funcx.
+- **funcx:** slug must be **catalog-resolvable** in **ai-tools** — funcx does **not** resolve `cheap/default` itself.
+
+### 4.4 MAIN `professional-answer` — different path (not this error)
+
+MAIN uses `skillModel` → `@exellix/ai-skills` → `@x12i/ai-gateway`:
+
+- Wire shape: `openrouter/google/gemini-2.5-flash-lite` (gateway prefix), not bare slug.
+- Validation: ai-tools `resolveInvokeModel` via gateway, **different error message** (`Could not resolve model "..." (provider: "...")`).
+
+So this incident is **PRE (or POST) xynthesis/funcx**, not MAIN professional-answer gateway invoke.
+
+---
+
+## 5. ai-profiles vs ai-tools — what is done today, could ai-profiles replace ai-tools here?
+
+### What is done today
+
+| Step | Package | Job |
+|------|---------|-----|
+| Profile → wire slug | **ai-profiles** (in xynthesis) | `cheap/default` → `google/gemini-2.5-flash-lite` |
+| Slug accepted for HTTP call? | **ai-tools** (inside funcx) | Re-lookup slug in bundled models JSON |
+| LLM HTTP call | **funcx** → OpenRouter | Uses validated `modelId` |
+
+**ai-profiles is already in the pipeline.** The failure is not “we should use ai-profiles instead of nothing” — it is **ai-tools rejecting a slug that ai-profiles just produced**.
+
+### Could funcx validate with ai-profiles instead of ai-tools?
+
+**Theoretically yes, but not how funcx is built today.**
+
+- ai-profiles exposes `ensureConcreteModel("google/gemini-2.5-flash-lite")` and `resolveCatalogModel(...)` against its own `models-catalog.json` / registry linkage — similar knowledge, **different package and index**.
+- funcx 4.x is wired to **ai-tools** for `requireCatalogModel`, pricing (`readCallCostFromAskResult`), and Activix `autoCost`.
+- funcx README requires both packages aligned (e.g. **^3.3.0**).
+
+**Practical options (no code changed in this session):**
+
+| Approach | Effect |
+|----------|--------|
+| **Align versions** in `worox-graphs-playground`: `@x12i/funcx`, `@x12i/ai-tools`, `@x12i/ai-profiles`, `@exellix/xynthesis` to mono-repo pins | Most likely fix — both catalogs should agree on `gemini-2.5-flash-lite` |
+| **Pass `cheap/default` into funcx `ask()`** | **Fails by design** — funcx requires concrete catalog slug, not profile alias |
+| **funcx skip ai-tools check when `modelResolution` from ai-profiles present** | Would need **funcx product change** — trust host resolution, use ai-tools only for cost |
+| **funcx call ai-profiles `resolveCatalogModel` instead of ai-tools resolver** | Would need **funcx product change** — duplicate validation path, still two catalogs unless unified |
+
+**“Work better with ai-profiles”** in the current architecture means: **keep resolving in xynthesis via ai-profiles (already done), then ensure the ai-tools copy in the same install recognizes the emitted slug** — not replace step 1, fix step 2 alignment.
+
+---
+
+## 6. Why ai-profiles can succeed and ai-tools can still fail
+
+Both use bundled JSON that can **drift across package versions** or **resolve differently**:
+
+- ai-profiles: registry + `normalizeInvokeModel` → OpenRouter slug from profile choice.
+- ai-tools: `ModelNameResolver` over merged direct + OpenRouter catalog maps; lookup strategies (exact, slug, provider-prefix, fallback catalog).
+
+Known mono-repo state (reference install):
+
+- **ai-tools** direct catalog includes `provider: google`, `modelId: gemini-2.5-flash-lite`.
+- **ai-tools** OpenRouter catalog may list newer ids (e.g. `google/gemini-3.1-flash-lite`) without listing `2.5-flash-lite` under OpenRouter lane — resolver should fall back to direct catalog, **if consumer ai-tools version is current**.
+
+Failure modes for step 7:
+
+1. **Older `@x12i/ai-tools`** in playground — slug not in bundled JSON.
+2. **Older `@x12i/funcx`** — different resolver behavior.
+3. **ai-tools client disabled / throws** — funcx catches and returns `found: false` → same “Unknown model” message.
+4. **Version skew** — ai-profiles 3.3 emits slug ai-tools 2.x does not index.
+
+---
+
+## 7. What we know vs what we do not know
+
+### Known
+
+- Input at runtime: `cheap/default` (verified).
+- Skill Catalox catalog: no models (verified).
+- Wire slug in error is expected output of ai-profiles for `cheap/default`.
+- Error originates in funcx `requireCatalogModel` (ai-tools gate), not skill catalog.
+- Error message shape implies PRE/POST funcx path, not MAIN gateway.
+- graph-engine attributes failure to `skillKey=professional-answer` regardless of phase.
+
+### Not confirmed in consumer repo (if debugging continues)
+
+- Installed versions: `npm ls @x12i/funcx @x12i/ai-tools @x12i/ai-profiles @exellix/xynthesis`
+- Whether error still reproduces after version align.
+- Whether `executionMode: "trace"` shows `profileChoiceKey: "cheap/default"` and `wireModelId` on PRE hop only.
+- Whether `OPENROUTER_API_KEY` is set (missing key usually causes different errors, but worth ruling out).
+
+### Ruled out
+
+- Wrong profile choice in authoring (`cheap/default` is valid).
+- Skill catalog supplying `google/gemini-2.5-flash-lite`.
+- xynthesis double-prefix bug (`openrouter/google/...` to OpenRouter API) — fixed in xynthesis ≥4.1.8; error shows **bare** slug, which is correct for funcx.
+
+---
+
+## 8. Minimal reproduction mental model
+
+```text
+cheap/default
+  → [ai-profiles] OK → google/gemini-2.5-flash-lite
+  → [funcx ask + ai-tools requireCatalogModel] FAIL? → Unknown model
+  → [OpenRouter HTTP] never reached
+```
+
+If ai-profiles step failed, you would never see this exact funcx message with that slug.
+
+---
+
+## 9. Recommended next step (consumer only)
+
+In `worox-graphs-playground`:
+
+```bash
+npm ls @x12i/funcx @x12i/ai-tools @x12i/ai-profiles @exellix/xynthesis @exellix/ai-tasks
+rg "gemini-2.5-flash-lite" node_modules/@x12i/ai-tools/dist/
+```
+
+Align to mono-repo reference (`ai-tasks/package.json`: funcx ^4.6.0 override, ai-profiles ^3.3.0, xynthesis ^4.6.4). Re-run graph.
+
+If still failing with current catalogs, file upstream on **funcx/ai-tools** with: input alias `cheap/default`, ai-profiles wire `google/gemini-2.5-flash-lite`, and ai-tools resolver `found: false` diagnostics.
+
+---
+
+## 10. Mono-repo code references
+
+| Piece | Location |
+|-------|----------|
+| PRE reads `preActionModel` | `ai-tasks/src/core/task-sdk.ts` `_runSynthesizedContextPreStep` |
+| ai-profiles resolve | `xynthesis/src/resolveAiProfileModel.ts` `resolveXynthesisModel` |
+| Pass wire to funcx | `xynthesis/src/executeXynthesisAction.ts`, `xynthesis/src/funcxInvoker.ts` |
+| funcx ai-tools gate | `node_modules/@x12i/funcx/dist/src/serve.js` `requireCatalogModel` |
+| cheap/default → gemini | `node_modules/@x12i/ai-profiles/dist/data/models-profiles.json` |
+| Subnet-style fixture | `ai-tasks/test/fixtures/run-task/graph-engine-pre-synthesis.json` |
+
+---
+
+## 11. Session CR/FR docs
+
+Deferred — not part of this problem analysis. See sibling files only if needed for future product work.

package/documenations/sessions/2026-06-08-subnets-model-resolution/README.md

@@ -0,0 +1,11 @@
+# Session: subnets-analysis model resolution (2026-06-08)
+
+**Canonical doc:** [PROBLEM.md](./PROBLEM.md) — everything we know about the `Unknown model "google/gemini-2.5-flash-lite"` failure.
+
+## One-line summary
+
+Runtime input `cheap/default` is correct; ai-profiles resolves it to `google/gemini-2.5-flash-lite`; **funcx then re-validates that slug against `@x12i/ai-tools`** (not the skill catalog) and throws. Skill Catalox catalog has no models.
+
+## Other files in this folder
+
+CR/FR drafts from earlier in the session — **out of scope** for the original bug; kept for reference only.

package/documenations/sessions/2026-06-08-subnets-model-resolution/funcx-test-resolveModel.cheapDefaultWireSlug.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Copy to funcx repo: `test/resolveModel.cheapDefaultWireSlug.test.ts`
+ *
+ * Reproduces PRE xynthesis catalog gate (graphs-studio / ai-tasks):
+ *   cheap/default → ai-profiles wire slug → funcx resolveModelSlug / requireCatalogModel
+ *
+ * Run (from funcx root):
+ *   mode=debug FUNCX_ACTIVIX_ENABLED=0 node --import ./test/helpers/testGlobalSetup.ts --import tsx --test test/resolveModel.cheapDefaultWireSlug.test.ts
+ *
+ * BEFORE fix (funcx <4.9, resolveModelSlug uses getAllModels + narrow resolver):
+ *   - ai-tools catalog.resolveModel → found: true
+ *   - funcx resolveModelSlug         → found: false  → THIS TEST FAILS
+ *
+ * AFTER fix (funcx >=4.9, resolveModelSlug delegates to @x12i/ai-profiles requireCatalogModel):
+ *   - both → found: true → THIS TEST PASSES
+ */
+import assert from "node:assert/strict";
+import { describe, it, beforeEach } from "node:test";
+import { ensureConcreteModel } from "@x12i/ai-profiles";
+import {
+  createAiToolsInvokeClient,
+  createModelNameResolver,
+} from "@x12i/ai-tools";
+import {
+  configureAiToolsEngine,
+  requireCatalogModel,
+  resetAiToolsClients,
+  resolveModelSlug,
+} from "../src/index.js";
+
+const PRE_ALIAS = "cheap/default";
+/** Wire slug xynthesis passes to funcx ask() after ai-profiles resolution. */
+const EXPECTED_WIRE_SLUG = "google/gemini-2.5-flash-lite";
+
+function useDefaultDevCatalogEngine(): void {
+  resetAiToolsClients();
+  configureAiToolsEngine({
+    bundledOnly: false,
+    catalogLane: "text",
+  });
+}
+
+describe("resolveModel — cheap/default PRE wire slug (subnets-analysis repro)", () => {
+  beforeEach(() => {
+    useDefaultDevCatalogEngine();
+  });
+
+  it("step A: ai-profiles resolves cheap/default to the expected OpenRouter wire slug", () => {
+    const resolved = ensureConcreteModel(PRE_ALIAS);
+    assert.equal(
+      resolved.modelId,
+      EXPECTED_WIRE_SLUG,
+      "host/xynthesis must resolve profile alias before funcx"
+    );
+  });
+
+  it("step B–E: funcx must accept the wire slug when ai-tools full resolveModel does (default dev catalog)", async () => {
+    // --- step A (again at runtime boundary) ---
+    const resolved = ensureConcreteModel(PRE_ALIAS);
+    const wireSlug = resolved.modelId;
+    assert.equal(wireSlug, EXPECTED_WIRE_SLUG);
+
+    // --- step C: narrow path input (what funcx uses today) ---
+    const client = createAiToolsInvokeClient({ bundledOnly: false });
+    const mergedMap = await client.catalog.getAllModels();
+    const narrow = createModelNameResolver(mergedMap).resolve({
+      model: wireSlug,
+      provider: "openrouter",
+    });
+
+    // --- step D: ai-tools full path (what funcx SHOULD use) ---
+    const full = await client.catalog.resolveModel({
+      model: wireSlug,
+      provider: "openrouter",
+    });
+
+    // --- step E: funcx public API used by Client.ask() → requireCatalogModel ---
+    const funcx = await resolveModelSlug({
+      model: wireSlug,
+      provider: "openrouter",
+    });
+
+    // Diagnostic log when run with `node --test` (visible in CI output)
+    console.info("[resolveModel.cheapDefaultWireSlug]", {
+      alias: PRE_ALIAS,
+      wireSlug,
+      mergedCatalogSize: mergedMap.size,
+      mergedHasSlug: mergedMap.has(wireSlug),
+      narrowFound: narrow.found,
+      fullResolveFound: full.found,
+      fullResolvedReason: full.found ? full.resolvedReason : full.reason,
+      funcxResolveFound: funcx.found,
+    });
+
+    assert.equal(
+      full.found,
+      true,
+      `ai-tools catalog.resolveModel must accept wire slug "${wireSlug}" (ai-profiles fallback / direct lane)`
+    );
+
+    // Core regression: funcx must not reject a slug that ai-tools full resolver accepts.
+    assert.equal(
+      funcx.found,
+      full.found,
+      "resolveModelSlug must delegate to catalog.resolveModel (not getAllModels narrow map only)"
+    );
+    assert.equal(funcx.modelId, wireSlug);
+
+    // Same gate Client.ask() hits before OpenRouter HTTP:
+    const required = await requireCatalogModel({
+      model: wireSlug,
+      provider: "openrouter",
+    });
+    assert.equal(required.found, true);
+    assert.equal(required.modelId, wireSlug);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/ai-tasks",
-  "version": "9.0.2",
+  "version": "9.0.5",
   "description": "Task orchestration for the Exellix stack: runTask() with local handlers or LLM-backed execution, task-scoped memory/context enrichment, and executor dispatch via @exellix/ai-skills. ERC-compliant.",
   "type": "module",
   "main": "dist/index.js",
@@ -60,10 +60,12 @@
     "node": ">=20"
   },
   "overrides": {
-    "@x12i/funcx": "^4.6.0"
+    "@x12i/funcx": "^4.9.5",
+    "@x12i/ai-tools": "^3.3.3",
+    "@x12i/ai-profiles": "^3.4.0"
   },
   "dependencies": {
-    "@exellix/ai-skills": "^6.5.0",
+    "@exellix/ai-skills": "^6.5.4",
     "@exellix/memorix-narrix-adapter": "^2.0.0",
     "@exellix/narrix-adapter-chat": "^2.0.0",
     "@exellix/narrix-adapter-docs": "^2.0.0",
@@ -75,9 +77,10 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.6.2",
-    "@x12i/activix": "^8.6.0",
-    "@x12i/ai-profiles": "^3.2.0",
+    "@exellix/xynthesis": "^4.6.5",
+    "@x12i/activix": "^8.6.2",
+    "@x12i/ai-profiles": "^3.4.0",
+    "@x12i/funcx": "^4.9.5",
     "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
     "@x12i/execution-memory-manager": "^1.2.0",
@@ -85,7 +88,7 @@
     "@x12i/graphenix-plan-format": "^1.1.1",
     "@x12i/graphenix-trace-format": "^1.1.1",
     "@x12i/logxer": "^4.6.0",
-    "@x12i/optimixer": "^3.4.0",
+    "@x12i/optimixer": "^3.5.1",
     "@x12i/rendrix": "^4.3.0",
     "@x12i/search-adapter": "^1.5.1",
     "handlebars": "^4.7.8",