TypeScript SDK

Complete reference for @yoke/sdk — defineRuntime, actors, portals, events, filters, queues, state, schedules, and context APIs.

The @yoke/sdk package is the author API for the internal TypeScript package the kernel loads. It is not your product's public SDK. Your users never import it.

Your product server embeds yoke-runtime (Rust). This package is what that runtime executes inside Deno — defineRuntime(), actors, portals, tools. See Embed Yoke in your product.

Every runtime loads a single default export from yoke.ts built with defineRuntime().

// yoke.ts — default export required
import { defineEvents, defineFor, defineRuntime, z } from "@yoke/sdk";

const events = defineEvents({
  "work.assigned": z.object({ role: z.string(), lang: z.string() }),
});

export default defineRuntime()
  .events(events)
  .portals(({ events }) => { /* ... */ })
  .actors(({ events, portals }) => { /* ... */ })
  .build();

Package contract

Requirement	Detail
Entry file	`yoke.ts` at package root
Default export	Must be a `defineRuntime()` builder (call `.build()` or export the builder — the worker accepts both)
Events	Declare once with `defineEvents()`; Zod schemas validate payloads at append and in `process()`
Zod re-export	Import `z` from `@yoke/sdk` (Zod 4)

The Deno worker loads your package, registers definitions in the Rust kernel, and bridges ctx.* calls over JSON-RPC. See Runtime for the IPC surface.

Core concepts

Concept	SDK entry	Role
Events	`defineEvents`, `ctx.append`	Global append-only stream; all communication flows through typed events
Actors	`defineActor`, `defineFor().actor`	Stateful, queued handlers; one or many instances per definition
Portals	`definePortal`, `defineFor().portal`	Singleton ingress/egress (HTTP routes + typed interface)
Filters	`InstanceFilter`, `filterFromConfig`	Instance subscription to stream events
Queues	`QueuePolicy`, `queueSelectFromConfig`	Per-instance drain order and concurrency
State	`ctx.state`, `ctx.sqlite`	Durable per-instance SQLite (typed document + raw SQL)
Schedules	`ctx.schedules`, `ctx.schedule`	Keyed delayed events owned by an instance
Context	`ActorCtx`, `PortalCtx`	Full runtime surface inside `process`, `start`, routes, lifecycle hooks

Runtime builder flow

defineRuntime()
  .events(eventMap)           // register Zod payload schemas
  .inferenceStack(stack)       // optional LLM routing
  .agents(() => …)             // optional high-level agent definitions
  .chatPlatforms(({ agents }) => …)  // optional chat platform integrations
  .bootstrap(async (ctx) => …) // optional one-shot instance provisioning
  .portals(({ events }) => …)  // portal definitions; APIs flow to actors
  .actors(({ events, portals }) => …)
  .build()                     // RuntimeDefinition → loaded by DenoHost

Prefer the callback style (.portals(), .actors()) so events and portal APIs are threaded through types automatically. Legacy .portal(name, def) / .actor(name, def) methods remain available.

Reference pages

Page	Topics
defineRuntime	Builder methods, `defineFor`, `defineEvents`, `agents`, `chatPlatforms`, `bootstrap`, `inferenceStack`
Actors	`defineActor`, `process`, lifecycle, queue, filters, `sqliteStoreId`
Portals	`definePortal`, `routes`, `start`, `interface`
Events	`StreamEvent`, `AppendInput`, Zod validation, priority, `groupId`
Filters	Declarative vs function filters, `FanoutIndex`, `filterFromConfig`
Queues	FIFO/LIFO/random/custom, concurrency, priority groups, inherit
State & SQLite	`ctx.state`, CAS updates, `__yoke_state`, multi-store segments
Schedules	`ScheduleManager`, keyed delayed events, HTTP client
Context API	Full `ActorCtx` / `PortalCtx` surface, conversations, instances, LLM

Type helpers

Common inference utilities exported from @yoke/sdk:

import type {
  InferSchema,
  InferConfig,
  InferState,
  InferActorConfig,
  InferActorState,
  InferPortalApi,
  InferPortalClients,
} from "@yoke/sdk";

Embed Yoke in your product — Rust host API vs this package
Runtime architecture — kernel components and data flow
Ops bridge — Rust ↔ Deno JSON-RPC ops
Mental model — stream, fan-out, instances
Quick start — minimal inline package tutorial