@exellix/ai-tasks 7.8.0

package/RUNTASK_REQUEST.md

@@ -0,0 +1,369 @@
+# RunTask request contract (`@exellix/ai-tasks`)
+
+Normative wire/SDK shape for `WorexClientTasks.runTask()` and the `runTask()` function wrapper.  
+There is **no HTTP server** in this package: hosts (e.g. graph-engine) must forward JSON equivalent to this contract into the SDK or executor.
+
+**Related artifacts**
+
+- Types: `RunTaskRequest` in [`src/types/task-types.ts`](src/types/task-types.ts) (extends `RunSkillRequest` from `@exellix/ai-skills`).
+- Template merge: [`mergeSkillTemplateVariables`](src/utils/skillTemplateVariables.ts).
+- Optional warnings / pipeline hints: [`normalizeRunTaskRequest`, `collectRunTaskRequestWarnings`, …](src/utils/runTaskRequestShape.ts) (`normalizeRunTaskRequest` is a shallow clone; no legacy field folding).
+- Hard validation: [`assertRequiredRunSkillCorrelation`](src/utils/assertRequiredRunSkillCorrelation.ts) runs at the start of every `runTask()` (throws if `agentId` / `jobTypeId` / `taskTypeId` are missing or blank).
+- **Execution strategies:** validation in [`resolveExecutionStrategies`](src/execution-strategies/resolveExecutionStrategies.ts); FuncX integration [`runFuncxExecutionStrategy`](src/execution-strategies/runFuncxExecutionStrategy.ts). **FR / function contracts:** [`documenations/funcx-scoping-integration-gaps.md`](documenations/funcx-scoping-integration-gaps.md) §**6**. **Catalog / hosting** so `run()` resolves `execution/plan` etc.: [`documenations/funcx-catalog-hosting-checklist.md`](documenations/funcx-catalog-hosting-checklist.md).
+- JSON Schema fragment: [`documenations/schemas/v1/run-task-request.json`](documenations/schemas/v1/run-task-request.json).
+- Graph authoring vs this payload: [Graph task node (authoring) → `RunTaskRequest` (invoke)](#graph-task-node-authoring--runtaskrequest-invoke).
+- Orchestrator / other repos (dated tasks): [.docs/investigation/external-packages-assignments.md](.docs/investigation/external-packages-assignments.md).
+
+---
+
+## Deprecation policy
+
+- **`RunTaskRequest` v7** aligns with the closed JSON Schema: **no** root `question`, top-level `inputs`, `jobInput`, or `executionType` — hosts must compile authoring into `input`, `variables`, `jobContext`, `narrixMode` / `narrixInput`, **`executionStrategies`** (required array), and `executionPipeline` / strategy keys.
+- Set **`AI_TASKS_REQUEST_WARNINGS=1`** (or `true` / `yes`) to log structured JSON lines for ignored pipeline steps and observability hints.
+
+---
+
+## Canonical input bucket
+
+| Bucket | Role |
+|--------|------|
+| **`input`** | **Canonical task payload** (compiled from `inputsConfig` + `taskVariable` on graph nodes). Passed to handlers, NARRIX, synthesis, and the gateway **as its own field** — ai-tasks does **not** fold `input` into `variables` on the MAIN path. |
+| **`variables`** | **Job/graph template bucket only** (same content as `executionMemory.jobVariables` when graph-engine compiles the request). Forwarded **as-is** on `runTask` MAIN; **node-scoped** values belong on **`executionMemory.taskVariables`**, not here. |
+| **`jobContext`** | Optional host/graph seed for templates. **Not** merged into `variables` by ai-tasks; compile into **`variables`** / **`executionMemory.jobVariables`** before invoke (graph-engine) or use [`mergeSkillTemplateVariables`](src/utils/skillTemplateVariables.ts) outside `runTask`. Omitted from the executor spread when only used for pre-compile. |
+
+**Pass-through on MAIN (graph-engine 5.13+)**
+
+- **`variables`**, **`input`**, **`executionMemory`** (including **`jobVariables`** and **`taskVariables`**), **`xynthesized`**, and **`smartInput`** are sent to `@exellix/ai-skills` **without** flattening scopes into one bag.
+- Path prefixes **`jobVariables.*`** / **`taskVariables.*`** resolve downstream (Rendrix / gateway) against **`executionMemory`**. **`@exellix/ai-skills` ≥ 5.5.0** merges top-level `executionMemory` into gateway `workingMemory`; ai-tasks forwards it via [`pickRunSkillRequestFields`](src/utils/bridgeRunSkillGatewayMemory.ts) (requires **ai-skills ≥ 5.5.0** in `package.json`). Legacy **`variables.*`** ≡ **`jobVariables.*`** when the engine resolves paths.
+- [`mergeSkillTemplateVariables`](src/utils/skillTemplateVariables.ts) remains exported for hosts that want a single merged template map **outside** the default `runTask` MAIN path.
+
+**Templates vs handlers**
+
+- Gateway templates may read **`input.*`**, **`variables.*`** (job bucket), **`executionMemory.jobVariables.*`**, **`executionMemory.taskVariables.*`**, and top-level **`xynthesized`** / **`smartInput`**.
+- **`input.question`** is what handlers / NARRIX / synthesis read from **`request.input`**.
+
+---
+
+## `executionMemory` vs `execution`
+
+| Surface | Meaning |
+|---------|---------|
+| **Request `executionMemory`** | Canonical execution-scoped blob on `RunTaskRequest`. Graph-engine **5.13+** mirrors template variables in separate buckets: **`jobVariables`** (whole run) and **`taskVariables`** (current node). ai-tasks forwards both **as-is** (no flattening). Legacy path prefix **`variables.*`** ≡ **`jobVariables.*`** when the engine resolves paths. |
+| **`jobMemory.execution`** | Populated internally by merging **`executionMemory`** into existing `jobMemory.execution` (deep merge) before memory enrichment. |
+| **Response `executionMemory`** | Merged snapshot: request execution memory plus any `executionMemory` extracted from the skill response / `parsed`. |
+| **Response `executionState.executionMemory`** | Alias mirror of the same merged blob for callers expecting a nested `executionState`. |
+| **`parsed.executionMemory`** | If present on structured output, merged into the response top-level `executionMemory` when attaching execution state. |
+| **`metadata` / `meta`** | `meta` aliases `metadata` on the response for observability consumers. |
+
+---
+
+## `executionPipeline`
+
+- **Phases:** `"pre"` | `"main"` | `"post"` (`ExecutionPhase`).
+- **Rule:** If `executionPipeline` is non-empty, there must be **exactly one** step with **`phase: "main"`** or `runTask` throws.
+- **MAIN step `type`:** **Ignored** at runtime — MAIN always runs the same direct/gateway path (`runDirect` → executor). Conventionally `type: "direct"`.
+- **PRE:** Only **`type: "synthesized-context"`** runs. The implementation executes **at most one** such PRE step (the first in pipeline order), then **`break`s** — additional PRE steps are **skipped** (warn with `AI_TASKS_REQUEST_WARNINGS=1`).
+- **PRE types other than `synthesized-context`:** **Ignored** (warn when warnings enabled).
+- **POST:** Only **`audit`** and **`polish`** are implemented; other POST types are **ignored** (warn when warnings enabled).
+
+**Utilities:** `runUtility()` (e.g. `xynthesis-finalize`) is **not** a pipeline step; it is a separate API.
+
+Default when `executionPipeline` is omitted: MAIN runs once via the gateway (`runSkill`). **`executionStrategies`** controls optional FuncX planners (before MAIN) and optimizers (after each MAIN attempt); use **`[]`** for plain MAIN.
+
+---
+
+## Field inventory (runtime reads)
+
+Properties are classified for **default MAIN path** unless noted. Inherited **`RunSkillRequest`** fields follow `@exellix/ai-skills`; task extensions are in `RunTaskRequest`.
+
+### Required (always)
+
+| Property | Notes |
+|----------|--------|
+| `skillKey` | Routing: local registry vs gateway skill id. |
+| `agentId` | Non-empty string — `@exellix/ai-skills` activity / routing correlation. |
+| `jobTypeId` | Non-empty string — upstream job classification (catalog / telemetry). |
+| `taskTypeId` | Non-empty string — upstream task classification (catalog / telemetry). |
+| `executionStrategies` | Array of MAIN wrappers: **`planner`** (`phase: "before"`) and **`optimizer`** (`phase: "after"`), each with **`priority`** (sort ascending). Use **`[]`** for plain MAIN. |
+
+### Optional — core execution
+
+| Property | Classification |
+|----------|----------------|
+| `input` | Optional task payload (`string` or object). |
+| `variables` | Job/graph template bucket; forwarded as-is on MAIN (see [Canonical input bucket](#canonical-input-bucket)). |
+| `jobMemory`, `taskMemory` | Enriched and forwarded; see executor payload. |
+| `modelConfig` | Forwarded to ai-skills; composed with `llmCall` on MAIN (see DirectExecutionStrategy). |
+| `llmCall` | MAIN skill overlay + trace semantics; stripped before `runSkill`, merged into `modelConfig`. |
+| `timeoutMs` | Forwarded when set (also overlaid from `llmCall.timeoutMs`). |
+| `coreSkillId` | Maps to `skillId` on `RunSkillRequest` for gateway. |
+| `graphId`, `nodeId`, `prevNodeId`, `masterSkillId`, `masterSkillActivityId` | Graph / activity telemetry (read in task-sdk & tracing). |
+| `jobId`, `taskId` | Assigned UUIDs when omitted before gateway. |
+| `identity` | Opaque envelope; enriched with task/skill ids. |
+| `executionMode` | `"default"` \| `"trace"` — trace enables debug trace collection and forwards trace flags downstream. |
+| `jobContext` | Merged into template variables only (stripped from top-level executor payload in `_executeDirect`). |
+| `includeContextInPrompt` | Context markdown generation for MAIN (and required for synthesis PRE unless `autoEnableContext`). |
+| `executionPipeline` | Multi-step PRE / MAIN / POST orchestration. |
+| `narrixMode` | Narrix invocation mode (catalog key); inferred from `narrix` / `narrixInput` when omitted (see `resolveRunTaskRuntimeKnobs`). |
+| `inputStrategyKey` | Input-strategy catalog key (authoring / UX); does **not** select `narrixMode`. |
+| `executionMemory` | Canonical execution blob; merged into `jobMemory.execution`. |
+| `narrix` | Task-level NARRIX pre-processor; mutates `executionMemory` / `jobMemory`. May include web scoping fields such as **`enableWebScope`**, **`webScopeTemplates`**, **`webScopeQuestionTemplate`**, **`webScopeObjects`**, **`webScopeQuestions`** (`Array<{ id?: string; question: string; source?: "manual" \| "ai-driven" }>` when using explicit question-pack mode — see [documenations/web-scoping-in-ai-tasks.md](documenations/web-scoping-in-ai-tasks.md)). |
+| `narrixInput`, `narrixScope` | Structured Narrix **handler** input (`$path` allowed); scope filters into `taskMemory.narrix`. |
+| `aiScoping`, `aiScopingOptions` | PRE MAIN scoped memory → `input.aiScoped`. |
+| `taskKind`, `outputValidation`, `autoValidateDecisionOutput` | Decision/utility/content semantics and **`parsed` validation inside `runTask` only** — **not** forwarded on `RunSkillRequest`; **`@exellix/ai-skills` does not read or validate these fields** (see [.docs/investigation/ai-skills.md](.docs/investigation/ai-skills.md)). |
+| `templateTokens`, `templateRenderOptions` | Inherited from `RunSkillRequest` (@exellix/ai-skills): gateway template overlay / render options per invoke. |
+
+### Invalid on `RunTaskRequest` (v7)
+
+These are **not** part of the typed request or closed schema: root `question`, top-level `inputs`, `jobInput`, `executionType`. Compile them away in the graph/runtime layer.
+
+## `executionStrategies` (FuncX wrappers around MAIN)
+
+- **`planner`:** runs **once** per entry (in global `priority` order among `before` rows) **before** the first MAIN attempt. Invokes FuncX function id **`execution/plan`** via **`run()`** from **`@x12i/funcx/functions`** with the **generic envelope** (`goal`, `input`, `context`, `args`, `attribution`). Override with `args.functionId` only when the target function accepts that **same** envelope. Responses are normalized with **`getRunJsonResult`** from **`@x12i/funcx/functions`** (≥3.8.2; also re-exported from `@exellix/ai-tasks`). `@exellix/ai-tasks` maps the JSON into gateway merge fields (`instructions` / `prompt` / `variables` / `templateTokens`); see [`genericExecutionFuncxEnvelope.ts`](src/execution-strategies/genericExecutionFuncxEnvelope.ts).
+- **`optimizer`:** runs **after** each MAIN attempt. The **first** `optimizer` row after sort drives the retry loop: FuncX **`execution/evaluate-result`** (same `run()` / generic envelope pattern; **`result`** carries the MAIN output summary). The package maps responses into `{ satisfied, feedback?, variables?, templateTokens? }` for merge; `suggestedChanges` / `issues` from FuncX are folded into **`feedback`** / **`variables.optimizerSuggestedChanges`**. If not satisfied, MAIN runs again with feedback in `variables` / `executionMemory` until **`maxIterations`** MAIN attempts (per-invocation `maxIterations`, else env `AI_TASKS_OPTIMIZER_MAX_ITERATIONS`, else default **3**). Additional optimizer rows are reserved (warning when `AI_TASKS_REQUEST_WARNINGS=1`).
+- Catalox catalogs **`ai-task-main-execution-wrappers`** (preferred) and **`ai-task-execution-strategies`** (same seeded rows) list **`direct`** (plain MAIN, `[]`), **`planner`**, **`optimizer`** for authoring metadata.
+- **FuncX FR specs** (stable **`functionId`** values, JSON input/output envelopes, behavior, **`ask()` correlation**): [`documenations/funcx-scoping-integration-gaps.md`](documenations/funcx-scoping-integration-gaps.md) §**6**.
+
+### Executor passthrough
+
+- Only keys listed in `RunTaskRequest` / the schema are guaranteed; extra keys are **not** part of the contract.
+- **`job.input`** as a distinct concept is **not** a first-class field — use `jobMemory` / `jobContext` / `input`.
+
+---
+
+## Xynthesis vs MAIN skill
+
+| Path | Xynthesis involvement |
+|------|------------------------|
+| PRE **`synthesized-context`** | Uses xynthesis `executeXynthesisAction` / structured gateway helpers. |
+| POST **audit** / **polish** | Uses xynthesis `executeXynthesisAction` via post-step LLM helpers. |
+| **aiScoping** | Internal scoping calls via xynthesis. |
+| **MAIN** gateway skill | Delegated to `@exellix/ai-skills` `runSkill` — may or may not use xynthesis inside the gateway depending on skill implementation. |
+| **Local tasks** | No gateway / no pipeline POST unless returning early — **no** xynthesis from MAIN path. |
+| **`runUtility`** | Separate entry (e.g. `xynthesis/finalize`). |
+
+**Why a run might show no “xynthesis actions”**
+
+1. **Local handler** short-circuits before enrichment/gateway.
+2. **MAIN-only** request with no PRE/POST pipeline and no ai-scoping — synthesis simply does not run in ai-tasks.
+3. **`executionMode` not `"trace"`** — fewer diagnostics / `debugTrace` surfaces even when xynthesis runs.
+4. **Pipeline steps ignored** — unsupported PRE/POST types or extra PRE synthesis steps after the first.
+
+---
+
+## Examples
+
+**Minimal valid**
+
+```json
+{
+  "skillKey": "skills/example",
+  "agentId": "my-agent",
+  "jobTypeId": "my-job-type",
+  "taskTypeId": "my-task-type",
+  "executionStrategies": [],
+  "input": { "question": "Hello?" }
+}
+```
+
+**Graph-shaped (correlation + memory)**
+
+```json
+{
+  "skillKey": "skills/example",
+  "agentId": "my-agent",
+  "jobTypeId": "my-job-type",
+  "taskTypeId": "my-task-type",
+  "executionStrategies": [],
+  "jobId": "…",
+  "taskId": "…",
+  "graphId": "g1",
+  "nodeId": "n1",
+  "input": { "assetId": "a1" },
+  "variables": { "orgName": "Acme", "locale": "en" },
+  "jobContext": { "tenantId": "t1" },
+  "jobMemory": {},
+  "taskMemory": {},
+  "executionMemory": {
+    "input": { "raw": {} },
+    "jobVariables": { "orgName": "Acme", "locale": "en" },
+    "taskVariables": { "tone": "concise" }
+  }
+}
+```
+
+---
+
+## Graph task node (authoring) → `RunTaskRequest` (invoke)
+
+Graph stores **`TaskNode`** model objects; `@exellix/ai-tasks` accepts only **`RunTaskRequest`**. Graph-engine compiles authoring into the wire shape; ai-tasks forwards fields **without** flattening **`jobVariables`** / **`taskVariables`** or merging **`input`** into **`variables`**.
+
+### Three “inputs” on a task node (do not confuse)
+
+| Name | On model | Compiled into |
+|------|----------|-----------------|
+| **`inputsConfig`** | Runtime payload bindings (`executionMemoryPath`, …) | **`RunTaskRequest.input`** (wires only) |
+| **`taskVariable`** | Prompts, literals, `{ "$path": "jobVariables.*" \| "taskVariables.*" }` | Merged into **`RunTaskRequest.input`** |
+| **`runtime.input`** / caller bag | Per-run MAIN payload | **`RunTaskRequest.input`** (+ mirrored `executionMemory.input`) |
+
+Deprecated on nodes: **`inputs`** (dual-read → **`inputsConfig`**). Not on request: top-level **`inputs`**.
+
+### Template variable scopes (two buckets)
+
+| Scope | Authored on | On `executionMemory` | `RunTaskRequest` |
+|-------|-------------|----------------------|------------------|
+| Job / graph (whole run) | `model.variables`, `runtime.variables`, `runtime.jobVariables` | **`jobVariables`** | **`variables`** (same bucket; forwarded as-is) |
+| Task / node (this step only) | `node.variables`, `runtime.taskVariables` | **`taskVariables`** | *(no top-level field yet — bucket only on `executionMemory`)* |
+
+Legacy path alias: **`variables.*`** ≡ **`jobVariables.*`** (prefer **`jobVariables.*`** in new graphs).
+
+### Node fields (authoring → request)
+
+| Node field | Role | On `RunTaskRequest`? |
+|------------|------|----------------------|
+| **`id`** | Stable node id | **Indirect:** **`nodeId`**, fresh **`taskId`** per invoke |
+| **`type`** | `task` \| `finalizer` | **No** — routing uses **`skillKey`** |
+| **`skillKey`** | Skill / local handler key | **Yes** — required; use **`node.skillKey`** only (not `metadata.skillKey`) |
+| **`taskKnowledge`** | Static knowledge refs | **No** — resolved into outbound **`taskMemory.knowledge`** by graph-engine |
+| **`inputsConfig`** | Execution-memory wires | **No** — compiled into **`input`** |
+| **`taskVariable`** | Dynamic task config / prompt | **No** — compiled into **`input`** |
+| **`variables`** | Node template overrides | **No** — mirrored to **`executionMemory.taskVariables`** |
+| **`inputs`** | Deprecated bindings name | **Do not author** — use **`inputsConfig`** |
+| **`metadata`** | Planning / readability only | **No** opaque passthrough — see forbidden table |
+| **`taskConfiguration`** | Execution-facing config | **Lifted** — see table below |
+| **`smartInput`** | Rendrix path list | **Yes** — **`smartInput`** (`paths`, optional **`strict`**) |
+| **`executionMapping`** | Post-run writes to execution memory | **No** — graph-engine after response |
+| **`jobContextMapping`** | Template variable seeds | **No** — compile to **`jobContext`** / **`jobVariables`** before invoke |
+| **`outputMapping`** | Finalizer / graph outputs | **No** — apply after response (finalizers only on finalizer type) |
+| **`scope`** | List-scoping declaration | **No** — compile to **`input`** / memory paths / **`narrixScope`** / **`aiScoping`** |
+| **`outputValidation`** | Local graph post-check (rules) | **No** on request — engine **`executeNode`** only |
+| **`conditions`** | Run gates | **No** — graph-engine |
+| **`memory`** | Rare per-node memory override | **No** — stays on model; engine applies to outbound memory copies |
+
+### Lifting `taskConfiguration` → `RunTaskRequest`
+
+| `node.taskConfiguration.*` | `RunTaskRequest` property |
+|------------------------------|---------------------------|
+| `taskTypeId` | **`taskTypeId`** |
+| `executionStrategies` | **`executionStrategies`** (required; use **`[]`** for plain MAIN) |
+| `executionStrategyCatalogItems` | **`executionStrategyCatalogItems`** |
+| `modelConfig` (+ `runtime.nodes[id].modelConfig`) | **`modelConfig`** (flat; aliases resolved by engine) |
+| `llmCall`, `timeoutMs` | same |
+| `narrix`, `narrixMode`, `narrixInput` | **`narrix`**, **`narrixMode`**, **`narrixInput`**, **`narrixScope`** |
+| `inputStrategyKey` | **`inputStrategyKey`** |
+| `aiTasksOutputValidation` | **`outputValidation`** (server-side in `runTask`) |
+| `executionPipeline` | **`executionPipeline`** |
+| `runTaskIdentity` | **`identity`** |
+| `taskKind`, `autoValidateDecisionOutput` | same |
+| `aiTaskProfile.webScoping` | **`narrix.webScoping`** (when preprocessor runs) |
+| `taskConfiguration.aiTaskProfile.inputSynthesis` | PRE **`synthesized-context`** — see compile table |
+| `taskConfiguration.aiTaskStrategies` | Forward on **`RunTaskRequest.taskConfiguration`** for ai-tasks compile (see below) |
+| `taskConfiguration.aiTaskProfile.preStrategyKey` / `postStrategyKey` | Engine utility `runTask` calls (not extra request fields) |
+
+### `inputSynthesis` → PRE pipeline (graph-engine compile)
+
+| `aiTaskProfile.inputSynthesis` | Effect |
+|--------------------------------|--------|
+| `enabled: true` | Insert PRE `{ phase: "pre", type: "synthesized-context" }`; set **`includeContextInPrompt: true`** |
+| `sources[]` | `SynthesisConfig.memoryPaths` |
+| `destination` + `outputKey` | `SynthesisConfig.xynthesizedOutput` |
+| Conflicts with explicit `executionPipeline` | Engine / compile rejects (`INPUT_SYNTHESIS_PIPELINE_CONFLICT`) |
+
+### `aiTaskStrategies` → PRE pipeline (ai-tasks compile at `runTask`)
+
+Graph-engine forwards the node blob on **`RunTaskRequest.taskConfiguration`** (stripped after compile). Alternatively call **`compileTaskConfigurationOnRunTaskRequest`** before invoke.
+
+| `taskConfiguration.aiTaskStrategies` | Effect |
+|--------------------------------------|--------|
+| `pre: "synthesis"` or `pre` array containing `"synthesis"` | Insert PRE `{ phase: "pre", type: "synthesized-context" }`; set **`includeContextInPrompt: true`** |
+| `preInputStrategy` | `SynthesisConfig.synthesisInputStrategy` (`policy`, `task-memory-only`, …) |
+| Conflicts with `inputSynthesis.enabled` + explicit PRE in `taskConfiguration.executionPipeline` | **`INPUT_SYNTHESIS_PIPELINE_CONFLICT`** |
+
+**Note:** `"synthesis"` on `pre` **enables** PRE; it is not an input-strategy catalog key. Post-audit strategy `"synthesis"` is unrelated.
+
+See [`reports/graph-engine-task-pre-synthesis-compile.md`](reports/graph-engine-task-pre-synthesis-compile.md) for the **graph-engine** work item (graph model, compile, runtime, CI).
+
+### Dual `outputValidation`
+
+| Authoring | Where it runs |
+|-----------|----------------|
+| **`node.outputValidation`** (rules) | Graph-engine **local** check before mappings — **not** forwarded to ai-tasks |
+| **`taskConfiguration.aiTasksOutputValidation`** | **`RunTaskRequest.outputValidation`** — validated inside **`runTask`** on **`response.parsed`** |
+
+### Forbidden on `node.metadata` (execution config)
+
+| Wrong | Correct |
+|-------|---------|
+| `metadata.modelConfig` | `taskConfiguration.modelConfig` |
+| `metadata.narrix` | `taskConfiguration.narrix` |
+| `metadata.aiTaskProfile` | `taskConfiguration.aiTaskProfile` |
+| `metadata.executionStrategyKey` | `taskConfiguration.executionStrategies` |
+| `metadata.outputConstraints` | `taskConfiguration.aiTasksOutputValidation` |
+| `metadata.taskKnowledge` | `node.taskKnowledge` |
+| `metadata.skillKey` | `node.skillKey` |
+| `metadata.variables` | `node.variables` |
+
+### `smartInput.paths` (engine allowlist)
+
+`input.*`, `inputs.*`, **`jobVariables.*`**, **`taskVariables.*`**, `jobMemory.*`, `taskMemory.*`, `executionMemory.*`, `xynthesized.job|task|execution.*`. Legacy **`variables.*`** ≡ **`jobVariables.*`**.
+
+### Gaps (not on `RunTaskRequest`)
+
+1. **`jobContextMapping`** — evaluate → **`jobContext`** / **`executionMemory.jobVariables`** before invoke.
+2. **`executionMapping`** / **`outputMapping`** — apply after `runTask`.
+3. **`conditions`**, **`stepRetryPolicy`**, opaque **`metadata`** execution passthrough.
+4. Per-node **`taskVariables`** top-level field — use **`executionMemory.taskVariables`** until a future request field exists.
+
+Correlations and memories on invoke: **`agentId`**, **`jobTypeId`**, **`taskTypeId`** (required); **`jobId`**, **`taskId`**; **`graphId`**, **`nodeId`**, **`prevNodeId`**; **`jobMemory`**, **`taskMemory`**, **`executionMemory`**; **`variables`**, **`includeContextInPrompt`**, **`xynthesized`**, **`smartInput`**, **`templateTokens`**, **`templateRenderOptions`**, and other **`RunSkillRequest`** fields forwarded by **`@exellix/ai-skills`**.
+
+---
+
+## Orchestrator integration (graph-engine and hosts)
+
+This package **does not declare** a tested minimum **`@exellix/graph-engine`** (or other orchestrator) semver. **Consume the orchestrator’s own `package.json` / lockfile** line for **`@exellix/ai-tasks`**. Breaking **`RunTaskRequest`** / runtime validation changes are **`CHANGELOG.md`** / **`BREAKING-CHANGES.md`** (typically **major** bumps). A joint **“graph-engine X ↔ ai-tasks Y tested in CI”** matrix lives with the **orchestrator** when you add CI for it — not in this repo today.
+
+### Metadata passthrough into `RunTaskRequest`
+
+There is **no machine-generated allowlist** or parity CI in **`@exellix/ai-tasks`**. Hosts that whitelist fields (e.g. `extractRunTaskMetadataPassthrough`) must **update manually** when [`documenations/schemas/v1/run-task-request.json`](documenations/schemas/v1/run-task-request.json) gains keys, or adopt broader forwarding policy. Optional future: export schema top-level keys from a small script for downstream CI diffs.
+
+### `taskTypeId` vs `skillKey`
+
+**`@exellix/ai-skills`** requires **`taskTypeId`** as a **non-empty opaque string** independent of **`skillKey`** (routing uses **`skillKey`** only). Orchestrators may set root **`taskTypeId`** from authoring **`metadata.taskTypeId`** when non-empty, else default **`taskTypeId === skillKey`** — both are valid. **`@exellix/ai-tasks`** does not validate **`taskTypeId`** against a Catalox catalog.
+
+### `RunTaskResponse.xynthesizedPatch` and optimizer / retries
+
+- **`xynthesizedPatch`** is populated only from **PRE pipeline `synthesized-context`** steps that set **`xynthesizedOutput`** (see [`src/utils/xynthesizedWrite.ts`](src/utils/xynthesizedWrite.ts): **`replace`** vs **`merge`** on **`outputKey`**; **`mergeXynthesizedPatchSlices`** merges **`job` / `task` / `execution` buckets**).
+- **`RunTaskRequest.xynthesized`** and **`RunTaskResponse.xynthesizedPatch`** use the same shape: **`{ job?, task?, execution? }`**, each a **`Record<string, unknown>`** keyed by synthesis **`outputKey`** (or caller-supplied keys). **`SynthesisConfig.xynthesizedOutput.destination`** may be **`"job"`**, **`"task"`**, or **`"execution"`** — ai-tasks does **not** redirect execution scope into job or task buckets.
+- **`smartInput.paths`** entries under **`xynthesized.*`** must use scope **`job`**, **`task`**, or **`execution`** (validated in [`src/utils/xynthesizedSmartInputPaths.ts`](src/utils/xynthesizedSmartInputPaths.ts)); path resolution against live memory remains downstream (Rendrix / gateway).
+- The **optimizer** loop (**`executionStrategies`** `optimizer`) runs **multiple MAIN attempts inside one `runTask`** but **does not append** additional **`xynthesizedPatch`** slices — patches reflect **PRE writes for that invocation**, not per-MAIN-attempt deltas.
+- Each **new** **`runTask`** call from an orchestrator **starts fresh** (optimizer iteration counter resets) unless the host **replays** **`executionMemory`**, **`xynthesized`**, etc. Worst-case MAIN executions ≈ **orchestrator retry count × inner optimizer iterations**.
+
+### Narrix web scoping
+
+When **`narrix.enableWebScope === true`**, **`@exellix/ai-tasks`** runs **`@exellix/narrix-web-scoper`** after the Narrix preprocessor unless **`narrix.skipWebScopeWhenExternalWebMarkdownPresent`** is set and **`executionMemory.webContextMarkdown`** is already a non-empty string. There is **no cross-process URL dedupe**; avoiding double fetch is a **configuration** concern (see [documenations/web-scoping-in-ai-tasks.md](documenations/web-scoping-in-ai-tasks.md)).
+
+### Buffered run logs and Logxer correlation on **`metadata`**
+
+**`runTask()`** in this package **does not set** orchestrator-specific keys such as buffered **`runLog`** / **`exellixRunLog`** or **`logxerRunId`** / **`logxerCorrelationId`** on the response. If those appear on merged **`response.metadata`**, that is **consumer/orchestrator + logging stack** behavior — not part of **`RunSkillResponse`** types from **`@exellix/ai-skills`**. Stable schema / deprecation policy for those keys should be documented **next to the orchestrator** (and **`@x12i/logxer`** if viewers depend on them).
+
+### PRE/POST utility-style **`runTask`** calls
+
+**`runTask`** does **not** forbid **`executionStrategies`** or a richer **`executionPipeline`** for **`taskKind: "utility"`**; isolating utilities to **`executionStrategies: []`** and a single MAIN pipeline step is an **orchestrator policy**, not an **`@exellix/ai-tasks`** runtime restriction.
+
+### Scope vs **`aiScoping`** vs **`narrixScope`**
+
+| Mechanism | Role in **`@exellix/ai-tasks`** |
+|-----------|-----------------------------------|
+| **`narrixScope`** | Filters what lands in **`taskMemory.narrix`** after the structured Narrix handler. |
+| **`aiScoping`** | PRE-MAIN LLM calls → **`input.aiScoped[]`**. |
+| Authoring **`scope`** / in-memory lists | No dedicated request field — compile into **`input`**, **`variables`**, **`jobContext`**, or **`executionMemory`** (see [Graph task node](#graph-task-node-authoring--runtaskrequest-invoke)). |
+
+### Cross-package assignment tracker
+
+Remaining work owned by **other packages** (docs, CI, log contracts) is listed with **target dates** in [.docs/investigation/external-packages-assignments.md](.docs/investigation/external-packages-assignments.md).
+
+---
+
+## Cross-package coordination
+
+**Orchestrator minimum version:** not declared in **`@exellix/ai-tasks`** — follow the consuming app’s dependency range and [**Orchestrator integration**](#orchestrator-integration-graph-engine-and-hosts) above. [**external-packages-assignments.md**](.docs/investigation/external-packages-assignments.md) tracks follow-ups outside this repo.

package/dist/activix/activixClient.d.ts

@@ -0,0 +1,6 @@
+import { Activix } from "@x12i/activix";
+/** MongoDB collection name for task activity records (must match `getActivixClient` and `getTaskActivities`). */
+export declare function getActivixCollectionName(): string;
+export declare function isActivixEnabled(): boolean;
+export declare function getActivixClient(): Promise<Activix | null>;
+//# sourceMappingURL=activixClient.d.ts.map

package/dist/activix/activixClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activixClient.d.ts","sourceRoot":"","sources":["../../src/activix/activixClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAQxC,iHAAiH;AACjH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AA+BD,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CA+FhE"}

package/dist/activix/activixClient.js

@@ -0,0 +1,131 @@
+import { Activix } from "@x12i/activix";
+import { resolvePackageLogsLevel } from "@x12i/logxer";
+let _client = null;
+let _initPromise = null;
+/** MongoDB collection name for task activity records (must match `getActivixClient` and `getTaskActivities`). */
+export function getActivixCollectionName() {
+    return process.env.ACTIVIX_COLLECTION ?? "task-activities";
+}
+export function isActivixEnabled() {
+    return process.env.ACTIVIX_ENABLED === "true";
+}
+/** Maps injected logger methods to `@x12i/logxer` `LogLevel` ordering (verbose…error). */
+function shouldEmitActivixLog(method, packageLogsDisabled, threshold) {
+    if (packageLogsDisabled)
+        return method === "error";
+    const rank = {
+        debug: 1,
+        info: 2,
+        warn: 3,
+        error: 4,
+    };
+    // `@x12i/logxer` may expand `LogLevel` over time (e.g. "off"/"silent"/"none").
+    // If an unknown level appears, default to "warn" to avoid breaking Activix logging.
+    const thresholdRank = {
+        verbose: 0,
+        debug: 1,
+        info: 2,
+        warn: 3,
+        error: 4,
+        off: Number.POSITIVE_INFINITY,
+        silent: Number.POSITIVE_INFINITY,
+        none: Number.POSITIVE_INFINITY,
+    };
+    const resolvedThresholdRank = thresholdRank[String(threshold)] ?? thresholdRank.warn;
+    return rank[method] >= resolvedThresholdRank;
+}
+export async function getActivixClient() {
+    if (!isActivixEnabled())
+        return null;
+    if (_client) {
+        if (!_initPromise)
+            return _client;
+    }
+    const mongoUri = process.env.MONGO_URI ?? process.env.MONGO_LOGS_URI;
+    if (!mongoUri)
+        return null;
+    const staleRecordTTL = process.env.ACTIVIX_STALE_TTL_MS
+        ? parseInt(process.env.ACTIVIX_STALE_TTL_MS, 10)
+        : 300_000;
+    const collectionName = getActivixCollectionName();
+    // Indexes help queries that group by correlationId and/or phase.
+    const correlationIdIndex = {
+        keys: { correlationId: 1 },
+        options: { name: "byCorrelationId" },
+    };
+    const phaseIndex = {
+        keys: { phase: 1 },
+        options: { name: "byPhase" },
+    };
+    const correlationPhaseIndex = {
+        keys: { correlationId: 1, phase: 1 },
+        options: { name: "byCorrelationIdAndPhase" },
+    };
+    const collectionConfig = {
+        name: collectionName,
+        primaryKey: "recordId",
+        primaryKeyPrefix: "act-",
+        statusField: "status",
+        startTimeField: "startTime",
+        endTimeField: "endTime",
+        durationField: "duration",
+        statusValues: {
+            started: "started",
+            completed: "completed",
+            failed: "failed",
+            timeout: "timeout",
+        },
+        indexes: [correlationIdIndex, phaseIndex, correlationPhaseIndex],
+        cache: {
+            // Activix passes this to xronox-store; caching is helpful but not required.
+            maxSize: 1_000,
+            ttlMs: 60_000,
+        },
+    };
+    const { packageLogsDisabled, logLevel } = resolvePackageLogsLevel({ envPrefix: "ACTIVIX" });
+    const ax = new Activix({
+        mongoUri,
+        storageMode: "database",
+        collections: [collectionConfig],
+        defaultCollection: collectionName,
+        staleRecordTTL,
+        logger: {
+            debug: (msg, meta) => {
+                if (!shouldEmitActivixLog("debug", packageLogsDisabled, logLevel))
+                    return;
+                // eslint-disable-next-line no-console
+                console.debug(`[activix] ${msg}`, meta ?? "");
+            },
+            info: (msg, meta) => {
+                if (!shouldEmitActivixLog("info", packageLogsDisabled, logLevel))
+                    return;
+                // eslint-disable-next-line no-console
+                console.info(`[activix] ${msg}`, meta ?? "");
+            },
+            warn: (msg, meta) => {
+                if (!shouldEmitActivixLog("warn", packageLogsDisabled, logLevel))
+                    return;
+                // eslint-disable-next-line no-console
+                console.warn(`[activix] ${msg}`, meta ?? "");
+            },
+            error: (msg, meta) => {
+                if (!shouldEmitActivixLog("error", packageLogsDisabled, logLevel))
+                    return;
+                // eslint-disable-next-line no-console
+                console.error(`[activix] ${msg}`, meta ?? "");
+            },
+        },
+    });
+    _client = ax;
+    if (!_initPromise) {
+        _initPromise = _client.init().catch(() => {
+            // Non-fatal: if init fails, we still allow call sites to ignore by receiving `null`.
+            // We keep the init promise cleared so future calls can try again.
+            _initPromise = null;
+            return;
+        });
+    }
+    await _initPromise;
+    return _client;
+}
+//# sourceMappingURL=activixClient.js.map

package/dist/activix/activixClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activixClient.js","sourceRoot":"","sources":["../../src/activix/activixClient.ts"],"names":[],"mappings":"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"}

package/dist/activix/getTaskActivities.d.ts

@@ -0,0 +1,10 @@
+export type TaskActivityRecord = Record<string, unknown>;
+/**
+ * Retrieve Activix phase records for a single logical task run.
+ *
+ * Notes:
+ * - Requires `ACTIVIX_ENABLED=true` and Mongo configured (same as tracking).
+ * - `taskId` is the runtime task identifier and also the Activix `correlationId`.
+ */
+export declare function getTaskActivities(taskId: string): Promise<TaskActivityRecord[]>;
+//# sourceMappingURL=getTaskActivities.d.ts.map

package/dist/activix/getTaskActivities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getTaskActivities.d.ts","sourceRoot":"","sources":["../../src/activix/getTaskActivities.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAWrF"}

package/dist/activix/getTaskActivities.js

@@ -0,0 +1,17 @@
+import { getActivixClient, getActivixCollectionName } from "./activixClient.js";
+/**
+ * Retrieve Activix phase records for a single logical task run.
+ *
+ * Notes:
+ * - Requires `ACTIVIX_ENABLED=true` and Mongo configured (same as tracking).
+ * - `taskId` is the runtime task identifier and also the Activix `correlationId`.
+ */
+export async function getTaskActivities(taskId) {
+    const ax = await getActivixClient().catch(() => null);
+    if (!ax)
+        return [];
+    // See docs/activix.md — records are grouped by correlationId.
+    const records = await ax.findRecords({ correlationId: taskId }, { collection: getActivixCollectionName(), sort: { startTime: 1 } });
+    return Array.isArray(records) ? records : [];
+}
+//# sourceMappingURL=getTaskActivities.js.map

package/dist/activix/getTaskActivities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getTaskActivities.js","sourceRoot":"","sources":["../../src/activix/getTaskActivities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAIhF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAc;IACpD,MAAM,EAAE,GAAG,MAAM,gBAAgB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IAEnB,8DAA8D;IAC9D,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,WAAW,CAClC,EAAE,aAAa,EAAE,MAAM,EAAE,EACzB,EAAE,UAAU,EAAE,wBAAwB,EAAE,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,CACnE,CAAC;IAEF,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,OAAgC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzE,CAAC"}

package/dist/activix/phaseTracking.d.ts

@@ -0,0 +1,17 @@
+import type { Activix } from "@x12i/activix";
+export type ActivixPhase = "local" | "narrix" | "narrix_then_direct" | "pipeline_pre" | "direct" | "audit" | "polish";
+export declare function createPhaseMeta(args: {
+    correlationId: string;
+    phase: ActivixPhase;
+    [k: string]: unknown;
+}): Record<string, unknown>;
+export declare function withPhaseRecord<T>(args: {
+    ax: Activix | null;
+    correlationId: string | undefined;
+    phase: ActivixPhase;
+    meta?: Record<string, unknown>;
+    onSuccessUpdates?: (result: T) => Record<string, unknown> | undefined;
+    onErrorUpdates?: (error: unknown) => Record<string, unknown> | undefined;
+    fn: () => Promise<T>;
+}): Promise<T>;
+//# sourceMappingURL=phaseTracking.d.ts.map

package/dist/activix/phaseTracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phaseTracking.d.ts","sourceRoot":"","sources":["../../src/activix/phaseTracking.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,QAAQ,GACR,oBAAoB,GACpB,cAAc,GACd,QAAQ,GACR,OAAO,GACP,QAAQ,CAAC;AAEb,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG1B;AAwCD,wBAAsB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE;IAC7C,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IACnB,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACzE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CACtB,GAAG,OAAO,CAAC,CAAC,CAAC,CA+Db"}