@exellix/ai-tasks 8.4.2 → 8.4.3

package/.docs/possible-components/pre-component/builder-guide.md

@@ -0,0 +1,127 @@
+# Pre-Task component — **builder guide** (single entry for implementation)
+
+Use this file plus the linked handler specs. **Full** platform rules (Activix field shapes, identity merge algorithm): [`../integration/platform.md`](../integration/platform.md).
+
+---
+
+## 1. What you are building
+
+A **Pre-Task engine** that runs **before MAIN** and returns:
+
+- Possibly updated `jobMemory` / `taskMemory` / `executionMemory` / `input`
+- Optional **`contextMarkdown`** override for the MAIN skill prompt
+- Optional **`synthesizedContext`** artifact on `executionMemory`
+- **`intermediateSteps`** for observability
+
+**Protocol:** [`unified-protocol.md`](unified-protocol.md).
+
+---
+
+## 2. Stack (minimum you must honor)
+
+| Topic | Rule |
+|-------|------|
+| LLM calls | **aifunctions-js** (`ask` / compatible client). Not a separate ai-gateway product API. |
+| Synthesized-context step | **@athenices/xynthesis** for templates, modes, validation; **SynthesisInvoker** calls aifunctions-js. |
+| Observability | **Activix** phase records where the host enables it; top-level **`identity`** on every record per `docs/activix-identity.md`. |
+| Correlation | Prefer **`correlationId === taskId`** for one run. |
+
+---
+
+## 3. NPM dependencies (pin to tested versions from `@woroces/ai-tasks`)
+
+| Package | Role in pre paths |
+|---------|-------------------|
+| `aifunctions-js` | All generative calls (scoping, System-2, synthesis invoker). |
+| `@athenices/xynthesis` | Synthesized-context PRE handler. |
+| `@woroces/ai-skills` | `enrichMemoriesWithScoping`, `resolveRawTemplate`, executor (host). |
+| `@woroces/memory-narrix-adapter` | `adaptMemoryToNarrixInput` (narrix preprocessor). |
+| `@narrices/narrix-*` | Ingest, adapters, runner, packs, web-scoper (see `package.json` of ai-tasks). |
+| `@xronoces/activix` | Phase recording (with host wrapper). |
+
+Also used indirectly: `handlebars` (if you render web scope templates in-host).
+
+---
+
+## 4. Host contract (skills / task runtime)
+
+The pre engine **does not** replace the skills client. The host must provide:
+
+| Capability | Used by |
+|------------|---------|
+| `enrichMemoriesWithScoping(skillKey, "task", memoryBundle)` | Synthesis PRE, direct-path enrich (same as today). |
+| `resolveRawTemplate(skillKey, "instructions" \| "prompt")` → raw markdown | Structured synthesis + template cores. |
+| Optional: same client’s `generateContextMarkdown` / executor | After pre returns, MAIN still runs in host. |
+
+---
+
+## 5. Request fields this engine reads (`RunTaskRequest`)
+
+| Field | Handler |
+|-------|---------|
+| `narrix?: NarrixPreProcessorConfig` | [`handler-narrix-preprocessor.md`](handler-narrix-preprocessor.md) |
+| `executionPipeline` with PRE `synthesized-context` | [`handler-synthesized-context.md`](handler-synthesized-context.md) |
+| `aiScoping?: AIScopingInstruction[]` | [`handler-ai-scoping.md`](handler-ai-scoping.md) |
+| `includeContextInPrompt`, `taskMemory`, `jobMemory`, `executionMemory`, `skillKey`, `input`, `identity`, `jobId`, `agentId` | Multiple |
+
+**Note:** `executionType: narrix-then-direct` + `narrixInput` is a **different** flow (Narrix then MAIN with `taskMemory.narrix`); it still uses `narrixRunHandler` and is **host-orchestrated** in `task-sdk.ts`. If your pre package only covers “pipeline + scoping + narrix preprocessor”, document whether `narrix-then-direct` stays in the host.
+
+---
+
+## 6. Environment variables (pre-relevant)
+
+| Variable | Handler / area |
+|----------|----------------|
+| `AI_SCOPING_MODEL`, `AI_SCOPING_CONCURRENCY`, `AI_SCOPING_TIMEOUT_MS` | AI scoping |
+| `SYNTHESIS_MODEL`, `SYNTHESIS_TIMEOUT_MS`, `SYNTHESIS_MAX_OUTPUT_LENGTH` | Synthesis PRE |
+| `NARRIX_SYSTEM2_MODE`, `NARRIX_SYSTEM2_MODEL`, `NARRIX_SYSTEM2_MAX_ITERATIONS`, `NARRIX_SYSTEM2_ENABLE_WRITES`, `NARRIX_SYSTEM2_SAVE_ARTIFACTS`, `NARRIX_SYSTEM2_ARTIFACT_DIR`, … | System-2 |
+| `TAVILY_API_KEY` | Web scope (default search) |
+| `MONGO_LOGS_DB` | Default `bindingDefaultsDb` merged into `execution` (current SDK behavior) |
+
+Centralize in one config module in your package.
+
+---
+
+## 7. Source file manifest (current `ai-tasks`)
+
+Copy or depend on these paths when extracting:
+
+| Path | Notes |
+|------|--------|
+| `src/aiScoping/*` | Scoping + `validateAiScoping.ts` |
+| `src/internal/runLlmTextCall.ts` | Shared LLM primitive |
+| `src/synthesis/resolveSourceMaterial.ts`, `synthesisGatewayCompat.ts`, `index.ts` | Synthesis wiring + xynthesis re-exports |
+| `src/narrix/**` except tests | Narrix run, web scoper, system2, context markdown builders |
+| `src/utils/jsonPaths.ts` | `getByPath` for scoping sources |
+| `src/types/task-types.ts` | Types listed in handler docs |
+
+---
+
+## 8. Definition of done (acceptance)
+
+- [ ] Handlers run in order: narrix preprocessor (if any) → pipeline PRE synthesized-context (if any) → (host) enrich → ai scoping (if any).  
+- [ ] Synthesis: markdown + structured modes behave per [`handler-synthesized-context.md`](handler-synthesized-context.md); `fallbackToDirect` respected.  
+- [ ] Scoping: parallel bounded concurrency; missing paths skipped; validation before LLM.  
+- [ ] Web scope: never throws to caller; `webContext` optional on `executionMemory`.  
+- [ ] System-2: PatchPlan JSON validated; iteration cap enforced.  
+- [ ] Activix + `identity` on each recorded phase when host passes client.  
+- [ ] Test hooks: scoping / synthesis / llmPlan / web scoper injectable.
+
+---
+
+## 9. Types (canonical source)
+
+Implementations should align with **`src/types/task-types.ts`**: `AIScopingInstruction`, `AIScopedItem`, `SynthesisConfig`, `SynthesizedContextArtifact`, `ContextSourcePolicy`, `WebEvidenceConfig`, `ExecutionStep`, `NarrixPreProcessorConfig`, `IntermediateStep`, and pipeline constants (`SYNTHESIZED_CONTEXT`). Re-export or depend on a shared types package when splitting repos.
+
+---
+
+## 10. Read next
+
+1. [`unified-protocol.md`](unified-protocol.md)  
+2. [`handler-narrix-preprocessor.md`](handler-narrix-preprocessor.md)  
+3. [`handler-synthesized-context.md`](handler-synthesized-context.md)  
+4. [`handler-ai-scoping.md`](handler-ai-scoping.md)  
+5. [`handler-web-scope.md`](handler-web-scope.md)  
+6. [`handler-narrix-system2.md`](handler-narrix-system2.md)  
+7. [`gaps-and-artifacts.md`](gaps-and-artifacts.md)  
+8. Merge / shared checklist: [`../integration/roadmap-and-checklists.md`](../integration/roadmap-and-checklists.md) Phase B, [`../integration/reintegrate-into-ai-tasks.md`](../integration/reintegrate-into-ai-tasks.md)

