@exellix/ai-tasks 8.4.1 → 8.4.2

package/README.md

@@ -11,7 +11,7 @@ Private Git/npm package for executing **tasks** using the Woreces execution stac
 | Package | Role in `runTask` | Minimum |
 |---------|-------------------|---------|
 | `@x12i/ai-profiles` | Profile/shortcut → wire model (`catalogLane` required on resolve) | **2.1.0** |
-| `@exellix/xynthesis` | PRE synthesis, POST audit/polish, scoping, utilities (`executeXynthesisAction`) | **4.3.0** |
+| `@exellix/xynthesis` | PRE synthesis, POST audit/polish, scoping, utilities (`executeXynthesisAction`) | **≥ 4.3.1** (4.3.0 breaks import with ai-profiles 2.1 — see [upstream §0](./documenations/upstream-feature-requests/xynthesis-orchestrator-invoke-contract-4.2.md)) |
 | `@exellix/ai-skills` | MAIN `runSkill` (Optimixer caps, `ModelConfig.reasoningEffort`) | **6.0.0** |
 
 Use explicit **ai-profiles** profile keys (`cheap`, `pro`, `cyber`, …) or **shortcuts** (`cheapest`, `default`, …) or **`profile/choice`** keys — not removed sync helpers or legacy tier aliases.

package/documenations/upstream-feature-requests/README.md

@@ -7,7 +7,8 @@ Fix reports filed for sibling packages. Hand these to the package owners; after
 | Package | Document | Status |
 |---------|----------|--------|
 | `@exellix/ai-skills` 6.0 | [ai-skills-orchestrator-invoke-contract-5.9.md](./ai-skills-orchestrator-invoke-contract-5.9.md) | **shipped** — `ModelConfig.reasoningEffort` |
-| `@exellix/xynthesis` 4.3 | [xynthesis-orchestrator-invoke-contract-4.2.md](./xynthesis-orchestrator-invoke-contract-4.2.md) | **shipped** — `reasoningEffort` on `ExecuteXynthesisActionRequest` (xynthesis should drop `isKnownProfileOrShortcut` import for ai-profiles 2.1) |
+| `@exellix/xynthesis` 4.3 | [**xynthesis-ai-profiles-2.1-import-break.md**](./xynthesis-ai-profiles-2.1-import-break.md) | **P0 blocked** — **4.3.0** breaks `import "@exellix/xynthesis"` with ai-profiles **2.1.0**; need **≥ 4.3.1** |
+| `@exellix/xynthesis` 4.3 | [xynthesis-orchestrator-invoke-contract-4.2.md](./xynthesis-orchestrator-invoke-contract-4.2.md) | **partial** — `reasoningEffort` shipped in 4.3.0; import break tracked in CR above |
 | `@x12i/ai-profiles` 2.1 | — | **shipped** — `catalogLane` required; sync `isKnownProfileOrShortcut` removed (safer — resolve at invoke) |
 | `@exellix/ai-tasks` | [ai-tasks-wrap-up-after-upstream.md](./ai-tasks-wrap-up-after-upstream.md) | **done** in 8.4 — no legacy tiers; resolve at invoke via `resolveAIProfile` |
 

package/documenations/upstream-feature-requests/ai-tasks-wrap-up-after-upstream.md

@@ -1,6 +1,6 @@
 # `@exellix/ai-tasks` — wrap-up after upstream invoke-contract fixes
 
-Status: **blocked** on **@exellix/xynthesis ≥ 4.3.1** fixing ai-profiles 2.1 import ([§0](./xynthesis-orchestrator-invoke-contract-4.2.md)); invoke-contract items below are otherwise shipped in **ai-skills 6.0** / **xynthesis 4.3**:
+Status: **blocked** on **@exellix/xynthesis ≥ 4.3.1** ([xynthesis-ai-profiles-2.1-import-break.md](./xynthesis-ai-profiles-2.1-import-break.md)); invoke-contract items below are otherwise shipped in **ai-skills 6.0** / **xynthesis 4.3**:
 
 - [`ai-skills-orchestrator-invoke-contract-5.9.md`](./ai-skills-orchestrator-invoke-contract-5.9.md)
 - [`xynthesis-orchestrator-invoke-contract-4.2.md`](./xynthesis-orchestrator-invoke-contract-4.2.md)
@@ -107,8 +107,8 @@ flowchart LR
 
 Recommended sequence:
 
