ultravisor 1.0.3 → 1.0.8

package/source/services/Ultravisor-TaskTypeRegistry.cjs

@@ -0,0 +1,213 @@
+const libPictService = require('pict-serviceproviderbase');
+
+/**
+ * Registry of all available task type classes and configs.
+ *
+ * Task types can be registered either as classes (via registerTaskType) or
+ * as config objects (via registerTaskTypeFromConfig).  Both paths produce
+ * instances that the ExecutionEngine can execute.
+ */
+class UltravisorTaskTypeRegistry extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeRegistry';
+
+		// Map of task type hash -> task type class (class-based registration)
+		this._TaskTypes = {};
+
+		// Map of task type hash -> config object (config-based registration)
+		this._TaskTypeConfigs = {};
+
+		// Map of task type hash -> definition (cached from either path)
+		this._Definitions = {};
+	}
+
+	/**
+	 * Register a task type class.
+	 *
+	 * @param {Function} pTaskTypeClass - A class extending UltravisorTaskType.
+	 * @returns {object|false} The task type definition, or false on failure.
+	 */
+	registerTaskType(pTaskTypeClass)
+	{
+		if (typeof(pTaskTypeClass) !== 'function')
+		{
+			this.log.error('UltravisorTaskTypeRegistry: registerTaskType requires a constructor function.');
+			return false;
+		}
+
+		// Instantiate temporarily to read the definition
+		let tmpInstance = new pTaskTypeClass(this.fable, {}, `TaskType-Probe-${Date.now()}`);
+		let tmpDefinition = tmpInstance.definition;
+
+		if (!tmpDefinition || !tmpDefinition.Hash)
+		{
+			this.log.error('UltravisorTaskTypeRegistry: task type class must have a definition with a Hash.');
+			return false;
+		}
+
+		this._TaskTypes[tmpDefinition.Hash] = pTaskTypeClass;
+		this._Definitions[tmpDefinition.Hash] = tmpDefinition;
+
+		this.log.info(`UltravisorTaskTypeRegistry: registered task type [${tmpDefinition.Hash}] "${tmpDefinition.Name}"`);
+
+		return tmpDefinition;
+	}
+
+	/**
+	 * Register a task type from a config object.
+	 *
+	 * @param {object} pConfig - Config object with:
+	 *   Definition  {object}   - Task type definition (Hash, Name, EventInputs, etc.)
+	 *   Execute     {function} - Optional. function(pTaskInstance, pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	 * @returns {object|false} The task type definition, or false on failure.
+	 */
+	registerTaskTypeFromConfig(pConfig)
+	{
+		if (!pConfig || typeof(pConfig) !== 'object')
+		{
+			this.log.error('UltravisorTaskTypeRegistry: registerTaskTypeFromConfig requires a config object.');
+			return false;
+		}
+
+		let tmpDefinition = pConfig.Definition;
+
+		if (!tmpDefinition || !tmpDefinition.Hash)
+		{
+			this.log.error('UltravisorTaskTypeRegistry: config must have a Definition with a Hash.');
+			return false;
+		}
+
+		this._TaskTypeConfigs[tmpDefinition.Hash] = pConfig;
+		this._Definitions[tmpDefinition.Hash] = tmpDefinition;
+
+		this.log.info(`UltravisorTaskTypeRegistry: registered config-driven task type [${tmpDefinition.Hash}] "${tmpDefinition.Name}"`);
+
+		return tmpDefinition;
+	}
+
+	/**
+	 * Register multiple task types from an array of config objects.
+	 *
+	 * @param {Array} pConfigs - Array of config objects.
+	 * @returns {number} Number of successfully registered task types.
+	 */
+	registerTaskTypesFromConfigArray(pConfigs)
+	{
+		if (!Array.isArray(pConfigs))
+		{
+			this.log.error('UltravisorTaskTypeRegistry: registerTaskTypesFromConfigArray requires an array.');
+			return 0;
+		}
+
+		let tmpCount = 0;
+
+		for (let i = 0; i < pConfigs.length; i++)
+		{
+			if (this.registerTaskTypeFromConfig(pConfigs[i]))
+			{
+				tmpCount++;
+			}
+		}
+
+		return tmpCount;
+	}
+
+	/**
+	 * Create a new instance of a task type by hash.
+	 *
+	 * Checks config-driven tasks first, then falls back to class-based tasks.
+	 *
+	 * @param {string} pHash - The task type hash (e.g. 'read-file').
+	 * @returns {object|null} A new instance of the task type, or null if not found.
+	 */
+	instantiateTaskType(pHash)
+	{
+		// Check config-driven tasks first
+		let tmpConfig = this._TaskTypeConfigs[pHash];
+
+		if (tmpConfig)
+		{
+			let tmpBaseClass = require('./tasks/Ultravisor-TaskType-Base.cjs');
+			let tmpOptions =
+			{
+				Definition: tmpConfig.Definition
+			};
+
+			if (typeof(tmpConfig.Execute) === 'function')
+			{
+				tmpOptions.Execute = tmpConfig.Execute;
+			}
+
+			return new tmpBaseClass(this.fable, tmpOptions, `TaskType-${pHash}-${Date.now()}`);
+		}
+
+		// Fall back to class-based tasks
+		let tmpTaskTypeClass = this._TaskTypes[pHash];
+
+		if (!tmpTaskTypeClass)
+		{
+			this.log.error(`UltravisorTaskTypeRegistry: unknown task type hash [${pHash}]`);
+			return null;
+		}
+
+		return new tmpTaskTypeClass(this.fable, {}, `TaskType-${pHash}-${Date.now()}`);
+	}
+
+	/**
+	 * Get the definition for a task type by hash.
+	 *
+	 * @param {string} pHash - The task type hash.
+	 * @returns {object|null} The definition, or null if not found.
+	 */
+	getDefinition(pHash)
+	{
+		return this._Definitions[pHash] || null;
+	}
+
+	/**
+	 * Get all registered task type definitions.
+	 *
+	 * @returns {Array} Array of definition objects.
+	 */
+	listDefinitions()
+	{
+		let tmpDefinitions = [];
+		let tmpKeys = Object.keys(this._Definitions);
+
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			tmpDefinitions.push(this._Definitions[tmpKeys[i]]);
+		}
+
+		return tmpDefinitions;
+	}
+
+	/**
+	 * Check if a task type hash is registered.
+	 *
+	 * @param {string} pHash - The task type hash.
+	 * @returns {boolean}
+	 */
+	hasTaskType(pHash)
+	{
+		return this._TaskTypes.hasOwnProperty(pHash) || this._TaskTypeConfigs.hasOwnProperty(pHash);
+	}
+
+	/**
+	 * Register all built-in task types.
+	 * Called during application initialization.
+	 */
+	registerBuiltInTaskTypes()
+	{
+		let tmpBuiltInConfigs = require('./tasks/Ultravisor-BuiltIn-TaskConfigs.cjs');
+		this.registerTaskTypesFromConfigArray(tmpBuiltInConfigs);
+
+		this.log.info(`UltravisorTaskTypeRegistry: ${Object.keys(this._Definitions).length} built-in task types registered.`);
+	}
+}
+
+module.exports = UltravisorTaskTypeRegistry;

