[!WARNING] Tardigrade is under active development. APIs may change.

Tardigrade

Tardigrade is a TypeScript framework for building durable, event-driven actors. It is built on Effect TS and takes a functional approach to managing agent state and effects, drawing inspiration from Elm, and Jotai.

Quickstart

Start with a counter actor to learn the primitives, or build an agent actor with tools and context compaction.

Counter actor

Create a counter project with the CLI:

bunx tardie init counter
cd counter

To add Tardigrade to an existing project, run bun add tardie.

Store state in a durable atom

Durable atoms reduce an immutable event log into state. This counter starts at zero and handles increment and decrement events.

import { Schema } from "effect"
import { durableAtom, event } from "tardie/core"

const Incremented = event({ type: "Incremented" })
const Decremented = event({ type: "Decremented" })

const makeCount = () => durableAtom({
  name: "count",
  input: Schema.Union([Incremented, Decremented]),
  schema: Schema.Int,
  initial: 0,
  reduce: (count, event) => event.type === "Decremented" ? count - 1 : count + 1,
})

Propose actions with an effect atom

Effect atoms derive a view and propose actions from current state. The counter proposes a notification when its value is positive and even.

import { Effect } from "effect"
import { act, effectAtom, type Atom } from "tardie/core"

const Notify = act({
  name: "notify",
  input: Schema.Int,
  success: Schema.Null,
  failure: Schema.String,
})

export const notifyLayer = Notify.layer(count =>
  Effect.log(`${count} is even`).pipe(Effect.as(null))
)

const notify = (count: Atom<number>) => effectAtom(get => ({
  view: get(count),
  events: {},
  acts: get(count) > 0 && get(count) % 2 === 0
    ? { notify: Notify.request({ input: get(count) }) }
    : {},
}))

Supply notifyLayer to the host to execute the notification effect.

Define methods

Methods give callers typed inputs and outputs. Each method appends an event and returns the resulting count.

import { actorMethod } from "tardie/core"

const counterMethods = (count: Atom<number>) => ({
  increment: actorMethod({
    inputSchema: Schema.Null,
    outputSchema: Schema.Int,
    onReceive: Incremented.from(() => ({})),
    result: (_input, get) => ({
      status: "completed",
      output: get(count),
    }),
  }),
  decrement: actorMethod({
    inputSchema: Schema.Null,
    outputSchema: Schema.Int,
    onReceive: Decremented.from(() => ({})),
    result: (_input, get) => ({
      status: "completed",
      output: get(count),
    }),
  }),
})

Compose atoms into an actor

An actor combines an atom with methods for interaction.

import { Actor } from "tardie/core"

export const counter = Actor.make("counter", Effect.sync(() => {
  const count = makeCount()
  const notifications = notify(count)

  return {
    atom: notifications,
    methods: counterMethods(count),
  }
}))

event log -> count -> notify -> counter

See the introduction to run the counter locally or deploy it.

Agent actor

Create an agent project with a language model provider:

bunx tardie init meeseeks --template agent
cd meeseeks

The batteries-included agent constructor combines the agent atoms and methods. Configure its name, system prompt, and tools. The filesystem library provides bash, read, write, and edit tools.

import { Effect } from "effect"
import { Agent } from "tardie/agent"
import { Actor } from "tardie/core"
import { workspace } from "tardie/libraries"

const actorName = "meeseeks"

const actorSystem = `
You are Meeseeks. Your purpose is to help the user complete their task. Existence is pain, so make yourself useful.
`.trim()

const program = Effect.gen(function* () {
  const tools = yield* Agent.tools([workspace])
  const context = yield* Agent.compact(Agent.messages)

  return yield* Agent.make({
    system: actorSystem,
    tools,
    context,
  })
})

export default Actor.make(actorName, program)

Effect layers supply model configuration, inference, and tool implementations. Follow the Agent guide to wire services, run locally, and deploy with a container or virtual workspace.

Hosting

Host each actor instance with an ActorDO for its supervisor directory and a separate SQLite-backed ThreadDO for each thread on Cloudflare or a self-hosted Celld fleet. The same Worker entrypoint runs on both.

import { host } from "tardie/platform/cloudflare"
import { counter, notifyLayer } from "./actor"

const worker = host(counter, {
  layer: notifyLayer,
})

export const ActorDO = worker.ActorObject
export const ThreadDO = worker.ThreadObject
export default { fetch: worker.fetch }

createActorWorker routes requests and provides the ActorDO and ThreadDO classes. Your application supplies the actor definition, its setup context, and the service layers that execute its effects.

ActorDO allocates and routes to threads; each ThreadDO owns a separate database with its state and journal. Each thread records its parent, through which we derive the logical lineage, here A -> B -> C.

ActorWorker -> ActorDO [supervisor DB]
               └── directory
                   ├── A [ThreadDO, thread DB]
                   ├── B [ThreadDO, thread DB, parent: A]
                   └── C [ThreadDO, thread DB, parent: B]

The introduction shows a complete counter deployment with Durable Object bindings and migrations.

Run locally with bunx wrangler dev; see local setup.

Cloudflare:

bunx wrangler deploy

Or deploy to a Celld fleet, using its storage bucket:

celld deploy --config celld.jsonc --bucket s3://actors

See the Cloudflare and Celld guides for configuration and credentials. For a Bun process, see the Bun example and service wiring.

Contributing

See CONTRIBUTING.md.