-1. Merge **xynthesis** + **ai-skills** contract PRs (can be parallel).
-2. Bump `package.json` minimums in ai-tasks.
+1. Merge **xynthesis** ai-profiles 2.1 import fix (**≥ 4.3.1**) + **ai-skills** contract PRs (can be parallel).
+2. Bump `package.json`: `"@exellix/xynthesis": "^4.3.1"` (minimum — **do not** ship ai-tasks 8.4.x consumer release on **4.3.0**).
 3. Execute **this wrap-up** checklist in one ai-tasks PR.
 4. Release note in **8.4.x** or **8.5.0** with graph-engine migration (drop `maxTokensCap` on task payloads if removed).
 

package/documenations/upstream-feature-requests/xynthesis-ai-profiles-2.1-import-break.md

@@ -0,0 +1,324 @@
+# `@exellix/xynthesis` — ai-profiles 2.1 import break (`isKnownProfileOrShortcut` removed)
+
+Status: **open — blocks all consumers**  
+Owner: `@exellix/xynthesis`  
+Filed by: `@exellix/ai-tasks`  
+Target release: **`@exellix/xynthesis` ≥ 4.3.1**  
+Reproduced with: `@exellix/xynthesis` **4.3.0** (broken), `@x12i/ai-profiles` **2.1.0** (required by `@x12i/ai-tools` ≥ 2.4)  
+Consumers blocked: `@exellix/ai-tasks` **8.4.x**, graph-engine import tests, any app that `import "@exellix/xynthesis"`
+
+Related: [`xynthesis-orchestrator-invoke-contract-4.2.md §0`](./xynthesis-orchestrator-invoke-contract-4.2.md) (invoke-contract track — this CR is the **P0 runtime fix**)
+
+---
+
+## Summary
+
+**`@exellix/xynthesis@4.3.0`** imports and re-exports **`isKnownProfileOrShortcut`** from **`@x12i/ai-profiles`**. That symbol was **removed from the package root in ai-profiles 2.1.0** (replaced by **`isKnownProfileChoice`** and strict **`profile/choice`** resolution).
+
+With the current Exellix stack pinned to ai-profiles **2.1.0**, **module load fails before any API call**:
+
+```text
+SyntaxError: The requested module '@x12i/ai-profiles' does not provide an export named 'isKnownProfileOrShortcut'
+```
+
+**Not an ai-profiles bug** — 2.1.0 intentionally dropped sync alias guessing.  
+**Not an ai-tasks bug** — ai-tasks already migrated to ai-profiles 2.1 APIs.  
+**Not fixable in consumers** — npm `overrides`, deep imports of `dist/isKnownProfileOrShortcut.js`, or pinning ai-profiles `<2.1` violate the no-legacy invoke contract and break `@x12i/ai-tools`.
+
+**Required:** xynthesis **4.3.1** patch — adopt ai-profiles 2.1 resolve input normalization (same pattern as ai-tasks 8.4).
+
+---
+
+## Impact
+
+| Path | Symptom |
+|------|---------|
+| `import "@exellix/xynthesis"` | **SyntaxError** at ESM link time |
+| `import "@exellix/ai-tasks"` | Same — ai-tasks depends on xynthesis |
+| graph-engine / consumer test suites | Fail at import; no `runTask()` coverage |
+| `executeXynthesisAction({ model: "cheap", … })` | Would fail at resolve **after** import fix if resolve path is not updated |
+
+---
+
+## Reproduction
+
+### Minimal (any Node 20+ project with both packages installed)
+
+```bash
+npm i @exellix/xynthesis@4.3.0 @x12i/ai-profiles@2.1.0
+node -e "import('@exellix/xynthesis').then(() => console.log('ok')).catch(e => console.error(e))"
+# SyntaxError: ... does not provide an export named 'isKnownProfileOrShortcut'
+```
+
+### From ai-tasks repo
+
+```bash
+cd ai-tasks
+npm install   # tree dedupes ai-profiles@2.1.0
+node -e "import('@exellix/xynthesis')"
+npm run test  # fails at import / dist-test compile depending on test graph
+```
+
+### Dependency tree (why ai-profiles cannot be downgraded)
+
+```text
+@exellix/ai-tasks
+├── @x12i/ai-profiles@2.1.0
+├── @exellix/xynthesis@4.3.0  → imports isKnownProfileOrShortcut ✗
+├── @exellix/ai-skills@6.0.0  → ai-profiles@2.1.0
+└── @x12i/funcx@4.3.3         → ai-profiles@2.1.0
+    └── @exellix/xynthesis (transitive)
+        └── @x12i/ai-tools@2.4.0 → requires ai-profiles 2.1 (formatProfileChoiceKey)
+```
+
+---
+
+## Root cause (xynthesis 4.3.0)
+
+### 1. Broken ESM import / re-export
+
+**File:** `src/index.ts` (compiled to `dist/index.js`)
+
+```ts
+export {
+  resolveAIProfile,
+  isKnownProfileOrShortcut,  // ← removed from ai-profiles 2.1 root
+  listAIProfiles,
+  listAIShortcuts,
+} from "@x12i/ai-profiles";
+```
+
+**File:** `src/resolveAiProfileModel.ts`
+
+```ts
+import { isKnownProfileOrShortcut, resolveAIProfile } from "@x12i/ai-profiles";
+
+export function assertKnownModelAlias(input: string): void {
+  // ...
+  if (!isKnownProfileOrShortcut(key)) {
+    throw new Error(`xynthesis: unknown model alias "${key}"…`);
+  }
+}
+```
+
+Because **`index.ts` re-exports the missing symbol**, Node fails while linking `@exellix/xynthesis` — even callers that never use `assertKnownModelAlias`.
+
+### 2. Stale resolve input shape (secondary — fails after import fix)
+
+**File:** `src/resolveAiProfileModel.ts` — `resolveXynthesisModel`
+
+```ts
+const profile = await resolveAIProfile(alias, mergedOptions);
+```
+
+ai-profiles **2.1.0** rejects bare profile keys:
+
+```text
+Unknown profile/choice key: cheap. Use "profile/choice" (e.g. "cheap/default") or a shortcut that pins both.
+```
+
+Orchestrators (graph-engine, ai-tasks) still send **`preActionModel: "cheap"`** / **`postActionModel: "cheap"`** on the wire. ai-tasks expands at invoke via `formatProfileChoiceKey(profile, "default")`; xynthesis must do the same before `resolveAIProfile`.
+
+---
+
+## Recommended fix (xynthesis ≥ 4.3.1)
+
+**No consumer workarounds.** Fix belongs entirely in `@exellix/xynthesis`.
+
+### Step 1 — Bump dependency
+
+```json
+"@x12i/ai-profiles": "^2.1.0"
+```
+
+### Step 2 — Add ai-profiles 2.1 input normalization helper
+
+Mirror **`@exellix/ai-tasks`** `src/utils/aiProfileModelFormat.ts` (`toStrictAiProfileResolveInput`). Suggested new file **`src/aiProfileResolveInput.ts`**:
+
+```ts
+import {
+  formatProfileChoiceKey,
+  isKnownProfileChoice,
+  isProfileChoiceKeyFormat,
+} from "@x12i/ai-profiles";
+
+/** Map caller alias → ai-profiles 2.1 `resolveAIProfile` input. */
+export function toStrictAiProfileResolveInput(profileSlot: string, explicitChoice?: string): string {
+  const trimmed = profileSlot.trim();
+  if (!trimmed) return trimmed;
+
+  if (explicitChoice?.trim()) {
+    return formatProfileChoiceKey(trimmed, explicitChoice.trim());
+  }
+
+  const at = trimmed.indexOf("@");
+  if (at > 0) {
+    const profile = trimmed.slice(0, at).trim();
+    const choice = trimmed.slice(at + 1).trim();
+    return choice
+      ? formatProfileChoiceKey(profile, choice)
+      : formatProfileChoiceKey(profile, "default");
+  }
+
+  if (isProfileChoiceKeyFormat(trimmed) || isKnownProfileChoice(trimmed)) {
+    return trimmed;
+  }
+
+  // Bare profile key (e.g. "cheap") → default choice ("cheap/default")
+  return formatProfileChoiceKey(trimmed, "default");
+}
+
+/** Sync bundled-registry check after normalization (shortcuts + profile/choice keys). */
+export function isKnownXynthesisModelAlias(input: string): boolean {
+  const trimmed = input.trim();
+  if (!trimmed) return false;
+  const resolveInput = toStrictAiProfileResolveInput(trimmed);
+  return isKnownProfileChoice(resolveInput);
+}
+```
+
+### Step 3 — Update `resolveAiProfileModel.ts`
+
+```ts
+import { resolveAIProfile } from "@x12i/ai-profiles";
+import {
+  isKnownXynthesisModelAlias,
+  toStrictAiProfileResolveInput,
+} from "./aiProfileResolveInput.js";
+
+export function assertKnownModelAlias(input: string): void {
+  const key = normalizeAliasInput(input);
+  if (!key) {
+    throw new Error("xynthesis: model alias must be a non-empty string");
+  }
+  if (!isKnownXynthesisModelAlias(key)) {
+    throw new Error(
+      `xynthesis: unknown model alias "${key}". Use profile/choice (e.g. cheap/default), profile@choice, or a shortcut (cheapest, default, json).`
+    );
+  }
+}
+
+export async function resolveXynthesisModel(input, options) {
+  // ... existing guards ...
+  const alias = normalizeAliasInput(input);
+  const resolveInput = toStrictAiProfileResolveInput(alias);
+  const profile = await resolveAIProfile(resolveInput, mergedOptions);
+  // ... rest unchanged ...
+}
+```
+
+### Step 4 — Fix public re-exports in `index.ts`
+
+**Remove** `isKnownProfileOrShortcut` from the ai-profiles re-export block.
+
+**Preferred replacement:**
+
+```ts
+export {
+  resolveAIProfile,
+  isKnownProfileChoice,
+  formatProfileChoiceKey,
+  listAIProfiles,
+  listAIShortcuts,
+} from "@x12i/ai-profiles";
+```
+
+**Breaking note for xynthesis CHANGELOG:** `isKnownProfileOrShortcut` re-export removed; use `isKnownProfileChoice` + `toStrictAiProfileResolveInput` (exported from xynthesis) or import directly from `@x12i/ai-profiles`.
+
+Optionally export `toStrictAiProfileResolveInput` / `isKnownXynthesisModelAlias` from the package root if downstream tools relied on xynthesis as the ai-profiles facade.
+
+### Step 5 — Tests (xynthesis)
+
+Extend **`test/resolveAiProfileModel.unit.ts`**:
+
+```ts
+import assert from "node:assert/strict";
+import { isKnownXynthesisModelAlias, toStrictAiProfileResolveInput } from "../src/aiProfileResolveInput.js";
+import { resolveXynthesisModel, assertKnownModelAlias } from "../src/resolveAiProfileModel.js";
+
+// Import smoke (add dedicated test file if needed)
+await import("../dist/index.js"); // must not throw with ai-profiles 2.1 peer
+
+assert.equal(toStrictAiProfileResolveInput("cheap"), "cheap/default");
+assert.equal(isKnownXynthesisModelAlias("cheap"), true);
+assert.equal(isKnownXynthesisModelAlias("cheapest"), true);
+assert.throws(() => assertKnownModelAlias("not-a-profile"));
+
+const resolved = await resolveXynthesisModel("cheap", {
+  source: "bundled",
+  preferOpenRouter: false,
+  openrouterApiKeyPresent: false,
+});
+assert.ok(resolved?.wireModelId.includes("/"));
+```
+
+Add **`test/aiProfiles21Import.unit.ts`**:
+
+```ts
+await import("@exellix/xynthesis"); // ESM link test
+```
+
+Run full suite with **`@x12i/ai-profiles@2.1.0`** installed (not 2.0.x).
+
+---
+
+## Explicitly rejected (no workarounds)
+
+| Approach | Why rejected |
+|----------|--------------|
+| Consumer npm `overrides` pinning ai-profiles 2.0.x | Breaks `@x12i/ai-tools` / `formatProfileChoiceKey`; violates stack alignment |
+| Deep import `@x12i/ai-profiles/dist/isKnownProfileOrShortcut.js` | Private path; not in package exports |
+| ai-profiles 2.1.1 re-export shim only | Pushes debt upstream; xynthesis still passes bare keys to `resolveAIProfile` |
+| graph-engine / ai-tasks patch | Wrong layer — xynthesis owns PRE/POST model resolve |
+
+---
+
+## After xynthesis 4.3.1 ships — ai-tasks follow-up
+
+1. `"@exellix/xynthesis": "^4.3.1"` in `@exellix/ai-tasks` `package.json`
+2. `npm install && npm run test`
+3. Patch release **8.4.x** updating README / BREAKING-CHANGES minimums
+
+See [`ai-tasks-wrap-up-after-upstream.md`](./ai-tasks-wrap-up-after-upstream.md).
+
+---
+
+## Paste-ready GitHub issue (xynthesis repo)
+
+**Title:** ai-profiles 2.1: remove `isKnownProfileOrShortcut` import; normalize profile resolve input
+
+**Labels:** `bug`, `ai-profiles`, `breaking`, `P0`
+
+**Body:**
+
+> `@exellix/xynthesis@4.3.0` fails to load with `@x12i/ai-profiles@2.1.0`:
+>
+> ```
+> SyntaxError: The requested module '@x12i/ai-profiles' does not provide an export named 'isKnownProfileOrShortcut'
+> ```
+>
+> Blocks `@exellix/ai-tasks@8.4.x` and graph-engine import tests.
+>
+> **Fix (4.3.1):**
+> 1. Remove `isKnownProfileOrShortcut` import/re-export; use ai-profiles 2.1 APIs.
+> 2. Normalize bare profile keys (`cheap` → `cheap/default`) before `resolveAIProfile` — see ai-tasks `toStrictAiProfileResolveInput`.
+> 3. Bump `@x12i/ai-profiles` peer to `^2.1.0`; add import + resolve unit tests.
+>
+> Full spec: [link to this doc in ai-tasks repo]
+
+**Acceptance criteria:**
+
+- [ ] `node -e "import('@exellix/xynthesis')"` succeeds with `@x12i/ai-profiles@2.1.0`.
+- [ ] `resolveXynthesisModel("cheap", { source: "bundled" })` returns a wire model id (no `UNKNOWN_PROFILE_CHOICE`).
+- [ ] `assertKnownModelAlias("cheap")` does not throw; `assertKnownModelAlias("not-a-profile")` throws.
+- [ ] `isKnownProfileOrShortcut` is **not** exported from `@exellix/xynthesis` root.
+- [ ] CHANGELOG entry; publish **4.3.1** (patch).
+
+---
+
+## Related
+
+- [`@exellix/ai-tasks` `src/utils/aiProfileModelFormat.ts`](../../src/utils/aiProfileModelFormat.ts) — reference implementation
+- [`.docs/ai-tasks-model-profile-aliases-7x.md`](../../.docs/ai-tasks-model-profile-aliases-7x.md) — wire shapes orchestrators send
+- [`BREAKING-CHANGES.md`](../../BREAKING-CHANGES.md) — 8.4.x blocked subsection
+- [`xynthesis-orchestrator-invoke-contract-4.2.md`](./xynthesis-orchestrator-invoke-contract-4.2.md) — invoke contract (reasoningEffort shipped; import fix is separate P0)

