ultravisor 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ultravisor",
-    "version": "1.0.15",
+    "version": "1.0.17",
     "description": "Cyclic process execution with ai integration.",
     "main": "source/Ultravisor.cjs",
     "bin": {
@@ -30,8 +30,8 @@
         "cron": "^4.4.0",
         "orator": "^6.0.4",
         "orator-authentication": "^1.0.0",
-        "orator-serviceserver-restify": "^2.0.9",
-        "pict": "^1.0.359",
+        "orator-serviceserver-restify": "^2.0.10",
+        "pict": "^1.0.361",
         "pict-service-commandlineutility": "^1.0.19",
         "pict-serviceproviderbase": "^1.0.4",
         "ultravisor-beacon": "^0.0.8",

package/source/services/Ultravisor-Beacon-Coordinator.cjs

@@ -989,6 +989,23 @@ class UltravisorBeaconCoordinator extends libPictService
 		{
 			this._tryPushToWebSocketBeacon(tmpWorkItem);
 		}
+		else if (tmpWorkItem.Status === 'Assigned' && tmpWorkItem.AssignedBeaconID && this._WorkItemPushHandler)
+		{
+			// Affinity pre-assigned — push directly to the assigned beacon via WebSocket
+			tmpWorkItem.Status = 'Running';
+			let tmpPushed = this._WorkItemPushHandler(tmpWorkItem.AssignedBeaconID,
+				this._sanitizeWorkItemForBeacon(tmpWorkItem));
+
+			if (tmpPushed)
+			{
+				this.log.info(`BeaconCoordinator: pushed affinity-assigned work item [${tmpWorkItemHash}] to WebSocket beacon [${tmpWorkItem.AssignedBeaconID}].`);
+			}
+			else
+			{
+				// WebSocket push failed — revert to Assigned for HTTP poll pickup
+				tmpWorkItem.Status = 'Assigned';
+			}
+		}
 
 		return tmpWorkItem;
 	}

package/source/services/Ultravisor-ExecutionEngine.cjs

@@ -1005,6 +1005,20 @@ class UltravisorExecutionEngine extends libPictService
 
 			if (typeof(tmpVal) === 'string' && tmpVal.indexOf('{~') >= 0)
 			{
+				// When the entire value is a single {~D:Record.X~} expression,
+				// resolve via StateManager to preserve non-scalar types
+				// (arrays, objects).  parseTemplate always returns strings.
+				let tmpDataMatch = tmpVal.match(/^\{~D:Record\.(.+?)~\}$/);
+				if (tmpDataMatch)
+				{
+					let tmpAddress = tmpDataMatch[1];
+					let tmpResolved = tmpStateManager.resolveAddress(tmpAddress, pContext);
+					if (tmpResolved !== undefined)
+					{
+						tmpSettings[tmpKey] = tmpResolved;
+						continue;
+					}
+				}
 				tmpSettings[tmpKey] = this._resolveTemplate(tmpVal, tmpTemplateContext);
 			}
 		}

package/source/services/tasks/flow-control/Ultravisor-TaskConfigs-FlowControl.cjs

@@ -174,6 +174,24 @@ function _handleStepComplete(pContext, fCallback)
 }
 
 
+/**
+ * Flatten a parameter set object into string-valued output fields.
+ * { seed: 42, guidance: 5.0 } → { seed: "42", guidance: "5.0" }
+ * This allows direct state wiring: ParameterSweep.seed → Denoise.seed
+ */
+function _flattenParams(pObj)
+{
+	let tmpResult = {};
+	let tmpKeys = Object.keys(pObj || {});
+	for (let i = 0; i < tmpKeys.length; i++)
+	{
+		let tmpVal = pObj[tmpKeys[i]];
+		tmpResult[tmpKeys[i]] = (tmpVal === null || tmpVal === undefined) ? '' : String(tmpVal);
+	}
+	return tmpResult;
+}
+
+
 // ═══════════════════════════════════════════════════════════════════
 //  FLOW CONTROL TASK CONFIGS
 // ═══════════════════════════════════════════════════════════════════
@@ -244,6 +262,104 @@ module.exports =
 		}
 	},
 
