ultravisor 1.0.3 → 1.0.8

package/source/services/tasks/llm/definitions/llm-tool-use.json

@@ -0,0 +1,42 @@
+{
+	"Hash": "llm-tool-use",
+	"Type": "llm-tool-use",
+	"Name": "LLM Tool Use",
+	"Description": "Sends messages to an LLM with tool/function definitions. Returns both content and tool call results. Supports conversation history.",
+	"Category": "llm",
+	"Capability": "LLM",
+	"Action": "ToolUse",
+	"Tier": "Extension",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "ToolCall" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "SystemPrompt", "DataType": "String", "Required": false, "Description": "System prompt text" },
+		{ "Name": "UserPrompt", "DataType": "String", "Required": false, "Description": "User prompt text" },
+		{ "Name": "Messages", "DataType": "String", "Required": false, "Description": "JSON array of messages for direct control" },
+		{ "Name": "Tools", "DataType": "String", "Required": true, "Description": "JSON array of tool definitions" },
+		{ "Name": "Model", "DataType": "String", "Required": false, "Description": "Override model name" },
+		{ "Name": "ToolChoice", "DataType": "String", "Required": false, "Description": "\"auto\", \"none\", or specific tool name" },
+		{ "Name": "Temperature", "DataType": "Number", "Required": false, "Description": "Sampling temperature" },
+		{ "Name": "MaxTokens", "DataType": "Number", "Required": false, "Description": "Maximum tokens to generate" },
+		{ "Name": "ConversationAddress", "DataType": "String", "Required": false, "Description": "State address for message history" },
+		{ "Name": "AppendToConversation", "DataType": "String", "Required": false, "Description": "Append this exchange to history" },
+		{ "Name": "InputAddress", "DataType": "String", "Required": false, "Description": "State address to read context data from" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to write completion content to" },
+		{ "Name": "AffinityKey", "DataType": "String", "Required": false, "Description": "Route to a specific Beacon worker" },
+		{ "Name": "TimeoutMs", "DataType": "Number", "Required": false, "Description": "Work item timeout in milliseconds" }
+	],
+	"StateOutputs": [
+		{ "Name": "Content", "DataType": "String", "Description": "The LLM text response (may be empty if tool calls)" },
+		{ "Name": "ToolCalls", "DataType": "String", "Description": "JSON array of tool call objects" },
+		{ "Name": "Model", "DataType": "String", "Description": "Model that generated the response" },
+		{ "Name": "FinishReason", "DataType": "String", "Description": "Why the completion ended (stop, tool_calls, etc.)" },
+		{ "Name": "PromptTokens", "DataType": "Number", "Description": "Tokens in the prompt" },
+		{ "Name": "CompletionTokens", "DataType": "Number", "Description": "Tokens in the completion" },
+		{ "Name": "BeaconID", "DataType": "String", "Description": "ID of the Beacon that executed the work" }
+	],
+	"DefaultSettings": { "Temperature": 0.7, "MaxTokens": 4096, "TimeoutMs": 120000, "ToolChoice": "auto" }
+}

package/source/services/tasks/meadow-api/Ultravisor-TaskConfigs-MeadowApi.cjs

