@exellix/ai-tasks 10.0.9 → 10.0.11

package/dist/narrix/webScoper.js

@@ -1,144 +0,0 @@
-import { createWebScoper } from "@exellix/narrix-web-scoper";
-import { createSearchAdapter } from "@x12i/search-adapter";
-let searchAdapterInstance = null;
-let defaultScoper = null;
-let testOverride = null;
-function getSearchAdapter() {
-    if (!searchAdapterInstance) {
-        searchAdapterInstance = createSearchAdapter({
-            provider: "tavily",
-            tavily: {
-                apiKey: process.env.TAVILY_API_KEY,
-            },
-        });
-    }
-    return searchAdapterInstance;
-}
-/** Returns (and lazily creates) the shared NarrixWebScoper instance (default @exellix/narrix-web-scoper config). */
-export function getWebScoper() {
-    if (testOverride)
-        return testOverride;
-    if (!defaultScoper) {
-        defaultScoper = createWebScoper({ enabled: true, searchAdapter: getSearchAdapter() });
-    }
-    return defaultScoper;
-}
-/** Reset singletons (test helper). */
-export function resetWebScoperSingleton() {
-    searchAdapterInstance = null;
-    defaultScoper = null;
-    testOverride = null;
-}
-/** Override singleton with a mock (test helper). */
-export function setWebScoperForTesting(mock) {
-    testOverride = mock;
-}
-function hasRequestScoping(scoping) {
-    if (!scoping)
-        return false;
-    return Object.keys(scoping).length > 0;
-}
-function scoperForCall(scoping) {
-    if (testOverride)
-        return testOverride;
-    if (hasRequestScoping(scoping)) {
-        return createWebScoper({
-            enabled: true,
-            searchAdapter: getSearchAdapter(),
-            scoping,
-        });
-    }
-    return getWebScoper();
-}
-function isWebContextLike(v) {
-    if (!v || typeof v !== "object")
-        return false;
-    const o = v;
-    return Array.isArray(o.findings) && Array.isArray(o.sources) && Array.isArray(o.queriesUsed);
-}
-/**
- * Map `scopeQuestionPack` output to the legacy `WebScoperResult` shape stored in `executionMemory.webContext`
- * so `buildWebContextEvidenceMarkdown` and synthesis paths stay compatible.
- */
-export function mapWebScopePackResultToWebScoperResult(pack) {
-    if (!pack.available) {
-        return { available: false, reason: "notEligible" };
-    }
-    const pc = pack.context;
-    const findings = Array.isArray(pc.findings) ? pc.findings : [];
-    const sources = Array.isArray(pc.sources) ? pc.sources : [];
-    const queriesUsed = Array.isArray(pc.queriesUsed) ? pc.queriesUsed : [];
-    const summary = typeof pc.summary === "string" ? pc.summary.trim() : "";
-    const hasLegacy = findings.length > 0 ||
-        sources.length > 0 ||
-        queriesUsed.length > 0 ||
-        summary.length > 0;
-    if (hasLegacy) {
-        return {
-            available: true,
-            context: {
-                findings,
-                ...(summary ? { summary } : {}),
-                queriesUsed,
-                evidenceCount: findings.length,
-                sources,
-                retrievedAt: new Date().toISOString(),
-            },
-            cached: false,
-        };
-    }
-    const scopes = pc.scopes;
-    if (scopes && typeof scopes === "object") {
-        for (const s of Object.values(scopes)) {
-            if (s?.available === true && s.context && isWebContextLike(s.context)) {
-                return {
-                    available: true,
-                    context: s.context,
-                    cached: Boolean(s.cached),
-                };
-            }
-        }
-    }
-    return { available: false, reason: "noQueries" };
-}
-/** Non-empty trimmed strings only; omits unset/blank ids. */
-export function webScopeActivixCorrelationPatch(parts) {
-    const out = {};
-    const jobId = typeof parts.jobId === "string" ? parts.jobId.trim() : "";
-    const taskId = typeof parts.taskId === "string" ? parts.taskId.trim() : "";
-    const sessionId = typeof parts.sessionId === "string" ? parts.sessionId.trim() : "";
-    if (jobId)
-        out.jobId = jobId;
-    if (taskId)
-        out.taskId = taskId;
-    if (sessionId)
-        out.sessionId = sessionId;
-    return out;
-}
-/**
- * Run scopeGeneric and return the result. On any thrown error, returns an available:false result
- * so callers can apply lenient fallback without try/catch boilerplate.
- */
-export async function runWebScope(input, options) {
-    try {
-        return await scoperForCall(options?.scoping).scopeGeneric(input);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { available: false, reason: "error", error: message };
-    }
-}
-/**
- * Run `scopeQuestionPack` and normalize to {@link WebScoperResult} for `executionMemory.webContext`.
- */
-export async function runWebScopeQuestionPack(input, options) {
-    try {
-        const pack = await scoperForCall(options?.scoping).scopeQuestionPack(input);
-        return mapWebScopePackResultToWebScoperResult(pack);
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { available: false, reason: "error", error: message };
-    }
-}
-//# sourceMappingURL=webScoper.js.map

