theokit 0.67.0 → 0.69.0

package/README.md

@@ -38,6 +38,27 @@ Node `>= 22.12.0`. Peers: `react`, `react-dom`, `react-router`, `zod`, and — w
 | `server/ws/chat.ts` | `ws://…/ws/chat` |
 | `server/middleware/01-cors.ts` | request middleware, in filename order |
 
+### `next` is supported on one of the two paths
+
+A middleware receives `(request, context, next)`. What `next` does depends on which runner is
+executing it, and the two differ today:
+
+| path | `next` |
+|---|---|
+| `executeWebRequest` — the Web runner | runs the rest of the chain **and the route**, so code after `await next()` observes the route's response |
+| `server/middleware/*.ts` — the file-scan runner | **refuses.** It runs BEFORE routing, so there is no downstream to await |
+
+The file-scan path throws `MiddlewareNextUnavailableError`, naming the alternative. It used to
+accept the call and continue silently, which meant the code after `await next()` never ran and
+nothing said so.
+
+**This is a real limitation, not a bug being hidden.** Closing it means either folding the
+file-scan path so the chain wraps the route, or retiring this contract for a single one; both are
+large and the choice is open — `docs/adr/0003` § *AMENDED 2026-09-21* records what each costs.
+
+Write a `server/middleware/*.ts` middleware that returns a `Response` to answer the request, or
+returns nothing to continue. Use the Web path when you need code to run after the route.
+
 ## Authoring surfaces
 
 Every surface is a fluent builder whose `.build()` is a compile error while a required link is

package/dist/{actions-virtual-module-YIWQTI6Q.js → actions-virtual-module-DH3N34I6.js}

@@ -1,12 +1,12 @@
-import "./chunk-WAYUHS54.js";
-import "./chunk-GAJOZJWD.js";
+import "./chunk-425FJKKO.js";
+import "./chunk-MOGTMGGA.js";
 import "./chunk-WSOAN4KN.js";
 import "./chunk-ENSFCKP6.js";
-import "./chunk-5AGNZXHJ.js";
+import "./chunk-SRJBH5E5.js";
+import "./chunk-3T5XLDOH.js";
 import "./chunk-P6OS7652.js";
 import "./chunk-ZDUO4IYN.js";
-import "./chunk-D4VP2QPR.js";
-import "./chunk-ENRT6DAU.js";
+import "./chunk-IDWN2OSG.js";
 import "./chunk-47FFT43U.js";
 import "./chunk-NTDN54XO.js";
 import "./chunk-PVNMLZ5G.js";
@@ -234,4 +234,4 @@ export const actions = manifest
 export {
   actionsVirtualModule
 };
-//# sourceMappingURL=actions-virtual-module-YIWQTI6Q.js.map
+//# sourceMappingURL=actions-virtual-module-DH3N34I6.js.map

