Skip to content

Deploy and operate

Node.js

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.

bun add @yielded/agent-platform-node@beta effect

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.

This example imports that agent setup and acquires one shared host:

node-host.ts
import {
import NodeDurableHost
NodeDurableHost
} from "@yielded/agent-platform-node";
import {
import Layer
Layer
} from "effect";
import {
const definitions: {
agent: string;
model: string;
tools: string;
}
definitions
,
const ModelLive: Model<"openai", LanguageModel, OpenAiClient>
ModelLive
,
const OpenAiLive: Layer.Layer<OpenAiClient, ConfigError, never>
OpenAiLive
,
const planner: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}
planner
} from "./node-agent.ts";
export const
const HostLive: Layer.Layer<DurableAgentRuntime | MessageDeliveryStore | ThreadReader | NodeDurableAgentRuntimeConfig | (SqlClient & DurableAgentRuntime) | (SqlClient & MessageDeliveryStore) | (SqlClient & ThreadReader) | (SqlClient & NodeDurableAgentRuntimeConfig) | (SqliteClient & DurableAgentRuntime) | (SqliteClient & MessageDeliveryStore) | (SqliteClient & ThreadReader) | (SqliteClient & NodeDurableAgentRuntimeConfig) | NodeDurableHost.NodeDurableHost, ConfigError | ... 3 more ... | NodePlatformConfigError, never>
HostLive
=
import NodeDurableHost
NodeDurableHost
.
const layer: <readonly [{
readonly agent: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
};
readonly model: Model<"openai", LanguageModel, OpenAiClient>;
readonly definitions: {
agent: string;
model: string;
tools: string;
};
}], never, never, never, never, never, never>(registrations: readonly [{
readonly agent: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
};
readonly model: Model<"openai", LanguageModel, OpenAiClient>;
readonly definitions: {
agent: string;
model: string;
tools: string;
};
}], options: NodeDurableAgentRuntimeOptions<...>) => Layer.Layer<...>

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<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}
agent
:
const planner: Definition<String, Struct<{
readonly itinerary: $Array<String>;
}>, "Plan a trip with one itinerary entry per day.", Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "trip-planner";
}
planner
,
model: Model<"openai", LanguageModel, OpenAiClient>
model
:
const ModelLive: Model<"openai", LanguageModel, OpenAiClient>
ModelLive
,
definitions: {
agent: string;
model: string;
tools: string;
}
definitions
}], {
NodeDurableAgentRuntimeOptions<ContextError = never, ContextRequirements = never, AuthorizationError = never, AuthorizationRequirements = never, ReconcilerError = never, ReconcilerRequirements = never>.filename: string
filename
: "./agents.sqlite",
NodeDurableAgentRuntimeOptions<ContextError = never, ContextRequirements = never, AuthorizationError = never, AuthorizationRequirements = never, ReconcilerError = never, ReconcilerRequirements = never>.deploymentId: string
deploymentId
: "travel-planner",
NodeDurableAgentRuntimeOptions<ContextError = never, ContextRequirements = never, AuthorizationError = never, AuthorizationRequirements = never, ReconcilerError = never, ReconcilerRequirements = never>.producerId: string
producerId
: "worker-start-001",
NodeDurableAgentRuntimeOptions<ContextError = never, ContextRequirements = never, AuthorizationError = never, AuthorizationRequirements = never, ReconcilerError = never, ReconcilerRequirements = never>.workerConcurrency?: number | undefined

Default 1; bounded to 1..64.

workerConcurrency
: 4,
}).
Pipeable.pipe<Layer.Layer<DurableAgentRuntime | MessageDeliveryStore | ThreadReader | NodeDurableAgentRuntimeConfig | (SqlClient & DurableAgentRuntime) | (SqlClient & MessageDeliveryStore) | (SqlClient & ThreadReader) | (SqlClient & NodeDurableAgentRuntimeConfig) | (SqliteClient & DurableAgentRuntime) | (SqliteClient & MessageDeliveryStore) | (SqliteClient & ThreadReader) | (SqliteClient & NodeDurableAgentRuntimeConfig) | NodeDurableHost.NodeDurableHost, DurableWorkerFailure | ... 2 more ... | NodePlatformConfigError, OpenAiClient>, Layer.Layer<...>>(this: Layer.Layer<...>, ab: (_: Layer.Layer<...>) => Layer.Layer<...>): Layer.Layer<...> (+21 overloads)
pipe
(
import Layer
Layer
.
const provide: <never, ConfigError, OpenAiClient>(that: Layer.Layer<OpenAiClient, ConfigError, never>) => <RIn2, E2, ROut2>(self: Layer.Layer<ROut2, E2, RIn2>) => Layer.Layer<ROut2, ConfigError | E2, Exclude<RIn2, OpenAiClient>> (+3 overloads)

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.

Example (Providing layer dependencies)

import { Context, Effect, Layer } from "effect"
class Database extends Context.Service<Database, {
readonly query: (sql: string) => Effect.Effect<string>
}>()("Database") {}
class UserService extends Context.Service<UserService, {
readonly getUser: (id: string) => Effect.Effect<{
id: string
name: string
}>
}>()("UserService") {}
class Logger extends Context.Service<Logger, {
readonly log: (msg: string) => Effect.Effect<void>
}>()("Logger") {}
// Create dependency layers
const databaseLayer = Layer.succeed(Database, {
query: Effect.fn("Database.query")((sql: string) => Effect.succeed(`DB: ${sql}`))
})
const logs: Array<string> = []
const loggerLayer = Layer.succeed(Logger, {
log: Effect.fn("Logger.log")((msg: string) => Effect.sync(() => logs.push(`[LOG] ${msg}`)))
})
// UserService depends on Database and Logger
const userServiceLayer = Layer.effect(UserService, Effect.gen(function*() {
const database = yield* Database
const logger = yield* Logger
return {
getUser: Effect.fn("UserService.getUser")(function*(id: string) {
yield* logger.log(`Looking up user ${id}`)
const result = yield* database.query(
`SELECT * FROM users WHERE id = ${id}`
)
return { id, name: result }
})
}
}))
// Provide dependencies to UserService layer
const userServiceWithDependencies = userServiceLayer.pipe(
Layer.provide(Layer.mergeAll(databaseLayer, loggerLayer))
)
// Now UserService layer has no dependencies
const program = Effect.gen(function*() {
const userService = yield* UserService
return yield* userService.getUser("123")
}).pipe(
Effect.provide(userServiceWithDependencies)
)
Effect.runSync(program) // => { id: "123", name: "DB: SELECT * FROM users WHERE id = 123" }
logs // => ["[LOG] Looking up user 123"]

@see ― provideMerge for retaining the dependency services

@stability ― stable

@category ― providing services

@since ― 2.0.0

provide
(
const OpenAiLive: Layer.Layer<OpenAiClient, ConfigError, never>
OpenAiLive
));

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.

Option Default Purpose
workerConcurrency 1 Concurrent workers; accepts 1–64
wakeScanInterval 1000 ms Fallback scan for missed wake hints
synchronous "FULL" SQLite durability setting
runContext Pass-through Application prompt preparation
toolAuthorization Allow all Action-time tool policy
toolReconciler Keep uncertain Resolve unconfirmed external outcomes

"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.