package/.docs/possible-components/pre-component/gaps-and-artifacts.md

@@ -0,0 +1,35 @@
+# Pre-Task component — gaps, code, templates
+
+What is **missing, external, or optional to add** when packaging the pre engine. **Behavior, env tables, dependencies, acceptance:** [`builder-guide.md`](builder-guide.md).
+
+## Code modules (current `ai-tasks` anchors)
+
+| Area | Paths / packages | Note |
+|------|------------------|------|
+| AI scoping | `src/aiScoping/*` (incl. `validateAiScoping.ts`) | Depends on `src/internal/runLlmTextCall.ts`. |
+| Synthesis source wiring | `src/synthesis/resolveSourceMaterial.ts`, `synthesisGatewayCompat.ts` | Re-export surface: `src/synthesis/index.ts` → **@athenices/xynthesis**. |
+| Narrix pre + web | `src/narrix/*` (large), `task-sdk` orchestration | System-1 ingest lives largely in **external** Narrix packages. |
+| System-2 | `src/narrix/system2/*` | Tied to `runLlmTextCall`. |
+| Types | `src/types/task-types.ts` (`AIScoping*`, `SynthesisConfig`, pipeline types) | May need a shared types package when extracting. |
+
+## Templates & assets
+
+| Asset | Status in repo | Action for standalone pre package |
+|-------|----------------|-------------------------------------|
+| Synthesis markdown templates | Loaded via **@athenices/xynthesis** `loadSynthesisTemplates()` | Confirm templates ship **inside** xynthesis or **vendor** copies into the pre package; audit/polish disk templates belong in **post** spec only. |
+| Skill instructions/prompt | **@woroces/ai-skills** `resolveRawTemplate` | Pre component needs a **host callback**; not bundled in pre-only package. |
+| AI scoping | **No** separate disk template — prompts inline in `runScopingCall.ts` | Optional: externalize to `templates/pre/scoping-system.md` for versioning. |
+| Narrix System-2 | System prompt **inline** in `llmPlan.ts` | Optional: externalize for tuning without code change. |
+
+## Environment variables
+
+Canonical table: [`builder-guide.md`](builder-guide.md) §6.
+
+## Tests / DI hooks to preserve
+
+`setScopingGateway`, `setSynthesisInvoker` / `setSynthesisGateway`, `setLlmPlanGateway`, `setWebScoperForTesting` — or equivalent constructor injection in a new package.
+
+## Open decisions
+
+- Whether **narrix-preprocessor** ships inside pre package or stays a **peer** dependency.  
+- Single **Activix** wrapper module shared with post (owned under integration / shared lib).