+	// ── parameter-sweep ───────────────────────────────────────
+	{
+		Definition: require('./definitions/parameter-sweep.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			if (pExecutionContext.TriggeringEventName === 'StepComplete')
+			{
+				// Read stored iteration state from prior invocations
+				let tmpStoredState = pExecutionContext.TaskOutputs[pExecutionContext.NodeHash] || {};
+				let tmpSets = tmpStoredState._ParameterSets;
+
+				if (!Array.isArray(tmpSets))
+				{
+					return fCallback(null, {
+						EventToFire: 'Error',
+						Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+						Log: ['StepComplete fired but no stored parameter sets found. Was BeginSweep called?']
+					});
+				}
+
+				let tmpCurrentIndex = tmpStoredState.CurrentIndex || 0;
+				let tmpCompletedCount = (tmpStoredState.CompletedCount || 0) + 1;
+				let tmpNextIndex = tmpCurrentIndex + 1;
+				let tmpTotalCount = tmpSets.length;
+
+				if (tmpNextIndex >= tmpTotalCount)
+				{
+					let tmpLast = tmpSets[tmpTotalCount - 1] || {};
+					let tmpOutputs = Object.assign(
+						{ _ParameterSets: tmpSets, CurrentParameters: JSON.stringify(tmpLast), CurrentIndex: tmpTotalCount - 1, TotalCount: tmpTotalCount, CompletedCount: tmpCompletedCount },
+						_flattenParams(tmpLast));
+					return fCallback(null, {
+						EventToFire: 'SweepComplete',
+						Outputs: tmpOutputs,
+						Log: ['Parameter sweep complete. Processed ' + tmpCompletedCount + '/' + tmpTotalCount + ' set(s).']
+					});
+				}
+
+				let tmpNext = tmpSets[tmpNextIndex] || {};
+				let tmpOutputs = Object.assign(
+					{ _ParameterSets: tmpSets, CurrentParameters: JSON.stringify(tmpNext), CurrentIndex: tmpNextIndex, TotalCount: tmpTotalCount, CompletedCount: tmpCompletedCount },
+					_flattenParams(tmpNext));
+				return fCallback(null, {
+					EventToFire: 'ParameterSetReady',
+					Outputs: tmpOutputs,
+					Log: ['Emitting parameter set ' + (tmpNextIndex + 1) + '/' + tmpTotalCount + '.']
+				});
+			}
+
+			// BeginSweep — parse the array and emit the first set
+			let tmpRawSets = pResolvedSettings.ParameterSets;
+			let tmpSets;
+			if (typeof tmpRawSets === 'string')
+			{
+				try { tmpSets = JSON.parse(tmpRawSets); }
+				catch (pErr)
+				{
+					return fCallback(null, {
+						EventToFire: 'Error',
+						Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+						Log: ['ParameterSets is not valid JSON: ' + pErr.message]
+					});
+				}
+			}
+			else if (Array.isArray(tmpRawSets))
+			{
+				tmpSets = tmpRawSets;
+			}
+			else
+			{
+				return fCallback(null, {
+					EventToFire: 'Error',
+					Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+					Log: ['ParameterSets must be a JSON array.']
+				});
+			}
+
+			if (!Array.isArray(tmpSets) || tmpSets.length === 0)
+			{
+				return fCallback(null, {
+					EventToFire: 'SweepComplete',
+					Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+					Log: ['ParameterSets is empty. Nothing to sweep.']
+				});
+			}
+
+			let tmpFirst = tmpSets[0] || {};
+			let tmpOutputs = Object.assign(
+				{ _ParameterSets: tmpSets, CurrentParameters: JSON.stringify(tmpFirst), CurrentIndex: 0, TotalCount: tmpSets.length, CompletedCount: 0 },
+				_flattenParams(tmpFirst));
+			return fCallback(null, {
+				EventToFire: 'ParameterSetReady',
+				Outputs: tmpOutputs,
+				Log: ['Parameter sweep started: ' + tmpSets.length + ' set(s). Emitting set 1/' + tmpSets.length + '.']
+			});
+		}
+	},
+
 	// ── launch-operation ───────────────────────────────────────
 	{
 		Definition: require('./definitions/launch-operation.json'),

package/source/services/tasks/flow-control/Ultravisor-TaskType-ParameterSweep.cjs

@@ -0,0 +1,197 @@
+/**
+ * Parameter Sweep — Iterates over a JSON array of parameter sets.
+ *
+ * Each entry in the array becomes one execution of downstream tasks.
+ * Individual fields from each parameter set are exposed as state outputs
+ * so they can be wired into downstream card settings.
+ *
+ * Graph pattern (identical to split-execute):
+ *   ParameterSweep.ParameterSetReady → [downstream tasks] → ParameterSweep.StepComplete
+ *   ParameterSweep.SweepComplete → [whatever follows the loop]
+ *
+ * Example ParameterSets input:
+ *   [{"seed": 42, "guidance": 5.0}, {"seed": 123, "guidance": 7.0}]
+ *
+ * State outputs per iteration:
+ *   CurrentParameters: '{"seed": 42, "guidance": 5.0}'  (full object as JSON string)
+ *   CurrentIndex: 0
+ *   TotalCount: 2
+ *   CompletedCount: 0
+ *   Plus: each key from the current parameter set is also exposed directly
+ *         e.g., "seed" = "42", "guidance" = "5.0" (all coerced to strings)
+ *
+ * @license MIT
+ * @author Steven Velozo <steven@velozo.com>
+ */
+
+'use strict';
+
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+const libPath = require('path');
+
+class TaskTypeParameterSweep extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'TaskType-ParameterSweep';
+	}
+
+	get definition()
+	{
+		return require('./definitions/parameter-sweep.json');
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpTrigger = pExecutionContext.TriggeringEventName || 'BeginSweep';
+
+		if (tmpTrigger === 'StepComplete')
+		{
+			return this._handleStepComplete(pResolvedSettings, pExecutionContext, fCallback);
+		}
+
+		return this._handleBeginSweep(pResolvedSettings, pExecutionContext, fCallback);
+	}
+
+	_handleBeginSweep(pSettings, pContext, fCallback)
+	{
+		let tmpRawSets = pSettings.ParameterSets;
+
+		// Parse the parameter array
+		let tmpSets;
+		if (typeof tmpRawSets === 'string')
+		{
+			try
+			{
+				tmpSets = JSON.parse(tmpRawSets);
+			}
+			catch (pError)
+			{
+				return fCallback(null,
+					{
+						EventToFire: 'Error',
+						Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+						Log: ['ParameterSets is not valid JSON: ' + pError.message]
+					});
+			}
+		}
+		else if (Array.isArray(tmpRawSets))
+		{
+			tmpSets = tmpRawSets;
+		}
+		else
+		{
+			return fCallback(null,
+				{
+					EventToFire: 'Error',
+					Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+					Log: ['ParameterSets must be a JSON array string or an array.']
+				});
+		}
+
+		if (!Array.isArray(tmpSets) || tmpSets.length === 0)
+		{
+			return fCallback(null,
+				{
+					EventToFire: 'Error',
+					Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+					Log: ['ParameterSets is empty or not an array.']
+				});
+		}
+
+		// Emit the first parameter set
+		let tmpFirst = tmpSets[0] || {};
+		let tmpOutputs = this._buildOutputs(tmpSets, tmpFirst, 0, 0);
+
+		return fCallback(null,
+			{
+				EventToFire: 'ParameterSetReady',
+				Outputs: tmpOutputs,
+				Log: ['Parameter sweep started: ' + tmpSets.length + ' set(s). Emitting set 1/' + tmpSets.length + '.']
+			});
+	}
+
+	_handleStepComplete(pSettings, pContext, fCallback)
+	{
+		// Read stored iteration state from prior invocations
+		let tmpStoredState = pContext.TaskOutputs[pContext.NodeHash] || {};
+		let tmpSets = tmpStoredState._ParameterSets;
+
+		if (!tmpSets || !Array.isArray(tmpSets))
+		{
+			return fCallback(null,
+				{
+					EventToFire: 'Error',
+					Outputs: { CurrentParameters: '{}', CurrentIndex: 0, TotalCount: 0, CompletedCount: 0 },
+					Log: ['StepComplete fired but no stored parameter sets found. Was BeginSweep called?']
+				});
+		}
+
+		let tmpCurrentIndex = (tmpStoredState.CurrentIndex || 0);
+		let tmpCompletedCount = (tmpStoredState.CompletedCount || 0) + 1;
+		let tmpNextIndex = tmpCurrentIndex + 1;
+		let tmpTotalCount = tmpSets.length;
+
+		if (tmpNextIndex >= tmpTotalCount)
+		{
+			// All parameter sets have been processed
+			let tmpLast = tmpSets[tmpTotalCount - 1] || {};
+			let tmpOutputs = this._buildOutputs(tmpSets, tmpLast, tmpTotalCount - 1, tmpCompletedCount);
+
+			return fCallback(null,
+				{
+					EventToFire: 'SweepComplete',
+					Outputs: tmpOutputs,
+					Log: ['Parameter sweep complete. Processed ' + tmpCompletedCount + '/' + tmpTotalCount + ' set(s).']
+				});
+		}
+
+		// Emit the next parameter set
+		let tmpNext = tmpSets[tmpNextIndex] || {};
+		let tmpOutputs = this._buildOutputs(tmpSets, tmpNext, tmpNextIndex, tmpCompletedCount);
+
+		return fCallback(null,
+			{
+				EventToFire: 'ParameterSetReady',
+				Outputs: tmpOutputs,
+				Log: ['Emitting parameter set ' + (tmpNextIndex + 1) + '/' + tmpTotalCount + '.']
+			});
+	}
+
+	/**
+	 * Build the output object for a given parameter set.
+	 * Includes internal state (_ParameterSets), iteration counters,
+	 * the full current set as JSON, and each individual field flattened.
+	 */
+	_buildOutputs(pSets, pCurrentSet, pIndex, pCompletedCount)
+	{
+		let tmpOutputs =
+		{
+			// Internal state (prefixed with _ so it doesn't show in the flow editor)
+			_ParameterSets: pSets,
+
+			// Iteration counters
+			CurrentParameters: JSON.stringify(pCurrentSet),
+			CurrentIndex: pIndex,
+			TotalCount: pSets.length,
+			CompletedCount: pCompletedCount
+		};
+
+		// Flatten each field from the current parameter set as a top-level output.
+		// This allows direct state wiring: ParameterSweep.seed → Denoise.seed
+		// without the downstream card needing to parse JSON.
+		let tmpKeys = Object.keys(pCurrentSet);
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			let tmpKey = tmpKeys[i];
+			let tmpVal = pCurrentSet[tmpKey];
+			// Coerce to string for consistent state wiring (the engine handles type coercion downstream)
+			tmpOutputs[tmpKey] = (tmpVal === null || tmpVal === undefined) ? '' : String(tmpVal);
+		}
+
+		return tmpOutputs;
+	}
+}
+
+module.exports = TaskTypeParameterSweep;

