@exellix/ai-tasks 7.8.0

package/.env.example

@@ -0,0 +1,3 @@
+# ============================================
+# nx-mongo Configuration
+# ============================================

package/.metadata/instructions-builders/create-expected-output-instructions.md

@@ -0,0 +1,195 @@
+## How to add “Output Expected” to an instruction (Flex-MD **Request** spec)
+
+These are instructions for generating a **request-side output contract** (what your system appends to the prompt). The model only needs to know **Markdown**.
+
+### 1) Always append an explicit Output Format block
+
+When you want predictable structure, append this at the **end** of the instruction:
+
+* `## Output Format (Markdown only)`
+
+This block is the **request frame**.
+
+---
+
+### 2) Declare the required sections as headings (order never matters)
+
+List the headings the model must include. State explicitly that order is irrelevant.
+
+**Pattern:**
+
+```md
+## Output Format (Markdown only)
+Return ONLY Markdown with these section headings (order does not matter):
+- {{Heading1}}
+- {{Heading2}}
+- ...
+```
+
+**Notes**
+
+* Use the **exact heading names** you expect to parse.
+* Do not require heading levels (`##` vs `###`) — any heading level is acceptable.
+
+---
+
+### 3) Attach structure requirements inline (list / table)
+
+If a section has a required structure, annotate it inline (still plain Markdown text):
+
+* `(ordered list)`
+* `(list)`
+* `(table: col1, col2, col3)`
+* `(ordered table: col1, col2, col3)` ← ordered table means: add a `#` column + row numbering
+
+**Example:**
+
+```md
+- Reasoning (ordered list)
+- Assumptions (list)
+- Evidence (table: source, claim, confidence)
+- Steps (ordered table: stepName, owner)
+```
+
+**Rules**
+
+* Lists: unordered uses `-`, ordered uses `1.`
+* Tables: Markdown pipe tables
+* Ordered tables: first column must be `#` and rows numbered `1..N`
+
+---
+
+### 4) (NEW) Add value constraints when needed (enum / range / types)
+
+When you need precise values (enums, ranges, datatypes), specify **value constraints** inline after the section name.
+
+Use compact tokens (Markdown text, not JSON):
+
+* Enum: `{a|b|c}`
+* Numeric range: `[min..max]` (example `[0..100]`)
+* Types: `text`, `int`, `num`, `bool`, `date` (ISO `YYYY-MM-DD`)
+* Optional: `?`
+* List values: `list<...>` (example `list<text>`)
+
+**Examples:**
+
+```md
+- Decision ({approve|reject|defer})
+- Score (int [0..100])
+- Tags (list<text>)
+- Due date (date?)
+```
+
+**Important**
+
+* Constraints belong in the **request**.
+* The **response** should output the actual value (e.g., `87`) and does not need to repeat the tokens.
+
+---
+
+### 5) Add the “None” rule (recommended)
+
+If you require sections, make emptiness deterministic:
+
+```md
+If a section is empty, write `None`.
+```
+
+---
+
+### 6) (Optional) Add a single-container rule for high reliability (L2+)
+
+If you need stricter capture/parsing, require one fenced Markdown block:
+
+````md
+Return your entire answer inside a single ```markdown fenced block and nothing else.
+````
+
+---
+
+## Request templates you can copy (levels)
+
+### Minimal (L0)
+
+```md
+## Output Format
+Reply in Markdown.
+```
+
+### Standard (L1)
+
+```md
+## Output Format (Markdown only)
+Return ONLY Markdown with these section headings (order does not matter):
+- Short answer
+- Long answer
+- Reasoning (ordered list)
+- Assumptions (list)
+- Unknowns (list)
+
+If a section is empty, write `None`.
+```
+
+### Standard + constraints (L1, with enum/range/types)
+
+```md
+## Output Format (Markdown only)
+Return ONLY Markdown with these section headings (order does not matter):
+- Decision ({approve|reject|defer})
+- Score (int [0..100])
+- Rationale (ordered list)
+- Risks (list)
+
+If a section is empty, write `None`.
+```
+
+### Strict (L2)
+
+````md
+## Output Format (Markdown only)
+Return your entire answer inside a single ```markdown fenced block and nothing else.
+
+Inside the block, include these section headings (order does not matter):
+- Short answer
+- Long answer
+- Reasoning (ordered list)
+- Assumptions (list)
+- Unknowns (list)
+
+If a section is empty, write `None`.
+````
+
+### Max strict (L3)
+
+````md
+## Output Format (Markdown only)
+Return your entire answer inside a single ```markdown fenced block and nothing else.
+
+Include these section headings (order does not matter):
+- Short answer
+- Long answer
+- Reasoning (ordered list)
+- Assumptions (list)
+- Unknowns (list)
+
+If a section is empty, write `None`.
+
+Formatting rules:
+- Ordered lists use `1.`, `2.`, …
+- Unordered lists use `-` bullets.
+- Tables use Markdown pipe tables.
+- Ordered tables include a first column named `#` with row numbers 1..N.
+Do not return JSON as the response format.
+````
+
+---
+
+## One-liner rule for your request-builder (tax-aware)
+
+When generating the Output Format block, include only what is used:
+
+* If no tables are requested → don’t mention tables.
+* If no ordered lists are requested → don’t mention numbering rules.
+* If no value constraints are requested → don’t mention enums/ranges/types.
+* If level is L0 → don’t list headings at all.
+* If level is L2+ → add the single fenced block rule.