package/.docs/possible-components/pre-component/handler-ai-scoping.md

@@ -0,0 +1,45 @@
+# Handler: AI memory scoping (`direct.ai-scoping`)
+
+> **Platform:** LLM + Activix + `identity` — [`../integration/platform.md`](../integration/platform.md).
+
+## Purpose
+
+Before MAIN, optionally turn memory slices into concise text. Each instruction is one LLM call over **only** resolved source content; results merge into `input.aiScoped[]`.
+
+## Trigger (current repo)
+
+- `RunTaskRequest.aiScoping?: AIScopingInstruction[]`
+- After enrich, before `executor.execute` in `_executeDirect` (`src/core/task-sdk.ts`).
+- Code: `src/aiScoping/runAiScoping.ts`, `runScopingCall.ts`.
+
+## Inputs
+
+| Field | Notes |
+|--------|--------|
+| Bundle | `jobMemory` / `taskMemory` / `executionMemory`; paths via `getByPath`. |
+| Instructions | `source`, `instructions` (NL), `targetToken` per item. |
+| Concurrency / timeout | Defaults 5 workers, 30s/item; env `AI_SCOPING_*`. |
+
+Skipped if source path missing (no error). `validateAiScoping` before calls.
+
+## Single call (`runScopingCall`)
+
+- Fixed system: use only source, no invention, plain text, no markdown fences.
+- User: `Instructions:\n…\n\nSource content:\n…` (serialized value).
+- `runLlmTextCall`: temp 0.2, maxTokens 2048; test hook `setScopingGateway`.
+
+## Orchestration (`runAiScoping`)
+
+Bounded parallel workers; failures → omit that item (tolerant).
+
+## Output
+
+`AIScopedItem[]` → merged into object `input` as `aiScoped`.
+
+## Non-goals
+
+Not full RAG; chunks are independent. No automatic memory writeback.
+
+## Types
+
+`AIScopingInstruction`, `AIScopedItem` — `src/types/task-types.ts`.

