@pellux/goodvibes-tui 0.24.1 → 0.25.0

package/src/daemon/remote/backends/types.ts

@@ -0,0 +1,71 @@
+import type { DaemonCredentialStore } from '../../operator/index.ts';
+import type { OperatorLogger } from '../../operator/index.ts';
+import type { PeerRecord } from '../peer-registry.ts';
+
+/**
+ * Payload accepted alongside a command on remote.peers.invoke. All fields are
+ * optional; backends interpret what they support.
+ */
+export interface DispatchPayload {
+  /** Positional args appended to the command (already tokenized). */
+  args?: string[];
+  /** Data piped to the process stdin. */
+  stdin?: string;
+  /** Per-invocation environment overlay (never includes secrets). */
+  env?: Record<string, string>;
+  /** Hard timeout for synchronous execution, in milliseconds. */
+  timeoutMs?: number;
+  /** Working directory override (backend-dependent). */
+  cwd?: string;
+}
+
+export interface BackendDispatchResult {
+  exitCode?: number;
+  workId?: string;
+  stdout: string;
+  stderr: string;
+}
+
+export interface BackendContext {
+  credentials: DaemonCredentialStore;
+  logger: OperatorLogger;
+  /** Daemon home dir — used for ephemeral key material under a 0700 subdir. */
+  homeDirectory: string;
+}
+
+/**
+ * A remote execution backend. Each backend dispatches a single command for a
+ * given peer and returns the captured stdout/stderr plus an exit code.
+ *
+ * Backends must NEVER place raw credentials in the returned stdout/stderr or in
+ * any thrown error message. Credentials are resolved internally from the daemon
+ * credential store via secret references on the peer's backendConfig.
+ */
+export interface Backend {
+  readonly kind: PeerRecord['backendKind'];
+  dispatch(
+    peer: PeerRecord,
+    command: string,
+    payload?: DispatchPayload,
+  ): Promise<BackendDispatchResult>;
+}
+
+export const DEFAULT_SYNC_TIMEOUT_MS = 120_000;
+export const MAX_SYNC_TIMEOUT_MS = 600_000;
+
+export function resolveTimeout(payload?: DispatchPayload): number {
+  const requested = payload?.timeoutMs;
+  if (typeof requested === 'number' && Number.isFinite(requested) && requested > 0) {
+    return Math.min(requested, MAX_SYNC_TIMEOUT_MS);
+  }
+  return DEFAULT_SYNC_TIMEOUT_MS;
+}
+
+export class BackendDispatchError extends Error {
+  readonly code: string;
+  constructor(message: string, code = 'REMOTE_BACKEND_DISPATCH_FAILED') {
+    super(message);
+    this.name = 'BackendDispatchError';
+    this.code = code;
+  }
+}

package/src/daemon/remote/dispatcher.ts