package/source/services/persistence/Ultravisor-Schedule-Persistence-JSONFile.cjs

@@ -0,0 +1,140 @@
+const libSchedulePersistenceBase = require('../Ultravisor-Schedule-Persistence-Base.cjs');
+
+const libFS = require('fs');
+const libPath = require('path');
+
+/**
+ * JSON file–backed schedule persistence provider.
+ *
+ * Stores the schedule array in the same `.ultravisor.json` config file
+ * used by HypervisorState, under the `Schedule` key.  Reads and writes
+ * are synchronous to stay consistent with HypervisorState's approach.
+ *
+ * To use a remote API instead, create a new provider that extends
+ * UltravisorSchedulePersistenceBase and register it under the service
+ * type 'UltravisorSchedulePersistence'.
+ */
+class UltravisorSchedulePersistenceJSONFile extends libSchedulePersistenceBase
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorSchedulePersistence';
+	}
+
+	/**
+	 * Resolve the config file path.
+	 *
+	 * Uses the same logic as HypervisorState.persistState():
+	 * walk the gather-phase list for a non-default path, then fall
+	 * back to ProgramConfigurationFileName relative to cwd.
+	 *
+	 * @returns {string|false} Resolved path, or false if none available.
+	 */
+	_getConfigPath()
+	{
+		let tmpFinalPath = false;
+
+		// Check gathered configuration phases (if available)
+		let tmpOutcome = this.fable._ConfigurationOutcome;
+		if (tmpOutcome && Array.isArray(tmpOutcome.GatherPhases))
+		{
+			for (let i = 0; i < tmpOutcome.GatherPhases.length; i++)
+			{
+				let tmpPhase = tmpOutcome.GatherPhases[i];
+				if ((tmpPhase.Phase !== 'Default Program Configuration') && (tmpPhase.Path))
+				{
+					tmpFinalPath = tmpPhase.Path;
+				}
+			}
+		}
+
+		if (!tmpFinalPath && this.fable.settings && this.fable.settings.ProgramConfigurationFileName)
+		{
+			tmpFinalPath = libPath.resolve(process.cwd(), this.fable.settings.ProgramConfigurationFileName);
+		}
+
+		return tmpFinalPath;
+	}
+
+	/**
+	 * Load the schedule from the JSON config file.
+	 *
+	 * @param {function} fCallback - fCallback(pError, pScheduleArray)
+	 */
+	loadSchedule(fCallback)
+	{
+		let tmpPath = this._getConfigPath();
+
+		if (!tmpPath)
+		{
+			this.log.warn('UltravisorSchedulePersistenceJSONFile: no config path available; returning empty schedule.');
+			return fCallback(null, []);
+		}
+
+		try
+		{
+			if (!libFS.existsSync(tmpPath))
+			{
+				return fCallback(null, []);
+			}
+
+			let tmpContent = libFS.readFileSync(tmpPath, 'utf8');
+			let tmpConfig = JSON.parse(tmpContent);
+			let tmpSchedule = Array.isArray(tmpConfig.Schedule) ? tmpConfig.Schedule : [];
+
+			return fCallback(null, tmpSchedule);
+		}
+		catch (pError)
+		{
+			this.log.error(`UltravisorSchedulePersistenceJSONFile: load error: ${pError.message}`);
+			return fCallback(null, []);
+		}
+	}
+
+	/**
+	 * Save the schedule to the JSON config file.
+	 *
+	 * Reads the existing file first so other keys (Operations, Templates,
+	 * GlobalState, etc.) are preserved.
+	 *
+	 * @param {Array} pSchedule - The schedule array to persist.
+	 * @param {function} fCallback - fCallback(pError)
+	 */
+	saveSchedule(pSchedule, fCallback)
+	{
+		let tmpPath = this._getConfigPath();
+
+		if (!tmpPath)
+		{
+			this.log.error('UltravisorSchedulePersistenceJSONFile: no config path available; schedule will not be saved.');
+			return fCallback(new Error('No config path available.'));
+		}
+
+		try
+		{
+			// Read existing config so we don't clobber other keys
+			let tmpConfig = {};
+			if (libFS.existsSync(tmpPath))
+			{
+				let tmpContent = libFS.readFileSync(tmpPath, 'utf8');
+				tmpConfig = JSON.parse(tmpContent);
+			}
+
+			tmpConfig.Schedule = pSchedule;
+
+			libFS.writeFileSync(tmpPath, JSON.stringify(tmpConfig, null, '\t'), 'utf8');
+			this.log.info(`UltravisorSchedulePersistenceJSONFile: persisted ${pSchedule.length} schedule entries to ${tmpPath}`);
+
+			return fCallback(null);
+		}
+		catch (pError)
+		{
+			this.log.error(`UltravisorSchedulePersistenceJSONFile: save error: ${pError.message}`);
+			return fCallback(pError);
+		}
+	}
+}
+
+module.exports = UltravisorSchedulePersistenceJSONFile;

