skills/plugins/document-navigator/docs/api-stack/api/api-worker-host/README.md

@suaveplan/api-worker-host - Worker-side runtime that hosts exactly one Suaveplan API plugin inside an isolated Worker thread. Provides the bootstrap entry point that handshakes with the main host, wires capability proxies via @suaveplan/api-worker-rpc, dispatches lifecycle commands (install/start/stop/uninstall/reload) to plugin hooks, and surfaces uncaught exceptions as WORKER_HOST.CRASHED envelopes so the main host's LifecycleDriver can transition the plugin to the crashed state.

Worker-side runtime that hosts exactly one Suaveplan API plugin inside an isolated Worker thread. The main-process counterpart is @suaveplan/api-host; this package owns everything that runs inside the worker: bootstrap handshake, capability proxy wiring, lifecycle command dispatch, and uncaught-exception → WORKER_HOST.CRASHED propagation.

This is API plugin system (design doc §2.2, §5.2a). The transport layer (@suaveplan/api-worker-rpc) is consumed here for every cross-boundary frame.

Documentation tree

• bootstrap — bootstrapWorkerPlugin is the single entry point a worker thread invokes to host exactly one Suaveplan API plugin. It…
  • bootstrap — bootstrapWorkerPlugin is the single entry point a worker thread invokes to host exactly one Suaveplan API plugin. It…
• capability-proxies — This module turns the capability-handle descriptor table delivered by the main host into a live, frozen map of RPC-back…
  • capability-proxies — This module turns the capability-handle descriptor table delivered by the main host into a live, frozen map of RPC-back…
• crash-detection — This module installs the worker-side safety net that turns silent process death into observable crash telemetry. Withou…
  • crash-detection — This module installs the worker-side safety net that turns silent process death into observable crash telemetry. Withou…
• error-codes — This module owns the namespaced WORKER_HOST.* error registry consumed by the worker-side runtime that hosts exactly o…
  • error-codes — This module owns the namespaced WORKER_HOST.* error registry consumed by the worker-side runtime that hosts exactly o…
• lifecycle — This module hosts the worker-side counterpart to the main host's LifecycleDriver. It owns the worker's nine-state lif…
  • lifecycle — This module hosts the worker-side counterpart to the main host's LifecycleDriver. It owns the worker's nine-state lif…
• protocol-extension — This module defines the Zod schemas that the worker host layers on top of the transport-level frame protocol owned by `…
  • protocol-extension — This module defines the Zod schemas that the worker host layers on top of the transport-level frame protocol owned by `…
• testing — runWorkerHostConformance spins up an in-process worker-shaped peer using paired MessageChannel ports. It exists so…
  • testing — runWorkerHostConformance spins up an in-process worker-shaped peer using paired MessageChannel ports. It exists so…

Layout

• bootstrap — bootstrapWorkerPlugin validates the manifest + capability handles, builds the proxy map, mounts the lifecycle RPC server, posts the worker-ready frame.
• capability-proxies — installCapabilityProxies builds frozen RPC-backed capability slots; getCapability enforces declared capabilities.
• lifecycle — createLifecycleReceiver owns the nine-state worker-side FSM and the LifecycleAck envelope.
• crash-detection — installCrashDetector wires uncaughtException / unhandledRejection to a WORKER_HOST.CRASHED envelope before exiting.
• protocol-extension — Zod schemas for every worker-host envelope.
• error-codes — nine stable WORKER_HOST.* codes.
• testing — runWorkerHostConformance in-process simulator.

Stability

• Version: 0.1.0 (Original).
• Tier: server (requires Node process + MessageChannel; Node 18+).
• Dependencies: @suaveplan/api-types, @suaveplan/api-worker-rpc, @suaveplan/api-lifecycle, @suaveplan/error, @suaveplan/events, @suaveplan/logger, tslib, zod.

Verification

bunx turbo lint typecheck test build --filter=@suaveplan/api-worker-host
bunx turbo test:coverage --filter=@suaveplan/api-worker-host

All four coverage dimensions land at 100/100/100/100.