@silkweave/nestjs 1.9.0

package/eslint.config.mjs

@@ -0,0 +1,93 @@
+import eslint from '@eslint/js'
+import stylistic from '@stylistic/eslint-plugin'
+import { defineConfig } from 'eslint/config'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig(eslint.configs.recommended, tseslint.configs.recommendedTypeChecked, tseslint.configs.stylisticTypeChecked, {
+  languageOptions: {
+    parserOptions: {
+      project: 'tsconfig.json',
+      tsconfigRootDir: import.meta.dirname
+    }
+  },
+  plugins: { '@stylistic': stylistic },
+  rules: {
+    '@stylistic/space-in-parens': ['error'],
+    '@stylistic/comma-spacing': ['error'],
+    '@stylistic/no-multi-spaces': ['error'],
+    '@stylistic/no-trailing-spaces': ['error'],
+    '@stylistic/no-whitespace-before-property': ['error'],
+    '@stylistic/array-bracket-newline': ['error', 'consistent'],
+    '@stylistic/array-bracket-spacing': ['error'],
+    '@stylistic/arrow-spacing': ['error'],
+    '@stylistic/arrow-parens': ['error', 'always'],
+    '@stylistic/block-spacing': ['error', 'always'],
+    '@stylistic/brace-style': ['error', '1tbs', { 'allowSingleLine': true }],
+    '@stylistic/comma-dangle': ['error', 'never'],
+    '@stylistic/key-spacing': ['error'],
+    '@stylistic/keyword-spacing': ['error'],
+    '@stylistic/member-delimiter-style': ['error', { 'multiline': { 'delimiter': 'none' } }],
+    '@stylistic/no-extra-semi': ['error'],
+    '@stylistic/indent': ['error', 2],
+    '@stylistic/no-multiple-empty-lines': ['error', { 'max': 1, 'maxEOF': 0, 'maxBOF': 0 }],
+    '@stylistic/object-curly-spacing': ['error', 'always'],
+    '@stylistic/quotes': ['error', 'single'],
+    '@stylistic/semi': ['error', 'never'],
+    '@stylistic/space-before-blocks': ['error', 'always'],
+    '@stylistic/space-before-function-paren': ['error', { 'anonymous': 'always', 'named': 'never', 'asyncArrow': 'always' }],
+    '@typescript-eslint/adjacent-overload-signatures': 'error',
+    '@typescript-eslint/array-type': 'off',
+    '@typescript-eslint/await-thenable': 'error',
+    '@typescript-eslint/ban-types': 'off',
+    '@typescript-eslint/consistent-type-assertions': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-member-accessibility': 'off',
+    '@typescript-eslint/no-angle-bracket-type-assertion': 'off',
+    '@typescript-eslint/no-empty-function': 'off',
+    '@typescript-eslint/no-empty-interface': 'off',
+    '@typescript-eslint/no-extra-non-null-assertion': 'error',
+    '@typescript-eslint/no-floating-promises': 'off',
+    '@typescript-eslint/no-misused-new': 'error',
+    '@typescript-eslint/no-misused-promises': 'off',
+    '@typescript-eslint/no-namespace': 'off',
+    '@typescript-eslint/no-non-null-asserted-optional-chain': 'error',
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/no-object-literal-type-assertion': 'off',
+    '@typescript-eslint/no-parameter-properties': 'off',
+    '@typescript-eslint/no-shadow': 'error',
+    '@typescript-eslint/no-triple-slash-reference': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', {
+      'args': 'all',
+      'argsIgnorePattern': '^_',
+      'caughtErrors': 'all',
+      'caughtErrorsIgnorePattern': '^_',
+      'destructuredArrayIgnorePattern': '^_',
+      'varsIgnorePattern': '^_',
+      'ignoreRestSiblings': true
+    }],
+    '@typescript-eslint/no-use-before-define': 'off',
+    '@typescript-eslint/no-var-requires': 'off',
+    '@typescript-eslint/prefer-for-of': 'error',
+    '@typescript-eslint/prefer-interface': 'off',
+    '@typescript-eslint/prefer-nullish-coalescing': 'off',
+    '@typescript-eslint/prefer-optional-chain': 'error',
+    '@typescript-eslint/return-await': 'error',
+    '@typescript-eslint/unified-signatures': 'error',
+    '@typescript-eslint/no-unsafe-return': 'off',
+    '@typescript-eslint/no-redundant-type-constituents': 'off',
+    '@typescript-eslint/no-unsafe-member-access': 'off',
+    '@typescript-eslint/no-unsafe-call': 'off',
+    '@typescript-eslint/no-unsafe-argument': 'off',
+    '@typescript-eslint/dot-notation': 'off',
+    '@typescript-eslint/prefer-regexp-exec': 'off',
+    '@typescript-eslint/require-await': 'off',
+    '@typescript-eslint/only-throw-error': 'error',
+    '@typescript-eslint/no-base-to-string': 'off',
+    '@typescript-eslint/restrict-template-expressions': 'off'
+  }
+}, {
+  files: ['eslint.config.mjs'],
+  extends: [tseslint.configs.disableTypeChecked]
+}, {
+  ignores: ['build', 'tsdown.config.ts', 'scratch']
+})

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@silkweave/nestjs",
+  "version": "1.9.0",
+  "description": "Silkweave NestJS Adapter",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/silkweave/silkweave.git",
+    "directory": "packages/nestjs"
+  },
+  "type": "module",
+  "main": "build/index.mjs",
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0"
+  },
+  "dependencies": {
+    "@trpc/server": "^11.7.1",
+    "change-case": "^5.4.4",
+    "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"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/node": "^22.0.0",
+    "reflect-metadata": "^0.2.2",
+    "rimraf": "^6.1.3",
+    "rxjs": "^7.8.1",
+    "tsdown": "^0.21.8",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint",
+    "check": "pnpm lint && pnpm typecheck"
+  },
+  "exports": {
+    ".": "./build/index.mjs"
+  },
+  "types": "./build/index.d.ts"
+}

