@exellix/ai-tasks 8.5.0 → 8.5.3

package/.docs/ai-tasks-model-profile-aliases-7x.md

@@ -41,18 +41,39 @@ Unknown profile keys fail at **`resolveAIProfile`** with a clear error.
 
 ## Resolution boundaries
 
-| Path | Fields | Normalized by |
-|------|--------|---------------|
-| Xynthesis (PRE/POST/scoping/utilities) | `preActionModel`, `postActionModel`, step `llmCall.model` | `resolveModelReferenceForXynthesis` → `toStrictAiProfileResolveInput` |
-| ai-skills MAIN | `skillModel`, `RunTaskRequest.llmCall.model` | `resolveModelReference` → concrete `provider/model` |
+| Path | Fields at ingress (before `resolveRunTaskModelReferences`) | Internal transform |
+|------|----------------------------------------------------------|--------------------|
+| **PRE / POST (xynthesis)** | `preActionModel`, `postActionModel`, step `llmCall.model` — **ai-profiles alias required** | `resolveModelReferenceForXynthesis` → `profile/choice` keys only |
+| **MAIN (ai-skills)** | `skillModel`, root `llmCall.model` — alias **or** concrete provider id | `resolveModelReference` → concrete `provider/model` for gateway |
 
 Concrete ids (`openrouter/...`, `anthropic/claude-...`, `openai/gpt-5`) pass through on **`skillModel`** only. PRE/POST must stay ai-profiles aliases under `@exellix/xynthesis` ≥ 4.3.1.
 
+### Ingress rule for hosts (graph-engine, studio BFF)
+
+> **Do not** pre-resolve `preActionModel` or `postActionModel` to OpenRouter/OpenAI model ids. Pass through profile keys, `profile/choice`, or shortcut keys (e.g. `cheap`, `cheap/default`).
+
+> **`skillModel`** may still be a concrete provider id at ingress.
+
+### Internal rule (ai-tasks)
+
+> `resolveRunTaskModelReferences` is the **only** place that transforms aliases on xynthesis paths at `runTask` entry. If a concrete id is detected on a xynthesis slot, ai-tasks fails with stable code **`XYNTHESIS_CONCRETE_MODEL_REJECTED`** (typed `RunTaskModelResolutionError`, not a generic wrapper).
+
+### Stable pre-MAIN error codes
+
+| Condition | `error.code` |
+|-----------|--------------|
+| Concrete id on xynthesis slot | `XYNTHESIS_CONCRETE_MODEL_REJECTED` |
+| Unknown / unresolvable alias | `XYNTHESIS_ALIAS_RESOLUTION_FAILED` |
+| PRE synthesis enabled but required paths empty | `SYNTHESIS_INPUT_EMPTY` |
+
+Failures emit logxer diagnostics with `failureClassification.role: "cause"` and event ids such as `xynthesis_concrete_model_rejected`. Hosts (graph-engine CR-7) should preserve `error.code` and `failureClassification` on attempt records instead of collapsing to `TASK_RUN_FAILED` / `classification: other`.
+
 ## graph-engine guidance
 
 - Send the triplet on every node/task compile — no env defaults, no `"balanced"` fallback.
 - Prefer explicit **`profile/choice`** keys in compiled payloads; bare profile keys are OK (ai-tasks normalizes before xynthesis).
-- Optional: pre-resolve aliases in graph-engine for diagnostics; ai-tasks re-resolves at invoke (idempotent for concrete ids).
+- **Do not** pre-resolve `preActionModel` / `postActionModel` to concrete provider ids — pass aliases and let ai-tasks normalize at `runTask` entry (see ingress rule above).
+- Optional: pre-resolve **`skillModel`** aliases for diagnostics; ai-tasks re-resolves at invoke (idempotent for concrete ids).
 - Do **not** npm-override `@x12i/ai-profiles` or pin `<2.1`.
 
 ## Stack minimums
@@ -69,6 +90,7 @@ Concrete ids (`openrouter/...`, `anthropic/claude-...`, `openai/gpt-5`) pass thr
 - `toStrictAiProfileResolveInput` — bare profile → `profile/default`
 - `resolveModelReference` / `resolveModelReferenceForXynthesis`
 - `isResolvableModelAlias` — true for known **`profile/choice`** keys only