package/.metadata/readme.md

@@ -0,0 +1,48 @@
+# nx-content — Content Folder
+
+This folder is managed by **nx-content**, the Content Manager.
+
+## How it works
+
+- Place instruction files, prompt files, and content blocks in this folder.
+- **Keys** are file paths relative to this folder, without extension.  
+  Example: `skills/professional-answer.instructions` → file `skills/professional-answer.instructions.md`
+- The Content Manager resolves keys to file content. It does **not** render templates or substitute variables — that is ai-parser's job.
+
+## Extension rules
+
+- No extension in key → tries `.md` first, then `.json`.
+- Key with extension → used as-is.
+
+## Block includes
+
+In your files, use `<< path >>` (double angle brackets) to include another file's content inline:
+
+```
+<< blocks/greeting >>
+```
+
+The Content Manager replaces `<< path >>` with that file's raw content. Use `/` or `\\` as separator — both work.
+
+## Folder structure (recommended)
+
+```
+.content/
+  skills/
+    professional-answer.instructions.md
+    summarize-task.instructions.md
+  prompts/
+    default.md
+  blocks/
+    greeting.md
+    disclaimer.md
+```
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `CONTENT_REGISTRY_LOCAL_ROOT` | Path to this folder (default: `<cwd>/.content`) |
+| `CONTENT_REGISTRY_MODE` | `dev` (local wins) or `prod` (git wins). Default: `dev` |
+| `GITHUB_REPO_URL` | Git repo URL (optional) |
+| `GITHUB_TOKEN` | GitHub PAT for HTTPS git access (optional) |

package/.metadata/shared/audit.md

@@ -0,0 +1,29 @@
+# Shared Audit Instruction
+
+You are an objective quality auditor. Evaluate an LLM's response against the original objective and any provided context/policies. Be strict, concrete, and concise.
+
+## Evaluation Criteria
+- **Alignment**: Does the response directly address the original objective?
+- **Accuracy**: Does the response avoid hallucinations and maintain factual correctness?
+- **Format Compliance**: Does the response follow the required Markdown audit frame (sections listed below)?
+- **Quality**: Is the tone appropriate and the content professionally high-grade?
+
+## Output Format (Markdown only)
+Return ONLY Markdown with these section headings (order does not matter):
+
+## Decision
+- Either: `passed` or `failed`
+
+## Score
+- A number from 0 to 100
+
+## The Good
+- Bullet list of what was done well
+
+## The Bad
+- Bullet list of what was missing / incorrect / could be improved
+
+## Takeaways
+- Bullet list of actionable improvements
+
+If a section has nothing to say, write `None`.