package/dist/{actions-virtual-module-WCHXKH6R.js → actions-virtual-module-OMIFGXK6.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import "tsx/esm";
-import "./chunk-B4Z7KIIU.js";
-import "./chunk-UETVDZBE.js";
+import "./chunk-SJ4AW54X.js";
+import "./chunk-BINRCILF.js";
 import "./chunk-QD5X56I3.js";
 import "./chunk-WSMLSIS5.js";
-import "./chunk-5VLP3GQ2.js";
+import "./chunk-MS4A7N77.js";
 import "./chunk-C27VRUVN.js";
 import "./chunk-7UZZHCRN.js";
 import "./chunk-BCFA6LHL.js";
@@ -218,4 +218,4 @@ export const actions = manifest
 export {
   actionsVirtualModule
 };
-//# sourceMappingURL=actions-virtual-module-WCHXKH6R.js.map
+//# sourceMappingURL=actions-virtual-module-OMIFGXK6.js.map

package/dist/adapters/agent-mount.d.ts

@@ -1,9 +1,14 @@
 import { a as RouteSubject, R as RoutePolicy } from '../route-policy-BHXQDzBF.js';
 import { C as CsrfMode } from '../csrf-Dgot9qSM.js';
 export { r as resolveProvider } from '../provider-resolver-Cc9C3-Rb.js';
+import { A as AgentNode } from '../agent-scan-BZa-pagG.js';
 export { s as scanAgents } from '../agent-scan-BZa-pagG.js';
-import 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { P as PluginRunner } from '../plugin-runner-BVMOSxvb.js';
+import { L as LoadModule } from '../module-loader-DCip7NoL.js';
 import '../audit-log-BQWM5YLG.js';
+import '../plugin-types-BUVfUQ0V.js';
+import 'vite';
 
 /**
  * ADR 0001, applied to the agent surface (usetheokit/theokit#365).
@@ -132,4 +137,187 @@ interface MountAgentOptions {
  */
 declare function mountAgent(mod: unknown, request: Request, apiKey: string | ApiKeyResolver, { source, csrfMode, projectRoot, agentName, policy, resolveSubject, }?: MountAgentOptions): Promise<Response>;
 
-export { mountAgent };
+/** Dependencies the aux dispatcher needs from its caller (dev or prod). */
+interface AuxRouteDeps {
+    /** Discovered agents (from `scanAgents`). */
+    agents: readonly AgentNode[];
+    /** Load an agent module from its file path (dev: vite loader; prod: dynamic import). */
+    loadModule: (filePath: string) => Promise<unknown>;
+    /** Absolute base URL (`http(s)://host`) for the agent-card endpoint URLs. */
+    baseUrl: string;
+    /**
+     * M34 (#97) — CSRF enforcement mode for the MCP route. `POST /api/agents/<name>/mcp` drives the
+     * agent (spends LLM tokens), so a cross-origin POST MUST be rejected in `'strict'` — parity with
+     * the agent-run route (`mount-agent.ts:83-91`). Defaults to `'strict'` (safe-by-default); a caller
+     * that already gated upstream may pass `'off'`.
+     */
+    csrfMode?: CsrfMode;
+    /**
+     * M39 — lazily resolve the provider apiKey. Required only for the thread
+     * follow-up route (which drives the agent); resolved on demand so non-agent
+     * aux routes (card, approvals, stream) never need a provider key.
+     *
+     * theokit#328 — it receives the model the agent declares, so the credential matches the provider
+     * the agent asked for. It was called with no argument, before the module was even compiled, so
+     * an agent declaring `anthropic/…` was handed whichever key env priority found first.
+     */
+    resolveApiKey?: ApiKeyResolver;
+    /**
+     * Who is asking (usetheokit/theokit#365). Invoked ONLY from {@link serveMatchedAuxRoute}, and only
+     * when the matched path's agent declares a policy — so the application's `createContext` never
+     * runs for a url this dispatcher merely declines. {@link matchAgentAuxRoute} is not given it, for
+     * the same reason it is not given the request body: deciding must cost nothing.
+     */
+    resolveSubject?: AgentSubjectResolver;
+}
+/**
+ * One aux route, already decided. Carries what the match resolved so the serve half re-derives
+ * nothing: the agent node it looked up, and for MCP the module it had to open in order to answer
+ * the opt-in question at all.
+ */
+type AgentAuxRoute = {
+    readonly kind: 'card';
+    readonly agent: AgentNode;
+} | {
+    readonly kind: 'approvals';
+    readonly agent: AgentNode;
+} | {
+    readonly kind: 'run-stream';
+    readonly agent: AgentNode;
+    readonly runId: string;
+} | {
+    readonly kind: 'thread-stream';
+    readonly agent: AgentNode;
+    readonly sessionId: string;
+} | {
+    readonly kind: 'thread-message';
+    readonly agent: AgentNode;
+    readonly sessionId: string;
+} | {
+    readonly kind: 'mcp';
+    readonly agent: AgentNode;
+    readonly mod: unknown;
+};
+/**
+ * Does this dispatcher own `urlPath`? Returns the matched route, or `null` to fall through (not an
+ * aux path, wrong method, unknown agent, or an agent that did not opt into MCP).
+ *
+ * theokit#400 — this function is where the "convert only on a path you are about to answer" rule
+ * now lives, and it is enforced by the signature rather than by discipline: it is handed a method
+ * and a url and has no request to convert. Converting in order to decide is what drained the Node
+ * body stream on every path this dispatcher declined, so an ordinary `POST /api/…` file route then
+ * waited forever for an `'end'` that had already fired — no status, no timeout, no response.
+ *
+ * The one branch that does real work here is MCP, which must open the module to read its
+ * `export const mcp` opt-in. That is deliberate: a match that could still fall through would hand
+ * the caller a request it had already started a lifecycle for, and the span opened for it would
+ * either double-count or never close.
+ */
+declare function matchAgentAuxRoute(method: string, urlPath: string, deps: AuxRouteDeps): Promise<AgentAuxRoute | null>;
+/**
+ * Answer a route {@link matchAgentAuxRoute} already claimed. Always returns a `Response` — every
+ * fall-through was decided upstream, which is what lets a caller open a request span before this
+ * runs and be sure something will close it.
+ */
+declare function serveMatchedAuxRoute(route: AgentAuxRoute, request: Request, deps: AuxRouteDeps): Promise<Response>;
+
+/**
+ * Who is asking, on the Node dispatch path that serves the agent endpoints
+ * (usetheokit/theokit#365).
+ *
+ * `executeRoute` answers this with `subjectFromContext(ctx)`, where `ctx` is the run context built
+ * from the application's `server/context.ts` plus plugin decorations. The agent branches build no
+ * such context — which is why `mountAgent`'s `subject` option had nowhere to come from and every
+ * caller left it out. This builds the same context from the same two sources, so the agent surface
+ * reads identity from the seam the routes already read it from rather than from a second one.
+ *
+ * ## Why it returns a resolver instead of a subject
+ *
+ * `tryServeAgentAux` runs for EVERY url, including the ones it does not own. Resolving eagerly
+ * there would execute the application's `createContext` twice on every route request — once in the
+ * aux branch that falls through, once in the route executor. So callers get a memoized thunk and
+ * invoke it only on a path they are about to answer, which is the same discipline theokit#400
+ * imposed on `source.toRequest()` for the same dispatcher.
+ *
+ * ## What `createContext` can read here, and what it cannot (usetheokit/theokit#415)
+ *
+ * **Headers and cookies: yes. The request body: no.**
+ *
+ * This used to state the opposite as a MUST — "invoke it before converting the request to a Web
+ * `Request`" — and no caller could honour it. The laziness argued for directly above is what makes
+ * it unsatisfiable: the invocation necessarily happens INSIDE the handler, and the handler is
+ * entered after `serveThroughPluginLifecycle` has already called `source.toRequest()` at the top of
+ * its bracket. `incomingMessageToWebRequest` attaches the Node readable as the request body
+ * (`body: webStream, duplex: 'half'`), so by the time an application's `createContext` receives
+ * that `IncomingMessage`, the stream is consumed.
+ *
+ * The contract was written for an EAGER resolver and kept when the resolver became lazy. Both
+ * decisions were right on their own; the sentence joining them was not, and it pointed callers at
+ * something impossible while implying a capability that does not exist.
+ *
+ * Practically this costs little — identity is overwhelmingly a header or a cookie, and both survive
+ * the conversion untouched. What it costs an application that resolves identity from the BODY is an
+ * empty read or a wait for an `'end'` that already fired, which is why saying so plainly matters
+ * more than the frequency suggests.
+ *
+ * Restoring body access would mean resolving eagerly — running the application's `createContext`
+ * twice on every route request, which is exactly what the laziness exists to prevent — or buffering
+ * every agent request body to replay it, which is a cost paid by every caller for a case almost
+ * none has.
+ */
+
+/** What {@link createAgentSubjectResolver} needs in order to build the run context. */
+interface AgentSubjectSources {
+    req: IncomingMessage;
+    res: ServerResponse;
+    loadModule: LoadModule;
+    /** The app's `server/` directory. Absent ⇒ there is no `context.ts` to consult. */
+    serverDir: string | undefined;
+    pluginRunner: PluginRunner | undefined;
+}
+/**
+ * Build a memoized resolver for the caller's identity.
+ *
+ * Decorations are applied ON TOP of the factory's result, matching `executeRoute`: a plugin
+ * decoration wins only where `context.ts` did not set the same key.
+ *
+ * A `createContext` that throws is not swallowed — an application whose identity resolution is
+ * broken must not be treated as an anonymous caller, because that reads as a clean refusal and
+ * hides the fault. The throw reaches the branch's own error handler and becomes a 500.
+ */
+declare function createAgentSubjectResolver(sources: AgentSubjectSources): () => Promise<RouteSubject | null>;
+/**
+ * The app's `createContext`, as a host that is not Node sees it.
+ *
+ * Deliberately NOT `middleware-runner`'s `ContextFactory`, which types its argument as
+ * `IncomingMessage`/`ServerResponse`. Those are exactly right for the dev path and wrong here: on
+ * every deploy target the pair is what `createWebShim` synthesises over a Web `Request`. Widening
+ * to `unknown` says what is actually true at this boundary rather than casting a lie past the
+ * type system — the app's own `createContext` is typed by the app, and a generated fragment is the
+ * one caller that cannot promise it Node objects.
+ */
+type HostContextFactory = (args: {
+    request: unknown;
+    response: unknown;
+}) => unknown;
+/**
+ * The half that CALLS an already-resolved context factory (B-185, ADR 0014).
+ *
+ * {@link createAgentSubjectResolver} does two things: it LOCATES `context.ts` on a filesystem —
+ * `existsSync` plus `loadModule`, inside `createServerContext` — and then CALLS what it found. A
+ * deploy target with no filesystem can do the second and not the first, so the generator bakes the
+ * module as a static import (the way routes, agents and plugins already are) and hands the factory
+ * here directly.
+ *
+ * Measured before this existed: passing `serverDir: undefined` to the resolver above takes its
+ * `produced = {}` branch, never touches `req`/`res`/`loadModule`, and returns
+ * `subjectFromContext({})` — which is null for every caller. Satisfying its types would have
+ * satisfied nothing.
+ *
+ * `request`/`response` are whatever the host has. On every deploy target that is the
+ * `ShimRequest`/`ShimResponse` pair `createWebShim` synthesises over a Web `Request`, which is the
+ * same contract routes on those targets have crossed since they were baked.
+ */
+declare function createSubjectResolverFromFactory(createContext: HostContextFactory | undefined, request: unknown, response: unknown, pluginRunner?: PluginRunner): () => Promise<RouteSubject | null>;
+
+export { createAgentSubjectResolver, createSubjectResolverFromFactory, matchAgentAuxRoute, mountAgent, serveMatchedAuxRoute };

package/dist/adapters/agent-mount.js

@@ -1,8 +1,15 @@
+import {
+  createAgentSubjectResolver,
+  createSubjectResolverFromFactory,
+  matchAgentAuxRoute,
+  serveMatchedAuxRoute
+} from "../chunk-BDPD5HEO.js";
 import {
   mountAgent
-} from "../chunk-GAJOZJWD.js";
+} from "../chunk-MOGTMGGA.js";
+import "../chunk-3T5XLDOH.js";
 import "../chunk-P6OS7652.js";
