Start with @yielded/agent@beta for agent definitions, conversations, execution, and durability.
Install storage, platform, sandbox execution, and testing packages as needed.
Keep all framework packages at the same release. Package manifests declare the compatible
Effect and platform versions.
Before 1.0, APIs and stored data may change without a migration path.
Prefer named namespace imports from package roots in application code and examples.
Namespaces use PascalCase; direct module paths use kebab-case. Agent definitions, execution,
capabilities, and durability live in one package:
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; after process death the replacement retires abandoned claims before
recovery, without waiting for their leases. 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;
For direct module access, unbundled startup, or lazy-loading boundaries, use:
Both forms support tree shaking in bundles. Native Node evaluates every namespace re-exported
by a root import; sideEffects does not make those exports lazy. Direct paths limit the initial
module graph, including when importing upstream Effect modules. Other root imports in the same
process can still load those shared modules.
Use direct module paths at lazy-loading boundaries: mixing a
static root import with a dynamic import of that same root can pull the runtime into the initial
bundle. Also use dedicated subpaths for optional adapters and helpers intended for another
runtime, such as the Node-safe Cloudflare AI Gateway helper. The Cloudflare package root
includes Workers-specific modules. Provider, storage, platform, and testing packages remain
separate installs.
Agent.make and AgentRuntime.run have the same call shape through either import form.
Use direct imports for individual declarations, including services and Schema values, instead
of importing a namespace when only its service key is needed:
Root imports name module namespaces. For example, root AgentPolicy exposes its Schema class as
AgentPolicy.AgentPolicy; a named import from @yielded/agent/agent-policy selects that class
directly. Ordinary agent definitions can pass a plain policy object to Agent.make, which
validates it and fills defaults.
Operations are available directly on their module namespace: Subagent.layer,
ThreadHistory.layer, and IdGenerator.layer. Service keys remain inside those modules,
for example IdGenerator.IdGenerator when supplying a custom generator.
Provide a native Effect model with Effect.provide(model) around an agent Run, or
Layer.provide(model) around Subagent.layer(delegation). The agent guide
shows this default composition. AutoModel uses the same API.
For an explicit reusable pairing, Agent.withModel(definition, model) returns an optional Agent
Binding. Subagent.layer(delegation, model) also accepts an explicit model override.
Durable registration uses { agent: definition, model, definitions: versions } so the host owns
each agent’s model and version declarations; an existing Binding is also accepted.
Import InMemory from @yielded/agent, or use import * as InMemory from "@yielded/agent/in-memory".
InMemory.layer supplies in-memory conversation history and a shared subagent reservation ledger.
Provide it once around the parent program and all child handler Layers. Runs with the same Thread
ID retain their conversation for that application Scope; independent builds have independent state.
Complete history updates remain after a failed or interrupted Run. Scope closure or process loss
releases the state; this layer provides no crash recovery. See in-memory conversations
for limits and a follow-up example.
Runtime IDs have an overridable default; no ID Layer is required. Context preparation is also
optional. InMemory.layer preserves custom IDs and context preparation supplied by the caller.
Models, tool handlers, credentials, and durable storage remain explicit application choices.
For storage-backed history, provide PersistentHistory.layer with a store and, when using subagents,
one shared SubagentReservationsMemoryLive instead of InMemory.layer. Durable hosts select
their own history and reservation services.
IdGenerator is a Context.Reference. Override it with Layer.succeed, Layer.effect, or
Effect.provideService. The module-level layer from @yielded/agent/id-generator restores
the default.
Use direct module paths when you need an individual module:
Module or declarations
Owning module
Agent constructors and inferred types
@yielded/agent/agent
Recall composition, sources, and outcomes
@yielded/agent/memory
Memory passages and recall limits
@yielded/agent/memory-reference
Memory reader/writer contracts
@yielded/agent/memory-store
Remembering checkpoints and persistence contract
@yielded/agent/remembering-store
Durable admission and finite remembering passes
@yielded/agent/remembering
MemoryAccess, revalidateMemoryLookup
@yielded/agent/memory-revalidation
Semantic index contracts and errors
@yielded/agent/semantic-memory-index
Delegation contracts and reservation amounts
@yielded/agent/subagent-contract
Runtime operations and inferred failures
@yielded/agent/agent-runtime
Native tool selection schemas and annotations
@yielded/agent/tool-exposure
Host tool visibility and eligible catalogue
@yielded/agent/tool-exposure
Bounded native and Code Mode discovery
@yielded/agent/tool-discovery
Compactor service
@yielded/agent/context-compactor
Command-drain, scheduling, and run options
@yielded/agent/run-options
Subagent authoring and handlers
@yielded/agent/subagent
Semantic indexing/query implementation
@yielded/agent/semantic-memory
Import individual declarations from their owning modules, or use the root module namespace.
CommandDrainPolicy and RunSchedulingOverride each expose a Schema and its inferred type
from RunOptions. MemoryThreadStoreLive comes from
@yielded/agent-storage-memory/memory-thread-store; SQLite memory readers and writers come
from @yielded/agent/sql-memory-store.
Test controls and conformance suites use /testing/module paths. Browser adapters, fixtures,
and other specialized paths use the same kebab-case convention. Unlisted source files and
implementation directories are private.
Use ContextCompactor to customize compaction and AgentPolicy.runStatus to configure status
messages. Token estimators and ContextCompactionState support custom compactors.
MCP servers connect through McpClient.layer over Streamable HTTP or stdio;
connectMcp bounds discovery and returns dynamic tools. Server-initiated sampling, elicitation,
resources, and prompts are not served.
Background subagents and
bounded nested delegation have public APIs.
Subagent handoff, runtime Skills, a framework-owned memory extraction or sharing policy,
arbitrary Thread metadata, and dynamic Turn Plans have no public APIs.
Applications own domain state. Memory.recall reads bounded passages from sources they select; it
does not store them. Thread history and compaction summaries do not replace application state.
Automatic compaction uses ContextCompactor. The separate
artifact utilities validate and apply
application-managed summaries; they do not run or persist automatically.
Thread-owned automatic model selection, using the native Effect DecisionModel service.
The package depends only on Effect and exports AutoModel and LanguageModelDecisionModel.
The latter adapts any structured-output language model to native decisions. Import ordinary assessments
from effect/ai using Decision and DecisionModel.
AutoModel selects a native model from described profiles on each thread’s
first turn, including new subagents. A shared selection store retains choices across follow-ups.
The Jev adapter: TypeSafeDecisionModel supplies the shared decision service, while
TypeSafeClient and TypeSafeSchema expose the native choice, score, and noul API.
This upstream Effect provider replaces @effect-agent/ai-typesafe and uses an Effect HttpClient.
Agent definitions, schemas, execution, streaming, policies, subagents, memory capabilities,
MCP, durable execution, and platform-neutral sandbox contracts. It has no database driver or platform runtime dependency.
Start with Agent, AgentRuntime, and InMemory.layer.
InMemory.layer retains in-memory conversation history and shared attached-subagent reservations.
For storage-backed history, use the root namespace PersistentHistory.layer.
Models, provider clients, credentials, tool handlers, and durable hosts remain application choices.
BrowserUse.make (@yielded/agent/browser-use) returns a matching toolkit and layer().
It defaults to direct, single actions; opt into grounding: "decision" or mode: "batched".
Applications supply observed controls and guarded actions through BrowserActions and a native
Effect DecisionModel for decision grounding. See browser tools.
Sandbox contracts including Sandbox, CodeExecutor, PageCapture, and InteractiveBrowser
are part of this package; concrete executors and browser adapters are separate. See
sandbox execution and browser tools.
These are internal directories, not separate packages or import prefixes. Storage drivers,
platform hosts, workflow integrations, sandbox execution, and testing remain separate packages.
Thread describes an identified, ordered conversation. Thread.Store holds in-memory snapshots
and InMemory.layer shares it across Runs. Persistence and execution recovery are separate choices.
Versioned records, storage contracts, recovery, scheduling, and subscriptions live under
packages/effect-agent/src/durable. Import their public namespaces from @yielded/agent, or use
kebab-case subpaths such as @yielded/agent/persistent-history and @yielded/agent/durable-agent-runtime.
DurableAgentRuntime.layerRegistered hashes version declarations and captures agent services
once at construction. layerWithBindings accepts previously compiled registrations owned by
the application’s Scope. Worker operations use those registrations without accepting services.
Optional processCommittedActivity runs bounded, resumable passes with separate processor
progress. The host owns record eligibility, extraction, and durable output application. See
committed memory processing.
Custom drivers can advance one FIFO-head Attempt with processThreadHead(threadId) and apply one
submission’s recovery decision with recoverSubmission. submissionStatus is the authorized
nonblocking read; inspectSubmissionStatus is reserved for trusted workers. Pending status and
an empty processing result do not imply completion.
Import
Use
@yielded/agent/persistent-history
Persistent history implementation
@yielded/agent/thread-store
History storage contracts
@yielded/agent/run-continuation
Canonical Run progress and work discovery contracts
AgentWorkflow.execute(agent, input, { name }) composes registered Agents inside native
Workflow.toLayer handlers. Stable step names deduplicate admission across replays; Effect’s
DurableDeferred suspends and resumes the parent. Results are decoded from canonical
settlements, and AgentWorkflow.Error supplies the workflow’s typed error Schema.
Import AgentWorkflow from the package root or use the direct
@yielded/agent-workflow/agent-workflow module. The WorkflowExecution module exports
the step options, Agent contract, and WorkflowExecutionFailure schema.
Optional WorkflowAgentHost over an injected upstream Effect WorkflowEngine. It reuses the
durable runtime’s admission, journal recovery, authorization, and settlement protocol.
WorkflowAgentHost.layer(options) consumes a runtime whose Layer owns agent registration.
Its required principal supplies the identity for workflow-originated submissions.
WorkflowDispatchStore retains dispatch intents; WorkflowRepairTrigger requires the host to
schedule startup and repeated repair. The shared package starts no polling loop and imports no
Node or Cloudflare implementation.
See the Effect Workflows guide for host composition, engine substitution,
and cancellation semantics, including the Node.js SQL setup.
Install it separately from @yielded/agent.
Scoped in-memory thread and submission stores for tests. The ledger is non-durable.
For ordinary conversations, use InMemory.layer from @yielded/agent.
The independent inMemorySemanticIndexLayer supplies a bounded exact cosine derivative index.
It is disposable and must be rebuilt from authoritative sources after its Scope closes.
Shared SQL implementations of thread history, submissions, schedules, subscriptions, message
delivery, and activity progress. SQLite and Postgres supply connections, format initialization,
and transaction settings. Cloudflare reuses the SQL helpers that fit Durable Objects.
Applications normally install their database adapter; adapter authors can use these factories
with Effect’s SqlClient. The shared package imports no platform runtime.
makeSqlThreadStore and makeSqlSubmissionLedger return individual service values in Effects.
Durable adapters also need SettlementPublisher: makeSqlSubmissionLedgerKernel returns
co-owned ledger and publisher services over the supplied journal. Install them together
with Layer.effectContext, alongside the thread store built over that journal.
Stores thread history and pending work in one Node SQLite database.
Accepts fresh databases or the exact current thread format; rejects mismatches without migration.
CurrentSqliteStorageVersion identifies the supported version.
See the SQLite storage guide for installation and agent wiring.
The independent memoryStoreLayer from @yielded/agent/sql-memory-store supplies optional MemoryReader, MemoryWriter, and SqlMemoryBatchWriter ports
for conditional document updates and terminal withdrawal. It initializes only memory tables.
Use memoryReaderLayer when the application needs no writer. See
memory lifecycle.
activityProcessorStoreLayer provides independent leases, prepared output, and per-Thread
progress for finite committed-activity passes. Its tables and fencing epochs are separate from
the Thread journal and submission ledger.
Stores thread history and pending work in one Postgres database, which several Node processes may
share. Rejects incompatible stored versions; no migration path is promised.
Requires Postgres 16 or newer.
PostgresStorage.layer provides ThreadStore, ThreadReader, SubmissionLedger, and
SettlementPublisher, requiring the application’s native Effect SqlClient and Crypto.
See the PostgreSQL storage guide
for client composition and agent wiring. Use PostgresStorage.layerWith(options) to configure
the core pair, or select individual ports:
Constructor
Provides
threadStoreLayer(options = {})
ThreadStore, ThreadReader
submissionLedgerLayer(options = {})
SubmissionLedger, SettlementPublisher
scheduleStoreLayer(options = {})
ScheduleStore
activityStoreLayer(options = {})
ActivityProcessorStore
messageDeliveryStoreLayer(options = {})
MessageDeliveryStore
subscriptionStoreLayer(partition, options = {})
SubscriptionStore
These constructors are exported by PostgresStorage. Activity progress remains independent of
the journal; subscriptions require an explicit partition. Message delivery accepts limits in
its options. The failpoint and activityFailpoint
options accept test handlers.
The schema option qualifies storage tables and defaults to public. It leaves the client’s
search path unchanged; pre-provisioned schemas need no database-wide CREATE permission.
Storage decodes native BIGINT values to safe integers and uses its persisted column names,
while application queries keep the client’s codecs and name transformations.
Writes use READ COMMITTED and serialize on one transaction-scoped advisory lock. A lock timeout
appears as a retryable PostgresWriteContention cause in thread and submission errors; other stores
report their own storage errors. Invoke storage writes and snapshot reads outside an existing
SQL transaction: they own top-level transactions and reject nesting with a typed failure.
Identifiers and other text parameters must contain valid Unicode without NUL; canonical JSON
payloads still preserve arbitrary strings. The @yielded/agent/sql-memory-store ports stay
SQLite-only.
NodeDurableHost.layer(registrations, options) acquires storage, recovers pending work, and
starts a bounded worker pool. NodeDurableHost.run observes that pool and propagates worker
failure to the application. Provide the host Layer once around the supervised application;
its Scope closes admission and joins workers before releasing runtime resources.
Assembles SQLite storage, recovery, and workers through NodeDurableHost.
Registers agent bindings before execution, recovers before admission, and releases ownership
before closing storage. See the Node.js guide.
NodeDurableAgentRuntimeOptions.toolFailureObserver installs a local tool-failure observer.
The optional @yielded/agent-platform-node/node-workflow import supplies SqlWorkflowDispatchStore
over an injected SqlClient and NodeWorkflowRepairTrigger with scoped startup and polling.
Pair them with NodeDurableAgentRuntime.layerRegistered and WorkflowAgentHost.layer as shown
in the Workflow guide’s Node.js setup. This assembly does not start
the ordinary Node worker loop.
Stores history and pending work in each Durable Object’s SQLite database.
Accepts injected Object handles without importing cloudflare:workers.
Rejects incompatible stored versions; CurrentDoStorageVersion identifies the supported version.
Failpoints and eviction helpers are in @yielded/agent-storage-cloudflare/testing/do-storage-failpoint-testing.
See Cloudflare storage for host ownership and direct adapter use.
doMemoryStoreLayer supplies optional memory ports using storage-backed SQLite transactions.
The separate memory protocol defines bounded batch requests, responses, and typed errors.
Assembles the durable host, RPC client, alarms, and Code Mode executor.
See the Cloudflare guide for bindings, service lifetimes, and admission limits.
The Code Mode guide covers the independent
Dynamic Worker executor and Worker Loader binding.
ThreadObject.Options.toolFailureObserver installs a local tool-failure observer.
MemoryObject.make and CloudflareMemoryClient share namespace-owned memory across
Threads, with one authoritative batch RPC per recall. See shared memory.
Browser adapters use separate imports:
Subpath
Adapter and requirements
/cloudflare-browser
Page capture through a browser binding; structured extraction also needs explicit Workers AI authorization and accounting
/browser-rest-capture
Node-safe page capture with account credentials and HttpClient
/browser-rest-crawl
Node-safe same-host Markdown crawl with bounded polling and scoped job cleanup
/interactive-browser
Bounded interactive browser and host controls with the included Puppeteer client
BrowserSessions.layer({ browser, accountId, apiToken }) requires HttpClient.
create(options, retain) calls the host’s retention Effect with a private
BrowserSessionReference; successful retention makes the host responsible for remote cleanup.
createAttached(options, retain) returns a BrowserSession after the same retention step,
keeping its initial connection in the caller’s Scope. Failed acquisition releases the child
scope before returning the failure. Its 30-second acquisition timeout does not cover subsequent
commands; each command uses the reference’s remaining expiry and command timeout.
attach(reference) acquires a local connection in Scope. Its finalizer disconnects locally.
Creation option
Default
Meaning
maxElapsedMillis
Required
Positive safe integer; fixes the session’s absolute expiry
keepAliveMillis
600000
Requested provider idle allowance, from 1 through 600,000 ms
commandTimeoutMillis
30000
Positive safe integer; bounds each authorized native operation
The reference stores redacted session, context, and page identities, expiresAt, and
commandTimeoutMillis. Keep it in private host storage. keepAlive(sessionId) refreshes
provider inactivity without changing expiresAt; close(sessionId) requires confirmed
termination or exact-session absence. The owner supplies its existing expiry/cleanup trigger.
Provider expiry can happen sooner; attachment never creates a replacement session.
session.run(authorize, action) checks current host authority under the attachment’s lock before
passing its native Puppeteer page to trusted code. The host owns network policy, output bounds,
controller fencing, and action receipts. handoff, getLiveView, and getHandoffState take the
same authorization Effect and use the existing BrowserRun request/result schemas.
Await all SDK work inside the native callback. A settled SDK rejection preserves the session for
inspection while reporting uncertain dispatch; unfinished or unsafe operations can terminate it.
Neither outcome authorizes automatic replay.
session.fillCredential(request) requires BrowserCredentialAccess for each call. Its
FillCredentialRequest selects 1–8 fields by explicit selector and role within one native form;
an optional frame path selects at most eight nested iframes. The service authorizes current
origins and resolves host-only material. The helper fills without submitting and returns only
dispatch evidence and the number of acknowledged writes. Ordinary browser observations remain
available after filling.
If a fill times out, CredentialFillError reports reason: "timeout", the acknowledged
filled count, dispatch evidence, and whether browser cleanup was confirmed. A pending write
reply remains possibly-dispatched; its assignment is not included in filled.
Runs a provider-neutral PR review over supplied patches and immutable base/head source.
Returns a schema-validated report, validated paths and line anchors, and token usage.
The host supplies provider configuration, pricing, GitHub access, and publication.
Provides scripted models for offline tests.
Fixtures, certification, chaos, and CodeExecutor helpers have
dedicated imports.
Production packages must not depend on this package.