@@ -0,0 +1,341 @@
+/**
+ * Task configurations for the "Meadow API" capability.
+ *
+ * REST calls to a Meadow API server for CRUD operations.
+ *
+ * Contains:
+ *   - meadow-read     — Reads a single record by ID from a Meadow REST endpoint.
+ *   - meadow-reads    — Reads multiple records with optional filter.
+ *   - meadow-create   — Creates a new record via a Meadow REST endpoint.
+ *   - meadow-update   — Updates a record via a Meadow REST endpoint.
+ *   - meadow-delete   — Deletes a record by ID via a Meadow REST endpoint.
+ *   - meadow-count    — Counts records for an entity via a Meadow REST endpoint.
+ */
+
+
+// ── Module-scoped helpers ───────────────────────────────────────────
+
+/**
+ * Get a service instance from the fable services map.
+ */
+function _getService(pTask, pTypeName)
+{
+	if (pTask.fable.servicesMap[pTypeName])
+	{
+		return Object.values(pTask.fable.servicesMap[pTypeName])[0];
+	}
+	return null;
+}
+
+/**
+ * Parse headers from a JSON string or return empty object.
+ */
+function _parseHeaders(pHeadersString)
+{
+	if (!pHeadersString || typeof(pHeadersString) !== 'string' || pHeadersString.trim().length === 0)
+	{
+		return {};
+	}
+
+	try
+	{
+		let tmpHeaders = JSON.parse(pHeadersString);
+		if (typeof(tmpHeaders) === 'object' && tmpHeaders !== null)
+		{
+			return tmpHeaders;
+		}
+	}
+	catch (pError)
+	{
+		// Not valid JSON — ignore
+	}
+
+	return {};
+}
+
+
+module.exports =
+[
+	// ── meadow-read ────────────────────────────────────────────
+	{
+		Definition: require('./definitions/meadow-read.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpEntity = pResolvedSettings.Entity || '';
+			let tmpEndpoint = pResolvedSettings.Endpoint || '';
+			let tmpRecordID = pResolvedSettings.RecordID || '';
+
+			if (!tmpEntity || !tmpEndpoint || !tmpRecordID)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowRead: Entity, Endpoint, and RecordID are required.'] });
+			}
+
+			let tmpRestClient = _getService(pTask, 'RestClient');
+			if (!tmpRestClient)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowRead: RestClient service not found.'] });
+			}
+
+			let tmpURL = `${tmpEndpoint}/${tmpEntity}/${tmpRecordID}`;
+
+			tmpRestClient.getJSON({ url: tmpURL, headers: _parseHeaders(pResolvedSettings.Headers) },
+				function (pError, pResponse, pData)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: [`MeadowRead: GET ${tmpURL} failed: ${pError.message}`] });
+					}
+
+					let tmpStateWrites = {};
+					if (pResolvedSettings.Destination)
+					{
+						tmpStateWrites[pResolvedSettings.Destination] = pData;
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: { Record: pData },
+						StateWrites: tmpStateWrites,
+						Log: [`MeadowRead: retrieved ${tmpEntity} #${tmpRecordID}`]
+					});
+				});
+		}
+	},
+
+	// ── meadow-reads ───────────────────────────────────────────
+	{
+		Definition: require('./definitions/meadow-reads.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpEntity = pResolvedSettings.Entity || '';
+			let tmpEndpoint = pResolvedSettings.Endpoint || '';
+
+			if (!tmpEntity || !tmpEndpoint)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowReads: Entity and Endpoint are required.'] });
+			}
+
+			let tmpRestClient = _getService(pTask, 'RestClient');
+			if (!tmpRestClient)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowReads: RestClient service not found.'] });
+			}
+
+			let tmpURL = `${tmpEndpoint}/${tmpEntity}s`;
+			if (pResolvedSettings.Filter)
+			{
+				tmpURL += `/FilteredTo/${pResolvedSettings.Filter}/${pResolvedSettings.PageNumber || 0}/${pResolvedSettings.PageSize || 100}`;
+			}
+
+			tmpRestClient.getJSON({ url: tmpURL, headers: _parseHeaders(pResolvedSettings.Headers) },
+				function (pError, pResponse, pData)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: [`MeadowReads: GET ${tmpURL} failed: ${pError.message}`] });
+					}
+
+					let tmpRecords = Array.isArray(pData) ? pData : [];
+					let tmpStateWrites = {};
+					if (pResolvedSettings.Destination)
+					{
+						tmpStateWrites[pResolvedSettings.Destination] = tmpRecords;
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: { Records: tmpRecords, RecordCount: tmpRecords.length },
+						StateWrites: tmpStateWrites,
+						Log: [`MeadowReads: retrieved ${tmpRecords.length} ${tmpEntity} records`]
+					});
+				});
+		}
+	},
+
+	// ── meadow-create ──────────────────────────────────────────
+	{
+		Definition: require('./definitions/meadow-create.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpEntity = pResolvedSettings.Entity || '';
+			let tmpEndpoint = pResolvedSettings.Endpoint || '';
+
+			if (!tmpEntity || !tmpEndpoint)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowCreate: Entity and Endpoint are required.'] });
+			}
+
+			let tmpRestClient = _getService(pTask, 'RestClient');
+			if (!tmpRestClient)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowCreate: RestClient service not found.'] });
+			}
+
+			let tmpBody = {};
+			if (pResolvedSettings.DataAddress && pExecutionContext.StateManager)
+			{
+				let tmpData = pExecutionContext.StateManager.resolveAddress(pResolvedSettings.DataAddress, pExecutionContext, pExecutionContext.NodeHash);
+				if (typeof(tmpData) === 'object' && tmpData !== null) { tmpBody = tmpData; }
+			}
+
+			tmpRestClient.postJSON({ url: `${tmpEndpoint}/${tmpEntity}`, body: tmpBody, headers: _parseHeaders(pResolvedSettings.Headers) },
+				function (pError, pResponse, pData)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: [`MeadowCreate: POST failed: ${pError.message}`] });
+					}
+
+					let tmpStateWrites = {};
+					if (pResolvedSettings.Destination)
+					{
+						tmpStateWrites[pResolvedSettings.Destination] = pData;
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: { Created: pData },
+						StateWrites: tmpStateWrites,
+						Log: [`MeadowCreate: created ${tmpEntity} record`]
+					});
+				});
+		}
+	},
+
+	// ── meadow-update ──────────────────────────────────────────
+	{
+		Definition: require('./definitions/meadow-update.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpEntity = pResolvedSettings.Entity || '';
+			let tmpEndpoint = pResolvedSettings.Endpoint || '';
+
+			if (!tmpEntity || !tmpEndpoint)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowUpdate: Entity and Endpoint are required.'] });
+			}
+
+			let tmpRestClient = _getService(pTask, 'RestClient');
+			if (!tmpRestClient)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowUpdate: RestClient service not found.'] });
+			}
+
+			let tmpBody = {};
+			if (pResolvedSettings.DataAddress && pExecutionContext.StateManager)
+			{
+				let tmpData = pExecutionContext.StateManager.resolveAddress(pResolvedSettings.DataAddress, pExecutionContext, pExecutionContext.NodeHash);
+				if (typeof(tmpData) === 'object' && tmpData !== null) { tmpBody = tmpData; }
+			}
+
+			tmpRestClient.putJSON({ url: `${tmpEndpoint}/${tmpEntity}`, body: tmpBody, headers: _parseHeaders(pResolvedSettings.Headers) },
+				function (pError, pResponse, pData)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: [`MeadowUpdate: PUT failed: ${pError.message}`] });
+					}
+
+					let tmpStateWrites = {};
+					if (pResolvedSettings.Destination)
+					{
+						tmpStateWrites[pResolvedSettings.Destination] = pData;
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: { Updated: pData },
+						StateWrites: tmpStateWrites,
+						Log: [`MeadowUpdate: updated ${tmpEntity} record`]
+					});
+				});
+		}
+	},
+
+	// ── meadow-delete ──────────────────────────────────────────
+	{
+		Definition: require('./definitions/meadow-delete.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpEntity = pResolvedSettings.Entity || '';
+			let tmpEndpoint = pResolvedSettings.Endpoint || '';
+			let tmpRecordID = pResolvedSettings.RecordID || '';
+
+			if (!tmpEntity || !tmpEndpoint || !tmpRecordID)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowDelete: Entity, Endpoint, and RecordID are required.'] });
+			}
+
+			let tmpRestClient = _getService(pTask, 'RestClient');
+			if (!tmpRestClient)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowDelete: RestClient service not found.'] });
+			}
+
+			tmpRestClient.delJSON({ url: `${tmpEndpoint}/${tmpEntity}/${tmpRecordID}`, headers: _parseHeaders(pResolvedSettings.Headers) },
+				function (pError, pResponse, pData)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: [`MeadowDelete: DELETE failed: ${pError.message}`] });
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Done',
+						Outputs: {},
+						Log: [`MeadowDelete: deleted ${tmpEntity} #${tmpRecordID}`]
+					});
+				});
+		}
+	},
+
+	// ── meadow-count ───────────────────────────────────────────
+	{
+		Definition: require('./definitions/meadow-count.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpEntity = pResolvedSettings.Entity || '';
+			let tmpEndpoint = pResolvedSettings.Endpoint || '';
+
+			if (!tmpEntity || !tmpEndpoint)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowCount: Entity and Endpoint are required.'] });
+			}
+
+			let tmpRestClient = _getService(pTask, 'RestClient');
+			if (!tmpRestClient)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: ['MeadowCount: RestClient service not found.'] });
+			}
+
+			let tmpURL = `${tmpEndpoint}/${tmpEntity}s/Count`;
+			if (pResolvedSettings.Filter)
+			{
+				tmpURL += '/FilteredTo/' + pResolvedSettings.Filter;
+			}
+
+			tmpRestClient.getJSON({ url: tmpURL, headers: _parseHeaders(pResolvedSettings.Headers) },
+				function (pError, pResponse, pData)
+				{
+					if (pError)
+					{
+						return fCallback(null, { EventToFire: 'Error', Outputs: {}, Log: [`MeadowCount: GET failed: ${pError.message}`] });
+					}
+
+					let tmpCount = (typeof(pData) === 'object' && pData !== null && 'Count' in pData) ? pData.Count : pData;
+					let tmpStateWrites = {};
+					if (pResolvedSettings.Destination)
+					{
+						tmpStateWrites[pResolvedSettings.Destination] = tmpCount;
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: { Count: tmpCount },
+						StateWrites: tmpStateWrites,
+						Log: [`MeadowCount: ${tmpEntity} count = ${tmpCount}`]
+					});
+				});
+		}
+	}
+];