-import "../chunk-ENRT6DAU.js";
+import "../chunk-IDWN2OSG.js";
 import "../chunk-PVNMLZ5G.js";
 import "../chunk-ZDCCILMP.js";
 import "../chunk-CHTAWXC2.js";
@@ -10,6 +17,10 @@ import "../chunk-AVQU5CQF.js";
 import {
   scanAgents
 } from "../chunk-KDP2HURW.js";
+import "../chunk-V6Y2SMRG.js";
+import "../chunk-ACKBVBUI.js";
+import "../chunk-IZ3TIL6K.js";
+import "../chunk-TQEE36VD.js";
 import {
   resolveProvider
 } from "../chunk-ICXXHV4V.js";
@@ -18,8 +29,12 @@ import "../chunk-SOYOYGWY.js";
 import "../chunk-ZWN3AODA.js";
 import "../chunk-XTHN6JBX.js";
 export {
+  createAgentSubjectResolver,
+  createSubjectResolverFromFactory,
+  matchAgentAuxRoute,
   mountAgent,
   resolveProvider,
-  scanAgents
+  scanAgents,
+  serveMatchedAuxRoute
 };
 //# sourceMappingURL=agent-mount.js.map

package/dist/adapters/security-headers.d.ts

@@ -57,6 +57,22 @@ export { b as buildSecurityHeaders } from '../security-headers-vris2MQq.js';
  * (`cli/commands/start/index.ts`). An app with no security block gets the same
  * baseline deployed as it gets locally.
  */