+- `RunTaskModelResolutionError`, `isRunTaskModelResolutionError` — stable pre-MAIN model slot failures
 - `listAiTasksProfileChoices`, `listAiTasksProfiles`, `listAiTasksProfileChoiceKeys`
 
 See [README — Model profile aliases](../README.md#model-profile-aliases-x12iai-profiles).

package/CHANGELOG.md

@@ -20,21 +20,17 @@ The published **npm version** always matches **`version`** in [`package.json`](p
 
 - `setFuncxExecutionStrategyInvoker`, `setResearchPlanQuestionsFuncxInvoker`, direct `@x12i/funcx` dependency.
 
-## [Unreleased]
+## [8.5.3] - 2026-06-04
 
-### Changed (breaking)
-
-- **`RunTaskRequest.modelConfig` is required** on every `runTask()` call (all three slots). No env-based or hardcoded model defaults (`SYNTHESIS_MODEL`, `AUDIT_MODEL`, `POST_STEP_MODEL`, `"balanced"`, etc.) for model selection.
-
-### Fixed
+### Changed
 
-- **PRE/MAIN model routing:** Root `RunTaskRequest.llmCall` is **MAIN-only** — no longer copied into PRE synthesis compile. When `llmCall.model` duplicates `preActionModel` while `skillModel` differs (graph-engine PRE leakage), MAIN uses `skillModel`. Validation warning `MODEL_CONFIG_LLM_CALL_PRE_MAIN_COLLISION`.
+- Bumped **`@exellix/xynthesis`** to **^4.4.5** and **`@exellix/ai-skills`** to **^6.0.2** for Optimixer **max-token retry** on PRE/POST (xynthesis) and MAIN (ai-skills): one automatic re-invoke when output hits the token limit and Optimixer returns **`retryPrediction`** (no host **`maxTokens`** required).
 
-## [8.4.0] - 2026-06-01
+### Added
 
-### Changed (breaking)
+- Unit test **`runPostStepLlmCall.maxTokenRetry.test.ts`** (mock Optimixer + synthesis invoker; no live LLM).
 
-- **`RunTaskRequest.modelConfig`:** **3-slot triplet only** — `preActionModel`, `skillModel`, `postActionModel`. **`xynthesisModel` removed** (validation rejects with `NON_CANONICAL_MODEL_CONFIG`). PRE uses `preActionModel`; POST uses `postActionModel`.
+## [8.4.0] - 2026-06-01 — `preActionModel`, `skillModel`, `postActionModel`. **`xynthesisModel` removed** (validation rejects with `NON_CANONICAL_MODEL_CONFIG`). PRE uses `preActionModel`; POST uses `postActionModel`.
 - **`@x12i/ai-profiles` ^2.0.0:** Required `catalogLane` on profile resolution; ai-tasks defaults `"text"` ( `"image"` for `vision` ). Registry source defaults to `auto`.
 - **`@exellix/xynthesis` ^4.2.1:** Minimum for ai-profiles v2 alignment.
 

package/README.md

@@ -1071,8 +1071,8 @@ Orchestrators send **model** + **sampling** + **`reasoningEffort`** + (for xynth
 
 | Phase | Package | Caller sends | Package owns |
 |-------|---------|--------------|--------------|
-| **MAIN** | `@exellix/ai-skills` ≥6 | `modelConfig` → `{ model, temperature, topP, reasoningEffort, … }` | Optimixer + Catalox skill catalog (`maxTokens` on `ModelConfig` is rejected) |
-| **PRE / POST / scoping / utility** | `@exellix/xynthesis` ≥4.3 | `outputExpectation` (required on every hop), optional `reasoningEffort`, `temperature`, `topP` | `resolveEffectiveMaxTokens` inside `executeXynthesisAction` |
+| **MAIN** | `@exellix/ai-skills` ≥6 | `modelConfig` → `{ model, temperature, topP, reasoningEffort, … }` | Optimixer + Catalox skill catalog (`maxTokens` on `ModelConfig` is rejected); **one automatic re-invoke** when output hits token limit and Optimixer returns `retryPrediction` |
+| **PRE / POST / scoping / utility** | `@exellix/xynthesis` ≥4.3 | `outputExpectation` (required on every hop), optional `reasoningEffort`, `temperature`, `topP` | `resolveEffectiveMaxTokens` inside `executeXynthesisAction`; **same one-shot max-token retry** via Optimixer `retryPrediction` |
 
 **Xynthesis `outputExpectation`** is sizing/density **intent** for Optimixer — not a literal token count. ai-tasks resolves a per-stage default when the caller omits it (`resolveOutputExpectation` / `resolveLlmOutputExpectationForXynthesis`).
 
@@ -1123,10 +1123,11 @@ Concrete ids (`openrouter/...`, `anthropic/claude-sonnet-4`, `openai/gpt-5`, …
 
 **Client impact:**
 
-- **No change** if you already send concrete provider model ids.
-- **New:** you may send ai-profiles aliases on `modelConfig`, `llmCall.model`, and pipeline step configs — graph-engine no longer has to pre-resolve every alias before `runTask` (hosts that already resolve can keep doing so; double resolution is a no-op for concrete ids).
-- **Validation:** alias tokens on `modelConfig` slots are accepted; unknown aliases fail at resolution with a clear error.
-- **Helpers:** `resolveModelReference`, `resolveRunTaskModelReferences`, `isResolvableModelAlias` (true only for **`profile/choice`** keys — bare profile keys are resolved at invoke, not sync-listed).
+- **`skillModel` / MAIN `llmCall.model`:** concrete provider ids pass through unchanged (alias or concrete accepted).
+- **`preActionModel` / `postActionModel`:** must be ai-profiles aliases — **do not** send concrete OpenRouter/OpenAI ids (rejected with `XYNTHESIS_CONCRETE_MODEL_REJECTED`).
+- **New:** you may send ai-profiles aliases on `modelConfig`, `llmCall.model`, and pipeline step configs — graph-engine must not pre-resolve xynthesis slots to concrete ids.
+- **Validation:** alias tokens on `modelConfig` slots are accepted; unknown aliases fail at resolution with `XYNTHESIS_ALIAS_RESOLUTION_FAILED`.
+- **Helpers:** `resolveModelReference`, `resolveRunTaskModelReferences`, `isRunTaskModelResolutionError`, `isResolvableModelAlias` (true only for **`profile/choice`** keys — bare profile keys are resolved at invoke, not sync-listed).
 
 Resolution uses the ai-profiles registry (`auto`: remote refresh with bundled fallback). See [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md).
 

package/RUNTASK_REQUEST.md

@@ -95,7 +95,7 @@ Properties are classified for **default MAIN path** unless noted. Inherited **`R
 | `inputs` | Optional plural task payload (`string` or object). Dual-root parity with `input`; smart-input **`inputs.*`** resolves here (not `executionMemory.inputs`). |
 | `variables` | Job/graph template bucket; forwarded as-is on MAIN (see [Canonical input bucket](#canonical-input-bucket)). |
 | `jobMemory`, `taskMemory` | Enriched and forwarded; see executor payload. |
-| `modelConfig` | **Canonical slots:** `preActionModel` + `skillModel` + `postActionModel`. **Aliases accepted on wire** (ai-profiles names + legacy tiers); resolved inside `runTask()` via [`resolveRunTaskModelReferences`](src/utils/resolveRunTaskModelReferences.ts). **`skillModel`** → concrete id for ai-skills MAIN; **`preActionModel`** / **`postActionModel`** → **alias only** for xynthesis PRE/POST (concrete ids rejected under `@exellix/xynthesis` ≥4). Legacy `model` and **`xynthesisModel`** rejected. |
+| `modelConfig` | **Canonical slots:** `preActionModel` + `skillModel` + `postActionModel`. **Aliases accepted on wire** (ai-profiles names + legacy tiers); resolved inside `runTask()` via [`resolveRunTaskModelReferences`](src/utils/resolveRunTaskModelReferences.ts). **`skillModel`** → concrete id for ai-skills MAIN; **`preActionModel`** / **`postActionModel`** → **alias only** for xynthesis PRE/POST (concrete ids rejected under `@exellix/xynthesis` ≥4 with code **`XYNTHESIS_CONCRETE_MODEL_REJECTED`**). Legacy `model` and **`xynthesisModel`** rejected. See [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md). |
 | `llmCall` | **MAIN override only** at root (`llmCall.model` wins over `skillModel` unless it duplicates `preActionModel` while `skillModel` differs — see collision guard). Not copied into PRE synthesis compile; use `preActionModel` or `executionPipeline[pre].config.llmCall` for PRE. Merged into ai-skills `modelConfig` at MAIN execution boundary. |
 | `timeoutMs` | Forwarded when set (also overlaid from `llmCall.timeoutMs`). |
 | `coreSkillId` | Maps to `skillId` on `RunSkillRequest` for gateway. |

package/dist/core/task-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-sdk.d.ts","sourceRoot":"","sources":["../../src/core/task-sdk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAazD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAuB,MAAM,mBAAmB,CAAC;AA2BzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA2OxD,KAAK,iBAAiB,GAAG,mBAAmB,CAAC;AA0S7C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF,qBAAa,gBAAgB;IAIzB,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;gBAGjC,YAAY,EAAE,iBAAiB,EACjC,QAAQ,EAAE;QACzB,OAAO,CAAC,OAAO,GAAG,GAAG,EACnB,KAAK,EAAE,GAAG,EACV,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;KACtC,EACD,OAAO,CAAC,EAAE,uBAAuB;IAQ7B,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAkmDtF;;OAEG;YACW,6BAA6B;IAshB3C;;;;;OAKG;YACW,cAAc;CAyR7B"}
+{"version":3,"file":"task-sdk.d.ts","sourceRoot":"","sources":["../../src/core/task-sdk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAazD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAuB,MAAM,mBAAmB,CAAC;AA2BzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA4OxD,KAAK,iBAAiB,GAAG,mBAAmB,CAAC;AA0S7C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF,qBAAa,gBAAgB;IAIzB,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;gBAGjC,YAAY,EAAE,iBAAiB,EACjC,QAAQ,EAAE;QACzB,OAAO,CAAC,OAAO,GAAG,GAAG,EACnB,KAAK,EAAE,GAAG,EACV,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;KACtC,EACD,OAAO,CAAC,EAAE,uBAAuB;IAQ7B,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAkmDtF;;OAEG;YACW,6BAA6B;IAshB3C;;;;;OAKG;YACW,cAAc;CAyR7B"}

package/dist/core/task-sdk.js

@@ -47,6 +47,7 @@ import { llmCallEnvPrefix, resolveLlmCall } from "../post-steps/resolvePostStepC
 import { buildXynthesisWorkScopeIdentity } from "../internal/buildXynthesisWorkScopeIdentity.js";
 import { getPostActionModelFromSlots, resolvePreActionModel } from "../utils/routeModelConfigSlots.js";
 import { assertPhaseModelAlias } from "../errors/modelConfigRequiredError.js";
+import { isRunTaskModelResolutionError } from "../errors/runTaskModelResolutionError.js";
 import { resolveRunTaskModelReferences } from "../utils/resolveRunTaskModelReferences.js";
 import { runPostStepLlmCall } from "../internal/runPostStepLlmCall.js";
 registerBuiltInLocalTasks();
@@ -439,11 +440,6 @@ export class WorexClientTasks {
         }
     }
     async runTask(input) {
-        const compiled = compileTaskConfigurationOnRunTaskRequest(input);
-        input = await resolveRunTaskModelReferences(compiled.request);
-        emitRunTaskRequestWarnings(input);
-        assertRequiredRunSkillCorrelation(input);
-        assertValidSmartInputConfig(input.smartInput, input.skillKey);
         const traceCollector = input.executionMode === "trace" ? createDebugTraceCollector() : null;
         const withTrace = (result) => {
             if (!traceCollector)
@@ -454,16 +450,21 @@ export class WorexClientTasks {
             };
         };
         return runAiTasksWithObservabilityContext({ logging: this.stackLogging }, async () => {
-            const failContext = () => ({
-                skillKey: input.skillKey,
-                jobId: input.jobId,
-                taskId: input.taskId,
-                graphId: input.graphId,
-                nodeId: input.nodeId,
-                agentId: input.agentId,
-                modelConfig: input.modelConfig,
+            const failContext = (req) => ({
+                skillKey: req.skillKey,
+                jobId: req.jobId,
+                taskId: req.taskId,
+                graphId: req.graphId,
+                nodeId: req.nodeId,
+                agentId: req.agentId,
+                modelConfig: req.modelConfig,
             });
             try {
+                const compiled = compileTaskConfigurationOnRunTaskRequest(input);
+                input = await resolveRunTaskModelReferences(compiled.request);
+                emitRunTaskRequestWarnings(input);
+                assertRequiredRunSkillCorrelation(input);
+                assertValidSmartInputConfig(input.smartInput, input.skillKey);
                 // `@exellix/ai-skills` requires stable ids on each gateway request; callers may omit for simple runs.
                 const taskId = input.taskId?.trim() ? input.taskId : randomUUID();
                 const jobId = input.jobId?.trim() ? input.jobId : randomUUID();
@@ -1801,7 +1802,8 @@ export class WorexClientTasks {
             catch (error) {
                 throw logAndEnrichRunTaskFailure({
                     cause: error,
-                    ...failContext(),
+                    ...(isRunTaskModelResolutionError(error) ? { phase: "model-resolution" } : {}),
+                    ...failContext(input),
                 });
             }
         });