@exellix/ai-tasks 9.0.3 → 9.0.6

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `@exellix/ai-tasks` are documented here.
 
 The published **npm version** always matches **`version`** in [`package.json`](package.json). If this file skips a semver, treat [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) and [`RUNTASK_REQUEST.md`](RUNTASK_REQUEST.md) as the source of truth for cross-version upgrades.
 
+## [9.0.5] - 2026-06-08
+
+### Changed
+
+- **`@x12i/funcx`** **^4.9.5** (direct dependency + npm override) — aligns PRE/POST xynthesis with funcx catalog gate via **`@x12i/ai-profiles`** (requires funcx ≥ 4.9.5; fixes subnet-style PRE `Unknown model "google/gemini-2.5-flash-lite"`).
+- **`@x12i/ai-profiles`** **^3.4.0**, **`@exellix/xynthesis`** **^4.6.5** (publish **4.6.6** for funcx bump).
+
 ## [9.0.1] - 2026-06-07
 
 ### Changed

package/dist/aiSkillsUpstreamExports.d.ts

@@ -4,8 +4,8 @@
  *
  * Gateway key helpers remain on {@link ./skillCatalogExports.js}.
  */
-export { AI_SKILLS_APP_ID, AI_SKILLS_CATALOG_ID, AI_SKILLS_DESCRIPTOR_VERSION, AI_SKILLS_CATALOG_ITEMS, AI_SKILLS_LLM_IDENTITY_KEY, buildAiSkillsCatalogDescriptor, computeSkillRowStatus, listAiSkillsCatalogItems, catalogSkillKeyToRunSkillKey, catalogItemIdFromSkillKey, fetchSkillTemplatesFromCatalox, extractRunnableTemplateBodiesFromAiSkillsCatalogData, defaultAiSkillsCataloxContext, CataloxSkillNotFoundError, CataloxSkillAlreadyExistsError, CataloxSkillNotRunnableError, initFirebaseAdminFromEnv, createCataloxFromEnv, enrichIdentityWithAiSkillsLlmSnapshot, normalizeForStorage, toPresentationMarkdown, extractTemplateTokensFromTexts, extractTokenNamesFromStrings, getSkillTemplatesForPresentation, updateSkillTemplatesFromPresentation, getSkillTemplateInputs, getSkillTokens, getSkillContent, modifySkillContent, createSubSkill, deleteSubSkill, SKILL_TEMPLATE_ROLES_ORDER, upsertSkillCatalogItem, softDeleteSkillCatalogItem, runSkillRequestFromFlat, resolveAiEngineIdForRunSkill, SkillExecutionTraceError, includeRawProviderPayload, isTraceExecutionMode, } from "@exellix/ai-skills";
-export type { AiSkillsCatalogItemSpec, AiSkillsLlmIdentitySlice, CatalogReleaseStatus, AiSkillsPublishedItem, ListAiSkillsCatalogItemsResult, SkillCatalogStatus, FetchSkillTemplatesMode, ExtractedTemplateInputs, RunnableTemplateBodiesFromCatalogData, SkillTemplatesPresentation, SkillTemplatePresentationPatch, UpdateSkillTemplatesFromPresentationOptions, UpsertSkillCatalogItemInput, UpsertSkillCatalogItemOptions, SkillTemplateRole, SkillContentPart, ModifySkillContentResult, CreateSubSkillOverrides, CreateSubSkillInput, CreateSubSkillResult, DeleteSubSkillResult, RunSkillRequestFlat, GatewayExecutionSummary, OutputContract, } from "@exellix/ai-skills";
+export { AI_SKILLS_APP_ID, AI_SKILLS_CATALOG_ID, AI_SKILLS_DESCRIPTOR_VERSION, AI_SKILLS_CATALOG_ITEMS, AI_SKILLS_LLM_IDENTITY_KEY, buildAiSkillsCatalogDescriptor, computeSkillRowStatus, listAiSkillsCatalogItems, listSubSkillsCatalogItems, catalogSkillKeyToRunSkillKey, catalogItemIdFromSkillKey, fetchSkillTemplatesFromCatalox, defaultAiSkillsCataloxContext, CataloxSkillNotFoundError, CataloxSkillAlreadyExistsError, CataloxSkillNotRunnableError, initFirebaseAdminFromEnv, createCataloxFromEnv, enrichIdentityWithAiSkillsLlmSnapshot, normalizeForStorage, toPresentationMarkdown, extractTemplateTokensFromTexts, extractTokenNamesFromStrings, getSkillTemplatesForPresentation, updateSkillTemplatesFromPresentation, getSkillTemplateInputs, getSkillTokens, getSkillContent, modifySkillContent, createSubSkill, deleteSubSkill, SKILL_TEMPLATE_ROLES_ORDER, upsertSkillCatalogItem, softDeleteSkillCatalogItem, updateSkillMetadata, isSubSkillCatalogItem, createAiSkillsCatalogApi, runSkillRequestFromFlat, resolveAiEngineIdForRunSkill, SkillExecutionTraceError, includeRawProviderPayload, isTraceExecutionMode, } from "@exellix/ai-skills";
+export type { AiSkillsCatalogItemSpec, AiSkillsLlmIdentitySlice, CatalogReleaseStatus, AiSkillsPublishedItem, AiSkillsCatalogItem, ListAiSkillsCatalogItemsResult, SkillCatalogStatus, FetchSkillTemplatesMode, ExtractedTemplateInputs, RunnableTemplateBodiesFromCatalogData, SkillTemplatesPresentation, SkillTemplatePresentationPatch, UpdateSkillTemplatesFromPresentationOptions, UpsertSkillCatalogItemInput, UpsertSkillCatalogItemOptions, UpdateSkillMetadataInput, AiSkillsCatalogApi, CreateAiSkillsCatalogApiOptions, CreateSkillInput, DeleteSkillResult, ForkSkillInput, ForkSkillResult, GetSkillOptions, ListSkillsOptions, SkillCatalogDetail, UpdateSkillInput, SkillTemplateRole, SkillContentPart, ModifySkillContentResult, CreateSubSkillOverrides, CreateSubSkillInput, CreateSubSkillResult, DeleteSubSkillResult, RunSkillRequestFlat, GatewayExecutionSummary, OutputContract, } from "@exellix/ai-skills";
 /** Lower-level execution entrypoints from `@exellix/ai-skills` (same package as {@link ExellixSkillsClient}). */
 export { SkillExecutor, BaseClient } from "@exellix/ai-skills";
 /** Markdown helper for gateway context payloads. */