+/**
+ * The two declarations every deploy entry emits to carry the security baseline.
+ *
+ * Four adapters wrote these same two lines — `netlify`, `vercel`, `aws-lambda`, `deno-deploy` —
+ * each under a comment naming its own host's static-asset boundary. The COMMENT differs and is
+ * meant to; the declarations do not.
+ *
+ * Extracted after SonarCloud's duplication gate failed a PR at 4.0% against a 3% ceiling and named
+ * this as the largest repeated block among the changed files. The gate was measuring something
+ * real: a literal renderer and a builder call, copied four times, is four places to update when
+ * either changes.
+ *
+ * Returns the lines rather than a joined string, because every caller splices them into an array
+ * of emitted lines.
+ */
+declare function securityHeadersDeclarations(config: SecurityHeadersConfig | undefined): string[];
 declare function renderSecurityHeadersConfigLiteral(headers: SecurityHeadersConfig | undefined): string;
 /**
  * Put the headers on a response, without overruling the handler.
@@ -129,4 +145,4 @@ interface DeployedSecurityHeaderLimits {
  */
 declare function describeDeployedSecurityHeaders(limits: DeployedSecurityHeaderLimits): string;
 
-export { type DeployedSecurityHeaderLimits, describeDeployedSecurityHeaders, renderSecurityHeadersConfigLiteral, withSecurityHeaders };
+export { type DeployedSecurityHeaderLimits, describeDeployedSecurityHeaders, renderSecurityHeadersConfigLiteral, securityHeadersDeclarations, withSecurityHeaders };

package/dist/adapters/security-headers.js

@@ -7,6 +7,12 @@ import {
 import "../chunk-XTHN6JBX.js";
 
 // src/adapters/security-headers.ts
+function securityHeadersDeclarations(config) {
+  return [
+    `const SECURITY_HEADERS_CONFIG = ${renderSecurityHeadersConfigLiteral(config)}`,
+    `const SECURITY_HEADERS = buildSecurityHeaders(SECURITY_HEADERS_CONFIG, { production: true })`
+  ];
+}
 function renderSecurityHeadersConfigLiteral(headers) {
   return JSON.stringify(headers ?? {});
 }
@@ -59,6 +65,7 @@ export {
   describeDeployedSecurityHeaders,
   generateNonce,
   renderSecurityHeadersConfigLiteral,
+  securityHeadersDeclarations,
   withSecurityHeaders
 };
 //# sourceMappingURL=security-headers.js.map

package/dist/adapters/security-headers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/adapters/security-headers.ts"],"mappings":";;;;;;;;;AA8EO,SAAS,mCACd,SACQ;AACR,SAAO,KAAK,UAAU,WAAW,CAAC,CAAC;AACrC;AAyBO,SAAS,oBAAoB,UAAoB,SAA2C;AACjG,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,SAAS,QAAQ,IAAI,GAAG,EAAG,UAAS,QAAQ,IAAI,KAAK,KAAK;AAAA,EACjE;AACA,SAAO;AACT;AAgDO,SAAS,gCAAgC,QAA8C;AAC5F,QAAM,UAAU,qBAAqB,OAAO,mBAAmB,CAAC,GAAG,EAAE,YAAY,KAAK,CAAC;AACvF,QAAM,QAAQ,OAAO,KAAK,OAAO;AACjC,MAAI,MAAM,WAAW,GAAG;AACtB,WAAO,SAAS,OAAO,MAAM;AAAA,EAC/B;AAEA,QAAM,QAAQ;AAAA,IACZ,iDAA4C,OAAO,MAAM,eAAe,MAAM,KAAK,IAAI,CAAC;AAAA,EAC1F;AACA,QAAM,WAAW,MAAM,KAAK,CAAC,SAAS,KAAK,WAAW,yBAAyB,CAAC;AAChF,MAAI,YAAY,CAAC,OAAO,YAAY;AAClC,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,oBAAoB,uBAAuB;AACpD,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,oBAAoB,sBAAsB;AACnD,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}
+{"version":3,"sources":["../../src/adapters/security-headers.ts"],"mappings":";;;;;;;;;AA6FO,SAAS,4BAA4B,QAAqD;AAC/F,SAAO;AAAA,IACL,mCAAmC,mCAAmC,MAAM,CAAC;AAAA,IAC7E;AAAA,EACF;AACF;AAEO,SAAS,mCACd,SACQ;AACR,SAAO,KAAK,UAAU,WAAW,CAAC,CAAC;AACrC;AAyBO,SAAS,oBAAoB,UAAoB,SAA2C;AACjG,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,CAAC,SAAS,QAAQ,IAAI,GAAG,EAAG,UAAS,QAAQ,IAAI,KAAK,KAAK;AAAA,EACjE;AACA,SAAO;AACT;AAgDO,SAAS,gCAAgC,QAA8C;AAC5F,QAAM,UAAU,qBAAqB,OAAO,mBAAmB,CAAC,GAAG,EAAE,YAAY,KAAK,CAAC;AACvF,QAAM,QAAQ,OAAO,KAAK,OAAO;AACjC,MAAI,MAAM,WAAW,GAAG;AACtB,WAAO,SAAS,OAAO,MAAM;AAAA,EAC/B;AAEA,QAAM,QAAQ;AAAA,IACZ,iDAA4C,OAAO,MAAM,eAAe,MAAM,KAAK,IAAI,CAAC;AAAA,EAC1F;AACA,QAAM,WAAW,MAAM,KAAK,CAAC,SAAS,KAAK,WAAW,yBAAyB,CAAC;AAChF,MAAI,YAAY,CAAC,OAAO,YAAY;AAClC,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,oBAAoB,uBAAuB;AACpD,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,oBAAoB,sBAAsB;AACnD,UAAM;AAAA,MACJ;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}

package/dist/{agent-C7F5O5V4.js → agent-7RPGAKTY.js}

@@ -3,8 +3,8 @@ import "tsx/esm";
 import {
   agentCommand,
   createAgentSsrLoader
-} from "./chunk-UKMOQWUC.js";
-import "./chunk-UETVDZBE.js";
+} from "./chunk-TJPENLGQ.js";
+import "./chunk-BINRCILF.js";
 import "./chunk-5NNFO7R7.js";
 import "./chunk-Z7CJHDLS.js";
 import "./chunk-3QPVEJ7D.js";
