@exellix/ai-tasks 8.0.0 → 8.0.7

package/BREAKING-CHANGES.md

@@ -26,9 +26,24 @@ See [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-
 
 ## Unreleased (synced runtime model)
 
+### `@x12i/ai-profiles` — in-package model alias resolution
+
+- **`@x12i/ai-profiles`** is a dependency. Profile aliases on `modelConfig` (`xynthesisModel`, `skillModel`), `llmCall.model`, and pipeline step configs are **resolved inside ai-tasks** before xynthesis (`executeXynthesisAction`) and ai-skills (`runSkill`) calls.
+- **Concrete provider model ids are unchanged** — pass-through, no migration for callers already using `openrouter/...`, `anthropic/...`, etc.
+- **New capability:** send ai-profiles names (`cheap`, `balanced`, `pro`, `cheapest`, …) or legacy tiers (`weak`, `strong`, `default`) directly on `RunTaskRequest`; graph-engine pre-resolution is optional.
+- **Validation:** alias tokens on `modelConfig` slots are **accepted** (replaces 8.0.0 behavior that rejected `weak` / `strong` / `default` with `MODEL_CONFIG_NOT_RESOLVED`).
+- **Exports:** `resolveModelReference`, `resolveRunTaskModelReferences`, `isResolvableModelAlias`, `formatResolvedProfileModelId`.
+
+See [README — Model profile aliases](./README.md#model-profile-aliases-x12iai-profiles) and [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md).
+
+### `@exellix/xynthesis` ≥ 4.0 and `@exellix/ai-skills` ≥ 5.8
+
+- Requires **`@exellix/xynthesis` ≥ 4.0.1** and **`@exellix/ai-skills` ≥ 5.8.1** (see `package.json`).
+- **`executeXynthesisAction`** (xynthesis 4.x) accepts **ai-profiles aliases only** (`balanced`, `cheapest`, `json`, …) — not concrete `provider/model` ids. ai-tasks keeps **`modelConfig.xynthesisModel`** and xynthesis **`llmCall.model`** as aliases; **`skillModel`** / MAIN gateway models still resolve to concrete ids for **`@exellix/ai-skills`**.
+- Optional upstream entry **`runXynthesisAiAction`** (Catalox-backed templates) is not used by ai-tasks yet; this package still materializes prompts and calls **`executeXynthesisAction`**.
+
 ### `@exellix/xynthesis` ≥ 3.6: `runSynthesisCall` removed
 
-- Requires **`@exellix/xynthesis` ≥ 3.6.4** (see `package.json`).
 - **`runSynthesisCall`** and **`RunSynthesisCallOpts`** are **removed** upstream. Use **`executeXynthesisAction`** with **`ExecuteXynthesisActionRequest`** (`gateway`, `prompts`, `workScope`, plus optional `model`, `maxTokens`, `timeoutMs`, …).
 - **`@exellix/ai-tasks`** no longer re-exports a `runSynthesisCall` alias. Public exports: **`executeXynthesisAction`**, **`setSynthesisInvoker`**, **`getSynthesisInvoker`**, plus type **`ExecuteXynthesisActionRequest`** (result type: import from **`@exellix/xynthesis`** or **`@exellix/xynthesis/ai-actions`**).
 - Post-step LLM helpers (`runPostStepLlmCall`, audit, polish, scoping) call **`executeXynthesisAction`** internally. Tests still mock via **`setSynthesisInvoker`**.
@@ -37,7 +52,7 @@ See [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-
 
 - **`RunTaskRequest.executionStrategies`** is **required**: an array of `{ strategyKey: "planner" \| "optimizer", phase: "before" \| "after", priority: number, maxIterations?, args? }`. Use **`[]`** for plain MAIN (same behavior as the former default `executionStrategyKey: "direct"`).
 - **`executionStrategyKey`** has been **removed** from types, schema, and metadata. **`response.metadata.executionStrategiesSummary`** replaces it (before/after key lists and optional `primaryOptimizerMaxIterations`).
-- Default FuncX function ids for planner/optimizer (**generic envelope**, **`run()`** from `@x12i/funcx/functions`): **`execution/plan`**, **`execution/evaluate-result`**. Use **`@x12i/funcx` ≥ 3.8.2** so **`getRunJsonResult`** matches planner/optimizer unwrap behavior (normalization fixes landed in **3.8.2**). Export constants: **`FUNCX_EXECUTION_PLAN_FUNCTION_ID`**, **`FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`**. Override via each invocation’s `args.functionId` only when the target accepts the **same** envelope (`goal`, `input`, `context`, `result?`, `args`, `attribution`).
+- Default FuncX function ids for planner/optimizer (**generic envelope**, **`run()`** from `@x12i/funcx/functions`): **`execution/plan`**, **`execution/evaluate-result`**. Use **`@x12i/funcx` ≥ 4.2.0** (re-exports **`getRunJsonResult`**, **`buildAskAttribution`**, and **`FUNCX_*_FUNCTION_ID`** constants from `@x12i/funcx/functions`). Override via each invocation’s `args.functionId` only when the target accepts the **same** envelope (`goal`, `input`, `context`, `result?`, `args`, `attribution`).
 
 ### `runTask` ordering: Narrix before pipeline PRE
 

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.
 
+## [Unreleased]
+
+### Added
+
+- **Model profile aliases (`@x12i/ai-profiles`):** Resolve ai-profiles profile/shortcut names and legacy tiers (`weak`, `strong`, `default`) to concrete provider model ids for **ai-skills MAIN** (`skillModel` / `llmCall.model`). Keep **ai-profiles aliases** on **xynthesis** paths (`modelConfig.xynthesisModel`, POST/PRE/scoping `llmCall.model`). Exports: `resolveModelReference`, `resolveModelReferenceForXynthesis`, `normalizeXynthesisModelAlias`, `resolveRunTaskModelReferences`, `isResolvableModelAlias`, `formatResolvedProfileModelId`.
+
+### Changed
+
+- **`@exellix/xynthesis` ^4.0.1:** Xynthesis LLM calls use alias-only model resolution (`resolveModelReferenceForXynthesis`); default post-step model is **`balanced`** when omitted. **`skillModel`** resolution for **`@exellix/ai-skills` ^5.8.1** unchanged.
+- **`@x12i/funcx` ^4.2.0:** Execution-strategy function ids are re-exported from `@x12i/funcx/functions` (`FUNCX_EXECUTION_PLAN_FUNCTION_ID`, etc.). Runtime integration unchanged: `createClient` + `run()` + `getRunJsonResult` / `unwrapFuncxRunValue` for planner, optimizer, and optional `research/plan-questions`.
+- **Validation:** `modelConfig` slots accept known profile aliases (no longer `MODEL_CONFIG_NOT_RESOLVED` for `weak` / `strong` / `default`).
+
+### Documentation
+
+- README — [Model profile aliases](#model-profile-aliases-x12iai-profiles); [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md).
+
 ## [7.7.1] - 2026-05-25
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 Private Git/npm package for executing **tasks** using the Woreces execution stack.
 
-**Breaking — `executionStrategies` (required):** Every `runTask` request must include **`executionStrategies`**: an array of FuncX MAIN wrappers or **`[]`** for plain gateway MAIN. The old **`executionStrategyKey`** field is removed. See [BREAKING-CHANGES.md](BREAKING-CHANGES.md) and [RUNTASK_REQUEST.md](RUNTASK_REQUEST.md). Supported MAIN execution is exactly: **direct** via **`executionStrategies: []`**, **planner** before MAIN, **optimizer** after MAIN, or planner + optimizer together. Default FuncX function ids (generic envelope via **`run()`**, **`@x12i/funcx` ≥ 3.8.2** recommended): **`execution/plan`**, **`execution/evaluate-result`** (overridable via each row’s `args.functionId` when the alternate implementation uses the **same** envelope). Planner/optimizer responses are normalized with **`getRunJsonResult`** from `@x12i/funcx/functions` (also re-exported from this package as **`unwrapFuncxRunValue`** → **`getRunJsonResult`**).
+**Breaking — `executionStrategies` (required):** Every `runTask` request must include **`executionStrategies`**: an array of FuncX MAIN wrappers or **`[]`** for plain gateway MAIN. The old **`executionStrategyKey`** field is removed. See [BREAKING-CHANGES.md](BREAKING-CHANGES.md) and [RUNTASK_REQUEST.md](RUNTASK_REQUEST.md). Supported MAIN execution is exactly: **direct** via **`executionStrategies: []`**, **planner** before MAIN, **optimizer** after MAIN, or planner + optimizer together. Default FuncX function ids (generic envelope via **`run()`**, **`@x12i/funcx` ≥ 4.2.0** recommended): **`execution/plan`**, **`execution/evaluate-result`** (overridable via each row’s `args.functionId` when the alternate implementation uses the **same** envelope). Planner/optimizer responses are normalized with **`getRunJsonResult`** from `@x12i/funcx/functions` (also re-exported from this package as **`unwrapFuncxRunValue`** → **`getRunJsonResult`**).
 
 **FuncX catalog / hosting:** Those function ids must exist in your FuncX content resolver for live **`run()`** calls — see [`documenations/funcx-catalog-hosting-checklist.md`](documenations/funcx-catalog-hosting-checklist.md).
 
@@ -1077,13 +1077,58 @@ The legacy `llmCall.maxTokens` field is still accepted as an alias for `maxToken
 
 ---
 
+## Model profile aliases (`@x12i/ai-profiles`)
+
+`@exellix/ai-tasks` resolves **profile aliases** to concrete provider model ids via [`@x12i/ai-profiles`](https://www.npmjs.com/package/@x12i/ai-profiles) at execution time. This applies to **both** execution paths:
+
+| Path | Slot / field | Resolved before |
+|------|----------------|-----------------|
+| **Xynthesis** (PRE synthesis, POST audit/polish, AI scoping, utilities) | `xynthesisModel`, `SynthesisConfig.llmCall.model`, `AuditConfig.llmCall.*`, `PolishConfig.llmCall`, `RunUtilityRequest.exec.model`, env fallbacks (`SYNTHESIS_MODEL`, `AUDIT_MODEL`, …) | `executeXynthesisAction` / `runPostStepLlmCall` |
+| **ai-skills MAIN** | `skillModel`, `RunTaskRequest.llmCall.model` | `runSkill` (via `DirectExecutionStrategy`) |
+
+**Accepted alias shapes:**
+
+- **ai-profiles profiles:** `cheap`, `fast`, `balanced`, `deep`, `pro`, `json`, `agentic`, `research`
+- **ai-profiles shortcuts:** `cheapest`, `default`, `best`, `standard`, `thinking`, `schema`, `agent`, `web-research`, … (see `@x12i/ai-profiles` README)
+- **Legacy graph tiers:** `weak` → `cheap`, `strong` → `pro`, `default` → `balanced`
+
+**Example (aliases on the request — resolved inside `runTask`):**
+
+```typescript
+await runTask({
+  skillKey: "tasks/analysis",
+  agentId: "agent-1",
+  jobTypeId: "analysis-job",
+  taskTypeId: "analysis-task",
+  executionStrategies: [],
+  input: { topic: "Q1 risks" },
+  modelConfig: {
+    xynthesisModel: "cheap",   // PRE synthesis → e.g. google/gemini-2.5-flash-lite
+    skillModel: "balanced",    // MAIN skill    → e.g. openai/gpt-5.4
+  },
+});
+```
+
+Concrete ids (`openrouter/...`, `anthropic/claude-sonnet-4`, `openai/gpt-5`, …) pass through unchanged.
+
+**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.
+- **Optional helpers** (for hosts/tests): `resolveModelReference`, `resolveRunTaskModelReferences`, `isResolvableModelAlias`.
+
+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).
+
+---
+
 ## LLM call configuration (`LlmCallConfig`)
 
 `LlmCallConfig` is the per-stage override knob set. On MAIN it composes with `RunTaskRequest.modelConfig` slots (`skillModel` / `xynthesisModel`) — when both are set, `llmCall.*` wins.
 
 ```typescript
 type LlmCallConfig = {
-  model?: string;             // provider/model id
+  model?: string;             // provider/model id or @x12i/ai-profiles alias (resolved at call time)
   maxTokensCap?: number;      // HARD CEILING for resolveMaxTokens (does NOT disable automation)
   maxTokens?: number;         // alias for maxTokensCap (backward compat)
   temperature?: number;
@@ -2080,11 +2125,11 @@ interface ModelConfig {
 }
 ```
 
-**Example:**
+**Example (concrete ids or aliases):**
 ```typescript
 const modelConfig = {
-  xynthesisModel: "openai/gpt-5-nano",
-  skillModel: "openai/gpt-5",
+  xynthesisModel: "cheap",      // or "openai/gpt-5-nano"
+  skillModel: "balanced",       // or "openai/gpt-5"
   temperature: 0.7,
   maxTokens: 2000,
   topP: 0.9
@@ -2098,7 +2143,7 @@ const result = await runTask({
 });
 ```
 
-**Note:** Root `RunTaskRequest.modelConfig` uses canonical slots (`RunTaskModelConfig`). See [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md).
+**Note:** Root `RunTaskRequest.modelConfig` uses canonical slots (`RunTaskModelConfig`: `xynthesisModel` + `skillModel`). Profile aliases are resolved via `@x12i/ai-profiles` at `runTask` entry and on each xynthesis / ai-skills call boundary. See [Model profile aliases](#model-profile-aliases-x12iai-profiles) and [`.docs/ai-tasks-model-profile-aliases-7x.md`](.docs/ai-tasks-model-profile-aliases-7x.md).
 
 ### `JobHistory`, `TaskHistory`, and `ExecutionHistory`
 

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;AAiQzF,KAAK,iBAAiB,GAAG,mBAAmB,CAAC;AA0S7C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAEzB,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADN,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;IAGG,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAghDtF;;OAEG;YACW,6BAA6B;IAqgB3C;;;;;OAKG;YACW,cAAc;CAuR7B"}
+{"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;AAyPzF,KAAK,iBAAiB,GAAG,mBAAmB,CAAC;AA0S7C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAEzB,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADN,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;IAGG,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAuhDtF;;OAEG;YACW,6BAA6B;IAmhB3C;;;;;OAKG;YACW,cAAc;CAuR7B"}

package/dist/core/task-sdk.js

@@ -35,7 +35,9 @@ import { createDebugTraceCollector, traceWrap } from "../observability/debugTrac
 import { loadSynthesisTemplates, buildSynthesisSystemPrompt, buildSynthesisUserPrompt, resolveSourceMaterial, resolveSourceMaterialParts, getRenderedTemplates, buildSynthesizedContextMarkdown, resolveSynthesisQuestion, runStructuredSynthesisGatewayCallRobust, getContextSynthesizer, normalizeAndValidateSynthesizedPayload, discoverTemplateCores, } from "../synthesis/index.js";
 import { resolveOutputExpectation as resolveOutputExpectationXynthesis } from "@exellix/xynthesis/ai-actions";
 import { llmCallEnvPrefix, resolveLlmCall } from "../post-steps/resolvePostStepConfig.js";
+import { buildXynthesisWorkScopeIdentity } from "../internal/buildXynthesisWorkScopeIdentity.js";
 import { getSkillModelFromSlots, resolveXynthesisModelForPre } from "../utils/routeModelConfigSlots.js";
+import { resolveRunTaskModelReferences } from "../utils/resolveRunTaskModelReferences.js";
 import { runPostStepLlmCall } from "../internal/runPostStepLlmCall.js";
 registerBuiltInLocalTasks();
 const DEFAULT_SYNTH_INPUT_MAX_CHARS = 200_000;
@@ -131,13 +133,6 @@ function withDefaultDecisionValidation(request) {
         },
     };
 }
-/** Runtime `request.identity` forwarded to xynthesis synthesis calls (not from step config). */
-function synthesisIdentityFromRequest(request) {
-    const id = request.identity;
-    if (id == null || typeof id !== "object")
-        return undefined;
-    return id;
-}
 /** When the skills client has no `enrichMemoriesWithScoping` (semver drift), pass memory through unchanged. */
 async function passthroughEnrichMemories(_id, _level, bundle) {
     return {
@@ -442,7 +437,7 @@ export class WorexClientTasks {
     }
     async runTask(input) {
         const compiled = compileTaskConfigurationOnRunTaskRequest(input);
-        input = compiled.request;
+        input = await resolveRunTaskModelReferences(compiled.request);
         emitRunTaskRequestWarnings(input);
         assertRequiredRunSkillCorrelation(input);
         assertValidSmartInputConfig(input.smartInput, input.skillKey);
@@ -1667,6 +1662,13 @@ export class WorexClientTasks {
                             jobId: request.jobId,
                             taskId: request.taskId,
                             skillKey: request.skillKey,
+                            agentId: request.agentId,
+                            graphId: request.graphId,
+                            nodeId: request.nodeId,
+                            prevNodeId: request.prevNodeId,
+                            coreSkillId: request.coreSkillId,
+                            masterSkillId: request.masterSkillId,
+                            identity: request.identity,
                         }),
                         onSuccessUpdates: (polishResult) => ({
                             totalPasses: polishResult.metadata?.totalPasses,
@@ -1833,7 +1835,7 @@ export class WorexClientTasks {
         };
         const synthLlmCall = resolveLlmCall(synthLlmCallInput, llmCallEnvPrefix("SYNTHESIS"), {}, {
             outputExpectation: resolveOutputExpectationXynthesis("synthesis"),
-            model: "gpt-5-nano",
+            model: "balanced",
             timeoutMs: 30_000,
         });
         const model = synthLlmCall.model;
@@ -1847,6 +1849,17 @@ export class WorexClientTasks {
                 synthLlmCalls.push(obs);
             }
             : undefined;
+        const workScopeIdentity = buildXynthesisWorkScopeIdentity({
+            jobId: request.jobId,
+            taskId: request.taskId,
+            agentId: request.agentId,
+            graphId: request.graphId,
+            nodeId: request.nodeId,
+            prevNodeId: request.prevNodeId,
+            coreSkillId: request.coreSkillId,
+            masterSkillId: request.masterSkillId,
+            identity: request.identity,
+        });
         if (config.questionDriven === true) {
             const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
             const nonEmptyString = (v) => {
@@ -1974,6 +1987,7 @@ export class WorexClientTasks {
                         jobId: request.jobId,
                         taskId: request.taskId,
                         agentId: request.agentId,
+                        workScopeIdentity,
                         traceCollector,
                         traceTask: traceCollector
                             ? {
@@ -2091,6 +2105,7 @@ export class WorexClientTasks {
                         jobId: request.jobId,
                         taskId: request.taskId,
                         agentId: request.agentId,
+                        identity: workScopeIdentity,
                     });
                 }
                 const contextMarkdown = buildSynthesizedContextMarkdown(payload);
@@ -2132,6 +2147,7 @@ export class WorexClientTasks {
                 jobId: request.jobId,
                 taskId: request.taskId,
                 agentId: request.agentId,
+                workScopeIdentity,
                 traceCollector,
                 traceTask: traceCollector
                     ? {