@exellix/ai-tasks 7.8.0

package/dist/core/task-sdk.js

@@ -0,0 +1,2432 @@
+// @exellix/ai-tasks
+import { randomUUID } from "crypto";
+import { resolveRunTaskRuntimeKnobs, } from "../internal/resolveRunTaskRuntimeKnobs.js";
+import { applyOptimizerFeedbackToRequest, applyPlannerOutputToRequest } from "../execution-strategies/applyExecutionStrategyOutputs.js";
+import { buildExecutionStrategyRequestPayload, runOptimizerFuncx, runPlannerFuncx, } from "../execution-strategies/runFuncxExecutionStrategy.js";
+import { resolveSafeExecutionStrategyCatalogDefaultFunctionId } from "../execution-strategies/executionStrategyCatalogMetadata.js";
+import { SYNTHESIZED_CONTEXT } from "../types/index.js";
+import { runAuditPostStep } from "../post-steps/audit/runAudit.js";
+import { runPolishPostStep } from "../post-steps/polish/runPolish.js";
+import { getLocalTask } from "../localTasks/registry.js";
+import { registerBuiltInLocalTasks } from "../localTasks/index.js";
+import { getByPath } from "../utils/jsonPaths.js";
+import { passthroughJobTemplateVariables } from "../utils/skillTemplateVariables.js";
+import { emitRunTaskRequestWarnings } from "../utils/runTaskRequestShape.js";
+import { assertRequiredRunSkillCorrelation } from "../utils/assertRequiredRunSkillCorrelation.js";
+import { compileTaskConfigurationOnRunTaskRequest } from "../compile/compileTaskConfiguration.js";
+import { assertValidSmartInputConfig } from "../utils/assertValidSmartInputConfig.js";
+import { extractSmartInputRenderResult } from "../utils/extractSmartInputRenderResult.js";
+import { normalizeSmartInputConfig } from "../utils/normalizeSmartInputConfig.js";
+import { applyXynthesizedOutputWrite, mergeXynthesizedPatchSlices, } from "../utils/xynthesizedWrite.js";
+import { validateParsedOutput } from "../utils/outputValidation.js";
+import { narrixRunHandler } from "../narrix/task.js";
+import { buildNarrixContextMarkdown, buildNarrixPreProcessorContextMarkdown } from "../narrix/narrixContextMarkdown.js";
+import { buildWebContextEvidenceMarkdown } from "../narrix/webContextMarkdown.js";
+import { applyNarrixScope } from "../narrix/applyNarrixScope.js";
+import { adaptMemoryToNarrixInput } from "@exellix/xmemory-narrix-adapter";
+import { buildNarrixAttachment } from "../narrix/buildNarrixAttachment.js";
+import { runWebScope, runWebScopeQuestionPack, webScopeActivixCorrelationPatch } from "../narrix/webScoper.js";
+import { resolveWebScopeQuestionAndTemplates } from "../narrix/buildWebScopeScopeInput.js";
+import { runAiScoping } from "../aiScoping/runAiScoping.js";
+import { getActivixClient } from "../activix/activixClient.js";
+import { withPhaseRecord } from "../activix/phaseTracking.js";
+import { activixOuterTier } from "@x12i/activix";
+import { createDebugTraceCollector, traceWrap } from "../observability/debugTrace.js";
+import { loadSynthesisTemplates, buildSynthesisSystemPrompt, buildSynthesisUserPrompt, resolveSourceMaterial, resolveSourceMaterialParts, getRenderedTemplates, buildSynthesizedContextMarkdown, resolveSynthesisQuestion, runStructuredSynthesisGatewayCallRobust, getContextSynthesizer, normalizeAndValidateSynthesizedPayload, discoverTemplateCores, } from "../synthesis/index.js";
+import { resolveOutputExpectation as resolveOutputExpectationXynthesis } from "@exellix/xynthesis/ai-actions";
+import { llmCallEnvPrefix, resolveLlmCall } from "../post-steps/resolvePostStepConfig.js";
+import { runPostStepLlmCall } from "../internal/runPostStepLlmCall.js";
+registerBuiltInLocalTasks();
+const DEFAULT_SYNTH_INPUT_MAX_CHARS = 200_000;
+function synthesizedResultForXynthesizedPatch(artifact, contextMarkdown) {
+    if (artifact !== undefined)
+        return artifact;
+    return { contextMarkdown };
+}
+function maxSynthesizedInputChars() {
+    const raw = process.env.SYNTHESIZED_INPUT_MAX_CHARS;
+    if (!raw)
+        return DEFAULT_SYNTH_INPUT_MAX_CHARS;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_SYNTH_INPUT_MAX_CHARS;
+}
+function buildSynthesizedInputArtifact(synthesisMode, sourceMaterial, parts, extras) {
+    const max = maxSynthesizedInputChars();
+    let truncated = false;
+    let sm = sourceMaterial;
+    if (sm.length > max) {
+        sm = sm.slice(0, Math.max(0, max - 80)) + "\n\n[truncated synthesizedInput.sourceMaterial]\n";
+        truncated = true;
+    }
+    const clip = (s) => (s.length <= max ? s : s.slice(0, max) + "…[truncated]");
+    return {
+        synthesisMode,
+        sourceMaterial: sm,
+        localMarkdown: clip(parts.localMarkdown),
+        supportingMarkdown: clip(parts.supportingMarkdown),
+        ...extras,
+        truncated,
+    };
+}
+function reuseableSynthesizedArtifact(artifact) {
+    if (!artifact || typeof artifact !== "object")
+        return false;
+    const a = artifact;
+    const mode = a.mode;
+    if (mode === "questionDriven") {
+        return typeof a.contextMarkdown === "string" && a.contextMarkdown.trim().length > 0;
+    }
+    if (mode === "markdown" || mode === "structured") {
+        return typeof a.contextMarkdown === "string";
+    }
+    return false;
+}
+function contextMarkdownFromArtifact(artifact) {
+    const a = artifact;
+    return typeof a.contextMarkdown === "string" ? a.contextMarkdown : "";
+}
+function appendExternalWebContextMarkdown(contextMarkdown, execMem, allowAppend) {
+    if (!allowAppend)
+        return contextMarkdown;
+    const raw = execMem?.webContextMarkdown;
+    if (typeof raw !== "string")
+        return contextMarkdown;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return contextMarkdown;
+    const base = contextMarkdown.length > 0 && !contextMarkdown.endsWith("\n") ? `${contextMarkdown}\n\n` : contextMarkdown;
+    return `${base}## Supplementary web context (caller-provided)\n\n${trimmed}\n`;
+}
+function isStrictDecisionTask(request) {
+    return request?.taskKind === "decision";
+}
+function defaultDecisionOutputSchema() {
+    return {
+        type: "object",
+        required: ["contractVersion", "shouldUseWeb", "reasonCodes", "missingSignals"],
+        properties: {
+            contractVersion: { type: "string" },
+            shouldUseWeb: { type: "boolean" },
+            reasonCodes: { type: "array", items: { type: "string" } },
+            missingSignals: { type: "array", items: { type: "string" } },
+        },
+        additionalProperties: false,
+    };
+}
+function withDefaultDecisionValidation(request) {
+    if (!isStrictDecisionTask(request))
+        return request;
+    const autoValidate = request.autoValidateDecisionOutput !== false;
+    if (!autoValidate)
+        return request;
+    if (request.outputValidation)
+        return request;
+    return {
+        ...request,
+        outputValidation: {
+            schema: defaultDecisionOutputSchema(),
+            mode: "fail",
+            validateWhenMissing: true,
+        },
+    };
+}
+/** Runtime `request.identity` forwarded to xynthesis synthesis calls (not from step config). */
+function synthesisIdentityFromRequest(request) {
+    const id = request.identity;
+    if (id == null || typeof id !== "object")
+        return undefined;
+    return id;
+}
+/** When the skills client has no `enrichMemoriesWithScoping` (semver drift), pass memory through unchanged. */
+async function passthroughEnrichMemories(_id, _level, bundle) {
+    return {
+        jobMemory: bundle.jobMemory ?? {},
+        taskMemory: bundle.taskMemory ?? {},
+        executionMemory: bundle.executionMemory ?? {},
+    };
+}
+/** When the skills client has no `generateContextMarkdown`, return empty context (callers that need context should use a client that implements it). */
+async function noopGenerateContextMarkdown() {
+    return "";
+}
+function bindEnrichMemoriesWithScoping(client) {
+    const c = client;
+    if (typeof c.enrichMemoriesWithScoping === "function") {
+        return c.enrichMemoriesWithScoping.bind(client);
+    }
+    return passthroughEnrichMemories;
+}
+function bindGenerateContextMarkdown(client) {
+    const c = client;
+    if (typeof c.generateContextMarkdown === "function") {
+        return c.generateContextMarkdown.bind(client);
+    }
+    return async (_id, _level, _bundle) => noopGenerateContextMarkdown();
+}
+function hasNonEmptyWebScoping(s) {
+    return s != null && Object.keys(s).length > 0;
+}
+/** Resolve narrixInput from request; if it has $path (e.g. jobMemory.currentRecord), resolve from jobMemory. */
+function resolveNarrixInput(narrixInput, jobMemory) {
+    if (!narrixInput || typeof narrixInput !== "object")
+        return null;
+    const o = narrixInput;
+    if (typeof o.$path === "string") {
+        const path = o.$path;
+        if (!path.startsWith("jobMemory."))
+            return null;
+        const rel = path.replace(/^jobMemory\./, "");
+        const resolved = getByPath(jobMemory ?? {}, rel);
+        if (!resolved || typeof resolved !== "object")
+            return null;
+        const r = resolved;
+        if (typeof r.medium !== "string" || typeof r.datasetId !== "string")
+            return null;
+        return resolved;
+    }
+    if (typeof o.medium === "string" && typeof o.datasetId === "string") {
+        return narrixInput;
+    }
+    return null;
+}
+/**
+ * Deep merge utility for execution objects.
+ * Merges source into target, with source taking precedence for conflicts.
+ * Arrays are concatenated, objects are deep merged.
+ */
+function deepMergeExecution(target, source) {
+    if (source === null || source === undefined) {
+        return target;
+    }
+    if (target === null || target === undefined) {
+        return source;
+    }
+    // If both are arrays, concatenate (source items appended)
+    if (Array.isArray(target) && Array.isArray(source)) {
+        return [...target, ...source];
+    }
+    // If both are objects, deep merge
+    if (typeof target === 'object' && typeof source === 'object' &&
+        !Array.isArray(target) && !Array.isArray(source)) {
+        const result = { ...target };
+        for (const key in source) {
+            if (source.hasOwnProperty(key)) {
+                if (typeof source[key] === 'object' && source[key] !== null && !Array.isArray(source[key]) &&
+                    typeof target[key] === 'object' && target[key] !== null && !Array.isArray(target[key])) {
+                    // Recursively merge nested objects
+                    result[key] = deepMergeExecution(target[key], source[key]);
+                }
+                else if (Array.isArray(target[key]) && Array.isArray(source[key])) {
+                    // Concatenate arrays
+                    result[key] = [...target[key], ...source[key]];
+                }
+                else {
+                    // Source takes precedence
+                    result[key] = source[key];
+                }
+            }
+        }
+        return result;
+    }
+    // Otherwise, source replaces target
+    return source;
+}
+/**
+ * Filter system/internal fields from execution object to prevent leakage into model context.
+ * Currently filters: bindingDefaultsDb
+ */
+function cleanseExecution(execution) {
+    if (!execution || typeof execution !== 'object' || Array.isArray(execution)) {
+        return execution;
+    }
+    const { bindingDefaultsDb, ...clean } = execution;
+    return clean;
+}
+function hasNarrixAttachmentShape(value) {
+    return !!(value &&
+        typeof value === "object" &&
+        "scoping" in value &&
+        "discovery" in value);
+}
+function coerceTaskMemoryNarrixToAttachment(taskMemoryNarrix) {
+    if (!Array.isArray(taskMemoryNarrix) || taskMemoryNarrix.length === 0)
+        return null;
+    const scopedEntries = taskMemoryNarrix.filter((entry) => !!entry && typeof entry === "object");
+    if (scopedEntries.length === 0)
+        return null;
+    const signals = scopedEntries.flatMap((entry) => Array.isArray(entry.signals) ? entry.signals : []);
+    const stories = scopedEntries.flatMap((entry) => Array.isArray(entry.stories) ? entry.stories : []);
+    if (signals.length === 0 && stories.length === 0)
+        return null;
+    return {
+        scoping: { signals, stories },
+        discovery: { signals: [], stories: [] },
+        meta: {
+            source: "taskMemory.narrix",
+            runCount: scopedEntries.length,
+        },
+    };
+}
+function resolveSynthesisMode(config) {
+    if (config.synthesisMode === "structured" || config.synthesisMode === "markdown") {
+        return config.synthesisMode;
+    }
+    return "markdown";
+}
+/**
+ * If parsed is an object with intermediateSteps, lift them to the response and remove from parsed
+ * so that response.intermediateSteps is the canonical place and parsed holds only task output.
+ */
+function liftIntermediateSteps(result) {
+    const parsed = result?.parsed;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return;
+    const steps = parsed.intermediateSteps;
+    if (!Array.isArray(steps) || steps.length === 0)
+        return;
+    const valid = steps.every((s) => typeof s === 'object' && s !== null && 'step' in s && 'id' in s && 'ok' in s);
+    if (!valid)
+        return;
+    result.intermediateSteps = steps;
+    const { intermediateSteps: _removed, ...rest } = parsed;
+    result.parsed = Object.keys(rest).length > 0 ? rest : undefined;
+}
+function extractExecutionMemoryFromResponse(result) {
+    if (result && typeof result === "object") {
+        if (result.executionMemory && typeof result.executionMemory === "object") {
+            return result.executionMemory;
+        }
+        if (result.parsed && typeof result.parsed === "object") {
+            const parsed = result.parsed;
+            if (parsed.executionMemory && typeof parsed.executionMemory === "object") {
+                return parsed.executionMemory;
+            }
+        }
+    }
+    return undefined;
+}
+function executionStrategiesSummaryFromKnobs(knobs) {
+    const r = knobs.resolvedExecutionStrategies;
+    return {
+        beforeKeys: r.orderedBefore.map((x) => x.strategyKey),
+        afterKeys: r.orderedAfter.map((x) => x.strategyKey),
+        ...(r.primaryOptimizer
+            ? { primaryOptimizerMaxIterations: r.effectivePrimaryOptimizerMaxIterations }
+            : {}),
+    };
+}
+function attachExecutionStateAndObservability(result, request, observability, runtimeKnobs) {
+    const responseExecution = extractExecutionMemoryFromResponse(result);
+    const finalExecutionMemory = {
+        ...(request.executionMemory ?? {}),
+        ...(responseExecution ?? {}),
+    };
+    result.executionMemory = finalExecutionMemory;
+    result.executionState = { executionMemory: finalExecutionMemory };
+    result.metadata = {
+        ...(result.metadata ?? {}),
+        synthesisEnabled: observability.synthesisEnabled,
+        effectiveExecutionPipeline: observability.effectiveExecutionPipeline,
+        synthesizedContextPresent: observability.synthesizedContextPresent,
+        mainContextSource: observability.mainContextSource,
+        detectedTemplateCores: observability.detectedTemplateCores ?? [],
+        synthesisMode: observability.synthesisMode,
+        ...(runtimeKnobs
+            ? {
+                narrixMode: runtimeKnobs.narrixMode,
+                inputStrategyKey: runtimeKnobs.inputStrategyKey,
+                executionStrategiesSummary: executionStrategiesSummaryFromKnobs(runtimeKnobs),
+            }
+            : {}),
+    };
+    // Alias for callers/docs that expect a `meta` block (same object as `metadata`).
+    result.meta = result.metadata;
+}
+function safeJson(value) {
+    return JSON.stringify(value ?? {}, null, 2);
+}
+function summarizeForOuter(value, maxChars) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "string") {
+        return value.length > maxChars ? value.slice(0, maxChars) + "…[truncated]" : value;
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    try {
+        const json = JSON.stringify(value);
+        if (typeof json !== "string")
+            return "[unserializable]";
+        if (json.length <= maxChars)
+            return value;
+        return json.slice(0, maxChars) + "…[truncated]";
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function extractDownstreamIdentity(result) {
+    if (!isRecord(result))
+        return undefined;
+    if (isRecord(result.identity))
+        return result.identity;
+    if (isRecord(result.metadata?.identity))
+        return result.metadata.identity;
+    if (isRecord(result.gatewayResponse?.identity))
+        return result.gatewayResponse.identity;
+    if (isRecord(result.enhancedResponse?.identity))
+        return result.enhancedResponse.identity;
+    return undefined;
+}
+function buildSynthesizerInputMaterial(strategy, resolveOpts) {
+    const selected = strategy ?? "policy";
+    if (selected === "execution-memory-only") {
+        const localMarkdown = safeJson({ executionMemory: resolveOpts.enrichedMemoryBundle.executionMemory ?? {} });
+        return { sourceMaterial: localMarkdown, parts: { localMarkdown, supportingMarkdown: "" } };
+    }
+    if (selected === "job-memory-only") {
+        const localMarkdown = safeJson({ jobMemory: resolveOpts.enrichedMemoryBundle.jobMemory ?? {} });
+        return { sourceMaterial: localMarkdown, parts: { localMarkdown, supportingMarkdown: "" } };
+    }
+    if (selected === "task-memory-only") {
+        const localMarkdown = safeJson({ taskMemory: resolveOpts.enrichedMemoryBundle.taskMemory ?? {} });
+        return { sourceMaterial: localMarkdown, parts: { localMarkdown, supportingMarkdown: "" } };
+    }
+    if (selected === "full-memory-bundle") {
+        const localMarkdown = safeJson({
+            jobMemory: resolveOpts.enrichedMemoryBundle.jobMemory ?? {},
+            taskMemory: resolveOpts.enrichedMemoryBundle.taskMemory ?? {},
+            executionMemory: resolveOpts.enrichedMemoryBundle.executionMemory ?? {},
+        });
+        return { sourceMaterial: localMarkdown, parts: { localMarkdown, supportingMarkdown: "" } };
+    }
+    const sourceMaterial = resolveSourceMaterial(resolveOpts);
+    const parts = resolveSourceMaterialParts(resolveOpts);
+    return { sourceMaterial, parts };
+}
+function safeResolveSynthesisQuestion(synthesisRequest, config, renderedPrompt) {
+    try {
+        const q = resolveSynthesisQuestion(synthesisRequest, config, renderedPrompt);
+        if (typeof q === "string")
+            return q;
+        return String(q ?? "");
+    }
+    catch {
+        // Utility tasks should not fail solely due to missing/invalid question resolution.
+        // If a template truly requires `question`, that will surface as a template resolution error elsewhere.
+        return "";
+    }
+}
+/**
+ * Task execution client for @exellix/ai-tasks.
+ *
+ * This class implements the canonical runTask algorithm:
+ * 1) Look up local handler by skillKey; if found, run it and return
+ * 2) Enrich memories at TASK level (using skillKey)
+ * 3) Generate TASK-level context markdown (using skillKey)
+ * 4) Execute via executor (no-enrichment primitive)
+ *
+ * This is a private package. We intentionally reuse @exellix/ai-skills directly,
+ * including its types and helpers. Naming leakage is acceptable.
+ */
+export class WorexClientTasks {
+    skillsClient;
+    executor;
+    constructor(skillsClient, executor) {
+        this.skillsClient = skillsClient;
+        this.executor = executor;
+    }
+    async runTask(input) {
+        const compiled = compileTaskConfigurationOnRunTaskRequest(input);
+        input = compiled.request;
+        emitRunTaskRequestWarnings(input);
+        assertRequiredRunSkillCorrelation(input);
+        assertValidSmartInputConfig(input.smartInput, input.skillKey);
+        const traceCollector = input.executionMode === "trace" ? createDebugTraceCollector() : null;
+        const withTrace = (result) => {
+            if (!traceCollector)
+                return result;
+            return {
+                ...result,
+                debugTrace: { tasks: traceCollector.tasks() },
+            };
+        };
+        // `@exellix/ai-skills` requires stable ids on each gateway request; callers may omit for simple runs.
+        const taskId = input.taskId?.trim() ? input.taskId : randomUUID();
+        const jobId = input.jobId?.trim() ? input.jobId : randomUUID();
+        input.taskId = taskId;
+        input.jobId = jobId;
+        // Optional activix tracking (non-fatal).
+        const ax = await getActivixClient().catch(() => null);
+        const correlationId = ax ? taskId : undefined;
+        const coreSkillId = input.coreSkillId;
+        const upstreamIdentity = isRecord(input.identity) ? input.identity : undefined;
+        const executingSkillId = coreSkillId ?? input.skillKey;
+        const effectiveIdentity = {
+            ...(upstreamIdentity ?? {}),
+            ...(upstreamIdentity?.taskId ? {} : { taskId }),
+            ...(upstreamIdentity?.skillId ? {} : { skillId: executingSkillId }),
+        };
+        const normalizedSmartInput = input.smartInput !== undefined && input.smartInput !== null
+            ? normalizeSmartInputConfig(input.smartInput)
+            : undefined;
+        let request = withDefaultDecisionValidation({
+            ...input,
+            identity: effectiveIdentity,
+            ...(normalizedSmartInput !== undefined ? { smartInput: normalizedSmartInput } : {}),
+        });
+        let xynthesizedPatchAccumulator;
+        const knobs = resolveRunTaskRuntimeKnobs(request);
+        const baseTraceMeta = () => ({
+            jobId,
+            taskId,
+            skillKey: input.skillKey,
+            executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+            narrixMode: knobs.narrixMode,
+            agentId: input.agentId,
+            graphId: input.graphId,
+            nodeId: input.nodeId,
+            prevNodeId: input.prevNodeId,
+            masterSkillId: input.masterSkillId,
+            masterSkillActivityId: input.masterSkillActivityId,
+            hasPipeline: Array.isArray(input.executionPipeline) && input.executionPipeline.length > 0,
+            hasNarrix: !!input.narrix,
+            hasNarrixInput: !!input.narrixInput,
+        });
+        const modelUsedFromResult = (result) => {
+            if (!result || typeof result !== "object")
+                return undefined;
+            const r = result;
+            const candidates = [
+                r?.metadata?.modelUsed,
+                r?.metadata?.model,
+                r?.gatewayResponse?.model,
+                r?.enhancedResponse?.model,
+                r?.model,
+            ];
+            const found = candidates.find((x) => typeof x === "string" && x.trim().length > 0);
+            return typeof found === "string" ? found : undefined;
+        };
+        const finalize = (result) => {
+            const downstreamIdentity = extractDownstreamIdentity(result);
+            const identityToReturn = downstreamIdentity ??
+                (upstreamIdentity ? effectiveIdentity : undefined);
+            if (identityToReturn) {
+                result.identity = identityToReturn;
+                result.metadata = { ...(result.metadata ?? {}), identity: identityToReturn };
+            }
+            const smartInputRenderResult = extractSmartInputRenderResult(result);
+            if (smartInputRenderResult) {
+                result.smartInputRenderResult = smartInputRenderResult;
+            }
+            result.metadata = {
+                ...result.metadata,
+                taskId,
+                ...(coreSkillId ? { skillId: coreSkillId } : {}),
+                identityPresent: (input.identity !== undefined),
+                ...(smartInputRenderResult ? { smartInputRenderResult } : {}),
+            };
+            const patchJob = xynthesizedPatchAccumulator?.job && Object.keys(xynthesizedPatchAccumulator.job).length > 0;
+            const patchTask = xynthesizedPatchAccumulator?.task && Object.keys(xynthesizedPatchAccumulator.task).length > 0;
+            const patchExecution = xynthesizedPatchAccumulator?.execution &&
+                Object.keys(xynthesizedPatchAccumulator.execution).length > 0;
+            if (patchJob || patchTask || patchExecution) {
+                result.xynthesizedPatch = xynthesizedPatchAccumulator;
+            }
+            return result;
+        };
+        const hasPipeline = Array.isArray(input.executionPipeline) && input.executionPipeline.length > 0;
+        const hasNarrix = !!input.narrix;
+        const hasNarrixInput = !!input.narrixInput;
+        // Activix 6+: correlation + task identity belong in `runContext`, not a parallel top-level `identity` field.
+        const runContext = {
+            ...effectiveIdentity,
+            sessionId: taskId,
+        };
+        const baseMeta = {
+            skillKey: input.skillKey,
+            executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+            narrixMode: knobs.narrixMode,
+            jobId: input.jobId,
+            agentId: input.agentId,
+            graphId: input.graphId,
+            nodeId: input.nodeId,
+            prevNodeId: input.prevNodeId,
+            masterSkillId: input.masterSkillId,
+            masterSkillActivityId: input.masterSkillActivityId,
+            runContext,
+            hasPipeline,
+            hasNarrix,
+            hasNarrixInput,
+        };
+        const runDirect = async (req, options) => {
+            const traceTask = {
+                taskType: "ai-task",
+                details: "direct execution (skills/gateway)",
+                metadata: {
+                    ...baseTraceMeta(),
+                    phase: "direct",
+                    overrideContextProvided: options?.overrideContext !== undefined,
+                    captureContextProvided: options?.captureContext !== undefined,
+                    synthesisContextAuthoritative: options?.synthesisContextAuthoritative === true,
+                    ...(traceCollector
+                        ? {
+                            smartInput: {
+                                paths: req.smartInput?.paths ?? [],
+                            },
+                        }
+                        : {}),
+                },
+            };
+            return traceWrap(traceCollector, traceTask, async () => withPhaseRecord({
+                ax,
+                correlationId,
+                phase: "direct",
+                meta: {
+                    ...baseMeta,
+                    outer: activixOuterTier({
+                        kind: "runTask.request",
+                        skillKey: req.skillKey,
+                        executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                        jobId: req.jobId,
+                        agentId: req.agentId,
+                        graphId: req.graphId,
+                        nodeId: req.nodeId,
+                        masterSkillId: req.masterSkillId,
+                        masterSkillActivityId: req.masterSkillActivityId,
+                        includeContextInPrompt: req.includeContextInPrompt === true,
+                        hasPipeline: Array.isArray(req.executionPipeline) && req.executionPipeline.length > 0,
+                        hasNarrix: !!req.narrix,
+                        hasNarrixInput: !!req.narrixInput,
+                        input: summarizeForOuter(req.input, 4_000),
+                    }, null, { phase: "direct" }),
+                    // pipeline MAIN vs DIRECT is still tracked as the same phase label ("direct")
+                    hasPipeline: !!req.executionPipeline,
+                    hasNarrix: !!req.narrix,
+                    hasNarrixInput: !!req.narrixInput,
+                    overrideContextProvided: options?.overrideContext !== undefined,
+                    captureContextProvided: options?.captureContext !== undefined,
+                    synthesisContextAuthoritative: options?.synthesisContextAuthoritative === true,
+                },
+                fn: async () => this._executeDirect(req, {
+                    ...options,
+                    validationCorrelationId: taskId,
+                    traceCollector,
+                }),
+                onSuccessUpdates: (result) => {
+                    const steps = result?.intermediateSteps;
+                    return {
+                        instructionVersion: result?.metadata?.instructionVersion,
+                        activityId: result?.metadata?.activityId,
+                        durationMs: result?.metadata?.durationMs,
+                        hasIntermediateSteps: Array.isArray(steps) && steps.length > 0,
+                        stepCount: Array.isArray(steps) ? steps.length : undefined,
+                        outer: activixOuterTier({
+                            kind: "runTask.request",
+                            skillKey: req.skillKey,
+                            executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                            jobId: req.jobId,
+                            agentId: req.agentId,
+                            graphId: req.graphId,
+                            nodeId: req.nodeId,
+                            masterSkillId: req.masterSkillId,
+                            masterSkillActivityId: req.masterSkillActivityId,
+                            includeContextInPrompt: req.includeContextInPrompt === true,
+                            hasPipeline: Array.isArray(req.executionPipeline) && req.executionPipeline.length > 0,
+                            hasNarrix: !!req.narrix,
+                            hasNarrixInput: !!req.narrixInput,
+                            input: summarizeForOuter(req.input, 4_000),
+                        }, {
+                            kind: "runTask.response",
+                            skillKey: result?.skillKey,
+                            // Keep this intentionally small; rawText / flexMd payloads can be huge.
+                            metadata: summarizeForOuter(result?.metadata, 4_000),
+                            parsed: summarizeForOuter(result?.parsed, 8_000),
+                        }, { phase: "direct" }),
+                    };
+                },
+            }), (result) => {
+                const modelUsed = modelUsedFromResult(result);
+                const r = result;
+                return {
+                    modelUsed: modelUsed ?? null,
+                    metadata: {
+                        activityId: r?.metadata?.activityId,
+                        instructionVersion: r?.metadata?.instructionVersion,
+                        durationMs: r?.metadata?.durationMs,
+                        outputValidation: r?.metadata?.outputValidation,
+                    },
+                };
+            });
+        };
+        const runMainWithExecutionStrategies = async (req, options) => {
+            const strat = knobs.resolvedExecutionStrategies;
+            let working = { ...req };
+            const prefixSteps = [];
+            for (let pi = 0; pi < strat.orderedBefore.length; pi++) {
+                const spec = strat.orderedBefore[pi];
+                if (spec.strategyKey !== "planner")
+                    continue;
+                const payload = buildExecutionStrategyRequestPayload({
+                    skillKey: working.skillKey,
+                    input: working.input,
+                    variables: working.variables,
+                    jobContext: working.jobContext,
+                    jobMemory: working.jobMemory,
+                    taskMemory: working.taskMemory,
+                    executionMemory: working.executionMemory,
+                    jobId: working.jobId,
+                    taskId: working.taskId,
+                    agentId: working.agentId,
+                    graphId: working.graphId,
+                    nodeId: working.nodeId,
+                    prevNodeId: working.prevNodeId,
+                    coreSkillId: working.coreSkillId,
+                    includeContextInPrompt: working.includeContextInPrompt,
+                });
+                const catalogDefaultFunctionId = resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, spec);
+                const plannerOut = await runPlannerFuncx({
+                    args: spec.args,
+                    requestPayload: payload,
+                    defaultFunctionId: catalogDefaultFunctionId,
+                });
+                working = applyPlannerOutputToRequest(working, plannerOut, pi);
+                prefixSteps.push({
+                    step: prefixSteps.length + 1,
+                    id: `executionStrategy.planner.${pi}`,
+                    ok: true,
+                    summary: "FuncX planner (execution/plan)",
+                    outputExcerpt: {
+                        hasInstructions: typeof plannerOut.instructions === "string",
+                        hasPrompt: typeof plannerOut.prompt === "string",
+                        variableKeys: plannerOut.variables ? Object.keys(plannerOut.variables).slice(0, 20) : [],
+                        functionIdSource: typeof spec.args?.functionId === "string"
+                            ? "invocation"
+                            : catalogDefaultFunctionId
+                                ? "catalog"
+                                : "code-default",
+                    },
+                });
+                if (traceCollector) {
+                    traceCollector.push({
+                        taskType: "pre-execution",
+                        details: "execution strategy planner (FuncX)",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "execution_strategy_planner",
+                            plannerIndex: pi,
+                        },
+                        modelUsed: null,
+                    });
+                }
+            }
+            const mergePrefixSteps = (result) => {
+                if (prefixSteps.length === 0)
+                    return result;
+                const existing = (result.intermediateSteps ?? []);
+                const shifted = existing.map((s, i) => ({ ...s, step: prefixSteps.length + i + 1 }));
+                result.intermediateSteps = [...prefixSteps, ...shifted];
+                return result;
+            };
+            const primary = strat.primaryOptimizer;
+            const maxIter = strat.effectivePrimaryOptimizerMaxIterations;
+            if (!primary) {
+                return mergePrefixSteps(await runDirect(working, options));
+            }
+            let last;
+            for (let iter = 0; iter < maxIter; iter++) {
+                last = await runDirect(working, options);
+                const mainSummary = {
+                    rawText: typeof last.rawText === "string" ? String(last.rawText).slice(0, 12_000) : undefined,
+                    parsed: last.parsed,
+                    skillKey: last.skillKey,
+                    metadata: last.metadata ? summarizeForOuter(last.metadata, 6_000) : undefined,
+                };
+                const evalOut = await runOptimizerFuncx({
+                    args: primary.args,
+                    defaultFunctionId: resolveSafeExecutionStrategyCatalogDefaultFunctionId(req.executionStrategyCatalogItems, primary),
+                    requestPayload: buildExecutionStrategyRequestPayload({
+                        skillKey: working.skillKey,
+                        input: working.input,
+                        variables: working.variables,
+                        jobContext: working.jobContext,
+                        jobMemory: working.jobMemory,
+                        taskMemory: working.taskMemory,
+                        executionMemory: working.executionMemory,
+                        jobId: working.jobId,
+                        taskId: working.taskId,
+                        agentId: working.agentId,
+                        graphId: working.graphId,
+                        nodeId: working.nodeId,
+                        prevNodeId: working.prevNodeId,
+                        coreSkillId: working.coreSkillId,
+                        includeContextInPrompt: working.includeContextInPrompt,
+                    }),
+                    mainResultSummary: mainSummary,
+                    iterationIndex: iter,
+                });
+                if (traceCollector) {
+                    traceCollector.push({
+                        taskType: "ai-task",
+                        details: "execution strategy optimizer (FuncX)",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "execution_strategy_optimizer",
+                            iterationIndex: iter,
+                            satisfied: evalOut.satisfied === true,
+                        },
+                        modelUsed: modelUsedFromResult(last) ?? null,
+                    });
+                }
+                if (evalOut.satisfied) {
+                    return mergePrefixSteps(last);
+                }
+                if (iter === maxIter - 1) {
+                    return mergePrefixSteps(last);
+                }
+                working = applyOptimizerFeedbackToRequest(working, evalOut, iter + 1);
+            }
+            return mergePrefixSteps(last);
+        };
+        // NARRIX task-level pre-processor + structured handler: `narrixMode` (+ inference) via `resolveRunTaskRuntimeKnobs`.
+        if (knobs.narrixMode === "preprocessor" && request.narrix) {
+            const narrixCfg = request.narrix;
+            await traceWrap(traceCollector, {
+                taskType: "pre-execution",
+                details: "narrix preprocessor",
+                metadata: {
+                    ...baseTraceMeta(),
+                    phase: "narrix",
+                    datasetId: narrixCfg.datasetId,
+                    attachToField: narrixCfg.attachToField ?? "_narrix",
+                    enableWebScope: narrixCfg.enableWebScope === true,
+                },
+            }, async () => withPhaseRecord({
+                ax,
+                correlationId,
+                phase: "narrix",
+                meta: {
+                    ...baseMeta,
+                    narrixAttachToField: narrixCfg.attachToField ?? "_narrix",
+                    outer: activixOuterTier({
+                        kind: "narrix.preProcessor.request",
+                        datasetId: narrixCfg.datasetId,
+                        attachToField: narrixCfg.attachToField ?? "_narrix",
+                        enableWebScope: narrixCfg.enableWebScope === true,
+                        webScoping: narrixCfg.webScoping ? summarizeForOuter(narrixCfg.webScoping, 2_000) : undefined,
+                        requestInput: summarizeForOuter(request.input, 4_000),
+                    }, null, { phase: "narrix" }),
+                },
+                fn: async () => {
+                    const adaptResult = adaptMemoryToNarrixInput({
+                        datasetId: narrixCfg.datasetId,
+                        mediumHint: "record",
+                        memory: {
+                            jobMemory: request.jobMemory,
+                            executionMemory: request.executionMemory,
+                            input: request.input,
+                        },
+                    }, {
+                        record: {
+                            minKeys: 1,
+                            preferPaths: [
+                                "executionMemory.input.raw",
+                                "executionMemory.inputs.*.raw",
+                                "jobMemory.record",
+                                "jobMemory.currentRecord",
+                                "executionMemory.input.record",
+                                "executionMemory.record",
+                                "taskMemory.currentRecord",
+                                "*.currentRecord",
+                                "*.record",
+                            ],
+                        },
+                    });
+                    if (!adaptResult.ok) {
+                        const attempted = adaptResult.attempted?.length ? ` Attempted: ${adaptResult.attempted.join(", ")}.` : "";
+                        const summary = adaptResult.foundSummary ? ` Seen: ${adaptResult.foundSummary}` : "";
+                        throw new Error(`NARRIX pre-processor: no usable input. ${adaptResult.message}.${attempted}${summary}`);
+                    }
+                    const ctx = {
+                        skillKey: request.skillKey,
+                        jobMemory: request.jobMemory,
+                        taskMemory: request.taskMemory,
+                        executionMemory: request.executionMemory,
+                        variables: input.variables,
+                        xynthesized: request.xynthesized,
+                        smartInput: request.smartInput,
+                        jobId: input.jobId,
+                        taskId: request.taskId,
+                        agentId: input.agentId,
+                        graphId: input.graphId,
+                        nodeId: input.nodeId,
+                        prevNodeId: input.prevNodeId,
+                        coreSkillId: input.coreSkillId,
+                        masterSkillId: request.masterSkillId,
+                        masterSkillActivityId: request.masterSkillActivityId,
+                    };
+                    const narrixResult = await narrixRunHandler({ input: adaptResult.narrixInput, ctx });
+                    if (!narrixResult.ok) {
+                        const fail = narrixResult;
+                        throw new Error(`NARRIX pre-processor failed: ${fail.error}${fail.message ? ` - ${fail.message}` : ""}`);
+                    }
+                    const attachment = buildNarrixAttachment(narrixResult);
+                    const attachToField = narrixCfg.attachToField ?? "_narrix";
+                    let webContextEntry = undefined;
+                    let webContextAvailable;
+                    let webContextReason;
+                    const externalWebMdPreNarrix = typeof request.executionMemory?.webContextMarkdown === "string" &&
+                        request.executionMemory.webContextMarkdown.trim().length > 0;
+                    const skipWebScopeForExternalMd = narrixCfg.skipWebScopeWhenExternalWebMarkdownPresent === true && externalWebMdPreNarrix;
+                    if (narrixCfg.enableWebScope === true && !skipWebScopeForExternalMd) {
+                        const successResult = narrixResult;
+                        const entity = adaptResult.narrixInput.medium === "record"
+                            ? adaptResult.narrixInput.record
+                            : undefined;
+                        const scopeFields = resolveWebScopeQuestionAndTemplates({
+                            narrix: narrixCfg,
+                            requestInput: request.input,
+                            successResult,
+                            entity,
+                        });
+                        const webScopeOpts = hasNonEmptyWebScoping(narrixCfg.webScoping)
+                            ? { scoping: narrixCfg.webScoping }
+                            : undefined;
+                        const activixPatch = webScopeActivixCorrelationPatch({
+                            jobId: request.jobId,
+                            taskId: request.taskId,
+                            sessionId: request.taskId,
+                        });
+                        const packQs = scopeFields.packQuestions;
+                        if (Array.isArray(packQs) && packQs.length > 0) {
+                            webContextEntry = await runWebScopeQuestionPack({
+                                datasetId: narrixCfg.datasetId,
+                                subjectId: successResult.entity.entityKey,
+                                entityKind: successResult.entity.entityKind,
+                                entity,
+                                cni: successResult.cni,
+                                ...activixPatch,
+                                questions: packQs,
+                            }, webScopeOpts);
+                        }
+                        else {
+                            const { packQuestions: _pq, ...genericScope } = scopeFields;
+                            void _pq;
+                            webContextEntry = await runWebScope({
+                                datasetId: narrixCfg.datasetId,
+                                subjectId: successResult.entity.entityKey,
+                                entityKind: successResult.entity.entityKind,
+                                entity,
+                                cni: successResult.cni,
+                                ...activixPatch,
+                                ...genericScope,
+                            }, webScopeOpts);
+                        }
+                        if (webContextEntry && typeof webContextEntry === "object") {
+                            const wc = webContextEntry;
+                            webContextAvailable = typeof wc.available === "boolean" ? wc.available : undefined;
+                            webContextReason = typeof wc.reason === "string" ? wc.reason : undefined;
+                        }
+                        if (webContextEntry &&
+                            typeof webContextEntry === "object" &&
+                            webContextEntry.available === false) {
+                            const miss = webContextEntry;
+                            if (process.env.NARRIX_DEBUG === "1") {
+                                // eslint-disable-next-line no-console
+                                console.warn("[NARRIX_WEB_SCOPE] miss:", miss.reason, miss.error ?? "");
+                            }
+                            if (traceCollector) {
+                                traceCollector.push({
+                                    taskType: "pre-execution",
+                                    details: "narrix web scope miss",
+                                    metadata: {
+                                        ...baseTraceMeta(),
+                                        phase: "narrix",
+                                        webContext: { available: false, reason: miss.reason, error: miss.error },
+                                    },
+                                    modelUsed: null,
+                                });
+                            }
+                        }
+                    }
+                    request = {
+                        ...request,
+                        executionMemory: {
+                            ...(request.executionMemory || {}),
+                            [attachToField]: attachment,
+                            ...(webContextEntry !== undefined ? { webContext: webContextEntry } : {}),
+                        },
+                        jobMemory: request.jobMemory ? { ...request.jobMemory, _narrix: attachment } : { _narrix: attachment },
+                    };
+                    const scopingSignalsCount = Array.isArray(attachment?.scoping?.signals) ? attachment.scoping.signals.length : undefined;
+                    const scopingStoriesCount = Array.isArray(attachment?.scoping?.stories) ? attachment.scoping.stories.length : undefined;
+                    const discoverySignalsCount = Array.isArray(attachment?.discovery?.signals) ? attachment.discovery.signals.length : undefined;
+                    const discoveryStoriesCount = Array.isArray(attachment?.discovery?.stories) ? attachment.discovery.stories.length : undefined;
+                    const entityKey = narrixResult?.entity?.entityKey;
+                    const entityKind = narrixResult?.entity?.entityKind;
+                    return {
+                        datasetId: narrixCfg.datasetId,
+                        attachToField,
+                        enableWebScope: narrixCfg.enableWebScope === true,
+                        webContextAvailable,
+                        webContextReason,
+                        attachmentMeta: isRecord(attachment?.meta) ? attachment.meta : undefined,
+                        scopingSignalsCount,
+                        scopingStoriesCount,
+                        discoverySignalsCount,
+                        discoveryStoriesCount,
+                        entityKey: typeof entityKey === "string" ? entityKey : undefined,
+                        entityKind: typeof entityKind === "string" ? entityKind : undefined,
+                        medium: typeof adaptResult.narrixInput?.medium === "string" ? adaptResult.narrixInput.medium : undefined,
+                    };
+                },
+                onSuccessUpdates: (r) => ({
+                    outer: activixOuterTier({
+                        kind: "narrix.preProcessor.request",
+                        datasetId: narrixCfg.datasetId,
+                        attachToField: narrixCfg.attachToField ?? "_narrix",
+                        enableWebScope: narrixCfg.enableWebScope === true,
+                        webScoping: narrixCfg.webScoping ? summarizeForOuter(narrixCfg.webScoping, 2_000) : undefined,
+                        requestInput: summarizeForOuter(request.input, 4_000),
+                    }, {
+                        kind: "narrix.preProcessor.result",
+                        datasetId: r.datasetId,
+                        attachToField: r.attachToField,
+                        enableWebScope: r.enableWebScope,
+                        entity: r.entityKey ? { entityKey: r.entityKey, entityKind: r.entityKind } : undefined,
+                        counts: {
+                            scopingSignals: r.scopingSignalsCount,
+                            scopingStories: r.scopingStoriesCount,
+                            discoverySignals: r.discoverySignalsCount,
+                            discoveryStories: r.discoveryStoriesCount,
+                        },
+                        webContext: r.enableWebScope
+                            ? { available: r.webContextAvailable, reason: r.webContextReason }
+                            : undefined,
+                        attachmentMeta: r.attachmentMeta,
+                    }, { phase: "narrix" }),
+                }),
+            }));
+        }
+        // Structured Narrix (`narrixInput`): same enrichment as legacy `narrix-then-direct`, but runs before local tasks / pipeline PRE.
+        if (knobs.narrixMode === "handler") {
+            if (!request.narrixInput) {
+                throw new Error(`narrixMode "handler" requires narrixInput. ` +
+                    `Provide { medium, datasetId, ... } or { $path: "jobMemory.currentRecord" } on the request.`);
+            }
+            const resolvedNarrixInput = resolveNarrixInput(request.narrixInput, request.jobMemory);
+            if (!resolvedNarrixInput) {
+                throw new Error(`narrixMode "handler": narrixInput could not be resolved. ` +
+                    `Ensure it has medium and datasetId, or that $path points to a valid object in jobMemory.`);
+            }
+            let narrixThenDirectPhaseRecordId = null;
+            if (ax && correlationId) {
+                try {
+                    narrixThenDirectPhaseRecordId = (await ax.startRecord({
+                        correlationId,
+                        phase: "narrix_then_direct",
+                        ...baseMeta,
+                        narrixDatasetId: resolvedNarrixInput.datasetId,
+                        narrixMedium: resolvedNarrixInput.medium,
+                        outer: activixOuterTier({
+                            kind: "narrixThenDirect.request",
+                            skillKey: request.skillKey,
+                            jobId: request.jobId,
+                            agentId: request.agentId,
+                            narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
+                        }, null, { phase: "narrix_then_direct" }),
+                    })).recordId;
+                }
+                catch {
+                    narrixThenDirectPhaseRecordId = null;
+                }
+            }
+            try {
+                const narrixStarted = Date.now();
+                const narrixHandlerCtx = {
+                    skillKey: request.skillKey,
+                    jobMemory: request.jobMemory,
+                    taskMemory: request.taskMemory,
+                    executionMemory: request.executionMemory,
+                    variables: request.variables,
+                    xynthesized: request.xynthesized,
+                    smartInput: request.smartInput,
+                    jobId: request.jobId,
+                    taskId: request.taskId,
+                    agentId: request.agentId,
+                    graphId: request.graphId,
+                    nodeId: request.nodeId,
+                    prevNodeId: request.prevNodeId,
+                    coreSkillId: request.coreSkillId,
+                    masterSkillId: request.masterSkillId,
+                    masterSkillActivityId: request.masterSkillActivityId,
+                };
+                const narrixResult = await traceWrap(traceCollector, {
+                    taskType: "pre-execution",
+                    details: "narrix structured handler (narrixInput)",
+                    metadata: {
+                        ...baseTraceMeta(),
+                        phase: "narrix_then_direct",
+                        datasetId: resolvedNarrixInput.datasetId,
+                        medium: resolvedNarrixInput.medium,
+                    },
+                }, async () => narrixRunHandler({ input: resolvedNarrixInput, ctx: narrixHandlerCtx }), (r) => ({
+                    metadata: { ok: r?.ok === true },
+                    modelUsed: null,
+                }));
+                const narrixDurationMs = Date.now() - narrixStarted;
+                if (!narrixResult.ok) {
+                    const fail = narrixResult;
+                    if (ax && correlationId && narrixThenDirectPhaseRecordId) {
+                        await ax
+                            .failRecord(narrixThenDirectPhaseRecordId, new Error(`Narrix handler failed: ${fail.error}${fail.message ? ` - ${fail.message}` : ""}`), {
+                            errorMessage: fail.message ? `${fail.error} - ${fail.message}` : fail.error,
+                            errorCode: fail.code,
+                            narrixDurationMs,
+                        })
+                            .catch(() => undefined);
+                    }
+                    return withTrace({
+                        skillKey: request.skillKey,
+                        rawText: JSON.stringify(narrixResult, null, 2),
+                        flexMd: { frame: "narrixThenDirect.v1", payloads: { narrix: JSON.stringify(narrixResult) } },
+                        parsed: {
+                            ok: false,
+                            error: narrixResult.error,
+                            phase: "narrix",
+                            message: narrixResult.message,
+                        },
+                        metadata: {
+                            instructionVersion: "narrix-then-direct",
+                            narrix: { ...narrixResult, durationMs: narrixDurationMs },
+                            narrixMode: knobs.narrixMode,
+                            inputStrategyKey: knobs.inputStrategyKey,
+                            executionStrategiesSummary: executionStrategiesSummaryFromKnobs(knobs),
+                        },
+                    });
+                }
+                const filteredEntry = applyNarrixScope(narrixResult, request.narrixScope);
+                const existingNarrix = Array.isArray(request.taskMemory?.narrix)
+                    ? request.taskMemory.narrix
+                    : [];
+                const updatedTaskMemory = {
+                    ...(request.taskMemory ?? {}),
+                    narrix: [...existingNarrix, filteredEntry],
+                };
+                const skillInput = typeof request.input === "object" && request.input !== null
+                    ? { ...request.input, narrixContext: filteredEntry }
+                    : { narrixContext: filteredEntry };
+                request = {
+                    ...request,
+                    taskMemory: updatedTaskMemory,
+                    input: skillInput,
+                };
+                if (ax && correlationId && narrixThenDirectPhaseRecordId) {
+                    await ax
+                        .completeRecord(narrixThenDirectPhaseRecordId, {
+                        narrixDurationMs,
+                        outer: activixOuterTier({
+                            kind: "narrixThenDirect.request",
+                            skillKey: request.skillKey,
+                            jobId: request.jobId,
+                            agentId: request.agentId,
+                            narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
+                        }, {
+                            kind: "narrixThenDirect.result",
+                            ok: true,
+                            durationMs: narrixDurationMs,
+                        }, { phase: "narrix_then_direct" }),
+                    })
+                        .catch(() => undefined);
+                }
+            }
+            catch (error) {
+                if (ax && correlationId && narrixThenDirectPhaseRecordId) {
+                    await ax
+                        .failRecord(narrixThenDirectPhaseRecordId, error instanceof Error ? error : new Error(String(error)), {
+                        errorMessage: error instanceof Error ? error.message : String(error),
+                        errorCode: error?.code,
+                        outer: activixOuterTier({
+                            kind: "narrixThenDirect.request",
+                            skillKey: request.skillKey,
+                            jobId: request.jobId,
+                            agentId: request.agentId,
+                            narrixInput: summarizeForOuter(resolvedNarrixInput, 6_000),
+                        }, {
+                            kind: "narrixThenDirect.error",
+                            message: error instanceof Error ? error.message : String(error),
+                        }, { phase: "narrix_then_direct" }),
+                    })
+                        .catch(() => undefined);
+                }
+                throw error;
+            }
+        }
+        // Local task dispatch: if a handler is registered, run it and return (no enrichment)
+        const handler = getLocalTask(request.skillKey);
+        if (handler) {
+            const result = await traceWrap(traceCollector, {
+                taskType: "pre-execution",
+                details: "local task handler",
+                metadata: {
+                    ...baseTraceMeta(),
+                    phase: "local",
+                    localSkillKey: request.skillKey,
+                },
+                modelUsed: null,
+            }, async () => withPhaseRecord({
+                ax,
+                correlationId,
+                phase: "local",
+                meta: {
+                    ...baseMeta,
+                    localSkillKey: request.skillKey,
+                    outer: activixOuterTier({
+                        kind: "localTask.request",
+                        skillKey: request.skillKey,
+                        jobId: request.jobId,
+                        agentId: request.agentId,
+                        input: summarizeForOuter(request.input, 4_000),
+                    }, null, { phase: "local" }),
+                },
+                fn: async () => {
+                    const started = Date.now();
+                    const ctx = {
+                        skillKey: request.skillKey,
+                        jobMemory: request.jobMemory,
+                        taskMemory: request.taskMemory,
+                        executionMemory: request.executionMemory,
+                        variables: input.variables,
+                        xynthesized: request.xynthesized,
+                        smartInput: request.smartInput,
+                        jobId: input.jobId,
+                        taskId: input.taskId,
+                        agentId: input.agentId,
+                        graphId: input.graphId,
+                        nodeId: input.nodeId,
+                        prevNodeId: input.prevNodeId,
+                        coreSkillId: input.coreSkillId,
+                        masterSkillId: request.masterSkillId,
+                        masterSkillActivityId: request.masterSkillActivityId,
+                    };
+                    const value = await handler({ input: request.input, ctx });
+                    const durationMs = Date.now() - started;
+                    let parsed = value;
+                    let intermediateSteps;
+                    if (value !== null &&
+                        typeof value === "object" &&
+                        !Array.isArray(value) &&
+                        "intermediateSteps" in value) {
+                        const steps = value.intermediateSteps;
+                        if (Array.isArray(steps) &&
+                            steps.length > 0 &&
+                            steps.every((s) => typeof s === "object" && s !== null && "step" in s && "id" in s && "ok" in s)) {
+                            intermediateSteps = steps;
+                            const { intermediateSteps: _removed, ...rest } = value;
+                            parsed = (Object.keys(rest).length > 0 ? rest : undefined);
+                        }
+                    }
+                    const response = {
+                        skillKey: request.skillKey,
+                        rawText: JSON.stringify(value, null, 2),
+                        flexMd: {
+                            frame: "localTask.v1",
+                            payloads: { value: JSON.stringify(value, null, 2) },
+                        },
+                        parsed,
+                        metadata: {
+                            instructionVersion: "local",
+                            activityId: undefined,
+                            durationMs,
+                            localSkillKey: request.skillKey,
+                        },
+                    };
+                    if (intermediateSteps)
+                        response.intermediateSteps = intermediateSteps;
+                    if (isStrictDecisionTask(request)) {
+                        const parsedMissing = response.parsed === undefined || response.parsed === null;
+                        if (parsedMissing) {
+                            throw new Error(`Decision task "${request.skillKey}" did not return response.parsed`);
+                        }
+                    }
+                    const outputValidation = request.outputValidation;
+                    if (outputValidation?.schema) {
+                        const validateWhenMissing = outputValidation.validateWhenMissing !== false;
+                        if (validateWhenMissing || response.parsed !== undefined) {
+                            const vr = validateParsedOutput(response.parsed, outputValidation.schema);
+                            vr.correlationId = taskId;
+                            response.metadata = { ...response.metadata, outputValidation: vr };
+                            if (!vr.ok && (outputValidation.mode ?? "fail") === "fail") {
+                                throw new Error(`outputValidation failed for skillKey ${request.skillKey}: ` +
+                                    vr.errors.map((e) => `${e.path} ${e.message}`).join("; "));
+                            }
+                            if (!vr.ok && (outputValidation.mode ?? "fail") === "warn") {
+                            }
+                        }
+                    }
+                    return response;
+                },
+                onSuccessUpdates: (result) => {
+                    const steps = result?.intermediateSteps;
+                    return {
+                        localSkillKey: result?.metadata?.localSkillKey,
+                        durationMs: result?.metadata?.durationMs,
+                        hasIntermediateSteps: Array.isArray(steps) && steps.length > 0,
+                        stepCount: Array.isArray(steps) ? steps.length : undefined,
+                        outer: activixOuterTier({
+                            kind: "localTask.request",
+                            skillKey: request.skillKey,
+                            jobId: request.jobId,
+                            agentId: request.agentId,
+                            input: summarizeForOuter(request.input, 4_000),
+                        }, {
+                            kind: "localTask.response",
+                            skillKey: result?.skillKey,
+                            metadata: summarizeForOuter(result?.metadata, 4_000),
+                            parsed: summarizeForOuter(result?.parsed, 8_000),
+                        }, { phase: "local" }),
+                    };
+                },
+            }), (r) => ({
+                metadata: {
+                    durationMs: r?.metadata?.durationMs,
+                },
+                modelUsed: null,
+            }));
+            return withTrace(finalize(result));
+        }
+        // Execution pipeline: when request.executionPipeline is set, run PRE steps then main then POST
+        const pipeline = request.executionPipeline;
+        if (pipeline && Array.isArray(pipeline) && pipeline.length > 0) {
+            const mainSteps = pipeline.filter((s) => s.phase === "main");
+            if (mainSteps.length !== 1) {
+                throw new Error(`executionPipeline must have exactly one step with phase "main"; got ${mainSteps.length}. skillKey: ${request.skillKey}`);
+            }
+            const preSteps = pipeline.filter((s) => s.phase === "pre");
+            let overrideContext;
+            let synthesizedArtifact;
+            let detectedTemplateCores = [];
+            // Aggregated trace-mode-only LlmCallObservations from PRE synthesis (markdown/structured/questionDriven).
+            // Lifted into `result.metadata.synthesizedContextLlmCalls` once the pipeline finishes.
+            const aggregatedSynthLlmCalls = [];
+            for (const step of preSteps) {
+                if (step.type !== SYNTHESIZED_CONTEXT) {
+                    throw new Error(`executionPipeline: unsupported PRE step type "${String(step.type)}". Only "${SYNTHESIZED_CONTEXT}" (Xynthesis synthesized-context) is supported.`);
+                }
+                {
+                    const config = (step.config ?? {});
+                    if (request.includeContextInPrompt !== true && config.autoEnableContext !== true) {
+                        throw new Error("synthesized-context PRE step requires includeContextInPrompt: true or synthesisConfig.autoEnableContext: true");
+                    }
+                    const reqWithContext = { ...request, includeContextInPrompt: true };
+                    const cachedSynth = request.executionMemory?.synthesizedContext;
+                    const preStepResult = config.reuseCachedSynthesizedContext === true &&
+                        cachedSynth &&
+                        reuseableSynthesizedArtifact(cachedSynth)
+                        ? {
+                            contextMarkdown: contextMarkdownFromArtifact(cachedSynth),
+                            artifact: cachedSynth,
+                            synthesizedInput: request.executionMemory?.synthesizedInput,
+                        }
+                        : await traceWrap(traceCollector, {
+                            taskType: "pre-execution",
+                            details: "synthesized-context pre step",
+                            metadata: {
+                                ...baseTraceMeta(),
+                                phase: "pipeline_pre",
+                                preStepType: "synthesized-context",
+                                synthesisMode: resolveSynthesisMode(config),
+                                reusedCache: false,
+                                ...(config.xynthesizedOutput && traceCollector
+                                    ? {
+                                        xynthesized: {
+                                            inputPathsUsed: [...(config.memoryPaths ?? [])],
+                                            outputDestination: config.xynthesizedOutput.destination,
+                                            outputKey: config.xynthesizedOutput.outputKey,
+                                            patchKeys: [config.xynthesizedOutput.outputKey],
+                                        },
+                                        smartInput: {
+                                            paths: reqWithContext.smartInput?.paths ?? [],
+                                        },
+                                    }
+                                    : traceCollector
+                                        ? {
+                                            smartInput: {
+                                                paths: reqWithContext.smartInput?.paths ?? [],
+                                            },
+                                        }
+                                        : {}),
+                            },
+                        }, async () => withPhaseRecord({
+                            ax,
+                            correlationId,
+                            phase: "pipeline_pre",
+                            meta: {
+                                ...baseMeta,
+                                preStepType: "synthesized-context",
+                                outer: activixOuterTier({
+                                    kind: "pipelinePre.synthesizedContext.request",
+                                    skillKey: reqWithContext.skillKey,
+                                    jobId: reqWithContext.jobId,
+                                    agentId: reqWithContext.agentId,
+                                    contextSourcePolicy: config?.contextSourcePolicy,
+                                    synthesisMode: resolveSynthesisMode(config),
+                                    input: summarizeForOuter(reqWithContext.input, 4_000),
+                                }, null, { phase: "pipeline_pre" }),
+                            },
+                            fn: async () => this._runSynthesizedContextPreStep(reqWithContext, config, traceCollector),
+                            onSuccessUpdates: (r) => ({
+                                outer: activixOuterTier({
+                                    kind: "pipelinePre.synthesizedContext.request",
+                                    skillKey: reqWithContext.skillKey,
+                                    jobId: reqWithContext.jobId,
+                                    agentId: reqWithContext.agentId,
+                                    contextSourcePolicy: config?.contextSourcePolicy,
+                                    synthesisMode: resolveSynthesisMode(config),
+                                    input: summarizeForOuter(reqWithContext.input, 4_000),
+                                }, {
+                                    kind: "pipelinePre.synthesizedContext.result",
+                                    contextMarkdown: summarizeForOuter(r.contextMarkdown, 8_000),
+                                    artifact: r.artifact
+                                        ? {
+                                            mode: r.artifact.mode,
+                                            templateCores: r.artifact?.templateCores ?? [],
+                                            question: typeof r.artifact?.question === "string"
+                                                ? summarizeForOuter(r.artifact.question, 2_000)
+                                                : undefined,
+                                        }
+                                        : undefined,
+                                }, { phase: "pipeline_pre" }),
+                            }),
+                        }), (r) => ({
+                            metadata: {
+                                synthesizedContextChars: typeof r.contextMarkdown === "string" ? r.contextMarkdown.length : 0,
+                                ...(config.xynthesizedOutput && traceCollector
+                                    ? {
+                                        xynthesized: {
+                                            inputPathsUsed: [...(config.memoryPaths ?? [])],
+                                            outputDestination: config.xynthesizedOutput.destination,
+                                            outputKey: config.xynthesizedOutput.outputKey,
+                                            patchKeys: [config.xynthesizedOutput.outputKey],
+                                        },
+                                    }
+                                    : {}),
+                            },
+                        }));
+                    overrideContext = preStepResult.contextMarkdown;
+                    synthesizedArtifact = preStepResult.artifact;
+                    if (traceCollector && preStepResult.synthesizedContextLlmCalls) {
+                        aggregatedSynthLlmCalls.push(...preStepResult.synthesizedContextLlmCalls);
+                    }
+                    if (synthesizedArtifact) {
+                        detectedTemplateCores = synthesizedArtifact?.templateCores ?? [];
+                    }
+                    const xynthOut = config.xynthesizedOutput;
+                    const writeLegacyToExecutionMemory = !xynthOut || xynthOut.alsoWriteLegacySynthesizedContext !== false;
+                    if (synthesizedArtifact && writeLegacyToExecutionMemory) {
+                        request = {
+                            ...request,
+                            executionMemory: {
+                                ...(request.executionMemory ?? {}),
+                                synthesizedContext: synthesizedArtifact,
+                                ...(preStepResult.synthesizedInput ? { synthesizedInput: preStepResult.synthesizedInput } : {}),
+                            },
+                        };
+                    }
+                    if (xynthOut) {
+                        const synthesizedResult = synthesizedResultForXynthesizedPatch(synthesizedArtifact, preStepResult.contextMarkdown);
+                        const { nextXynthesized, patchSlice } = applyXynthesizedOutputWrite(request.xynthesized, xynthOut, synthesizedResult);
+                        request = { ...request, xynthesized: nextXynthesized };
+                        xynthesizedPatchAccumulator = mergeXynthesizedPatchSlices(xynthesizedPatchAccumulator, patchSlice);
+                    }
+                    if (traceCollector &&
+                        config.reuseCachedSynthesizedContext === true &&
+                        cachedSynth &&
+                        reuseableSynthesizedArtifact(cachedSynth)) {
+                        traceCollector.push({
+                            taskType: "pre-execution",
+                            details: "synthesized-context pre step (reused cached artifact)",
+                            metadata: {
+                                ...baseTraceMeta(),
+                                phase: "pipeline_pre",
+                                preStepType: "synthesized-context",
+                                synthesisMode: resolveSynthesisMode(config),
+                                reusedCache: true,
+                                ...(config.xynthesizedOutput
+                                    ? {
+                                        xynthesized: {
+                                            inputPathsUsed: [...(config.memoryPaths ?? [])],
+                                            outputDestination: config.xynthesizedOutput.destination,
+                                            outputKey: config.xynthesizedOutput.outputKey,
+                                            patchKeys: [config.xynthesizedOutput.outputKey],
+                                        },
+                                        smartInput: {
+                                            paths: request.smartInput?.paths ?? [],
+                                        },
+                                    }
+                                    : {
+                                        smartInput: {
+                                            paths: request.smartInput?.paths ?? [],
+                                        },
+                                    }),
+                            },
+                            modelUsed: null,
+                        });
+                    }
+                    break;
+                }
+            }
+            const synthesizedFromExecution = request.executionMemory?.synthesizedContext &&
+                typeof request.executionMemory.synthesizedContext === "object";
+            const mainContextSource = synthesizedFromExecution ? "synthesizedContext" : "unsynthesized";
+            if (mainContextSource === "synthesizedContext") {
+                const artifact = request.executionMemory?.synthesizedContext;
+                if (artifact && typeof artifact === "object" && typeof artifact.contextMarkdown === "string") {
+                    overrideContext = artifact.contextMarkdown;
+                }
+            }
+            const postSteps = pipeline.filter((s) => s.phase === "post");
+            const observability = {
+                synthesisEnabled: preSteps.some((s) => s.type === SYNTHESIZED_CONTEXT),
+                effectiveExecutionPipeline: pipeline,
+                synthesizedContextPresent: synthesizedFromExecution,
+                mainContextSource,
+                detectedTemplateCores,
+                synthesisMode: synthesizedArtifact?.mode === "markdown" || synthesizedArtifact?.mode === "structured"
+                    ? synthesizedArtifact.mode
+                    : undefined,
+            };
+            const directOpts = {
+                overrideContext,
+                synthesisContextAuthoritative: mainContextSource === "synthesizedContext",
+            };
+            if (postSteps.length === 0) {
+                const result = finalize(await runMainWithExecutionStrategies(request, directOpts));
+                if (overrideContext !== undefined) {
+                    const synthesisStep = {
+                        step: 1,
+                        id: "synthesis",
+                        ok: true,
+                        summary: "context synthesized",
+                        outputExcerpt: {
+                            mainContextSource,
+                            synthesizedContextPresent: observability.synthesizedContextPresent,
+                            detectedTemplateCores: observability.detectedTemplateCores ?? [],
+                        },
+                    };
+                    const existingSteps = result.intermediateSteps ?? [];
+                    result.intermediateSteps = [
+                        synthesisStep,
+                        ...existingSteps.map((s, i) => ({ ...s, step: i + 2 })),
+                    ];
+                }
+                attachExecutionStateAndObservability(result, request, observability);
+                if (traceCollector && aggregatedSynthLlmCalls.length > 0) {
+                    result.metadata = {
+                        ...(result.metadata ?? {}),
+                        synthesizedContextLlmCalls: aggregatedSynthLlmCalls,
+                    };
+                }
+                return withTrace(result);
+            }
+            const capture = { contextMarkdown: "" };
+            let result = finalize(await runMainWithExecutionStrategies(request, { ...directOpts, captureContext: capture }));
+            if (overrideContext !== undefined) {
+                const synthesisStep = {
+                    step: 1,
+                    id: "synthesis",
+                    ok: true,
+                    summary: "context synthesized",
+                    outputExcerpt: {
+                        mainContextSource,
+                        synthesizedContextPresent: observability.synthesizedContextPresent,
+                        detectedTemplateCores: observability.detectedTemplateCores ?? [],
+                    },
+                };
+                const existingSteps = result.intermediateSteps ?? [];
+                result.intermediateSteps = [
+                    synthesisStep,
+                    ...existingSteps.map((s, i) => ({ ...s, step: i + 2 })),
+                ];
+            }
+            let currentOutput = typeof result.rawText === "string"
+                ? result.rawText
+                : JSON.stringify(result.parsed ?? result.rawText ?? "", null, 2);
+            const postStepsMeta = {};
+            let nextStepNumber = (result.intermediateSteps?.length ?? 0) + 1;
+            const reRunMain = (overrideContextWithFeedback) => runDirect(request, { overrideContext: overrideContextWithFeedback });
+            for (const step of postSteps) {
+                if (step.type === "audit") {
+                    const auditResult = await traceWrap(traceCollector, {
+                        taskType: "post-execution",
+                        details: "audit post step",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "audit",
+                            postStepType: "audit",
+                        },
+                    }, async () => withPhaseRecord({
+                        ax,
+                        correlationId,
+                        phase: "audit",
+                        meta: {
+                            ...baseMeta,
+                            postStepType: "audit",
+                            outer: activixOuterTier({
+                                kind: "postStep.audit.request",
+                                skillKey: request.skillKey,
+                                jobId: request.jobId,
+                                agentId: request.agentId,
+                                input: summarizeForOuter({
+                                    currentOutput,
+                                    hasContextMarkdown: !!capture.contextMarkdown,
+                                }, 8_000),
+                            }, null, { phase: "audit" }),
+                        },
+                        fn: async () => runAuditPostStep({
+                            request,
+                            mainResult: result,
+                            contextMarkdown: capture.contextMarkdown,
+                            config: (step.config ?? {}),
+                            reRunMain,
+                            traceCollector,
+                        }),
+                        onSuccessUpdates: (auditResult) => ({
+                            totalCycles: auditResult.metadata?.totalCycles,
+                            allMustPassed: auditResult.metadata?.allMustPassed,
+                            synthesisUsed: auditResult.metadata?.synthesisUsed,
+                            durationMs: auditResult.metadata?.durationMs,
+                            outer: activixOuterTier({
+                                kind: "postStep.audit.request",
+                                skillKey: request.skillKey,
+                                jobId: request.jobId,
+                                agentId: request.agentId,
+                                input: summarizeForOuter({
+                                    currentOutput,
+                                    hasContextMarkdown: !!capture.contextMarkdown,
+                                }, 8_000),
+                            }, {
+                                kind: "postStep.audit.result",
+                                outputText: summarizeForOuter(auditResult.outputText, 8_000),
+                                metadata: summarizeForOuter(auditResult.metadata, 6_000),
+                            }, { phase: "audit" }),
+                        }),
+                    }), (r) => ({
+                        metadata: {
+                            durationMs: r?.metadata?.durationMs,
+                            totalCycles: r?.metadata?.totalCycles,
+                            allMustPassed: r?.metadata?.allMustPassed,
+                        },
+                        modelUsed: r?.metadata?.modelUsed ?? null,
+                    }));
+                    currentOutput = auditResult.outputText;
+                    postStepsMeta.audit = auditResult.metadata;
+                    const stepsWithNumbers = auditResult.intermediateSteps.map((s) => ({
+                        ...s,
+                        step: nextStepNumber++,
+                    }));
+                    result.intermediateSteps = [
+                        ...(result.intermediateSteps ?? []),
+                        ...stepsWithNumbers,
+                    ];
+                }
+                else if (step.type === "polish") {
+                    const polishResult = await traceWrap(traceCollector, {
+                        taskType: "post-execution",
+                        details: "polish post step",
+                        metadata: {
+                            ...baseTraceMeta(),
+                            phase: "polish",
+                            postStepType: "polish",
+                        },
+                    }, async () => withPhaseRecord({
+                        ax,
+                        correlationId,
+                        phase: "polish",
+                        meta: {
+                            ...baseMeta,
+                            postStepType: "polish",
+                            outer: activixOuterTier({
+                                kind: "postStep.polish.request",
+                                skillKey: request.skillKey,
+                                jobId: request.jobId,
+                                agentId: request.agentId,
+                                input: summarizeForOuter({ currentOutput }, 8_000),
+                            }, null, { phase: "polish" }),
+                        },
+                        fn: async () => runPolishPostStep({
+                            currentOutput,
+                            config: (step.config ?? {}),
+                            originalInput: step.config?.includeOriginalContext ? request.input : undefined,
+                            promptContext: step.config?.includeOriginalContext ? capture.contextMarkdown : undefined,
+                            traceCollector,
+                            jobId: request.jobId,
+                            taskId: request.taskId,
+                            skillKey: request.skillKey,
+                        }),
+                        onSuccessUpdates: (polishResult) => ({
+                            totalPasses: polishResult.metadata?.totalPasses,
+                            durationMs: polishResult.metadata?.durationMs,
+                            outer: activixOuterTier({
+                                kind: "postStep.polish.request",
+                                skillKey: request.skillKey,
+                                jobId: request.jobId,
+                                agentId: request.agentId,
+                                input: summarizeForOuter({ currentOutput }, 8_000),
+                            }, {
+                                kind: "postStep.polish.result",
+                                outputText: summarizeForOuter(polishResult.outputText, 8_000),
+                                metadata: summarizeForOuter(polishResult.metadata, 6_000),
+                            }, { phase: "polish" }),
+                        }),
+                    }), (r) => ({
+                        metadata: {
+                            durationMs: r?.metadata?.durationMs,
+                            totalPasses: r?.metadata?.totalPasses,
+                        },
+                        modelUsed: r?.metadata?.modelUsed ?? null,
+                    }));
+                    currentOutput = polishResult.outputText;
+                    postStepsMeta.polish = polishResult.metadata;
+                    const stepsWithNumbers = polishResult.intermediateSteps.map((s) => ({
+                        ...s,
+                        step: nextStepNumber++,
+                    }));
+                    result.intermediateSteps = [
+                        ...(result.intermediateSteps ?? []),
+                        ...stepsWithNumbers,
+                    ];
+                }
+            }
+            result.rawText = currentOutput;
+            result.parsed = currentOutput;
+            result.metadata = {
+                ...(result.metadata ?? {}),
+                postSteps: postStepsMeta,
+                ...(traceCollector && aggregatedSynthLlmCalls.length > 0
+                    ? { synthesizedContextLlmCalls: aggregatedSynthLlmCalls }
+                    : {}),
+            };
+            attachExecutionStateAndObservability(result, request, observability, knobs);
+            return withTrace(result);
+        }
+        // MAIN path (direct / gateway skill). Narrix handler runs earlier when `narrixMode === "handler"`.
+        {
+            const result = finalize(await runMainWithExecutionStrategies(request));
+            attachExecutionStateAndObservability(result, request, {
+                synthesisEnabled: false,
+                synthesizedContextPresent: !!request.executionMemory?.synthesizedContext,
+                mainContextSource: "unsynthesized",
+            }, knobs);
+            return withTrace(result);
+        }
+    }
+    /**
+     * Run the synthesized-context PRE step: enrich memory, resolve source material, render templates, call synthesis model, return synthesized context.
+     */
+    async _runSynthesizedContextPreStep(request, config, traceCollector) {
+        const input = request;
+        let jobMemoryWithExecution = input.jobMemory || {};
+        if (input.executionMemory) {
+            const executionWithDefaults = {
+                bindingDefaultsDb: process.env.MONGO_LOGS_DB || "logs-db",
+                ...input.executionMemory,
+            };
+            if (jobMemoryWithExecution.execution) {
+                jobMemoryWithExecution = {
+                    ...jobMemoryWithExecution,
+                    execution: deepMergeExecution(jobMemoryWithExecution.execution, executionWithDefaults),
+                };
+            }
+            else {
+                jobMemoryWithExecution = { ...jobMemoryWithExecution, execution: executionWithDefaults };
+            }
+        }
+        else if (!jobMemoryWithExecution.execution?.bindingDefaultsDb) {
+            jobMemoryWithExecution = {
+                ...jobMemoryWithExecution,
+                execution: { ...jobMemoryWithExecution.execution, bindingDefaultsDb: process.env.MONGO_LOGS_DB || "logs-db" },
+            };
+        }
+        const memoryBundle = {
+            jobMemory: jobMemoryWithExecution,
+            taskMemory: input.taskMemory,
+            executionMemory: {
+                bindingDefaultsDb: process.env.MONGO_LOGS_DB || "logs-db",
+                ...(input.executionMemory || {}),
+            },
+        };
+        const enrichMemories = bindEnrichMemoriesWithScoping(this.skillsClient);
+        const enrichedBundle = await enrichMemories(request.skillKey, "task", memoryBundle);
+        const cleanExecution = cleanseExecution(enrichedBundle.jobMemory?.execution);
+        const bundleForRendering = {
+            ...enrichedBundle,
+            jobMemory: { ...enrichedBundle.jobMemory, execution: cleanExecution },
+            xynthesized: input.xynthesized,
+            smartInput: input.smartInput,
+        };
+        const attachToField = input.narrix?.attachToField ?? "_narrix";
+        const preProcessorAttachment = input.executionMemory?.[attachToField];
+        const narrixAttachment = hasNarrixAttachmentShape(preProcessorAttachment)
+            ? preProcessorAttachment
+            : coerceTaskMemoryNarrixToAttachment(input.taskMemory?.narrix);
+        const contextSourcePolicy = config.contextSourcePolicy ?? "auto";
+        const resolveOpts = {
+            contextSourcePolicy,
+            narrixAttachment,
+            enrichedMemoryBundle: enrichedBundle,
+            memoryPaths: config.memoryPaths,
+            webEvidence: config.webEvidence,
+            narrixAttachToField: input.narrix?.attachToField ?? "_narrix",
+        };
+        let sourceMaterial;
+        let sourceMaterialParts;
+        try {
+            const material = buildSynthesizerInputMaterial(config.synthesisInputStrategy, resolveOpts);
+            sourceMaterial = material.sourceMaterial;
+            sourceMaterialParts = material.parts;
+        }
+        catch (e) {
+            if (config.fallbackToDirect)
+                return { contextMarkdown: "" };
+            throw e;
+        }
+        const resolveRawTemplate = async (key) => {
+            const section = key.endsWith(".instructions") || key.endsWith(".instructions.md")
+                ? "instructions"
+                : key.endsWith(".prompt") || key.endsWith(".prompt.md")
+                    ? "prompt"
+                    : null;
+            const baseSkillKey = request.skillKey;
+            const skillsClient = this.skillsClient;
+            if (section && typeof skillsClient.resolveRawTemplate === "function") {
+                try {
+                    const result = await skillsClient.resolveRawTemplate(baseSkillKey, section);
+                    if (result?.found && typeof result.content === "string" && result.content.length > 0) {
+                        return result.content;
+                    }
+                }
+                catch {
+                    // Keep hard failure behavior in structured mode via empty token discovery.
+                }
+            }
+            return undefined;
+        };
+        const synthesisRequest = request;
+        const { rawInstructions, rawPrompt, renderedInstructions, renderedPrompt } = await getRenderedTemplates({
+            skillKey: request.skillKey,
+            bundle: bundleForRendering,
+            request: synthesisRequest,
+            resolveRawTemplate,
+        });
+        // Resolve effective LlmCallConfig for the PRE synthesis call. `config.llmCall` overrides
+        // `modelConfig.model` / `timeoutMs` / `maxOutputLength`. Default `outputExpectation` from
+        // `resolveOutputExpectation("synthesis")` (per xynthesis routing JSON).
+        const synthLlmCallInput = {
+            ...(config.llmCall ?? {}),
+            model: config.llmCall?.model ??
+                config.modelConfig?.model,
+            timeoutMs: config.llmCall?.timeoutMs ?? config.timeoutMs,
+            maxOutputLength: config.llmCall?.maxOutputLength ?? config.maxOutputLength,
+        };
+        const synthLlmCall = resolveLlmCall(synthLlmCallInput, llmCallEnvPrefix("SYNTHESIS"), {}, {
+            outputExpectation: resolveOutputExpectationXynthesis("synthesis"),
+            model: "gpt-5-nano",
+            timeoutMs: 30_000,
+        });
+        const model = synthLlmCall.model;
+        const timeoutMs = synthLlmCall.timeoutMs;
+        const maxOutputLength = synthLlmCall.maxOutputLength;
+        // Trace-mode-only sink for PRE synthesis observations. Surfaced to the caller via the return value's
+        // `synthesizedContextLlmCalls` field (lifted into result.metadata higher up the call stack).
+        const synthLlmCalls = [];
+        const synthObservationSink = traceCollector
+            ? (obs) => {
+                synthLlmCalls.push(obs);
+            }
+            : undefined;
+        if (config.questionDriven === true) {
+            const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+            const nonEmptyString = (v) => {
+                if (typeof v !== "string")
+                    return undefined;
+                const t = v.trim();
+                return t ? t : undefined;
+            };
+            const truncate = (s, maxChars) => {
+                if (!maxChars || maxChars <= 0)
+                    return s;
+                if (s.length <= maxChars)
+                    return s;
+                return s.slice(0, Math.max(0, maxChars - 20)) + "\n\n[truncated]";
+            };
+            const questions = Array.isArray(config.questions) ? config.questions : [];
+            if (questions.length === 0) {
+                const artifact = {
+                    mode: "questionDriven",
+                    answers: {},
+                    contextMarkdown: "",
+                };
+                return {
+                    contextMarkdown: "",
+                    artifact,
+                    synthesizedInput: buildSynthesizedInputArtifact("questionDriven", "", {
+                        localMarkdown: "",
+                        supportingMarkdown: "",
+                    }),
+                    synthesizedContextLlmCalls: traceCollector ? synthLlmCalls : undefined,
+                };
+            }
+            const execMem = (enrichedBundle.executionMemory ?? memoryBundle.executionMemory);
+            const recordRaw = isRecord(execMem?.input) ? execMem.input.raw : undefined;
+            const recordMd = recordRaw !== undefined
+                ? `## Record (executionMemory.input.raw)\n\n\`\`\`json\n${truncate(JSON.stringify(recordRaw, null, 2), maxOutputLength ? Math.min(maxOutputLength, 60_000) : 60_000)}\n\`\`\`\n`
+                : "";
+            const webContextEntry = execMem?.webContext;
+            const webMd = buildWebContextEvidenceMarkdown(webContextEntry, config.webEvidence);
+            const { system: systemTemplate, user: userTemplate } = await loadSynthesisTemplates();
+            const systemPrompt = buildSynthesisSystemPrompt(systemTemplate, config.synthesisPromptOverride, config.customSynthesizingGuidelines);
+            const extractWebEvidence = () => {
+                if (!isRecord(webContextEntry))
+                    return { webUnavailableReason: "webContext missing" };
+                if (webContextEntry.available !== true) {
+                    const reason = nonEmptyString(webContextEntry.reason) ?? "unavailable";
+                    const err = nonEmptyString(webContextEntry.error);
+                    return { webUnavailableReason: err ? `${reason}: ${err}` : reason };
+                }
+                const ctx = webContextEntry.context;
+                if (!isRecord(ctx))
+                    return {};
+                const sourcesRaw = Array.isArray(ctx.sources) ? ctx.sources : [];
+                const sources = sourcesRaw
+                    .filter((s) => isRecord(s))
+                    .map((s) => ({
+                    url: nonEmptyString(s.url) ?? nonEmptyString(s.link),
+                    title: nonEmptyString(s.title) ?? nonEmptyString(s.name),
+                }))
+                    .filter((s) => s.url || s.title);
+                const scopesRaw = Array.isArray(ctx.scopes) ? ctx.scopes : [];
+                const webScopeIds = scopesRaw
+                    .filter((s) => isRecord(s))
+                    .map((s) => nonEmptyString(s.id) ?? nonEmptyString(s.scopeId))
+                    .filter((x) => !!x);
+                return {
+                    sources: sources.length > 0 ? sources : undefined,
+                    webScopeIds: webScopeIds.length > 0 ? webScopeIds : undefined,
+                };
+            };
+            const webEvidence = extractWebEvidence();
+            const answers = {};
+            for (const q of questions) {
+                if (!q || typeof q !== "object")
+                    continue;
+                const id = q.id;
+                const question = q.question;
+                if (typeof id !== "string" || !id.trim())
+                    continue;
+                if (typeof question !== "string" || !question.trim())
+                    continue;
+                const source = q.source === "record" || q.source === "web" || q.source === "both"
+                    ? q.source
+                    : "both";
+                const allowRecord = source === "record" || source === "both";
+                const allowWeb = source === "web" || source === "both";
+                const hasRecord = !!recordMd;
+                const hasWeb = !!webMd;
+                const materialParts = [
+                    "## Target question",
+                    "",
+                    question.trim(),
+                    "",
+                    "## Allowed sources",
+                    "",
+                    `- source: ${source}`,
+                    "",
+                ];
+                if (allowRecord)
+                    materialParts.push(recordMd || "## Record\n\n[missing]");
+                if (allowWeb)
+                    materialParts.push(webMd || "## Web sources (primary evidence)\n\n[unavailable]");
+                const perQuestionMaterial = materialParts.join("\n");
+                const userPrompt = buildSynthesisUserPrompt(renderedInstructions, renderedPrompt, perQuestionMaterial, userTemplate);
+                let synthesisText;
+                if (allowWeb && !hasWeb && !allowRecord) {
+                    const reason = webEvidence.webUnavailableReason ?? "web scoping unavailable";
+                    synthesisText = `Unknown — web-derived context unavailable (${reason}).`;
+                }
+                else if (allowRecord && !hasRecord && !allowWeb) {
+                    synthesisText = `Unknown — record-derived context unavailable (missing executionMemory.input.raw).`;
+                }
+                else if (allowRecord && allowWeb && !hasRecord && !hasWeb) {
+                    const reason = webEvidence.webUnavailableReason ?? "web scoping unavailable";
+                    synthesisText =
+                        `Unknown — no inputs available (missing executionMemory.input.raw; web unavailable: ${reason}).`;
+                }
+                else {
+                    const res = await runPostStepLlmCall({
+                        systemPrompt,
+                        userPrompt,
+                        llmCall: synthLlmCall,
+                        stage: "pre-synthesis-question",
+                        stepId: `questionDriven:${id}`,
+                        jobId: request.jobId,
+                        taskId: request.taskId,
+                        agentId: request.agentId,
+                        traceCollector,
+                        traceTask: traceCollector
+                            ? {
+                                taskType: "pre-execution",
+                                details: "synthesized-context question call",
+                                modelUsed: model ?? null,
+                                metadata: {
+                                    jobId: request.jobId,
+                                    taskId: request.taskId,
+                                    skillKey: request.skillKey,
+                                    phase: "pipeline_pre",
+                                    preStepType: "synthesized-context",
+                                    step: { phase: "pre", type: "synthesized-context", stepId: `questionDriven:${id}` },
+                                    questionId: id,
+                                },
+                            }
+                            : undefined,
+                        observationSink: synthObservationSink,
+                    });
+                    synthesisText = res.text;
+                }
+                answers[id] = {
+                    question: question.trim(),
+                    source,
+                    synthesis: synthesisText,
+                    evidence: {
+                        recordPaths: allowRecord ? ["executionMemory.input.raw"] : undefined,
+                        webScopeIds: allowWeb ? webEvidence.webScopeIds : undefined,
+                        sources: allowWeb ? webEvidence.sources : undefined,
+                    },
+                };
+            }
+            const contextMarkdown = "## Question-driven synthesized context\n\n" +
+                Object.entries(answers)
+                    .map(([id, a]) => `### ${id}\n\n**Question:** ${a.question}\n\n${a.synthesis}\n`)
+                    .join("\n");
+            const qdSource = [recordMd, webMd].filter(Boolean).join("\n\n");
+            const artifact = {
+                mode: "questionDriven",
+                answers,
+                contextMarkdown,
+            };
+            return {
+                contextMarkdown,
+                artifact,
+                synthesizedInput: buildSynthesizedInputArtifact("questionDriven", qdSource, {
+                    localMarkdown: recordMd,
+                    supportingMarkdown: webMd,
+                }),
+                synthesizedContextLlmCalls: traceCollector ? synthLlmCalls : undefined,
+            };
+        }
+        const synthesisMode = resolveSynthesisMode(config);
+        if (synthesisMode === "structured") {
+            const parts = sourceMaterialParts;
+            const question = safeResolveSynthesisQuestion(synthesisRequest, config, renderedPrompt);
+            const { templateCores } = discoverTemplateCores({
+                templates: [
+                    { name: "instructions", content: rawInstructions },
+                    { name: "prompt", content: rawPrompt },
+                ],
+            });
+            if (templateCores.length === 0) {
+                if (!rawInstructions.trim() && !rawPrompt.trim()) {
+                    throw new Error(`structured synthesized-context could not resolve raw instructions/prompt templates for skillKey: ${request.skillKey}. ` +
+                        `Ensure ai-skills content registry is available for resolveRawTemplate().`);
+                }
+                throw new Error(`structured synthesized-context requires at least one template core token in instructions or prompt. skillKey: ${request.skillKey}`);
+            }
+            const validateOpts = {
+                expectedTemplateCores: templateCores,
+                expectedQuestion: question,
+                maxItemsPerSide: config.structuredMaxItemsPerSide,
+                maxItemContentChars: config.structuredMaxItemContentChars,
+            };
+            try {
+                const custom = getContextSynthesizer();
+                let payload;
+                if (custom) {
+                    payload = await custom.synthesize({
+                        templateCores,
+                        question,
+                        localRaw: parts.localMarkdown,
+                        supportingRaw: parts.supportingMarkdown,
+                        metadata: {
+                            renderedInstructions,
+                            renderedPrompt,
+                            templateCores,
+                            skillKey: request.skillKey,
+                            jobId: request.jobId,
+                            taskId: request.taskId,
+                        },
+                    });
+                    payload = normalizeAndValidateSynthesizedPayload(payload, validateOpts);
+                }
+                else {
+                    payload = await runStructuredSynthesisGatewayCallRobust({
+                        question,
+                        localMarkdown: parts.localMarkdown,
+                        supportingMarkdown: parts.supportingMarkdown,
+                        renderedInstructions,
+                        renderedPrompt,
+                        templatesBasePath: config.templatesBasePath,
+                        synthesisPromptOverride: config.synthesisPromptOverride,
+                        customSynthesizingGuidelines: config.customSynthesizingGuidelines,
+                        model: model,
+                        timeoutMs: timeoutMs,
+                        maxOutputLength: maxOutputLength,
+                        // Caller-supplied outputExpectation overrides the per-action default in the structured-repair path.
+                        outputExpectation: synthLlmCall.outputExpectation,
+                        // Hard ceiling for `resolveMaxTokens` in the AIGateway repair fallback.
+                        maxTokensCap: synthLlmCall.maxTokensCap,
+                        // Forward trace mode so the structured gateway returns a `debugTrace` (lifted into observations elsewhere).
+                        executionMode: traceCollector ? "trace" : undefined,
+                        jobId: request.jobId,
+                        taskId: request.taskId,
+                        agentId: request.agentId,
+                    });
+                }
+                const contextMarkdown = buildSynthesizedContextMarkdown(payload);
+                return {
+                    contextMarkdown,
+                    artifact: {
+                        templateCores,
+                        question,
+                        mode: synthesisMode,
+                        payload,
+                        contextMarkdown,
+                    },
+                    synthesizedInput: buildSynthesizedInputArtifact(synthesisMode, sourceMaterial, parts, {
+                        question,
+                        templateCores,
+                    }),
+                    synthesizedContextLlmCalls: traceCollector ? synthLlmCalls : undefined,
+                };
+            }
+            catch (e) {
+                if (config.fallbackToDirect === true)
+                    return {
+                        contextMarkdown: "",
+                        synthesizedContextLlmCalls: traceCollector ? synthLlmCalls : undefined,
+                    };
+                throw e;
+            }
+        }
+        const { system: systemTemplate, user: userTemplate } = await loadSynthesisTemplates();
+        const systemPrompt = buildSynthesisSystemPrompt(systemTemplate, config.synthesisPromptOverride, config.customSynthesizingGuidelines);
+        const userPrompt = buildSynthesisUserPrompt(renderedInstructions, renderedPrompt, sourceMaterial, userTemplate);
+        try {
+            const { text: contextMarkdown } = await runPostStepLlmCall({
+                systemPrompt,
+                userPrompt,
+                extraMaterial: sourceMaterial,
+                llmCall: synthLlmCall,
+                stage: "pre-synthesis-markdown",
+                jobId: request.jobId,
+                taskId: request.taskId,
+                agentId: request.agentId,
+                traceCollector,
+                traceTask: traceCollector
+                    ? {
+                        taskType: "pre-execution",
+                        details: "synthesized-context markdown call",
+                        modelUsed: model ?? null,
+                        metadata: {
+                            jobId: request.jobId,
+                            taskId: request.taskId,
+                            skillKey: request.skillKey,
+                            phase: "pipeline_pre",
+                            preStepType: "synthesized-context",
+                            step: { phase: "pre", type: "synthesized-context", stepId: "markdown" },
+                        },
+                    }
+                    : undefined,
+                observationSink: synthObservationSink,
+            });
+            const question = safeResolveSynthesisQuestion(synthesisRequest, config, renderedPrompt);
+            const { templateCores } = discoverTemplateCores({
+                templates: [
+                    { name: "instructions", content: rawInstructions },
+                    { name: "prompt", content: rawPrompt },
+                ],
+            });
+            return {
+                contextMarkdown,
+                artifact: {
+                    templateCores,
+                    question,
+                    mode: "markdown",
+                    payload: { kind: "markdown-synthesis" },
+                    contextMarkdown,
+                },
+                synthesizedInput: buildSynthesizedInputArtifact("markdown", sourceMaterial, sourceMaterialParts, {
+                    question,
+                    templateCores,
+                }),
+                synthesizedContextLlmCalls: traceCollector ? synthLlmCalls : undefined,
+            };
+        }
+        catch (e) {
+            if (config.fallbackToDirect === true)
+                return {
+                    contextMarkdown: "",
+                    synthesizedContextLlmCalls: traceCollector ? synthLlmCalls : undefined,
+                };
+            throw e;
+        }
+    }
+    /**
+     * Execute the DIRECT path: build memory bundle, enrich, generate context (including Narrix section from taskMemory.narrix), then executor.
+     * When options.overrideContext is set, that string is used as context markdown instead of generating it.
+     * When options.captureContext is set, the context markdown sent to the MAIN step is written into it (for POST steps).
+     * When options.synthesisContextAuthoritative is true, an empty override is not replaced by Narrix/web fallback.
+     */
+    async _executeDirect(request, options) {
+        const input = request;
+        const traceCollector = options?.traceCollector ?? null;
+        const taskId = input.taskId;
+        const jobId = input.jobId;
+        // Merge executionMemory into jobMemory as "execution" before enrichment
+        let jobMemoryWithExecution = input.jobMemory || {};
+        if (input.executionMemory) {
+            const executionWithDefaults = {
+                bindingDefaultsDb: process.env.MONGO_LOGS_DB || 'logs-db',
+                ...input.executionMemory
+            };
+            if (jobMemoryWithExecution.execution) {
+                jobMemoryWithExecution = {
+                    ...jobMemoryWithExecution,
+                    execution: deepMergeExecution(jobMemoryWithExecution.execution, executionWithDefaults),
+                };
+            }
+            else {
+                jobMemoryWithExecution = {
+                    ...jobMemoryWithExecution,
+                    execution: executionWithDefaults,
+                };
+            }
+        }
+        else if (!jobMemoryWithExecution.execution || !jobMemoryWithExecution.execution.bindingDefaultsDb) {
+            jobMemoryWithExecution = {
+                ...jobMemoryWithExecution,
+                execution: {
+                    ...jobMemoryWithExecution.execution,
+                    bindingDefaultsDb: process.env.MONGO_LOGS_DB || 'logs-db'
+                }
+            };
+        }
+        const memoryBundle = {
+            jobMemory: jobMemoryWithExecution,
+            taskMemory: input.taskMemory,
+            executionMemory: {
+                bindingDefaultsDb: process.env.MONGO_LOGS_DB || 'logs-db',
+                ...(input.executionMemory || {}),
+            },
+        };
+        const client = this.skillsClient;
+        const enrichMemories = bindEnrichMemoriesWithScoping(this.skillsClient);
+        const generateContext = bindGenerateContextMarkdown(this.skillsClient);
+        let diagnose;
+        if (typeof this.skillsClient.diagnoseSkillContent === 'function') {
+            diagnose = this.skillsClient.diagnoseSkillContent.bind(this.skillsClient);
+        }
+        else if (typeof client.diagnoseSkillContent === 'function') {
+            diagnose = client.diagnoseSkillContent.bind(client);
+        }
+        else {
+            diagnose = async (key) => {
+                const registry = this.skillsClient.registry;
+                if (registry && typeof registry.diagnose === 'function') {
+                    await registry.diagnose(key);
+                }
+            };
+        }
+        const enrichedBundle = await enrichMemories(request.skillKey, "task", memoryBundle);
+        const cleanExecution = cleanseExecution(enrichedBundle.jobMemory?.execution);
+        const bundleForRendering = {
+            ...enrichedBundle,
+            jobMemory: {
+                ...enrichedBundle.jobMemory,
+                execution: cleanExecution,
+            }
+        };
+        const attachToField = input.narrix?.attachToField ?? "_narrix";
+        const preProcessorAttachment = input.executionMemory?.[attachToField];
+        const narrixInPlay = hasNarrixAttachmentShape(preProcessorAttachment);
+        const narrixInTaskMemory = Array.isArray(input.taskMemory?.narrix) && input.taskMemory.narrix.length > 0;
+        const narrixRequested = !!input.narrix || narrixInTaskMemory;
+        const contextRequested = input.includeContextInPrompt === true || narrixRequested;
+        let contextMarkdown;
+        if (options?.overrideContext !== undefined) {
+            contextMarkdown = options.overrideContext;
+            if (narrixRequested &&
+                contextMarkdown.trim() === "" &&
+                options?.synthesisContextAuthoritative !== true) {
+                if (narrixInPlay) {
+                    contextMarkdown = buildNarrixPreProcessorContextMarkdown(preProcessorAttachment);
+                    const execMem = (enrichedBundle.executionMemory ?? memoryBundle.executionMemory);
+                    const webMd = buildWebContextEvidenceMarkdown(execMem?.webContext);
+                    if (webMd)
+                        contextMarkdown += webMd;
+                }
+                else {
+                    contextMarkdown = buildNarrixContextMarkdown(input.taskMemory?.narrix);
+                }
+            }
+        }
+        else if (!contextRequested) {
+            contextMarkdown = "";
+        }
+        else if (narrixInPlay) {
+            contextMarkdown = buildNarrixPreProcessorContextMarkdown(preProcessorAttachment);
+            const execMem = (enrichedBundle.executionMemory ?? memoryBundle.executionMemory);
+            const webMd = buildWebContextEvidenceMarkdown(execMem?.webContext);
+            if (webMd)
+                contextMarkdown += webMd;
+        }
+        else {
+            contextMarkdown = await generateContext(request.skillKey, "task", bundleForRendering);
+            const narrixSection = buildNarrixContextMarkdown(input.taskMemory?.narrix);
+            if (narrixSection)
+                contextMarkdown += narrixSection;
+        }
+        const execMemForCallerWeb = (enrichedBundle.executionMemory ?? memoryBundle.executionMemory);
+        const allowCallerWebAppend = input.includeContextInPrompt === true ||
+            narrixRequested ||
+            options?.overrideContext !== undefined;
+        contextMarkdown = appendExternalWebContextMarkdown(contextMarkdown, execMemForCallerWeb, allowCallerWebAppend);
+        if (options?.captureContext) {
+            options.captureContext.contextMarkdown = contextMarkdown;
+        }
+        let aiScoped;
+        let aiScopingFailures;
+        let aiScopingLlmCalls;
+        if (input.aiScoping && input.aiScoping.length > 0) {
+            const requestLevelLlmCall = input.aiScopingOptions?.llmCall;
+            const fallbackModel = requestLevelLlmCall?.model ??
+                input.modelConfig?.model ??
+                process.env.AI_SCOPING_MODEL;
+            const concurrency = input.aiScopingOptions?.concurrency ??
+                (process.env.AI_SCOPING_CONCURRENCY
+                    ? parseInt(process.env.AI_SCOPING_CONCURRENCY, 10)
+                    : 5);
+            const timeoutMsPerItem = input.aiScopingOptions?.timeoutMsPerItem ??
+                (process.env.AI_SCOPING_TIMEOUT_MS
+                    ? parseInt(process.env.AI_SCOPING_TIMEOUT_MS, 10)
+                    : 30_000);
+            const scopingLlmCall = {
+                ...requestLevelLlmCall,
+                model: requestLevelLlmCall?.model ?? fallbackModel,
+                timeoutMs: requestLevelLlmCall?.timeoutMs ?? timeoutMsPerItem,
+            };
+            const scopingResult = await runAiScoping({
+                bundle: enrichedBundle,
+                instructions: input.aiScoping,
+                llmCall: scopingLlmCall,
+                concurrency,
+                traceCollector,
+                jobId,
+                taskId,
+            });
+            aiScoped = scopingResult.scoped;
+            aiScopingFailures = scopingResult.failures.length > 0 ? scopingResult.failures : undefined;
+            aiScopingLlmCalls = traceCollector && scopingResult.llmCalls.length > 0 ? scopingResult.llmCalls : undefined;
+        }
+        let finalJobMemory = { ...enrichedBundle.jobMemory };
+        const originalExecution = jobMemoryWithExecution?.execution;
+        const executionFromEnrichment = enrichedBundle.jobMemory?.execution;
+        const activeExecution = executionFromEnrichment || originalExecution;
+        const cleanActiveExecution = cleanseExecution(activeExecution);
+        finalJobMemory = {
+            ...finalJobMemory,
+            execution: cleanActiveExecution,
+        };
+        const { jobContext: _omitJobContextFromExecutor, ...inputForExecutor } = input;
+        const mergedInput = aiScoped && aiScoped.length > 0
+            ? {
+                ...(input.input && typeof input.input === "object" && input.input !== null
+                    ? input.input
+                    : {}),
+                aiScoped,
+            }
+            : input.input;
+        const enrichedInput = {
+            ...inputForExecutor,
+            skillKey: request.skillKey,
+            jobMemory: finalJobMemory,
+            taskMemory: enrichedBundle.taskMemory,
+            executionMemory: enrichedBundle.executionMemory || memoryBundle.executionMemory,
+            context: contextMarkdown,
+            input: mergedInput,
+            xynthesized: input.xynthesized,
+            smartInput: input.smartInput,
+            variables: passthroughJobTemplateVariables(input.variables),
+        };
+        const result = await this.executor.execute(enrichedInput, async (key) => {
+            await diagnose(key);
+        });
+        liftIntermediateSteps(result);
+        const parsedIsEmpty = result.parsed === undefined ||
+            result.parsed === null ||
+            (typeof result.parsed === 'object' && Object.keys(result.parsed).length === 0);
+        const strictDecision = isStrictDecisionTask(request);
+        if (strictDecision && parsedIsEmpty) {
+            throw new Error(`Decision task "${request.skillKey}" did not return response.parsed`);
+        }
+        if (!strictDecision && parsedIsEmpty && result) {
+            if (result.flexMd && result.flexMd.payloads && Object.keys(result.flexMd.payloads).length > 0) {
+                result.parsed = result.flexMd.payloads;
+            }
+            else {
+                const resultAny = result;
+                if (resultAny.parsedContent && typeof resultAny.parsedContent === 'object' && Object.keys(resultAny.parsedContent).length > 0) {
+                    result.parsed = resultAny.parsedContent;
+                }
+                else if (resultAny.metadata?.parsedContent && typeof resultAny.metadata.parsedContent === 'object' && Object.keys(resultAny.metadata.parsedContent).length > 0) {
+                    result.parsed = resultAny.metadata.parsedContent;
+                }
+                else if (resultAny.gatewayResponse?.parsedContent && typeof resultAny.gatewayResponse.parsedContent === 'object' && Object.keys(resultAny.gatewayResponse.parsedContent).length > 0) {
+                    result.parsed = resultAny.gatewayResponse.parsedContent;
+                }
+                else if (resultAny.enhancedResponse?.parsedContent && typeof resultAny.enhancedResponse.parsedContent === 'object' && Object.keys(resultAny.enhancedResponse.parsedContent).length > 0) {
+                    result.parsed = resultAny.enhancedResponse.parsedContent;
+                }
+            }
+        }
+        const outputValidation = request.outputValidation;
+        if (outputValidation?.schema) {
+            const validateWhenMissing = outputValidation.validateWhenMissing !== false;
+            if (validateWhenMissing || result.parsed !== undefined) {
+                const vr = validateParsedOutput(result.parsed, outputValidation.schema);
+                if (options?.validationCorrelationId) {
+                    vr.correlationId = options.validationCorrelationId;
+                }
+                result.metadata = { ...result.metadata, outputValidation: vr };
+                if (!vr.ok && (outputValidation.mode ?? "fail") === "fail") {
+                    throw new Error(`outputValidation failed for skillKey ${request.skillKey}: ` +
+                        vr.errors.map((e) => `${e.path} ${e.message}`).join("; "));
+                }
+            }
+        }
+        // Surface AI scoping per-item failures + per-item LlmCallObservations on result metadata.
+        // `aiScopingFailures` is published whenever any item failed (regardless of mode); previously
+        // failures were silently dropped. `aiScopingLlmCalls` is trace-mode-only.
+        if (aiScopingFailures || aiScopingLlmCalls) {
+            result.metadata = {
+                ...(result.metadata ?? {}),
+                ...(aiScopingFailures ? { aiScopingFailures } : {}),
+                ...(aiScopingLlmCalls ? { aiScopingLlmCalls } : {}),
+            };
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=task-sdk.js.map