@exellix/ai-tasks 8.4.2 → 8.5.0

package/documenations/upstream-feature-requests/xynthesis-execution-strategies-option-a.md

@@ -0,0 +1,637 @@
+# `@exellix/xynthesis` — MAIN execution strategies (Option A: absorb FuncX wrappers)
+
+Status: **shipped** in `@exellix/xynthesis` ≥ 4.4.0; ai-tasks **8.5.0** consumes via `runExecutionStrategyViaXynthesis`  
+Owner: `@exellix/xynthesis`  
+Filed by: `@exellix/ai-tasks`  
+Consumer: `@exellix/ai-tasks` 8.4+ (sole consumer — no separate package planned)  
+Target release: **`@exellix/xynthesis` ≥ 4.4.0** (semver minor; ai-tasks follow-up in 8.5.x)  
+Pinned in ai-tasks today: `@exellix/xynthesis@^4.3.1`
+
+Related:
+
+- [`xynthesis-orchestrator-invoke-contract-4.2.md`](./xynthesis-orchestrator-invoke-contract-4.2.md) — invoke contract this FR extends
+- [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) §6 — current FuncX wire contracts (source of truth for shapes)
+- [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — what FuncX hosts today (to migrate prompts into xynthesis/Catalox)
+- ai-tasks reference adapters: [`genericExecutionFuncxEnvelope.ts`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts)
+
+---
+
+## 0. Decision record
+
+**Chosen:** Option A — implement planner / optimizer / consolidated web-scope planning as **first-class xynthesis actions**, invoked like audit, polish, and scoping.
+
+**Rejected:** Option B — a new `@exellix/*` package for execution strategies. Only `@exellix/ai-tasks` consumes these capabilities; a separate package would add publish/version overhead without reuse.
+
+**Goal:** Remove **direct** `@x12i/funcx` usage from `@exellix/ai-tasks` for MAIN wrappers while preserving behavior, catalogs, and observability parity with other xynthesis hops.
+
+---
+
+## 1. Summary
+
+Today `@exellix/ai-tasks` calls FuncX **`run(functionId, payload)`** for:
+
+| Capability | FuncX `functionId` | When |
+|------------|-------------------|------|
+| Planner | `execution/plan` | Once before first MAIN attempt |
+| Optimizer | `execution/evaluate-result` | After each MAIN attempt (retry loop) |
+| Web-scope questions (optional backend) | `research/plan-questions` | Narrix web-scope preprocessor |
+
+These hops **bypass** the 8.4 invoke contract: no `modelConfig` slots, no Optimixer via `outputExpectation`, no `InvokeAttemptSummary`, no unified `LlmCallObservation`.
+
+**Ask:** xynthesis exposes three structured actions on the same surface as audit/polish/scoping (`executeXynthesisAction` or thin dedicated wrappers), owns prompts + JSON schemas + Optimixer defaults, and returns typed results ai-tasks merges into `RunTaskRequest` before/after MAIN.
+
+| Orchestrator sends (ai-tasks) | xynthesis owns internally |
+|------------------------------|---------------------------|
+| Wire **model** (from `modelConfig` slot — see §4) | — |
+| **outputExpectation** | — |
+| **temperature**, **topP**, **reasoningEffort** | — |
+| Structured **input** payload (§5) | Prompt rendering from Catalox templates |
+| **workScope** (`jobId`, `taskId`, `agentId`, identity) | Correlation / Activix attribution |
+| — | **max completion tokens** (Optimixer) |
+| — | Provider invoke (OpenRouter / gateway) |
+| — | JSON parse + schema validation |
+
+**ai-tasks keeps:** `executionStrategies` validation/sort, MAIN retry loop, `applyPlannerOutputToRequest` / `applyOptimizerFeedbackToRequest`, intermediateSteps / trace assembly. xynthesis does **not** call ai-skills or execute MAIN.
+
+---
+
+## 2. Background — current ai-tasks behavior
+
+### 2.1 Planner flow
+
+1. `resolveExecutionStrategies` sorts `executionStrategies[]` rows with `strategyKey: "planner"`, `phase: "before"`.
+2. For each planner row (typically one), ai-tasks builds `buildExecutionStrategyRequestPayload(...)` and calls `runPlannerFuncx` → FuncX `execution/plan`.
+3. Response adapted by `adaptExecutionPlanResult` → merged via `applyPlannerOutputToRequest`:
+   - `variables` (shallow merge)
+   - `templateTokens` (+ `instructions` / `prompt` keys when present)
+   - `executionMemory.executionStrategies.lastPlanner` / `plannerChain`
+
+### 2.2 Optimizer flow
+
+1. First `optimizer` row after sort drives retry loop (`maxIterations` default 3, env `AI_TASKS_OPTIMIZER_MAX_ITERATIONS`).
+2. Each iteration: `runDirect` (MAIN via ai-skills) → build `mainResultSummary` (rawText ≤ 12k, parsed, metadata summarized ≤ 6k) → `runOptimizerFuncx` → FuncX `execution/evaluate-result`.
+3. If `satisfied === true` or last iteration: return MAIN result.
+4. Else: `applyOptimizerFeedbackToRequest` sets `variables.optimizerFeedback`, `variables.optimizerIteration`, `variables.optimizerSuggestedChanges`, optional `templateTokens`, then retry MAIN.
+
+### 2.3 Web-scope questions
+
+- **Default path (keep):** `runPlanWebScopeQuestions` → `runPostStepLlmCall` → `executeXynthesisAction` with inline system prompt + `parseAndValidatePlanWebScopeQuestionsOutput`.
+- **FuncX path (deprecate):** `backend: "funcx"` → `research/plan-questions` generic envelope.
+
+### 2.4 Problem with FuncX path
+
+[`runFuncxExecutionStrategy.ts`](../../src/execution-strategies/runFuncxExecutionStrategy.ts) uses `createClient({ backend: "openrouter" })` with **no** `RunTaskRequest.modelConfig` forwarding. Planner/optimizer ignore `preActionModel` / `postActionModel` and the unified observability stack.
+
+---
+
+## 3. Scope
+
+### 3.1 In scope (xynthesis)
+
+- Three new **`SidekickActionType`** values (names provisional — see §4.1).
+- Catalox sidekick templates + Optimixer catalog entries for each action.
+- Public TypeScript request/response types + JSON schemas.
+- Integration with `executeXynthesisAction` (preferred) or dedicated exports that delegate to it.
+- Structured JSON output validation (same shapes ai-tasks adapters expect today).
+- `InvokeAttemptSummary` / token resolution / model routing identical to audit/polish.
+- Test hook: injectable invoker (same pattern as existing synthesis tests).
+
+### 3.2 Out of scope (stays in ai-tasks)
+
+- `RunTaskRequest.executionStrategies` array shape and validation.
+- Optimizer **retry loop** and `maxIterations` policy.
+- Merging planner/optimizer outputs into gateway request fields.
+- FuncX catalog hosting for `execution/*` and `research/plan-questions` (deprecated after migration).
+- MAIN skill execution (`@exellix/ai-skills`).
+
+### 3.3 Deprecation
+
+After ai-tasks migrates:
+
+- ai-tasks removes direct `@x12i/funcx` dependency (may remain transitive via xynthesis/narrix).
+- `backend: "funcx"` on `runPlanWebScopeQuestions` removed in ai-tasks major/minor follow-up.
+- FuncX function ids remain documented for hosts that still call FuncX directly during transition.
+
+---
+
+## 4. Public API
+
+### 4.1 New sidekick actions
+
+Add to xynthesis `SidekickActionType`:
+
+| Action key | Purpose | ai-tasks `LlmCallStage` |
+|------------|---------|-------------------------|
+| `execution-plan` | Planner before MAIN | `execution-strategy-planner` |
+| `execution-evaluate-result` | Optimizer after MAIN attempt | `execution-strategy-optimizer` |
+| `plan-web-scope-questions` | Web-scope question planner (consolidate inline prompt) | `plan-web-scope-questions` (existing stage) |
+
+**Canonical aliases** (for Catalox / docs): mirror former FuncX ids `execution/plan`, `execution/evaluate-result`, `research/plan-questions` as **documentation aliases only** — xynthesis uses sidekick action keys, not FuncX `functionId` routing.
+
+### 4.2 Entry points
+
+**Preferred — extend existing hop API:**
+
+```typescript
+import type { OutputExpectation } from "@exellix/xynthesis/ai-actions";
+import type { OptimixerReasoningEffort } from "@x12i/optimixer";
+
+/** Shared invoke fields — same contract as audit/polish (see xynthesis-orchestrator-invoke-contract-4.2.md). */
+type ExecutionStrategyInvokeBase = {
+  model: string;
+  outputExpectation: OutputExpectation;
+  temperature?: number;
+  topP?: number;
+  reasoningEffort?: OptimixerReasoningEffort;
+  timeoutMs?: number;
+  maxOutputLength?: number;
+  gateway?: { agentId?: string; sessionId?: string; temperature?: number };
+  workScope?: {
+    jobId?: string;
+    taskId?: string;
+    agentId?: string;
+    identity?: Record<string, unknown>;
+  };
+  /** Strategy row args minus functionId — opaque JSON-safe knobs forwarded into template context. */
+  strategyArgs?: Record<string, unknown>;
+};
+
+/** Planner — maps from buildPlannerGenericPayload envelope. */
+export type RunExecutionPlanRequest = ExecutionStrategyInvokeBase & {
+  sidekickAction: "execution-plan";
+  goal: string;
+  input?: unknown;
+  context: ExecutionStrategyContext;
+};
+
+/** Optimizer — maps from buildOptimizerGenericPayload envelope. */
+export type RunExecutionEvaluateResultRequest = ExecutionStrategyInvokeBase & {
+  sidekickAction: "execution-evaluate-result";
+  goal: string;
+  input?: unknown;
+  context: ExecutionStrategyContext;
+  result: MainResultSummary;
+  iterationIndex: number;
+};
+
+/** Web-scope — maps from buildResearchPlanQuestionsPayload envelope. */
+export type RunPlanWebScopeQuestionsRequest = ExecutionStrategyInvokeBase & {
+  sidekickAction: "plan-web-scope-questions";
+  goal: string;
+  input: { nodeInput?: unknown; rawRecord?: unknown };
+  context?: {
+    memorySummary?: unknown;
+    xynthesized?: { job?: unknown; task?: unknown };
+  };
+  args: {
+    maxQuestions: number; // 1–20, clamped by xynthesis
+    sourceType: "web";
+    allowSkip: boolean;
+    includeReasons?: boolean;
+  };
+};
+
+export type ExecutionStrategyContext = {
+  skillKey?: string;
+  variables?: Record<string, unknown>;
+  jobContext?: Record<string, unknown>;
+  jobMemory?: unknown;
+  taskMemory?: unknown;
+  executionMemory?: unknown;
+  jobId?: string;
+  taskId?: string;
+  agentId?: string;
+  graphId?: string;
+  nodeId?: string;
+  prevNodeId?: string;
+  coreSkillId?: string;
+  includeContextInPrompt?: boolean;
+};
+
+export type MainResultSummary = {
+  rawText?: string;
+  parsed?: unknown;
+  skillKey?: string;
+  metadata?: unknown;
+};
+```
+
+**Dispatch:** Either overload `executeXynthesisAction` to accept these `sidekickAction` values, or export:
+
+```typescript
+export async function runExecutionPlan(req: RunExecutionPlanRequest): Promise<ExecutionPlanResult>;
+export async function runExecutionEvaluateResult(req: RunExecutionEvaluateResultRequest): Promise<ExecutionEvaluateResult>;
+export async function runPlanWebScopeQuestionsAction(req: RunPlanWebScopeQuestionsRequest): Promise<PlanWebScopeQuestionsResult>;
+```
+
+All three must return `{ result, invokeSummary, debugTrace? }` consistent with other actions.
+
+### 4.3 Model slot mapping (ai-tasks caller policy)
+
+ai-tasks resolves model aliases before invoke:
+
+| Action | Default `modelConfig` slot | Rationale |
+|--------|---------------------------|-----------|
+| `execution-plan` | **`preActionModel`** | Runs before MAIN; same phase family as PRE synthesis |
+| `execution-evaluate-result` | **`postActionModel`** | Evaluative hop (like audit); judges MAIN output quality |
+| `plan-web-scope-questions` | **`preActionModel`** | Pre-MAIN Narrix web-scope preprocessor |
+
+Per-strategy override (ai-tasks follow-up, optional): `executionStrategies[].llmCall?.model` wins over slot default when set.
+
+### 4.4 OutputExpectation defaults (xynthesis Optimixer catalog)
+
+Register Catalox defaults per action (ai-tasks may override via `llmCall.outputExpectation`):
+
+| Action | Suggested default | Notes |
+|--------|-------------------|-------|
+| `execution-plan` | `{ size: { mode: "absolute", minWords: 80, maxWords: 600 }, density: "concise" }` | Structured plan text + optional variables |
+| `execution-evaluate-result` | `{ size: { mode: "absolute", minWords: 40, maxWords: 400 }, density: "concise" }` | Boolean satisfied + feedback |
+| `plan-web-scope-questions` | `{ size: { mode: "absolute", minWords: 50, maxWords: 800 }, density: "concise" }` | JSON array of questions |
+
+Expose via `resolveOutputExpectation("execution-plan" | ...)` when action keys are added.
+
+---
+
+## 5. Input contracts (wire payloads)
+
+These mirror today's FuncX generic envelope built in ai-tasks. xynthesis templates receive **`goal`**, **`input`**, **`context`**, optional **`result`** (optimizer only), **`args`**, and **`strategyArgs`**.
+
+### 5.1 Planner input
+
+Built by ai-tasks `buildPlannerGenericPayload`:
+
+```json
+{
+  "goal": "Plan how to execute the MAIN gateway skill for skillKey \"my.skill\" (coreSkillId: node-1).",
+  "input": { "...": "task input — opaque" },
+  "context": {
+    "skillKey": "my.skill",
+    "variables": {},
+    "jobContext": {},
+    "jobMemory": {},
+    "taskMemory": {},
+    "executionMemory": {},
+    "jobId": "uuid",
+    "taskId": "uuid",
+    "agentId": "uuid",
+    "graphId": "optional",
+    "nodeId": "optional",
+    "prevNodeId": "optional",
+    "coreSkillId": "optional",
+    "includeContextInPrompt": false
+  },
+  "args": { "...": "optional strategy row args except functionId" },
+  "attribution": {
+    "runId": "jobId",
+    "subjectId": "taskId",
+    "actorId": "agentId",
+    "tags": { "caller": "ai-tasks", "jobId": "...", "taskId": "...", "agentId": "..." }
+  }
+}
+```
+
+**Template requirements:**
+
+- Must **not** execute MAIN or call ai-skills.
+- Use `goal` as the primary objective line in the user prompt.
+- Render `input` + `context` as JSON-safe sections (truncate large blobs with explicit markers).
+- Forward correlation from `workScope` / `attribution` into provider attribution fields.
+
+### 5.2 Optimizer input
+
+Built by ai-tasks `buildOptimizerGenericPayload`. Same as planner plus:
+
+```json
+{
+  "result": {
+    "rawText": "...(max ~12000 chars from ai-tasks)...",
+    "parsed": { "...": "skill parsed output if any" },
+    "skillKey": "my.skill",
+    "metadata": { "...": "summarized metadata max ~6000 chars" }
+  },
+  "args": {
+    "iterationIndex": 0,
+    "...": "optional strategy row args except functionId"
+  }
+}
+```
+
+`iterationIndex` is **zero-based** (first MAIN attempt → optimizer call with `iterationIndex: 0`).
+
+### 5.3 Web-scope questions input
+
+Built by ai-tasks `buildResearchPlanQuestionsPayload`:
+
+```json
+{
+  "goal": "<nodeQuestion trimmed>",
+  "input": {
+    "nodeInput": null,
+    "rawRecord": { "...": "optional" }
+  },
+  "context": {
+    "memorySummary": { "jobMemory": {}, "taskMemory": {}, "executionMemory": {} },
+    "xynthesized": { "job": {}, "task": {} }
+  },
+  "args": {
+    "maxQuestions": 5,
+    "sourceType": "web",
+    "allowSkip": true,
+    "includeReasons": true
+  }
+}
+```
+
+**Migration note:** Replace ai-tasks inline `PLAN_WEB_SCOPE_SYSTEM` string with xynthesis Catalox template producing **identical** JSON shape (§6.3).
+
+---
+
+## 6. Output contracts (structured JSON)
+
+xynthesis validates model JSON **before** returning to ai-tasks. On parse/validation failure: throw `XynthesisResponseParseError` with raw text preserved (same as structured synthesis).
+
+### 6.1 Planner output — `ExecutionPlanResult`
+
+Minimum schema (all fields optional except empty object allowed):
+
+```typescript
+type ExecutionPlanResult = {
+  /** Primary merge field — preferred over plan/steps. */
+  instructions?: string;
+  plan?: string;
+  steps?: Array<{
+    title?: string;
+    description?: string;
+    reason?: string;
+  }>;
+  assumptions?: string[];
+  missingInputs?: string[];
+  suggestedContext?: string[];
+  /** Direct gateway overlays (optional). */
+  prompt?: string;
+  variables?: Record<string, unknown>;
+  templateTokens?: Record<string, unknown>;
+  /** Alternate nesting — ai-tasks adapters also read metadata.* today. */
+  metadata?: {
+    variables?: Record<string, unknown>;
+    templateTokens?: Record<string, unknown>;
+  };
+};
+```
+
+**Normalization (xynthesis or ai-tasks — pick one owner, document):**
+
+- ai-tasks today merges `instructions` ← `instructions` || `plan` || rendered `steps`; appends assumptions/missingInputs/suggestedContext into `instructions` text.
+- **Recommendation:** xynthesis returns **raw structured object**; ai-tasks keeps `adaptExecutionPlanResult` unchanged during migration, then optionally deletes adapter once xynthesis guarantees canonical shape.
+
+### 6.2 Optimizer output — `ExecutionEvaluateResult`
+
+```typescript
+type ExecutionEvaluateResult = {
+  /** Required — strict boolean; only `true` stops retry loop. */
+  satisfied: boolean;
+  feedback?: string;
+  suggestedChanges?: string[];
+  issues?: Array<{
+    issue: string;
+    severity?: string;
+    reason?: string;
+  }>;
+  variables?: Record<string, unknown>;
+  templateTokens?: Record<string, unknown>;
+  metadata?: {
+    variables?: Record<string, unknown>;
+    templateTokens?: Record<string, unknown>;
+  };
+};
+```
+
+**ai-tasks merge semantics (unchanged):**
+
+- `feedback` + rendered `suggestedChanges` + rendered `issues` → `variables.optimizerFeedback`
+- `suggestedChanges` → `variables.optimizerSuggestedChanges`
+- `templateTokens` shallow-merged into request
+- `satisfied === true` → stop retry loop
+
+### 6.3 Web-scope output — `PlanWebScopeQuestionsResult`
+
+Must match ai-tasks [`PlanWebScopeQuestionsOutput`](../../src/planWebScopeQuestions/index.ts):
+
+```typescript
+type PlanWebScopeQuestionsResult = {
+  questions: Array<{
+    id?: string;
+    question: string;
+    reason: string;
+    source: "ai-driven";
+  }>;
+  confidence: number; // 0–1 inclusive
+  skipped?: boolean;
+  reasonCodes?: string[];
+};
+```
+
+**Validation rules** (port from `parseAndValidatePlanWebScopeQuestionsOutput`):
+
+- Root must be object; `confidence` finite in [0, 1].
+- `questions` array length ≤ `args.maxQuestions` (1–20).
+- Each question: non-empty `question`, non-empty `reason`, `source` must be `"ai-driven"` when set.
+- Empty questions + `skipped: true` allowed (e.g. `reasonCodes: ["INPUT_TOO_THIN"]`).
+- xynthesis assigns UUID `id` when missing **or** leave to ai-tasks (document choice; ai-tasks can keep id generation).
+
+**System prompt content** to migrate into Catalox (currently in ai-tasks):
+
+```
+You are a planning assistant for web evidence collection.
+Return ONLY a single JSON object (no markdown fences, no prose) with this exact shape:
+{
+  "questions": Array<{ "id"?: string, "question": string, "reason": string, "source": "ai-driven" }>,
+  "confidence": number,
+  "skipped"?: boolean,
+  "reasonCodes"?: string[]
+}
+Rules:
+- "confidence" is a number from 0 to 1.
+- Each "question" must be a concrete web search or research question (non-empty string).
+- Each "reason" briefly explains why that question helps (non-empty string).
+- "source" must be the literal string "ai-driven" for every question entry.
+- Produce at most the requested maxQuestions items in "questions".
+- If you cannot propose useful questions, set "skipped": true, "questions": [], "confidence" <= 0.5, and include "reasonCodes" such as ["INPUT_TOO_THIN"].
+```
+
+---
+
+## 7. Invoke contract (must match 4.2+)
+
+Every new action **must** follow [`xynthesis-orchestrator-invoke-contract-4.2.md`](./xynthesis-orchestrator-invoke-contract-4.2.md):
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `model` | yes | Resolved alias from ai-tasks |
+| `outputExpectation` | yes | Throws if missing |
+| `reasoningEffort` | optional | Forward to Optimixer |
+| `temperature` / `topP` | optional | Echo in `invokeSummary.executionMetadata` |
+| `maxTokens` on request | optional ceiling only | Do not require hosts to pre-compute |
+| Host pre-resolve via `resolveMaxTokens` | **forbidden** | Internal Optimixer only |
+
+**Structured output:** Use JSON mode / schema-constrained generation where provider supports it; otherwise validate parse server-side and throw `XynthesisResponseParseError`.
+
+---
+
+## 8. Observability and correlation
+
+### 8.1 InvokeAttemptSummary
+
+Each action returns `invokeSummary` with:
+
+- `sidekickAction`: one of the three new keys
+- `tokenResolution` / Optimixer diagnostics
+- `routing` (OpenRouter vs direct)
+- `executionMetadata.temperature`, `executionMetadata.topP`, effective `reasoningEffort`
+
+### 8.2 Activix / workScope
+
+Forward `workScope.jobId`, `workScope.taskId`, `workScope.agentId`, and optional `identity` into xynthesis Activix phases:
+
+- Suggested activix action types: `execution-strategy-planner`, `execution-strategy-optimizer`, `plan-web-scope-questions`
+
+### 8.3 ai-tasks trace integration
+
+ai-tasks will push trace rows (already stubbed for FuncX):
+
+- Planner: `phase: "execution_strategy_planner"`, `taskType: "pre-execution"`
+- Optimizer: `phase: "execution_strategy_optimizer"`, metadata `{ iterationIndex, satisfied }`
+- Web-scope: existing `plan-web-scope-questions` stage → `LlmCallObservation`
+
+---
+
+## 9. Catalox / template deliverables
+
+For each action, ship:
+
+1. Sidekick template (system + user Handlebars or equivalent).
+2. Optimixer catalog spec (`reasoningEffort`, `outputIntent`, …).
+3. JSON schema for structured output validation.
+4. Studio/catalog id stable across releases (version template, not action key).
+
+| Catalox item | Action key | Replaces FuncX id |
+|--------------|------------|-------------------|
+| Execution plan sidekick | `execution-plan` | `execution/plan` |
+| Execution evaluate sidekick | `execution-evaluate-result` | `execution/evaluate-result` |
+| Plan web scope questions sidekick | `plan-web-scope-questions` | `research/plan-questions` |
+
+---
+
+## 10. Test ergonomics
+
+Mirror existing xynthesis test patterns:
+
+```typescript
+/** Test-only: replace live provider call for execution-strategy actions. */
+export function setExecutionStrategyActionInvoker(
+  fn: ((req: RunExecutionPlanRequest | RunExecutionEvaluateResultRequest) => Promise<unknown>) | null
+): void;
+
+export function setPlanWebScopeQuestionsActionInvoker(
+  fn: ((req: RunPlanWebScopeQuestionsRequest) => Promise<PlanWebScopeQuestionsResult>) | null
+): void;
+```
+
+ai-tasks will migrate `setFuncxExecutionStrategyInvoker` → xynthesis invoker or wrap `setSynthesisInvoker` with action discrimination.
+
+---
+
+## 11. Migration plan
+
+### Phase 1 — xynthesis ships actions (≥ 4.4.0)
+
+- Implement three actions + Catalox templates + tests.
+- Export types and schemas.
+- Document in xynthesis CHANGELOG.
+
+### Phase 2 — ai-tasks migration (8.5.x)
+
+- Replace `runPlannerFuncx` / `runOptimizerFuncx` with `runPostStepLlmCall`-style wrappers calling new xynthesis actions.
+- Map `modelConfig.preActionModel` / `postActionModel` per §4.3.
+- Add `LlmCallStage`: `execution-strategy-planner`, `execution-strategy-optimizer`.
+- Extend `sidekickActionForStage` mapping in ai-tasks.
+- Wire `LlmCallObservation` / `logLlmProviderInvocation` for new stages.
+- Remove `runFuncxExecutionStrategy.ts`, `runResearchPlanQuestionsFuncx.ts`, direct `@x12i/funcx` imports.
+- Deprecate exports: `setFuncxExecutionStrategyInvoker`, `FUNCX_*_FUNCTION_ID`, `unwrapFuncxRunValue`, `backend: "funcx"`.
+- Keep `adaptExecutionPlanResult` / `adaptEvaluateResultResponse` until xynthesis output is proven stable (then inline or delete).
+
+### Phase 3 — cleanup
+
+- Remove `@x12i/funcx` from ai-tasks `dependencies` and `overrides` if no transitive need.
+- Update `CANONICAL_EXECUTION_STRATEGIES` catalog metadata: `runtimeKind: "xynthesis-action"` (replace `funcx-wrapper`).
+- Archive FuncX hosting checklist items as deprecated.
+
+---
+
+## 12. ai-tasks follow-up checklist (after xynthesis ships)
+
+- [ ] Bump `"@exellix/xynthesis": "^4.4.0"` (or whatever minor ships this).
+- [ ] Implement `runExecutionPlannerViaXynthesis` / `runExecutionOptimizerViaXynthesis` in `src/execution-strategies/`.
+- [ ] Pass `preActionModel` / `postActionModel` + `llmCall` overlays from `RunTaskRequest`.
+- [ ] Update `runPlanWebScopeQuestions` to call xynthesis action only (remove FuncX backend).
+- [ ] Remove `@x12i/funcx` direct dependency.
+- [ ] Update tests: replace `setFuncxExecutionStrategyInvoker` with xynthesis test invoker.
+- [ ] Update README / BREAKING-CHANGES / RUNTASK_REQUEST.md.
+- [ ] Update task-strategies catalog descriptions and `defaultFunctionId` → `defaultSidekickAction` (or remove functionId concept).
+
+---
+
+## 13. Acceptance criteria (xynthesis PR)
+
+### 13.1 execution-plan
+
+- [ ] `runExecutionPlan({ model, outputExpectation, goal, input, context, workScope })` returns valid `ExecutionPlanResult`.
+- [ ] Optimixer runs; no host `maxTokens` required.
+- [ ] `invokeSummary.sidekickAction === "execution-plan"`.
+- [ ] Integration test with mock provider: structured JSON → typed result.
+- [ ] Invalid JSON → `XynthesisResponseParseError`.
+
+### 13.2 execution-evaluate-result
+
+- [ ] Accepts `result` + `iterationIndex`; returns `satisfied` boolean.
+- [ ] Handles missing/partial `result.rawText` gracefully (empty string ok).
+- [ ] `invokeSummary` includes iteration metadata when passed in request context.
+
+### 13.3 plan-web-scope-questions
+
+- [ ] Output passes ai-tasks validation rules (§6.3).
+- [ ] `maxQuestions` clamped 1–20 server-side.
+- [ ] Parity test: same input → same shape as current ai-tasks inline prompt path (golden fixture).
+
+### 13.4 Cross-cutting
+
+- [ ] All three actions accept `reasoningEffort`, `temperature`, `topP`.
+- [ ] Model alias resolution via `@x12i/ai-profiles` consistent with audit/polish.
+- [ ] Activix correlation when diagnostics enabled.
+- [ ] CHANGELOG + README section for orchestrators.
+
+---
+
+## 14. Non-goals / explicit boundaries
+
+- xynthesis **must not** implement the optimizer retry loop or call `@exellix/ai-skills`.
+- xynthesis **must not** require `@exellix/ai-tasks` as a dependency.
+- No new npm package — ai-tasks is the only orchestrator consumer.
+- FuncX may remain xynthesis's internal provider adapter; ai-tasks should not call FuncX directly after migration.
+
+---
+
+## 15. Paste-ready GitHub issue (xynthesis repo)
+
+**Title:** Add execution-strategy sidekick actions (planner, optimizer, plan-web-scope-questions)
+
+**Body:**
+
+> `@exellix/ai-tasks` currently invokes FuncX `execution/plan`, `execution/evaluate-result`, and optionally `research/plan-questions` for MAIN wrappers. These bypass `modelConfig`, Optimixer, and `InvokeAttemptSummary`.
+>
+> Please add three first-class xynthesis actions (`execution-plan`, `execution-evaluate-result`, `plan-web-scope-questions`) on the same contract as audit/polish (`executeXynthesisAction`, required `outputExpectation`, optional `reasoningEffort`).
+>
+> Full spec (input/output JSON, model slot policy, Catalox deliverables, acceptance tests):
+> [link to this doc in ai-tasks repo]
+>
+> ai-tasks will migrate in 8.5.x and remove direct `@x12i/funcx` usage. No separate consumer package planned.

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

@@ -167,8 +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.
+- [x] Replace `isKnownProfileOrShortcut` → `isKnownProfileChoice` (shipped in **4.3.1** — see [xynthesis-ai-profiles-2.1-import-break.md](./xynthesis-ai-profiles-2.1-import-break.md)).
+- [x] `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.2",
+  "version": "8.5.0",
   "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",
@@ -14,6 +14,7 @@
     "CHANGELOG.md",
     "RUNTASK_REQUEST.md",
     "documenations",
+    ".docs",
     ".env.example",
     ".metadata"
   ],
@@ -62,7 +63,6 @@
     "@x12i/activix": "$@x12i/activix",
     "@x12i/ai-profiles": "$@x12i/ai-profiles",
     "@x12i/catalox": "$@x12i/catalox",
-    "@x12i/funcx": "$@x12i/funcx",
     "@x12i/logxer": "$@x12i/logxer"
   },
   "dependencies": {
@@ -78,13 +78,12 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.3.1",
+    "@exellix/xynthesis": "^4.4.0",
     "@x12i/activix": "^8.5.0",
     "@x12i/ai-profiles": "^2.1.0",
     "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
     "@x12i/execution-memory-manager": "^1.2.0",
-    "@x12i/funcx": "^4.3.3",
     "@x12i/logxer": "^4.6.0",
     "@x12i/rendrix": "^4.3.0",
     "@x12i/search-adapter": "^1.5.1",