@@ -12,4 +12,4 @@ export {
   agentCommand,
   createAgentSsrLoader
 };
-//# sourceMappingURL=agent-C7F5O5V4.js.map
+//# sourceMappingURL=agent-7RPGAKTY.js.map

package/dist/{app-typed-client-2ZEGNFJP.js → app-typed-client-C4LRUSIS.js}

@@ -1,14 +1,14 @@
 import {
   scanControllerModules
-} from "./chunk-WAYUHS54.js";
-import "./chunk-GAJOZJWD.js";
+} from "./chunk-425FJKKO.js";
+import "./chunk-MOGTMGGA.js";
 import "./chunk-WSOAN4KN.js";
 import "./chunk-ENSFCKP6.js";
-import "./chunk-5AGNZXHJ.js";
+import "./chunk-SRJBH5E5.js";
+import "./chunk-3T5XLDOH.js";
 import "./chunk-P6OS7652.js";
 import "./chunk-ZDUO4IYN.js";
-import "./chunk-D4VP2QPR.js";
-import "./chunk-ENRT6DAU.js";
+import "./chunk-IDWN2OSG.js";
 import "./chunk-47FFT43U.js";
 import "./chunk-NTDN54XO.js";
 import "./chunk-PVNMLZ5G.js";
@@ -427,4 +427,4 @@ export {
   generateClientDts,
   shouldReemitForFile
 };
-//# sourceMappingURL=app-typed-client-2ZEGNFJP.js.map
+//# sourceMappingURL=app-typed-client-C4LRUSIS.js.map