package/source/services/tasks/Ultravisor-BuiltIn-TaskConfigs.cjs

@@ -0,0 +1,19 @@
+/**
+ * Built-in task type configurations for Ultravisor.
+ *
+ * Aggregates per-capability config files into a single array.
+ * Each capability folder contains its own config file exporting
+ * an array of task type definitions.
+ */
+module.exports = [].concat(
+	require('./data-transform/Ultravisor-TaskConfigs-DataTransform.cjs'),
+	require('./flow-control/Ultravisor-TaskConfigs-FlowControl.cjs'),
+	require('./file-system/Ultravisor-TaskConfigs-FileSystem.cjs'),
+	require('./shell/Ultravisor-TaskConfigs-Shell.cjs'),
+	require('./http-client/Ultravisor-TaskConfigs-HttpClient.cjs'),
+	require('./user-interaction/Ultravisor-TaskConfigs-UserInteraction.cjs'),
+	require('./meadow-api/Ultravisor-TaskConfigs-MeadowApi.cjs'),
+	require('./extension/Ultravisor-TaskConfigs-Extension.cjs'),
+	require('./llm/Ultravisor-TaskConfigs-LLM.cjs'),
+	require('./content-system/Ultravisor-TaskConfigs-ContentSystem.cjs')
+);

package/source/services/tasks/Ultravisor-TaskHelper-BeaconDispatch.cjs