package/.docs/possible-components/pre-component/handler-narrix-preprocessor.md

@@ -0,0 +1,49 @@
+# Handler: Narrix preprocessor (`narrix-preprocessor`)
+
+> **Platform:** [`../integration/platform.md`](../integration/platform.md).  
+> **Sub-steps:** [`handler-web-scope.md`](handler-web-scope.md), [`handler-narrix-system2.md`](handler-narrix-system2.md) (inside `narrixRunHandler`).
+
+## Purpose
+
+When `RunTaskRequest.narrix` is set, adapt task memory to a **Narrix run input**, execute **`narrixRunHandler`** (local skill `skills/skill.local:narrixRun`), attach enrichment to **`executionMemory`** and **`jobMemory`**, optionally fetch **web evidence**.
+
+## Trigger (current repo)
+
+- `request.narrix` present → phase `narrix` in `task-sdk.ts` before local-task dispatch and pipeline.  
+- Uses `adaptMemoryToNarrixInput` from `@woroces/memory-narrix-adapter` with path preferences (`executionMemory.input.raw`, `jobMemory.currentRecord`, …).  
+- Failure to adapt → **throw** (strict). Narrix run `ok: false` → **throw**.
+
+## Config (`NarrixPreProcessorConfig`) — fields builders need
+
+| Field | Role |
+|-------|------|
+| `datasetId` | Required. |
+| `attachToField` | Default `_narrix`; where attachment lives on `executionMemory`. |
+| `deterministicSort` | Default true (narrative ordering). |
+| `enableWebScope` | After success, call web scoper → `executionMemory.webContext`. |
+| `webScopeTemplates`, `webScopeQuestionTemplate`, `webScopeObjects`, `webScoping` | Web query shaping (see `NarrixPreProcessorConfig` in `task-types.ts`). |
+| `engineConfigPath`, `packsRoot`, `assumptionsPolicy` | Reserved / future. |
+
+Full interface: `src/types/task-types.ts`.
+
+## Success path (summary)
+
+1. `adaptMemoryToNarrixInput(...)` → `narrixInput`.  
+2. `narrixRunHandler({ input, ctx })` with skill/job/graph ids from request.  
+3. `buildNarrixAttachment(success)` → store under `executionMemory[attachToField]` and `jobMemory._narrix` (current behavior).  
+4. If `enableWebScope`: `resolveWebScopeQuestionAndTemplates` + `runWebScope` → merge `webContext` (lenient).  
+
+## Related execution mode
+
+**`narrix-then-direct`** uses resolved `narrixInput` + `narrixRunHandler` + `applyNarrixScope` and writes **`taskMemory.narrix`** — different injection shape. Implement either in the same package behind flags or document as **host-only** if out of scope.
+
+## Code anchors
+
+- `src/core/task-sdk.ts` (narrix block)  
+- `src/narrix/task.ts` (`narrixRunHandler`)  
+- `src/narrix/buildNarrixAttachment.ts`, `buildWebScopeScopeInput`, `webScoper.ts`  
+- `src/activix/phaseTracking.ts` (`withPhaseRecord`)
+
+## Dependencies
+
+Narrix ingest/runner/packs packages; `NARRIX_DISABLED` / flags in `src/narrix/flags.ts` may disable behavior.

package/.docs/possible-components/pre-component/handler-narrix-system2.md

