@exellix/ai-tasks 8.4.2 → 8.4.3

package/.docs/code-used-before/run-task.txt

@@ -0,0 +1,39 @@
+taken from client.ts 
+
+
+ 
+ /**
+     * Executes a task with a specific execution strategy.
+     *
+     * WHY: Allows for more complex execution logic (e.g. multi-step,
+     * tool-calling, direct pass-through) while maintaining a consistent API.
+     * Now includes two-step context enrichment: memory scoping + context generation.
+     */
+    async runTask<TParsed = any>(input: RunTaskRequest): Promise<RunSkillResponse<TParsed>> {
+        // Extract taskId from skillKey (remove "tasks/" prefix if present, or use skillKey as-is)
+        const taskId = input.skillKey.replace(/^tasks\//, '');
+
+        // Build memory bundle
+        const memoryBundle = {
+            jobMemory: input.jobMemory,
+            taskMemory: input.taskMemory
+        };
+
+        // Step 1: Enrich memories with scoping data
+        const enrichedBundle = await this.enrichMemoriesWithScoping(taskId, 'task', memoryBundle);
+
+        // Step 2: Generate context markdown
+        const contextMarkdown = await this.generateContextMarkdown(taskId, 'task', enrichedBundle);
+
+        // Create enriched input
+        const enrichedInput: RunTaskRequest = {
+            ...input,
+            jobMemory: enrichedBundle.jobMemory,
+            taskMemory: enrichedBundle.taskMemory,
+            context: contextMarkdown
+        };
+
+        return this.taskExecutor.execute<TParsed>(enrichedInput, async (key) => {
+            await this.registry.diagnose(key);
+        });
+    }

package/.docs/code-used-before/task-executor.ts.old

@@ -0,0 +1,57 @@
+import { BaseClient } from "./base-client";
+import { SkillExecutor } from "./skill-executor";
+import { ExecutionType, RunTaskRequest, RunSkillResponse } from "../types";
+
+/**
+ * TaskExecutor
+ * 
+ * WHY: This class handles the "orchestration" of tasks which can have 
+ * different execution strategies (ExecutionType). It currently supports 
+ * 'direct' execution which simply delegates to the SkillExecutor.
+ */
+export class TaskExecutor extends BaseClient {
+    private skillExecutor: SkillExecutor;
+
+    constructor(gateway: any, logger: any, skillExecutor: SkillExecutor) {
+        super(gateway, logger);
+        this.skillExecutor = skillExecutor;
+    }
+
+    /**
+     * Executes a task based on its execution type.
+     * 
+     * WHY: Centralized entry point for task-based execution.
+     */
+    async execute<TParsed = any>(
+        taskRequest: RunTaskRequest,
+        onNotFound?: (skillKey: string) => Promise<void>
+    ): Promise<RunSkillResponse<TParsed>> {
+        const { executionType, taskMemory, jobMemory, ...rest } = taskRequest;
+
+        this.logger.info("[AI-SKILLS] runTask() entry", {
+            skillKey: taskRequest.skillKey,
+            executionType,
+            jobId: taskRequest.jobId,
+            identity: "runTask execute"
+        });
+
+        switch (executionType) {
+            case ExecutionType.DIRECT:
+                this.logger.info("[AI-SKILLS] Executing direct task (pass-through to skill)", {
+                    skillKey: taskRequest.skillKey,
+                    identity: "runTask direct"
+                });
+
+                return this.skillExecutor.execute<TParsed>({
+                    ...rest,
+                    taskMemory,
+                    jobMemory
+                }, onNotFound);
+
+            default:
+                const errorMsg = `[AI-SKILLS] Unsupported execution type: ${executionType}`;
+                this.logger.error(errorMsg, { identity: "runTask execute" });
+                throw new Error(errorMsg);
+        }
+    }
+}

package/.docs/code-used-before/test-run-task.ts.old

@@ -0,0 +1,42 @@
+import { XeonoxSkillsClient } from "./src/client";
+import { ExecutionType } from "./src/types";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+async function testRunTask() {
+    console.log("Starting runTask verification...");
+
+    const client = new XeonoxSkillsClient({
+        packageName: "TEST-TASK",
+        enableContentRegistry: true,
+        contentRegistryLocalPath: ".metadata"
+    });
+
+    try {
+        console.log("Calling runTask with ExecutionType.DIRECT...");
+        const response = await client.runTask({
+            skillKey: "skills/professional-answer",
+            executionType: ExecutionType.DIRECT,
+            input: {
+                question: "What is the capital of France?"
+            },
+            variables: {
+                orgName: "TestOrg"
+            }
+        });
+
+        console.log("Response received:");
+        console.log(JSON.stringify(response, null, 2));
+
+        if (response.skillKey === "skills/professional-answer") {
+            console.log("SUCCESS: runTask returned the correct skillKey.");
+        } else {
+            console.log("FAILURE: runTask returned an incorrect skillKey.");
+        }
+    } catch (error) {
+        console.error("Error during runTask execution:", error);
+    }
+}
+
+testRunTask();

package/.docs/code-used-before/types.txt

@@ -0,0 +1,23 @@
+
+export interface RunTaskRequest {
+  skillKey: string;                 // "skills/professional-answer"
+  input: Record<string, any> | string;
+  /** 
+   * WHY: Alias for 'memory'. Contextual variables for the skill (e.g. orgName, tone). 
+   * Aligns with SkillMetadata concepts of required/optional variables.
+   */
+  variables?: Record<string, any>;
+  context?: Record<string, any> | string;
+  knowledge?: Record<string, any>;
+  jobMemory?: JobHistory; // the history of all the tasks results so far from previous steps up to this task being executed ---> to the short term memory of the skill called
+  taskMemory?: TaskHistory; // the skills that were exuectuted up to this task---> to the  temporary memory of the skill called
+
+  jobId?: string;
+  agentId?: string;
+  skillId?: string;
+  masterSkillId?: string;
+  masterSkillActivityId?: string;
+  timeoutMs?: number;
+  executionType: ExecutionType;
+
+}

package/.docs/env-ready-policy.md

@@ -0,0 +1,40 @@
+# Standard: Env-Ready Component (ERC)
+
+**Version**: 1.0.0  
+**Drafting Agency**: Xeonox Architecture Team  
+**Goal**: Zero-Config "Plug & Play" across the entire AI ecosystem.
+
+## 1. Philosophy: "Plug & Play" (Zero-Config)
+
+Every component (SDK, Gateway, Provider) must be operational immediately upon installation if the host environment provides the necessary configuration. Explicit code-based configuration is the **Advanced Mode** fallback.
+
+## 2. Mandatory Internal Behaviors
+
+### 2.1 Auto-Discovery
+- Constructors **MUST** attempt to resolve state from `process.env` when no explicit configuration object is passed.
+- **Example**: `new AIGateway()` should find its own keys, database URIs, and registry settings without being told where they are in code.
+
+### 2.2 Transitive Configuration (The Sum Principle)
+- A component's environment requirement is the **UNION** of its own required variables and the required variables of all components it utilizes.
+- **Example**: If `@xeonoces/ai-skills` uses `@athenices/ai-gateway`, the `ai-skills` `.env.example` must include all `GITHUB_*` keys (from gateway) AND its own unique keys.
+
+### 2.3 Built-in Validation
+- Components **MUST** validate their configuration (whether from object or env) during initialization.
+- If a mandatory requirement is missing, it must throw a named error:
+  - `[NAME] ERC_VALIDATION_ERROR: Missing [VARIABLE_NAME].`
+
+## 3. Mandatory Documentation
+
+### 3.1 The `.env.example` Standard
+Every repository **MUST** maintain a `.env.example` root file following this structure:
+- **Marker**: `[REQUIRED]` or `[OPTIONAL]`.
+- **Purpose**: Short description of the variable's impact.
+- **Source**: If the variable is required by a *dependency*, note which one (e.g., `[REQUIRED by AI-GATEWAY]`).
+
+### 3.2 The README "Env-Ready" Badge
+READMEs must explicitly claim compliance:
+> 🚀 **Env-Ready (ERC)**: This component supports automatic zero-config initialization via environment variables.
+
+## 4. Compliance Check (The "Bug" Rule)
+
+Failure of a component to auto-initialize when `.env` is correctly populated is no longer a "feature gap"—it is a **High-Priority Bug** (ERC Policy Violation). Reports should be filed with the `erc-violation` label.

package/.docs/flow-io/flow-README.md

@@ -0,0 +1,76 @@
+# `runTask` architecture (ai-tasks)
+
+High-level map only. Details live in the linked docs below.
+
+**Component:** [`@exellix/xynthesis`](https://www.npmjs.com/package/@exellix/xynthesis) is the LLM package ai-tasks calls for PRE/POST pipeline steps. It is **not** the same as the request field `xynthesized` (graph memory buckets).
+
+---
+
+## Block diagram
+
+```
+RunTaskRequest
+      │
+      ▼
+┌─────────────────┐
+│  runTask()      │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+    ▼         ▼
+ local     continue
+ task      (LLM path)
+    │         │
+    │    ┌────┴────────────────────────────────────┐
+    │    │                                         │
+    │    ▼                                         │
+    │  NARRIX pre-processor (optional)             │  →  [narrix.md](./narrix.md)
+    │    │ may include web scoping                  │  →  [web-scoping.md](./web-scoping.md)
+    │    ▼                                         │
+    │  executionPipeline PRE (optional)            │
+    │    └─ synthesized-context                    │  →  [xynthesis-pre.md](./xynthesis-pre.md)
+    │         calls @exellix/xynthesis             │
+    │    ▼                                         │
+    │  MAIN — @exellix/ai-skills runSkill          │  (not documented here)
+    │    ▼                                         │
+    │  executionPipeline POST (optional)           │
+    │    └─ audit / polish                         │  →  [xynthesis-post.md](./xynthesis-post.md)
+    │         calls @exellix/xynthesis             │
+    │    ▼                                         │
+    └────┴─────────────────────────────────────────┘
+         │
+         ▼
+   RunTaskResponse
+```
+
+---
+
+## Focused documentation
+
+| Doc | Scope |
+|-----|--------|
+| [xynthesis-pre.md](./xynthesis-pre.md) | PRE `synthesized-context` — how ai-tasks calls **xynthesis** before MAIN |
+| [xynthesis-post.md](./xynthesis-post.md) | POST `audit` / `polish` — how ai-tasks calls **xynthesis** after MAIN |
+| [narrix.md](./narrix.md) | NARRIX pre-processor — ingest, runner, `_narrix` attachment (no xynthesis) |
+| [web-scoping.md](./web-scoping.md) | Web scoper — `executionMemory.webContext` (no xynthesis) |
+
+---
+
+## Graph-engine authoring (model vs runtime)
+
+Each flow doc ends with two sections:
+
+| Section | Contract |
+|---------|----------|
+| **TaskNode model** | Static `TaskNode` / `taskConfiguration` fields graph-engine compiles into `RunTaskRequest` |
+| **TaskNode runtime** | Per-run `GraphRuntimeObject.nodes[nodeId]` and run-scoped memory that affect that step |
+
+Full graph contracts (graph-engine repo): **Task Node Model Object Format**, **Task Node Runtime Object Format**.
+
+---
+
+## Normative contracts (outside `.docs`)
+
+- [RUNTASK_REQUEST.md](../../RUNTASK_REQUEST.md) — request/response wire shape
+- [documenations/synthesized-context-guide.md](../../documenations/synthesized-context-guide.md) — PRE step config reference

package/.docs/flow-io/narrix.md

@@ -0,0 +1,124 @@
+# NARRIX pre-processor
+
+How `@exellix/ai-tasks` runs **NARRIX** before MAIN. This path does **not** call **xynthesis**.
+
+For web enrichment after NARRIX, see [web-scoping.md](./web-scoping.md).
+
+---
+
+## When it runs
+
+- `RunTaskRequest.narrix` is set (`NarrixPreProcessorConfig`)
+- Runs early in `runTask()`, before local-task check’s LLM path and before pipeline PRE
+- Separate path: `narrixMode: "handler"` + `narrixInput` (structured handler, not the same as `request.narrix` pre-processor)
+
+---
+
+## Request
+
+```typescript
+narrix?: {
+  datasetId: string;           // required
+  attachToField?: string;      // default "_narrix"
+  enableWebScope?: boolean;    // default false → see web-scoping.md
+  deterministicSort?: boolean;
+  // web scope templates / questions when enableWebScope: true
+}
+```
+
+Record source: adapted from `jobMemory` / `executionMemory` / `input` via `@exellix/xmemory-narrix-adapter`.
+
+---
+
+## Execution flow
+
+```
+runTask()
+  → adaptMemoryToNarrixInput(...)
+  → narrixRunHandler({ input, ctx })
+       → @exellix/narrix-ingest (CNI)
+       → @exellix/narrix-runner
+  → buildNarrixAttachment(result)
+  → executionMemory[attachToField] = attachment
+  → jobMemory._narrix = attachment (mirror)
+  → optional web scoping → executionMemory.webContext
+  → continue with same RunTaskRequest
+```
+
+Implementation: `src/core/task-sdk.ts` (NARRIX block), `src/narrix/task.ts`, `src/narrix/buildNarrixAttachment.ts`.
+
+---
+
+## Context passed to handler
+
+`ctx` includes: `skillKey`, memories, `variables`, `xynthesized`, `smartInput`, graph ids — same top-level fields as the request (no xynthesis).
+
+---
+
+## Downstream use
+
+| Consumer | Uses NARRIX output |
+|----------|-------------------|
+| MAIN context generation | `buildNarrixPreProcessorContextMarkdown` from `executionMemory._narrix` when `includeContextInPrompt` |
+| PRE xynthesis | Narrix markdown in `resolveSourceMaterial*` when `contextSourcePolicy` includes narrix — [xynthesis-pre.md](./xynthesis-pre.md) |
+| `taskMemory.narrix` | Handler mode / legacy narrix-then-direct |
+
+---
+
+## Failure
+
+NARRIX pre-processor failure **throws** (task does not continue). Web scoping failure is **non-fatal** (see [web-scoping.md](./web-scoping.md)).
+
+---
+
+## Packages (not xynthesis)
+
+- `@exellix/narrix-ingest`, `@exellix/narrix-runner`, `@exellix/narrix-cni`
+- `@exellix/xmemory-narrix-adapter`
+
+---
+
+## TaskNode model (graph authoring)
+
+NARRIX config belongs on **`taskConfiguration`**, not `metadata`.
+
+| TaskNode field | Role for NARRIX |
+|----------------|-----------------|
+| `taskConfiguration.narrix` | **`RunTaskRequest.narrix`**: `datasetId`, `attachToField`, `enableWebScope`, web scope templates/questions, `deterministicSort`, … |
+| `taskConfiguration.narrixMode` | `"preprocessor"` (default path: `request.narrix`) vs `"handler"` (`narrixInput` + handler pipeline). |
+| `taskConfiguration.narrixInput` | Handler mode structured input (may use `$path` into `jobMemory`). |
+| `taskConfiguration.aiTaskProfile.webScoping` | Canonical authoring intent for web; graph-engine forwards into resolved `narrix` payload (see [web-scoping.md](./web-scoping.md)). |
+| `node.inputsConfig` | Binds runtime payload paths (e.g. `executionMemoryPath: "input.raw"`) that the adapter prefers when locating a record. |
+| `node.taskVariable` | May supply `question` / literals compiled into `RunTaskRequest.input` for web question templates. |
+| `node.taskKnowledge` | Static refs → outbound `taskMemory.knowledge` copy for this node (not NARRIX ingest itself). |
+| `node.memory` | Rare per-node memory override on the model; forwarded if graph-engine maps it. |
+
+**Forbidden:** `metadata.narrix` — use `taskConfiguration.narrix`.
+
+NARRIX does **not** read `node.executionPipeline` or `modelConfig` (no LLM in the ingest/runner path).
+
+---
+
+## TaskNode runtime (per-run overrides)
+
+| Runtime field | Role for NARRIX |
+|---------------|-----------------|
+| `runtime.jobMemory` | Record discovery via `@exellix/xmemory-narrix-adapter` (`jobMemory.record`, `currentRecord`, …). |
+| `runtime.taskMemory` | Handler / legacy paths; may hold prior `narrix` entries. |
+| `runtime.executionMemory` | **Written by ai-tasks:** `executionMemory[attachToField]` (`_narrix`), optional `webContext`. **Read:** `input`, `inputs`, paths from `inputsConfig`. |
+| `runtime.input` / `runtime.inputs` | Mirrored into `executionMemory` before the pre-processor runs. |
+| `runtime.nodes[nodeId].modelConfig` | **Does not affect NARRIX** (ingest/runner are deterministic; no xynthesis call). |
+
+**Not on node runtime:** `datasetId`, `enableWebScope`, or attach field — those are model/`taskConfiguration` only.
+
+---
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/core/task-sdk.ts` | Pre-processor orchestration |
+| `src/narrix/task.ts` | `narrixRunHandler` |
+| `src/narrix/narrixContextMarkdown.ts` | Context markdown for MAIN / synthesis |
+| `src/narrix/buildNarrixAttachment.ts` | Attachment shape |
+| `src/types/task-types.ts` | `NarrixPreProcessorConfig` |

package/.docs/flow-io/web-scoping.md

@@ -0,0 +1,135 @@
+# Web scoping
+
+How `@exellix/ai-tasks` fills **`executionMemory.webContext`** using **`@exellix/narrix-web-scoper`**. This path does **not** call **xynthesis**.
+
+For how web markdown is consumed in PRE synthesis, see [xynthesis-pre.md](./xynthesis-pre.md).
+
+---
+
+## When it runs
+
+- Inside the **NARRIX pre-processor** path (`request.narrix` set)
+- `narrix.enableWebScope === true`
+- After NARRIX runner succeeds (CNI + entity)
+- Requires **`TAVILY_API_KEY`** (via `@x12i/search-adapter`)
+
+Skipped when:
+
+- `enableWebScope` is false or omitted
+- `skipWebScopeWhenExternalWebMarkdownPresent === true` and caller already set `executionMemory.webContextMarkdown`
+
+---
+
+## Request knobs
+
+On `RunTaskRequest.narrix`:
+
+| Field | Role |
+|-------|------|
+| `enableWebScope` | Opt-in boolean |
+| `webScoping` | Per-request scoper config (snippets, caps) |
+| `webScopeTemplates` | Template-driven scope |
+| `webScopeQuestionTemplate` | Question template for AI-driven questions |
+| `webScopeObjects` | Scope targets |
+| `webScopeQuestions` | Explicit question-pack mode |
+
+---
+
+## Execution flow
+
+```
+NARRIX success
+  → resolveWebScopeQuestionAndTemplates(...)
+  → runWebScope / runWebScopeQuestionPack   (src/narrix/webScoper.ts)
+       → createWebScoper({ searchAdapter: Tavily })
+       → @exellix/narrix-web-scoper
+  → executionMemory.webContext = WebScoperResult
+```
+
+Implementation: `src/core/task-sdk.ts`, `src/narrix/webScoper.ts`, `src/narrix/buildWebScopeScopeInput.ts`.
+
+---
+
+## Result shape
+
+Stored at **`executionMemory.webContext`**:
+
+- `available: true` → `context` with `sources`, `findings`, `scopes`, …
+- `available: false` → `reason` / `error` (task still continues)
+
+Always written when scoping was attempted (lenient — NARRIX attachment is kept).
+
+---
+
+## Downstream consumers
+
+| Consumer | Behavior |
+|----------|----------|
+| MAIN context | `buildWebContextEvidenceMarkdown` appended when web hit |
+| PRE xynthesis | Web section in `resolveSourceMaterial` / question-driven `web` source |
+| Question-driven PRE | Per-question `source: "web"` reads `executionMemory.webContext` |
+
+Raw `webContext` JSON is **not** dumped into memory JSON for synthesis; it is rendered to markdown excerpts (`SynthesisConfig.webEvidence` caps dedupe/clean text).
+
+---
+
+## Activix
+
+`webScopeActivixCorrelationPatch` links scoping to `jobId` / `taskId` for telemetry.
+
+---
+
+## Failure stance
+
+Web scoping errors are logged; NARRIX output and task execution continue. Synthesis may record `webUnavailableReason` in question-driven answers.
+
+---
+
+## TaskNode model (graph authoring)
+
+Web scoping is configured on the **NARRIX** block graph-engine forwards to `RunTaskRequest.narrix`.
+
+| TaskNode field | Role for web scoping |
+|----------------|----------------------|
+| `taskConfiguration.aiTaskProfile.webScoping` | **Canonical** authoring path for web intent; engine merges into outbound `narrix` / scoping options. |
+| `taskConfiguration.narrix.enableWebScope` | Opt-in boolean on the forwarded `RunTaskRequest.narrix` (default false). |
+| `taskConfiguration.narrix.webScoping` | Per-request scoper caps/snippets (`WebScoperConfig.scoping`). |
+| `taskConfiguration.narrix.webScopeTemplates` | Template-driven scope when set. |
+| `taskConfiguration.narrix.webScopeQuestionTemplate` | AI-driven question generation template. |
+| `taskConfiguration.narrix.webScopeObjects` | Scope targets for the scoper. |
+| `taskConfiguration.narrix.webScopeQuestions` | Explicit question-pack mode (`{ id?, question, source? }[]`). |
+| `node.taskVariable.question` | Feeds scope question resolution when templates reference the task question. |
+| `taskConfiguration.narrix.skipWebScopeWhenExternalWebMarkdownPresent` | Skip scoper when caller already supplies external web markdown at runtime. |
+
+Requires `taskConfiguration.narrix` (or equivalent forwarded `request.narrix`) with NARRIX pre-processor enabled — web scoping does not run standalone.
+
+**Forbidden:** `metadata.webScoping` — use `taskConfiguration.aiTaskProfile.webScoping` / `taskConfiguration.narrix`.
+
+---
+
+## TaskNode runtime (per-run overrides)
+
+| Runtime field | Role for web scoping |
+|---------------|------------------------|
+| `runtime.executionMemory.webContext` | **Output** of the scoper for this run (`WebScoperResult`: `available`, `context` \| `reason`). |
+| `runtime.executionMemory.webContextMarkdown` | Caller-provided markdown; when set + `skipWebScopeWhenExternalWebMarkdownPresent`, scoper may be skipped. |
+| `runtime.executionMemory` (entity context) | NARRIX entity/CNI from prior step in the same `runTask` — scoper input after NARRIX success. |
+| `runtime.input` | Question/entity hints via `resolveWebScopeQuestionAndTemplates`. |
+| `runtime.nodes[nodeId].modelConfig` | **Does not affect** web scoping (Tavily search + scoper, no xynthesis). |
+
+**Not on node runtime:** `enableWebScope`, templates, or question packs — model only.
+
+Host must supply **`TAVILY_API_KEY`** in the environment; not a TaskNode field.
+
+---
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/narrix/webScoper.ts` | Scoper singleton, `runWebScope*` |
+| `src/narrix/webContextMarkdown.ts` | Markdown for context / synthesis |
+| `src/narrix/buildWebScopeScopeInput.ts` | Question/template resolution |
+| `src/synthesis/resolveSourceMaterial.ts` | Policy includes web markdown |
+
+Extended reference: [documenations/web-scoping-in-ai-tasks.md](../documenations/web-scoping-in-ai-tasks.md).