@nightowlsdev/runner-nextjs

`createNextjsRunner({ swarm | engine, auth, storage, background? })` returns a core `Runner` plus nine App Router route factories: `chatRoute()` (POST /api/swarm/chat → authenticate, build SwarmContext from AuthContext only, `engine.run()`, SSE), `resumeRoute()` (POST /api/swarm/resume → authenticate, authorize the typed follow-up cross-tenant, recover the run, `engine.resume()`, SSE), `eventsRoute()` (GET /api/swarm/events/[id] → hydrate `events.list` for dedup-by-seq reconnect), `historyRoute()` and `threadEventsRoute()` (GET .../history|thread-events/[id] → the message history / full SwarmEvent log for a thread, to rebuild the rich timeline on reload), `scratchpadRoute()` (GET .../scratchpad/[id] → the public scratchpad section), `activeRoute()` (GET .../active/[id] → in-flight runs for a container), `threadsRoute()` (GET .../threads), and `agentsRoute()` (GET .../agents); `handlers()` exposes all eight raw handler functions for hosts that wire their own routes. It's a pure transport adapter that projects each typed `SwarmEvent` onto a custom AI SDK v7 `data-<name>` UI Message Stream part (status as transient, question/answer/tool parts durable). Identity is server-only (forged tenant/userId in the body is ignored; runId is server-minted). `ai` (^7) is a required peer; `next` (>=15) is an optional types-only peer, handlers are plain Request→Response functions and `next` is never imported at runtime (the engine wall, no `@mastra/*` either). Durable execution is now opt-in IN this runner: pass `background: createBackgroundRunner(...)` and `chatRoute` ENQUEUES the run on it (returns `{ runId }` JSON the react client subscribes/hydrates) instead of streaming SSE, so the run outlives the request; `enqueue()` delegates to that background runner and only throws when one isn't wired.

