@exellix/ai-tasks 8.2.5 → 8.4.0

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

@@ -0,0 +1,21 @@
+# Upstream feature requests (from `@exellix/ai-tasks`)
+
+Fix reports filed for sibling packages. Hand these to the package owners; after they ship, complete the ai-tasks wrap-up.
+
+## Invoke contract (8.4+) — **current priority**
+
+| Package | Document | Status |
+|---------|----------|--------|
+| `@exellix/ai-skills` ≥ 5.9 | [ai-skills-orchestrator-invoke-contract-5.9.md](./ai-skills-orchestrator-invoke-contract-5.9.md) | **open** — `reasoningEffort` on request |
+| `@exellix/xynthesis` ≥ 4.2 | [xynthesis-orchestrator-invoke-contract-4.2.md](./xynthesis-orchestrator-invoke-contract-4.2.md) | **open** — `reasoningEffort`, temperature/topP audit, docs |
+| `@exellix/ai-tasks` | [ai-tasks-wrap-up-after-upstream.md](./ai-tasks-wrap-up-after-upstream.md) | **blocked** on above |
+
+## Older / parallel tracks
+
+| Package | Document |
+|---------|----------|
+| `@exellix/ai-skills` | [ai-skills-llm-observability.md](./ai-skills-llm-observability.md) |
+| `@exellix/xynthesis` | [xynthesis-llm-observability.md](./xynthesis-llm-observability.md) |
+| `@x12i/logxer` | [logxer-failure-classification-and-causal-diagnostics.md](./logxer-failure-classification-and-causal-diagnostics.md) |
+| `@x12i/funcx` | [funcx-openrouter-model-id-pass-through.md](./funcx-openrouter-model-id-pass-through.md) |
+| `@exellix/xynthesis` | [xynthesis-openrouter-wire-model-double-prefix-bug.md](./xynthesis-openrouter-wire-model-double-prefix-bug.md) |

package/documenations/upstream-feature-requests/ai-skills-orchestrator-invoke-contract-5.9.md

