@exellix/ai-tasks 8.4.3 → 8.5.2

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

@@ -4,6 +4,22 @@ 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.
 
+## [8.5.0] - 2026-06-03
+
+### Changed (breaking)
+
+- **Execution strategies:** planner/optimizer invoke **`@exellix/xynthesis` ≥ 4.4.0** (`execution-plan`, `execution-evaluate-result`) with `modelConfig.preActionModel` / `postActionModel`. Removed direct `@x12i/funcx` `run()` from ai-tasks.
+- **`runPlanWebScopeQuestions`:** xynthesis `plan-web-scope-questions` only; removed `backend: "funcx"`.
+- **Catalog:** `runtimeKind: "xynthesis-action"`, `defaultSidekickAction` on planner/optimizer rows.
+
+### Added
+
+- `runPlannerViaXynthesis`, `runOptimizerViaXynthesis`, `setExecutionStrategyActionInvoker`, `setPlanWebScopeQuestionsActionInvoker`, `resolveSafeExecutionStrategyCatalogDefaultSidekickAction`.
+
+### Removed
+
+- `setFuncxExecutionStrategyInvoker`, `setResearchPlanQuestionsFuncxInvoker`, direct `@x12i/funcx` dependency.
+
 ## [Unreleased]
 
 ### Changed (breaking)

package/README.md

@@ -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;IA6kDtF;;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

@@ -2,8 +2,9 @@
 import { randomUUID } from "crypto";
 import { resolveRunTaskRuntimeKnobs, } from "../internal/resolveRunTaskRuntimeKnobs.js";
 import { applyOptimizerFeedbackToRequest, applyPlannerOutputToRequest } from "../execution-strategies/applyExecutionStrategyOutputs.js";
-import { buildExecutionStrategyRequestPayload, runOptimizerFuncx, runPlannerFuncx, } from "../execution-strategies/runFuncxExecutionStrategy.js";
-import { resolveSafeExecutionStrategyCatalogDefaultFunctionId } from "../execution-strategies/executionStrategyCatalogMetadata.js";
+import { buildExecutionStrategyRequestPayload } from "../execution-strategies/executionStrategyRequestPayload.js";
+import { runOptimizerViaXynthesis, runPlannerViaXynthesis, } from "../execution-strategies/runExecutionStrategyViaXynthesis.js";
+import { resolveSafeExecutionStrategyCatalogDefaultSidekickAction } from "../execution-strategies/executionStrategyCatalogMetadata.js";
 import { SYNTHESIZED_CONTEXT } from "../types/index.js";
 import { runAuditPostStep } from "../post-steps/audit/runAudit.js";
 import { buildRunTaskResultMetaFromModelId } from "../invocation/buildRunTaskResultMeta.js";
@@ -46,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();
@@ -438,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)
@@ -453,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();
@@ -718,33 +720,45 @@ export class WorexClientTasks {
                             coreSkillId: working.coreSkillId,
                             includeContextInPrompt: working.includeContextInPrompt,
                         });
-                        const catalogDefaultFunctionId = resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, spec);
-                        const plannerOut = await runPlannerFuncx({
+                        const catalogDefaultSidekickAction = resolveSafeExecutionStrategyCatalogDefaultSidekickAction(req.executionStrategyCatalogItems, spec);
+                        const plannerOut = await runPlannerViaXynthesis({
                             args: spec.args,
                             requestPayload: payload,
-                            defaultFunctionId: catalogDefaultFunctionId,
+                            modelConfig: req.modelConfig,
+                            jobId: working.jobId,
+                            taskId: working.taskId,
+                            agentId: working.agentId,
+                            workScopeIdentity: buildXynthesisWorkScopeIdentity({
+                                jobId: working.jobId,
+                                taskId: working.taskId,
+                                agentId: working.agentId,
+                                graphId: working.graphId,
+                                nodeId: working.nodeId,
+                                prevNodeId: working.prevNodeId,
+                                coreSkillId: working.coreSkillId,
+                            }),
                         });
                         working = applyPlannerOutputToRequest(working, plannerOut, pi);
                         prefixSteps.push({
                             step: prefixSteps.length + 1,
                             id: `executionStrategy.planner.${pi}`,
                             ok: true,
-                            summary: "FuncX planner (execution/plan)",
+                            summary: "xynthesis planner (execution-plan)",
                             outputExcerpt: {
                                 hasInstructions: typeof plannerOut.instructions === "string",
                                 hasPrompt: typeof plannerOut.prompt === "string",
                                 variableKeys: plannerOut.variables ? Object.keys(plannerOut.variables).slice(0, 20) : [],
-                                functionIdSource: typeof spec.args?.functionId === "string"
-                                    ? "invocation"
-                                    : catalogDefaultFunctionId
-                                        ? "catalog"
-                                        : "code-default",
+                                sidekickActionSource: catalogDefaultSidekickAction
+                                    ? "catalog"
+                                    : spec.strategyKey === "planner"
+                                        ? "execution-plan"
+                                        : "execution-evaluate-result",
                             },
                         });
                         if (traceCollector) {
                             traceCollector.push({
                                 taskType: "pre-execution",
-                                details: "execution strategy planner (FuncX)",
+                                details: "execution strategy planner (xynthesis)",
                                 metadata: {
                                     ...baseTraceMeta(),
                                     phase: "execution_strategy_planner",
@@ -776,9 +790,21 @@ export class WorexClientTasks {
                             skillKey: last.skillKey,
                             metadata: last.metadata ? summarizeForOuter(last.metadata, 6_000) : undefined,
                         };
-                        const evalOut = await runOptimizerFuncx({
+                        const evalOut = await runOptimizerViaXynthesis({
                             args: primary.args,
-                            defaultFunctionId: resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, primary),
+                            modelConfig: req.modelConfig,
+                            jobId: working.jobId,
+                            taskId: working.taskId,
+                            agentId: working.agentId,
+                            workScopeIdentity: buildXynthesisWorkScopeIdentity({
+                                jobId: working.jobId,
+                                taskId: working.taskId,
+                                agentId: working.agentId,
+                                graphId: working.graphId,
+                                nodeId: working.nodeId,
+                                prevNodeId: working.prevNodeId,
+                                coreSkillId: working.coreSkillId,
+                            }),
                             requestPayload: buildExecutionStrategyRequestPayload({
                                 skillKey: working.skillKey,
                                 input: working.input,
@@ -802,7 +828,7 @@ export class WorexClientTasks {
                         if (traceCollector) {
                             traceCollector.push({
                                 taskType: "ai-task",
-                                details: "execution strategy optimizer (FuncX)",
+                                details: "execution strategy optimizer (xynthesis)",
                                 metadata: {
                                     ...baseTraceMeta(),
                                     phase: "execution_strategy_optimizer",
@@ -1776,7 +1802,8 @@ export class WorexClientTasks {
             catch (error) {
                 throw logAndEnrichRunTaskFailure({
                     cause: error,
-                    ...failContext(),
+                    ...(isRunTaskModelResolutionError(error) ? { phase: "model-resolution" } : {}),
+                    ...failContext(input),
                 });
             }
         });