@warlock.js/core 5.30.0 → 5.31.0

package/skills/run-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-app
-description: 'Three operational commands — `warlock dev` (HMR + type-gen + health checks), `warlock build` (esbuild bundle), `warlock start` (spawn the production bundle). All flags, all `warlock.config.ts` knobs that shape them. Triggers: `warlock dev`, `warlock build`, `warlock start`, `devServer`, `--fresh`, `--skip-typings`, `--skip-health`, `outdir`, `outFile`, `sourcemap`, `PortInUseError`, `assertPortIsAvailable`, `EADDRINUSE`, `EsbuildBinaryMissingError`; "start the dev server", "build for production", "run the bundle", "skip type generation", "tune watch globs", "dev server keyboard shortcuts", "press r to restart", "press q to quit", "restart the dev server", "port already in use"; typical config `warlock.config.ts > devServer / build`. Skip: writing a custom CLI — the `write-cli-command` topic; config shape — the `configure-app` topic; competing tooling `nodemon`, `tsx`, `ts-node-dev`, `esbuild` direct.'
+description: 'Three operational commands — `warlock dev` (HMR + type-gen + health checks), `warlock build` (esbuild bundle), `warlock start` (spawn the production bundle). All flags, all `warlock.config.ts` knobs that shape them. Triggers: `warlock dev`, `warlock build`, `warlock start`, `devServer`, `--fresh`, `--skip-typings`, `--skip-health`, `outdir`, `outFile`, `sourcemap`, `PortInUseError`, `assertPortIsAvailable`, `EADDRINUSE`, `EsbuildBinaryMissingError`, `detectJavaScriptRuntime`, `assertNodeOnlyCommand`, Bun, Deno, `bun dist/app.js`, `deno run -A`; "start the dev server", "build for production", "run the bundle", "skip type generation", "tune watch globs", "dev server keyboard shortcuts", "press r to restart", "press q to quit", "restart the dev server", "port already in use", "run on Bun", "run on Deno", "supported runtimes"; typical config `warlock.config.ts > devServer / build`. Skip: writing a custom CLI — the `write-cli-command` topic; config shape — the `configure-app` topic; competing tooling `nodemon`, `tsx`, `ts-node-dev`, `esbuild` direct.'
 ---
 
 # Warlock — run the app
@@ -40,14 +40,14 @@ When a flag is **not** passed, the corresponding `warlock.config.ts > devServer.
 
 Once the server is ready, `warlock dev` listens for single keypresses:
 
-| Key      | Does                                                                                                                                                                    |
-| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `r`      | Restart the server on a fresh process.                                                                                                                                  |
-| `c`      | Clear the console.                                                                                                                                                      |
-| `q`      | Graceful shutdown, exit `0` — the same path as `Ctrl+C`.                                                                                                                |
-| `h`      | Print the shortcuts that are armed right now.                                                                                                                           |
+| Key      | Does                                                                                                                                      |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `r`      | Restart the server on a fresh process.                                                                                                    |
+| `c`      | Clear the console.                                                                                                                        |
+| `q`      | Graceful shutdown, exit `0` — the same path as `Ctrl+C`.                                                                                  |
+| `h`      | Print the shortcuts that are armed right now.                                                                                             |
 | `u`      | **Only while an update notice is showing** — update every `@warlock.js/*` package, install, and restart. See the `update-packages` topic. |
-| `Ctrl+C` | Graceful shutdown, unchanged.                                                                                                                                           |
+| `Ctrl+C` | Graceful shutdown, unchanged.                                                                                                             |
 
 A "restart" is a fresh process (`r` and `u` both use it) — see [The supervisor](#the-supervisor) below for how that works.
 
@@ -123,7 +123,7 @@ preload: {
 
 HTTP + Socket connectors are **Late** phase — they boot later in the dev-server startup sequence, after app modules load. That ordering is what guarantees `app.http` / `app.socket` are live by the time your `main.ts` runs.
 
-**Runs on any Node version.** `warlock.config.ts` is loaded by transpiling it with esbuild when the runtime can't import `.ts` natively (Node < 22.18 / < 23.6) — so `build`/`start` work on older production Node without `--experimental-strip-types` or a newer Node.
+**Requires Node 22.15 or newer.** The CLI checks the runtime before loading either the published entry or the source loader and exits with a clear message on older versions. `warlock.config.ts` is transpiled with esbuild when the supported runtime cannot import `.ts` natively (Node < 22.18 / < 23.6); no `--experimental-strip-types` flag is needed.
 
 **Boot failures are fatal and loud.** Anything that throws during preload — a bad import in a `src/config/*.ts` file, a removed package export, a connector that fails to start — stops `dev`/`start` immediately with the error message and the offending file/line, then exits `1`. A common cause is upgrading `@warlock.js/*` and hitting a removed export (e.g. a config file that pulls in a model importing a symbol the new version no longer exports). If `warlock dev` ever just freezes right after the banner with no message, treat it as a bug and report it — preload errors are meant to print, never hang.
 
@@ -138,24 +138,48 @@ export default defineConfig({
       include: ["**/*.{ts,tsx}"],
       exclude: ["**/node_modules/**", "**/dist/**", "**/.warlock/**", "**/.git/**"],
     },
