@exellix/ai-tasks 7.8.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to `@exellix/ai-tasks` are documented here.
+
+The published **npm version** always matches **`version`** in [`package.json`](package.json). If this file skips a semver, treat [`BREAKING-CHANGES.md`](BREAKING-CHANGES.md) and [`RUNTASK_REQUEST.md`](RUNTASK_REQUEST.md) as the source of truth for cross-version upgrades.
+
+## [7.7.1] - 2026-05-25
+
+### Added
+
+- **`RunTaskRequest.taskConfiguration`:** Graph-engine may forward the node `taskConfiguration` blob; **`compileTaskConfigurationOnRunTaskRequest`** (also at **`runTask()`** entry) maps **`aiTaskStrategies.pre: "synthesis"`** and **`aiTaskProfile.inputSynthesis.enabled`** into PRE **`synthesized-context`** + **`includeContextInPrompt: true`**. Exports **`TaskConfigurationCompileError`**, **`AI_TASK_PRE_ENABLE_SYNTHESIS`**.
+
+### Documentation
+
+- **`RUNTASK_REQUEST.md`**, **README**, [`.docs/flow-io/xynthesis-pre.md`](.docs/flow-io/xynthesis-pre.md), graph-engine task [`reports/graph-engine-task-pre-synthesis-compile.md`](reports/graph-engine-task-pre-synthesis-compile.md).
+- Fixtures: [`test/fixtures/run-task/graph-engine-pre-synthesis.json`](test/fixtures/run-task/graph-engine-pre-synthesis.json), [`test/fixtures/graphs/graph-qcrbz6t-pre-synthesis.json`](test/fixtures/graphs/graph-qcrbz6t-pre-synthesis.json).
+
+## [7.6.4] - 2026-05-18
+
+### Changed
+
+- **`@exellix/ai-skills` ≥ 5.5.0:** Dependency **5.5.2**; `pickRunSkillRequestFields` forwards top-level **`executionMemory`** on `runSkill` (native `buildWorkingMemory` support). Removed the 7.6.3 `jobMemory.executionMemory` nest bridge.
+
+### Dependencies
+
+- **`@exellix/ai-skills`:** `5.5.2` (was `5.4.0`).
+
+## [7.6.3] - 2026-05-18
+
+### Fixed
+
+- **Gateway `executionMemory` paths (interim):** `DirectExecutionStrategy` nested `request.executionMemory` on `jobMemory.executionMemory` before `runSkill` for ai-skills **< 5.5.0**. Superseded in **7.6.4** by native top-level forward. Strips `RunTaskRequest`-only fields from the `runSkill` payload.
+
+### Documentation
+
+- **Change request:** [`reports/change-request-tasknode-variable-scopes-7.6.2.md`](reports/change-request-tasknode-variable-scopes-7.6.2.md) — upstream work for `@exellix/ai-skills`, `@x12i/rendrix`, and optional gateway path aliases.
+
+## [7.6.2] - 2026-05-18
+
+### Fixed
+
+- **`smartInput.strict`:** Accepted on `RunTaskRequest.smartInput` and forwarded through `normalizeSmartInputConfig` to the gateway path.
+
+### Changed
+
+- **MAIN template variables:** `runTask` forwards **`variables`** (job/graph bucket) **as-is** via `passthroughJobTemplateVariables` — no longer folds `jobContext`, `input`, `xynthesized`, or `smartInput` into `variables`. Node scope remains on **`executionMemory.taskVariables`**.
+
+### Documentation
+
+- **`RUNTASK_REQUEST.md`:** TaskNode authoring map (`taskConfiguration`, `inputsConfig`, `taskVariable`, two-bucket `jobVariables` / `taskVariables`), dual `outputValidation`, `inputSynthesis` compile table, forbidden metadata.
+- **README**, web-scoping doc, Narrix JSDoc: authoring path **`taskConfiguration.narrix`** (not `metadata.narrix`).
+
+### Schema
+
+- **`run-task-request.json`:** `executionStrategyCatalogItems`, `smartInputRenderOptions`, Rendrix path objects, `smartInput.strict`, variable-bucket descriptions.
+
+## [7.6.0] - 2026-05-18
+
+### Added
+
+- **`xynthesized.execution` scope:** `XynthesizedMemory.execution`, `XynthesizedDestinationScope` includes **`"execution"`**, PRE **`xynthesizedOutput.destination: "execution"`** writes and returns **`xynthesizedPatch.execution`** (same replace/merge semantics as job/task; no redirect to other buckets).
+- **Smart-input:** `xynthesized.*` paths must use scope **`job`**, **`task`**, or **`execution`**; **`resolveXynthesizedSmartInputPath`** helper for in-package resolution against request **`xynthesized`**.
+- **`TaskRequestBuilder.withXynthesizedExecution(key, value)`**.
+
+### Documentation
+
+- **`RUNTASK_REQUEST.md`**, **`documenations/synthesized-context-guide.md`**, and **`documenations/schemas/v1/run-task-request.json`** updated for the execution bucket.
+
+## [7.2.0] - 2026-05-06
+
+### Changed
+
+- **Breaking (exports):** Replaced **`AI_TASKS_FUNCX_*`** constants with **`FUNCX_EXECUTION_PLAN_FUNCTION_ID`** (`execution/plan`), **`FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`** (`execution/evaluate-result`), **`FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`** (`research/plan-questions`).
+- **Execution strategies:** Planner and optimizer call **`run(functionId, payload)`** with the **generic FuncX envelope** only (`goal`, `input`, `context`, `result?`, `args`, `attribution`). Responses are adapted via **`adaptExecutionPlanResult`** / **`adaptEvaluateResultResponse`** ([`genericExecutionFuncxEnvelope.ts`](src/execution-strategies/genericExecutionFuncxEnvelope.ts)).
+- **`runPlanWebScopeQuestions`:** Optional **`backend: "funcx"`** for **`research/plan-questions`**; **`setResearchPlanQuestionsFuncxInvoker`** for tests.
+- **`ExecutionType`:** Re-exported from **`@exellix/ai-tasks`** via local [`executionType.ts`](src/types/executionType.ts) (`DIRECT`) because **`@exellix/ai-skills`** no longer exports this symbol on supported versions.
+- **`@x12i/funcx` ≥ 3.8.2:** **`unwrapFuncxRunValue`** delegates to **`getRunJsonResult`** (use **3.8.2+** for current normalization behavior). Re-exports: **`getRunJsonResult`**, **`isHttpRunSuccessBody`**, **`genericExecutionEnvelopeJsonSchema`**, **`buildAskAttribution`**, type **`GenericExecutionEnvelope`**.
+
+## [7.1.2] - 2026-05-06
+
+### Added
+
+- **`narrix.webScopeQuestions`:** optional explicit web-scope questions on `RunTaskRequest.narrix`; when `webScopeTemplates` is unset, the NARRIX preprocessor runs `@exellix/narrix-web-scoper` **`scopeQuestionPack`** and stores a normalized `WebScoperResult` in `executionMemory.webContext`.
+- **`runPlanWebScopeQuestions`** (and **`parseAndValidatePlanWebScopeQuestionsOutput`**, **`buildPlanWebScopeQuestionsUserPrompt`**) for AI-driven web-scope planning; FuncX path uses **`research/plan-questions`** (see **Unreleased** / **`FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`**). FR tracker: **`documenations/funcx-scoping-integration-gaps.md`** §6.
+
+### Documentation
+
+- **`documenations/web-scoping-in-ai-tasks.md`**, **README**, **RUNTASK_REQUEST.md:** documented `webScopeQuestions` shape and precedence vs templates.
+
+## [7.1.1] - 2026-05-06
+
+### Added
+
+- **Package root type exports:** `XynthesizedMemory`, `SmartInputConfig`, `XynthesizedDestinationScope`, `XynthesizedOutputConfig`, `ExecutionStrategyInvocation`, `ExecutionStrategyPhase`, and `ExecutionStrategyWrapperKey` are re-exported from `@exellix/ai-tasks` alongside `RunTaskRequest`, so hosts can depend on stable names instead of `NonNullable<RunTaskRequest['xynthesized']>` or `RunTaskRequest['executionStrategies'][number]`.
+
+### Documentation
+
+- **CHANGELOG discipline:** Documented that `package.json` is authoritative for the shipped semver and pointed cross-version migration readers at `BREAKING-CHANGES.md` / `RUNTASK_REQUEST.md` when intermediate entries are missing.
+
+_Note: Releases **after 6.0.1** through **before 7.1.1** were not listed here chronologically; consult git history and `BREAKING-CHANGES.md` for that span._
+
+## [6.0.1] - 2026-05-05
+
+### Fixed
+
+- **Synthesis E2E gate:** `test/synthesis/e2e-synthesis-real.test.ts` no longer requires `LLM_MODEL_STRONG` / `LLM_MODEL_NORMAL`; it runs when **`RUN_SYNTHESIS_E2E=1`** and a recognized provider key is set (`OPEN_ROUTER_KEY`, `GROK_API_KEY`, etc.). Warns when a model env var is missing.
+
+### Documentation
+
+- **Xynthesis upstream work:** [`documenations/xynthesis-upstream-fixes-checklist.md`](documenations/xynthesis-upstream-fixes-checklist.md) (Activix `diagnostics.owner`, `jobId`/`taskId` hardening in `runSidekickGatewayCall`, tests to add in xynthesis).
+
+## [6.0.0] - 2026-05-04
+
+### Breaking
+
+- **`runTask` / `RunTaskRequest`:** `agentId`, `jobTypeId`, and `taskTypeId` are **required** again (aligned with `@exellix/ai-skills` `RunSkillRequest`). `runTask()` calls **`assertRequiredRunSkillCorrelation`** and throws if any value is missing or whitespace-only.
+- **`TaskRequestBuilder.build()`** throws unless those three fields were set (use **`withAiSkillsCorrelation`** or **`withAgentId` / `withJobTypeId` / `withTaskTypeId`**).
+- **`TaskConvenienceMethods.executeDirect`** now requires an **`options`** object including **`agentId`**, **`jobTypeId`**, and **`taskTypeId`** (third argument is no longer optional).
+- **`TaskConvenienceMethods.executeWithType`** now requires the **`options`** argument (same correlation fields as `RunTaskRequest`).
+
+### Added
+
+- Exported **`assertRequiredRunSkillCorrelation`** from the package root for hosts that validate payloads before calling `runTask`.
+
+## [5.7.1] - 2026-05-04
+
+### Fixed
+
+- **Types:** `RunTaskRequest` now **omits and re-declares** `agentId`, `jobTypeId`, and `taskTypeId` as **optional**, matching `runTask()` usage and latest `@exellix/ai-skills` `RunSkillRequest` where those fields are required. Callers can still pass them when the gateway requires them.
+
+## [5.7.0] - 2026-05-04
+
+### Added
+
+- **RunTask request contract documentation:** [`RUNTASK_REQUEST.md`](RUNTASK_REQUEST.md) — normative field list, template merge precedence, `executionMemory` vs `jobMemory.execution`, `executionPipeline` semantics, xynthesis visibility notes, and examples.
+- **JSON Schema fragment:** [`documenations/schemas/v1/run-task-request.json`](documenations/schemas/v1/run-task-request.json) and OpenAPI component `RunTaskRequestSubset` in [`documenations/schemas/openapi-3.1-components.yaml`](documenations/schemas/openapi-3.1-components.yaml).
+- **Request shape helpers** (exported from package root): `normalizeRunTaskRequest`, `collectRunTaskRequestWarnings`, `collectExecutionPipelineWarnings`, `isRunTaskRequestWarningsEnabled`.
+- **Env-gated diagnostics:** `AI_TASKS_REQUEST_WARNINGS=1` (also `true` / `yes`) logs structured JSON for deprecated duplicate fields, ignored pipeline steps, and observability hints at the start of each `runTask` call.
+
+### Changed
+
+- **Types:** `RunTaskRequest` documents deprecated mirrors: optional root `question`, `inputs`, and `jobInput` (typed for discoverability; removal deferred to a future major after hosts migrate).
+
+### Notes
+
+- **Additive / non-breaking:** Runtime merge behavior is unchanged; warnings are opt-in via env.
+- **Cross-package:** Minimum orchestrator (e.g. graph-engine) version is **not declared** in `@exellix/ai-tasks` — follow the consuming app’s pinned `@exellix/ai-tasks` range; see `RUNTASK_REQUEST.md` § Orchestrator integration.