@@ -0,0 +1,35 @@
+# Sub-handler: Narrix System-2 LLM patch plan
+
+> **Platform:** [`../integration/platform.md`](../integration/platform.md).
+
+## Purpose
+
+After Narrix System-1, optionally detect gaps and call an LLM for **PatchPlan** JSON (routing/schema actions), apply patches, optionally re-run System-1.
+
+## Trigger (current repo)
+
+- `narrixRunHandler` → `runWithSystem2` (`src/narrix/system2/runWithSystem2.ts`)
+- LLM: `llmPlan` (`src/narrix/system2/llmPlan.ts`)
+- Env/options: `NARRIX_SYSTEM2_MODE`, `maxIterations`, `enableWrites`, `model`, etc.
+
+## LLM I/O
+
+- User content from `buildSystem2Input(input, result, gapHints)`.
+- System: PatchPlan JSON only; allowed action types defined in code (`rememberDatasetPackRouting`, …).
+- Parse: `extractJsonFromText` + `validatePatchPlan`.
+
+## Invocation
+
+`runLlmTextCall`: temp 0.2, maxTokens 8192; `setLlmPlanGateway` for tests.
+
+## Post-LLM
+
+`applyPatchPlan`, optional `writeArtifacts`, rerun loop under `maxIterations`.
+
+## Non-goals
+
+Not a general agent; closed action set. Does not replace System-1 ingest (external packages).
+
+## Dependencies (repo)
+
+`src/narrix/system2/*`, `src/internal/runLlmTextCall.ts`

package/.docs/possible-components/pre-component/handler-synthesized-context.md

@@ -0,0 +1,65 @@
+# Handler: synthesized context (`pipeline.synthesized-context`)
+
+> **Platform:** **@athenices/xynthesis** for synthesis contracts; **aifunctions-js** inside `SynthesisInvoker`; Activix + `identity` — [`../integration/platform.md`](../integration/platform.md) §1b.
+
+## Purpose
+
+PRE pipeline step: build markdown **context** for MAIN from memory, Narrix attachment, optional web evidence, and rendered skill templates. Modes: **markdown** completion vs **structured** synthesis (cores + validation).
+
+## Trigger (current repo)
+
+- `executionPipeline`: `{ phase: "pre", type: "synthesized-context", config?: SynthesisConfig }`
+- Requires `includeContextInPrompt === true` or `config.autoEnableContext === true`
+- `WorexClientTasks._runSynthesizedContextPreStep` in `src/core/task-sdk.ts`
+
+## Orchestration (high level)
+
+1. Merge `executionMemory` into `jobMemory.execution` (incl. `bindingDefaultsDb` default).  
+2. `enrichMemoriesWithScoping(skillKey, "task", memoryBundle)`.  
+3. Cleanse `execution` for prompts.  
+4. Narrix-shaped attachment from `executionMemory[attachToField]` or `taskMemory.narrix`.  
+5. `buildSynthesizerInputMaterial` (**@athenices/xynthesis** + host `resolveSourceMaterial*`).  
+6. `getRenderedTemplates` (skill raw templates + placeholders).  
+7. Branch: markdown vs structured (below).  
+8. Optional `SynthesizedContextArtifact` on `executionMemory.synthesizedContext`.  
+
+`fallbackToDirect` → empty context instead of throw on materialization failure (when enabled).
+
+## Mode A — Markdown
+
+- `loadSynthesisTemplates`, `buildSynthesisSystemPrompt`, `runSynthesisCall` from **@athenices/xynthesis**.
+- Defaults: model from config → `SYNTHESIS_MODEL` → `gpt-5-nano`; timeout `SYNTHESIS_TIMEOUT_MS` / 30_000.
+
+## Mode B — Structured
+
+- Parts: `localMarkdown` / `supportingMarkdown`; `resolveSynthesisQuestion`; `discoverTemplateCores`.
+- Custom path: `getContextSynthesizer()` if set; else `runStructuredSynthesisGatewayCall`.
+- Output: `buildSynthesizedContextMarkdown(payload)`.
+
+## Xynthesis vs aifunctions-js (single definition)
+
+| Layer | Role |
+|-------|------|
+| **@athenices/xynthesis** | Templates, modes, validation, artifact types, `setSynthesisInvoker`. |
+| **aifunctions-js** | Implement invoker with `client.ask` (or shared helper). |
+
+## Testing / migration
+
+- `setSynthesisInvoker` (preferred).  
+- Legacy: `src/synthesis/synthesisGatewayCompat.ts` → `setSynthesisGateway` for `invoke`-shaped mocks only.
+
+## Downstream
+
+MAIN uses `overrideContext`; `synthesisContextAuthoritative` blocks Narrix/web fill-in when empty. POST audit/polish use captured context markdown.
+
+## Config surface
+
+`SynthesisConfig`: `modelConfig`, `timeoutMs`, `maxOutputLength`, `synthesisInputStrategy`, `contextSourcePolicy`, `memoryPaths`, `webEvidence`, `fallbackToDirect`, structured limits, prompt overrides, mode.
+
+## Risks
+
+Structured mode needs `resolveRawTemplate` / registry; missing templates → errors unless fallback.
+
+## Repo anchors
+
+`src/synthesis/resolveSourceMaterial.ts`, `src/synthesis/synthesisGatewayCompat.ts`, `src/synthesis/index.ts` (re-exports xynthesis).