package/src/adapter/mcp.ts

@@ -0,0 +1,55 @@
+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'
+
+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. */
+  basePath?: string
+  /** Optional bearer-token / OAuth auth applied to MCP requests. Same shape as `@silkweave/mcp`'s `http()` auth. */
+  auth?: AuthConfig
+}
+
+/**
+ * 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.
+ *
+ * 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)
+ *
+ * Note: this adapter mounts an Express sub-app. On `@nestjs/platform-fastify`,
+ * register `@fastify/express` before this adapter so Nest can serve Express
+ * middleware.
+ */
+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.')
+      }
+      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 */ }
+        }
+      }
+    }
+  }
+}

package/src/adapter/rest.ts

@@ -0,0 +1,179 @@
+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 { 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'
+
+const CONSOLE_LEVEL_MAP: Record<LogLevel, 'log' | 'info' | 'warn' | 'error'> = {
+  emergency: 'error',
+  alert: 'error',
+  critical: 'error',
+  error: 'error',
+  warning: 'warn',
+  notice: 'info',
+  info: 'info',
+  debug: 'log'
+}
+
+export interface RestAdapterOptions {
+  /** URL prefix at which the REST routes are mounted. e.g. `'/api'` → `POST /api/users/list`. Default: `'/'`. */
+  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
+  query?: unknown
+  url?: string
+  method?: string
+}
+
+function actionNameToPath(name: string): string {
+  return `/${name.replace(/\./g, '/')}`
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    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) }
+    })
+    req.on('error', reject)
+  })
+}
+
+function parseQuery(url: string | undefined): Record<string, string> {
+  if (!url) { return {} }
+  const qIndex = url.indexOf('?')
+  if (qIndex === -1) { return {} }
+  const params: Record<string, string> = {}
+  const search = new URLSearchParams(url.slice(qIndex + 1))
+  for (const [k, v] of search.entries()) { params[k] = v }
+  return params
+}
+
+function sendJson(res: ServerResponse, body: unknown, status: number): void {
+  if (res.headersSent) { return }
+  res.statusCode = status
+  res.setHeader('Content-Type', 'application/json')
+  res.end(JSON.stringify(body))
+}
+
+function handleRestError(err: unknown, res: ServerResponse): void {
+  if (err instanceof z.ZodError) {
+    sendJson(res, { error: 'validation_error', issues: err.issues }, 400)
+    return
+  }
+  if (err instanceof SilkweaveError) {
+    sendJson(res, { error: err.code, message: err.message }, err.statusCode)
+    return
+  }
+  if (err instanceof HttpException) {
+    const body = err.getResponse()
+    const payload = typeof body === 'string' ? { error: err.name, message: body } : body
+    sendJson(res, payload, err.getStatus())
+    return
+  }
+  console.error(err)
+  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
+    }
+    try {
+      const reqLike = req as unknown as RequestLike
+      let authInfo: AuthInfo | undefined
+      if (auth) {
+        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)
+          }
+          sendJson(res, result.error.body, result.error.statusCode)
+          return
+        }
+        authInfo = result.auth
+      }
+      const raw = action.kind === 'query'
+        ? (reqLike.query ?? parseQuery(req.url))
+        : (reqLike.body ?? await readJsonBody(req))
+      const input = action.input.parse(raw) as object
+      const result = await action.run(input, context.fork({
+        logger,
+        request: req,
+        response: res,
+        ...(authInfo ? { auth: authInfo } : {})
+      }))
+      sendJson(res, result, 200)
+    } catch (err) {
+      handleRestError(err, res)
+    }
+  }
+}
+
+/**
+ * REST adapter for `@silkweave/nestjs`. Mounts each discovered `@Action` as a
+ * route on Nest's running HTTP server:
+ *
+ * - `kind: 'query'` → `GET ${basePath}/${actionName-with-slashes}` (input read from query string)
+ * - `kind: 'mutation'` → `POST ${basePath}/${actionName-with-slashes}` (input read 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.
+ */
+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 */ }
+        }
+      }
+    }
+  }
+}