package/dist/aiSkillsUpstreamExports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiSkillsUpstreamExports.d.ts","sourceRoot":"","sources":["../src/aiSkillsUpstreamExports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,8BAA8B,EAC9B,oDAAoD,EACpD,6BAA6B,EAC7B,yBAAyB,EACzB,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,qCAAqC,EACrC,mBAAmB,EACnB,sBAAsB,EACtB,8BAA8B,EAC9B,4BAA4B,EAC5B,gCAAgC,EAChC,oCAAoC,EACpC,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,8BAA8B,EAC9B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,qCAAqC,EACrC,0BAA0B,EAC1B,8BAA8B,EAC9B,2CAA2C,EAC3C,2BAA2B,EAC3B,6BAA6B,EAC7B,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,iHAAiH;AACjH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE/D,oDAAoD;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"aiSkillsUpstreamExports.d.ts","sourceRoot":"","sources":["../src/aiSkillsUpstreamExports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,qCAAqC,EACrC,mBAAmB,EACnB,sBAAsB,EACtB,8BAA8B,EAC9B,4BAA4B,EAC5B,gCAAgC,EAChC,oCAAoC,EACpC,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,8BAA8B,EAC9B,kBAAkB,EAClB,uBAAuB,EACvB,uBAAuB,EACvB,qCAAqC,EACrC,0BAA0B,EAC1B,8BAA8B,EAC9B,2CAA2C,EAC3C,2BAA2B,EAC3B,6BAA6B,EAC7B,wBAAwB,EACxB,kBAAkB,EAClB,+BAA+B,EAC/B,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,iHAAiH;AACjH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE/D,oDAAoD;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/aiSkillsUpstreamExports.js

@@ -4,7 +4,7 @@
  *
  * Gateway key helpers remain on {@link ./skillCatalogExports.js}.
  */
-export { AI_SKILLS_APP_ID, AI_SKILLS_CATALOG_ID, AI_SKILLS_DESCRIPTOR_VERSION, AI_SKILLS_CATALOG_ITEMS, AI_SKILLS_LLM_IDENTITY_KEY, buildAiSkillsCatalogDescriptor, computeSkillRowStatus, listAiSkillsCatalogItems, catalogSkillKeyToRunSkillKey, catalogItemIdFromSkillKey, fetchSkillTemplatesFromCatalox, extractRunnableTemplateBodiesFromAiSkillsCatalogData, defaultAiSkillsCataloxContext, CataloxSkillNotFoundError, CataloxSkillAlreadyExistsError, CataloxSkillNotRunnableError, initFirebaseAdminFromEnv, createCataloxFromEnv, enrichIdentityWithAiSkillsLlmSnapshot, normalizeForStorage, toPresentationMarkdown, extractTemplateTokensFromTexts, extractTokenNamesFromStrings, getSkillTemplatesForPresentation, updateSkillTemplatesFromPresentation, getSkillTemplateInputs, getSkillTokens, getSkillContent, modifySkillContent, createSubSkill, deleteSubSkill, SKILL_TEMPLATE_ROLES_ORDER, upsertSkillCatalogItem, softDeleteSkillCatalogItem, runSkillRequestFromFlat, resolveAiEngineIdForRunSkill, SkillExecutionTraceError, includeRawProviderPayload, isTraceExecutionMode, } from "@exellix/ai-skills";
+export { AI_SKILLS_APP_ID, AI_SKILLS_CATALOG_ID, AI_SKILLS_DESCRIPTOR_VERSION, AI_SKILLS_CATALOG_ITEMS, AI_SKILLS_LLM_IDENTITY_KEY, buildAiSkillsCatalogDescriptor, computeSkillRowStatus, listAiSkillsCatalogItems, listSubSkillsCatalogItems, catalogSkillKeyToRunSkillKey, catalogItemIdFromSkillKey, fetchSkillTemplatesFromCatalox, defaultAiSkillsCataloxContext, CataloxSkillNotFoundError, CataloxSkillAlreadyExistsError, CataloxSkillNotRunnableError, initFirebaseAdminFromEnv, createCataloxFromEnv, enrichIdentityWithAiSkillsLlmSnapshot, normalizeForStorage, toPresentationMarkdown, extractTemplateTokensFromTexts, extractTokenNamesFromStrings, getSkillTemplatesForPresentation, updateSkillTemplatesFromPresentation, getSkillTemplateInputs, getSkillTokens, getSkillContent, modifySkillContent, createSubSkill, deleteSubSkill, SKILL_TEMPLATE_ROLES_ORDER, upsertSkillCatalogItem, softDeleteSkillCatalogItem, updateSkillMetadata, isSubSkillCatalogItem, createAiSkillsCatalogApi, runSkillRequestFromFlat, resolveAiEngineIdForRunSkill, SkillExecutionTraceError, includeRawProviderPayload, isTraceExecutionMode, } from "@exellix/ai-skills";
 /** Lower-level execution entrypoints from `@exellix/ai-skills` (same package as {@link ExellixSkillsClient}). */
 export { SkillExecutor, BaseClient } from "@exellix/ai-skills";
 /** Markdown helper for gateway context payloads. */

package/dist/aiSkillsUpstreamExports.js.map

@@ -1 +1 @@
-{"version":3,"file":"aiSkillsUpstreamExports.js","sourceRoot":"","sources":["../src/aiSkillsUpstreamExports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,8BAA8B,EAC9B,oDAAoD,EACpD,6BAA6B,EAC7B,yBAAyB,EACzB,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,qCAAqC,EACrC,mBAAmB,EACnB,sBAAsB,EACtB,8BAA8B,EAC9B,4BAA4B,EAC5B,gCAAgC,EAChC,oCAAoC,EACpC,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AA6B5B,iHAAiH;AACjH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE/D,oDAAoD;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"aiSkillsUpstreamExports.js","sourceRoot":"","sources":["../src/aiSkillsUpstreamExports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,qCAAqC,EACrC,mBAAmB,EACnB,sBAAsB,EACtB,8BAA8B,EAC9B,4BAA4B,EAC5B,gCAAgC,EAChC,oCAAoC,EACpC,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,EACtB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAyC5B,iHAAiH;AACjH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE/D,oDAAoD;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/internal/setAiToolsBundledOnlyEnv.d.ts.map

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

package/dist/internal/setAiToolsBundledOnlyEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setAiToolsBundledOnlyEnv.js","sourceRoot":"","sources":["../../src/internal/setAiToolsBundledOnlyEnv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,KAAK,GAAG,EAAE,CAAC;IAC9C,OAAO,CAAC,GAAG,CAAC,qBAAqB,GAAG,GAAG,CAAC;AAC1C,CAAC"}

package/documenations/sessions/2026-06-08-subnets-model-resolution/CR-1-no-concrete-wire-in-graph-plans.md

@@ -0,0 +1,93 @@
+# CR-1 — No concrete wire models in compiled graph plans
+
+Status: **proposed**  
+Type: Change request  
+Owners: `@x12i/graphenix-plan-compiler`, `@exellix/graph-engine`, `@exellix/ai-tasks`  
+Filed: 2026-06-08  
+Session: [README](./README.md)
+
+---
+
+## Summary
+
+Compiled executable node plans must store **profile/choice selections only**. They must **not** freeze concrete OpenRouter or gateway wire slugs in `resolvedInvocationSnapshot.modelId` or `AiConcreteModelSelection`.
+
+Concrete resolution happens **once at invoke time** inside ai-tasks / xynthesis / ai-skills — same boundary as xynthesis PRE/POST today.
+
+---
+
+## Problem
+
+`overlayUnitModelOnRequest` prefers a pre-resolved snapshot over the authored selection:
+
+```typescript
+// ai-tasks/src/node-execution/resolveUnitModelSelection.ts
+if (snapshot && typeof snapshot.modelId === "string" && snapshot.modelId.trim()) {
+  wireValue = snapshot.modelId;  // e.g. "google/gemini-2.5-flash-lite"
+} else if (selection) {
+  wireValue = selectionToWireValue(selection);  // e.g. "cheap/default"
+}
+```
+
+When the compiler writes `resolvedInvocationSnapshot.modelId: "google/gemini-2.5-flash-lite"`:
+
+- Authoring shows `cheap/default` (correct).
+- Runtime overlay injects a **concrete slug** into `preActionModel` / `postActionModel` / `skillModel`.
+- Operators cannot tell whether failure is alias resolution or catalog lookup.
+- Catalog drift (retired slugs) breaks frozen plans even when profiles are still valid.
+
+This session's error slug may appear in the plan **even when input was `cheap/default`**.
+
+---
+
+## Requirements
+
+### CR-1.1 — Compiler output
+
+- `executionUnits[].modelSelection` MUST be one of:
+  - `{ kind: "profileChoice", key: "cheap/default" }`
+  - `{ kind: "profile", profile: "cheap", choice: "default" }`
+- MUST NOT emit `{ kind: "concrete", ... }` / `AiConcreteModelSelection` in new plans (version gate).
+- MUST NOT emit `resolvedInvocationSnapshot.modelId` as a concrete provider/OpenRouter slug.
+
+### CR-1.2 — Optional compile-time preview (read-only)
+
+If compile needs a preview for UI, use a separate non-authoritative field, e.g.:
+
+```json
+"invocationPreview": {
+  "profileChoiceKey": "cheap/default",
+  "resolvedWireModelId": "google/gemini-2.5-flash-lite",
+  "phase": "preAction",
+  "resolverVersion": "ai-tasks/9.0.3"
+}
+```
+
+Preview MUST NOT be consumed by `overlayUnitModelOnRequest`.
+
+### CR-1.3 — ai-tasks runtime
+
+- `overlayUnitModelOnRequest`: ignore `resolvedInvocationSnapshot.modelId` when it looks like a concrete wire id (`isConcreteModelId`).
+- Prefer `modelSelection` profile/choice keys only.
+- Reject plans that only have concrete snapshot and no profile selection (validation error with path to unit).
+
+### CR-1.4 — Migration
+
+- Graphenix plan version bump (e.g. v2.2) documenting the rule.
+- One release: warn on concrete snapshot; next release: reject.
+
+---
+
+## Acceptance criteria
+
+- [ ] Compiled plan for subnet PRE unit contains `modelSelection: { kind: "profileChoice", key: "cheap/default" }` and no concrete `modelId` in authoritative fields.
+- [ ] `overlayUnitModelOnRequest` passes `cheap/default` to `runTask`, not `google/gemini-2.5-flash-lite`.
+- [ ] `resolveInvocationPlan` at compile preview may still show resolved wire for UI — not stored on executable plan.
+- [ ] Existing graphs with concrete snapshots: migration script or re-compile from authoring.
+
+---
+
+## Out of scope
+
+- Changing ai-profiles registry contents.
+- Banning concrete ids on ephemeral `RunTaskRequest.modelConfig` from direct API callers (see CR-2 for `skillModel` storage policy).

package/documenations/sessions/2026-06-08-subnets-model-resolution/CR-2-skillModel-profile-only-at-storage.md

@@ -0,0 +1,88 @@
+# CR-2 — `skillModel` profile/choice only at storage (align with PRE/POST)
+
+Status: **proposed**  
+Type: Change request  
+Owners: `@exellix/ai-tasks`, `@exellix/graph-engine`, `@x12i/graphenix-authoring-format`  
+Filed: 2026-06-08  
+Session: [README](./README.md)
+
+---
+
+## Summary
+
+Today:
+
+| Slot | Storage rule |
+|------|----------------|
+| `preActionModel` | profile/choice only ✓ |
+| `postActionModel` | profile/choice only ✓ |
+| `skillModel` | profile/choice **or** concrete wire id ✗ |
+
+There is no catalog field called "main model" (skill catalog stores no model — verified). The issue is **runtime/graph storage**: allowing **concrete** `skillModel` in graph JSON, fixtures, and plans freezes vendor slugs in orchestration data, separate from Catalox skill rows.
+
+**Change:** `skillModel` and MAIN `llmCall.model` MUST be profile/choice keys at storage and in graph plans. Concrete wire ids are produced only at invoke resolution (ai-tasks → ai-skills), identical to how xynthesis resolves PRE/POST.
+
+---
+
+## Problem
+
+- `BREAKING-CHANGES.md` (8.4+) still documents concrete ids on `skillModel` as accepted.
+- Fixtures use concrete MAIN models, e.g. `skillModel: "openrouter/x-ai/grok-4.1-fast"`.
+- Operators conflate "MAIN model" with a durable catalog property; it is only the **`skillModel` runtime slot** for the `mainSkill` execution unit.
+
+Desired model:
+
+- **Suggested profile** on skill catalog row (FR-1) → default hint for graph authoring.
+- **Per-node override** → `skillModel: "pro/default"` in plan.
+- **Invoke** → ai-tasks resolves to gateway wire id once before `runSkill`.
+
+---
+
+## Requirements
+
+### CR-2.1 — Validation
+
+- `validateRunTaskModelReferences` / `resolveRunTaskModelReferences`: reject concrete ids on `skillModel` and MAIN `llmCall.model` with `XYNTHESIS_CONCRETE_MODEL_REJECTED` equivalent: `SKILL_MODEL_CONCRETE_REJECTED`.
+- Message: use profile/choice (e.g. `pro/default`, `cyber/default`).
+
+### CR-2.2 — Resolution unchanged at invoke
+
+- `prepareMainSkillModelConfigForInvoke` continues to resolve profile → gateway wire (`openrouter/...`) immediately before ai-skills.
+- No behavior change for correctly authored graphs.
+
+### CR-2.3 — Graph authoring
+
+- Node model picker for MAIN unit: profile/choice only (same UX as PRE/POST).
+- Remove concrete model picker from persisted graph JSON.
+
+### CR-2.4 — Docs and fixtures
+
+- Update `ai-tasks/README.md`, `BREAKING-CHANGES.md`, test fixtures to profile-only `skillModel`.
+- Remove "concrete ids on MAIN only" exception language.
+
+---
+
+## Acceptance criteria
+
+- [ ] `skillModel: "openrouter/x-ai/grok-4.1-fast"` fails validation at `runTask` entry.
+- [ ] `skillModel: "pro/default"` resolves and invokes successfully.
+- [ ] `professional-answer` Catalox row still has **no** model field (only optional `suggestedProfile` per FR-1).
+- [ ] Graph-engine passes profile keys on `mainSkill` units.
+
+---
+
+## Migration
+
+| From | To |
+|------|-----|
+| `skillModel: "anthropic/claude-sonnet-4"` | `skillModel: "pro/default"` (or appropriate profile) |
+| `skillModel: "openrouter/x-ai/grok-4.1-fast"` | `skillModel: "cyber/default"` or explicit profile choice |
+
+Provide `resolveInvocationPlan` mapping table in migration notes for common concrete → profile mappings.
+
+---
+
+## Non-goals
+
+- Removing invoke-time resolution to concrete ids (still required for ai-gateway).
+- Changing Optimixer catalog fields on skill rows.

package/documenations/sessions/2026-06-08-subnets-model-resolution/CR-3-reject-concrete-models-in-catalog-rows.md

@@ -0,0 +1,76 @@
+# CR-3 — Reject concrete model ids in skill / funcx / xynthesis catalog rows
+
+Status: **proposed (guardrail)** — verified compliant today  
+Type: Change request  
+Owners: `@exellix/ai-skills`, `@x12i/funcx`, `@exellix/xynthesis`  
+Filed: 2026-06-08  
+Session: [README](./README.md)
+
+---
+
+## Summary
+
+**Verified 2026-06-08:** skill / funcx **content** catalogs do **not** store models today. This CR is a **preventive guardrail** (provision lint + schema), not remediation of a current data bug.
+
+Do not confuse with:
+
+- **Runtime** `modelConfig` / graph `modelSelection` (orchestrator data — see CR-1, CR-2).
+- **`@x12i/ai-tools` models catalog** (npm package used by funcx for slug validation — unrelated to Catalox skill rows).
+
+Catalog rows (Catalox `ai-skills`, funcx function defaults, xynthesis sidekick seeds) must **never** store a concrete LLM wire model as the authoritative model for a skill or action.
+
+Allowed:
+
+- `suggestedProfile` / `modelPick` as **`profile/choice`** (e.g. `pro/default`, `balanced/default`).
+- Optimixer sizing fields (output intent, reasoning effort catalog default, task type).
+
+Forbidden:
+
+- `model`, `modelId`, `mainModel`, `defaultModel` with values like `google/gemini-2.5-flash-lite`, `gpt-4o-mini`, `openrouter/...`.
+
+---
+
+## Current state (mono-repo audit 2026-06-08)
+
+| Catalog | Concrete model stored? | Profile suggestion? |
+|---------|------------------------|---------------------|
+| `ai-skills` Catalox (`AI_SKILLS_CATALOG_ITEMS`) | **No** ✓ | **No** (gap → FR-1) |
+| `xynthesis` `model-routing.json` | **No** ✓ (output sizing only) | N/A |
+| `xynthesis` Catalox seed (`modelPick`) | **No** ✓ | `balanced/default`, etc. |
+| funcx built-in / content catalog | Audit consumer + funcx repo | TBD |
+
+`professional-answer` row contains only Optimixer metadata — **compliant** with CR-3.
+
+---
+
+## Requirements
+
+### CR-3.1 — Schema validation at provision time
+
+- ai-skills `provision-ai-skills-catalog`: reject rows with `model`, `mainModel`, `defaultModel`, or concrete-pattern `modelId`.
+- xynthesis seed validators: allow only `modelPick` matching `profile/choice` regex.
+- funcx catalog linter: same rule for function `defaults.model`.
+
+### CR-3.2 — Runtime must not read catalog model for invoke
+
+- ai-skills `runSkill` model comes **only** from `RunSkillRequest.modelConfig.model` (set by orchestrator).
+- funcx `run()` / sidekick: model from request or `modelPick` profile resolved at invoke — never a frozen slug from catalog body.
+
+### CR-3.3 — Naming ban
+
+- Disallow field names `mainModel`, `defaultModel`, `skillModel` on catalog `data` objects (reserved for runtime request shape).
+
+---
+
+## Acceptance criteria
+
+- [ ] Provision script fails if a skill row includes `model: "google/..."`.
+- [ ] `professional-answer` provision unchanged (Optimixer-only).
+- [ ] Documentation lists allowed catalog model fields: `suggestedProfile` only (see FR-1).
+
+---
+
+## Related
+
+- FR-1 adds the **positive** allowed field.
+- CR-2 ensures graph/runtime `skillModel` is also profile-only at storage.

package/documenations/sessions/2026-06-08-subnets-model-resolution/FR-1-suggested-profile-in-catalogs.md

@@ -0,0 +1,96 @@
+# FR-1 — Suggested profile on skill and funcx catalog rows
+
+Status: **proposed**  
+Type: Feature request  
+Owners: `@exellix/ai-skills`, `@x12i/funcx`, `@exellix/xynthesis`  
+Filed: 2026-06-08  
+Session: [README](./README.md)
+
+---
+
+## Summary
+
+Add an optional **`suggestedProfile`** (or reuse xynthesis **`modelPick`**) on catalog rows: a single **`profile/choice`** string that recommends which ai-profiles tier fits this skill or sidekick action.
+
+This is a **hint for authoring and studio UIs** — not an invoke-time default that bypasses the orchestrator.
+
+---
+
+## Motivation
+
+- Operators want "what model tier fits `professional-answer`?" without storing concrete slugs.
+- Graph nodes should start from `suggestedProfile` when the author does not override `skillModel`.
+- Aligns with CR-3 (no concrete models in catalog) while supporting discoverability.
+
+---
+
+## Proposed shape
+
+### ai-skills Catalox row
+
+```json
+{
+  "skillKey": "professional-answer",
+  "suggestedProfile": "pro/default",
+  "optimixerReasoningEffort": "low",
+  "optimixerOutputIntent": { "mode": "relative", "expectedVisibleTokens": 1200 }
+}
+```
+
+### xynthesis sidekick seed (already similar)
+
+```json
+{
+  "defaults": {
+    "modelPick": "balanced/default",
+    "outputMode": "structured"
+  }
+}
+```
+
+Standardize naming in docs: **`suggestedProfile`** for skills, **`modelPick`** for xynthesis actions (alias in UI).
+
+---
+
+## Behavior
+
+| Layer | Behavior |
+|-------|----------|
+| **Catalog** | Store `suggestedProfile` only; validate `profile/choice` via `@x12i/ai-profiles`. |
+| **Studio / graph authoring** | New node MAIN unit pre-fills `modelSelection` from skill's `suggestedProfile`. |
+| **runTask / runSkill** | Orchestrator MUST still send `modelConfig.skillModel` (or plan unit selection). Catalog hint is **not** a silent default at invoke. |
+| **diagnoseSkillInCatalog** | Return `suggestedProfile` in diagnostic payload for tooling. |
+
+---
+
+## API sketch (ai-skills)
+
+```typescript
+type AiSkillsCatalogItemSpec = {
+  skillKey: string;
+  // ...
+  suggestedProfile?: string; // e.g. "pro/default"
+};
+```
+
+Export helper:
+
+```typescript
+function assertSuggestedProfile(value: string): void;
+```
+
+---
+
+## Acceptance criteria
+
+- [ ] `professional-answer` can ship with `suggestedProfile: "pro/default"` (product choice).
+- [ ] Provision rejects invalid profile keys and concrete slugs.
+- [ ] Invoke without `skillModel` still fails fast (no hidden catalog default).
+- [ ] Studio can list skills with suggested tier for graph palette.
+
+---
+
+## Non-goals
+
+- Auto-picking model at `runSkill` without orchestrator `modelConfig`.
+- Storing multiple ranked profiles (future: `suggestedProfiles[]` if needed).

package/documenations/sessions/2026-06-08-subnets-model-resolution/FR-2-graph-engine-failure-phase-attribution.md

@@ -0,0 +1,92 @@
+# FR-2 — Graph-engine failure phase attribution (PRE vs MAIN vs POST)
+
+Status: **proposed**  
+Type: Feature request  
+Owners: `@exellix/graph-engine`  
+Filed: 2026-06-08  
+Session: [README](./README.md)
+
+---
+
+## Summary
+
+When `runTask` fails, graph-engine should surface **`phase`** and **`stage`** from `@exellix/ai-tasks` `RunTaskExecutionError` (or root cause), not only `skillKey`.
+
+This session's confusion: error message referenced `skillKey=professional-answer` while the root cause was likely **PRE synthesis** (`cheap/default` → funcx catalog), not MAIN skill invoke.
+
+---
+
+## Problem
+
+Current wrapper shape (observed):
+
+```text
+runTask failed (skillKey=professional-answer nodeId=node:inbound-reachability graphId=graph:subnets-analysis): Unknown model "google/gemini-2.5-flash-lite" ...
+```
+
+ai-tasks native format includes phase when known:
+
+```text
+runTask failed (phase=pipeline_pre skillKey=...): ...
+```
+
+Graph-engine omits `phase=`, so operators assume **MAIN / professional-answer model** is wrong.
+
+---
+
+## Requirements
+
+### FR-2.1 — Error envelope
+
+Node execution error SHOULD include:
+
+```json
+{
+  "skillKey": "professional-answer",
+  "graphId": "graph:subnets-analysis",
+  "nodeId": "node:inbound-reachability",
+  "phase": "pipeline_pre",
+  "stage": "pre-synthesis",
+  "rootMessage": "Unknown model \"google/gemini-2.5-flash-lite\" ...",
+  "rootCode": "MISSING_ENV",
+  "modelConfig": {
+    "preActionModel": "cheap/default",
+    "skillModel": "pro/default",
+    "postActionModel": "cheap/default"
+  },
+  "failureClassification": { "role": "cause", "event": "provider_invoke" }
+}
+```
+
+### FR-2.2 — Propagation
+
+- Parse `RunTaskExecutionError.details.phase` when present.
+- Fall back to heuristic on `rootMessage` (funcx catalog → `pipeline_pre` or `pipeline_post`; gateway → `main_skill`).
+
+### FR-2.3 — UI copy
+
+- Display: **"PRE synthesis failed"** vs **"Skill invoke failed"** based on `phase`.
+- Do not show "professional-answer model error" when `phase !== main_skill`.
+
+---
+
+## Acceptance criteria
+
+- [ ] PRE funcx catalog failure shows `phase: "pipeline_pre"` in graph-engine node error JSON.
+- [ ] MAIN gateway failure shows `phase: "main_skill"`.
+- [ ] Same `skillKey` on wrapper; phase disambiguates.
+
+---
+
+## Reference (ai-tasks)
+
+- `RunTaskFailurePhase`: `pipeline_pre`, `main_skill`, `pipeline_post`, `model-resolution`, …
+- `formatRunTaskExecutionMessage` in `ai-tasks/src/errors/runTaskExecutionError.ts`
+- `classifyRunTaskFailure` in `ai-tasks/src/observability/classifyRunTaskFailure.ts`
+
+---
+
+## Non-goals
+
+- Changing ai-tasks error types (consume as-is).
+- Resolving catalog issues (see [INVESTIGATION-original-bug.md](./INVESTIGATION-original-bug.md)).

package/documenations/sessions/2026-06-08-subnets-model-resolution/INVESTIGATION-original-bug.md

@@ -0,0 +1,182 @@
+# Investigation: `Unknown model "google/gemini-2.5-flash-lite"`
+
+Status: **runtime / consumer deps** (skill catalog ruled out)  
+Filed: 2026-06-08  
+Repro: `worox-graphs-playground` — `graph:subnets-analysis`, `node:inbound-reachability`, `skillKey=professional-answer`  
+Verified: 2026-06-08 — **no models in skill/funcx content catalog**; runtime `cheap/default` → wire slug is correct.
+
+---
+
+## Executive summary
+
+| Question | Answer |
+|----------|--------|
+| Was `google/gemini-2.5-flash-lite` the authored input? | **No** — runtime uses `cheap/default`. |
+| Is `cheap/default` → `google/gemini-2.5-flash-lite` correct? | **Yes** — expected OpenRouter slug from `@x12i/ai-profiles` at **invoke time**. |
+| Did it come from the skill catalog? | **No** — Catalox skill rows store no model; verified. |
+| Which phase failed? | Almost certainly **PRE or POST xynthesis** (funcx), **not** MAIN `professional-answer` (ai-gateway). |
+| Why does the error say `skillKey=professional-answer`? | Graph-engine wraps the whole `runTask` failure under the node task key. |
+
+**Conclusion:** Runtime profile resolution is fine. If the error persists, it is **funcx + `@x12i/ai-tools` package catalog lookup** at invoke (or misleading phase in the error wrapper) — **not** skill catalog data and not wrong input from `cheap/default`.
+
+### “Catalog” disambiguation
+
+| Name | Role in this incident |
+|------|----------------------|
+| Catalox **ai-skills** catalog | Templates + Optimixer only — **not involved** |
+| **Runtime** `modelConfig` / graph plan | Source of `cheap/default` — **correct** |
+| `@x12i/ai-tools` **models catalog** (inside funcx) | Validates `google/gemini-2.5-flash-lite` at `ask()` — **only place “catalog-resolvable” applies** |
+
+---
+
+## Observed error
+
+```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: `@exellix/graph-engine` → `runTask` → root error from `@x12i/funcx` `requireCatalogModel()`.
+
+Exact funcx message shape (from `@x12i/funcx` ≥4.3):
+
+```text
+Unknown model "<slug>". Pass a catalog-resolvable model slug (e.g. "deepseek/deepseek-v4-flash").
+```
+
+ai-gateway / ai-tools `ModelResolutionError` uses a **different** message (`Could not resolve model "..." (provider: "...")`). So this failure is **not** the MAIN gateway path.
+
+---
+
+## Resolution chain (verified in mono-repo)
+
+### 1. ai-profiles: `cheap/default`
+
+Bundled registry (`@x12i/ai-profiles`):
+
+- Profile `cheap`, choice `default`
+- `provider: google`, `modelId: gemini-2.5-flash-lite`
+- OpenRouter invocation: `google/gemini-2.5-flash-lite`
+
+### 2. xynthesis: alias → bare OpenRouter slug
+
+`resolveXynthesisModel("cheap/default")` → `wireModelId: "google/gemini-2.5-flash-lite"`  
+Used by `FuncxInvoker.client.ask({ model: wireModelId })`.
+
+### 3. ai-tasks PRE step
+
+When `taskConfiguration.aiTaskStrategies.pre` includes synthesis, `_runSynthesizedContextPreStep` reads `modelConfig.preActionModel` (typically `cheap/default` for subnet-style graphs).
+
+Fixture pattern in this repo:
+
+```json
+"modelConfig": {
+  "preActionModel": "cheap/default",
+  "postActionModel": "cheap/default",
+  "skillModel": "<MAIN profile or concrete — separate from PRE>"
+}
+```
+
+### 4. MAIN professional-answer (different path)
+
+`skillModel` resolves to **gateway** wire id, e.g. `openrouter/google/gemini-2.5-flash-lite` — not the bare slug in the error.
+
+---
+
+## Failure hypothesis (ranked)
+
+### H1 — Stale `@x12i/ai-tools` / `@x12i/funcx` in `worox-graphs-playground` (most likely)
+
+funcx `requireCatalogModel()` calls ai-tools `createModelNameResolver(catalog).resolve()`. If the installed catalog predates `gemini-2.5-flash-lite`, or OpenRouter lane index is incomplete, `found: false` → this exact error.
+
+**Mono-repo reference versions (known good):**
+
+| Package | Version in `ai-tasks` |
+|---------|----------------------|
+| `@exellix/ai-tasks` | 9.0.3 |
+| `@exellix/xynthesis` | 4.6.4 |
+| `@x12i/funcx` (override) | ^4.6.0 |
+| `@x12i/ai-profiles` | ^3.3.0 |
+
+### H2 — funcx ai-tools client disabled or throws in catalog load
+
+funcx `resolveModelSlug` catches all errors and returns `found: false` — surfaces as "Unknown model" even when the slug is valid.
+
+Check env / config: FuncX ai-tools `enabled=false`, broken catalog fetch, etc.
+
+### H3 — Compile-time concrete slug injection (secondary)
+
+If graph plan has `resolvedInvocationSnapshot.modelId: "google/gemini-2.5-flash-lite"` on a PRE unit, behavior is the same at funcx — but **authoring** was still `cheap/default`. See CR-1.
+
+### H4 — Wrong phase in operator UI (symptom only)
+
+Operator reads "professional-answer failed" and assumes MAIN model is wrong. PRE failed before MAIN ran. See FR-2.
+
+---
+
+## Investigation checklist (`worox-graphs-playground`)
+
+Run in the consumer repo (not this mono-repo unless linked):
+
+- [ ] **1. Confirm runtime `modelConfig` on the failing node**
+  - `preActionModel`, `skillModel`, `postActionModel` on the `RunTaskRequest` graph-engine builds.
+  - Expect: `cheap/default` on PRE; MAIN slot may differ.
+
+- [ ] **2. Confirm compiled `nodePlan` for `node:inbound-reachability`**
+  - Per-unit `modelSelection` (`profileChoice` vs concrete).
+  - `resolvedInvocationSnapshot.modelId` — if present with concrete slug, note for CR-1.
+
+- [ ] **3. Lockfile versions**
+  ```bash
+  npm ls @x12i/funcx @x12i/ai-tools @exellix/xynthesis @exellix/ai-tasks @x12i/ai-profiles
+  ```
+  Compare to mono-repo `ai-tasks/package.json`.
+
+- [ ] **4. Catalog spot-check in installed tree**
+  ```bash
+  rg "gemini-2.5-flash-lite" node_modules/@x12i/ai-tools/dist/
+  ```
+  Should appear in bundled `models-catalog.json` chunk.
+
+- [ ] **5. Reproduce with trace**
+  - `executionMode: "trace"` on `runTask`.
+  - Look for xynthesis `wireModelId` / `profileChoiceKey: "cheap/default"` **before** any MAIN skill observation.
+  - If only PRE logs appear → confirms H4.
+
+- [ ] **6. Minimal isolated PRE call**
+  - xynthesis `executeXynthesisAction` with `model: "cheap/default"` and same env as playground.
+  - If fails → H1/H2. If passes → graph wiring or plan overlay issue.
+
+- [ ] **7. OPENROUTER_API_KEY**
+  - Required for OpenRouter backend; missing key causes other errors, but verify present.
+
+---
+
+## What is **not** the bug
+
+- Choosing `cheap/default` for PRE/POST.
+- ai-profiles mapping `cheap/default` → `google/gemini-2.5-flash-lite`.
+- xynthesis emitting bare OpenRouter slug to funcx (by design since xynthesis ≥4.1.8).
+- Skill / funcx **content** catalog storing or supplying a model (verified: **no models there**).
+- Confusing runtime resolved wire with catalog-authored model (there is no latter).
+
+---
+
+## Recommended fix path (consumer)
+
+1. Align `@x12i/funcx`, `@x12i/ai-tools`, `@exellix/xynthesis`, `@exellix/ai-tasks` to mono-repo versions (or newer).
+2. Re-run graph; if still failing, run checklist §5–6.
+3. If catalog is current and resolve still fails, file upstream bug on funcx/ai-tools with `resolveModelSlug` diagnostics (`attemptedStrategies`, `bestRejectedCandidate`).
+
+---
+
+## Related mono-repo references
+
+- PRE fixture: `ai-tasks/test/fixtures/run-task/graph-engine-pre-synthesis.json`
+- xynthesis wire: `xynthesis/src/funcxInvoker.ts`, `xynthesis/src/resolveAiProfileModel.ts`
+- funcx validation: `node_modules/@x12i/funcx/dist/src/serve.js` → `requireCatalogModel`
+- Error wrap: `ai-tasks/src/errors/runTaskExecutionError.ts`

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.3",
+  "version": "9.0.6",
   "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,11 @@
     "node": ">=20"
   },
   "overrides": {
-    "@x12i/funcx": "^4.6.0"
+    "@x12i/ai-tools": "^3.3.3",
+    "@x12i/ai-profiles": "^3.4.0"
   },
   "dependencies": {
-    "@exellix/ai-skills": "^6.5.4",
+    "@exellix/ai-skills": "^6.7.0",
     "@exellix/memorix-narrix-adapter": "^2.0.0",
     "@exellix/narrix-adapter-chat": "^2.0.0",
     "@exellix/narrix-adapter-docs": "^2.0.0",
@@ -75,9 +76,10 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.6.4",
+    "@exellix/xynthesis": "^4.6.7",
     "@x12i/activix": "^8.6.2",
-    "@x12i/ai-profiles": "^3.3.0",
+    "@x12i/ai-profiles": "^3.4.0",
+    "@x12i/funcx": "^4.9.6",
     "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
     "@x12i/execution-memory-manager": "^1.2.0",