@@ -0,0 +1,107 @@
+/**
+ * Ultravisor Task Helper — Beacon Dispatch
+ *
+ * Shared helper function for system-specific task types that dispatch
+ * work to beacon workers.  Encapsulates the "enqueue to Beacon
+ * Coordinator + return WaitingForInput" pattern.
+ *
+ * Usage (from a task config Execute function):
+ *
+ *   const beaconDispatch = require('../Ultravisor-TaskHelper-BeaconDispatch.cjs');
+ *
+ *   Execute: function(pTask, pResolvedSettings, pExecutionContext, fCallback)
+ *   {
+ *     beaconDispatch(pTask, {
+ *       Capability: 'ContentSystem',
+ *       Action: 'ReadFile',
+ *       Settings: { FilePath: pResolvedSettings.FilePath },
+ *       AffinityKey: pResolvedSettings.AffinityKey,
+ *       TimeoutMs: pResolvedSettings.TimeoutMs
+ *     }, pExecutionContext, fCallback);
+ *   }
+ */
+
+
+/**
+ * Get a named service from the Fable services map.
+ */
+function _getService(pTask, pTypeName)
+{
+	return pTask.fable.servicesMap[pTypeName]
+		? Object.values(pTask.fable.servicesMap[pTypeName])[0]
+		: null;
+}
+
+
+/**
+ * Dispatch work to a beacon via the BeaconCoordinator.
+ *
+ * @param {object} pTask - The task instance (has pTask.fable, pTask.log)
+ * @param {object} pWorkInfo - Work item description:
+ *   {
+ *     Capability: 'ContentSystem',
+ *     Action: 'ReadFile',
+ *     Settings: { FilePath: '/docs/README.md' },
+ *     AffinityKey: '',       // optional
+ *     TimeoutMs: 300000      // optional
+ *   }
+ * @param {object} pExecutionContext - Has RunHash, NodeHash, OperationHash
+ * @param {function} fCallback - Standard task callback
+ */
+function beaconDispatch(pTask, pWorkInfo, pExecutionContext, fCallback)
+{
+	let tmpCoordinator = _getService(pTask, 'UltravisorBeaconCoordinator');
+
+	if (!tmpCoordinator)
+	{
+		return fCallback(null, {
+			EventToFire: 'Error',
+			Outputs: { StdOut: 'BeaconCoordinator service not available.', Result: '', BeaconID: '' },
+			Log: ['Beacon dispatch: BeaconCoordinator service not found.']
+		});
+	}
+
+	// Check if any beacons are registered
+	let tmpBeacons = tmpCoordinator.listBeacons();
+	if (tmpBeacons.length === 0)
+	{
+		return fCallback(null, {
+			EventToFire: 'Error',
+			Outputs: { StdOut: 'No Beacon workers are registered.', Result: '', BeaconID: '' },
+			Log: ['Beacon dispatch: no Beacon workers registered. Cannot dispatch work.']
+		});
+	}
+
+	// Build work item
+	let tmpWorkItemInfo = {
+		RunHash: pExecutionContext.RunHash,
+		NodeHash: pExecutionContext.NodeHash,
+		OperationHash: pExecutionContext.OperationHash,
+		Capability: pWorkInfo.Capability || 'Unknown',
+		Action: pWorkInfo.Action || '',
+		Settings: pWorkInfo.Settings || {},
+		AffinityKey: pWorkInfo.AffinityKey || '',
+		TimeoutMs: pWorkInfo.TimeoutMs || 300000
+	};
+
+	// Enqueue the work item
+	let tmpWorkItem = tmpCoordinator.enqueueWorkItem(tmpWorkItemInfo);
+
+	pTask.log.info(`Beacon dispatch [${pWorkInfo.Capability}/${pWorkInfo.Action}]: enqueued [${tmpWorkItem.WorkItemHash}]` +
+		(tmpWorkItemInfo.AffinityKey ? ` with affinity [${tmpWorkItemInfo.AffinityKey}]` : ''));
+
+	// Pause execution — the BeaconCoordinator will call resumeOperation when the beacon reports back
+	return fCallback(null, {
+		WaitingForInput: true,
+		ResumeEventName: 'Complete',
+		PromptMessage: `Waiting for Beacon (${pWorkInfo.Capability}/${pWorkInfo.Action})`,
+		OutputAddress: '',
+		Outputs: {},
+		Log: [
+			`Beacon dispatch: dispatched as [${tmpWorkItem.WorkItemHash}].`,
+			`Capability: ${tmpWorkItemInfo.Capability}, Action: ${tmpWorkItemInfo.Action}`
+		]
+	});
+}
+
+module.exports = beaconDispatch;