package/src/adapter/trpc.ts

@@ -0,0 +1,82 @@
+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'
+
+export interface TrpcAdapterOptions {
+  /** URL prefix at which the tRPC handler is mounted. Default `'/trpc'`. */
+  basePath?: string
+  /** Optional bearer-token auth applied to every tRPC procedure. */
+  auth?: AuthConfig
+}
+
+/**
+ * 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 names with dots (e.g. `users.list` from `@Actions('users')`) collapse
+ * to camelCase procedure keys (`usersList`) for v1 — flat router only.
+ *
+ * Works on `@nestjs/platform-express`. On `@nestjs/platform-fastify`, register
+ * `@fastify/express` first so Nest can mount 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.')
+      }
+      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' })
+        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 */ }
+        }
+      }
+    }
+  }
+}
+
+export { type InferTrpcRouter } from '@silkweave/trpc'

package/src/decorator/action.ts

@@ -0,0 +1,38 @@
+import { SetMetadata } from '@nestjs/common'
+import { ACTION_METADATA, type ActionMetadata } from '../lib/metadata.js'
+
+/**
+ * Method decorator that registers a Silkweave action.
+ *
+ * The decorated method becomes an Action and is exposed via every adapter
+ * configured on `SilkweaveModule` (REST/tRPC/MCP), unless `transports` is
+ * provided to restrict it.
+ *
+ * The method receives `(input, context)` where `input` is the parsed Zod input
+ * and `context` is the `SilkweaveContext` (with `logger`, `request`, optional
+ * `auth`). The class instance is a normal Nest provider, so other services can
+ * be injected via the constructor.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * @Actions('users')
+ * export class UserActions {
+ *   constructor(private db: DbService) {}
+ *
+ *   @Action({
+ *     description: 'List users',
+ *     input: z.object({ limit: z.number().optional() }),
+ *     kind: 'query'
+ *   })
+ *   list(input: { limit?: number }, ctx: SilkweaveContext) {
+ *     return this.db.listUsers(input.limit)
+ *   }
+ * }
+ * ```
+ */
+export function Action<I extends object = object, O extends object = object>(
+  options: ActionMetadata<I, O>
+): MethodDecorator {
+  return SetMetadata(ACTION_METADATA, options)
+}

package/src/decorator/actions.ts

