Channel drivers

A channel driver connects an external messaging surface to workflows without placing provider-specific code in workflow definitions. Drivers are trusted code loaded by the Faimulus server at restart.

Package contract

Application-owned drivers use workspace/drivers/channel/<name>/manifest.yaml:

apiVersion: 1
kind: channel
type: example
entrypoint: ./driver.ts

The entrypoint exports a ChannelDriverDefinition with a stable type, display name, JSON configuration schema, optional actions, and createChannel(context). Driver and instance types are generated in the channel SDK reference.

Instance lifecycle

The server validates configuration, stores ordinary values and encrypted secrets separately, then calls create. Enabled instances receive start; updates and shutdown receive stop. Implement status with machine-readable state plus diagnostics or presentation blocks. Optional handlers receive run completions, interaction questions, and outbound messages.

Driver context

The context scopes storage and secrets to one instance and supplies an abort signal, structured logger, data directory, workflow discovery, idempotent message submission, interaction-request resolution, event publication, and status publication. Never log message bodies, credentials, QR payloads, or encryption keys.

Channel submissions always deliver interaction requests back to the originating channel. They default to private and non-broadcasted; drivers can override both flags through interactionRequest.

Discovery and dependencies

Workspace drivers are type-checked and compiled at startup. Discovery skips malformed manifests, duplicate types, unsafe entrypoints, compilation failures, and exports that do not implement the contract. In strict discovery mode (the default), these issues fail startup; in degraded mode they are reported and skipped. Workspace drivers execute with server privileges.

Drivers may declare external packages in their own package.json. A shared workspace/drivers/package.json and package-lock.json lock dependencies for memory, provider, and channel drivers. Faimulus installs that production tree into a content-addressed cache below RUN_DATA_DIR and reuses it until the lock or a driver package changes. Registry access is therefore required only for a new dependency hash.

Continue with the implementation reference for the complete adapter example, discovery layout, mounted extensions, and legacy migration procedure.