package/source/services/tasks/Ultravisor-TaskType-Base.cjs

@@ -0,0 +1,125 @@
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+/**
+ * Base class for all Ultravisor task types.
+ *
+ * Subclasses override `definition` to declare their port schema
+ * (EventInputs, EventOutputs, SettingsInputs, StateOutputs)
+ * and `execute` to implement the task logic.
+ */
+class UltravisorTaskType extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskType';
+	}
+
+	/**
+	 * Port schema and metadata for this task type.
+	 * Subclasses MUST override this getter.
+	 *
+	 * @returns {object} Task type definition with:
+	 *   Hash            {string}   - unique type identifier (e.g. 'read-file')
+	 *   Name            {string}   - display name
+	 *   Description     {string}   - what the task does
+	 *   Category        {string}   - grouping key (file-io, data, control, interaction)
+	 *   Capability      {string}   - capability grouping for worker dispatch (e.g. 'File System', 'Data Transform')
+	 *   Action          {string}   - verb within the capability (e.g. 'Read', 'Write')
+	 *   Tier            {string}   - capability tier: 'Engine' | 'Platform' | 'Service' | 'Extension'
+	 *   EventInputs     {Array}    - [{ Name, Description? }]
+	 *   EventOutputs    {Array}    - [{ Name, Description?, IsError? }]
+	 *   SettingsInputs  {Array}    - [{ Name, DataType, Required?, Default?, Description? }]
+	 *   StateOutputs    {Array}    - [{ Name, DataType?, Description? }]
+	 *   DefaultSettings {object}   - default values for SettingsInputs
+	 */
+	get definition()
+	{
+		// Config-driven: if Definition was provided in options, use it
+		if (this.options.Definition && typeof(this.options.Definition) === 'object'
+			&& this.options.Definition.Hash)
+		{
+			return this.options.Definition;
+		}
+
+		// Default fallback (overridden by subclasses)
+		return {
+			Hash: 'base',
+			Name: 'Base Task',
+			Description: 'Override this in subclasses.',
+			Category: 'internal',
+			Capability: 'Internal',
+			Action: 'Base',
+			Tier: 'Engine',
+			EventInputs: [],
+			EventOutputs: [],
+			SettingsInputs: [],
+			StateOutputs: [],
+			DefaultSettings: {}
+		};
+	}
+
+	/**
+	 * Execute the task.
+	 *
+	 * @param {object} pResolvedSettings - The task's Settings with incoming
+	 *   State connections already resolved by the engine.
+	 * @param {object} pExecutionContext - Runtime context:
+	 *   GlobalState     {object}  - state shared across all operations
+	 *   OperationState  {object}  - state shared across tasks in this run
+	 *   TaskOutputs     {object}  - keyed by NodeHash, per-task output state
+	 *   StagingPath     {string}  - path to the operation's staging folder
+	 *   OperationHash   {string}  - the operation being executed
+	 *   NodeHash        {string}  - this task node's hash in the graph
+	 *   RunHash         {string}  - the execution run hash
+	 *   RunMode         {string}  - 'production' | 'standard' | 'debug'
+	 *   StateManager    {object}  - reference to the StateManager service
+	 *   TriggeringEventName {string} - the event that triggered this execution
+	 *     (e.g. 'PerformSplit', 'StepComplete') — lets state-machine tasks
+	 *     distinguish which input event caused the current invocation.
+	 * @param {function} fCallback - function(pError, pResult) where pResult is:
+	 *   EventToFire  {string}  - which output event to fire (e.g. 'ReadComplete')
+	 *   Outputs      {object}  - key/value pairs written to TaskOutputs[NodeHash]
+	 *   Log          {Array}   - array of log message strings
+	 * @param {function} [fFireIntermediateEvent] - Optional. For re-entrant
+	 *   tasks (like split-execute) that fire events multiple times.
+	 *   Signature: fFireIntermediateEvent(pEventName, pOutputs, fResumeCallback)
+	 */
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		// Config-driven: if Execute function was provided in options, call it
+		if (typeof(this.options.Execute) === 'function')
+		{
+			return this.options.Execute(this, pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent);
+		}
+
+		return fCallback(new Error(`Task type "${this.definition.Hash}" has not implemented execute().`));
+	}
+
+	/**
+	 * Resolve a file path relative to the staging folder if it is not absolute.
+	 *
+	 * @param {string} pFilePath - The file path from settings.
+	 * @param {string} pStagingPath - The operation's staging folder.
+	 * @returns {string} Resolved absolute path.
+	 */
+	resolveFilePath(pFilePath, pStagingPath)
+	{
+		if (!pFilePath || typeof(pFilePath) !== 'string')
+		{
+			return pStagingPath || '';
+		}
+
+		const libPath = require('path');
+
+		if (libPath.isAbsolute(pFilePath))
+		{
+			return pFilePath;
+		}
+
+		return libPath.resolve(pStagingPath || process.cwd(), pFilePath);
+	}
+}
+
+module.exports = UltravisorTaskType;

