Litro
Filesystem-first agent layer for Litro apps: tools that return server-rendered web components, durable NDJSON session streams, pluggable model providers. Deploys anywhere Nitro deploys.
npm install @beatzball/litro-agent pnpm add @beatzball/litro-agent
Filesystem-first AI agents for Litro, with tools that can return server-rendered components.
- A directory is an agent —
agents/<name>/agent.tsbecomes a durable endpoint; files intools/become its tools - Durable by construction — every event is written to the session log before it reaches the HTTP stream, so turns survive a client disconnect and a reconnect can replay from any point
- Tools can return UI — a tool returns both
datafor the model and server-renderedhtmlfor the page. The model never sees the html - Streaming — turns stream as NDJSON
SessionEvents over a single endpoint - No SDK dependency — providers are thin adapters this package owns; OpenTelemetry, when used, is passed in by your app rather than depended on
Requires @beatzball/litro. Agents are wired into the Litro server by a Nitro plugin, so this package is not usable standalone.
Installation
npm install @beatzball/litro-agent
# or
pnpm add @beatzball/litro-agent
Wiring an app takes a few edits to nitro.config.ts, package.json, and .gitignore. The Agents guide walks through them; create-litro template wiring is not in yet.
Directory convention
agents/
_config.ts <- optional runtime config (sessions, telemetry)
demo/
agent.ts <- default export: defineAgent({ ... })
instructions.md <- system prompt
tools/
get-weather.ts <- filename is the tool name
Each agent becomes one endpoint:
POST /__litro/agent/<agent>/<session> run a turn, stream the events
GET /__litro/agent/<agent>/<session> replay from ?from=<seq>, then live-tail
Defining an agent
// agents/demo/agent.ts
import { defineAgent } from '@beatzball/litro-agent';
import { anthropic } from '@beatzball/litro-agent/providers/anthropic';
export default defineAgent({
model: anthropic({ model: 'claude-sonnet-5' }),
instructions: './instructions.md',
});
Tools declare an input schema using any Standard Schema validator. The schema is required — it is what the model is handed and what the input is validated against before execute runs.
// agents/demo/tools/get-weather.ts
import { defineTool } from '@beatzball/litro-agent';
export default defineTool({
description: 'Look up the current weather for a city',
input: citySchema,
async execute({ city }) {
return { city, tempC: 21, summary: 'sunny' };
},
});
UI tools
A tool can return a rendered component instead of plain data. ui() server-renders it and returns both halves:
import { defineTool } from '@beatzball/litro-agent';
import { ui } from '@beatzball/litro-agent/ui';
import { html } from 'lit';
import { WeatherCard } from '../../../components/weather-card.js';
void WeatherCard; // named import + void: bare side-effect imports get tree-shaken
export default defineTool({
description: 'Show the weather as a card',
input: citySchema,
async execute({ city }) {
const tempC = 21;
const summary = 'sunny';
return ui(html`<weather-card .city=${city} .tempC=${tempC}></weather-card>`, {
data: { city, tempC, summary },
});
},
});
The model observes data; the html streams to the page and is never shown to the model. That separation is enforced in the runtime — for direct returns, generator returns, and nested results alike — and it holds in traces too.
The renderer follows LITRO_ADAPTER: Lit (Declarative Shadow DOM via @lit-labs/ssr) or FAST. The component must be registered server-side. Elena is not supported yet.
MCP server
litro mcp serve puts one agent's tools, and the ui:// documents
litro mcp-app build packed, in front of an MCP host over stdio:
// the host's server configuration
{
"command": "<project>/node_modules/.bin/litro",
"args": ["mcp", "serve", "--project", "<project>"]
}
Both halves of that are load-bearing, and neither is obvious. A host starts
this command with a working directory of its own choosing, and at least one
desktop host ignores a cwd field in its configuration entirely:
- Name the binary with a path.
npx litroresolves the name from the CURRENT directory, so from anywhere else it goes to the public registry and fails withnpm error code ENOVERSIONS / No versions available for litro, which says nothing about the real cause. - Pass
--project. Otherwise the project is the host's working directory, which is not yours.
Verified against Claude Desktop, which rendered the ui:// card on screen.
--agent <name> picks the agent when there is more than one; --apps-dir <dir>
points at a build output other than dist/mcp-apps; --timeout <ms> and
--max-result-bytes <n> tune the per-call guards.
Several servers run side by side — the command opens no port, and it exits when its host disconnects.
Tool names are global to a host. Two servers exposing a tool of the same name are ambiguous: the host picks one and the reader cannot tell which answered. Name a tool for what it does in the world, not just within its project.
| To get | Change needed |
|---|---|
| tools over stdio | nothing. litro mcp serve |
| a tool's app linked to it | one field on that tool: app: '<manifest name>' |
| the apps served | nothing, if litro mcp-app build has run |
| the SDK | pnpm add -D @modelcontextprotocol/sdk |
export default defineTool({
description: 'Get the current weather for a city.',
input: citySchema,
app: 'weather-card', // a dist/mcp-apps/manifest.json entry, or a literal ui:// address
async execute({ city }) { /* ... */ },
});
tools/list publishes _meta.ui.resourceUri for that tool, and the host reads
the document with resources/read. An app name the manifest does not list is a
startup failure, because the MCP Apps specification requires the resource to
exist on the server. visibility is emitted only when you set it —
app: { name: 'weather-card', visibility: ['app'] } hides a tool from the model
— because the extension already defaults to ['model', 'app'].
inputSchema is only as good as your schema library. It comes from
~standard.jsonSchema.input, so zod and arktype convert and a hand-rolled
schema publishes { type: 'object' }, which tells a host nothing about the
arguments.
ctx.event is undefined over stdio. There is no request, so a tool that
reads a cookie or a header has nothing to read.
@modelcontextprotocol/sdk is an optional peer dependency. Only a project
that serves MCP installs it; every other project builds and runs without it, and
litro mcp serve says what to add when it is missing.
Streamable HTTP, auth, progress notifications and outputSchema are later
phases of design/specs/2026-09-24-mcp-server.md and are not here yet.
Providers
| Import | Use |
|---|---|
@beatzball/litro-agent/providers/anthropic |
Anthropic models |
@beatzball/litro-agent/providers/openai-compatible |
OpenAI, or any compatible endpoint — Ollama, LM Studio, vLLM |
@beatzball/litro-agent/providers/scripted |
Deterministic canned responses for tests and demos |
API keys are read from the environment only. openaiCompatible takes an optional system name so a local endpoint is not mislabelled as OpenAI in telemetry.
Sessions
A session is an append-only log. The default store writes JSONL under .litro/sessions/; .litro/ holds conversation data and must be gitignored. Point the default store somewhere else with fileSessionStore({ dir }), or with the LITRO_AGENT_SESSIONS_DIR environment variable when you cannot reach the config — two servers sharing one project directory each need their own.
sqliteSessionStore (from @beatzball/litro-agent/sessions/sqlite) is the alternative for deployments running more than one instance against shared storage. It adds crash-safe sequence numbers and a cross-instance turn lease. It requires Node 22.5+, which is why it sits behind its own subpath — Node 20 users are unaffected and keep the JSONL store.
Telemetry
Agent turns can emit OpenTelemetry spans following the GenAI semantic conventions: invoke_agent per turn, chat per provider round, execute_tool per tool call.
Off unless you supply a tracer, and your app brings OpenTelemetry rather than this package depending on it:
// agents/_config.ts
import * as otel from '@opentelemetry/api';
import { defineAgentConfig } from '@beatzball/litro-agent';
import { otelTracer } from '@beatzball/litro-agent/telemetry';
export default defineAgentConfig({
telemetry: { tracer: otelTracer(otel) },
});
Prompt and completion content is not recorded by default. Even with capture enabled, a UI tool's rendered html is never recorded — only its data.
Client
@beatzball/litro-agent/client is browser-safe — it imports the isomorphic wire protocol and type-only shapes, never H3 or a Node built-in.
import { agentSession, hydrateUIResult } from '@beatzball/litro-agent/client';
Documentation
Full guide, security model, and the deferred-feature list: litro.dev/docs/agents
License
Apache-2.0
Changelog
0.7.1
Patch Changes
- 95b6336: Raise the
@modelcontextprotocol/sdkoptional peer dependency range from^1.30.0to^1.31.0, so an app that opts into the MCP server starts from a release patched against GHSA-6qxp-vccf-f47h (High, CVSS 7.5), where an OAuth client could send credentials to an authorization server chosen by the MCP server. - Updated dependencies [95b6336]
- @beatzball/litro@0.17.3
0.7.0
Minor Changes
-
49c281a: Serve an agent's tools and
ui://apps over MCP Streamable HTTP, as a Nitro route.The same server phase 1 put behind stdio now also answers over HTTP at
/__litro/mcp/:agent. One URL per agent, and one new subpath,@beatzball/litro-agent/mcp-handler, that the agents plugin's generatedserver/stubs/mcp-handler.tsfeeds the build-time manifest into. A project turns it on with two static handler entries innitro.config.ts— POST for the JSON-RPC channel, OPTIONS for the CORS preflight.The gates, in order:
Originmust be allowlisted when it is present (absent is allowed, because a host that is not a browser sends none), then a staticAuthorization: Bearertoken compared in constant time, then the agent's ownaccess(event)guard. No wildcard CORS is ever sent. A build that is neither marked local nor given a token refuses to start, and says which environment variable to set;litro devneeds neither.LITRO_MCP_TOKEN,LITRO_MCP_LOCAL,LITRO_MCP_ORIGINSandLITRO_MCP_APPS_DIRconfigure it. The route is stateless — no session id is issued or validated — so it works wherever Nitro deploys to more than one instance, and a client that disconnects mid-call closes its transport instead of leaking one.
Patch Changes
- Updated dependencies [4cdba19]
- @beatzball/litro@0.17.1
0.6.0
Minor Changes
-
bfe941d: Add an MCP server behind a new
./mcp-serversubpath: one agent's tools, and theui://documentslitro mcp-app buildpacked, in front of an MCP host over stdio.tools/listfrom the agent's tools, withinputSchemafrom the tool's Standard Schema and_meta.ui.resourceUrifor a tool that names an app.tools/callvalidates through the tool's schema, executes, drains a generator to its final value, and answers with text incontentand data instructuredContent. AUIResult'shtmlis never sent; theui://document is the view.resources/listandresources/readfrommanifest.json, bytes untouched. A uri from a request is looked up in that manifest or refused, and never becomes a file path.- Result hygiene: a non-object result is wrapped under one key (the SDK rejects a
non-record
structuredContent), a result over 1 MiB is truncated with a marker and the real size logged, a call has a 30s timeout, and a tool that throws answersisError: truerather than a protocol error. An unknown tool and invalid arguments are protocol errors, as the specification groups them. - New optional
appfield ondefineTool, naming amanifest.jsonentry or a literalui://address, with optionalvisibility. An app the manifest does not list is a startup failure. The chat loop ignores the field. @modelcontextprotocol/sdkis an optional peer dependency. A project that does not serve MCP is unaffected; one that does gets an actionable message naming the package when it is missing.
The pure half of a tool call — look up, validate, execute, drain, split a
UIResult— moves to one function that the chat loop and the server both call. Every store append, its order, and every span stay in the loop.serveMcpStdioreports when its host disconnects, so the caller can shut down rather than leaving a process behind.Streamable HTTP, auth, progress notifications and
outputSchemaare later phases.
Patch Changes
- Updated dependencies [bfe941d]
- Updated dependencies [1f347da]
- @beatzball/litro@0.17.0
0.5.0
Minor Changes
- 4d55cba:
defineMcpAppacceptsdomainand writes it to_meta.ui.domainin the resource descriptor. It asks the host for a dedicated sandbox origin — for an OAuth callback, a CORS policy, or an API key allowlist. The MCP Apps spec leaves the format to each host, so the value is carried through unchanged; a value that is not a non-empty string fails atdefineMcpAppwith a clear message. - 9330114: Agent tools now reach the provider with a real JSON Schema for their input. When a tool's Standard Schema vendor implements the Standard JSON Schema converter (
~standard.jsonSchema.input), the loop sends that schema, so the model sees field names, types and required fields. A vendor without a converter, a converter that throws, or a result that is not an object schema still sends{ type: 'object' }, as before.
Patch Changes
- 656a061: MCP App bridge:
window.litroMcp.callTool()andreadResource()now reject after 30 seconds when the host does not answer, instead of staying pending forever. The error is aTimeoutErrorwhose message names the method, and a late answer is ignored. Pass{ timeoutMs }as the last argument to change it per call;0waits forever.callTool(name, args)works as before. Theui/initializehandshake has no timeout.
0.4.0
Minor Changes
-
bf8b54e:
runtimeandapplyare parsed at build time, and a replaced fill step says soBoth are browser source as a STRING, so nothing type-checks them, nothing lints them, and a typo is invisible until the document is inside a host — where a
SyntaxErrorkills the whole script tag and the view never fills, with no error anyone sees and a build that reported success.buildMcpAppDocumentnow compiles both withnode:vmand refuses source that does not parse. It is a PARSE, NOT AN EXECUTION: no author code runs at build time.applyis wrapped in parentheses first, since it is inlined as the right-hand side of an assignment and has to be an expression.It cannot tell you the code is correct, and it cannot tell you the code is safe.
runtimeandapplyare trusted author code by design.Separately, a
runtimethat assignslitroMcpApplynow prints a warning. That assignment REPLACES the bridge's default fill step — the one that refusesinnerHTML,srcdocandon*in a tool result — and it does so without the app ever declaring anapply. A customapplymakes the same choice but declares itself by existing; this route did not. A warning rather than an error, because replacing the fill step is a legitimate thing to want.The check is a text match, and it says so: it finds the name in assignment position however it is reached —
window.,globalThis.,self., a local alias, bracket notation,??=— and strips comments first. A string that mentions the name still warns, andObject.assign(window, { litroMcpApply })does not. Both gaps are documented rather than implied away. -
5c09b18: MCP Apps:
uriis now optional indefineMcpApp()buildMcpAppDocument(app, { uri })takes a fallback address, which is what letslitro mcp-app buildderive one — package name as the authority, file path as the path. An app that declares its ownurikeeps it — the config wins over the fallback — so no existing app needs an edit.Code that reads the config may.
MCP_APP_CONFIGis exported, andapp[MCP_APP_CONFIG].uriis now typedstring | undefined— so assigning it to astringno longer type-checks — and it isundefinedat runtime for an app whose address is derived. Readdescriptor.urifrom the result ofbuildMcpAppDocument()instead, orurifrom the built.jsondescriptor ormanifest.json; those always hold the resolved address.URI validation moved from
defineMcpApp()tobuildMcpAppDocument(). An absenturiis only an error once it is known that no fallback is coming, anddefineMcpApp()cannot know that. A malformed one is still rejected, and now a path-derived address is held to the same standard as a hand-written one.Calling
buildMcpAppDocument()standalone is unchanged: with no file there is nothing to derive from, so it throws unless the config carries aurior one is passed in.
Patch Changes
- Updated dependencies [5c09b18]
- @beatzball/litro@0.16.0
0.3.0
Minor Changes
-
df9971f: Add
@beatzball/litro-agent/mcp-app— packages a Litro component as an MCP Appsui://resource.defineMcpApp()declares the app;buildMcpAppDocument()server-renders the shell and returns one self-contained HTML5 document plus theresources/*descriptor (text/html;profile=mcp-app, nested_meta.ui).A
ui://resource is a static, cached, data-free template — hosts prefetch it and reuse it across tool calls — so the shell is rendered with no data, and the inlined bridge fills it fromstructuredContentwhenui/notifications/tool-resultarrives after theui/initializehandshake. The bridge also answerspingandui/resource-teardown, reports its size so a flexible-height host can fit it, and exposeswindow.litroMcp.callTool().The default fill step refuses scripting sinks (
on*,innerHTML,outerHTML,srcdoc,src,href,style, …) and reports what it refused.structuredContentis server JSON and the host's default CSP permits inline event handlers, so a plainObject.assignonto the element would let a tool result execute code holdingwindow.litroMcp.callTool.The descriptor carries
nameas well asuri— the base MCPResourcetype requires both, and a server forwarding the descriptor intoresources/listwould otherwise emit an invalid entry.Packing fails if the document would load anything from outside itself, because the host's default CSP is
default-src 'none'and such a fetch fails silently inside the iframe.Works with the Lit and FAST renderers — the packager routes through
ui(), so it followsLITRO_ADAPTER. Elena is not supported, becauseui()does not support it yet.
Patch Changes
-
a9345f4:
fileSessionStoreno longer breaks permanently when its session directory disappears, and can be pointed elsewhere withLITRO_AGENT_SESSIONS_DIR.The store creates
.litro/sessionsonce and caches that result for the life of the process. If the directory was then removed — a cleanup script, a log rotation, a tmpfs reaper — every laterappendfailed withENOENTforever and the agent endpoint returned a 500 error event on every turn until the server restarted. It now recreates the directory and retries the append once.LITRO_AGENT_SESSIONS_DIRoverrides the default directory (an explicitfileSessionStore({ dir })still wins). It exists for the case where two servers run against the same project directory and must not share session state. -
Updated dependencies [df9971f]
- @beatzball/litro@0.15.0
0.2.2
Patch Changes
- Updated dependencies [15c112d]
- @beatzball/litro@0.14.0
0.2.1
Patch Changes
- 83c8d5a: Remove the
sourceexport condition so consumers always resolve the compiled output. Publishingsourcepointed installed apps at TypeScript that Vite does not transpile insidenode_modules, which produced an unparseable client bundle on Vite 8. No API change. - Updated dependencies [83c8d5a]
- @beatzball/litro@0.13.1
0.2.0
Minor Changes
-
040f4b6: ## OpenTelemetry GenAI spans
Add OpenTelemetry GenAI spans (v0.1 milestone, item 1).
Agent turns now emit spans following the OpenTelemetry GenAI semantic conventions:
invoke_agent <agent>per turn,chat <model>per provider round, andexecute_tool <tool>per tool call. Tool spans are parented to the turn rather than to the chat round that dispatched them, so a tool run reads as a sibling of the model call, not a child of it.Telemetry is opt-in and off by default. Configure it in
agents/_config.ts:import * as otel from "@opentelemetry/api"; import { defineAgentConfig } from "@beatzball/litro-agent"; import { otelTracer } from "@beatzball/litro-agent/telemetry"; export default defineAgentConfig({ telemetry: { tracer: otelTracer(otel) }, });The package takes no dependency on
@opentelemetry/api— the namespace is passed in, so the runtime always uses the same api singleton the app registered its SDK against. Any object matching the exportedAgentTracerinterface works just as well. With no tracer configured every span hook short-circuits to a shared no-op before building any attributes.Prompt, completion and tool payloads are NOT recorded unless
captureContent: trueis set, matching the semantic conventions' opt-in stance on content capture. AUIResult'shtmlis never recorded even then — the rule that keeps rendered markup out of the model channel now also keeps it out of traces. Span errors carry a semconverror.typeand a message, never a stack.Also additive, in support of the above:
Providergains an optionalinfo: { system, model }used forgen_ai.provider.name/gen_ai.request.model; the built-in openai-compatible, anthropic and scripted providers populate it, and the attributes are omitted entirely for a provider that does not.openaiCompatible()accepts asystemoption so an adapter pointed at a non-OpenAI compatible endpoint (Ollama, vLLM, ...) is not mislabelled in traces.- The turn loop now reads the
doneprovider event'susagefield, which was previously accepted by the type and discarded. Token counts appear per round onchatspans and summed on theinvoke_agentspan.
No behaviour changes: the session log, the NDJSON wire stream, and the event sequence are byte-identical whether telemetry is on or off.
node:sqlitesession storeAdd a
node:sqlitesession store with a cross-instance turn lease (v0.1 milestone, item 2).@beatzball/litro-agent/sessions/sqliteis an alternative to the default JSONL store, for apps running more than one instance:// agents/_config.ts import { defineAgentConfig } from "@beatzball/litro-agent"; import { sqliteSessionStore } from "@beatzball/litro-agent/sessions/sqlite"; export default defineAgentConfig({ sessions: sqliteSessionStore({ path: ".litro/sessions.db" }), });What it adds over the JSONL store:
- Crash-safe sequence numbers.
seqis computed asMAX(seq)+1inside the sameBEGIN IMMEDIATEtransaction as the insert, so there is no in-memory counter to lose on restart and two writers can never mint the same seq. WAL mode lets replays and live tails read while a turn appends;synchronous = FULLkeeps the durability promise that makes append-before-wire meaningful. - A real turn lease.
SessionStoregains two OPTIONAL methods,acquireLeaseandisLeased. A store that implements them upgrades the runtime's per-process turn lock to a cross-instance one — without it, two app instances each pass their own local check and run concurrent turns on one session. The holder renews on a heartbeat; losing the lease stops the heartbeat but never aborts an in-flight turn, per the durability contract. A lease only lapses if an instance stalls or dies for a full TTL, at which point another instance may recover the session. - A store-poll live tail. A
GETthat reconnects while the turn is running on a DIFFERENT instance cannot reach that instance's in-process broadcast, so it polls the store instead — checking the lease before each drain, so a turn that ends between two polls is never truncated. Without this, multi-instance would be a half-claim: the lock would be honest but reconnects would silently return a partial log.
Requires Node 22.5+ (
node:sqlite), which is why it lives behind its own subpath and is never in the default import graph — the package'senginesrange still admits Node 20, where the default JSONL store continues to work unchanged. Node prints its ownExperimentalWarningfornode:sqlite.Known limitations, deliberate for this milestone:
DatabaseSyncis synchronous, so an append briefly blocks the event loop (correctness first, matching the JSONL store's fsync-per-append); and the defaultfileSessionStoreimplements no lease, so it stays single-instance exactly as before — nothing about existing deployments changes.
0.1.1
Patch Changes
- e576f80: Bump
nitropackfrom^2.13.1to^2.13.4, resolving Medium-severity advisories GHSA-5w89-w975-hf9q and GHSA-9phm-9p8f-hw5m. - fbcbe21: Session store hygiene:
fileSessionStoreno longer pays amkdirsyscall on every singleappend()call (cached once per store instance, with retry-on-failure preserved), and its internal per-session promise-chain registry now drops an entry once it settles and nothing has chained onto it since, instead of retaining one for every distinct session id for the lifetime of the process. - Updated dependencies [141513a]
- Updated dependencies [e576f80]
- Updated dependencies [16d2705]
- @beatzball/litro@0.13.0
0.1.0
Minor Changes
- 97e80be: Initial release: filesystem-first agent layer for Litro apps.
agents/<name>/directories become durable session endpoints (POST|GET /__litro/agent/:agent/:session) streaming NDJSON session events. Tools (defineTool, Standard Schema input) can returnUIResults — server-rendered design-system components (Lit DSD or FAST) whosedatais what the model observes while the HTML streams to the surface. Includes openai-compatible, anthropic, and scripted providers; JSONL session store with reconnect/replay (resume(fromSeq)); browser client withhydrateUIResult; Nitro build plugin following the Server Actions wiring pattern.
Patch Changes
- Updated dependencies [97e80be]
- @beatzball/litro@0.12.0