@@ -0,0 +1,25 @@
+import { SetMetadata } from '@nestjs/common'
+import { ACTIONS_METADATA, type ActionsClassMetadata, type Transport } from '../lib/metadata.js'
+
+/**
+ * Class decorator that groups a provider's `@Action` methods under a common
+ * 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()`
+ * separately so it can be resolved by the DI container.
+ *
+ * Accepts either a prefix string (shorthand) or a full options object:
+ * ```ts
+ * @Actions('users')
+ * @Actions({ prefix: 'users', transports: ['rest', 'trpc'] })
+ * ```
+ */
+export function Actions(prefixOrOptions: string | ActionsClassMetadata = {}): ClassDecorator {
+  const options: ActionsClassMetadata = typeof prefixOrOptions === 'string'
+    ? { prefix: prefixOrOptions }
+    : prefixOrOptions
+  return SetMetadata(ACTIONS_METADATA, options)
+}
+
+export type { ActionsClassMetadata, Transport }

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from './adapter/mcp.js'
+export * from './adapter/rest.js'
+export * from './adapter/trpc.js'
+export * from './decorator/action.js'
+export * from './decorator/actions.js'
+export * from './lib/discovery.js'
+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

@@ -0,0 +1,90 @@
+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 { kebabCase } from 'change-case'
+import { buildIsEnabled } from './filter.js'
+import { collectGuards, runGuards } from './guards.js'
+import { ACTION_METADATA, ACTIONS_METADATA, type ActionMetadata, type ActionsClassMetadata } from './metadata.js'
+
+interface DiscoveredAction {
+  instance: object
+  classRef: Type<unknown>
+  method: (...args: unknown[]) => unknown
+  methodName: string
+  meta: ActionMetadata
+  classMeta: ActionsClassMetadata
+}
+
+@Injectable()
+export class ActionDiscovery {
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly scanner: MetadataScanner,
+    private readonly reflector: Reflector,
+    private readonly moduleRef: ModuleRef
+  ) {}
+
+  /**
+   * Walk every Nest provider, find methods annotated with `@Action`, and build
+   * a list of core `Action` objects ready to feed into `silkweave().actions()`.
+   *
+   * Action invocation is wrapped to (a) run `@UseGuards` guards declared on the
+   * method or its class against the incoming HTTP request (read from
+   * `ctx.get('request')`) and (b) bind `this` to the resolved Nest provider so
+   * DI-injected dependencies remain available.
+   */
+  discover(): Action[] {
+    const discovered: DiscoveredAction[] = []
+    const wrappers = this.discovery.getProviders()
+    for (const wrapper of wrappers) {
+      const { instance } = wrapper
+      if (!instance || typeof instance !== 'object') { continue }
+      const proto = Object.getPrototypeOf(instance) as object | null
+      if (!proto) { continue }
+      const classRef = instance.constructor as Type<unknown>
+      const classMeta = (this.reflector.get<ActionsClassMetadata>(ACTIONS_METADATA, classRef) ?? {})
+      for (const methodName of this.scanner.getAllMethodNames(proto)) {
+        const method = (proto as Record<string, unknown>)[methodName] as ((...args: unknown[]) => unknown) | undefined
+        if (typeof method !== 'function') { continue }
+        const meta = this.reflector.get<ActionMetadata>(ACTION_METADATA, method)
+        if (!meta) { continue }
+        discovered.push({ instance, classRef, method, methodName, meta, classMeta })
+      }
+    }
+    return discovered.map((d) => this.toAction(d))
+  }
+
+  private toAction(d: DiscoveredAction): Action {
+    const baseName = d.meta.name ?? kebabCase(d.methodName)
+    const name = d.classMeta.prefix ? `${d.classMeta.prefix}.${baseName}` : baseName
+    const transports = d.meta.transports ?? d.classMeta.transports
+    const isEnabled = buildIsEnabled(transports, d.meta.isEnabled)
+    const guards = collectGuards(this.reflector, d.classRef, d.method)
+    const moduleRef = this.moduleRef
+    const reflector = this.reflector
+
+    // 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]
+    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'],
+      kind: d.meta.kind ?? 'mutation',
+      args: d.meta.args as CreateActionArg['args'],
+      isEnabled,
+      toolResult: d.meta.toolResult as CreateActionArg['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)
+        }
+        const result = await (d.method.call(d.instance, input, context) as Promise<object>)
+        return result
+      }
+    })
+  }
+}