@@ -0,0 +1,151 @@
+# `@exellix/ai-skills` — orchestrator invoke contract fixes (≥ 5.9)
+
+Status: **open** — blocks clean `@exellix/ai-tasks` 8.4+ integration  
+Owner: `@exellix/ai-skills`  
+Filed by: `@exellix/ai-tasks`  
+Consumer: `@exellix/ai-tasks` 8.4.0, graph-engine 7.x (`RunTaskRequest.modelConfig` triplet)  
+Pinned in ai-tasks today: `@exellix/ai-skills@5.9.11`
+
+Related (older, partially superseded): [`ai-skills-llm-observability.md`](./ai-skills-llm-observability.md)
+
+---
+
+## Summary
+
+**MAIN** skill invocation should follow the same contract as xynthesis 4.2+:
+
+| Orchestrator sends | Package owns internally |
+|--------------------|-------------------------|
+| Wire **model** (`model` / `modelId`) | — |
+| **temperature**, **topP**, other sampling knobs | — |
+| **reasoningEffort** (for Optimixer / provider) | — |
+| — | **max completion tokens** (Optimixer + Catalox catalog) |
+
+ai-skills **5.9.11 already enforces the right side** (`ModelConfig.maxTokens?: never`, Optimixer merge before invoke). The remaining gap is the **left side**: the public request must **ask for `reasoningEffort`**, not only read it from Catalox.
+
+---
+
+## Already correct in 5.9.11 (no change needed)
+
+### 1. Caller must not set completion token caps on `ModelConfig`
+
+- `ModelConfig.maxTokens` is typed `never` and validated/rejected at invoke.
+- `mergeOptimixerPredictionIntoModelConfig` / `skills-optimixer` set the effective cap.
+- Trace echo uses `maxTokensRequested` on `SkillDiagnosticsTrace`, not `invokeRequest.modelConfig.maxTokens`.
+
+**Acceptance (already met):** Hosts that pass `modelConfig: { model, temperature, topP }` without `maxTokens` succeed; hosts that pass `maxTokens` get a clear rejection or strip + anomaly log.
+
+### 2. Catalox catalog carries Optimixer metadata
+
+- `SkillOptimixerCatalogSpec` includes mandatory `reasoningEffort`, `outputIntent`, etc. (`skill-optimixer-catalog.ts`).
+
+---
+
+## Required fixes
+
+### 1. Accept `reasoningEffort` on `RunSkillRequest` (or explicit `ModelConfig` extension)
+
+#### Today
+
+- `reasoningEffort` exists only on the **Catalox `ai-skills` catalog row** (`SkillOptimixerCatalogSpec.reasoningEffort`).
+- `RunSkillRequest` / `ModelConfig` expose `model`, `temperature`, `topP`, … but **no `reasoningEffort`**.
+- `@exellix/ai-tasks` has nothing to forward from graph-engine / `llmCall` even when the operator configures it per task.
+
+#### Why it hurts
+
+Orchestrators (graph-engine, ai-tasks) are the **source of truth** for per-node tuning. Catalog defaults are not enough when one skill key is reused with different reasoning depth per graph node. xynthesis 4.2 already threads `reasoningEffort` into Optimixer predict input internally; ai-skills should expose the same knob on the **host-facing** API.
+
+#### Asked behavior
+
+Add optional:
+
+```typescript
+import type { OptimixerReasoningEffort } from "@x12i/optimixer";
+
+// Option A — on ModelConfig (preferred for parity with temperature/topP):
+interface ModelConfig {
+  // ...existing fields...
+  reasoningEffort?: OptimixerReasoningEffort;
+}
+
+// Option B — top-level on RunSkillRequest:
+interface RunSkillRequest {
+  reasoningEffort?: OptimixerReasoningEffort;
+}
+```
+
+**Resolution order** (document and implement consistently):
+
+1. Request override (`modelConfig.reasoningEffort` or `RunSkillRequest.reasoningEffort`)
+2. Catalox `SkillOptimixerCatalogSpec.reasoningEffort`
+3. Package default (e.g. `"not-applicable"`)
+
+Forward the resolved value into `buildAiMaxTokensPredictionInput` / Optimixer predict (same as xynthesis `resolveEffectiveMaxTokens`).
+
+#### Acceptance
+
+- `runSkill({ modelConfig: { model: "…", reasoningEffort: "high" } })` uses `"high"` in Optimixer predict even when catalog says `"medium"`.
+- Trace / `invokeRequest` echo includes effective `reasoningEffort` (or Optimixer diagnostics slice).
+- Omitting the field keeps today’s catalog-only behavior unchanged.
+
+---
+
+### 2. Document the orchestrator ↔ MAIN invoke contract (README / BREAKING)
+
+Add a short **“Host responsibilities”** section:
+
+- **Send:** concrete or resolved wire `model`, optional `temperature`, `topP`, `reasoningEffort`, `timeoutMs`.
+- **Do not send:** `maxTokens`, `max_completion_tokens`, `max_output_tokens` on `modelConfig` (rejected).
+- **Token budget:** owned by Optimixer from catalog + prompts; echo `usage.maxTokensRequested` / `metadata.maxTokensRequested` after invoke.
+
+Point `@exellix/ai-tasks` integrators to this section instead of legacy `modelConfig.maxTokens` docs.
+
+---
+
+### 3. Update §2 in `ai-skills-llm-observability.md` (stale)
+
+The open item **“`outputExpectation` passthrough + xynthesis-style auto-sizer on RunSkillRequest”** assumed hosts still set `modelConfig.maxTokens`. With 5.9 Optimixer, revise to:
+
+- **Optional:** `outputExpectation` on `RunSkillRequest` to steer Optimixer output intent (parity with xynthesis), **not** to supply a literal token count.
+- **Not asked:** restoring caller `modelConfig.maxTokens`.
+
+(Can be a separate FR or folded into §1 if output intent is also catalog-only today.)
+
+---
+
+## Integration note (5.9.12 — ai-tasks)
+
+### `analyzeSkillRequest` root export removed
+
+- **Today:** `analyzeSkillRequest(catalox, …)` exists in `dist/analysis/` but is **not** re-exported from `@exellix/ai-skills` package root. Use **`ExellixSkillsClient.analyzeSkillRequest`** (or export the function again from `index.js` for Catalox-only callers).
+- **ai-tasks:** `analyzeRunTaskRequest` uses a short-lived `ExellixSkillsClient` until root export returns.
+
+### `testContentRegistryConnection` renamed
+
+- Use **`ExellixSkillsClient.testCatalogConnection()`** (Catalox reachability; replaces gateway content-registry check).
+
+---
+
+## Optional (lower priority)
+
+### 4. `SkillExecutionError` in default mode
+
+Still valuable; see [`ai-skills-llm-observability.md` §1](./ai-skills-llm-observability.md). Independent of token / reasoning contract.
+
+---
+
+## Verification checklist (for ai-skills PR)
+
+- [ ] TypeScript: `ModelConfig` / `RunSkillRequest` exposes `reasoningEffort`.
+- [ ] Unit test: request override beats catalog default in Optimixer predict input.
+- [ ] Unit test: `modelConfig.maxTokens` still rejected.
+- [ ] README/BREAKING: host must not send max token caps on `modelConfig`.
+
+---
+
+## After this ships — ai-tasks follow-up
+
+See [`ai-tasks-wrap-up-after-upstream.md`](./ai-tasks-wrap-up-after-upstream.md):
+
+- Add `reasoningEffort` to `LlmCallConfig` / tuning passthrough → `buildAiSkillsModelConfigForMain`.
+- Stop forwarding any `maxTokens` / `maxTokensCap` to `runSkill`.

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