package/documenations/upstream-feature-requests/xynthesis-orchestrator-invoke-contract-4.2.md

@@ -10,13 +10,13 @@ Related (older, partially superseded): [`xynthesis-llm-observability.md`](./xynt
 
 ---
 
-## 0. Blocker: `isKnownProfileOrShortcut` import vs ai-profiles 2.1.0
+## 0. Blocker: ai-profiles 2.1 import break — **see dedicated CR**
 
-**`@exellix/xynthesis@4.3.0`** (and **4.2.x**) still import and re-export **`isKnownProfileOrShortcut`** from **`@x12i/ai-profiles`**. That symbol was **removed from the package root in ai-profiles 2.1.0** (implementation remains under `dist/isKnownProfileOrShortcut.js`).
+**P0 — tracked in [`xynthesis-ai-profiles-2.1-import-break.md`](./xynthesis-ai-profiles-2.1-import-break.md).**
 
-With **`@x12i/ai-profiles@2.1.0`** (required by **`@x12i/ai-tools`** for `formatProfileChoiceKey`), **`import "@exellix/xynthesis"` fails at runtime** before any `executeXynthesisAction` call.
+**`@exellix/xynthesis@4.3.0`** breaks `import "@exellix/xynthesis"` with **`@x12i/ai-profiles@2.1.0`** (`isKnownProfileOrShortcut` removed). Fix requires **≥ 4.3.1** with ai-profiles 2.1 resolve-input normalization — not a symbol rename only.
 
-**Ask:** Replace with **`isKnownProfileChoice`** + **`matchDiscoveryProfileInput`** (or re-export `isKnownProfileOrShortcut` from ai-profiles 2.1.1). Release **≥ 4.3.1**.
+**After publish — ai-tasks bump:** `"@exellix/xynthesis": "^4.3.1"`, test, patch release.
 
 ---
 
@@ -167,6 +167,8 @@ ai-tasks will follow whichever contract is published; default integration is **n
 
 ## Verification checklist (for xynthesis PR)
 
+- [ ] Replace `isKnownProfileOrShortcut` → `isKnownProfileChoice` (index re-export + `resolveAiProfileModel` / `assertKnownModelAlias`).
+- [ ] `import "@exellix/xynthesis"` succeeds with `@x12i/ai-profiles@2.1.0` installed.
 - [ ] `ExecuteXynthesisActionRequest.reasoningEffort` (and gateway wrappers).
 - [ ] Optimixer predict receives resolved `reasoningEffort`.
 - [ ] `temperature` + `topP` integration tests on `executeXynthesisAction` + structured gateway.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/ai-tasks",
-  "version": "8.4.1",
+  "version": "8.4.2",
   "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",
@@ -78,7 +78,7 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.3.0",
+    "@exellix/xynthesis": "^4.3.1",
     "@x12i/activix": "^8.5.0",
     "@x12i/ai-profiles": "^2.1.0",
     "@x12i/catalox": "^5.1.3",