package/source/services/tasks/meadow-api/definitions/meadow-count.json

@@ -0,0 +1,26 @@
+{
+	"Hash": "meadow-count",
+	"Type": "meadow-count",
+	"Name": "Meadow Count",
+	"Description": "Counts records for an entity via a Meadow REST endpoint.",
+	"Category": "meadow",
+	"Capability": "Meadow API",
+	"Action": "Count",
+	"Tier": "Service",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Entity", "DataType": "String", "Required": true, "Description": "Entity/table name" },
+		{ "Name": "Endpoint", "DataType": "String", "Required": true, "Description": "Base URL of the Meadow API" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store the count" },
+		{ "Name": "Headers", "DataType": "String", "Required": false, "Description": "JSON string of request headers" },
+		{ "Name": "Filter", "DataType": "String", "Required": false, "Description": "Meadow filter expression" }
+	],
+	"StateOutputs": [
+		{ "Name": "Count", "DataType": "Number", "Description": "Number of records" }
+	],
+	"DefaultSettings": { "Entity": "", "Endpoint": "", "Destination": "", "Headers": "", "Filter": "" }
+}

package/source/services/tasks/meadow-api/definitions/meadow-create.json

@@ -0,0 +1,26 @@
+{
+	"Hash": "meadow-create",
+	"Type": "meadow-create",
+	"Name": "Meadow Create",
+	"Description": "Creates a new record via a Meadow REST endpoint.",
+	"Category": "meadow",
+	"Capability": "Meadow API",
+	"Action": "Create",
+	"Tier": "Service",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Entity", "DataType": "String", "Required": true, "Description": "Entity/table name" },
+		{ "Name": "Endpoint", "DataType": "String", "Required": true, "Description": "Base URL of the Meadow API" },
+		{ "Name": "DataAddress", "DataType": "String", "Required": false, "Description": "State address of the record data to create" },
+		{ "Name": "Headers", "DataType": "String", "Required": false, "Description": "JSON string of request headers" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store the created record" }
+	],
+	"StateOutputs": [
+		{ "Name": "Created", "DataType": "Object", "Description": "The created record" }
+	],
+	"DefaultSettings": { "Entity": "", "Endpoint": "", "DataAddress": "", "Headers": "", "Destination": "" }
+}