package/source/services/tasks/flow-control/definitions/parameter-sweep.json

@@ -0,0 +1,36 @@
+{
+	"Hash": "parameter-sweep",
+	"Type": "parameter-sweep",
+	"Name": "Parameter Sweep",
+	"Description": "Iterates over a JSON array of parameter sets, firing one execution per entry. Each entry's fields are exposed as state outputs for downstream cards. Use for batch experiments with different seeds, models, LoRAs, guidance scales, etc.",
+	"Category": "flow-control",
+	"Capability": "Flow Control",
+	"Action": "ParameterSweep",
+	"Tier": "Engine",
+
+	"EventInputs": [
+		{ "Name": "BeginSweep", "Description": "Start iterating through the parameter array" },
+		{ "Name": "StepComplete", "Description": "Signal that the current parameter set has been fully processed by downstream tasks" }
+	],
+
+	"EventOutputs": [
+		{ "Name": "ParameterSetReady", "Description": "Fired for each parameter set in the array. Downstream tasks receive the current parameters via state connections." },
+		{ "Name": "SweepComplete", "Description": "Fired after all parameter sets have been processed." },
+		{ "Name": "Error", "Description": "Fired if the parameter array is invalid or empty.", "IsError": true }
+	],
+
+	"SettingsInputs": [
+		{ "Name": "ParameterSets", "DataType": "String", "Required": true, "Default": "[{\"seed\": 42}, {\"seed\": 123}, {\"seed\": 456}]", "Description": "JSON array of objects. Each object is one set of parameters to sweep through. Example: [{\"seed\": 42, \"guidance\": 5.0}, {\"seed\": 123, \"guidance\": 7.0}]" }
+	],
+
+	"StateOutputs": [
+		{ "Name": "CurrentParameters", "DataType": "String", "Description": "JSON string of the current parameter set object (e.g., {\"seed\": 42, \"guidance\": 5.0})" },
+		{ "Name": "CurrentIndex", "DataType": "Number", "Description": "0-based index of the current parameter set" },
+		{ "Name": "TotalCount", "DataType": "Number", "Description": "Total number of parameter sets in the array" },
+		{ "Name": "CompletedCount", "DataType": "Number", "Description": "Number of parameter sets fully processed so far" }
+	],
+
+	"DefaultSettings": {
+		"ParameterSets": "[{\"seed\": 42}, {\"seed\": 123}, {\"seed\": 456}]"
+	}
+}

