@empyria/restate

Restate.dev helpers for Empyria, a nanoservice framework built primarily on Bun: an Admin API client, a generic dynamic-dispatch service, cron-driven workflow scheduling, and Restate-aware input/output schema validation.

Targets Restate server 1.7.x and @restatedev/restate-sdk 1.17.x.

Requirements

• Bun >=1.4.0 or Node.js >=26
• Plain ESM, no build step, no TypeScript

Both requirements come from @empyria/classification and @empyria/common, which this package depends on and which use the native Temporal global for all date/time handling.

Install

bun add @empyria/restate

Usage

import { createRestateAdmin, withValidation, cronJob, cronJobInitiator } from '@empyria/restate'

const admin = createRestateAdmin({
    restateAdminURL: 'http://localhost:9070',
    restateURL: 'http://localhost:9071',
})

const services = await admin.listServices()

Everything is re-exported from the package root via index.js. Individual modules under lib/ can also be imported directly if you only need one:

import { checkServiceHandler } from '@empyria/restate/lib/Admin.js'

Modules

Agents: @empyria/restate/agent

LLM agents as Restate building blocks (formerly @empyria/restate-llm). A separate entry point, so the root import never loads the AI SDK. It needs the optional peer dependencies:

bun add ai @ai-sdk/openai-compatible @ai-sdk/provider

Recurring jobs

cronJob (a virtual object) runs a target handler on a cron schedule: each run sends the target, then schedules the next one from the current time, so a restart or an outage never causes a backlog of runs. Register cronJob on your endpoint, then create jobs with either:

• cronJobInitiator.create(request): a new job with a random ID each call (good for jobs created by users);
• ensureCronJob({restateURL, id, cronExpression, service, method, key?, payload?}): idempotent, for code that starts with the application. The job has the stable id you give it, so calling it on every start never adds a second job: the same request changes nothing, and a changed request (another schedule, target or payload) replaces the pending run under the same ID. Call it once the endpoint has registered, e.g. from setupRestate's registrationCallbackFn.
• getCronJob({restateURL, id}): the job's request and next run, or null when it does not exist;
• cancelCronJob({restateURL, id}): cancels the pending run, clears the job and reads it back: it resolves only when the job is really gone, and throws otherwise. Safe to repeat, and for a job that never existed.

Cron expressions are croner patterns (five fields, or six with seconds for tests). The target handler is sent the payload as its input, or no input when there is none.

Serving and registering an endpoint

setupRestate({ restateAdminURL, serviceURL: 'https://agent-service.internal:9080', services }) takes one complete URL, the address Restate reaches the endpoint at. It is registered as given and the endpoint listens on its port (80 or 443 when the URL has none or states the scheme's default), so the scheme is required (there is no separate host or port option); pass port when the endpoint listens on another port than the one in the URL (a container behind a Service or proxy). The health endpoint listens on the port after that unless healthPort is set.

It serves, registers the deployment, and deletes it again on SIGINT/SIGTERM. Invocations in flight are pinned to their deployment, so deleting it strands them: a restarted process cannot finish them and they can only be killed. For a process restarted at the same address, pass keepDeploymentOnShutdown: true and forceRegistration: true: Restate keeps the deployment ID when the same address registers again (checked against Restate 1.7), running invocations resume on the new process, and force updates the services and handlers in place (a plain re-registration keeps the old handler list). Only compatible changes are safe this way: an invocation of a removed or renamed handler cannot resume.

To serve without registering: when something else owns registration (a supervisor that registers a process's address once and restarts the process), use serveEndpoint({port, services}) instead: it only serves. Invocations already running on a deployment are pinned to its address, so the deployment must survive the process stopping and come back at the same address.

Shaping an agent

defineAgent options beyond the basics:

Keying block tools. A block tool calls another Restate building block. Its key(args, meta) and input(args, meta) hooks decide the target key and the parameter from the model's arguments and a per-call idempotency key (meta.idempotencyKey, unique for every tool call). A key that is the same for several calls (e.g. lock:<resource>) makes a virtual object run those calls one at a time and queue the rest durably; a key built from the idempotency key makes every call independent. input adds what the model must not control, such as the caller or the allowed folder. Both hooks must not throw: validate before the run, not inside them.

Size caps on tool calls. Tool arguments and results are journaled and replayed, so each tool has maxInputBytes (default 16 KB) and maxOutputBytes (default 32 KB). Oversized arguments are not run and the model is told why; an oversized result is replaced by an error the model sees. For an execute tool the check happens inside its own ctx.run, so the big value is never recorded.

What a run records. Each llm-step-N journals a small meta (model, finishReason, inputTokens, outputTokens, durationMs), never the prompt or the reply. The loop returns the same facts as trace (one entry per step with the tool names asked for) and logs one ctx.console line per step, which stays silent on replay.

Configuration. readLlmEnv(process.env) returns {LLM_BASE_URL, LLM_API_KEY?, MODEL_ID} and fails with a terminal 500 that names the missing setting and never prints a value.

Testing agents. @empyria/restate/testing exports fakeCtx (a journaling run, genericCall, awakeable, state and a capturing console) and the model-result helpers textResult, toolCallResult and sequence, without loading the AI SDK.

Error policy: a tool that fails terminally (rejected or timed-out approval, a callee's TerminalError, an execute tool out of retries) goes back to the model as an error result, so the agent can adapt. Transient errors are left to Restate to retry, and cancellation always propagates.

There is no official Restate Admin API client (verified directly against the published @restatedev/restate-sdk/-clients packages) — lib/Admin.js is a hand-written wrapper kept in sync with the live Admin API's OpenAPI spec (<admin-url>/openapi) by hand.

Every exported function is documented with JSDoc directly in its source file — hovering a function in VSCode or Zed shows its parameters and return type without any extra tooling, since both editors read JSDoc from plain .js files automatically.

Tests live under test/, one file per module, separate from the sources. They mock fetch and the Restate SDK client rather than requiring a live server — the one exception is setupRestate, which binds real ports and installs process signal handlers and is deliberately left untested (see AGENTS.md).

Scripts

bun run format       # check formatting (oxfmt)
bun run format:fix   # apply formatting
bun run lint         # lint (oxlint)
bun run lint:fix     # lint and fix
bun run test         # run tests with coverage

License

MIT © Imre Fazekas