Skip to content

Deploy and operate

Cloudflare

A Thread Object owns a conversation’s durable state and live execution. Your Worker authenticates requests and routes them to that owner. SQLite retains accepted work across eviction; alarms bring the Object back to advance it.

Cloudflare Thread ownership. Your Worker sends authorized input to a Thread Object. The Object commits to its SQLite database and effect-cf alarms drive pending work.
  • Your code: Your WorkerAuthenticate and route
  • Yielded Agent: Thread ObjectAdmit, execute, recover
  • External: effect-cf alarmsWake pending work
  • External: Object SQLiteHistory and unfinished work
  • Your Worker to Thread Object: RPC
  • effect-cf alarms to Thread Object
  • Thread Object to Object SQLite: commit

Install @yielded/agent-platform-cloudflare@beta, effect, effect-cf, and your provider. Reuse the example agent and provider setup:

import {
import ThreadObject
ThreadObject
} from "@yielded/agent-platform-cloudflare";
import {
import Layer
Layer
} from "effect";
const
const RuntimeLive: Layer.Layer<DurableAgentRuntime | ThreadStore | SubmissionLedger | MessageDeliveryStore | WakeScheduler | ThreadReader | RunStorage | SettlementPublisher | StorageOwner | ThreadPublication | ThreadProjectionMaintenance | ThreadMutationGate | SqlClient | DoStorageConfig | SqliteClient | DurableAlarmService | ProgressWaitRegistry | ThreadObject.ThreadObjectPorts | ThreadMaintenance, DigestError | ... 4 more ... | ConfigError, Digest | ... 11 more ... | CloudflareDurableRuntimeConfig>
RuntimeLive
=
import ThreadObject
ThreadObject
.
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>(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?: ThreadObject.PublicationOptions<...> | undefined): Layer.Layer<...> (+1 overload)
export layer

Preserve additional index services only when a projection Layer is actually supplied.

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
}]).
Pipeable.pipe<Layer.Layer<DurableAgentRuntime | ThreadStore | SubmissionLedger | MessageDeliveryStore | WakeScheduler | ThreadReader | RunStorage | SettlementPublisher | StorageOwner | ThreadPublication | ThreadProjectionMaintenance | ThreadMutationGate | SqlClient | DoStorageConfig | SqliteClient | DurableAlarmService | ProgressWaitRegistry | ThreadObject.ThreadObjectPorts | ThreadMaintenance, DigestError | ... 3 more ... | DoStorageInitializationError, OpenAiClient | ... 12 more ... | CloudflareDurableRuntimeConfig>, 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
),
);
export class
class TravelThread
TravelThread
extends
import ThreadObject
ThreadObject
.
const make: <DoStorageConfig | SqliteClient, DigestError | ThreadStoreError | MessageDeliveryError | DurableAlarmError | DoStorageInitializationError | ConfigError, never, never, never, never>(applicationLayer: Layer.Layer<DoStorageConfig | SqliteClient | ThreadObject.Services, DigestError | ThreadStoreError | MessageDeliveryError | DurableAlarmError | DoStorageInitializationError | ConfigError, DurableObjectContext | ... 4 more ... | WorkerEnvironment>, options: ThreadObject.Options<...>) => ThreadObject.Class<...>

Export a composed application Layer as a native Durable Object class. Bootstrap services are provided to the whole graph before it acquires, so application Layers can yield effect-cf's WorkerEnvironment and DurableObjectState, derived identity, Digest, and SecureRandom. Effect Config reads scalar Worker vars and secrets through effect-cf's environment provider; WorkerEnvironment exposes resource bindings without a separate config Layer. Application dependencies remain visible until Layer.provide satisfies them. effect-cf owns the cached ManagedRuntime, native RPC methods, event scopes, and telemetry flushing. Initialization is local and bounded inside the constructor gate. Cloudflare eviction does not guarantee finalizers; put resources requiring timely release in scoped operations or eventLayer.