package/.docs/possible-components/pre-component/handler-web-scope.md

@@ -0,0 +1,29 @@
+# Sub-step: Web scope / evidence (Narrix add-on)
+
+> **Platform:** Activix + `identity` for phases; no generative LLM here — [`../integration/platform.md`](../integration/platform.md).
+
+## Purpose
+
+After a successful Narrix pre-processor run, optionally fetch search-backed evidence into `executionMemory.webContext` for synthesis / MAIN.
+
+## Trigger (current repo)
+
+- `request.narrix.enableWebScope === true`
+- `resolveWebScopeQuestionAndTemplates` + `runWebScope` in `src/narrix/webScoper.ts`, called from `task-sdk.ts`.
+
+## Stack
+
+- `createWebScoper` + `createSearchAdapter` (Tavily + `TAVILY_API_KEY` default).
+- Errors → `{ available: false, reason: "error", error }` (no throw).
+
+## Testing
+
+`setWebScoperForTesting`, `resetWebScoperSingleton`.
+
+## Relation to synthesis
+
+`SynthesisConfig.webEvidence` / `resolveSourceMaterial*` may consume `webContext` from memory.
+
+## Dependencies
+
+`@narrices/narrix-web-scoper`, `@narrices/search-adapter`

package/.docs/possible-components/pre-component/unified-protocol.md

@@ -0,0 +1,89 @@
+# Pre-Task component — unified protocol
+
+> **Scope:** Target architecture only; not a mandate to change `ai-tasks` code until you choose to.  
+> **Shared platform (aifunctions-js, Activix, identity, Xynthesis):** single source of truth is [`../integration/platform.md`](../integration/platform.md).
+
+---
+
+## Goal
+
+One **Pre-Task engine** that:
+
+- Accepts a standard **input envelope** (task request, skills client, memory, optional Activix + correlation + identity).
+- Runs an **ordered chain** of handlers sharing one protocol.
+- Produces **patches** to request/memory/input, optional **context override** for MAIN, optional **synthesis artifact**, and **intermediate steps**.
+
+---
+
+## Handler protocol (conceptual)
+
+```ts
+type PreHandlerId =
+  | "narrix-preprocessor"
+  | "pipeline.synthesized-context"
+  | "direct.ai-scoping";
+
+interface PreHandlerContext {
+  request: RunTaskRequest;
+  identity?: Record<string, unknown>;
+  memoryBundle?: unknown;
+  skillsClient?: unknown;
+  correlationId?: string;
+  activix?: unknown;
+  prior: {
+    contextMarkdownOverride?: string;
+    synthesisContextAuthoritative?: boolean;
+    executionMemoryPatch?: Record<string, unknown>;
+  };
+}
+
+interface PreHandlerResult {
+  ok: boolean;
+  patches?: {
+    jobMemory?: Record<string, unknown>;
+    taskMemory?: Record<string, unknown>;
+    executionMemory?: Record<string, unknown>;
+    input?: unknown;
+  };
+  contextMarkdownOverride?: string;
+  synthesisContextAuthoritative?: boolean;
+  artifact?: unknown;
+  intermediateSteps?: IntermediateStep[];
+  error?: { code: string; message: string };
+}
+
+interface PreTaskHandler {
+  id: PreHandlerId;
+  order: number;
+  shouldRun(ctx: PreHandlerContext): boolean;
+  run(ctx: PreHandlerContext): Promise<PreHandlerResult>;
+}
+```
+
+**Composition:** engine merges `patches` in order, concatenates `intermediateSteps`, forwards `prior` to the next handler. Per-handler failure policy (strict vs tolerant) is part of each handler spec.
+
+---
+
+## Built-in handlers (index)
+
+| Handler id | Trigger (today) | Detail doc |
+|------------|-----------------|------------|
+| `narrix-preprocessor` | `RunTaskRequest.narrix` | [`handler-narrix-preprocessor.md`](handler-narrix-preprocessor.md); web scope [`handler-web-scope.md`](handler-web-scope.md). |
+| `pipeline.synthesized-context` | `executionPipeline` PRE `synthesized-context` | [`handler-synthesized-context.md`](handler-synthesized-context.md) (**@athenices/xynthesis**). |
+| `direct.ai-scoping` | `RunTaskRequest.aiScoping[]` | [`handler-ai-scoping.md`](handler-ai-scoping.md). |
+
+**Narrix System-2** (`llmPlan`) is a **sub-phase** of narrix (or a nested handler with the same result type). Spec: [`handler-narrix-system2.md`](handler-narrix-system2.md).
+
+---
+
+## Canonical execution order
+
+1. `narrix-preprocessor` (if `request.narrix`)  
+2. Pipeline PRE steps — `pipeline.synthesized-context` when present  
+3. MAIN prep inside direct: memory enrich → `direct.ai-scoping` → executor  
+
+---
+
+## Extension
+
+New pre feature ⇒ new `PreTaskHandler` + register. For synthesis-like behavior, prefer **Xynthesis** (see platform doc §1b) instead of parallel prompt systems.