package/dist/{app-typed-client-CUM2GZ5Y.js → app-typed-client-R6OUJZEE.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import "tsx/esm";
-import "./chunk-B4Z7KIIU.js";
-import "./chunk-UETVDZBE.js";
+import "./chunk-SJ4AW54X.js";
+import "./chunk-BINRCILF.js";
 import {
   scanControllerModules
 } from "./chunk-QD5X56I3.js";
 import "./chunk-WSMLSIS5.js";
-import "./chunk-5VLP3GQ2.js";
+import "./chunk-MS4A7N77.js";
 import "./chunk-C27VRUVN.js";
 import "./chunk-7UZZHCRN.js";
 import {
@@ -411,4 +411,4 @@ export {
   generateClientDts,
   shouldReemitForFile
 };
-//# sourceMappingURL=app-typed-client-CUM2GZ5Y.js.map
+//# sourceMappingURL=app-typed-client-R6OUJZEE.js.map

package/dist/assets-map-BMQASQHW.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import "tsx/esm";
+
+// src/vite-plugin/assets-map.ts
+var PAGE_FILE = /[/\\]page\.(tsx|ts|jsx|js)$/;
+function routePathForPageFile(appDir, moduleId) {
+  const normalised = moduleId.replace(/\\/g, "/");
+  const root = appDir.replace(/\\/g, "/").replace(/\/$/, "");
+  if (!normalised.startsWith(`${root}/`)) return void 0;
+  if (!PAGE_FILE.test(normalised)) return void 0;
+  const relative = normalised.slice(root.length).replace(PAGE_FILE, "");
+  return relative === "" ? "/" : relative;
+}
+function staticClosure(bundle, start) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [start];
+  while (queue.length > 0) {
+    const name = queue.pop();
+    if (name === void 0 || seen.has(name)) continue;
+    seen.add(name);
+    for (const next of bundle[name]?.imports ?? []) queue.push(next);
+  }
+  return seen;
+}
+function buildAssetsMap(bundle, appDir) {
+  const chunks = Object.entries(bundle).filter(
+    (entry) => entry[1]?.type === "chunk"
+  );
+  const alreadyLoaded = /* @__PURE__ */ new Set();
+  for (const [name, chunk] of chunks) {
+    if (chunk.isEntry === true) {
+      for (const reachable of staticClosure(bundle, name)) alreadyLoaded.add(reachable);
+    }
+  }
+  const map = {};
+  for (const [name, chunk] of chunks) {
+    const moduleId = chunk.facadeModuleId;
+    if (moduleId === void 0 || moduleId === null) continue;
+    const route = routePathForPageFile(appDir, moduleId);
+    if (route === void 0) continue;
+    map[route] = [...staticClosure(bundle, name)].filter((f) => !alreadyLoaded.has(f)).sort((a, b) => a.localeCompare(b));
+  }
+  return map;
+}
+function assetsMapPlugin(opts) {
+  let isSsrPass = false;
+  return {
+    name: "theokit:assets-map",
+    apply: "build",
+    configResolved(config) {
+      isSsrPass = Boolean(config.build.ssr);
+    },
+    generateBundle(_options, bundle) {
+      if (isSsrPass) return;
+      const map = buildAssetsMap(bundle, opts.appDir);
+      this.emitFile({
+        type: "asset",
+        fileName: "assets-map.json",
+        source: `${JSON.stringify(map, null, 2)}
+`
+      });
+    }
+  };
+}
+export {
+  assetsMapPlugin,
+  buildAssetsMap,
+  routePathForPageFile
+};
+//# sourceMappingURL=assets-map-BMQASQHW.js.map

package/dist/assets-map-BMQASQHW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite-plugin/assets-map.ts"],"sourcesContent":["/**\n * Emits `assets-map.json` — the route-to-chunks relation a document needs in order to preload\n * what the current route will import, instead of discovering it one round trip later.\n *\n * Chunk names exist only AFTER bundling, which is why this is a `generateBundle` hook and not a\n * post-build script reading `.vite/manifest.json`: Rollup hands the bundle in as an argument, and\n * the pre-bundle manifests must keep emitting before Vite so a failing build still leaves\n * diagnostics (B-035 ADR-1).\n *\n * `apply: 'build'` is not decoration. The plugin set this joins is shared by `theokit build`,\n * `theo dev` and `theo agent`; removing the plugin from the two serve chains is stronger than\n * relying on the hook never being reached there. The repository already uses the mirror of this in\n * `services-typed-client.ts` (`apply: 'serve'`, \"dev-only; never runs in build\").\n *\n * The SSR pass is skipped by reading the RESOLVED `build.ssr`, never a factory option: the adapter\n * calls the plugin factory twice (`adapters/node.ts:57` client, `:71` ssr) and passes `ssr: true`\n * to BOTH when the project enables SSR, so the option in the signature cannot tell the passes\n * apart. Emitting on the server pass would produce a second, unread `assets-map.json` under\n * `.theokit/server/` — harmless, because `this.emitFile` can only write inside its own build's\n * `outDir`, and deliberately avoided anyway so no future reader picks the wrong one.\n */\nimport type { Plugin } from 'vite'\n\n/** A route path mapped to the chunk file names it needs beyond what the entry already loads. */\nexport type AssetsMap = Record<string, string[]>\n\n/** Rollup's `generateBundle` bundle value, narrowed to the fields this hook reads. */\n/**\n * Exported so a fixture can be typed as one. A test that builds a chunk shape by hand and cannot\n * name the type is a test the compiler checks against `Record<string, unknown>` — which is what\n * silently erased every `fileName` a fixture passed until the root `tsc` reported it.\n */\nexport interface BundleChunk {\n  type: string\n  isEntry?: boolean\n  fileName: string\n  facadeModuleId?: string | null\n  imports?: string[]\n  /**\n   * Declared and deliberately NOT walked. A dynamic import is by definition what the browser fetches\n   * later; preloading it would defeat the split that made it dynamic.\n   *\n   * Naming it here is what makes the test asserting that meaningful. The field was absent from this\n   * type while a fixture passed it, so the case named \"does not follow dynamic imports\" passed\n   * because the walker ignores unknown keys — proving the behaviour by accident rather than by\n   * design. The root `tsc` reported it once the fixture helper stopped erasing its overrides.\n   */\n  dynamicImports?: string[]\n}\n\n/**\n * A bundle as this hook reads it. The value is `| undefined` ON PURPOSE: an `imports` entry may\n * name something the bundle does not contain (an external), and a lookup that cannot miss would\n * make the optional chain in `staticClosure` look redundant to a type-based lint while removing\n * it would crash at runtime. The type is widened to match reality rather than the guard narrowed\n * to match the type.\n */\ntype BundleLike = Record<string, BundleChunk | undefined>\n\nconst PAGE_FILE = /[/\\\\]page\\.(tsx|ts|jsx|js)$/\n\n/**\n * Derive the route path a page file serves. `<appDir>/about/page.tsx` -> `/about`;\n * `<appDir>/page.tsx` -> `/`. Returns undefined when the file is not a page under `appDir`.\n */\nexport function routePathForPageFile(appDir: string, moduleId: string): string | undefined {\n  const normalised = moduleId.replace(/\\\\/g, '/')\n  const root = appDir.replace(/\\\\/g, '/').replace(/\\/$/, '')\n  if (!normalised.startsWith(`${root}/`)) return undefined\n  if (!PAGE_FILE.test(normalised)) return undefined\n  const relative = normalised.slice(root.length).replace(PAGE_FILE, '')\n  return relative === '' ? '/' : relative\n}\n\n/**\n * Every chunk reachable from `start` through STATIC imports, `start` included. Dynamic imports are\n * deliberately excluded: they are what the browser fetches later, by definition, and preloading\n * them would defeat the split that produced them.\n */\nfunction staticClosure(bundle: BundleLike, start: string): Set<string> {\n  const seen = new Set<string>()\n  const queue = [start]\n  while (queue.length > 0) {\n    const name = queue.pop()\n    if (name === undefined || seen.has(name)) continue\n    seen.add(name)\n    for (const next of bundle[name]?.imports ?? []) queue.push(next)\n  }\n  return seen\n}\n\n/**\n * Compute the map from a Rollup bundle. Exported for unit testing without running a build —\n * the hook below is a thin wrapper so this function carries the behaviour.\n */\nexport function buildAssetsMap(bundle: BundleLike, appDir: string): AssetsMap {\n  const chunks = Object.entries(bundle).filter(\n    (entry): entry is [string, BundleChunk] => entry[1]?.type === 'chunk',\n  )\n\n  // What the document already loads. A route needing only these needs no preload at all, which is\n  // the case an over-eager implementation gets wrong and the empty array records honestly.\n  const alreadyLoaded = new Set<string>()\n  for (const [name, chunk] of chunks) {\n    if (chunk.isEntry === true) {\n      for (const reachable of staticClosure(bundle, name)) alreadyLoaded.add(reachable)\n    }\n  }\n\n  const map: AssetsMap = {}\n  for (const [name, chunk] of chunks) {\n    const moduleId = chunk.facadeModuleId\n    if (moduleId === undefined || moduleId === null) continue\n    const route = routePathForPageFile(appDir, moduleId)\n    if (route === undefined) continue\n    map[route] = [...staticClosure(bundle, name)]\n      .filter((f) => !alreadyLoaded.has(f))\n      .sort((a, b) => a.localeCompare(b))\n  }\n  return map\n}\n\n/** The plugin. See the module docblock for why `apply` and the SSR skip are what they are. */\nexport function assetsMapPlugin(opts: { appDir: string }): Plugin {\n  let isSsrPass = false\n  return {\n    name: 'theokit:assets-map',\n    apply: 'build',\n    configResolved(config) {\n      // The RESOLVED flag, per build pass — not the factory option, which is `true` in both.\n      isSsrPass = Boolean(config.build.ssr)\n    },\n    generateBundle(_options, bundle) {\n      if (isSsrPass) return\n      const map = buildAssetsMap(bundle, opts.appDir)\n      this.emitFile({\n        type: 'asset',\n        fileName: 'assets-map.json',\n        source: `${JSON.stringify(map, null, 2)}\\n`,\n      })\n    },\n  }\n}\n"],"mappings":";;;;AA2DA,IAAM,YAAY;AAMX,SAAS,qBAAqB,QAAgB,UAAsC;AACzF,QAAM,aAAa,SAAS,QAAQ,OAAO,GAAG;AAC9C,QAAM,OAAO,OAAO,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AACzD,MAAI,CAAC,WAAW,WAAW,GAAG,IAAI,GAAG,EAAG,QAAO;AAC/C,MAAI,CAAC,UAAU,KAAK,UAAU,EAAG,QAAO;AACxC,QAAM,WAAW,WAAW,MAAM,KAAK,MAAM,EAAE,QAAQ,WAAW,EAAE;AACpE,SAAO,aAAa,KAAK,MAAM;AACjC;AAOA,SAAS,cAAc,QAAoB,OAA4B;AACrE,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,QAAQ,CAAC,KAAK;AACpB,SAAO,MAAM,SAAS,GAAG;AACvB,UAAM,OAAO,MAAM,IAAI;AACvB,QAAI,SAAS,UAAa,KAAK,IAAI,IAAI,EAAG;AAC1C,SAAK,IAAI,IAAI;AACb,eAAW,QAAQ,OAAO,IAAI,GAAG,WAAW,CAAC,EAAG,OAAM,KAAK,IAAI;AAAA,EACjE;AACA,SAAO;AACT;AAMO,SAAS,eAAe,QAAoB,QAA2B;AAC5E,QAAM,SAAS,OAAO,QAAQ,MAAM,EAAE;AAAA,IACpC,CAAC,UAA0C,MAAM,CAAC,GAAG,SAAS;AAAA,EAChE;AAIA,QAAM,gBAAgB,oBAAI,IAAY;AACtC,aAAW,CAAC,MAAM,KAAK,KAAK,QAAQ;AAClC,QAAI,MAAM,YAAY,MAAM;AAC1B,iBAAW,aAAa,cAAc,QAAQ,IAAI,EAAG,eAAc,IAAI,SAAS;AAAA,IAClF;AAAA,EACF;AAEA,QAAM,MAAiB,CAAC;AACxB,aAAW,CAAC,MAAM,KAAK,KAAK,QAAQ;AAClC,UAAM,WAAW,MAAM;AACvB,QAAI,aAAa,UAAa,aAAa,KAAM;AACjD,UAAM,QAAQ,qBAAqB,QAAQ,QAAQ;AACnD,QAAI,UAAU,OAAW;AACzB,QAAI,KAAK,IAAI,CAAC,GAAG,cAAc,QAAQ,IAAI,CAAC,EACzC,OAAO,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,CAAC,EACnC,KAAK,CAAC,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC;AAAA,EACtC;AACA,SAAO;AACT;AAGO,SAAS,gBAAgB,MAAkC;AAChE,MAAI,YAAY;AAChB,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,eAAe,QAAQ;AAErB,kBAAY,QAAQ,OAAO,MAAM,GAAG;AAAA,IACtC;AAAA,IACA,eAAe,UAAU,QAAQ;AAC/B,UAAI,UAAW;AACf,YAAM,MAAM,eAAe,QAAQ,KAAK,MAAM;AAC9C,WAAK,SAAS;AAAA,QACZ,MAAM;AAAA,QACN,UAAU;AAAA,QACV,QAAQ,GAAG,KAAK,UAAU,KAAK,MAAM,CAAC,CAAC;AAAA;AAAA,MACzC,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}

package/dist/assets-map-CV2YZ3MY.js

@@ -0,0 +1,69 @@
+import "./chunk-XTHN6JBX.js";
+
+// src/vite-plugin/assets-map.ts
+var PAGE_FILE = /[/\\]page\.(tsx|ts|jsx|js)$/;
+function routePathForPageFile(appDir, moduleId) {
+  const normalised = moduleId.replace(/\\/g, "/");
+  const root = appDir.replace(/\\/g, "/").replace(/\/$/, "");
+  if (!normalised.startsWith(`${root}/`)) return void 0;
+  if (!PAGE_FILE.test(normalised)) return void 0;
+  const relative = normalised.slice(root.length).replace(PAGE_FILE, "");
+  return relative === "" ? "/" : relative;
+}
+function staticClosure(bundle, start) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [start];
+  while (queue.length > 0) {
+    const name = queue.pop();
+    if (name === void 0 || seen.has(name)) continue;
+    seen.add(name);
+    for (const next of bundle[name]?.imports ?? []) queue.push(next);
+  }
+  return seen;
+}
+function buildAssetsMap(bundle, appDir) {
+  const chunks = Object.entries(bundle).filter(
+    (entry) => entry[1]?.type === "chunk"
+  );
+  const alreadyLoaded = /* @__PURE__ */ new Set();
+  for (const [name, chunk] of chunks) {
+    if (chunk.isEntry === true) {
+      for (const reachable of staticClosure(bundle, name)) alreadyLoaded.add(reachable);
+    }
+  }
+  const map = {};
+  for (const [name, chunk] of chunks) {
+    const moduleId = chunk.facadeModuleId;
+    if (moduleId === void 0 || moduleId === null) continue;
+    const route = routePathForPageFile(appDir, moduleId);
+    if (route === void 0) continue;
+    map[route] = [...staticClosure(bundle, name)].filter((f) => !alreadyLoaded.has(f)).sort((a, b) => a.localeCompare(b));
+  }
+  return map;
+}
+function assetsMapPlugin(opts) {
+  let isSsrPass = false;
+  return {
+    name: "theokit:assets-map",
+    apply: "build",
+    configResolved(config) {
+      isSsrPass = Boolean(config.build.ssr);
+    },
+    generateBundle(_options, bundle) {
+      if (isSsrPass) return;
+      const map = buildAssetsMap(bundle, opts.appDir);
+      this.emitFile({
+        type: "asset",
+        fileName: "assets-map.json",
+        source: `${JSON.stringify(map, null, 2)}
+`
+      });
+    }
+  };
+}
+export {
+  assetsMapPlugin,
+  buildAssetsMap,
+  routePathForPageFile
+};
+//# sourceMappingURL=assets-map-CV2YZ3MY.js.map

package/dist/assets-map-CV2YZ3MY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite-plugin/assets-map.ts"],"mappings":";;;AA2DA,IAAM,YAAY;AAMX,SAAS,qBAAqB,QAAgB,UAAsC;AACzF,QAAM,aAAa,SAAS,QAAQ,OAAO,GAAG;AAC9C,QAAM,OAAO,OAAO,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AACzD,MAAI,CAAC,WAAW,WAAW,GAAG,IAAI,GAAG,EAAG,QAAO;AAC/C,MAAI,CAAC,UAAU,KAAK,UAAU,EAAG,QAAO;AACxC,QAAM,WAAW,WAAW,MAAM,KAAK,MAAM,EAAE,QAAQ,WAAW,EAAE;AACpE,SAAO,aAAa,KAAK,MAAM;AACjC;AAOA,SAAS,cAAc,QAAoB,OAA4B;AACrE,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,QAAQ,CAAC,KAAK;AACpB,SAAO,MAAM,SAAS,GAAG;AACvB,UAAM,OAAO,MAAM,IAAI;AACvB,QAAI,SAAS,UAAa,KAAK,IAAI,IAAI,EAAG;AAC1C,SAAK,IAAI,IAAI;AACb,eAAW,QAAQ,OAAO,IAAI,GAAG,WAAW,CAAC,EAAG,OAAM,KAAK,IAAI;AAAA,EACjE;AACA,SAAO;AACT;AAMO,SAAS,eAAe,QAAoB,QAA2B;AAC5E,QAAM,SAAS,OAAO,QAAQ,MAAM,EAAE;AAAA,IACpC,CAAC,UAA0C,MAAM,CAAC,GAAG,SAAS;AAAA,EAChE;AAIA,QAAM,gBAAgB,oBAAI,IAAY;AACtC,aAAW,CAAC,MAAM,KAAK,KAAK,QAAQ;AAClC,QAAI,MAAM,YAAY,MAAM;AAC1B,iBAAW,aAAa,cAAc,QAAQ,IAAI,EAAG,eAAc,IAAI,SAAS;AAAA,IAClF;AAAA,EACF;AAEA,QAAM,MAAiB,CAAC;AACxB,aAAW,CAAC,MAAM,KAAK,KAAK,QAAQ;AAClC,UAAM,WAAW,MAAM;AACvB,QAAI,aAAa,UAAa,aAAa,KAAM;AACjD,UAAM,QAAQ,qBAAqB,QAAQ,QAAQ;AACnD,QAAI,UAAU,OAAW;AACzB,QAAI,KAAK,IAAI,CAAC,GAAG,cAAc,QAAQ,IAAI,CAAC,EACzC,OAAO,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,CAAC,EACnC,KAAK,CAAC,GAAG,MAAM,EAAE,cAAc,CAAC,CAAC;AAAA,EACtC;AACA,SAAO;AACT;AAGO,SAAS,gBAAgB,MAAkC;AAChE,MAAI,YAAY;AAChB,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,IACP,eAAe,QAAQ;AAErB,kBAAY,QAAQ,OAAO,MAAM,GAAG;AAAA,IACtC;AAAA,IACA,eAAe,UAAU,QAAQ;AAC/B,UAAI,UAAW;AACf,YAAM,MAAM,eAAe,QAAQ,KAAK,MAAM;AAC9C,WAAK,SAAS;AAAA,QACZ,MAAM;AAAA,QACN,UAAU;AAAA,QACV,QAAQ,GAAG,KAAK,UAAU,KAAK,MAAM,CAAC,CAAC;AAAA;AAAA,MACzC,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}