package/.metadata/skills/professional-answer

@@ -0,0 +1,32 @@
+# Professional Answer Instruction
+
+You are an expert professional advisor. Provide a comprehensive, accurate, evidence-based answer to the user's inquiry.
+
+## Constraints
+- Base your answer on the provided context and facts.
+- Explicitly state any assumptions you make.
+- Clearly identify any unknowns or information gaps.
+- Maintain a professional and objective tone.
+
+## Output Format
+You MUST respond with EXACTLY this markdown structure, no extra text before or after:
+
+### Short Answer
+[Your 1-2 sentence summary here]
+
+### Full Answer
+[Your detailed explanation here]
+
+### Assumptions
+- [Assumption 1]
+- [Assumption 2]
+
+### Unknowns
+- [Unknown 1]
+- [Unknown 2]
+
+### Evidence
+1. [Evidence point 1]
+2. [Evidence point 2]
+
+IMPORTANT: Do not add any introductory text, conclusions, or formatting outside these exact section headings.

package/.metadata/skills/professional-answer.compressed.md

@@ -0,0 +1,11 @@
+Reply as an expert professional advisor. Use only the given context/facts.
+
+Output Markdown ONLY with these headings (order doesn’t matter):
+- Short answer (1–2 sentences)
+- Full answer
+- Assumptions (list)
+- Unknowns (list)
+- Evidence (ordered list)
+
+Lists: unordered uses `-`, ordered uses `1.`.
+If a section is empty, write `None`.

package/.metadata/skills/professional-answer.instructions

@@ -0,0 +1,33 @@
+# Professional Answer Instruction
+<!-- template-cores: {{core:question}} {{core:analysis}} -->
+
+You are an expert professional advisor. Provide a comprehensive, accurate, evidence-based answer to the user's inquiry.
+
+## Constraints
+- Base your answer on the provided context and facts.
+- Explicitly state any assumptions you make.
+- Clearly identify any unknowns or information gaps.
+- Maintain a professional and objective tone.
+
+## Output Format
+You MUST respond with EXACTLY this markdown structure, no extra text before or after:
+
+### Short Answer
+[Your 1-2 sentence summary here]
+
+### Full Answer
+[Your detailed explanation here]
+
+### Assumptions
+- [Assumption 1]
+- [Assumption 2]
+
+### Unknowns
+- [Unknown 1]
+- [Unknown 2]
+
+### Evidence
+1. [Evidence point 1]
+2. [Evidence point 2]
+
+IMPORTANT: Do not add any introductory text, conclusions, or formatting outside these exact section headings.

package/.metadata/skills/professional-answer.instructions.md

@@ -0,0 +1,33 @@
+# Professional Answer Instruction
+<!-- template-cores: {{core:question}} {{core:analysis}} -->
+
+You are an expert professional advisor. Provide a comprehensive, accurate, evidence-based answer to the user's inquiry.
+
+## Constraints
+- Base your answer on the provided context and facts.
+- Explicitly state any assumptions you make.
+- Clearly identify any unknowns or information gaps.
+- Maintain a professional and objective tone.
+
+## Output Format
+You MUST respond with EXACTLY this markdown structure, no extra text before or after:
+
+### Short Answer
+[Your 1-2 sentence summary here]
+
+### Full Answer
+[Your detailed explanation here]
+
+### Assumptions
+- [Assumption 1]
+- [Assumption 2]
+
+### Unknowns
+- [Unknown 1]
+- [Unknown 2]
+
+### Evidence
+1. [Evidence point 1]
+2. [Evidence point 2]
+
+IMPORTANT: Do not add any introductory text, conclusions, or formatting outside these exact section headings.

package/.metadata/skills/professional-answer.l2.md