package/.docs/prefer-openrouter-routing-policy.md

@@ -0,0 +1,132 @@
+# `PREFER_OPENROUTER` routing policy (Exellix stack)
+
+Normative contract for **OpenRouter vs vendor-direct** model routing across `@exellix/ai-tasks`, `@exellix/graph-engine`, graphs-studio, and `@x12i/ai-profiles` consumers.
+
+## Summary
+
+| Env / API field | Status | Meaning |
+|-----------------|--------|---------|
+| **`PREFER_OPENROUTER`** | **Current** | Operator **preference**: use OpenRouter when an OpenRouter API key is available. |
+| **`USE_OPENROUTER`** | **Deprecated** | Legacy name — read only as fallback when `PREFER_OPENROUTER` is unset. Remove from new code and docs. |
+| **`preferOpenRouter`** | **Current** (API) | Same semantics as env; use on `resolveInvocationPlan({ policy })` and model-resolution options. |
+| **`useOpenRouter`** | **Deprecated** (API) | Accepted temporarily for backward compatibility; map to `preferOpenRouter`. |
+
+**Vendor API keys** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) do **not** change this policy. They are used only when effective routing is **direct**. To force vendor-direct routing, set `PREFER_OPENROUTER=false`.
+
+---
+
+## Decision table (effective routing)
+
+After resolving `preferOpenRouter` (explicit → env → default **`true`**):
+
+| `preferOpenRouter` | `OPENROUTER_API_KEY` / `OPEN_ROUTER_KEY` | **Effective routing** | Wire model id (example) |
+|--------------------|--------------------------------------------|------------------------|-------------------------|
+| `false` | (any) | **direct** | `anthropic/claude-sonnet-4-5` |
+| `true` | present | **openrouter** | `openrouter/anthropic/claude-sonnet-4.5` |
+| `true` | absent | **direct** (fallback) + warning | `anthropic/claude-sonnet-4-5` |
+
+This replaces the old **`USE_OPENROUTER=true` without key → still plan OpenRouter** behavior. **Prefer** means “use OpenRouter when you *can*”; missing key → honest direct fallback.
+
+---
+
+## Environment
+
+```env
+# Prefer OpenRouter when OPENROUTER_API_KEY is set (default when omitted)
+PREFER_OPENROUTER=true
+
+# Force vendor-direct for all phases (MAIN + PRE/POST resolution)
+# PREFER_OPENROUTER=false
+
+OPENROUTER_API_KEY=sk-or-...
+ANTHROPIC_API_KEY=sk-ant-...   # used only when effective routing is direct
+```
+
+**Deprecated (do not set in new deployments):**
+
+```env
+USE_OPENROUTER=true   # → read as PREFER_OPENROUTER if PREFER_OPENROUTER unset
+```
+
+---
+
+## API (`@exellix/ai-tasks`)
+
+```ts
+import { resolveInvocationPlan } from "@exellix/ai-tasks";
+
+const plan = await resolveInvocationPlan({
+  profiles: {
+    preActionModel: "cheap",
+    skillModel: "cyber@default",
+    postActionModel: "cheap",
+  },
+  policy: {
+    preferOpenRouter: true,
+    openrouterApiKeyPresent: !!process.env.OPENROUTER_API_KEY,
+  },
+});
+```
+
+Policy fields on `resolveInvocationPlan`, `resolveProfileInvocationRouting`, and `resolveModelReference`:
+
+- **`preferOpenRouter`** — operator preference (see decision table).
+- **`openrouterApiKeyPresent`** — optional snapshot; defaults to env detection in-process.
+- **`useOpenRouter`** — deprecated alias for `preferOpenRouter`.
+
+Internal mapping to `@x12i/ai-profiles` (until that package renames its option):
+
+```ts
+resolveAIProfile(profile, {
+  useOpenRouter: effectiveUseOpenRouter, // from resolvePreferOpenRouterPolicy()
+});
+```
+
+---
+
+## Per-phase behavior (`runTask`)
+
+All phases (PRE / MAIN / POST) use the **same** `resolvePreferOpenRouterPolicy()` snapshot at plan and execute time.
+
+| Phase | Consumer | Notes |
+|-------|----------|-------|
+| PRE / POST | `@exellix/xynthesis` | Alias on wire; xynthesis resolves via ai-profiles with same effective routing. |
+| MAIN (skill) | `@exellix/ai-skills` | Concrete model id on wire; must include `openrouter/` prefix when effective routing is openrouter. |
+
+Plan output: trust **`routing`** + **`engineLabel`**, not model-id prefix alone.
+
+---
+
+## Migration checklist (other components)
+
+### graphs-studio / BFF
+
+- [ ] Rename env reads: `USE_OPENROUTER` → `PREFER_OPENROUTER` (keep deprecated fallback one release).
+- [ ] POST `/api/exellix/invocation-plan` body: `policy.preferOpenRouter` (stop sending `useOpenRouter`).
+- [ ] Simulate Engine layer: call `resolveInvocationPlan` only; do not re-derive from choices matrix.
+- [ ] Update UI copy: “prefers OpenRouter when key present” vs “always OpenRouter”.
+
+### `@exellix/graph-engine`
+
+- [ ] Pass `policy: { preferOpenRouter, openrouterApiKeyPresent }` into `resolveInvocationPlan` before execute.
+- [ ] Thread same snapshot into `runTask` policy (when execute parity lands on request env).
+- [ ] Stop documenting `USE_OPENROUTER` in graph runbooks.
+
+### `@x12i/ai-profiles` (upstream)
+
+- [ ] Add `preferOpenRouter` option + `readPreferOpenRouterFromEnv()` mirroring this policy.
+- [ ] Deprecate `useOpenRouter` / `USE_OPENROUTER` with fallback read.
+- [ ] Document that **`prefer`** falls back to direct when OpenRouter key absent.
+
+### `@exellix/xynthesis`
+
+- [ ] Replace `defaultResolveAiProfileOptions()` env wiring to use `PREFER_OPENROUTER`.
+- [ ] Funcx OpenRouter client: align with effective routing fallback when key missing.
+
+---
+
+## Related
+
+- [`.docs/ai-tasks-model-profile-aliases-7x.md`](ai-tasks-model-profile-aliases-7x.md) — profile slots on `RunTaskRequest`
+- `src/invocation/preferOpenRouterPolicy.ts` — implementation in ai-tasks
+- `src/invocation/resolveInvocationPlan.ts` — pre-run plan API