package/source/services/tasks/meadow-api/definitions/meadow-delete.json

@@ -0,0 +1,23 @@
+{
+	"Hash": "meadow-delete",
+	"Type": "meadow-delete",
+	"Name": "Meadow Delete",
+	"Description": "Deletes a record by ID via a Meadow REST endpoint.",
+	"Category": "meadow",
+	"Capability": "Meadow API",
+	"Action": "Delete",
+	"Tier": "Service",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Done" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Entity", "DataType": "String", "Required": true, "Description": "Entity/table name" },
+		{ "Name": "Endpoint", "DataType": "String", "Required": true, "Description": "Base URL of the Meadow API" },
+		{ "Name": "RecordID", "DataType": "String", "Required": true, "Description": "ID of the record to delete" },
+		{ "Name": "Headers", "DataType": "String", "Required": false, "Description": "JSON string of request headers" }
+	],
+	"StateOutputs": [],
+	"DefaultSettings": { "Entity": "", "Endpoint": "", "RecordID": "", "Headers": "" }
+}

package/source/services/tasks/meadow-api/definitions/meadow-read.json

@@ -0,0 +1,26 @@
+{
+	"Hash": "meadow-read",
+	"Type": "meadow-read",
+	"Name": "Meadow Read",
+	"Description": "Reads a single record by ID from a Meadow REST endpoint.",
+	"Category": "meadow",
+	"Capability": "Meadow API",
+	"Action": "Read",
+	"Tier": "Service",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Entity", "DataType": "String", "Required": true, "Description": "Entity/table name" },
+		{ "Name": "Endpoint", "DataType": "String", "Required": true, "Description": "Base URL of the Meadow API" },
+		{ "Name": "RecordID", "DataType": "String", "Required": true, "Description": "ID of the record to read" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store the record" },
+		{ "Name": "Headers", "DataType": "String", "Required": false, "Description": "JSON string of request headers" }
+	],
+	"StateOutputs": [
+		{ "Name": "Record", "DataType": "Object", "Description": "The retrieved record" }
+	],
+	"DefaultSettings": { "Entity": "", "Endpoint": "", "RecordID": "", "Destination": "", "Headers": "" }
+}