runner-nextjs is the interactive transport for a core swarm on the Next.js App Router. createNextjsRunner({ engine, auth, storage }) returns a core Runner plus a family of route factories: the chat/resume/events/history/thread-events/scratchpad/active/threads/agents routes for a full chat client, and — behind one default-deny guard — the definition-admin, skill-store, connections/MCP, model-provider, and grant-holder studio routes. It authenticates every request server-side, `for await`s over engine.run()/engine.resume(), and projects each typed SwarmEvent onto an AI SDK v7 UI Message Stream part that @nightowlsdev/react understands. It is a pure transport adapter — it never imports @mastra/* and never imports `next` at runtime.

createNextjsRunner returns a NextjsRunner (which also implements the core Runner interface). Each route factory runs the same spine: auth.authenticate(req) first (null ⇒ 401), then the participation gate (storage.runs.resolveContainerAccess) on thread-scoped endpoints, then a SwarmContext built only from the AuthContext (body tenantId/userId ignored, runId server-minted). chatRoute() then iterates engine.run() and streamEvents serializes each SwarmEvent onto the AI SDK v7 UI Message Stream — one custom data-<suffix> part per event, with stable part ids so re-writes reconcile in place across SSE, hydrate, and Realtime. resumeRoute() validates the follow-up cross-tenant before recovering the run and calling engine.resume(). Pass `background` and chatRoute enqueues via background.enqueue() (returning { runId } JSON) instead of streaming, without changing any route path.

Two things happen after a turn ends that are not part of the turn: delta compaction (FR-071) folds a thread's settled single-token swarm.message deltas into one event per bubble, and message-search indexing (FR-072) walks the conversation's new messages into the embedding sidecar. Both are hygiene, so both ride the same lane: the runner calls an internal detach(), which swallows every error with a log and hands the promise to your waitUntil if you supplied one. Neither can fail a turn, and neither can make the user wait.

That is exactly why a serverless host MUST pass waitUntil. detach() starts the chore and does not await it, and on Vercel, Lambda or Netlify the function FREEZES the moment the response flushes — so an un-kept promise is cut short mid-flight, silently, on every single turn. No data is lost (compaction is idempotent and retried on the thread's next terminal; the indexer's repair pass rediscovers whatever a truncated call missed), but neither chore ever finishes, and nothing in the logs says so. The fix is one import: `import { after } from "next/server"` and `createNextjsRunner({ …, waitUntil: after })`.

Since FR-072 the runner diagnoses this itself. At construction, if a chore is configured (compactDeltas, or messageSearch with turn-end indexing that can actually be detached) AND waitUntil is absent AND the environment looks serverless (VERCEL, AWS_LAMBDA_FUNCTION_NAME or NETLIFY), it emits exactly ONE console.warn naming the orphaned chores and the fix. It stays silent when nothing is configured — a warning an operator cannot act on is how a channel gets ignored. The INDEXING half of that predicate is also dropped for a FULLY durable deployment (background wired WITH resumeEnqueue), because there every turn takes the enqueue branch and the indexing chore is never detached at all; a background runner WITHOUT resumeEnqueue falls through to the interactive resume and still detaches it, so it still counts. Compaction is detached on BOTH paths — enqueue of turn N+1 is a perfectly good moment to fold turn N — so a host with compactDeltas warns regardless of how durable it is. Auto-importing next/server and defaulting waitUntil to after() was declined deliberately: this package declares zero dependencies and next is an optional peer, and after() throws outside a request scope — so a runner constructed at module load, the near-universal shape, would throw at import time on precisely the deployments the warning exists for.

Both settings are PER RUNNER INSTANCE — not per process, not per deployment, and not shared with the durable path. The flag, its tuning and the sweep's entire bookkeeping live on one createNextjsRunner(...) closure, so a host that constructs two runners (a stock chat route plus a bespoke one, or one per tenant, or a separate instance used for resumes) has two independent sweepers: enabling a chore on one does NOT enable it on the other. Each sweep also starts its cursor empty, so compactDeltas' maxPasses (default 8) is a per-CALL budget, never a running total. And @nightowlsdev/runner-background's compactDeltas / messageSearch are a THIRD, separate pair of settings, covering runs with no request behind them; a host running both enables both, and the overlap is safe because the operations are idempotent.

compactDeltas is DEFAULT OFF even though it is the cheaper win, because the fold DELETES rows from events — a table some deployments treat as an audit trail, where per-token arrival timing is data. It also needs a store that carries compactContainerDeltas (storage-supabase ≥ 2.18); on any other adapter it is a silent no-op, so setting it is always safe. Message-search indexing is default ON once a plane is wired, for the mirror-image reason: it only ever inserts into its own tables and deletes nothing a host could be relying on.

messageSearch is one option carrying a host-constructed plane: { plane, indexOnTurnEnd?, allowTenantSearch? }. The plane is @nightowlsdev/storage-supabase's createMessageSearch({ pool, embedder, embedderTag, dimensions }) — a Postgres + pgvector object a chat-only adopter must never inherit — so this package takes no dependency on it and mirrors only the two methods the route calls, the same structural-injection posture as skillPlane / connectionsPlane / taskPlane.

searchRoute() mounts POST /api/swarm/search. Its contract is the executable version of the FR-072 authorization split: authenticate through the same auth context as the thread-events routes → canonicalize the container with core's containerOf → run the SAME fail-closed resolveContainerAccess every container route runs, with the caller's orgScope forwarded → only mayRead admits. A denial returns BEFORE the plane is invoked, so a same-org nonparticipant cannot even cause an embedding to be computed. The tenant and the FR-055 scope come from the auth context and are never read from the body; tenantId / orgId / orgScope keys in the request are ignored outright.

scope:"tenant" widens the search across every conversation in the org, including ones the caller does not participate in, so no participation gate can authorize it — only the host can. It is refused unless allowTenantSearch(authCtx) exists and returns exactly true; missing, false, OR THROWING all deny (a throwing authorizer is logged and treated as a denial, because an exception falling through as "allowed" would open the whole org).

The accessor NEVER throws at the mount, unlike todosRoute() / taskRoutes(). Search is a capability a client PROBES for rather than a wiring mistake, so with no plane injected POST answers a stable 404 { ok:false, reason:"absent" } — the same status and body for every caller, checked before the participation gate so participation cannot make it vary. @nightowlsdev/react's dock retires itself on that 404 and no warning fires. The other statuses are deliberately distinguishable: 200 matches · 400 a malformed body or the store's own bad-input · 401 unauthenticated · 403 denied by the gate or by tenant-search authorization · 503 the plane reported itself unavailable (wrong dimension, embedder outage, schema drift).

Indexing after a turn happens on INTERACTIVE turns only. The durable path's runEnd fires at ENQUEUE — before the run has written a single message — so indexing there would walk a container whose newest turn does not exist yet, spending a lock and a cursor advance to index nothing, every turn, forever. The durable half lives in @nightowlsdev/runner-background (messageSearch.indexOnDriveEnd), after the drive. Set indexOnTurnEnd: false to drive indexContainer from your own cron or backfill route instead. Wiring messageSearch also activates the run-end hook the chore hangs off, so a host that wires ONLY search still gets the interactive terminal it needs.