@exellix/ai-tasks 9.1.0 → 9.1.1

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

@@ -1,39 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,23 +0,0 @@
-
-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

@@ -1,40 +0,0 @@
-# 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

@@ -1,76 +0,0 @@
-# `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

@@ -1,124 +0,0 @@
-# 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

@@ -1,135 +0,0 @@
-# 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).