@@ -0,0 +1,160 @@
+import { sha256First } from '../operator/index.ts';
+import type { OperatorLogger, DaemonCredentialStore } from '../operator/index.ts';
+import { PeerRegistry, type PeerRecord } from './peer-registry.ts';
+import {
+  type Backend,
+  type BackendContext,
+  type DispatchPayload,
+  BackendDispatchError,
+  createBackends,
+} from './backends/index.ts';
+
+// ---------------------------------------------------------------------------
+// Work-item hook — long-running invocations are enqueued as work items visible
+// in remote.work.list. The surface does not own the distributed runtime; the
+// integrator wires this hook to the existing remoteRunnerRegistry.
+// ---------------------------------------------------------------------------
+
+export interface RemoteWorkItemInput {
+  peerId: string;
+  command: string;
+  payload?: DispatchPayload;
+  /** Echoed onto the work item so the runner can pick the right backend. */
+  backendKind: PeerRecord['backendKind'];
+  queuedBy: string;
+}
+
+export interface RemoteWorkEnqueuer {
+  enqueue(item: RemoteWorkItemInput): Promise<{ workId: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Invoke result — returned to the agent through remote.peers.invoke. Includes
+// stdoutDigest (sha256 of FULL stdout, 64 hex chars) per the receipt contract.
+// The agent may receive only a truncated stdout preview.
+// ---------------------------------------------------------------------------
+
+export const STDOUT_PREVIEW_LIMIT = 4_096;
+
+export interface RemoteInvokeResult {
+  peerId: string;
+  backendKind: PeerRecord['backendKind'];
+  /** Present for synchronous completion. */
+  exitCode?: number;
+  /** Present for async/long-running dispatch. */
+  workId?: string;
+  completed: boolean;
+  stdout: string;
+  stderr: string;
+  /** SHA-256 of the full stdout, 64 hex chars. */
+  stdoutDigest: string;
+}
+
+export interface RemoteDispatcherOptions {
+  registry: PeerRegistry;
+  credentials: DaemonCredentialStore;
+  logger: OperatorLogger;
+  homeDirectory: string;
+  /** Optional hook for enqueuing long-running work items. */
+  workEnqueuer?: RemoteWorkEnqueuer;
+  /** Override the backend map (tests inject fakes). */
+  backends?: Map<PeerRecord['backendKind'], Backend>;
+}
+
+export interface DispatchRequest {
+  peerId: string;
+  command: string;
+  payload?: DispatchPayload;
+  /** Principal that requested the dispatch (for work-item attribution). */
+  principalId: string;
+  /** When true (and a work enqueuer exists), run as an async work item. */
+  async?: boolean;
+}
+
+function truncate(value: string, limit: number): string {
+  return value.length > limit ? value.slice(0, limit) : value;
+}
+
+/**
+ * Routes remote.peers.invoke commands to the correct execution backend.
+ * Synchronous commands return an exitCode; long-running commands (async:true
+ * with a configured work enqueuer) return a workId tracked via remote.work.list.
+ */
+export class RemoteDispatcher {
+  private readonly registry: PeerRegistry;
+  private readonly backends: Map<PeerRecord['backendKind'], Backend>;
+  private readonly workEnqueuer?: RemoteWorkEnqueuer;
+  private readonly logger: OperatorLogger;
+
+  constructor(options: RemoteDispatcherOptions) {
+    this.registry = options.registry;
+    this.logger = options.logger;
+    if (options.workEnqueuer) this.workEnqueuer = options.workEnqueuer;
+    const backendContext: BackendContext = {
+      credentials: options.credentials,
+      logger: options.logger,
+      homeDirectory: options.homeDirectory,
+    };
+    this.backends = options.backends ?? createBackends(backendContext);
+  }
+
+  async dispatch(request: DispatchRequest): Promise<RemoteInvokeResult> {
+    const peerId = typeof request.peerId === 'string' ? request.peerId.trim() : '';
+    if (peerId.length === 0) {
+      throw new BackendDispatchError('peerId is required.', 'REMOTE_PEER_ID_REQUIRED');
+    }
+    const command = typeof request.command === 'string' ? request.command : '';
+    if (command.trim().length === 0) {
+      throw new BackendDispatchError('command is required.', 'REMOTE_COMMAND_REQUIRED');
+    }
+    const peer = this.registry.get(peerId);
+    if (!peer) {
+      throw new BackendDispatchError(
+        `No registered peer with id '${peerId}'.`,
+        'REMOTE_PEER_NOT_FOUND',
+      );
+    }
+    const backend = this.backends.get(peer.backendKind);
+    if (!backend) {
+      throw new BackendDispatchError(
+        `No backend available for kind '${peer.backendKind}'.`,
+        'REMOTE_BACKEND_UNAVAILABLE',
+      );
+    }
+
+    // Async path: enqueue a work item and return its id immediately.
+    if (request.async === true && this.workEnqueuer) {
+      const { workId } = await this.workEnqueuer.enqueue({
+        peerId: peer.peerId,
+        command,
+        backendKind: peer.backendKind,
+        queuedBy: request.principalId,
+        ...(request.payload !== undefined ? { payload: request.payload } : {}),
+      });
+      this.logger.info('remote invoke enqueued', { peerId: peer.peerId, workId });
+      return {
+        peerId: peer.peerId,
+        backendKind: peer.backendKind,
+        workId,
+        completed: false,
+        stdout: '',
+        stderr: '',
+        stdoutDigest: sha256First('', 64),
+      };
+    }
+
+    // Synchronous path: run on the backend and capture output.
+    const result = await backend.dispatch(peer, command, request.payload);
+    const fullStdout = result.stdout ?? '';
+    return {
+      peerId: peer.peerId,
+      backendKind: peer.backendKind,
+      ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+      ...(result.workId !== undefined ? { workId: result.workId } : {}),
+      completed: result.workId === undefined,
+      stdout: truncate(fullStdout, STDOUT_PREVIEW_LIMIT),
+      stderr: truncate(result.stderr ?? '', STDOUT_PREVIEW_LIMIT),
+      stdoutDigest: sha256First(fullStdout, 64),
+    };
+  }
+}

package/src/daemon/remote/index.ts

@@ -0,0 +1,74 @@
+// Remote Execution Backends surface (Docker / SSH / Cloud Terminal / local).
+//
+// Publishes the daemon-internal `remote.peers.register` operator method and a
+// dispatch adapter for the already-published `remote.peers.invoke` route. The
+// integrator attaches the dispatch adapter to the existing invoke router and
+// (optionally) wires the work enqueuer to the distributed runtime work queue.
+
+export {
+  PeerRegistry,
+  PeerRegistryValidationError,
+  normalizeBackendConfig,
+} from './peer-registry.ts';
+export type {
+  BackendKind,
+  CloudProvider,
+  BackendConfig,
+  DockerBackendConfig,
+  SshBackendConfig,
+  CloudTerminalBackendConfig,
+  LocalProcessBackendConfig,
+  PeerRecord,
+  PeerRegistrationInput,
+} from './peer-registry.ts';
+
+export {
+  createBackends,
+  createLocalProcessBackend,
+  createDockerBackend,
+  createSshBackend,
+  createCloudTerminalBackend,
+  tokenizeCommand,
+  runProcess,
+  BackendDispatchError,
+  resolveTimeout,
+  DEFAULT_SYNC_TIMEOUT_MS,
+  MAX_SYNC_TIMEOUT_MS,
+} from './backends/index.ts';
+export type {
+  Backend,
+  BackendContext,
+  BackendDispatchResult,
+  DispatchPayload,
+  RunOptions,
+  RunResult,
+} from './backends/index.ts';
+
+export {
+  RemoteDispatcher,
+  STDOUT_PREVIEW_LIMIT,
+} from './dispatcher.ts';
+export type {
+  RemoteDispatcherOptions,
+  RemoteInvokeResult,
+  RemoteWorkEnqueuer,
+  RemoteWorkItemInput,
+  DispatchRequest,
+} from './dispatcher.ts';
+
+export {
+  createRemoteSurface,
+  registerRemoteMethods,
+  registerRemoteDispatch,
+  attachRemoteInvokeRoute,
+  REMOTE_PEERS_REGISTER,
+  REMOTE_PEERS_INVOKE,
+  REMOTE_PEERS_INVOKE_DESCRIPTOR,
+} from './register.ts';
+export type {
+  RemoteSurface,
+  RemoteSurfaceOptions,
+  RegisteredRemoteMethods,
+  RemoteInvokeAdapter,
+  RegisterPeerResult,
+} from './register.ts';

package/src/daemon/remote/peer-registry.ts

@@ -0,0 +1,321 @@
+import { OperatorSqliteStore } from '../operator/index.ts';
+import { isSecretReferenceValue } from '../../config/secret-config.ts';
+
+// ---------------------------------------------------------------------------
+// Backend vocabulary + per-backend config shapes
+// ---------------------------------------------------------------------------
+
+export type BackendKind = 'docker' | 'ssh' | 'cloud-terminal' | 'local-process';
+
+export type CloudProvider = 'gcp' | 'aws' | 'azure';
+
+export interface DockerBackendConfig {
+  containerName: string;
+  /**
+   * Optional Docker host. When it points at a remote daemon over TLS this MUST
+   * be a goodvibes://secrets/ reference (never a raw URL with embedded creds).
+   * A bare local socket path (unix://...) or tcp host without credentials is
+   * also accepted.
+   */
+  dockerHost?: string;
+}
+
+export interface SshBackendConfig {
+  sshHost: string;
+  sshPort?: number;
+  sshUser: string;
+  /** goodvibes://secrets/ reference to the private key — never the raw key. */
+  identityRef: string;
+}
+
+export interface CloudTerminalBackendConfig {
+  provider: CloudProvider;
+  projectId?: string;
+  /** goodvibes://secrets/ reference to the provider credential. */
+  credentialRef: string;
+  /** Optional zone/region/location passed to the provider CLI. */
+  location?: string;
+  /** For gcp: the Cloud Shell / VM instance to target. */
+  instance?: string;
+}
+
+export interface LocalProcessBackendConfig {
+  /** Optional working directory for spawned processes. */
+  cwd?: string;
+  /** Optional allowlist of executables; when set, only these may be invoked. */
+  allowedCommands?: string[];
+}
+
+export type BackendConfig =
+  | ({ kind: 'docker' } & DockerBackendConfig)
+  | ({ kind: 'ssh' } & SshBackendConfig)
+  | ({ kind: 'cloud-terminal' } & CloudTerminalBackendConfig)
+  | ({ kind: 'local-process' } & LocalProcessBackendConfig);
+
+export interface PeerRecord {
+  peerId: string;
+  displayName: string;
+  backendKind: BackendKind;
+  backendConfig: BackendConfig;
+}
+
+export interface PeerRegistrationInput {
+  peerId: string;
+  displayName: string;
+  backendKind: BackendKind;
+  // Raw, untrusted config from the operator method body. Normalized + validated.
+  backendConfig: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers — backendConfig must hold ONLY secret refs for any
+// credential-bearing field. Raw secrets are rejected outright.
+// ---------------------------------------------------------------------------
+
+class PeerRegistryValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PeerRegistryValidationError';
+  }
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new PeerRegistryValidationError(`Field '${field}' is required and must be a non-empty string.`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw new PeerRegistryValidationError(`Field '${field}' must be a string when provided.`);
+  }
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function requireSecretRef(value: unknown, field: string): string {
+  const ref = requireString(value, field);
+  if (!isSecretReferenceValue(ref)) {
+    throw new PeerRegistryValidationError(
+      `Field '${field}' must be a goodvibes://secrets/ reference, not a raw credential.`,
+    );
+  }
+  return ref;
+}
+
+function assertSecretRefIfPresent(value: string | undefined, field: string): void {
+  // A dockerHost may legitimately be a non-credential socket/tcp address, but if
+  // it looks like it embeds credentials (userinfo segment) it must be a ref.
+  if (value === undefined) return;
+  if (value.includes('@') && !isSecretReferenceValue(value)) {
+    throw new PeerRegistryValidationError(
+      `Field '${field}' appears to embed credentials; pass a goodvibes://secrets/ reference instead.`,
+    );
+  }
+}
+
+/** Normalize + validate raw backendConfig into a typed, ref-only BackendConfig. */
+export function normalizeBackendConfig(
+  backendKind: BackendKind,
+  raw: Record<string, unknown>,
+): BackendConfig {
+  switch (backendKind) {
+    case 'docker': {
+      const dockerHost = optionalString(raw.dockerHost, 'dockerHost');
+      assertSecretRefIfPresent(dockerHost, 'dockerHost');
+      return {
+        kind: 'docker',
+        containerName: requireString(raw.containerName, 'containerName'),
+        ...(dockerHost !== undefined ? { dockerHost } : {}),
+      };
+    }
+    case 'ssh': {
+      const portValue = raw.sshPort;
+      let sshPort: number | undefined;
+      if (portValue !== undefined && portValue !== null) {
+        const parsed = typeof portValue === 'number' ? portValue : Number(portValue);
+        if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+          throw new PeerRegistryValidationError("Field 'sshPort' must be an integer between 1 and 65535.");
+        }
+        sshPort = parsed;
+      }
+      return {
+        kind: 'ssh',
+        sshHost: requireString(raw.sshHost, 'sshHost'),
+        sshUser: requireString(raw.sshUser, 'sshUser'),
+        identityRef: requireSecretRef(raw.identityRef, 'identityRef'),
+        ...(sshPort !== undefined ? { sshPort } : {}),
+      };
+    }
+    case 'cloud-terminal': {
+      const provider = requireString(raw.provider, 'provider');
+      if (provider !== 'gcp' && provider !== 'aws' && provider !== 'azure') {
+        throw new PeerRegistryValidationError("Field 'provider' must be one of 'gcp' | 'aws' | 'azure'.");
+      }
+      const projectId = optionalString(raw.projectId, 'projectId');
+      const location = optionalString(raw.location, 'location');
+      const instance = optionalString(raw.instance, 'instance');
+      return {
+        kind: 'cloud-terminal',
+        provider,
+        credentialRef: requireSecretRef(raw.credentialRef, 'credentialRef'),
+        ...(projectId !== undefined ? { projectId } : {}),
+        ...(location !== undefined ? { location } : {}),
+        ...(instance !== undefined ? { instance } : {}),
+      };
+    }
+    case 'local-process': {
+      const cwd = optionalString(raw.cwd, 'cwd');
+      let allowedCommands: string[] | undefined;
+      if (raw.allowedCommands !== undefined && raw.allowedCommands !== null) {
+        if (!Array.isArray(raw.allowedCommands)) {
+          throw new PeerRegistryValidationError("Field 'allowedCommands' must be an array of strings.");
+        }
+        const list = raw.allowedCommands
+          .map((entry) => (typeof entry === 'string' ? entry.trim() : ''))
+          .filter((entry) => entry.length > 0);
+        allowedCommands = list;
+      }
+      return {
+        kind: 'local-process',
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(allowedCommands !== undefined ? { allowedCommands } : {}),
+      };
+    }
+    default:
+      throw new PeerRegistryValidationError(`Unknown backendKind: ${String(backendKind)}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Peer registry — persisted via OperatorSqliteStore
+// ---------------------------------------------------------------------------
+
+const PEER_REGISTRY_FILE = 'remote-peers.sqlite';
+
+const SCHEMA = [
+  `CREATE TABLE IF NOT EXISTS peers (
+     peerId TEXT PRIMARY KEY,
+     displayName TEXT NOT NULL,
+     backendKind TEXT NOT NULL,
+     backendConfig TEXT NOT NULL
+   )`,
+];
+
+interface PeerRow {
+  peerId: string;
+  displayName: string;
+  backendKind: string;
+  backendConfig: string;
+}
+
+const VALID_BACKEND_KINDS: ReadonlySet<BackendKind> = new Set([
+  'docker',
+  'ssh',
+  'cloud-terminal',
+  'local-process',
+]);
+
+function rowToRecord(row: PeerRow): PeerRecord {
+  const backendKind = row.backendKind as BackendKind;
+  const parsed = JSON.parse(row.backendConfig) as BackendConfig;
+  return {
+    peerId: row.peerId,
+    displayName: row.displayName,
+    backendKind,
+    backendConfig: parsed,
+  };
+}
+
+export class PeerRegistry {
+  private readonly store: OperatorSqliteStore;
+  private initialized = false;
+
+  constructor(workingDirectory: string) {
+    this.store = new OperatorSqliteStore({
+      workingDirectory,
+      fileName: PEER_REGISTRY_FILE,
+      schema: SCHEMA,
+    });
+  }
+
+  get dbPath(): string {
+    return this.store.dbPath;
+  }
+
+  async init(): Promise<void> {
+    if (this.initialized) return;
+    await this.store.init();
+    this.initialized = true;
+  }
+
+  private requireInit(): void {
+    if (!this.initialized) {
+      throw new Error('PeerRegistry not initialized: call init() first.');
+    }
+  }
+
+  /** Register (upsert) a peer. Validates + normalizes backendConfig to refs-only. */
+  async register(input: PeerRegistrationInput): Promise<PeerRecord> {
+    this.requireInit();
+    const peerId = requireString(input.peerId, 'peerId');
+    const displayName = requireString(input.displayName, 'displayName');
+    if (!VALID_BACKEND_KINDS.has(input.backendKind)) {
+      throw new PeerRegistryValidationError(`Unknown backendKind: ${String(input.backendKind)}`);
+    }
+    const backendConfig = normalizeBackendConfig(input.backendKind, input.backendConfig ?? {});
+    const serialized = JSON.stringify(backendConfig);
+    this.store.run(
+      `INSERT INTO peers (peerId, displayName, backendKind, backendConfig)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(peerId) DO UPDATE SET
+         displayName = excluded.displayName,
+         backendKind = excluded.backendKind,
+         backendConfig = excluded.backendConfig`,
+      [peerId, displayName, input.backendKind, serialized],
+    );
+    await this.store.save();
+    return { peerId, displayName, backendKind: input.backendKind, backendConfig };
+  }
+
+  /** Look up a peer by id. Returns null when not registered. */
+  get(peerId: string): PeerRecord | null {
+    this.requireInit();
+    const row = this.store.get<PeerRow>(
+      'SELECT peerId, displayName, backendKind, backendConfig FROM peers WHERE peerId = ?',
+      [peerId],
+    );
+    return row ? rowToRecord(row) : null;
+  }
+
+  /** List all registered peers (config included; contains only secret refs). */
+  list(): PeerRecord[] {
+    this.requireInit();
+    const rows = this.store.all<PeerRow>(
+      'SELECT peerId, displayName, backendKind, backendConfig FROM peers ORDER BY peerId ASC',
+    );
+    return rows.map(rowToRecord);
+  }
+
+  /** Remove a peer. Returns true when a row was deleted. */
+  async remove(peerId: string): Promise<boolean> {
+    this.requireInit();
+    const existed = this.get(peerId) !== null;
+    if (existed) {
+      this.store.run('DELETE FROM peers WHERE peerId = ?', [peerId]);
+      await this.store.save();
+    }
+    return existed;
+  }
+
+  close(): void {
+    if (this.initialized) {
+      this.store.close();
+      this.initialized = false;
+    }
+  }
+}
+
+export { PeerRegistryValidationError };