@exellix/ai-tasks 8.1.10 → 8.1.12

package/.metadata/log-diagnostics.json

@@ -0,0 +1,76 @@
+{
+  "RUN_TASK_REQUEST_DUPLICATE_INPUT_BUCKETS": {
+    "defaultLevel": "warn",
+    "title": "RunTaskRequest sets both input and inputs",
+    "impact": "Smart-input resolution treats input.* and inputs.* as separate buckets; overlapping keys may confuse templates.",
+    "remediation": [
+      "Use only one top-level bucket unless both are intentional.",
+      "Review smartInput path bindings against input vs inputs."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "EXECUTION_PIPELINE_MULTIPLE_SYNTH_PRE": {
+    "defaultLevel": "warn",
+    "title": "Multiple PRE synthesized-context steps",
+    "impact": "Only the first PRE synthesized-context step runs; extra steps are ignored.",
+    "remediation": ["Consolidate PRE synthesized-context steps into one step."],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "EXECUTION_PIPELINE_UNSUPPORTED_PRE": {
+    "defaultLevel": "warn",
+    "title": "Unsupported PRE executionPipeline step",
+    "impact": "runTask throws when an unsupported PRE step is reached.",
+    "remediation": ["Use only synthesized-context for PRE steps, or remove unsupported PRE steps."],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "EXECUTION_PIPELINE_UNSUPPORTED_POST": {
+    "defaultLevel": "warn",
+    "title": "Unsupported POST executionPipeline step",
+    "impact": "Unsupported POST steps are ignored at runtime.",
+    "remediation": ["Use audit or polish for POST steps, or remove unsupported POST steps."],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "RUN_TASK_OBSERVABILITY_HINT": {
+    "defaultLevel": "warn",
+    "title": "RunTask observability hint",
+    "impact": "Detailed synthesis or scoping diagnostics are only surfaced in trace execution mode.",
+    "remediation": ["Set executionMode to trace when debugging PRE/POST xynthesis or aiScoping."],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "high"
+  },
+  "EXECUTION_STRATEGIES_MULTIPLE_OPTIMIZERS": {
+    "defaultLevel": "warn",
+    "title": "Multiple optimizer execution strategies",
+    "impact": "Only the first optimizer (after priority sort) drives the MAIN retry loop.",
+    "remediation": ["Supply a single optimizer or merge optimizer behavior into one entry."],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "NARRIX_WEB_SCOPE_MISS": {
+    "defaultLevel": "warn",
+    "title": "Narrix web scope unavailable",
+    "impact": "Web context evidence is omitted from Narrix PRE attachment for this run.",
+    "possibleCauses": [
+      "Web scoping query returned no usable evidence.",
+      "Narrix web scoper failed or timed out.",
+      "enableWebScope was set without sufficient scoping configuration."
+    ],
+    "remediation": [
+      "Inspect NARRIX_DEBUG logs and trace-mode webContext metadata.",
+      "Verify web scoping configuration and upstream search availability."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  }
+}

package/CHANGELOG.md

@@ -6,6 +6,10 @@ The published **npm version** always matches **`version`** in [`package.json`](p
 
 ## [Unreleased]
 
+### Changed
+
+- **`@x12i/logxer` ^4.4.2:** Package diagnostics use **`createLogxer`** with diagnostic catalog (`.metadata/log-diagnostics.json`), **`warnCode`** / **`DebugLogAbstract`**, **`fieldEvidence`**, **`runWithLogContext`** during **`runTask()`**, and in-process **`getAiTasksJobLogs`** for debug UIs. Override pins transitive logxer to **4.4.2** (no nested **4.4.0** from `@x12i/optimixer`).
+
 ## [8.1.1] - 2026-05-28
 
 ### Changed

package/README.md

@@ -80,7 +80,7 @@ npm install @exellix/ai-tasks
 npm install @exellix/ai-tasks @woroces/ai-skills
 ```
 
-**Bundled x12i stack (direct dependencies of this package):** `@x12i/catalox` (catalog reads / publish script), `@x12i/env` (env conventions aligned with the Woreces stack), and `@x12i/logxer` **4.4+** (`createLogxer` for package diagnostics — `AI_TASKS_LOGS_LEVEL` / `ACTIVIX_LOGS_LEVEL`; structured metadata, PII sanitization, shadow capture, and host-level sinks per the logxer ERC contract). Older names `logs-gateway` and `nx-config2` are not direct dependencies here.
+**Bundled x12i stack (direct dependencies of this package):** `@x12i/catalox` (catalog reads / publish script), `@x12i/env` (env conventions aligned with the Woreces stack), and `@x12i/logxer` **4.4.2+** — **`createLogxer`**, **`warnCode`/`errorCode`** with shipped diagnostic catalog (`.metadata/log-diagnostics.json`), **`DebugLogAbstract`**, **`fieldEvidence`**, **`runWithLogContext`** (wired in **`runTask()`** via **`runAiTasksWithLogContext`**), and in-process **`getAiTasksJobLogs`** for debug tooling. Per-package thresholds: **`AI_TASKS_LOGS_LEVEL`**, **`ACTIVIX_LOGS_LEVEL`**. Older names `logs-gateway` and `nx-config2` are not direct dependencies here.
 
 ### Narrix (v5+)
 
@@ -2411,7 +2411,9 @@ When `false` (the default), `runTask()` runs exactly as today with zero overhead
 | `ACTIVIX_STALE_TTL_MS` | `300000` | TTL (ms) before a stuck `started` record is marked `timeout` |
 | `ACTIVIX_LOGS_LEVEL` | _(see below)_ | Canonical internal log threshold for injected Activix logger (`@x12i/logxer` `createLogxer`, env prefix **`ACTIVIX`**). If unset, falls back to `ACTIVIX_LOG_LEVEL`, then default `warn`. Values: `verbose` \| `debug` \| `info` \| `warn` \| `error` \| `off` / `silent` / `none`. |
 | `ACTIVIX_LOG_LEVEL` | `warn` | Legacy alias when `ACTIVIX_LOGS_LEVEL` is unset (same resolution rules as `@x12i/logxer`). |
-| `AI_TASKS_LOGS_LEVEL` | `warn` | Canonical threshold for `@exellix/ai-tasks` diagnostics (`AI_TASKS_REQUEST_WARNINGS`, execution-strategy warnings, optional `NARRIX_DEBUG` paths). Legacy alias: `AI_TASKS_LOG_LEVEL`. |
+| `AI_TASKS_LOGS_LEVEL` | `warn` | Canonical threshold for `@exellix/ai-tasks` diagnostics (`AI_TASKS_REQUEST_WARNINGS`, execution-strategy warnings, optional `NARRIX_DEBUG` paths). Uses **`@x12i/logxer` 4.4.2** **`warnCode`** + catalog (`.metadata/log-diagnostics.json`). Legacy alias: `AI_TASKS_LOG_LEVEL`. |
+
+**Debug tooling (logxer 4.4.2):** **`getAiTasksJobLogs({ jobId, level, limit })`** queries in-process structured log envelopes captured during **`runTask()`**. Correlation ids (`jobId`, `taskId`, `graphId`, `nodeId`) are set via **`runAiTasksWithLogContext`** / **`patchRunTaskLogContext`** (re-exported from this package).
 
 ### What is recorded
 

package/dist/core/task-sdk.d.ts

@@ -1,5 +1,6 @@
 import { ExellixSkillsClient } from "@exellix/ai-skills";
 import { RunTaskRequest, RunTaskResponse } from "../types/index.js";
+import type { StackLoggingOptions } from "@x12i/logxer";
 type WorexClientSkills = ExellixSkillsClient;
 /**
  * Task execution client for @exellix/ai-tasks.
@@ -13,12 +14,17 @@ type WorexClientSkills = ExellixSkillsClient;
  * This is a private package. We intentionally reuse @exellix/ai-skills directly,
  * including its types and helpers. Naming leakage is acceptable.
  */
+export type WorexClientTasksOptions = {
+    /** Host pass-through for logxer ≥ 4.5 stack levels (ai-tasks, ai-skills, xynthesis, funcx). */
+    logging?: StackLoggingOptions;
+};
 export declare class WorexClientTasks {
     protected readonly skillsClient: WorexClientSkills;
     private readonly executor;
+    protected readonly stackLogging?: StackLoggingOptions;
     constructor(skillsClient: WorexClientSkills, executor: {
         execute<TParsed = any>(input: any, onNotFound: (key: string) => Promise<void>): Promise<RunTaskResponse<TParsed>>;
-    });
+    }, options?: WorexClientTasksOptions);
     runTask<TParsed = any>(input: RunTaskRequest): Promise<RunTaskResponse<TParsed>>;
     /**
      * Run the synthesized-context PRE step: enrich memory, resolve source material, render templates, call synthesis model, return synthesized context.

package/dist/core/task-sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-sdk.d.ts","sourceRoot":"","sources":["../../src/core/task-sdk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAazD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAuB,MAAM,mBAAmB,CAAC;AA0PzF,KAAK,iBAAiB,GAAG,mBAAmB,CAAC;AA0S7C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAEzB,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADN,YAAY,EAAE,iBAAiB,EACjC,QAAQ,EAAE;QACzB,OAAO,CAAC,OAAO,GAAG,GAAG,EACnB,KAAK,EAAE,GAAG,EACV,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;KACtC;IAGG,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IA2hDtF;;OAEG;YACW,6BAA6B;IAmhB3C;;;;;OAKG;YACW,cAAc;CAuR7B"}
+{"version":3,"file":"task-sdk.d.ts","sourceRoot":"","sources":["../../src/core/task-sdk.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAazD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAuB,MAAM,mBAAmB,CAAC;AAyBzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAyOxD,KAAK,iBAAiB,GAAG,mBAAmB,CAAC;AA0S7C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,+FAA+F;IAC/F,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF,qBAAa,gBAAgB;IAIzB,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;gBAGjC,YAAY,EAAE,iBAAiB,EACjC,QAAQ,EAAE;QACzB,OAAO,CAAC,OAAO,GAAG,GAAG,EACnB,KAAK,EAAE,GAAG,EACV,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;KACtC,EACD,OAAO,CAAC,EAAE,uBAAuB;IAQ7B,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IA2iDtF;;OAEG;YACW,6BAA6B;IAmhB3C;;;;;OAKG;YACW,cAAc;CAuR7B"}