make
(
const RuntimeLive: Layer.Layer<DurableAgentRuntime | ThreadStore | SubmissionLedger | MessageDeliveryStore | WakeScheduler | ThreadReader | RunStorage | SettlementPublisher | StorageOwner | ThreadPublication | ThreadProjectionMaintenance | ThreadMutationGate | SqlClient | DoStorageConfig | SqliteClient | DurableAlarmService | ProgressWaitRegistry | ThreadObject.ThreadObjectPorts | ThreadMaintenance, DigestError | ... 4 more ... | ConfigError, Digest | ... 11 more ... | CloudflareDurableRuntimeConfig>
RuntimeLive
, {
BaseOptions<ApplicationServices, EventServices, EventLayerError, AlarmServices>.namespaceBinding: string

Name of the Worker env binding carrying THIS class's DurableObjectNamespace — the Object's route back to sibling Thread Objects for the WP2 cross-Object port calls and remote wakes (DEPLOY-010: the binding enters through a Layer, never ambiently).

namespaceBinding
: "THREADS",
CloudflareDurableRuntimeOptions.deploymentId: string
deploymentId
: "travel-planner",
CloudflareDurableRuntimeOptions.producerPrefix: string

Head of the minted producer identity {producerPrefix}:{threadId}.

producerPrefix
: "travel-worker",
}) {}

Bind the exported class as a SQLite Durable Object under THREADS, enable nodejs_compat, and supply the provider secret. The runnable travel planner includes deployment and application wiring. No separate storage Layer is needed.

CloudflareThreadClient.layerFromBinding({ namespace: env.THREADS }) supplies the client. Submit authenticated input with a Thread ID, principal, idempotency key, and definition digests. Admission arms maintenance before accepting work and returns a receipt after durable writes. By default, the submit event also starts the admitted work in an effect-cf processing scope. The receipt does not wait for execution or a model request.

Use awaitSettlementRecord(receipt) for the canonical terminal record and decode ordinary completed output with the agent’s Schema. Use readPage and awaitProgress for retained updates. Cancelling observation does not abort accepted work.

watchText(threadId) supplies provisional text and available provider reasoning summaries. Reconcile it against canonical records; reset or discard drafts as directed by its frames. Canonical completion permanently retires matching drafts, including after reconnects. Drafts disappear on eviction.

Intermediary Workers can forward watchTextBytes(threadId) without decoding or re-encoding NDJSON. Blank keepalive lines every 15 seconds help idle HTTP connections detect disconnected readers. At the final consumer, use decodeLiveText(threadId, bytes) from @yielded/agent-platform-cloudflare/live-text to discard keepalives and validate frames and their lifecycle in a browser or Worker. Both streaming client methods cancel the remote subscription when their stream scope closes.

effect-cf owns the native alarm. ThreadObject.make registers manual Thread maintenance and composes application registrations from options.alarms. Do not write the raw alarm slot or replace its handler.

dispatchAfterEvent defaults to true, allowing submit to start admitted work immediately and other events to dispatch due work. To opt out, provide DurableObjectAlarm.ScheduleConfiguration with { dispatchAfterEvent: false } through Layer.provideMerge on the application Layer. In that mode, alarms still start work promptly; the recovery window does not delay execution.

recoveryWindowMillis controls recovery after interruption without another client request. After activity, the Object retains one wake for this window and reuses it for nearby requests. An empty wake clears itself. A longer window can avoid an alarm write before the first model request, in exchange for slower recovery without a client. Reopening an Object with pending work still schedules prompt recovery. Set the window to 0 to restore the short recovery deadlines and immediate idle cancellation.

Setting Default
Admission queue depth per Thread 256 nonterminal Submissions
Encoded input limit 1,900,000 bytes
Database admission ceiling 9,000,000,000 bytes
Failed/no-progress pass backoff 100 ms base, 5 seconds cap
Recovery window (recoveryWindowMillis) 60,000 ms (60 seconds)

An alarm has a ten-minute cooperative yield boundary and fourteen-minute watchdog. These are event limits; agent maxDuration applies to each active durable Attempt using the Run’s original allowance. Suspension is outside that duration. An explicit Unknown outcome stays unresolved; a restart does not authorize replay.

Provide model, tool, and context Layers before constructing the Object. They are acquired per incarnation. Keep initialization local and bounded; eviction does not guarantee finalizers. Use scoped operations or eventLayer for timely cleanup. Keep RPC private and configure operationAuthorizer; its default trusts service possession.

Acquire CloudflareTracer.layer in eventLayer for invocation-specific tracing.

Use ThreadObject.layerInHost to place logical Threads in an existing Object. Share its SQL client and mutation gate; keep placement stable. Register ThreadObject.alarms with the host’s DurableObjectAlarm.mergeAll and call ThreadMaintenance.ensureAlarm during local initialization. Follow the shared-owner example.

MemoryObject.make and CloudflareMemoryClient provide separately owned documents shared across Threads. You choose namespaces and authorize access. See the memory example and context guide.

The Node-safe /cloudflare-ai-gateway subpath configures upstream provider clients; model behavior stays with Effect AI. Browser and Code Mode adapters are independent capabilities.