ultravisor-beacon 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,100 @@
+Ultravisor Beacon
+=================
+
+A lightweight beacon client and Fable service for remote task execution. Ultravisor Beacon turns any Node.js application into a distributed worker node that connects to an Ultravisor server, advertises capabilities, and executes work items on demand.
+
+## Features
+
+- **Fable Service Integration** — Register as a service in any Fable/Pict application with `addAndInstantiateServiceType()`
+- **Pluggable Providers** — Built-in Shell, FileSystem, and LLM providers; extend with custom providers via class, factory, or npm package
+- **Automatic Transport** — Tries WebSocket for push-based dispatch, falls back to HTTP polling transparently
+- **File Transfer** — Automatic source file download and output collection with affinity-scoped caching
+- **Multi-Backend LLM** — Unified interface across OpenAI, Anthropic, Ollama, and OpenAI-compatible APIs
+- **Resilient Connectivity** — Auto-reconnect with re-authentication on connection loss
+
+## Documentation
+
+Comprehensive documentation is available in the [docs](./docs) folder:
+
+- [Overview](./docs/README.md) — Introduction and getting started
+- [Quick Start](./docs/quickstart.md) — Step-by-step setup guide
+- [Architecture](./docs/architecture.md) — System design and mermaid diagrams
+- [API Reference](./docs/api/README.md) — All classes and methods
+- [Providers](./docs/providers/README.md) — Built-in and custom providers
+
+## Install
+
+```sh
+$ npm install ultravisor-beacon
+```
+
+## Quick Start
+
+### As a Fable Service
+
+```javascript
+const libFable = require('fable');
+const libBeacon = require('ultravisor-beacon');
+
+let tmpFable = new libFable({ Product: 'MyApp', ProductVersion: '1.0.0' });
+
+tmpFable.addAndInstantiateServiceType('UltravisorBeacon', libBeacon, {
+	ServerURL: 'http://localhost:54321',
+	Name: 'my-app-beacon'
+});
+
+let tmpBeacon = tmpFable.services.UltravisorBeacon;
+
+tmpBeacon.registerCapability({
+	Capability: 'MyApp',
+	actions:
+	{
+		'ProcessData':
+		{
+			Description: 'Process a data payload',
+			Handler: function (pWorkItem, pContext, fCallback)
+			{
+				let tmpResult = doSomeWork(pWorkItem.Settings);
+				return fCallback(null, { Outputs: { Result: tmpResult }, Log: ['Done.'] });
+			}
+		}
+	}
+});
+
+tmpBeacon.enable(function (pError, pBeacon)
+{
+	console.log('Beacon online:', pBeacon.BeaconID);
+});
+```
+
+### Standalone Client
+
+```javascript
+const libBeaconClient = require('ultravisor-beacon').BeaconClient;
+
+let tmpClient = new libBeaconClient({
+	ServerURL: 'http://localhost:54321',
+	Name: 'shell-worker',
+	Capabilities: ['Shell'],
+	MaxConcurrent: 4
+});
+
+tmpClient.start(function (pError, pBeacon)
+{
+	console.log('Worker online:', pBeacon.BeaconID);
+});
+```
+
+## Related Packages
+
+- [fable](https://github.com/stevenvelozo/fable) — Service dependency injection framework
+- [fable-serviceproviderbase](https://github.com/stevenvelozo/fable-serviceproviderbase) — Service provider base class
+- [ultravisor](https://github.com/stevenvelozo/ultravisor) — Process supervision and orchestration server
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/README.md

@@ -0,0 +1,98 @@
+# Ultravisor Beacon
+
+> Lightweight beacon client and Fable service for remote task execution
+
+Ultravisor Beacon turns any Node.js application into a distributed worker node. A beacon connects to an Ultravisor server, advertises the capabilities it can perform, and executes work items dispatched by the orchestrator. It handles authentication, transport negotiation, file transfer, and progress reporting so your application only needs to provide the business logic.
+
+## Features
+
+- **Fable Service Integration** — Register as a service in any Fable/Pict application with `addAndInstantiateServiceType()`
+- **Pluggable Providers** — Built-in Shell, FileSystem, and LLM providers; extend with custom providers via class, factory function, or npm package
+- **Automatic Transport** — Tries WebSocket for push-based dispatch, falls back to HTTP polling transparently; reconnects on disconnect
+- **File Transfer** — Automatic source file download and output collection with affinity-scoped caching for repeated operations
+- **Multi-Backend LLM** — Unified interface across OpenAI, Anthropic, Ollama, and OpenAI-compatible APIs
+- **Resilient Connectivity** — Auto-reconnect with re-authentication on connection loss; WebSocket-to-HTTP fallback
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libBeacon = require('ultravisor-beacon');
+
+let tmpFable = new libFable({ Product: 'MyApp' });
+
+tmpFable.addAndInstantiateServiceType('UltravisorBeacon', libBeacon, {
+	ServerURL: 'http://localhost:54321',
+	Name: 'my-worker'
+});
+
+let tmpBeacon = tmpFable.services.UltravisorBeacon;
+
+tmpBeacon.registerCapability({
+	Capability: 'DataProcessor',
+	actions:
+	{
+		'Transform':
+		{
+			Description: 'Transform a data payload',
+			Handler: function (pWorkItem, pContext, fCallback)
+			{
+				let tmpInput = pWorkItem.Settings.Payload || '';
+				return fCallback(null, {
+					Outputs: { Result: tmpInput.toUpperCase() },
+					Log: ['Transformed payload.']
+				});
+			}
+		}
+	}
+});
+
+tmpBeacon.enable(function (pError, pBeacon)
+{
+	if (pError) throw pError;
+	console.log('Beacon online:', pBeacon.BeaconID);
+});
+```
+
+## Installation
+
+```bash
+npm install ultravisor-beacon
+```
+
+## Core Concepts
+
+### Two Usage Modes
+
+1. **Fable Service** — Use `UltravisorBeaconService` to embed beacon functionality into an existing Fable application. Register capabilities with handler functions and call `enable()`.
+
+2. **Standalone Client** — Use `UltravisorBeaconClient` directly for headless worker nodes. Configure with provider descriptors and call `start()`.
+
+### Capabilities and Providers
+
+A **capability** is a named unit of work a beacon can perform (e.g. `Shell`, `FileSystem`, `LLM`). Each capability has one or more **actions** (e.g. `Execute`, `Read`, `Write`).
+
+A **provider** implements a capability. Built-in providers handle common tasks; custom providers extend `CapabilityProvider` for application-specific work.
+
+### Transport
+
+Beacons auto-negotiate their transport:
+
+1. Try WebSocket — server pushes work items immediately
+2. Fall back to HTTP polling if WebSocket unavailable
+3. Reconnect automatically on disconnection
+
+The coordinator does not track transport type. It checks for a live WebSocket when dispatching and falls through to the queue for polling beacons.
+
+## Documentation
+
+- [Quick Start](quickstart.md) — Step-by-step setup
+- [Architecture](architecture.md) — System design with diagrams
+- [Providers](providers/README.md) — Built-in and custom providers
+- [API Reference](api/README.md) — Complete class and method reference
+
+## Related Packages
+
+- [fable](https://github.com/stevenvelozo/fable) — Service dependency injection framework
+- [fable-serviceproviderbase](https://github.com/stevenvelozo/fable-serviceproviderbase) — Service provider base class
+- [ultravisor](https://github.com/stevenvelozo/ultravisor) — Process supervision and orchestration server

package/docs/_cover.md

@@ -0,0 +1,12 @@
+# Ultravisor Beacon <small>0.0.1</small>
+
+> Lightweight beacon client and Fable service for remote task execution
+
+- Pluggable capability providers (Shell, FileSystem, LLM, custom)
+- Automatic WebSocket push with HTTP polling fallback
+- File transfer with affinity-scoped caching
+- First-class Fable ecosystem integration
+
+[Get Started](quickstart.md)
+[API Reference](api/README.md)
+[GitHub](https://github.com/stevenvelozo/ultravisor-beacon)

package/docs/_sidebar.md

@@ -0,0 +1,31 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Quick Start](quickstart.md)
+  - [Architecture](architecture.md)
+
+- Core Concepts
+
+  - [Providers Overview](providers/README.md)
+  - [Shell](providers/shell.md)
+  - [FileSystem](providers/filesystem.md)
+  - [LLM](providers/llm.md)
+
+- API Reference
+
+  - [Overview](api/README.md)
+
+  - Service
+
+    - [BeaconService](api/beacon-service.md)
+    - [BeaconClient](api/beacon-client.md)
+
+  - Execution
+
+    - [Executor](api/executor.md)
+    - [ProviderRegistry](api/provider-registry.md)
+
+  - Capabilities
+
+    - [CapabilityManager](api/capability-manager.md)
+    - [CapabilityProvider](api/capability-provider.md)

package/docs/_topbar.md

@@ -0,0 +1,4 @@
+[Home](/)
+[Quick Start](quickstart.md)
+[API Reference](api/README.md)
+[GitHub](https://github.com/stevenvelozo/ultravisor-beacon)

package/docs/api/README.md

@@ -0,0 +1,94 @@
+# API Reference
+
+Complete reference documentation for all public classes and methods in the Ultravisor Beacon module.
+
+## Module Exports
+
+```javascript
+const libBeacon = require('ultravisor-beacon');
+```
+
+The default export is `UltravisorBeaconService`. Sub-components are available as named properties:
+
+| Export | Class | Description |
+|--------|-------|-------------|
+| *(default)* | [BeaconService](api/beacon-service.md) | Fable service wrapper |
+| `.BeaconClient` | [BeaconClient](api/beacon-client.md) | Thin client for standalone workers |
+| `.CapabilityManager` | [CapabilityManager](api/capability-manager.md) | Host app capability registry |
+| `.CapabilityAdapter` | CapabilityAdapter | Descriptor-to-provider bridge |
+| `.CapabilityProvider` | [CapabilityProvider](api/capability-provider.md) | Base class for providers |
+| `.ProviderRegistry` | [ProviderRegistry](api/provider-registry.md) | Provider index and router |
+| `.ConnectivityHTTP` | ConnectivityHTTP | HTTP transport configuration |
+| `.ConnectivityWebSocket` | ConnectivityWebSocket | WebSocket transport configuration |
+
+## Class Hierarchy
+
+```
+UltravisorBeaconService (extends FableServiceProviderBase)
+├── CapabilityManager
+├── ConnectivityHTTP
+└── BeaconClient
+    └── Executor
+        └── ProviderRegistry
+            ├── Shell (extends CapabilityProvider)
+            ├── FileSystem (extends CapabilityProvider)
+            ├── LLM (extends CapabilityProvider)
+            └── CapabilityAdapter (extends CapabilityProvider)
+```
+
+## Common Patterns
+
+### Callback Convention
+
+All async methods use Node.js-style callbacks:
+
+```javascript
+function (pError, pResult) { ... }
+```
+
+### Work Item Shape
+
+Work items passed to providers have this structure:
+
+```javascript
+{
+	WorkItemHash: '0x1234abcd',
+	Capability: 'Shell',
+	Action: 'Execute',
+	Settings: { Command: 'echo hello', Parameters: '' },
+	TimeoutMs: 300000,
+	OperationHash: '0xabcd1234'
+}
+```
+
+### Result Shape
+
+Provider execution results follow this format:
+
+```javascript
+{
+	Outputs:
+	{
+		StdOut: 'Command output text',
+		ExitCode: 0,
+		Result: 'Primary result value'
+	},
+	Log: ['Log message 1', 'Log message 2']
+}
+```
+
+### Progress Reporting
+
+Long-running operations can report progress:
+
+```javascript
+fReportProgress({
+	Percent: 50,
+	Message: 'Halfway done',
+	Step: 3,
+	TotalSteps: 6,
+	Log: ['Step 3 complete']
+});
+```
+
+All fields are optional. The beacon client sends progress updates to the server via WebSocket or HTTP.

package/docs/api/beacon-client.md

@@ -0,0 +1,176 @@
+# BeaconClient
+
+A lightweight worker node that connects to an Ultravisor server, registers its capabilities, and executes work items. Used directly for standalone workers or internally by `BeaconService`.
+
+## Constructor
+
+```javascript
+const libBeaconClient = require('ultravisor-beacon').BeaconClient;
+
+let tmpClient = new libBeaconClient(pConfig);
+```
+
+### Config
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `ServerURL` | `string` | `'http://localhost:54321'` | Server endpoint |
+| `Name` | `string` | `'beacon-worker'` | Worker name |
+| `Password` | `string` | `''` | Authentication password |
+| `Capabilities` | `string[]` | `['Shell']` | Legacy: built-in provider names to load |
+| `Providers` | `object[]` | — | Provider descriptors: `[{ Source, Config }]` |
+| `MaxConcurrent` | `number` | `1` | Max parallel work items |
+| `PollIntervalMs` | `number` | `5000` | HTTP poll frequency (ms) |
+| `HeartbeatIntervalMs` | `number` | `30000` | Heartbeat interval (ms) |
+| `ReconnectIntervalMs` | `number` | `10000` | Reconnect delay (ms) |
+| `StagingPath` | `string` | `process.cwd()` | Working directory for file transfer |
+| `Tags` | `object` | `{}` | Metadata tags |
+
+### Provider Loading
+
+If `Providers` is specified, the client loads each descriptor via `ProviderRegistry.loadProvider()`. Otherwise, the legacy `Capabilities` array is converted to provider descriptors automatically (e.g. `['Shell', 'FileSystem']` becomes `[{ Source: 'Shell' }, { Source: 'FileSystem' }]`).
+
+---
+
+## start()
+
+Start the beacon client: initialize providers, authenticate, register, and begin accepting work.
+
+### Signature
+
+```javascript
+client.start(fCallback)
+```
+
+### Callback
+
+```javascript
+function (pError, pBeacon)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `Error\|null` | Error if start failed |
+| `pBeacon` | `object` | `{ BeaconID: '...' }` on success |
+
+### Description
+
+1. Initialize all providers via `providerRegistry.initializeAll()`
+2. Authenticate with `POST /1.0/Authenticate`
+3. Try WebSocket transport (if `ws` library is available)
+4. Fall back to HTTP polling if WebSocket fails
+5. Begin heartbeat at `HeartbeatIntervalMs`
+
+### Transport Auto-Detection
+
+The client automatically tries WebSocket first:
+
+- If the `ws` npm package is installed and the server accepts the upgrade, the client registers over WebSocket and receives pushed work items.
+- If WebSocket fails for any reason (library not installed, server doesn't support it, network blocks upgrades), the client falls back to HTTP polling transparently.
+- No configuration flag is needed.
+
+### Example
+
+```javascript
+let tmpClient = new libBeaconClient({
+	ServerURL: 'http://localhost:54321',
+	Name: 'my-worker',
+	Capabilities: ['Shell', 'FileSystem'],
+	MaxConcurrent: 4
+});
+
+tmpClient.start(function (pError, pBeacon)
+{
+	if (pError)
+	{
+		console.error('Start failed:', pError.message);
+		return;
+	}
+	console.log('Worker online:', pBeacon.BeaconID);
+});
+```
+
+---
+
+## stop()
+
+Stop the beacon client: stop polling, close WebSocket, shutdown providers, deregister.
+
+### Signature
+
+```javascript
+client.stop(fCallback)
+```
+
+### Callback
+
+```javascript
+function (pError)
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pError` | `Error\|null` | Error if shutdown had issues (non-fatal) |
+
+### Description
+
+1. Stop poll and heartbeat intervals
+2. Close WebSocket (sends `Deregister` message first)
+3. Clean up affinity staging directories
+4. Shut down all providers via `providerRegistry.shutdownAll()`
+5. Deregister from the server via `DELETE /Beacon/{id}`
+
+### Example
+
+```javascript
+process.on('SIGTERM', function ()
+{
+	tmpClient.stop(function (pError)
+	{
+		console.log('Worker stopped.');
+		process.exit(0);
+	});
+});
+```
+
+---
+
+## Reconnection
+
+The client handles disconnection automatically:
+
+**HTTP transport** — On a `401 Unauthorized` response, the client re-authenticates, re-registers, and restarts polling.
+
+**WebSocket transport** — On connection close, the client:
+
+1. Re-authenticates (new session cookie)
+2. Tries WebSocket reconnection
+3. If WebSocket fails, falls back to HTTP polling
+4. If HTTP also fails, retries after `ReconnectIntervalMs`
+
+No user intervention is needed. The beacon recovers silently.
+
+---
+
+## WebSocket Protocol
+
+When connected via WebSocket, the client uses JSON messages:
+
+### Client → Server
+
+| Action | Fields | Description |
+|--------|--------|-------------|
+| `BeaconRegister` | `Name`, `Capabilities`, `MaxConcurrent`, `Tags` | Register the beacon |
+| `BeaconHeartbeat` | `BeaconID` | Keep-alive heartbeat |
+| `WorkComplete` | `WorkItemHash`, `Outputs`, `Log` | Report successful execution |
+| `WorkError` | `WorkItemHash`, `ErrorMessage`, `Log` | Report execution failure |
+| `WorkProgress` | `WorkItemHash`, `ProgressData` | Report execution progress |
+| `Deregister` | `BeaconID` | Deregister before disconnect |
+
+### Server → Client
+
+| EventType | Fields | Description |
+|-----------|--------|-------------|
+| `BeaconRegistered` | `BeaconID` | Registration confirmation |
+| `WorkItem` | `WorkItem` | Pushed work item to execute |
+| `Deregistered` | — | Server-initiated deregistration |