@exellix/ai-tasks 10.0.9 → 10.0.11

package/dist/web-scope/webContextMarkdown.js

@@ -0,0 +1,163 @@
+/**
+ * Serialize executionMemory.webContext (`@x12i/web-scoper` WebScopeResult / WebScopePackResult) into markdown.
+ */
+import { isWebScopeSearchManyResult } from "./client.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function nonEmptyString(v) {
+    if (typeof v !== "string")
+        return undefined;
+    const t = v.trim();
+    return t ? t : undefined;
+}
+function normalizeUrlKey(url) {
+    try {
+        const u = new URL(url.trim());
+        u.hash = "";
+        return u.href;
+    }
+    catch {
+        return url.trim().split("#")[0] ?? url.trim();
+    }
+}
+function pickSourceUrl(src) {
+    return nonEmptyString(src.url) ?? nonEmptyString(src.link);
+}
+function pickSourceBody(src) {
+    return nonEmptyString(src.snippet) ?? nonEmptyString(src.title);
+}
+function resolveWebContext(entry) {
+    if (!isRecord(entry))
+        return undefined;
+    if (entry.ok === true && isRecord(entry.context))
+        return entry.context;
+    if (isWebScopeSearchManyResult(entry)) {
+        if (isRecord(entry.pack?.primary))
+            return entry.pack.primary;
+        for (const scope of Object.values(entry.pack?.scopes ?? {})) {
+            if (isRecord(scope) && scope.ok === true && isRecord(scope.context)) {
+                return scope.context;
+            }
+        }
+    }
+    return undefined;
+}
+function formatFindings(findings) {
+    if (findings == null)
+        return undefined;
+    if (typeof findings === "string") {
+        const t = findings.trim();
+        return t ? `**Findings:**\n\n${t}` : undefined;
+    }
+    if (!Array.isArray(findings) || findings.length === 0)
+        return undefined;
+    const lines = ["**Findings:**", ""];
+    for (const f of findings) {
+        if (typeof f === "string" && f.trim())
+            lines.push(`- ${f.trim()}`);
+        else if (isRecord(f)) {
+            const claim = nonEmptyString(f.claim);
+            lines.push(`- ${claim ?? JSON.stringify(f)}`);
+        }
+    }
+    return lines.join("\n");
+}
+function parseMaxTotalCharsEnv() {
+    const raw = process.env.WEB_CONTEXT_MARKDOWN_MAX_CHARS;
+    if (!raw)
+        return undefined;
+    const n = parseInt(raw, 10);
+    return !Number.isNaN(n) && n > 0 ? n : undefined;
+}
+export function isWebContextEvidenceAvailable(webContextEntry) {
+    const ctx = resolveWebContext(webContextEntry);
+    if (!ctx)
+        return false;
+    const sources = Array.isArray(ctx.sources) ? ctx.sources : [];
+    const hasSourceMaterial = sources.some((s) => isRecord(s) && (pickSourceBody(s) || pickSourceUrl(s)));
+    const summary = nonEmptyString(ctx.summary);
+    const findingsBlock = formatFindings(ctx.findings);
+    return hasSourceMaterial || !!summary || !!findingsBlock;
+}
+export function buildWebContextEvidenceMarkdown(webContextEntry, options) {
+    const ctx = resolveWebContext(webContextEntry);
+    if (!ctx)
+        return "";
+    let sources = Array.isArray(ctx.sources) ? [...ctx.sources] : [];
+    const dedupeByUrl = options?.dedupeByUrl !== false;
+    const maxSources = options?.maxSources ?? 5;
+    if (dedupeByUrl && sources.length > 0) {
+        const seen = new Set();
+        const out = [];
+        for (const s of sources) {
+            if (!isRecord(s)) {
+                out.push(s);
+                continue;
+            }
+            const url = pickSourceUrl(s);
+            const key = url ? normalizeUrlKey(url) : `__nourl_${out.length}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(s);
+        }
+        sources = out;
+    }
+    if (maxSources > 0 && sources.length > maxSources) {
+        sources = sources.slice(0, maxSources);
+    }
+    const summary = nonEmptyString(ctx.summary);
+    const findingsBlock = formatFindings(ctx.findings);
+    const hasSourceMaterial = sources.some((s) => isRecord(s) && (pickSourceBody(s) || pickSourceUrl(s)));
+    if (!hasSourceMaterial && !summary && !findingsBlock)
+        return "";
+    const lines = [
+        "",
+        "## Web sources (primary evidence)",
+        "",
+        "Ground factual claims in the **source excerpts** below. **Summary** and **findings** (if present) are overview hints only—not authoritative on their own.",
+        "",
+    ];
+    if (summary || findingsBlock) {
+        lines.push("### Web overview (hints only)", "", "*Do not treat this subsection alone as sufficient evidence.*", "");
+        if (summary)
+            lines.push("**Summary:**", summary, "");
+        if (findingsBlock)
+            lines.push(findingsBlock, "");
+    }
+    lines.push("### Source excerpts (ground truth)", "");
+    for (let i = 0; i < sources.length; i++) {
+        const src = sources[i];
+        if (!isRecord(src))
+            continue;
+        const title = nonEmptyString(src.title) ?? nonEmptyString(src.name) ?? `Source ${i + 1}`;
+        const url = pickSourceUrl(src);
+        const body = pickSourceBody(src);
+        if (!body && !url)
+            continue;
+        lines.push(`#### ${title}`, "");
+        if (url)
+            lines.push(`- URL: ${url}`, "");
+        if (body)
+            lines.push(body, "");
+    }
+    let out = lines.join("\n");
+    const maxTotal = options?.maxTotalChars ?? parseMaxTotalCharsEnv();
+    if (maxTotal !== undefined && out.length > maxTotal) {
+        const marker = "\n\n[truncated — web source budget exceeded]";
+        const cut = Math.max(0, maxTotal - marker.length);
+        return out.slice(0, cut) + marker;
+    }
+    return out.endsWith("\n") ? out : `${out}\n`;
+}
+export function omitWebContextFromMemoryBundle(bundle) {
+    const ex = bundle.executionMemory;
+    if (!ex || typeof ex !== "object" || !("webContext" in ex)) {
+        return bundle;
+    }
+    const restExec = { ...ex };
+    delete restExec.webContext;
+    return { ...bundle, executionMemory: restExec };
+}
+//# sourceMappingURL=webContextMarkdown.js.map

package/dist/web-scope/webContextMarkdown.js.map

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

package/documenations/run-task-execution-flow.md

@@ -13,11 +13,7 @@ flowchart TD
     B -- Yes --> N1[Resolve raw record]
     N1 --> N2[Run Narrix pre-processor]
     N2 --> N3[Attach _narrix to executionMemory and jobMemory]
-    N3 --> N4{narrix.enableWebScope === true?}
-    N4 -- Yes --> N5[Run web scoper]
-    N5 --> N6[Set executionMemory.webContext]
-    N4 -- No --> B2
-    N6 --> B2
+    N3 --> B2
 
     B2 -- Yes --> H1[Resolve narrixInput]
     H1 --> H2[Run structured Narrix handler]
@@ -57,7 +53,7 @@ flowchart TD
    - Resolve the raw record from `executionMemory`, `jobMemory`, or `input`.
    - Run Narrix (ingest + runner).
    - Attach result to `executionMemory._narrix` (or configured field) and mirror to `jobMemory._narrix`.
-   - If `narrix.enableWebScope` is `true`, run web scoping and store result in `executionMemory.webContext`.
+   - NARRIX does **not** trigger web scoping. Web context comes from a standalone `webScope` PRE unit (see [web-scoping-in-ai-tasks.md](./web-scoping-in-ai-tasks.md)).
 4. Else if **`narrixMode === "handler"`**, run structured Narrix from `narrixInput` (same behavior as legacy `narrix-then-direct` Narrix phase), **before** local tasks and pipeline PRE.
 5. Check local task registry for `skillKey`.
 6. If local handler exists, execute it and return immediately (skip enrichment/LLM path).
@@ -77,7 +73,7 @@ flowchart TD
 
 - Default execution is effectively direct when no pipeline is provided.
 - Local tasks are deterministic and bypass LLM execution.
-- Web scoping is non-fatal: Narrix attachment can still succeed when web scope misses/fails.
+- Web scoping is a standalone `webScope` PRE unit (rendered `webQueryTemplate`); it is non-fatal at runtime and decoupled from NARRIX.
 - POST steps (`audit`, `polish`) run only when declared in `executionPipeline`.
 - For PRE `synthesized-context`, structured mode is additive and template-core-aware (`templateCores` + question), while markdown mode remains available for backward compatibility.
 - Structured core discovery is pre-render from raw instructions/prompt templates and expects core directives in `{{core:...}}` form.