-    generateTypings: true,             // background type generation
-    checkForUpdates: true,             // notify on a newer @warlock.js/core at dev start
-    restartOnConfigChange: true,       // restart when warlock.config.ts / .env* changes
-    healthCheckers: [...] /* or false */,
-    transpileCacheDebug: false,        // name cache files <slug>.<hash>.js w/ // @source markers
-    timings: false,                    // print a per-phase reload timing breakdown
+    generateTypings: true, // background type generation
+    checkForUpdates: true, // notify on a newer @warlock.js/core at dev start
+    restartOnConfigChange: true, // restart when warlock.config.ts / .env* changes
+    healthCheckers: { typescript: true }, // built-in switches, custom checkers, or false
+    transpileCacheDebug: false, // name cache files <slug>.<hash>.js w/ // @source markers
+    timings: false, // print a per-phase reload timing breakdown
   },
 });
 ```
 
 - **`watch.include` / `watch.exclude`** — globs piped into the file watcher. Override when you have non-`.ts(x)` files driving reloads (e.g. SQL fixtures), or to exclude a generated folder.
 - **`generateTypings`** — turn off if you're committing generated typings and don't want them rewritten on every boot. The `--skip-typings` flag is the per-run version.
-- **`healthCheckers`** — custom file health checker contracts (or `false` to disable). The `--skip-health` flag is the per-run version.
+- **`healthCheckers`** — built-in switches (`{ typescript?, eslint?, oxlint? }`), custom file health checker contracts, or `false` to disable. The `--skip-health` flag disables all checkers for that run. TypeScript runs by default. ESLint uses core's dependency and requires only an app-root flat config; Oxlint requires its package installed in the app plus a config. Both run when configured.
 - **`transpileCacheDebug`** — diagnostic only. Names `.warlock/transpile/*.js` files `<slug>.<hash>.js` and appends `// @source <path>` markers so you can eyeball which cache entry came from which source. Leave off in normal use.
 - **`checkForUpdates`** — on `warlock dev` start, check npm for a newer `@warlock.js/core` and print a one-line notice if one exists. Best-effort and non-blocking; auto-skipped in CI and non-TTY shells. In an interactive terminal the notice arms a **`u` shortcut** that updates every `@warlock.js/*` package, installs, and restarts the server; elsewhere it prints `npx warlock update` instead. The registry answer is cached for 24h in `.warlock/update-check.json`, so a day of restarts costs one lookup. See the `update-packages` topic.
 - **`restartOnConfigChange`** — restart the dev server when `warlock.config.ts` or any `.env*` changes (default `true`). Set `false` to get a warning instead and restart by hand. Neither file can be hot-reloaded, so without a restart the running services keep the old values.
 - **`timings`** — print a one-line, per-phase breakdown next to the `hmr update` line on every hot reload: `watcher`, `debounce`, `graph`, `reimport`, `connectors`. `watcher` is the raw-fs-notification-to-stabilised-event gap (chokidar's `awaitWriteFinish` window); `debounce` is the handler's own adaptive wait; the rest are self-explanatory. Opt-in, off by default — a disabled flag costs one boolean check per reload, since the watcher-settle bookkeeping only runs when this is on. Use it to see which phase a slow reload is actually spending time in.
 
+### Optional Oxlint file checks
+
+Install `oxlint` in the app (`npm install --save-dev oxlint`) and add `.oxlintrc.json` at the app root:
+
+```json
+{
+  "rules": { "no-debugger": "error", "no-unused-vars": "warn" }
+}
+```
+
+`warlock dev` then checks changed JavaScript/TypeScript files in an isolated worker and reports rule ids, line/column spans, errors and warnings. It reads saved files from disk, honors the app's Oxlint ignore/config rules, and uses the app-resolved CLI package. A missing package or config skips the checker. Large file lists run in sequential batches of at most 500 files within platform command-line limits, using paths relative to the app; a batch whose report overflows the 8 MiB buffer is split and retried, and a single path the OS refuses as too long is reported as an unchecked warning instead of failing the scan. Tool/config errors include the CLI output and are reported without stopping the dev server. On worker shutdown CLI children get SIGTERM, then SIGKILL after 250 ms; the interrupted check is cancelled quietly ("the development server is shutting down") rather than reported as a timeout.
+
+```ts
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  devServer: {
+    healthCheckers: { typescript: true, eslint: false, oxlint: true },
+  },
+});
+```
+
+Omit the switches to run TypeScript and every installed/configured linter; `true` still requires the linter's config, and Oxlint also requires its app-installed package. Set `oxlint: false` to disable only Oxlint while leaving other defaults intact. A custom checker array replaces the built-in list. Config discovery also accepts `.oxlintrc.jsonc`, `oxlint.config.ts` and `oxlint.config.mts`; use JSON/JSONC on Node 22.15 because current Oxlint TypeScript configs need Node 22.18 or newer.
+
 ## `warlock build` — production bundle
 
 esbuild bundle of the app down to a single JS file in `dist/`. No flags — every setting comes from `warlock.config.ts > build`.
@@ -163,6 +187,8 @@ esbuild bundle of the app down to a single JS file in `dist/`. No flags — ever
 ### `build.*` config knobs
 
 ```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
 export default defineConfig({
   build: {
     outdir: "dist", // default — relative or absolute
@@ -305,10 +331,10 @@ pnpm 10+ will not run a dependency's install script unless the app names it. esb
 
 Where the approval goes depends on the pnpm version (measured with real installs):
 
-| pnpm             | Approve esbuild in                                                           |
-| ---------------- | ---------------------------------------------------------------------------- |
-| 10.26+, 11, 12   | `pnpm-workspace.yaml`: `allowBuilds:` / `  esbuild: true`                    |
-| 10.5 – 10.25     | `pnpm-workspace.yaml`: `onlyBuiltDependencies:` / `  - esbuild`              |
+| pnpm             | Approve esbuild in                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| 10.26+, 11, 12   | `pnpm-workspace.yaml`: `allowBuilds:` / `  esbuild: true`                                        |
+| 10.5 – 10.25     | `pnpm-workspace.yaml`: `onlyBuiltDependencies:` / `  - esbuild`                                  |
 | 7 – 9, 10.0–10.4 | `package.json`: `"pnpm": { "onlyBuiltDependencies": ["esbuild"] }`, and no `pnpm-workspace.yaml` |
 
 ```yaml
@@ -391,6 +417,50 @@ Three consequences worth knowing:
 
 If you need the same fact inside the app, use `Application.onceBooted()` / `Application.whenBooted()` — the signal and your listeners fire from the same latch.
 
+## Runtimes — Node, Bun, Deno
+
+| Command              | Node.js 22.15+     | Bun 1.4.3                     | Deno 2.9.7                    |
+| -------------------- | ------------------ | ----------------------------- | ----------------------------- |
+| `warlock dev`        | supported          | refused (exit 1, clear error) | refused (exit 1, clear error) |
+| `warlock build`      | supported          | runs with a notice — use Node | runs with a notice — use Node |
+| `warlock start`      | supported          | supported                     | supported                     |
+| built entry directly | `node dist/app.js` | `bun dist/app.js`             | `deno run -A dist/app.js`     |
+
+Build on Node, then start the same `dist/` (plus `node_modules` and `.env`) on any of the three:
+
+```bash
+npx warlock build                                                          # Node
+NODE_ENV=production bun dist/app.js                                        # Bun, direct
+NODE_ENV=production bun node_modules/@warlock.js/core/bin/warlock.js start # Bun, via the CLI (--role works)
+NODE_ENV=production deno run -A dist/app.js                                # Deno, direct
+NODE_ENV=production deno run -A node_modules/@warlock.js/core/bin/warlock.js start
+```
+
+- `warlock start` spawns the server with the runtime the CLI runs on (`process.execPath`), so the server runs on Bun/Deno whenever the CLI does. `bun --bun run start` works; plain `bun run start` runs the CLI on Node.
+- Deno needs no npm-compat flag — it reads `node_modules` through the app's `package.json`. `-A` is what CI verifies.
+- Pages render on Bun and Deno: both resolve `react-dom/server` to a build without `renderToPipeableStream`, so `@warlock.js/web` loads `react-dom/server.node` in that case (no change on Node).
+- The versions above are pinned in `.github/workflows/runtimes.yml`; `packages/core/tests/acceptance/run-runtime-acceptance.mjs --runtimes=node,bun,deno` repeats the CI check locally.
+
+A custom Node-only command can reuse the same guard:
+
+```ts title="src/app/tools/commands/profile.command.ts"
+import { assertNodeOnlyCommand, command, detectJavaScriptRuntime } from "@warlock.js/core";
+
+export const profileCommand = command({
+  name: "profile",
+  description: "Capture a CPU profile (uses node:inspector)",
+  preAction: () => {
+    // Prints "warlock profile runs on Node.js only — this process is Bun 1.4.3." and exits 1 on Bun/Deno.
+    assertNodeOnlyCommand("profile");
+  },
+  action: () => {
+    const runtime = detectJavaScriptRuntime(); // { type: "node", version: "22.15.0" }
+
+    console.log(`profiling on ${runtime.type} ${runtime.version}`);
+  },
+});
+```
+
 ## Picking which mode you're in
 
 `Application.environment` and `Application.runtimeStrategy` are separate axes:
@@ -424,14 +494,14 @@ Now `npm run dev` / `npm run build` / `npm run start`. Standard Node hosting pro
 ### Production Dockerfile
 
 ```dockerfile
-FROM node:20-alpine AS build
+FROM node:22.15-alpine AS build
 WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci
 COPY . .
 RUN npx warlock build
 
-FROM node:20-alpine
+FROM node:22.15-alpine
 WORKDIR /app
 COPY --from=build /app/dist ./dist
 COPY --from=build /app/node_modules ./node_modules
@@ -479,6 +549,8 @@ npx warlock dev --skip-typings
 Or persist it:
 
 ```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
 export default defineConfig({
   devServer: {
     generateTypings: false,
@@ -510,6 +582,7 @@ NODE_OPTIONS=--max-old-space-size=4096 npx warlock start
 - **`outdir` is the directory, `outFile` is the filename within it.** A common mistake is putting the full path in one and leaving the other default — you end up with `<full-path>/app.js` or `dist/<full-path>`. They concatenate.
 - **`sourcemap: false` cascades to `start`.** Stack traces lose `.ts` precision. Keep sourcemaps on unless artifact size is a hard constraint.
 - **`NODE_ENV` is not set by these commands.** The deployment env (your Dockerfile, CI, hosting provider) sets it. Forget it on a production server and `Application.isProduction` returns `false`, which flips cookie security, CORS, logging — silently. Always set `NODE_ENV=production` in production deployments.
+- **`warlock dev` is Node only.** On Bun or Deno it exits 1 before doing anything; develop on Node and run only the production build on Bun/Deno.
 - **`prestart` runs once on dev boot, not on reload.** If you're seeding test data in `src/app/prestart.ts`, it fires on `warlock dev` startup only. HMR reloads don't re-run it.
 
 ## See also
@@ -520,3 +593,14 @@ NODE_OPTIONS=--max-old-space-size=4096 npx warlock start
 - The `add-connector` topic — Early vs Late connector phases (why HTTP/socket boot late in dev).
 - The `update-packages` topic — `warlock update` + the dev-server update notice (`devServer.checkForUpdates`).
 - The `warlock-routes` topic — `warlock routes` / `warlock routes:diff`, the latter comparing live page routes against the manifest `warlock build` writes.
+
+Oxlint config failures preserve both warning and error output; structured
+diagnostics keep their specific message. Command failure messages contain a
+bounded status/output summary, without the batch command line. Shutdown gives
+workers up to 500 ms to exit and reap owned CLI children before forcing termination.
+
+Source TypeScript health workers use the framework's JavaScript/tsx bootstrap on
+Node.js 22.15; published JavaScript workers start directly. Framework regression
+tests cover that bootstrap and a built `.mjs` worker with no inherited loader
+hooks. Both paths check configured declaration roots, source updates and deleted
+declarations under the supported minimum runtime.

package/skills/send-response/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: send-response
-description: 'Send HTTP responses via @warlock.js/core''s Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `ResourceNotFoundError`, `ForbiddenError`, `request.cookie`, `request.hasCookie`, `CookieJarUnavailableError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — the `create-controller` topic; route registration — the `register-route` topic; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.'
+description: 'Send HTTP responses via @warlock.js/core''s Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `retainEvents`, `retainChunks`, `backpressure`, `@warlock.js/core/errors`, `ResourceNotFoundError`, `ForbiddenError`, `request.cookie`, `request.hasCookie`, `CookieJarUnavailableError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — the `create-controller` topic; route registration — the `register-route` topic; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.'
 ---
 
 # Warlock — send a response
@@ -69,6 +69,23 @@ return response.redirect("/login"); // 302
 return response.redirect("/new-home", 301); // permanent
 ```
 
+A target from the request (`?next=`, `returnTo`) goes through `safeRedirect()`:
+same-origin paths and allow-listed origins pass, anything else (`//evil.com`,
+`javascript:`) becomes the fallback.
+
+```ts
+import { safeRedirect, type RequestHandler } from "@warlock.js/core";
+
+export const afterLoginController: RequestHandler = async ({ request, response }) => {
+  return response.redirect(
+    safeRedirect(request.input("next"), {
+      allowedOrigins: ["https://app.example.com"],
+      fallback: "/dashboard",
+    }),
+  );
+};
+```
+
 ## Files
 
 ```ts
@@ -84,6 +101,27 @@ return response.sendBuffer(buffer, { contentType: "image/png" });
 
 `SendFileOptions` lets you set `cacheTime`, `immutable`, `inline`, `filename` (download attachment name).
 
+Conditional requests are handled for you (RFC 9110): `If-None-Match` compares weakly (`W/"a"` matches `"a"`) and answers 304 on GET/HEAD; `If-Match` compares strongly (a `W/` tag never passes) and answers 412. For your own ETags, use the same helper:
+
+```ts
+import { evaluateConditionalRequest, type RequestHandler } from "@warlock.js/core";
+
+export const showDocumentController: RequestHandler = async ({ request, response }) => {
+  const etag = `"doc-42-v7"`;
+  const outcome = evaluateConditionalRequest({
+    method: request.method,
+    etag,
+    ifMatch: request.header("if-match"),
+    ifNoneMatch: request.header("if-none-match"),
+  });
+
+  if (outcome === "not-modified") return response.setStatusCode(304).send();
+  if (outcome === "precondition-failed") return response.setStatusCode(412).send();
+
+  return response.header("ETag", etag).success({ id: 42 });
+};
+```
+
 `response.xml(string | XMLable, statusCode?)` sends `application/xml` — pass a raw XML string, or anything with a `toXML(): string` method (structural, so core never depends on `@warlock.js/sitemap`). This is for BOUNDED values only: a raw string, or a single `@warlock.js/sitemap` `Sitemap` under the sitemaps.org 50,000-URL / 50MB ceiling. `SitemapIndex` has no `toXML()` — it is the streaming path for larger URL sets and does not fit in one response body. It writes shards plus a master index as FILES via `saveTo`/`publish`, and those files are served directly rather than passed through `xml()`. In Warlock web this is the `web.sitemap` config: `enabled`, `outputDir` (default `storagePath("sitemap")`), and `path` (default `/sitemap.xml`) — the app serves the generated files from `outputDir` at that route, it never builds a `SitemapIndex` response inline.
 
 ## Streams
@@ -115,6 +153,8 @@ import {
   HttpError, // base class — `new HttpError(status, message, payload?)` for arbitrary codes
 } from "@warlock.js/core";
 
+declare const id: string;
+
 throw new ResourceNotFoundError("product.notFound");
 throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
@@ -246,18 +286,42 @@ A route can still override it — call `response.header("Content-Security-Policy
 from a controller or middleware that runs after the funnel, and your value
 wins, same as any other header.
 
+### Header values from user input
+
+`escapeHeaderValue(value)` removes CR/LF and other control characters (tabs
+stay) and replaces non-Latin-1 characters with `?`, so input can neither split
+a header nor make Node throw a 500:
+
+```ts
+import { escapeHeaderValue, type RequestHandler } from "@warlock.js/core";
+
+export const exportController: RequestHandler = async ({ request, response }) => {
+  response.header("X-Export-Name", escapeHeaderValue(request.input("name")));
+  return response.success({ ok: true });
+};
+```
+
+SSE `event`/`id` fields are already single-lined by `response.sse()`
+(`toSingleLineSseField()` is exported for custom writers).
+
 ## Common patterns
 
 ### Localized error
 
 ```ts
-import { t } from "@warlock.js/core";
+import { t, type RequestHandler } from "@warlock.js/core";
 
-if (!result) {
-  return response.unauthorized({ error: t("auth.invalidCredentials") });
-}
+declare function attemptLogin(email: string, password: string): Promise<{ token: string } | null>;
+
+export const loginController: RequestHandler = async ({ request, response }) => {
+  const result = await attemptLogin(request.input("email"), request.input("password"));
+
+  if (!result) {
+    return response.unauthorized({ error: t("auth.invalidCredentials") });
+  }
 
-return response.success(result);
+  return response.success(result);
+};
 ```
 
 ### Created with link header
@@ -273,18 +337,23 @@ return response.successCreate({ product });
 ### Streaming an LLM reply
 
 ```ts
-import { ai } from "@warlock.js/ai";
+import type { AgentContract } from "@warlock.js/ai";
+import { type RequestHandler } from "@warlock.js/core";
 
-const stream = response.stream("text/event-stream");
-const streamedAgent = await myAgent.stream(request.input("message"));
+declare const myAgent: AgentContract; // an ai.agent(...) instance
 
-for await (const event of streamedAgent.events) {
-  if (event.type === "text-delta") {
-    stream.send(`data: ${JSON.stringify({ delta: event.text })}\n\n`);
+export const chatController: RequestHandler = async ({ request, response }) => {
+  const stream = response.stream("text/event-stream");
+  const run = myAgent.stream(request.input("message"));
+
+  for await (const event of run) {
+    if (event.type === "agent.trip.streaming") {
+      stream.send(`data: ${JSON.stringify({ delta: event.delta })}\n\n`);
+    }
   }
-}
 
-stream.end();
+  stream.end();
+};
 ```
 
 (For the agent surface itself, see `@warlock.js/ai/skills/subskills/agent.md`.)
@@ -316,3 +385,99 @@ return response.header("X-Cache", "HIT").replay({
 - The `create-controller` topic — what calls `response.<helper>()` from.
 - The `register-route` topic — wiring the controller to a URL.
 - The `warlock-conventions` topic — when to use HTTP error helpers vs `throw`.
+
+## Stream wire format, headers and synchronous producers
+
+```ts
+const sse = response.sse({
+  headers: { "Cache-Control": "private, no-store" },
+  maxQueuedBytes: 1024 * 1024,
+  onOverflow: "disconnect",
+});
+sse.send(undefined, { status: "ready" }); // no event field: EventSource.onmessage
+sse.enqueue(undefined, "already serialized\nsecond line", undefined, { raw: true });
+```
+
+The positional `send(event, data, id?, options?)` and `write(...)` calls still work.
+An undefined event omits `event:`. Data is JSON by default; `{ raw: true }` requires
+string data and emits one safe `data:` line per input line. Event/id line breaks
+and NUL are removed, so raw data cannot inject event fields.
+
+Both `sse({ headers })` and `stream(contentType, { headers })` apply caller headers
+before flushing. Cache-Control keeps the safe stream default unless explicitly
+set in options.headers; a pre-existing global cache header does not override it.
+Caller protocol headers are filtered case-insensitively before applying overrides.
+Both helpers use chunked HTTP/1.1 framing, set their own content type, and preserve
+Connection: close during graceful drain. Content-Length cannot override framing.
+
+Use synchronous `enqueue()` for event-bus producers. It returns false when closed
+or overflowing. The byte cap includes queued UTF-8 data and Node's unsent buffer.
+It defaults to 1 MiB for enqueue; `onOverflow: "disconnect"` aborts the signal and
+runs disconnect cleanup, while `"drop"` rejects the newest chunk so the producer
+can schedule a resync. Every drop increments controller.dropped, including drops
+from send/write/render/comments. write() still returns false only when ended or
+disconnected; true means ready to continue, so inspect dropped when using drop
+mode. A single event exceeding the byte cap is always rejected (and disconnects
+in the default overflow mode). Choosing maxQueuedBytes also bounds send/write/render and
+SSE comments; using enqueue switches subsequent writes on that controller into
+bounded mode. `drain()` waits for both queues. `end()` stops accepting new output
+and flushes already accepted queued output before ending. Without a byte cap or
+enqueue, send/write retain their existing behavior.
+
+Graceful HTTP/1 drain tracks raw responses, including hijacked replies. Before
+headers flush it adds Connection: close; already-streaming replies finish and
+then have their idle connections reaped. A hand-written hijacked writer that sets
+its own Connection header must preserve close during drain rather than overwrite
+it with keep-alive. Headers already on the wire cannot be changed.
+
+On HTTP/2, SSE and stream helpers omit connection-specific and Transfer-Encoding
+headers. Graceful drain sends GOAWAY and closes sessions once active streams finish;
+HTTP/1.1 keeps its existing Connection: close behavior. HTTP/1.0 uses close-delimited responses without Transfer-Encoding. The shutdown timeout still
+bounds a stream that never finishes.
+
+`http.serverOptions: { http2: true }` uses session draining by default. The
+framework maps idle-connection shutdown to session tracking on HTTP/2, so Fastify
+never receives its unsupported `forceCloseConnections: "idle"` setting.
+
+## Complete backpressure examples
+
+```ts title="src/app/events/controllers/events.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+
+export const eventsController: RequestHandler = async ({ response }) => {
+  const sse = response.sse({ retainEvents: 2 });
+  try {
+    for (const count of [1, 2, 3]) {
+      if (sse.signal.aborted || !(await sse.write("tick", { count }))) break;
+    }
+    await sse.drain();
+  } finally {
+    sse.end();
+  }
+};
+
+export const exportController: RequestHandler = async ({ response }) => {
+  const stream = response.stream("text/plain", { retainChunks: 1 });
+  try {
+    for (const line of ["id,name\n", "1,Anvil\n"]) {
+      if (stream.signal.aborted || !(await stream.write(line))) break;
+    }
+    await stream.drain();
+  } finally {
+    stream.end();
+  }
+};
+```
+
+Retention keeps only the requested tail in `response.body` for inspection; it
+is not a buffer to replay the whole stream. Neither controller's `signal`
+aborts on its normal `end()`.
+
+```ts title="src/app/catalog/services/require-product.service.ts"
+import { ResourceNotFoundError } from "@warlock.js/core/errors";
+
+export function requireProduct<T>(product: T | null | undefined): T {
+  if (product == null) throw new ResourceNotFoundError("Product not found");
+  return product;
+}
+```