Runtime helpers for Apps that follow the Lazurio Module Standard: read the
listener a Lazurio Platform assigned, answer health, shut down cleanly on
SIGTERM, learn who came to the App and with which application role, and
offer the App's tools to agents through /mcp and WebMCP.
This is the only shared runtime library of a Module. It stays small on purpose: reading the runtime environment, health, shutdown and dev server options, and the one tool contract for agents. It is not a framework, it has no runtime dependencies, and anything beyond that belongs in the Module itself.
bun add github:Lazurio/module-kit#v0.4.0The package ships TypeScript sources (exports and types point at
src/index.ts). Bun runs them natively and there is no build step. The source
uses only erasable syntax and compiles under strict,
noUncheckedIndexedAccess and exactOptionalPropertyTypes.
An App reads its host and port only from
LAZURIO_RUNTIME_LISTENER_<ID>_HOST and LAZURIO_RUNTIME_LISTENER_<ID>_PORT,
and its browser origin from LAZURIO_RUNTIME_LISTENER_<ID>_EXTERNAL_ORIGIN
(hosted entrypoint only). <ID> is the listener id upper-cased, with -
mapped to _. When a variable is missing or invalid, the helpers throw
ModuleKitError with code listener-missing, and the message names the exact
variable. They never fall back to PORT, LAZURIO_RUNTIME_HOST/_PORT, lease
files or defaults. The standard says such an App does not run and exits with
code 2:
import { type Listener, listener, ModuleKitError } from "@lazurio/module-kit";
let app: Listener;
try {
app = listener("app");
} catch (error) {
if (!(error instanceof ModuleKitError)) throw error;
console.error(error.message);
process.exit(2);
}| Function | Returns |
|---|---|
listener(id, env = process.env) |
{ host, port, externalOrigin } (externalOrigin is null unless hosted); throws listener-missing |
listeners(env) |
every listener as { id, host, port, externalOrigin }, from LAZURIO_RUNTIME_LISTENERS_JSON when present, else derived from LAZURIO_RUNTIME_LISTENER_*; a malformed JSON value throws listeners-invalid |
runtimeIdentity(env) |
{ schemaVersion, appId, entrypointId } from LAZURIO_RUNTIME_SCHEMA_VERSION, _APP_ID and _ENTRYPOINT_ID, or null |
allowedHosts(id, env) |
the external origin's hostname (if any) plus localhost, 127.0.0.1 and ::1; never a wildcard |
viteShutdownPlugin({ closeTimeoutMs = 2000 }) |
Vite plugin: SIGTERM/SIGINT closes every connection, bounds server.close() and exits 0 (Vite alone reports 128 + signal and an open keep-alive connection can hold close()); use in vite.config.ts plugins for dev and preview |
viteServerOptions(id, env) |
{ host, port, strictPort: true, allowedHosts } for Vite server |
astroServerOptions(id, env) |
{ host, port, allowedHosts } for Astro server |
health(ready) |
(req) => Promise<Response>: 200 {"status":"ok"} when ready() is true, else (or when it throws) 503 {"status":"starting"} |
withHealth(handler, path = "/healthz", ready = () => true) |
a Bun.serve fetch handler that answers path with health(ready) and passes everything else on |
onShutdown(fn, { timeoutMs = 10_000 }) |
on SIGTERM/SIGINT, runs fn once and exits 0; exits 1 if fn throws or does not finish within timeoutMs; returns a function that removes the handlers |
requireEnvironment(names, env) |
the values as a record; throws environment-missing naming every absent or empty variable |
| appAccess(request, id = "app", env) | who came to the App for this request and with which application role: always { entry, appRole, person, source, reason }, see Who came and with which role |
| isLazurioUsername(value) | whether a value is a Lazurio username (3–39 lowercase letters and digits, single dashes between them, not UUID-shaped, not a service account) |
ModuleKitError.code is one of listener-missing, listeners-invalid or
environment-missing.
Lazurio decides who may open a Module's App and with which application role,
Application Admin or Application User, and the Organization decides in the
Module's code what each role may do (Lazurio decisions 0231 and 0234).
appRole carries the role as a stable value, "admin" for the Application
Admin and "user" for the Application User; the values do not change with the
names. appAccess is the only way a Module learns it, and its answer is the
stable contract: its fields and values never change meaning or disappear, and
new information comes as new fields. The contract is the Module Standard's
"Who came and with which role" in Lazurio Platform (docs/module-standard.md).
import { appAccess } from "@lazurio/module-kit";
// inside Bun.serve fetch(request), on every request, including APIs
const access = appAccess(request, "app");
if (access.appRole === null)
return new Response("Lazurio did not say who you are.", { status: 403 });
const mayApprove = access.appRole === "admin"; // the Organization's own rule
const author = access.person?.subject ?? null; // null: from inside the EnvironmentEvery answer has the same five fields:
entry |
appRole |
person |
source |
reason |
When |
|---|---|---|---|---|---|
environment |
admin |
subject and username | gateway |
null |
the person has the whole Environment where the App runs |
app |
admin or user |
subject and username | gateway |
null |
the person has this App only, with the application role the Organization gave them |
local |
admin |
null |
null |
not-hosted, not-through-gateway, local-entry |
from inside the Environment: no gateway in front of the App (a person's own computer), a request to a loopback address (a sibling, a script, an agent), or the Environment browser's local entry |
unknown |
null |
null |
null |
no-identity |
through the gateway without a valid statement, or a Host that is neither the App's hostname nor loopback: no role, show "unavailable" |
source says who stated the person: gateway today, from its own admission
answer after removing every copy a client sent; an identity signed by Lazurio
Auth for use outside the Environment will come as auth. A request whose
Host names the App's external hostname, in any letter case, with any port or
a trailing dot, as the gateway matches it, counts only by the gateway's
statement; a missing, repeated or malformed statement is unknown, never a
role.
- Enforce on the server, per request. Check the role for every request, including APIs, downloads, WebSockets and direct URLs, never only by hiding a button, and never cache it: after another account signs in, the next request names the new person.
- Remember a person by
subject, showusername(nullwhen the gateway named none). Never fill in a name from the browser, the operating system account or the Environment's Assigned User. - Finer roles are the Module's. Approvers, technicians and the like live in
the Module's own data, keyed by
subject. Lazurio keeps only the two application roles, Application Admin and Application User. - Its boundary is the Environment. A process on the Environment that reaches the App's loopback port could send anything, as it could read the App's data. The statement holds against visitors who have only the App, not against the Environment's operator. Do not forward it to a sibling or another service.
- Transport is not the contract.
GATEWAY_HEADERSnames the headers the gateway uses today so that a Module's own tests can build requests; read them only throughappAccess.
Proof through the real gateway. bun proof/gateway.ts <Machines checkout>
renders the Lazurio workspace gateway from a Machines checkout, runs it with
Caddy in front of a TypeScript App and a Python App and checks every Host form
a client can send: the App's hostname as is, in upper case, with :443 or
another port (the gateway's statement counts: environment/admin with a
person, unknown without one, nothing without a session) and with a trailing
dot (refused by the gateway itself). A client's forged statement never counts
and no request through the gateway is local. It needs Caddy, OpenSSL and uv,
so it is not part of bun test.
Python: app_access(headers, "app") takes the request headers as a mapping
(matched case-insensitively; a repeated header reads as none) and returns
AppAccess(entry, app_role, person, source, reason) with
AppPerson(subject, username) or None, by the same rules; app_role takes
the same values, "admin" for the Application Admin and "user" for the
Application User.
An App defines its tools once, on its server, and offers them through two transports over the same handler (Module Standard, "Agents in the App"):
/mcp: a stateless MCP server (Streamable HTTP, JSON answers, POST only, no batches, body bounded to 64 KiB) behind the Application host's gateway, which admits a Lazurio Auth Bearer token with the application's role;- the page:
GET /api/agent-toolslists the tools for the person who has the page open andPOST /api/agent-tools/<name>calls one with the page's own session (only from the App's own origin).@lazurio/module-kit/webmcpregisters them as WebMCP tools, so an agent with the App open in the Environment browser calls them directly.
Both read who came only through appAccess, list only the tools the role and
the writer mode allow, and refuse with the same codes. Every registry also
answers get_app_context: module, version, data generation, production or
environment, entry, role and whether the caller may change data now.
import { z } from "zod";
import { createToolRegistry, defineTool } from "@lazurio/module-kit/tools";
const FindInput = z.strictObject({ query: z.string().max(200) });
const registry = createToolRegistry({
app: { module: "revisions", version: "1.4.0", dataGeneration: "v3" },
tools: [
defineTool({
name: "find_revisions",
description: "Najde revize podle čísla, zákazníka nebo adresy.",
input: FindInput,
inputSchema: z.toJSONSchema(FindInput, { io: "input" }),
minRole: "user",
effect: "read",
untrustedContent: true,
// The same domain service the interface calls, never the data files.
run: async ({ query }, { access }) => ({
ok: true,
data: { items: await revisions.find(query, access) },
}),
}),
],
});
Bun.serve({
hostname: host,
port,
fetch: withHealth(async (request) => {
const path = new URL(request.url).pathname;
if (path === "/mcp") return registry.handleMcp(request);
return (await registry.handlePage(request)) ?? app(request);
}),
});On the page:
import { registerAgentTools } from "@lazurio/module-kit/webmcp";
const tools = await registerAgentTools({
// View tools of the page never change data.
viewTools: [{ name: "open_revision", description: "Otevře revizi.",
inputSchema: { type: "object", properties: { id: { type: "string" } } },
execute: ({ id }) => router.open(id) }],
});
// After a sign-in or a role change: await tools.refresh();Effects (Lazurio Module Standard, "Effects and publication"; decision D1
of LZD-0037). read changes nothing (finding, reading, computing, producing a
file such as a PDF) and is offered in the read-only mode as well. prepare
changes no shared data and prepares a step a person completes in the
interface. write is a draft: a reversible change that publishes nothing, which
an agent makes on its own. publish is a publication: an irreversible step or
one others see (an approval, a signature, a sending, a deletion, a movement of
money, the publication of a draft or of data to everyone). An agent calls it
only after the person's explicit "Publikuj". A publication is a tool of its own,
never a mode of a draft tool, and the registry gives it destructiveHint: true
itself. A draft and a publication are offered only while dataWriter allows
writing (LAZURIO_RUNTIME_DATA_WRITER=true; unset, never in a runtime that
states LAZURIO_RUNTIME_DEPLOYMENT=production, else only to a local or
Environment entry). Until the Owner decides how the App knows that the person
said "Publikuj", a production application offers no publication, on /mcp
or on the page, and a development version does
(AGENT_PUBLICATION_IN_PRODUCTION, the one place that decision changes). A
0.4 declaration of a publication (effect: "write" with publishesData: true, or publicationConsent) is refused at registration.
Answers and refusals. A tool returns { ok: true, data, files? } or
{ ok: false, reason, message, current_revision?, details? } and never throws
for an expected outcome. The common reasons are identity_unavailable,
forbidden, unknown_tool, invalid_input, not_found, record_changed
(with current_revision), data_read_only, unavailable and
internal_error; a Module adds domain reasons of its own. On /mcp a refusal
is a tool result with isError and structuredContent; a file is an embedded
resource. Every call writes one audit line (channel, tool, entry, subject,
role, outcome, duration), never the input or the answer.
A data layer that decides by the method. Every tool call is a POST.
An App whose data layer chooses a read or a write path by the HTTP method asks
registry.effectOf(request) instead: the named tool's effect for tools/call
and page calls, read for other MCP methods and the manifest, and null
(treat as a write) for any other path or anything it cannot tell. It reads a copy, so the request stays
readable.
Tests. @lazurio/module-kit/tools/testing builds requests as the gateway
states them (gatewayRequest, hostedEnvironment, localEnvironment) and
calls the registry (mcpCall, mcpToolNames, mcpTool, pageTool), so a
Module tests the list per role, the refusal without a role, writes in the
read-only mode and record_changed on both transports.
import { listener, onShutdown, withHealth } from "@lazurio/module-kit";
const { host, port } = listener("app");
let ready = false;
const server = Bun.serve({
hostname: host,
port,
fetch: withHealth(() => new Response("hello"), "/healthz", () => ready),
});
ready = true;
onShutdown(async () => {
await server.stop();
});The /healthz path must match lazurio.runtime.listeners[].health.
vite build has no listener, so read it only when serving:
// vite.config.ts
import { viteServerOptions } from "@lazurio/module-kit";
import { defineConfig } from "vite";
export default defineConfig(({ command }) => ({
...(command === "serve" ? { server: viteServerOptions("app") } : {}),
}));Astro also evaluates server during astro build, so read it only for
astro dev:
// astro.config.ts
import { astroServerOptions } from "@lazurio/module-kit";
import { defineConfig } from "astro/config";
const dev = process.argv.includes("dev");
export default defineConfig({
...(dev ? { server: astroServerOptions("app") } : {}),
});The python/ directory holds lazurio-module-kit, the same listener,
health and app_access semantics for a Python Module (uv + pyproject.toml):
uv add "lazurio-module-kit @ git+https://github.com/Lazurio/module-kit@v0.3.0#subdirectory=python"import asyncio
import sys
from lazurio_module_kit import ModuleKitError, health, listener
try:
app = listener("app") # Listener(host, port, external_origin)
except ModuleKitError as error:
print(error, file=sys.stderr)
sys.exit(2)
check = health(lambda: True)
response = asyncio.run(check()) # HealthResponse(status, body, content_type)health is framework-neutral: it returns the status, JSON body and content
type, and your server writes them.
bun install
bun run check # tsc --noEmit + biome check
bun test
cd python
uv sync --frozen
uv run ruff check . && uv run pyright && uv run pytestMIT, Copyright (c) 2026 Lazurio.