@silkweave/nestjs 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silkweave/nestjs",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Silkweave NestJS Adapter",
   "repository": {
     "type": "git",
@@ -16,19 +16,25 @@
   "dependencies": {
     "@trpc/server": "^11.7.1",
     "change-case": "^5.4.4",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
     "zod": "^3.25.0",
-    "@silkweave/auth": "1.9.0",
-    "@silkweave/logger": "1.9.0",
-    "@silkweave/core": "1.9.0",
-    "@silkweave/trpc": "1.9.0",
-    "@silkweave/mcp": "1.9.0"
+    "@silkweave/auth": "1.10.0",
+    "@silkweave/core": "1.10.0",
+    "@silkweave/trpc": "1.10.0",
+    "@silkweave/mcp": "1.10.0",
+    "@silkweave/logger": "1.10.0",
+    "@silkweave/typegen": "1.10.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
     "@types/node": "^22.0.0",
+    "eslint": "^10.4.0",
     "reflect-metadata": "^0.2.2",
     "rimraf": "^6.1.3",
     "rxjs": "^7.8.1",

package/src/adapter/mcp.ts

@@ -1,55 +1,102 @@
-import type { HttpAdapterHost } from '@nestjs/core'
 import { AuthConfig } from '@silkweave/auth'
-import type { Adapter, AdapterGenerator } from '@silkweave/core'
-import { createMcpExpressHandler, type CreateMcpExpressHandlerOptions } from '@silkweave/mcp'
-import { reserveSlot, type NodeMiddleware } from '../lib/slot.js'
-import type { NestSilkweaveAdapter } from '../lib/types.js'
+import {
+  authMiddleware,
+  mcpCors,
+  mcpTransport,
+  oauthRoutes,
+  protectedResourceMetadata,
+  sideloadResource
+} from '@silkweave/mcp'
+import { type CorsOptions } from 'cors'
+import express, { type RequestHandler } from 'express'
+import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
 
-export interface McpAdapterOptions extends Omit<CreateMcpExpressHandlerOptions, 'auth'> {
-  /** URL prefix at which the MCP sub-app is mounted. Default `'/'` — the MCP transport then lives at `/mcp`, OAuth routes at `/authorize`, etc. */
+export interface McpAdapterOptions {
+  /** URL prefix the MCP namespace lives under - the transport itself is at this exact path. Default `'/mcp'`. */
   basePath?: string
-  /** Optional bearer-token / OAuth auth applied to MCP requests. Same shape as `@silkweave/mcp`'s `http()` auth. */
+  /** Optional bearer-token / OAuth 2.1 config. */
   auth?: AuthConfig
+  /** CORS configuration. `false` to disable, `true`/omitted for permissive defaults, or a `CorsOptions` object. */
+  cors?: CorsOptions | boolean
+  /** Mount the sideload resource route at `${basePath}/resource/:id`. Default `true`. */
+  sideloadResources?: boolean
+  /** Directory the sideload route reads from. Default `'resources'`. */
+  resourceDir?: string
+}
+
+function compose(...handlers: RequestHandler[]): RequestHandler {
+  return (req, res, next) => {
+    let i = 0
+    const dispatch: () => void = () => {
+      const h = handlers[i++]
+      if (!h) { return next() }
+      h(req, res, (err) => err ? next(err) : dispatch())
+    }
+    dispatch()
+  }
 }
 
 /**
- * MCP Streamable HTTP adapter for `@silkweave/nestjs`. Builds the same Express
- * sub-app that `@silkweave/mcp`'s `http()` adapter uses internally (via
- * `createMcpExpressHandler`) and mounts it on Nest's running HTTP server at
- * the configured base path.
+ * MCP adapter for `@silkweave/nestjs`. Registers the MCP Streamable HTTP
+ * transport, sideload, well-known and OAuth routes individually on Nest's
+ * HTTP adapter at the configured `basePath` (default `/mcp`):
  *
- * Routes provided by the mounted sub-app:
- * - `POST /mcp`, `GET /mcp`, `DELETE /mcp` — MCP Streamable HTTP transport
- * - `GET /resource/:id` — sideload resources (large MCP responses)
- * - `GET /.well-known/oauth-protected-resource` (when `auth.resourceUrl`/`auth.authorizationServers` set)
- * - `GET /authorize`, `POST /token`, `POST /register`, `GET /auth/callback` (when `auth.provider` set)
+ * - `POST/GET/DELETE ${basePath}` - Streamable HTTP transport
+ * - `GET ${basePath}/resource/:id` - sideload (`sideloadResources` opt-out)
+ * - `GET ${basePath}/.well-known/oauth-protected-resource` - RFC 9728 metadata (when `auth.resourceUrl`/`auth.authorizationServers` set)
+ * - `GET ${basePath}/authorize`, `POST ${basePath}/token`, `POST ${basePath}/register`, `GET ${basePath}${callbackPath}` (when `auth.provider` set)
  *
- * Note: this adapter mounts an Express sub-app. On `@nestjs/platform-fastify`,
- * register `@fastify/express` before this adapter so Nest can serve Express
- * middleware.
+ * Each route is a real Nest-level route - they show up in
+ * `RoutesResolver`'s log and there is no sub-app or middleware-slot
+ * indirection.
  */
 export function mcp(options: McpAdapterOptions = {}): NestSilkweaveAdapter {
   return {
     name: 'mcp',
-    install: (host: HttpAdapterHost): AdapterGenerator => {
-      const httpAdapter = host.httpAdapter
-      if (!httpAdapter) {
-        throw new Error('@silkweave/nestjs mcp(): HttpAdapterHost.httpAdapter is not available.')
+    register({ httpAdapter, silkweaveOptions, baseContext, actions }: NestAdapterRegisterContext): void {
+      const basePath = (options.basePath ?? '/mcp').replace(/\/$/, '')
+      if (!basePath) { throw new Error('@silkweave/nestjs mcp(): basePath cannot be empty or "/" - pick a path like "/mcp".') }
+
+      const adapter = httpAdapter as unknown as {
+        get: (path: string, ...h: RequestHandler[]) => unknown
+        post: (path: string, ...h: RequestHandler[]) => unknown
+        delete: (path: string, ...h: RequestHandler[]) => unknown
+      }
+
+      const corsHandler = mcpCors(options.cors ?? true)
+      const auth = options.auth
+      const guard = auth ? authMiddleware(auth, baseContext) : null
+      const prefix = (...handlers: (RequestHandler | null)[]): RequestHandler[] =>
+        handlers.filter((h): h is RequestHandler => Boolean(h))
+
+      // Public auth-discovery / OAuth routes - registered first so they're
+      // never inadvertently guarded by the auth middleware.
+      if (auth?.authorizationServers?.length && auth.resourceUrl) {
+        adapter.get(
+          `${basePath}/.well-known/oauth-protected-resource`,
+          ...prefix(corsHandler, protectedResourceMetadata(auth))
+        )
+      }
+      if (auth?.provider) {
+        const oauth = oauthRoutes(auth)
+        adapter.get(`${basePath}/.well-known/oauth-authorization-server`, ...prefix(corsHandler, oauth.wellKnownAuthServer))
+        adapter.get(`${basePath}/authorize`, ...prefix(corsHandler, oauth.authorize))
+        adapter.get(`${basePath}${oauth.callbackPath}`, ...prefix(corsHandler, oauth.callback))
+        adapter.post(`${basePath}/token`, ...prefix(corsHandler, ...oauth.token))
+        adapter.post(`${basePath}/register`, ...prefix(corsHandler, ...oauth.register))
       }
-      const { basePath = '/', auth, ...handlerOptions } = options
-      const mountPath = basePath === '/' ? '/' : basePath.replace(/\/$/, '')
-      const setHandler = reserveSlot(httpAdapter as unknown as { use: (path: string, h: NodeMiddleware) => unknown }, mountPath, 'MCP')
-      return (silkweaveOptions, baseContext): Adapter => {
-        const context = baseContext.fork({ adapter: 'mcp' })
-        return {
-          context,
-          start: async (actions) => {
-            const app = createMcpExpressHandler(silkweaveOptions, context, actions, { ...handlerOptions, auth })
-            setHandler(app as unknown as NodeMiddleware)
-          },
-          stop: async () => { /* Nest owns the HTTP server */ }
-        }
+
+      // Protected routes - wrapped with auth middleware (when configured).
+      const protect = guard ? (h: RequestHandler) => compose(guard, h) : (h: RequestHandler) => h
+
+      if (options.sideloadResources !== false) {
+        adapter.get(`${basePath}/resource/:id`, ...prefix(corsHandler, protect(sideloadResource({ resourceDir: options.resourceDir }))))
       }
+
+      const transport = mcpTransport(silkweaveOptions, baseContext, actions)
+      adapter.post(basePath, ...prefix(corsHandler, express.json(), protect(transport.post)))
+      adapter.get(basePath, ...prefix(corsHandler, protect(transport.stream)))
+      adapter.delete(basePath, ...prefix(corsHandler, protect(transport.stream)))
     }
   }
 }

package/src/adapter/rest.ts

@@ -1,12 +1,11 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
 import { HttpException } from '@nestjs/common'
-import type { HttpAdapterHost } from '@nestjs/core'
 import { AuthConfig, AuthInfo, validateToken } from '@silkweave/auth'
-import { type Action, type Adapter, type AdapterGenerator, type SilkweaveContext, SilkweaveError } from '@silkweave/core'
+import { type Action, type SilkweaveContext, SilkweaveError } from '@silkweave/core'
 import { buildLogLevels, type Logger, type LogLevel } from '@silkweave/logger'
 import type { IncomingMessage, ServerResponse } from 'http'
 import { z } from 'zod/v4'
-import { reserveSlot, type NodeMiddleware } from '../lib/slot.js'
-import type { NestSilkweaveAdapter } from '../lib/types.js'
+import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
 
 const CONSOLE_LEVEL_MAP: Record<LogLevel, 'log' | 'info' | 'warn' | 'error'> = {
   emergency: 'error',
@@ -20,21 +19,12 @@ const CONSOLE_LEVEL_MAP: Record<LogLevel, 'log' | 'info' | 'warn' | 'error'> = {
 }
 
 export interface RestAdapterOptions {
-  /** URL prefix at which the REST routes are mounted. e.g. `'/api'` → `POST /api/users/list`. Default: `'/'`. */
+  /** URL prefix joined to each action's path. e.g. `'/api'` → `POST /api/users/list`. Default: `'/api'`. */
   basePath?: string
   /** Optional bearer-token auth applied to every REST action. */
   auth?: AuthConfig
 }
 
-function createRestLogger(): Logger {
-  return {
-    ...buildLogLevels((level, data) => {
-      console[CONSOLE_LEVEL_MAP[level]](data)
-    }),
-    progress: () => { /* progress notifications not supported on REST */ }
-  }
-}
-
 interface RequestLike {
   headers: Record<string, string | string[] | undefined>
   body?: unknown
@@ -43,6 +33,13 @@ interface RequestLike {
   method?: string
 }
 
+function createRestLogger(): Logger {
+  return {
+    ...buildLogLevels((level, data) => { console[CONSOLE_LEVEL_MAP[level]](data) }),
+    progress: () => { /* progress notifications not supported on REST */ }
+  }
+}
+
 function actionNameToPath(name: string): string {
   return `/${name.replace(/\./g, '/')}`
 }
@@ -53,7 +50,11 @@ async function readJsonBody(req: IncomingMessage): Promise<unknown> {
     req.on('data', (c: Buffer) => chunks.push(c))
     req.on('end', () => {
       if (chunks.length === 0) { return resolve({}) }
-      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf-8'))) } catch (err) { reject(err) }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf-8')))
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error('Unable to parse JSON body'))
+      }
     })
     req.on('error', reject)
   })
@@ -95,22 +96,13 @@ function handleRestError(err: unknown, res: ServerResponse): void {
   sendJson(res, { error: 'internal', message: 'Internal error' }, 500)
 }
 
-function buildHandler(actions: Action[], context: SilkweaveContext, auth: AuthConfig | undefined): NodeMiddleware {
-  const routes = new Map<string, Action>()
-  for (const action of actions) {
-    const method = action.kind === 'query' ? 'GET' : 'POST'
-    routes.set(`${method} ${actionNameToPath(action.name)}`, action)
-  }
-  const logger = createRestLogger()
-  return async (req, res, next) => {
-    const pathOnly = (req.url ?? '/').split('?')[0]
-    const key = `${req.method ?? ''} ${pathOnly}`
-    const action = routes.get(key)
-    if (!action) {
-      if (next) { return next() }
-      sendJson(res, { error: 'not_found', message: `No route for ${req.method} ${pathOnly}` }, 404)
-      return
-    }
+function createActionHandler(
+  action: Action,
+  context: SilkweaveContext,
+  auth: AuthConfig | undefined,
+  logger: Logger
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  return async (req, res) => {
     try {
       const reqLike = req as unknown as RequestLike
       let authInfo: AuthInfo | undefined
@@ -118,9 +110,7 @@ function buildHandler(actions: Action[], context: SilkweaveContext, auth: AuthCo
         const authHeader = typeof reqLike.headers.authorization === 'string' ? reqLike.headers.authorization : undefined
         const result = await validateToken(authHeader, auth, context.fork({ request: req }))
         if (result.error) {
-          for (const [k, v] of Object.entries(result.error.headers)) {
-            res.setHeader(k, v)
-          }
+          for (const [k, v] of Object.entries(result.error.headers)) { res.setHeader(k, v) }
           sendJson(res, result.error.body, result.error.statusCode)
           return
         }
@@ -144,35 +134,27 @@ function buildHandler(actions: Action[], context: SilkweaveContext, auth: AuthCo
 }
 
 /**
- * REST adapter for `@silkweave/nestjs`. Mounts each discovered `@Action` as a
- * route on Nest's running HTTP server:
+ * REST adapter for `@silkweave/nestjs`. Registers each discovered `@Action`
+ * as an individual route on Nest's HTTP adapter:
  *
- * - `kind: 'query'` → `GET ${basePath}/${actionName-with-slashes}` (input read from query string)
- * - `kind: 'mutation'` → `POST ${basePath}/${actionName-with-slashes}` (input read from JSON body)
+ * - `kind: 'query'` → `GET ${basePath}/${actionName-with-slashes}` (input from query string)
+ * - `kind: 'mutation'` → `POST ${basePath}/${actionName-with-slashes}` (input from JSON body)
  *
- * Works on `@nestjs/platform-express` out of the box. For
- * `@nestjs/platform-fastify`, register `@fastify/express` before this adapter
- * so Nest can serve Express-style middleware.
+ * Routes show up in Nest's `RoutesResolver` logger and are eligible for
+ * `@nestjs/swagger` scanning. Works on `@nestjs/platform-express` out of the
+ * box. For `@nestjs/platform-fastify`, register `@fastify/express` first.
  */
 export function rest(options: RestAdapterOptions = {}): NestSilkweaveAdapter {
   return {
     name: 'rest',
-    install: (host: HttpAdapterHost): AdapterGenerator => {
-      const httpAdapter = host.httpAdapter
-      if (!httpAdapter) {
-        throw new Error('@silkweave/nestjs rest(): HttpAdapterHost.httpAdapter is not available.')
-      }
-      const basePath = (options.basePath ?? '').replace(/\/$/, '') || '/'
-      const setHandler = reserveSlot(httpAdapter as unknown as { use: (path: string, h: NodeMiddleware) => unknown }, basePath, 'REST')
-      return (_silkweaveOptions, baseContext): Adapter => {
-        const context = baseContext.fork({ adapter: 'rest' })
-        return {
-          context,
-          start: async (actions) => {
-            setHandler(buildHandler(actions, context, options.auth))
-          },
-          stop: async () => { /* Nest owns the HTTP server */ }
-        }
+    register({ httpAdapter, baseContext, actions }: NestAdapterRegisterContext): void {
+      const basePath = (options.basePath ?? '/api').replace(/\/$/, '')
+      const logger = createRestLogger()
+      for (const action of actions) {
+        const path = `${basePath}${actionNameToPath(action.name)}`
+        const method = action.kind === 'query' ? 'get' : 'post'
+        const handler = createActionHandler(action, baseContext, options.auth, logger)
+          ; (httpAdapter as unknown as Record<string, (path: string, h: typeof handler) => unknown>)[method](path, handler)
       }
     }
   }

package/src/adapter/trpc.ts

@@ -1,11 +1,8 @@
-import type { HttpAdapterHost } from '@nestjs/core'
 import { AuthConfig } from '@silkweave/auth'
-import type { Adapter, AdapterGenerator } from '@silkweave/core'
 import { buildRouter, createActionLogger, resolveAuth, type TrpcHandlerContext } from '@silkweave/trpc'
 import { createExpressMiddleware } from '@trpc/server/adapters/express'
 import type { IncomingMessage, ServerResponse } from 'http'
-import { reserveSlot, type NodeMiddleware } from '../lib/slot.js'
-import type { NestSilkweaveAdapter } from '../lib/types.js'
+import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
 
 export interface TrpcAdapterOptions {
   /** URL prefix at which the tRPC handler is mounted. Default `'/trpc'`. */
@@ -16,65 +13,44 @@ export interface TrpcAdapterOptions {
 
 /**
  * tRPC adapter for `@silkweave/nestjs`. Builds a tRPC router from discovered
- * `@Action` methods via `@silkweave/trpc`'s `buildRouter` and mounts the
- * resulting `createExpressMiddleware()` at the configured base path on Nest's
- * underlying HTTP server.
+ * `@Action` methods and mounts the resulting express middleware at
+ * `basePath` on Nest's HTTP adapter.
  *
  * Action names with dots (e.g. `users.list` from `@Actions('users')`) collapse
- * to camelCase procedure keys (`usersList`) for v1 — flat router only.
+ * to camelCase procedure keys (`usersList`).
  *
  * Works on `@nestjs/platform-express`. On `@nestjs/platform-fastify`, register
- * `@fastify/express` first so Nest can mount Express-style middleware.
+ * `@fastify/express` first so Nest can serve Express-style middleware.
  */
 export function trpc(options: TrpcAdapterOptions = {}): NestSilkweaveAdapter {
   return {
     name: 'trpc',
-    install: (host: HttpAdapterHost): AdapterGenerator => {
-      const httpAdapter = host.httpAdapter
-      if (!httpAdapter) {
-        throw new Error('@silkweave/nestjs trpc(): HttpAdapterHost.httpAdapter is not available.')
-      }
+    register({ httpAdapter, baseContext, actions }: NestAdapterRegisterContext): void {
       const basePath = (options.basePath ?? '/trpc').replace(/\/$/, '') || '/'
-      const setHandler = reserveSlot(httpAdapter as unknown as { use: (path: string, h: NodeMiddleware) => unknown }, basePath, 'tRPC')
-      return (_silkweaveOptions, baseContext): Adapter => {
-        const context = baseContext.fork({ adapter: 'trpc' })
+      const router = buildRouter(actions)
+      const logger = createActionLogger()
+      const createContext = async (
+        opts: { req: IncomingMessage; res: ServerResponse }
+      ): Promise<TrpcHandlerContext> => {
+        const resolved = await resolveAuth(options.auth, opts.req.headers.authorization, baseContext.fork({ request: opts.req }))
+        if (resolved.kind === 'error') {
+          for (const [key, value] of Object.entries<string>(resolved.error.headers)) { opts.res.setHeader(key, value) }
+          opts.res.statusCode = resolved.error.statusCode
+          opts.res.setHeader('Content-Type', 'application/json')
+          opts.res.end(JSON.stringify(resolved.error.body))
+          throw new Error('Unauthorized')
+        }
         return {
-          context,
-          start: async (actions) => {
-            const router = buildRouter(actions)
-            const logger = createActionLogger()
-            const createContext = async (
-              opts: { req: IncomingMessage; res: ServerResponse }
-            ): Promise<TrpcHandlerContext> => {
-              const resolved = await resolveAuth(
-                options.auth,
-                opts.req.headers.authorization,
-                context.fork({ request: opts.req })
-              )
-              if (resolved.kind === 'error') {
-                for (const [key, value] of Object.entries<string>(resolved.error.headers)) {
-                  opts.res.setHeader(key, value)
-                }
-                opts.res.statusCode = resolved.error.statusCode
-                opts.res.setHeader('Content-Type', 'application/json')
-                opts.res.end(JSON.stringify(resolved.error.body))
-                throw new Error('Unauthorized')
-              }
-              return {
-                silkweaveContext: context.fork({
-                  logger,
-                  request: opts.req,
-                  response: opts.res,
-                  ...(resolved.authInfo ? { auth: resolved.authInfo } : {})
-                })
-              }
-            }
-            const middleware = createExpressMiddleware({ router, createContext })
-            setHandler(middleware as unknown as NodeMiddleware)
-          },
-          stop: async () => { /* Nest owns the HTTP server */ }
+          silkweaveContext: baseContext.fork({
+            logger,
+            request: opts.req,
+            response: opts.res,
+            ...(resolved.authInfo ? { auth: resolved.authInfo } : {})
+          })
         }
       }
+      const middleware = createExpressMiddleware({ router, createContext })
+      ;(httpAdapter as unknown as { use: (path: string, h: unknown) => unknown }).use(basePath, middleware)
     }
   }
 }

package/src/adapter/typegen.ts

@@ -0,0 +1,55 @@
+import { renderTypegen, type TypegenFormat } from '@silkweave/typegen'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import type { NestAdapterRegisterContext, NestSilkweaveAdapter } from '../lib/types.js'
+
+export interface TypegenAdapterOptions {
+  /** Output file path for the generated `.d.ts` file. Resolved against `process.cwd()`. Parent directories are created automatically. */
+  path: string
+  /**
+   * What to emit (default `'all'`):
+   * - `'interfaces'` - `{Name}Input` / `{Name}Output` interfaces per action
+   * - `'trpc-router'` - `AppRouter` type alias for `createTRPCClient<AppRouter>()`
+   * - `'all'` - both
+   */
+  format?: TypegenFormat
+  /**
+   * Whether to write the file at all. Default: `process.env.NODE_ENV !== 'production'`.
+   * Server processes generally shouldn't write to disk in production deploys -
+   * leave it on the default unless you know you want otherwise.
+   */
+  enabled?: boolean
+}
+
+/**
+ * Typegen adapter for `@silkweave/nestjs`. Discovers every `@Action`-decorated
+ * method (regardless of `transports` filtering) and writes a single `.d.ts`
+ * file with REST input/output interfaces and/or a tRPC `AppRouter` type alias.
+ *
+ * Designed for the monorepo pattern where the server (this app) is the source
+ * of truth for types and consumer apps import from `path` - e.g.
+ * `path: '../app/src/types/silkweave.ts'`.
+ */
+export function typegen(options: TypegenAdapterOptions): NestSilkweaveAdapter {
+  const enabled = options.enabled ?? (process.env['NODE_ENV'] !== 'production')
+  return {
+    name: 'typegen',
+    allActions: true,
+    register({ actions }: NestAdapterRegisterContext): void {
+      if (!enabled) { return }
+      const output = renderTypegen(actions, options.format ?? 'all')
+      const target = resolve(options.path)
+      // Fire-and-forget: we don't want to make `configure()` await disk IO and
+      // delay app startup. Errors are surfaced via console.
+      void (async () => {
+        try {
+          await mkdir(dirname(target), { recursive: true })
+          await writeFile(target, output, 'utf-8')
+          console.info(`@silkweave/nestjs typegen: wrote ${actions.length} action types to ${target}`)
+        } catch (err) {
+          console.error('@silkweave/nestjs typegen:', err)
+        }
+      })()
+    }
+  }
+}

package/src/decorator/action.ts

@@ -31,8 +31,8 @@ import { ACTION_METADATA, type ActionMetadata } from '../lib/metadata.js'
  * }
  * ```
  */
-export function Action<I extends object = object, O extends object = object>(
-  options: ActionMetadata<I, O>
+export function Action<I extends object = object, O extends object = object, C = unknown>(
+  options: ActionMetadata<I, O, C>
 ): MethodDecorator {
   return SetMetadata(ACTION_METADATA, options)
 }

package/src/decorator/actions.ts

@@ -6,7 +6,7 @@ import { ACTIONS_METADATA, type ActionsClassMetadata, type Transport } from '../
  * prefix. The prefix is joined to each method's action name with a dot
  * (e.g. `@Actions('users')` + method `list` → action name `users.list`).
  *
- * The class itself remains a normal Nest provider — add `@Injectable()`
+ * The class itself remains a normal Nest provider - add `@Injectable()`
  * separately so it can be resolved by the DI container.
  *
  * Accepts either a prefix string (shorthand) or a full options object:

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './adapter/mcp.js'
 export * from './adapter/rest.js'
 export * from './adapter/trpc.js'
+export * from './adapter/typegen.js'
 export * from './decorator/action.js'
 export * from './decorator/actions.js'
 export * from './lib/discovery.js'
@@ -8,5 +9,4 @@ export * from './lib/filter.js'
 export * from './lib/guards.js'
 export * from './lib/metadata.js'
 export * from './lib/silkweave.module.js'
-export * from './lib/silkweave.service.js'
 export * from './lib/types.js'

package/src/lib/discovery.ts

@@ -1,6 +1,7 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
 import { Injectable, type Type } from '@nestjs/common'
 import { DiscoveryService, MetadataScanner, ModuleRef, Reflector } from '@nestjs/core'
-import { createAction, type Action, type SilkweaveContext } from '@silkweave/core'
+import { createAction, type Action, type ActionKind, type SilkweaveContext, type StreamingActionInput } from '@silkweave/core'
 import { kebabCase } from 'change-case'
 import { buildIsEnabled } from './filter.js'
 import { collectGuards, runGuards } from './guards.js'
@@ -22,7 +23,7 @@ export class ActionDiscovery {
     private readonly scanner: MetadataScanner,
     private readonly reflector: Reflector,
     private readonly moduleRef: ModuleRef
-  ) {}
+  ) { }
 
   /**
    * Walk every Nest provider, find methods annotated with `@Action`, and build
@@ -63,25 +64,51 @@ export class ActionDiscovery {
     const moduleRef = this.moduleRef
     const reflector = this.reflector
 
+    const applyGuards = async (context: SilkweaveContext): Promise<void> => {
+      if (guards.length === 0) { return }
+      const request = context.getOptional<unknown>('request')
+      const response = context.getOptional<unknown>('response')
+      await runGuards(guards, moduleRef, reflector, d.classRef, d.method, request, response)
+    }
+
     // Cast at the createAction boundary to bridge dual-zod-version installs
-    // (zod@3.25 + zod@4.x can both be present transitively). Runtime is fine —
-    // they share the same /v4 surface — but the structural types are distinct.
-    type CreateActionArg = Parameters<typeof createAction>[0]
+    // (zod@3.25 + zod@4.x can both be present transitively). Runtime is fine -
+    // they share the same /v4 surface - but the structural types are distinct.
+    const streaming = d.method.constructor?.name === 'AsyncGeneratorFunction'
+
+    if (streaming) {
+      if (!d.meta.chunk) {
+        throw new Error(`@Action "${name}" is an async generator but has no \`chunk\` schema`)
+      }
+      const method = d.method
+      const instance = d.instance
+      return createAction({
+        name,
+        description: d.meta.description,
+        input: d.meta.input,
+        chunk: d.meta.chunk,
+        kind: d.meta.kind ?? 'mutation',
+        args: d.meta.args,
+        isEnabled,
+        toolResult: d.meta.toolResult,
+        run: async function* (input: object, context: SilkweaveContext) {
+          await applyGuards(context)
+          yield* (method.call(instance, input, context) as AsyncGenerator<object, void, void>)
+        }
+      } as StreamingActionInput<object, unknown, string, ActionKind>) as Action
+    }
+
     return createAction({
       name,
       description: d.meta.description,
-      input: d.meta.input as unknown as CreateActionArg['input'],
-      output: d.meta.output as unknown as CreateActionArg['output'],
+      input: d.meta.input,
+      output: d.meta.output,
       kind: d.meta.kind ?? 'mutation',
-      args: d.meta.args as CreateActionArg['args'],
+      args: d.meta.args,
       isEnabled,
-      toolResult: d.meta.toolResult as CreateActionArg['toolResult'],
+      toolResult: d.meta.toolResult,
       run: async (input: object, context: SilkweaveContext): Promise<object> => {
-        if (guards.length > 0) {
-          const request = context.getOptional<unknown>('request')
-          const response = context.getOptional<unknown>('response')
-          await runGuards(guards, moduleRef, reflector, d.classRef, d.method, request, response)
-        }
+        await applyGuards(context)
         const result = await (d.method.call(d.instance, input, context) as Promise<object>)
         return result
       }

package/src/lib/executionContext.ts

@@ -1,6 +1,6 @@
 import type { ArgumentsHost, ContextType, ExecutionContext, Type } from '@nestjs/common'
 
-/** Subset of `HttpArgumentsHost` we need — re-declared inline to avoid deep `@nestjs/common/interfaces` imports. */
+/** Subset of `HttpArgumentsHost` we need - re-declared inline to avoid deep `@nestjs/common/interfaces` imports. */
 interface HttpHost {
   getRequest<T = unknown>(): T
   getResponse<T = unknown>(): T
@@ -28,8 +28,8 @@ export class SilkweaveExecutionContext implements ExecutionContext, ArgumentsHos
     private readonly args: unknown[],
     private readonly classRef: Type<unknown>,
     private readonly handler: (...handlerArgs: unknown[]) => unknown,
-    private readonly contextType: string = 'http'
-  ) {}
+    private readonly contextType = 'http'
+  ) { }
 
   getType<T extends string = ContextType>(): T {
     return this.contextType as T