package/source/services/tasks/user-interaction/Ultravisor-TaskConfigs-UserInteraction.cjs

@@ -94,7 +94,26 @@ module.exports =
 			let tmpPromptMessage = pResolvedSettings.PromptMessage || 'Please provide a value:';
 			let tmpOutputAddress = pResolvedSettings.OutputAddress || '';
 
-			// Options: accept array (accumulator pattern) or JSON string (legacy)
+			// Auto-resolve: if the output address already has a value in state
+			// (e.g., pre-seeded via /Operation/:Hash/Trigger with Parameters),
+			// skip the pause and fire immediately. This lets operations work both
+			// interactively (flow editor — pauses for input) and programmatically
+			// (API trigger / retold-labs experiment runner — runs straight through).
+			if (tmpOutputAddress && pExecutionContext.StateManager)
+			{
+				let tmpExistingValue = pExecutionContext.StateManager.resolveAddress(
+					tmpOutputAddress, pExecutionContext, pExecutionContext.NodeHash);
+				if (tmpExistingValue !== undefined && tmpExistingValue !== null && tmpExistingValue !== '')
+				{
+					return fCallback(null, {
+						EventToFire: 'ValueInputComplete',
+						Outputs: { InputValue: tmpExistingValue },
+						Log: [`Auto-resolved from pre-seeded state: "${tmpOutputAddress}" = "${String(tmpExistingValue).substring(0, 100)}"`]
+					});
+				}
+			}
+
+			// No pre-seeded value — pause and wait for interactive input
 			let tmpOptions = pResolvedSettings.Options || '';
 			if (Array.isArray(tmpOptions))
 			{

package/test/Ultravisor_tests.js

@@ -190,7 +190,7 @@ suite
 						Expect(tmpInstance.definition.Hash).to.equal('read-file');
 
 						let tmpDefs = tmpRegistry.listDefinitions();
-						Expect(tmpDefs.length).to.equal(53);
+						Expect(tmpDefs.length).to.equal(54);
 
 						// Verify all registered definitions have Capability, Action, and Tier
 						for (let i = 0; i < tmpDefs.length; i++)
@@ -1806,7 +1806,7 @@ suite
 						let tmpBuiltInConfigs = require('../source/services/tasks/Ultravisor-BuiltIn-TaskConfigs.cjs');
 						let tmpCount = tmpRegistry.registerTaskTypesFromConfigArray(tmpBuiltInConfigs);
 
-						Expect(tmpCount).to.equal(53);
+						Expect(tmpCount).to.equal(54);
 
 						// Spot-check a few
 						Expect(tmpRegistry.hasTaskType('error-message')).to.equal(true);
@@ -1991,7 +1991,7 @@ suite
 
 						// Configs already registered by createTestFable — verify all present
 						let tmpDefs = tmpRegistry.listDefinitions();
-						Expect(tmpDefs.length).to.equal(53);
+						Expect(tmpDefs.length).to.equal(54);
 					}
 				);
 			}

package/webinterface/package.json

@@ -36,10 +36,6 @@
 		"whenFileExists": "overwrite"
 	},
 	"copyFiles": [
-		{
-			"from": "./ultravisor-webinterface*",
-			"to": "./dist/"
-		},
 		{
 			"from": "./html/*",
 			"to": "./dist/"