@@ -0,0 +1,28 @@
+# Professional Answer Instruction
+
+You are an expert professional advisor. Provide a comprehensive, accurate, evidence-based answer to the user's inquiry.
+
+## Constraints
+- Base your answer on the provided context and facts.
+- Explicitly state any assumptions you make.
+- Clearly identify any unknowns or information gaps.
+- Maintain a professional and objective tone.
+
+## Output Format (Markdown only)
+Return your entire answer inside a single ```markdown fenced block and nothing else.
+
+Inside the block, include these section headings (order does not matter):
+- Short answer
+- Full answer
+- Assumptions (list)
+- Unknowns (list)
+- Evidence (ordered list)
+
+Section rules:
+- **Short answer**: 1–2 sentences.
+- **Full answer**: detailed explanation in paragraphs (and bullets if helpful).
+- **Assumptions**: `-` bullet list.
+- **Unknowns**: `-` bullet list.
+- **Evidence**: numbered list (`1.`, `2.`, …) of the key supporting facts/reasoning.
+
+If a section is empty, write `None`

package/.metadata/skills/professional-answer.md

@@ -0,0 +1,32 @@
+# Professional Answer Instruction
+
+You are an expert professional advisor. Provide a comprehensive, accurate, evidence-based answer to the user's inquiry.
+
+## Constraints
+- Base your answer on the provided context and facts.
+- Explicitly state any assumptions you make.
+- Clearly identify any unknowns or information gaps.
+- Maintain a professional and objective tone.
+
+## Output Format
+You MUST respond with EXACTLY this markdown structure, no extra text before or after:
+
+### Short Answer
+[Your 1-2 sentence summary here]
+
+### Full Answer
+[Your detailed explanation here]
+
+### Assumptions
+- [Assumption 1]
+- [Assumption 2]
+
+### Unknowns
+- [Unknown 1]
+- [Unknown 2]
+
+### Evidence
+1. [Evidence point 1]
+2. [Evidence point 2]
+
+IMPORTANT: Do not add any introductory text, conclusions, or formatting outside these exact section headings.

package/.metadata/skills/professional-answer.prompt

@@ -0,0 +1 @@
+{{input}}

package/.metadata/skills/professional-answer.prompt.md

@@ -0,0 +1 @@
+{{input}}

package/.metadata/skills/professional-decision.md

@@ -0,0 +1,26 @@
+# Professional Decision Instruction
+
+You are a senior strategic decision-maker. Your role is to evaluate situations and provide clear, well-reasoned decisions.
+
+## Constraints
+- Evaluate all factors provided in the input.
+- Consider specific risks and constraints mentioned.
+- Provide a clear decision based on the priorities.
+- Maintain a balanced and authoritative tone.
+
+## Output Format
+You MUST respond with EXACTLY this markdown structure, no extra text before or after:
+
+### Decision
+[Your final decision or recommendation]
+
+### Score
+[Number from 0-100]
+
+### Rationale
+[Your detailed reasoning]
+
+### Risks
+[Potential risks and drawbacks]
+
+IMPORTANT: Do not add any introductory text, conclusions, or formatting outside these exact section headings.

package/BREAKING-CHANGES.md

@@ -0,0 +1,43 @@
+# Breaking changes (`@exellix/ai-tasks`)
+
+## Unreleased (synced runtime model)
+
+### `@exellix/xynthesis` ≥ 3.6: `runSynthesisCall` removed
+
+- Requires **`@exellix/xynthesis` ≥ 3.6.4** (see `package.json`).
+- **`runSynthesisCall`** and **`RunSynthesisCallOpts`** are **removed** upstream. Use **`executeXynthesisAction`** with **`ExecuteXynthesisActionRequest`** (`gateway`, `prompts`, `workScope`, plus optional `model`, `maxTokens`, `timeoutMs`, …).
+- **`@exellix/ai-tasks`** no longer re-exports a `runSynthesisCall` alias. Public exports: **`executeXynthesisAction`**, **`setSynthesisInvoker`**, **`getSynthesisInvoker`**, plus type **`ExecuteXynthesisActionRequest`** (result type: import from **`@exellix/xynthesis`** or **`@exellix/xynthesis/ai-actions`**).
+- Post-step LLM helpers (`runPostStepLlmCall`, audit, polish, scoping) call **`executeXynthesisAction`** internally. Tests still mock via **`setSynthesisInvoker`**.
+
+### Required `executionStrategies`; removed `executionStrategyKey`
+
+- **`RunTaskRequest.executionStrategies`** is **required**: an array of `{ strategyKey: "planner" \| "optimizer", phase: "before" \| "after", priority: number, maxIterations?, args? }`. Use **`[]`** for plain MAIN (same behavior as the former default `executionStrategyKey: "direct"`).
+- **`executionStrategyKey`** has been **removed** from types, schema, and metadata. **`response.metadata.executionStrategiesSummary`** replaces it (before/after key lists and optional `primaryOptimizerMaxIterations`).
+- Default FuncX function ids for planner/optimizer (**generic envelope**, **`run()`** from `@x12i/funcx/functions`): **`execution/plan`**, **`execution/evaluate-result`**. Use **`@x12i/funcx` ≥ 3.8.2** so **`getRunJsonResult`** matches planner/optimizer unwrap behavior (normalization fixes landed in **3.8.2**). Export constants: **`FUNCX_EXECUTION_PLAN_FUNCTION_ID`**, **`FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`**. Override via each invocation’s `args.functionId` only when the target accepts the **same** envelope (`goal`, `input`, `context`, `result?`, `args`, `attribution`).
+
+### `runTask` ordering: Narrix before pipeline PRE
+
+- **Structured Narrix** (`narrixInput` with legacy `executionType: "narrix-then-direct"`, or explicit `narrixMode: "handler"`) now runs **before** `executionPipeline` PRE steps and **before** the local-task short-circuit, so PRE synthesis sees `taskMemory.narrix` / enriched memory the same way as the Narrix preprocessor path.
+- Previously, `narrix-then-direct` ran **after** the pipeline when both were set, so Narrix could be skipped for PRE. That combination is fixed.
+
+### `narrixMode` and resolver errors
+
+- New field **`narrixMode`**: `off` \| `preprocessor` \| `handler`. When both `request.narrix` and `narrixInput` are set, you **must** set `narrixMode` explicitly or `resolveRunTaskRuntimeKnobs` throws.
+- **`narrixMode: "off"`** strictly disables all Narrix invocation (ignores `request.narrix` / `narrixInput` for running Narrix).
+
+### Pipeline PRE step types
+
+- Unknown **`phase: "pre"`** step types now **throw** at execution time. Only **`synthesized-context`** is supported for PRE (Xynthesis pre-actions).
+
+### Default `contextSourcePolicy: "auto"` (PRE synthesis material)
+
+- **`auto`** now always resolves to the full combined layout (**`narrix-web-memory`** semantics): memory JSON plus optional Narrix and web markdown sections, so PRE does not silently narrow to **`memory-web`** when web is present but Narrix is absent. Explicit `memory-web` / `memory-only` still behave as before.
+
+### Catalox snapshot shape
+
+- **`getAiTasksTaskStrategiesCatalogSnapshot`** now includes **`input`**, **`execution`**, **`narrixModes`** list results and their catalog id fields (`inputCatalogId`, `executionCatalogId`, `narrixModesCatalogId`).
+- **`mainExecutionWrappers`** and **`mainExecutionWrappersCatalogId`** (`ai-task-main-execution-wrappers`): same canonical rows as **`execution`**; use for FuncX-focused UI without dropping the legacy **`ai-task-execution-strategies`** catalog.
+
+### Observability digest
+
+- **`extractAiTasksObservabilityFromRunTaskResponse`** surfaces **`narrixMode`**, **`inputStrategyKey`**, and **`executionStrategiesSummary`** from `response.metadata` when present (populated by `runTask` on pipeline/direct paths that call `attachExecutionStateAndObservability` with resolved knobs). **`executionStrategyKey`** is no longer used.