package/source/services/tasks/meadow-api/definitions/meadow-reads.json

@@ -0,0 +1,29 @@
+{
+	"Hash": "meadow-reads",
+	"Type": "meadow-reads",
+	"Name": "Meadow Reads",
+	"Description": "Reads multiple records from a Meadow REST endpoint with optional filter.",
+	"Category": "meadow",
+	"Capability": "Meadow API",
+	"Action": "ReadMany",
+	"Tier": "Service",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Entity", "DataType": "String", "Required": true, "Description": "Entity/table name" },
+		{ "Name": "Endpoint", "DataType": "String", "Required": true, "Description": "Base URL of the Meadow API" },
+		{ "Name": "Filter", "DataType": "String", "Required": false, "Description": "Meadow filter expression" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store the records" },
+		{ "Name": "Headers", "DataType": "String", "Required": false, "Description": "JSON string of request headers" },
+		{ "Name": "PageSize", "DataType": "Number", "Required": false, "Description": "Number of records per page" },
+		{ "Name": "PageNumber", "DataType": "Number", "Required": false, "Description": "Page number (0-indexed)" }
+	],
+	"StateOutputs": [
+		{ "Name": "Records", "DataType": "Array", "Description": "Retrieved records" },
+		{ "Name": "RecordCount", "DataType": "Number", "Description": "Number of records returned" }
+	],
+	"DefaultSettings": { "Entity": "", "Endpoint": "", "Filter": "", "Destination": "", "Headers": "", "PageSize": 100, "PageNumber": 0 }
+}

package/source/services/tasks/meadow-api/definitions/meadow-update.json

@@ -0,0 +1,26 @@
+{
+	"Hash": "meadow-update",
+	"Type": "meadow-update",
+	"Name": "Meadow Update",
+	"Description": "Updates a record via a Meadow REST endpoint.",
+	"Category": "meadow",
+	"Capability": "Meadow API",
+	"Action": "Update",
+	"Tier": "Service",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Entity", "DataType": "String", "Required": true, "Description": "Entity/table name" },
+		{ "Name": "Endpoint", "DataType": "String", "Required": true, "Description": "Base URL of the Meadow API" },
+		{ "Name": "DataAddress", "DataType": "String", "Required": false, "Description": "State address of the record data to update" },
+		{ "Name": "Headers", "DataType": "String", "Required": false, "Description": "JSON string of request headers" },
+		{ "Name": "Destination", "DataType": "String", "Required": false, "Description": "State address to store the updated record" }
+	],
+	"StateOutputs": [
+		{ "Name": "Updated", "DataType": "Object", "Description": "The updated record" }
+	],
+	"DefaultSettings": { "Entity": "", "Endpoint": "", "DataAddress": "", "Headers": "", "Destination": "" }
+}

package/source/services/tasks/shell/Ultravisor-TaskConfigs-Shell.cjs