package/dist/narrix/webScoper.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"webScoper.js","sourceRoot":"","sources":["../../src/narrix/webScoper.ts"],"names":[],"mappings":"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"}

package/documenations/activix.md

@@ -1,187 +0,0 @@
-# Activix Integration
-
-This packaged doc summarizes task-activity tracking via `@x12i/activix`.
-
-## Activix Integration Best Practices Checklist
-
-Use this as the operational checklist for integrating `@x12i/activix` correctly and consistently.
-
-### 1) Ownership and boundaries
-
-- Treat **Activix** as the activity-domain layer:
-  - lifecycle semantics (`start` / `in_progress` / `complete` / `fail`)
-  - activity contract validation
-  - run-context correlation persistence
-- Treat **xronox-store** as the data tier:
-  - cache, write mode, retry policy, Mongo persistence behavior
-  - collection/index management
-  - generic primary-key storage mechanics
-
-### 2) Construct once, reuse instance
-
-- Prefer one `Activix` instance per service process (or one shared `XronoxStore` with `skipStoreInit: true`).
-- Do not create a new `Activix` per tiny unit of work unless architecture requires it.
-- If multi-instance is expected, pass `diagnostics` metadata so logs are self-identifying.
-
-```ts
-const ax = new Activix({
-  storageMode: 'automatic', // or 'database'
-  mongoUri: process.env.MONGO_URI!,
-  collection: 'task-activities',
-  diagnostics: {
-    owner: '@your-org/your-service',
-    component: 'graph-executor',
-    instanceLabel: 'worker-main',
-    workerId: process.pid.toString(),
-  },
-});
-await ax.init();
-```
-
-### 3) Define collection contract explicitly
-
-- Set collection names in code (`collection` or `collections`).
-- Keep `primaryKey` and `primaryKeyPrefix` intentional.
-- If you index `activityId` uniquely, Activix must always persist a non-null `activityId` (current behavior).
-- Ensure store-side visibility matches `purgeAtField` if using soft purge.
-
-### 4) Always pass run context at write time
-
-- `runContext` is runtime context, not constructor config.
-- Always pass a real `sessionId` from true upstream when available.
-- Forward run context through layers; do not replace inherited correlation IDs.
-
-```ts
-const { activityId } = await ax.startRecord({
-  runContext: {
-    sessionId: request.sessionId,
-    jobId: request.jobId,
-    taskId: request.taskId,
-  },
-  outer: {
-    input: payload,
-    output: null,
-    metadata: { type: 'task' },
-  },
-});
-```
-
-### 5) Use lifecycle APIs as intended
-
-- `startRecord()` first; keep returned `activityId`.
-- Use the same `activityId` for all follow-ups:
-  - `markInProgress(activityId, ...)`
-  - `completeRecord(activityId, ...)`
-  - `failRecord(activityId, ...)`
-  - `patchRecord(activityId, ...)`
-  - `getRecord(activityId)`
-- Never pass empty IDs; treat missing ID as integration bug and fail fast.
-
-### 6) Respect payload ownership rules
-
-- Integrators should provide domain payload (`outer`/`inner`/`runContext`).
-- Do not provide lifecycle-owned fields manually:
-  - `activityId` / configured primary key
-  - `status`, `startTime`, `endTime`, `duration`
-  - `createdAt`, `updatedAt`
-  - `error` (except via `failRecord`)
-
-### 6b) Collection tracking state (Activix 8.4+) — always call, let Activix persist
-
-- **Always call** Activix lifecycle APIs on every AI activity phase (`startRecord`, `completeRecord`, `failRecord`, …).
-- **Do not** branch in ai-tasks (or other integrators) on whether to write to Mongo.
-- Activix reads the **`activix-collections`** legend row for your collection and its **`state`**:
-  - **`track`** (default) — rows are persisted
-  - **`off`** — same API and return shapes; Mongo writes are skipped
-- Toggle persistence at runtime: `setCollectionTrackingState('task-activities', 'off' | 'track')`.
-- ai-tasks constructs Activix when **`MONGO_URI`** or **`MONGO_LOGS_URI`** is set; set **`ACTIVIX_ENABLED=false`** only to skip client construction entirely (dev/CI zero-overhead escape hatch).
-- Package collection name is **`task-activities`** (hard-coded in `src/activix/activixClient.ts`).
-
-### 7) Validate shape and observability expectations
-
-- `outer` is required and must contain:
-  - `input`
-  - `output` (or omitted initially and normalized)
-  - `metadata` object
-- Optional `inner` must follow request/response/metadata shape.
-- Enable logs during rollout:
-  - `ACTIVIX_LOGS_LEVEL=debug`
-  - `XRONOX_STORE_LOG=1`
-
-### 8) Multi-instance init diagnostics
-
-If `storageMode: 'automatic'`, each Activix instance performs:
-
-1. one Mongo probe
-2. one store init
-
-Use these fields to distinguish healthy multi-instance behavior from bugs:
-
-- `activixInstanceId`
-- `alreadyInitialized`
-- `usingInitPromise`
-- `initCallCount`
-
-Expected pattern: one probe + one store init per `activixInstanceId`.
-
-### 9) Reliability and retry expectations
-
-- Retry/classification policy belongs to xronox-store.
-- For deterministic Mongo failures (e.g. duplicate key), rely on current store behavior/version policy.
-- Keep `@xronoces/xronox-store` up to date and pin known-good versions in CI.
-
-### 10) Minimum production readiness checklist
-
-- [ ] Single shared Activix instance (or intentional multi-instance with diagnostics metadata)
-- [ ] Stable collection configuration committed in code
-- [ ] `runContext.sessionId` passed from upstream for correlated runs
-- [ ] `startRecord` return value (`activityId`) propagated through full lifecycle
-- [ ] Logging flags documented for operations team
-- [ ] Integration test path covers start -> progress -> complete/fail
-- [ ] Dependency version policy defined for `@xronoces/xronox-store`
-
----
-
-For deeper reference, see:
-
-- `README.md`
-- `.docs/run-context-object.md`
-- `.docs/session-id-usage.md`
-- `.docs/activity-structure.md`
-- `.docs/logging-stack.md`
-
-## What it tracks
-
-A single `runTask()` call can emit phase records such as:
-
-- `local`
-- `narrix`
-- `pipeline_pre`
-- `direct`
-- `audit`
-- `polish`
-- `narrix_then_direct`
-
-All records for a run share a correlation id for grouping.
-
-## Enablement
-
-- **Client wiring:** Activix is constructed when `MONGO_URI` or `MONGO_LOGS_URI` is set. Set `ACTIVIX_ENABLED=false` to opt out (no client, no lifecycle API calls).
-- **Mongo persistence:** Controlled by Activix collection legend **`state`** (`track` | `off`) in `activix-collections`, not by a required `ACTIVIX_ENABLED=true` flag. ai-tasks always calls lifecycle APIs when wired; Activix decides whether rows reach Mongo.
-- Activix failures are treated as non-fatal to task execution.
-
-## Typical metadata
-
-- `skillKey`, `executionStrategiesSummary`, `narrixMode`, `jobId`, `agentId`
-- graph/node identity fields
-- start/end/duration, status transitions
-- success metadata and error details
-
-## Stale cleanup
-
-Use stale-marking (for example periodic `markStaleRecords`) to convert stuck `started` records to `timeout`.
-
-## Related
-
-- `README.md` (Activix section)
-- `documenations/run-task-execution-flow.md`