package/source/services/tasks/content-system/Ultravisor-TaskConfigs-ContentSystem.cjs

@@ -0,0 +1,90 @@
+/**
+ * Task configurations for the "ContentSystem" capability.
+ *
+ * Provides dedicated cards for remote-controlling a retold-content-system
+ * beacon.  Each task dispatches to a beacon advertising the ContentSystem
+ * capability, using the shared beacon dispatch helper.
+ *
+ * Cards:
+ *   - content-read-file    — Read a markdown/content file
+ *   - content-save-file    — Save content to a file
+ *   - content-list-files   — List files in a content directory
+ *   - content-create-folder — Create a folder in the content directory
+ */
+
+const beaconDispatch = require('../Ultravisor-TaskHelper-BeaconDispatch.cjs');
+
+
+module.exports =
+[
+	// ── content-read-file ─────────────────────────────────────────
+	{
+		Definition: require('./definitions/content-read-file.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			beaconDispatch(pTask, {
+				Capability: 'ContentSystem',
+				Action: 'ReadFile',
+				Settings: {
+					FilePath: pResolvedSettings.FilePath || ''
+				},
+				AffinityKey: pResolvedSettings.AffinityKey,
+				TimeoutMs: pResolvedSettings.TimeoutMs
+			}, pExecutionContext, fCallback);
+		}
+	},
+
+	// ── content-save-file ─────────────────────────────────────────
+	{
+		Definition: require('./definitions/content-save-file.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			beaconDispatch(pTask, {
+				Capability: 'ContentSystem',
+				Action: 'SaveFile',
+				Settings: {
+					FilePath: pResolvedSettings.FilePath || '',
+					Content: pResolvedSettings.Content || ''
+				},
+				AffinityKey: pResolvedSettings.AffinityKey,
+				TimeoutMs: pResolvedSettings.TimeoutMs
+			}, pExecutionContext, fCallback);
+		}
+	},
+
+	// ── content-list-files ────────────────────────────────────────
+	{
+		Definition: require('./definitions/content-list-files.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			beaconDispatch(pTask, {
+				Capability: 'ContentSystem',
+				Action: 'ListFiles',
+				Settings: {
+					Path: pResolvedSettings.Path || '',
+					Pattern: pResolvedSettings.Pattern || '',
+					Recursive: pResolvedSettings.Recursive || false
+				},
+				AffinityKey: pResolvedSettings.AffinityKey,
+				TimeoutMs: pResolvedSettings.TimeoutMs
+			}, pExecutionContext, fCallback);
+		}
+	},
+
+	// ── content-create-folder ─────────────────────────────────────
+	{
+		Definition: require('./definitions/content-create-folder.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			beaconDispatch(pTask, {
+				Capability: 'ContentSystem',
+				Action: 'CreateFolder',
+				Settings: {
+					Path: pResolvedSettings.Path || ''
+				},
+				AffinityKey: pResolvedSettings.AffinityKey,
+				TimeoutMs: pResolvedSettings.TimeoutMs
+			}, pExecutionContext, fCallback);
+		}
+	}
+];