@@ -0,0 +1,63 @@
+/**
+ * Task configurations for the "Shell" capability.
+ *
+ * Contains:
+ *   - command   — Executes a shell command on the server.
+ */
+
+const libChildProcess = require('child_process');
+const libPath = require('path');
+
+
+module.exports =
+[
+	// ── command ─────────────────────────────────────────────────
+	{
+		Definition: require('./definitions/command.json'),
+		Execute: function (pTask, pResolvedSettings, pExecutionContext, fCallback)
+		{
+			let tmpCommand = pResolvedSettings.Command || '';
+			let tmpParameters = pResolvedSettings.Parameters || '';
+
+			if (!tmpCommand)
+			{
+				return fCallback(null, { EventToFire: 'Error', Outputs: { StdOut: '', StdErr: '', ExitCode: -1 }, Log: ['Command: no command specified.'] });
+			}
+
+			let tmpFullCommand = tmpParameters ? (tmpCommand + ' ' + tmpParameters) : tmpCommand;
+
+			let tmpBasePath = pExecutionContext.StagingPath || process.cwd();
+			let tmpCwd = pResolvedSettings.WorkingDirectory
+				? libPath.resolve(tmpBasePath, pResolvedSettings.WorkingDirectory)
+				: tmpBasePath;
+
+			let tmpExecOptions = { cwd: tmpCwd, timeout: pResolvedSettings.TimeoutMs || 300000 };
+
+			if (pResolvedSettings.Environment)
+			{
+				let tmpEnv = {};
+				try { tmpEnv = JSON.parse(pResolvedSettings.Environment); } catch(e) {}
+				tmpExecOptions.env = Object.assign({}, process.env, tmpEnv);
+			}
+
+			libChildProcess.exec(tmpFullCommand, tmpExecOptions,
+				function (pError, pStdOut, pStdErr)
+				{
+					if (pError)
+					{
+						return fCallback(null, {
+							EventToFire: 'Error',
+							Outputs: { StdOut: pStdOut || '', StdErr: pStdErr || '', ExitCode: pError.code || 1 },
+							Log: [`Command failed: ${pError.message}`, pStdErr || '']
+						});
+					}
+
+					return fCallback(null, {
+						EventToFire: 'Complete',
+						Outputs: { StdOut: pStdOut || '', StdErr: pStdErr || '', ExitCode: 0 },
+						Log: [`Command executed: ${tmpFullCommand}`]
+					});
+				});
+		}
+	}
+];

package/source/services/tasks/shell/definitions/command.json

@@ -0,0 +1,29 @@
+{
+	"Hash": "command",
+	"Type": "command",
+	"Name": "Command",
+	"Description": "Executes a shell command on the server.",
+	"Category": "control",
+	"Capability": "Shell",
+	"Action": "Execute",
+	"Tier": "Platform",
+	"EventInputs": [{ "Name": "Trigger" }],
+	"EventOutputs": [
+		{ "Name": "Complete" },
+		{ "Name": "Error", "IsError": true }
+	],
+	"SettingsInputs": [
+		{ "Name": "Command", "DataType": "String", "Required": true, "Description": "Shell command to execute" },
+		{ "Name": "Parameters", "DataType": "String", "Required": false, "Description": "Command-line parameters" },
+		{ "Name": "Description", "DataType": "String", "Required": false, "Description": "Human-readable description of this command" },
+		{ "Name": "WorkingDirectory", "DataType": "String", "Required": false, "Description": "Working directory for the command" },
+		{ "Name": "TimeoutMs", "DataType": "Number", "Required": false, "Description": "Command timeout in milliseconds (default 300000)" },
+		{ "Name": "Environment", "DataType": "String", "Required": false, "Description": "JSON object of environment variables to set" }
+	],
+	"StateOutputs": [
+		{ "Name": "StdOut", "DataType": "String", "Description": "Standard output from the command" },
+		{ "Name": "StdErr", "DataType": "String", "Description": "Standard error from the command" },
+		{ "Name": "ExitCode", "DataType": "Number", "Description": "Exit code of the command" }
+	],
+	"DefaultSettings": { "Command": "", "Parameters": "", "Description": "", "WorkingDirectory": "", "TimeoutMs": 300000, "Environment": "" }
+}