# Server Runtime

> Use when working on packages/theseus-server RPC/HTTP process assembly, runtime layer wiring, server handlers, provider configuration, or server-side serialization.

- Skill: `theseus-run/server-runtime` (Agent Skill)
- Install (CLI): `npx skillmds@latest add theseus-run/server-runtime`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theseus-run/server-runtime/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theseus-run (https://skillmd.com/u/theseus-run)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theseus-run/server-runtime

---


# Server Runtime

Use this skill for `packages/theseus-server`. For runtime host, systems, sinks,
projections, active registry, tool catalog, or SQLite runtime stores, use the
`runtime-engine` skill instead.

## Read First

- `packages/theseus-server/src/handlers.ts`
- `packages/theseus-server/src/index.ts`
- `packages/theseus-server/src/serialize.ts`
- `packages/theseus-runtime/src/index.ts`
- `packages/theseus-runtime/src/live.ts`

## Boundaries

- Handlers stay at the transport boundary. They call `TheseusRuntime` and map runtime errors to RPC errors.
- `TheseusRuntime` owns dispatch lifecycle, tool hydration, current capsule binding, registry updates, and persistence side effects.
- Tool catalog code lives in `packages/theseus-runtime`. Do not let handlers hydrate tools directly.
- Serialization belongs in `serialize.ts`; do not scatter wire-shape conversion through runtime logic.
- SQLite persistence belongs behind runtime store/capsule services or runtime projections, not server handlers.
- Server may assemble layers and providers. It must not become the runtime.
- Do not add plugin routing, dynamic extension loading, or extension registry
  semantics in server. Server exposes/adapts runtime commands and queries; it
  does not define the harness extension model.

## Error Rules

- Runtime errors should be typed tagged errors.
- Handler error mapping should be explicit and stable for clients.
- Do not leak raw causes through RPC responses unless the API contract says so.

## Verification

- Run `bun run typecheck` after runtime, handler, or RPC schema changes.
- Run relevant server/core tests when dispatch lifecycle, persistence, or serialization behavior changes.