The Node host owns a SQLite file and a bounded worker pool for its application
Scope. It recovers retained work before opening admission, then advances registered
agents as input arrives. Your process owns the server, credentials, and shutdown.
Define the agent, choose its native Effect model, and supply provider and tool
Layers. A durable registration also carries explicit agent, model, and tool version
declarations. Update those declarations when behavior changes.
The runnable Node example
includes node-agent.ts, provider configuration, and the process entry point.
Its provider reads OPENAI_API_KEY from the environment.
Acquire a complete Node host and start one bounded, scoped worker pool after recovery.
Own the SQLite file exclusively until the host and its storage close. A second connection
fails construction. Process death releases the file lock; a replacement acquires it before
recovering retained work with fresh local generations. Use this host's services for live inspection.
Provide model, tool, instruction, and schema dependencies to this Layer. Reusing the Layer
shares the same pool. A worker failure closes admission; observe it with run at the process
boundary so the application exits and releases the host instead of remaining idle.
layer([{
agent:Definition<String,Struct<{
readonlyitinerary:$Array<String>;
}>,"Plan a trip with one itinerary entry per day.",Toolkit<{}>,undefined,undefined,undefined>&{
Feeds the output services of the dependency layer into the requirements of
this layer, returning a layer that only provides the services from this layer.
When to use
Use when you need to hide an implementation dependency layer from callers.
Details
In serviceLayer.pipe(Layer.provide(dependencyLayer)), the dependency layer is
built first and is used to satisfy the requirements of serviceLayer.
Give each process start a distinct producerId. Run NodeDurableHost.run with
HostLive provided; the example’s node-main.ts does this through
NodeRuntime.runMain. run observes the existing pool and propagates worker
failure. When also serving HTTP, supervise the server and run together with
Effect.raceFirst so either failure closes the shared Scope.
The host holds an exclusive SQLite connection lock, including against independent
readers. Keep the file on persistent local storage with working SQLite locks.
Stop the host before opening it with the standalone admin CLI or another connection.
Existing files must already use WAL mode; fresh files are initialized for you.
"NORMAL" synchronization can lose acknowledged commits after power loss or an OS
crash, potentially repeating external effects during recovery. Choose it only with
that tradeoff understood.
Services are captured when the host Layer is acquired. Provide context, tool
policy, or compactor Layers at that boundary and keep their resources alive for
its Scope. Authentication and authorization of incoming requests remain yours.
Call host.submit(agent, input, options) from an authenticated handler, supplying
Thread identity, principal, definition digests, and an idempotency key. Return the
receipt after admission. Retry the same request with the same key; changed input
under that key conflicts.
Use host.awaitSettlement(receipt) for the outcome or host.observe(receipt) for
canonical records. An explicit Unknown outcome stays parked for
authorized resolution; a restart does not authorize replay.
Closing the Scope stops admission, joins workers, releases live ownership, and
closes storage. A replacement host opens the file and recovers retained work with
fresh local owner generations. There are no distributed leases or takeover protocol.
The host Layer also supplies DurableAgentRuntime; use its explain, verify, and
scanObligations methods for inspection and its recovery methods for operator actions.
NodeDurableAgentRuntime.layerRegistered acquires a registered runtime without
starting workers. Use it when your application supplies dispatch. For PostgreSQL, compose a
custom durable host around its storage ports.