@@ -0,0 +1,126 @@
+# `@exellix/ai-tasks` — wrap-up after upstream invoke-contract fixes
+
+Status: **blocked** on upstream PRs until both packages ship items in:
+
+- [`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)
+
+Owner: `@exellix/ai-tasks`  
+Target release: **8.4.x** (or **8.5.0** if breaking `llmCall` surface)
+
+---
+
+## Contract (locked with product)
+
+**ai-tasks sends to lower layers:**
+
+- Model ids via `RunTaskModelConfig` triplet (`preActionModel`, `skillModel`, `postActionModel`) + optional `llmCall.model` overrides.
+- `temperature`, `topP`, **`reasoningEffort`** (once upstream exposes it).
+- **`outputExpectation`** on xynthesis-backed hops only (sizing intent — **not** a token count).
+
+**ai-tasks does not send:**
+
+- `maxTokens` / `maxTokensCap` on `modelConfig`, `runSkill`, `executeXynthesisAction`, or direct gateway repair (unless product later revives an explicit ceiling knob with a new name).
+
+**Lower layers own:**
+
+- MAIN caps → `@exellix/ai-skills` Optimixer + Catalox skill catalog.
+- PRE/POST/scoping/utility caps → `@exellix/xynthesis` `resolveEffectiveMaxTokens` inside `executeXynthesisAction`.
+
+---
+
+## Already done in ai-tasks (this branch)
+
+- [x] `RunTaskRequest.modelConfig` typed as `RunTaskModelConfig` (not ai-skills `ModelConfig` with `maxTokens`).
+- [x] Removed `maxTokens` from `RunTaskModelConfig`; strip legacy key at ai-skills boundary.
+- [x] Stopped mapping `llmCall.maxTokensCap` → `modelConfig.maxTokens` in `buildAiSkillsModelConfigForMain`.
+- [x] Trace repair: `mapGatewayInvokeToTrace` uses `maxTokensRequested` only (not `modelConfig.maxTokens`).
+- [x] README / BREAKING-CHANGES partial updates for modelConfig + MAIN Optimixer.
+
+---
+
+## TODO after upstream ships
+
+### 1. Remove broken / duplicate token budgeting
+
+| File / area | Change |
+|-------------|--------|
+| `src/internal/resolveLlmCallForXynthesis.ts` | Remove `resolveMaxTokens` import; either delete token resolution or reduce to **outputExpectation-only** helper (rename e.g. `resolveLlmOutputExpectationForXynthesis`). |
+| `src/internal/runPostStepLlmCall.ts` | Drop `maxTokens` / `resolveLlmCallForXynthesis` pre-resolution; pass **`outputExpectation`** (required). |
+| `src/synthesis/runStructuredSynthesisRobust.ts` | Repair path: stop `resolveMaxTokens`; do not push `maxTokens` into raw AIGateway `config` unless gateway documents a non-Optimixer escape hatch. |
+| `src/index.ts` | Stop re-exporting `resolveMaxTokens`; export `resolveEffectiveMaxTokens` only if graph-engine needs it (prefer not). |
+| `src/utilities/runUtility.ts` | Remove `maxTokens` forward to xynthesis finalize. |
+| `src/post-steps/resolvePostStepConfig.ts` | Remove env `*_MAX_TOKENS_CAP` wiring if contract is zero host caps (or keep env as deprecated no-op one release). |
+
+### 2. Add `reasoningEffort` to ai-tasks surface
+
+| File | Change |
+|------|--------|
+| `src/types/llmCall.ts` | `reasoningEffort?: OptimixerReasoningEffort` (re-export type from `@x12i/optimixer` or xynthesis). |
+| `src/types/model-config.ts` | Optional tuning field; passthrough in `modelConfigTuningPassthrough` (not stripped). |
+| `src/types/task-types.ts` | Document on `llmCall` and post-step configs. |
+| `buildAiSkillsModelConfigForMain` | Forward to ai-skills `modelConfig` when upstream §1 ships. |
+| `runPostStepLlmCall` / `task-sdk` synthesis | Forward to `executeXynthesisAction` / structured params. |
+| `src/validation/helpers.ts` | Optional enum validation if finite set. |
+| `src/builders/task-request-builder.ts` | Document in `withLlmCall` JSDoc. |
+
+### 3. Fix xynthesis call sites (no new upstream needed except §1–2)
+
+| Call site | Pass |
+|-----------|------|
+| `runPostStepLlmCall` → `executeXynthesisAction` | `outputExpectation`, `temperature`, `topP`, `sidekickAction` / `activixActionType`, `reasoningEffort` (when exists) |
+| PRE structured / markdown synthesis (`task-sdk`) | Same via gateway / `runStructuredSynthesisGatewayCall` params |
+| AI scoping | `outputExpectation` (already defaulted in `runScopingCall`) |
+
+### 4. Remove / deprecate `maxTokensCap` on `LlmCallConfig`
+
+- **Breaking:** remove `maxTokensCap` from `LlmCallConfig`, `RunUtilityRequest.exec`, post-step env fallbacks, validation, README.
+- **Or soft:** mark deprecated in 8.4.1, ignore at runtime, remove in 8.5.0.
+
+Confirm with graph-engine before hard removal.
+
+### 5. Tests & docs
+
+- [ ] `npm run build` + `tsc -p tsconfig.test.json` green (no `resolveMaxTokens` import).
+- [ ] `npm run test` green (mocks via `setSynthesisInvoker` unchanged).
+- [ ] Update [`README.md`](../../README.md) token-budget section (remove `llmCall.maxTokensCap` → `modelConfig.maxTokens` overlay story).
+- [ ] Update [`ai-skills-llm-observability.md`](./ai-skills-llm-observability.md) §2 (stale maxTokens wording).
+- [ ] Update [`xynthesis-llm-observability.md`](./xynthesis-llm-observability.md) superseded sections.
+- [ ] Link all three contract docs from [`BREAKING-CHANGES.md`](../../BREAKING-CHANGES.md) 8.4 section.
+
+---
+
+## Dependency order
+
+```mermaid
+flowchart LR
+  A[ai-skills: reasoningEffort on RunSkillRequest]
+  B[xynthesis: reasoningEffort on ExecuteXynthesisActionRequest]
+  C[xynthesis: verify temperature topP all paths]
+  D[ai-tasks: remove maxTokens forwarding]
+  E[ai-tasks: wire reasoningEffort + outputExpectation]
+  A --> E
+  B --> E
+  C --> E
+  D --> E
+```
+
+Recommended sequence:
+
+1. Merge **xynthesis** + **ai-skills** contract PRs (can be parallel).
+2. Bump `package.json` minimums in ai-tasks.
+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).
+
+---
+
+## Quick smoke test after wrap-up
+
+```bash
+npm run build
+npm run test
+# Optional live:
+# npm run test:e2e:synthesis
+```
+
+Expect: no import of `resolveMaxTokens` from `@exellix/xynthesis/ai-actions`; live POST/PRE calls succeed with `outputExpectation` only (no `maxTokens` on request).

package/documenations/upstream-feature-requests/funcx-openrouter-model-id-pass-through.md

@@ -0,0 +1,105 @@
+# `@x12i/funcx` — OpenRouter `model` pass-through (no defect; optional hardening)
+
+Status: **informational — not a funcx bug; xynthesis fix in 4.1.8 verified**  
+Filed by: `@exellix/ai-tasks` (8.2.x)  
+Context: investigation of OpenRouter **400 invalid model ID** on xynthesis PRE/POST hops (resolved upstream)  
+Primary report: [`xynthesis-openrouter-wire-model-double-prefix-bug.md`](./xynthesis-openrouter-wire-model-double-prefix-bug.md)
+
+---
+
+## Summary
+
+During live E2E (`test/e2e/ai-profiles-live.test.ts`), OpenRouter rejected:
+
+```text
+openrouter/google/gemini-2.5-flash-lite is not a valid model ID
+```
+
+Tracing the call stack shows **funcx sends exactly the `model` string it receives** from `@exellix/xynthesis` **`FuncxInvoker.askFuncx`** — no transformation, strip, or re-prefix inside funcx.
+
+**Fix belongs in xynthesis** (`wireModelId` formatting). **Do not** add a funcx workaround that strips `openrouter/` unless funcx explicitly documents that callers may send gateway-shaped ids (that would hide upstream bugs).
+
+---
+
+## Call chain (verified)
+
+| Layer | Responsibility |
+|-------|----------------|
+| ai-tasks | Passes ai-profiles **alias** on `llmCall.model` / `executeXynthesisAction({ model: "cheap" })` |
+| xynthesis | `resolveXynthesisModel` → **`wireModelId`** (bug: double `openrouter/` prefix) |
+| xynthesis `FuncxInvoker` | `client.ask(userPrompt, { model: resolved.wireModelId, … })` |
+| funcx | Forwards `model` to `https://openrouter.ai/api/v1/chat/completions` |
+| OpenRouter | Expects slug like `google/gemini-2.5-flash-lite` |
+
+Funcx activity log (from live run) shows the invalid model in the **request body** — same value xynthesis supplied:
+
+```json
+{
+  "url": "https://openrouter.ai/api/v1/chat/completions",
+  "body": {
+    "model": "openrouter/google/gemini-2.5-flash-lite"
+  }
+}
+```
+
+---
+
+## Why this is not a funcx defect
+
+1. **Contract:** Funcx OpenRouter backend accepts a **provider model slug** for the REST API. It is not funcx’s job to guess whether the caller meant gateway notation vs API notation.
+
+2. **Correct upstream already exists:** `@x12i/ai-profiles` **≥ 1.8.0** exposes the correct slug on **`ResolvedAIProfile.invocation.openrouter.modelId`**. Xynthesis should use that for Funcx, not re-wrap with `openrouter/`.
+
+3. **Silent correction in funcx would be harmful:** Stripping `openrouter/` inside funcx could mask bugs in other callers and make debugging harder.
+
+---
+
+## Optional enhancements (funcx — low priority, not required for this incident)
+
+If funcx wants better operator experience **without** changing wire behavior:
+
+### O1 — Document OpenRouter `model` field
+
+In README / `Client.ask` JSDoc, state explicitly:
+
+- OpenRouter backend: **`model`** must be the **OpenRouter API model id** (e.g. `google/gemini-2.5-flash-lite`, `anthropic/claude-sonnet-4.5`).
+- **Not** the ai-skills gateway form `openrouter/<vendor>/<model>`.
+
+### O2 — Fail fast on obvious gateway-shaped ids (optional)
+
+When `backend === "openrouter"` and `model.startsWith("openrouter/")`, throw a **clear, named error** before HTTP:
+
+```text
+Funcx OpenRouter backend: model must be a bare OpenRouter slug (got gateway-shaped "openrouter/…").
+Resolve via @x12i/ai-profiles invocation.openrouter.modelId or fix upstream wire formatting.
+```
+
+**Pros:** Surfaces misconfiguration immediately; points to xynthesis/ai-skills boundary.  
+**Cons:** Breaking if any caller intentionally relied on funcx to accept gateway ids (none known).
+
+### O3 — Include requested model in `AI_ACTIVITY_FAILED` diagnostics
+
+Already partially present in activity logs. Ensure **`request.body.model`** is always in structured diagnostics for 400 responses (helps cross-package RCA).
+
+---
+
+## Paste-ready GitHub issue (funcx repo) — **optional, enhancement only**
+
+**Title:** Document OpenRouter `ask({ model })` must use bare API slug; optional guard against `openrouter/` prefix
+
+**Type:** Documentation (+ optional DX guard)
+
+**Body:** Summarize O1–O2 above. Link xynthesis fix as primary resolution.
+
+**Acceptance criteria:**
+
+- [ ] README documents valid OpenRouter model id format.
+- [ ] (Optional) Named error when `model.startsWith("openrouter/")` on OpenRouter backend.
+- [ ] No automatic rewrite/strip of model ids (avoid masking upstream bugs).
+
+---
+
+## Related
+
+- [`xynthesis-openrouter-wire-model-double-prefix-bug.md`](./xynthesis-openrouter-wire-model-double-prefix-bug.md) — **fix here first**
+- [`funcx-upstream-github-issues-draft.md`](../funcx-upstream-github-issues-draft.md) — other funcx tracking

package/documenations/upstream-feature-requests/xynthesis-openrouter-wire-model-double-prefix-bug.md

@@ -0,0 +1,191 @@
+# `@exellix/xynthesis` — OpenRouter wire model double-prefix (400 invalid model ID)
+
+Status: **fixed in `@exellix/xynthesis` ≥ 4.1.8**  
+Filed by: `@exellix/ai-tasks` (8.2.x)  
+Reproduced with: `@x12i/ai-profiles` **≥ 1.8.0**, `@exellix/xynthesis` **4.1.7** (broken), **4.1.8+** (fixed), `@x12i/funcx` **4.3.0**  
+Live test: `test/e2e/ai-profiles-live.test.ts` → `npm run test:live`  
+Verified: **2026-05-31** — all 8 live ai-profiles tests pass on **xynthesis 4.1.8** (wire id `google/gemini-2.5-flash-lite`, real POST-step LLM OK).
+
+---
+
+## Summary
+
+When **`PREFER_OPENROUTER`** routing is active, xynthesis PRE/POST hops resolve an ai-profiles alias (e.g. `cheap`) and pass a **wire model id** to **`FuncxInvoker`** → **`client.ask({ model })`**. That wire id is incorrectly formatted as **`openrouter/<openrouter-api-slug>`** instead of the **bare OpenRouter API slug** returned by ai-profiles.
+
+OpenRouter responds **400**:
+
+```json
+{
+  "error": {
+    "message": "openrouter/google/gemini-2.5-flash-lite is not a valid model ID",
+    "code": 400
+  }
+}
+```
+
+Valid slug for that profile choice: **`google/gemini-2.5-flash-lite`**.
+
+**Not an ai-profiles bug.** **Not an ai-tasks bug** (ai-tasks passes aliases; xynthesis resolves at invoke time). **Not a funcx bug** (funcx forwards the model string it receives).
+
+---
+
+## Impact
+
+| Path | Symptom |
+|------|---------|
+| `executeXynthesisAction` with alias `model` (`cheap`, `balanced`, …) + OpenRouter key | **400** from OpenRouter; POST audit/polish/scoping/PRE synthesis fails |
+| `@exellix/ai-tasks` `runPostStepLlmCall` | Same — all xynthesis-backed post steps |
+| MAIN skill via `@exellix/ai-skills` | **Unaffected** — ai-skills expects gateway shape `openrouter/<vendor>/<model>` |
+
+---
+
+## Reproduction
+
+### Minimal (ai-tasks live test)
+
+```bash
+# Requires OPENROUTER_API_KEY (or OPEN_ROUTER_KEY) and network
+cd ai-tasks
+npm run test:live
+# Fails: diagnostic + real LLM tests until xynthesis is fixed
+```
+
+Or:
+
+```bash
+RUN_LIVE_AI_E2E=1 node --test dist-test/test/e2e/ai-profiles-live.test.js
+```
+
+### Resolution chain (alias `cheap`, OpenRouter routing)
+
+| Step | Component | Value |
+|------|-----------|-------|
+| 1 | `@x12i/ai-profiles` `resolveAIProfile("cheap")` → `invocation.openrouter.modelId` | `google/gemini-2.5-flash-lite` ✓ |
+| 2 | `@exellix/xynthesis` `resolveXynthesisModel("cheap").wireModelId` | `openrouter/google/gemini-2.5-flash-lite` ✗ |
+| 3 | `@x12i/funcx` HTTP body `model` | `openrouter/google/gemini-2.5-flash-lite` (pass-through) |
+| 4 | OpenRouter API | **400 invalid model ID** |
+
+Observed Funcx request body (from live run):
+
+```json
+{
+  "model": "openrouter/google/gemini-2.5-flash-lite",
+  "messages": [ … ]
+}
+```
+
+---
+
+## Root cause (xynthesis `@exellix/xynthesis` **4.1.7**)
+
+**File:** `src/resolveAiProfileModel.ts`
+
+1. `openrouterModelIdFromInvocation()` correctly reads ai-profiles **`invocation.openrouter.modelId`** (bare slug when it contains `/`).
+
+2. **`openrouterWireModelId()`** then **always prepends** `openrouter/`:
+
+```ts
+function openrouterWireModelId(resolved: ResolvedAIProfile): string | undefined {
+  const or = openrouterModelIdFromInvocation(resolved);
+  if (!or) return undefined;
+  return or.startsWith("openrouter/") ? or : `openrouter/${or}`; // ← bug
+}
+```
+
+3. **`xynthesisWireModelIdFromResolved()`** uses that helper for OpenRouter-routed profiles:
+
+```ts
+export function xynthesisWireModelIdFromResolved(resolved: ResolvedAIProfile): string {
+  if (resolved.routing === "openrouter") {
+    const orWire = openrouterWireModelId(resolved);
+    if (orWire) return orWire;
+  }
+  return toOpenRouterModelId(resolved.provider, resolved.modelId);
+}
+```
+
+4. **`FuncxInvoker.askFuncx`** passes `wireModelId` directly to OpenRouter:
+
+```ts
+return client.ask(opts.userPrompt, {
+  model: resolved.wireModelId, // must be bare OR slug, not openrouter/…
+  …
+});
+```
+
+### Why two wire shapes exist
+
+| Consumer | Expected model shape | Example |
+|----------|---------------------|---------|
+| **ai-skills MAIN** (gateway) | `openrouter/<vendor>/<model>` | `openrouter/anthropic/claude-sonnet-4.5` |
+| **Funcx OpenRouter backend** (REST API) | bare OpenRouter slug | `google/gemini-2.5-flash-lite` |
+
+Xynthesis conflates the **gateway** prefix rule with the **OpenRouter API** slug rule on the Funcx path.
+
+---
+
+## Recommended fix (xynthesis)
+
+**In `xynthesisWireModelIdFromResolved` (Funcx / PRE/POST path):**
+
+- Use **`resolved.invocation.openrouter.modelId`** as-is when present.
+- Fallback: when `resolved.routing === "openrouter"` and `resolved.modelId` already contains `/`, return **`resolved.modelId`** (not `openrouter/${modelId}`).
+- Only use `toOpenRouterModelId(provider, modelId)` for **vendor-direct** routing.
+
+**Do not** prepend `openrouter/` on the Funcx invoke path.
+
+**Remove or restrict** `openrouterWireModelId()` so it is not used for xynthesis wire ids (it may remain useful only if a future gateway-shaped export is needed elsewhere).
+
+### Tests to add (xynthesis)
+
+In `test/resolveAiProfileModel.unit.ts` (or new file):
+
+```ts
+const cheapOr = await resolveXynthesisModel("cheap", {
+  source: "bundled",
+  preferOpenRouter: true,
+  openrouterApiKeyPresent: true,
+});
+assert.equal(cheapOr?.routing, "openrouter");
+assert.ok(cheapOr?.wireModelId.includes("/"));
+assert.ok(!cheapOr!.wireModelId.startsWith("openrouter/"));
+assert.equal(
+  cheapOr?.wireModelId,
+  cheapOr?.profile.invocation?.openrouter?.modelId
+);
+```
+
+Optional integration test: mock Funcx `client.ask` and assert `model` is bare slug.
+
+---
+
+## ai-tasks alignment (diagnostics only)
+
+`@exellix/ai-tasks` **`resolveProfileInvocationRouting`** mirrored the same double-prefix for **`phaseKind: "xynthesis"`** in observability logs (`LLM_PROVIDER_INVOCATION`). That affects **diagnostics only** — the HTTP payload is built inside xynthesis. ai-tasks should align xynthesis-phase diagnostics with the fixed wire shape once xynthesis ships.
+
+Skill phase (`phaseKind: "skill"`) should **keep** `openrouter/` gateway prefix for ai-skills MAIN.
+
+---
+
+## Paste-ready GitHub issue (xynthesis repo)
+
+**Title:** `resolveXynthesisModel`: Funcx OpenRouter wire id must use bare API slug, not `openrouter/` prefix
+
+**Labels:** `bug`, `openrouter`, `ai-profiles`
+
+**Body:** Use the Summary, Reproduction, and Recommended fix sections above.
+
+**Acceptance criteria:**
+
+- [ ] `resolveXynthesisModel("cheap", { preferOpenRouter: true })` → `wireModelId` equals ai-profiles `invocation.openrouter.modelId` (no `openrouter/` prefix).
+- [ ] Live OpenRouter call with alias `cheap` succeeds (200, non-empty completion).
+- [ ] Vendor-direct routing (`preferOpenRouter: false`) unchanged.
+- [ ] Changelog entry; semver patch or minor per release policy.
+
+---
+
+## Related
+
+- [`.docs/prefer-openrouter-routing-policy.md`](../../.docs/prefer-openrouter-routing-policy.md)
+- [`funcx-openrouter-model-id-pass-through.md`](./funcx-openrouter-model-id-pass-through.md) — funcx is pass-through; no fix required there
+- [`xynthesis-upstream-fixes-checklist.md`](../xynthesis-upstream-fixes-checklist.md)