@soederpop/luca 0.1.2 → 0.1.3

package/src/introspection/generated.web.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-30T06:52:54.962Z
+// Generated at: 2026-04-03T01:24:52.187Z
 
 setBuildTimeData('features.containerLink', {
   "id": "features.containerLink",
@@ -767,7 +767,7 @@ setContainerBuildTimeData('Container', {
           "description": "The id of the feature to create."
         },
         "options": {
-          "type": "ConstructorParameters<Features[T]>[0]",
+          "type": "FeatureInputOptions<Features>[T] | Record<string, unknown>",
           "description": "The options to pass to the feature constructor."
         }
       },
@@ -776,6 +776,52 @@ setContainerBuildTimeData('Container', {
       ],
       "returns": "InstanceType<Features[T]>"
     },
+    "entity": {
+      "description": "Creates a lightweight entity object with observable state, a typed event bus, and access to the container. Same id + options always returns the same cached base instance. An optional third argument auto-extends the entity with functions and getters. All extended methods and getters can access the entity (state, options, container, on/off/emit, etc.) via `this`.",
+      "parameters": {
+        "id": {
+          "type": "string",
+          "description": "Stable identifier for this entity (included in cache key)"
+        },
+        "options": {
+          "type": "TOptions",
+          "description": "Arbitrary options stored on `entity.options` (included in cache key)"
+        },
+        "extensions": {
+          "type": "Ext & ThisType<Entity<TState, TOptions, TEvents> & Ext>",
+          "description": "Optional object of functions/getters to graft onto the entity"
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "returns": "Entity<TState, TOptions, TEvents> & Ext",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "// Basic entity with typed state and events\nconst counter = container.entity<{ count: number }>('counter')\ncounter.setState({ count: 0 })\ncounter.on('tick', () => counter.setState(s => ({ count: s.count + 1 })))\n\n// With options and auto-extension\nconst user = container.entity('user:42', { name: 'Alice' }, {\n greet() { return `Hello ${this.options.name}` },\n get label() { return `User: ${this.options.name}` },\n})\nuser.greet() // \"Hello Alice\""
+        }
+      ]
+    },
+    "getHelperByUUID": {
+      "description": "Look up any helper instance (feature, client, server) by its UUID. Returns undefined if the UUID is unknown or the instance was never created.",
+      "parameters": {
+        "uuid": {
+          "type": "string",
+          "description": "The `instance.uuid` value assigned at construction time"
+        }
+      },
+      "required": [
+        "uuid"
+      ],
+      "returns": "Helper | undefined",
+      "examples": [
+        {
+          "language": "ts",
+          "code": "const assistant = container.feature('assistant')\nconst { uuid } = assistant\n// ... later ...\nconst same = container.getHelperByUUID(uuid) // === assistant"
+        }
+      ]
+    },
     "start": {
       "description": "Start the container. Emits the 'started' event and sets `state.started` to true. Plugins and features can listen for this event to perform initialization.",
       "parameters": {},
@@ -1841,7 +1887,7 @@ export const containerIntrospectionData = [
             "description": "The id of the feature to create."
           },
           "options": {
-            "type": "ConstructorParameters<Features[T]>[0]",
+            "type": "FeatureInputOptions<Features>[T] | Record<string, unknown>",
             "description": "The options to pass to the feature constructor."
           }
         },
@@ -1850,6 +1896,52 @@ export const containerIntrospectionData = [
         ],
         "returns": "InstanceType<Features[T]>"
       },
+      "entity": {
+        "description": "Creates a lightweight entity object with observable state, a typed event bus, and access to the container. Same id + options always returns the same cached base instance. An optional third argument auto-extends the entity with functions and getters. All extended methods and getters can access the entity (state, options, container, on/off/emit, etc.) via `this`.",
+        "parameters": {
+          "id": {
+            "type": "string",
+            "description": "Stable identifier for this entity (included in cache key)"
+          },
+          "options": {
+            "type": "TOptions",
+            "description": "Arbitrary options stored on `entity.options` (included in cache key)"
+          },
+          "extensions": {
+            "type": "Ext & ThisType<Entity<TState, TOptions, TEvents> & Ext>",
+            "description": "Optional object of functions/getters to graft onto the entity"
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "returns": "Entity<TState, TOptions, TEvents> & Ext",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "// Basic entity with typed state and events\nconst counter = container.entity<{ count: number }>('counter')\ncounter.setState({ count: 0 })\ncounter.on('tick', () => counter.setState(s => ({ count: s.count + 1 })))\n\n// With options and auto-extension\nconst user = container.entity('user:42', { name: 'Alice' }, {\n greet() { return `Hello ${this.options.name}` },\n get label() { return `User: ${this.options.name}` },\n})\nuser.greet() // \"Hello Alice\""
+          }
+        ]
+      },
+      "getHelperByUUID": {
+        "description": "Look up any helper instance (feature, client, server) by its UUID. Returns undefined if the UUID is unknown or the instance was never created.",
+        "parameters": {
+          "uuid": {
+            "type": "string",
+            "description": "The `instance.uuid` value assigned at construction time"
+          }
+        },
+        "required": [
+          "uuid"
+        ],
+        "returns": "Helper | undefined",
+        "examples": [
+          {
+            "language": "ts",
+            "code": "const assistant = container.feature('assistant')\nconst { uuid } = assistant\n// ... later ...\nconst same = container.getHelperByUUID(uuid) // === assistant"
+          }
+        ]
+      },
       "start": {
         "description": "Start the container. Emits the 'started' event and sets `state.started` to true. Plugins and features can listen for this event to perform initialization.",
         "parameters": {},

package/src/introspection/scan.ts

@@ -587,7 +587,7 @@ export class IntrospectionScannerFeature extends Feature<IntrospectionScannerSta
         if (!commentText.startsWith('/**')) continue;
 
         const match = commentText.match(/@returns?\s*\{([^}]+)\}/);
-        if (match) return match[1].trim();
+        if (match && match[1]) return match[1].trim();
       }
     }
 

package/src/node/container.ts

@@ -366,7 +366,7 @@ export class NodeContainer<
   }
 
   /** Returns URL utility functions for parsing URIs. */
-  get urlUtils(): { parse: (uri: string) => url.URL | null } {
+  get urlUtils(): { parse: (uri: string) => url.UrlWithStringQuery } {
     return {
       parse: (uri: string) => url.parse(uri)
     }

package/src/node/features/content-db.ts

@@ -46,7 +46,7 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
   static { Feature.register(this, 'contentDb') }
 
   /** Tools that any assistant can use to progressively explore this collection. */
-  static tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
+  static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
     getCollectionOverview: {
       schema: z.object({}).describe(
         'Get a high-level overview of the document collection: models, document counts, directory tree, and search index status. Call this first to understand what is available.'
@@ -460,7 +460,7 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
     // Dynamically import and attach SemanticSearch if not already registered
     const { SemanticSearch } = await import('./semantic-search.js')
     if (!this.container.features.available.includes('semanticSearch')) {
-      SemanticSearch.attach(this.container as any)
+      ;(SemanticSearch as any).attach(this.container as any)
     }
 
     // Store search index in ~/.luca/contentbase/{hash}/ keyed by the real (symlink-resolved) collection path
@@ -660,7 +660,7 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
   get queries(): Record<string, ReturnType<typeof this.query>> {
     const queryChains: [string, ReturnType<typeof this.query>][] = []
     for (const modelName of this.modelNames) {
-      const queryChain = this.query(this.models[modelName])
+      const queryChain = this.query(this.models[modelName]!)
       const pluralized = this.container.utils.stringUtils.pluralize(modelName).toLowerCase()
       queryChains.push([modelName.toLowerCase(), queryChain])
       queryChains.push([pluralized, queryChain])

package/src/node/features/file-manager.ts

@@ -147,7 +147,7 @@ export class FileManager<
 
   /** Returns the list of directories currently being watched. */
   get watchedPaths(): string[] {
-    return this.state.get("watchedPaths") || [];
+    return (this.state.get("watchedPaths") as string[] | undefined) || [];
   }
 
   /** 
@@ -199,7 +199,7 @@ export class FileManager<
       const { git } = this.container;
       if (!git.isRepo) return null;
 
-      const gitDir = pathJoin(git.repoRoot, '.git');
+      const gitDir = pathJoin(git.repoRoot!, '.git');
       const head = readFileSync(pathJoin(gitDir, 'HEAD'), 'utf8').trim();
 
       // Detached HEAD — already a sha
@@ -217,7 +217,7 @@ export class FileManager<
         const ref = head.slice(5);
         const packed = readFileSync(packedRefsPath, 'utf8');
         const match = packed.match(new RegExp(`^([0-9a-f]{40}) ${ref}`, 'm'));
-        if (match) return match[1];
+        if (match) return match[1] ?? null;
       }
 
       return null;
@@ -334,8 +334,8 @@ export class FileManager<
       if (cwdRelative) {
         const prefix = cwdRelative + '/';
         for (let i = 0; i < fileIds.length; i++) {
-          if (fileIds[i].startsWith(prefix)) {
-            fileIds[i] = fileIds[i].slice(prefix.length);
+          if (fileIds[i]!.startsWith(prefix)) {
+            fileIds[i] = fileIds[i]!.slice(prefix.length);
           }
         }
       }
@@ -422,12 +422,12 @@ export class FileManager<
 
     // If already watching, just add the new paths
     if (this.isWatching && this.watcher) {
-      const currentPaths: string[] = this.state.get("watchedPaths") || [];
+      const currentPaths: string[] = (this.state.get("watchedPaths") as string[] | undefined) || [];
       const newPaths = pathsToWatch.filter(p => !currentPaths.includes(p));
 
       if (newPaths.length) {
         this.watcher.add(newPaths);
-        this.state.set("watchedPaths", [...currentPaths, ...newPaths]);
+        this.state.set("watchedPaths", [...currentPaths, ...newPaths] as any);
       }
 
       return;
@@ -481,7 +481,7 @@ export class FileManager<
 
     watcher.on("ready", () => {
       this.state.set("watching", true);
-      this.state.set("watchedPaths", pathsToWatch);
+      this.state.set("watchedPaths", pathsToWatch as any);
     });
 
     this.watcher = watcher;
@@ -495,7 +495,7 @@ export class FileManager<
     if (this.watcher) {
       this.watcher.close();
       this.state.set("watching", false);
-      this.state.set("watchedPaths", []);
+      this.state.set("watchedPaths", [] as any);
       this.watcher = null;
     }
   }
@@ -508,6 +508,7 @@ export class FileManager<
       const stats = statSync(absolutePath);
       this.files.set(path, {
         dirname: dir,
+        relativeDirname: this.container.paths.relative(dir),
         absolutePath,
         relativePath: path,
         name,

package/src/node/features/git.ts

@@ -155,7 +155,7 @@ export class Git extends Feature {
      */
     get branch(): string | null {
         if(!this.isRepo) { return null }
-        return this.container.feature('proc').exec(`${this.gitPath} branch`).split("\n").filter(line => line.startsWith('*')).map(line => line.replace('*', '').trim()).pop()
+        return this.container.feature('proc').exec(`${this.gitPath} branch`).split("\n").filter(line => line.startsWith('*')).map(line => line.replace('*', '').trim()).pop() ?? null
     }
     
     /**
@@ -230,7 +230,7 @@ export class Git extends Feature {
      */
     get repoRoot(): string | null {
         if (this.state.has('repoRoot')) {
-            return this.state.get('repoRoot')
+            return this.state.get('repoRoot') ?? null
         }
 
         const repoRoot = this.container.fs.findUp('.git')
@@ -507,12 +507,12 @@ export class Git extends Feature {
         if (str.startsWith('github.com/')) str = str.replace('github.com/', '')
         if (str.includes('#')) {
             const parts = str.split('#')
-            str = parts[0]
-            ref = parts[1]
+            str = parts[0] ?? str
+            ref = parts[1] ?? ref
         }
 
         const parts = str.split('/')
-        return { user: parts[0], repo: parts[1], ref, subdir: parts.slice(2).join('/') }
+        return { user: parts[0] ?? '', repo: parts[1] ?? '', ref, subdir: parts.slice(2).join('/') }
     }
 
     /**

package/src/node/features/helpers.ts

@@ -201,7 +201,7 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
     }
 
     // Schemas
-    const schemasModule = { CommandOptionsSchema: commands.baseClass?.optionsSchema || z.object({}) }
+    const schemasModule: Record<string, any> = { CommandOptionsSchema: commands.baseClass?.optionsSchema || z.object({}) }
     try {
       // Pull all base schemas from the already-loaded schemas/base module
       const baseSchemas = require('../../schemas/base.js')

package/src/node/features/json-tree.ts

@@ -121,7 +121,7 @@ export class JsonTree<T extends JsonTreeState = JsonTreeState> extends Feature<T
     for (const file of jsonFiles.filter(Boolean)) {
       if (file?.relativePath) {
         const fileContent = fileSystem.readFile(file.relativePath);
-        const fileData = JSON.parse(fileContent);
+        const fileData = JSON.parse(String(fileContent));
         const path = file.relativePath
           .replace(/\.json$/, "")
           .replace(basePath + "/", "")

package/src/node/features/os.ts

@@ -207,12 +207,12 @@ export class OS extends Feature {
           displays.push({
             name: d._name ?? 'Unknown',
             resolution: {
-              width: resMatch ? parseInt(resMatch[1], 10) : 0,
-              height: resMatch ? parseInt(resMatch[2], 10) : 0,
+              width: resMatch ? parseInt(resMatch[1] ?? '0', 10) : 0,
+              height: resMatch ? parseInt(resMatch[2] ?? '0', 10) : 0,
             },
             retina: /retina/i.test(d._spdisplays_resolution ?? '') || /retina/i.test(d.spdisplays_display_type ?? ''),
             main: d.spdisplays_main === 'spdisplays_yes' || /yes/i.test(d.spdisplays_main ?? ''),
-            refreshRate: hzMatch ? parseFloat(hzMatch[1]) : undefined,
+            refreshRate: hzMatch ? parseFloat(hzMatch[1] ?? '0') : undefined,
             connectionType: d.spdisplays_connection_type ?? undefined,
           })
         }

package/src/node/features/package-finder.ts

@@ -296,7 +296,7 @@ export class PackageFinder<
    */
   get scopes(): string[] {
     return Array.from(
-      new Set(this.packageNames.filter(p => p.startsWith('@')).map(p => p.split('/')[0]))
+      new Set(this.packageNames.filter(p => p.startsWith('@')).map(p => p.split('/')[0]).filter((s): s is string => s !== undefined))
     )
   }
  

package/src/node/features/process-manager.ts

@@ -436,7 +436,7 @@ export class ProcessManager extends Feature {
   static { Feature.register(this, 'processManager') }
 
   /** Tools that an assistant can use to spawn and manage processes. */
-  static tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
+  static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
     spawnProcess: {
       schema: z.object({
         command: z.string().describe('The command to execute (e.g. "node", "bun", "python")'),

package/src/node/features/python.ts

@@ -59,7 +59,7 @@ export const PythonEventsSchema = FeatureEventsSchema.extend({
   }).describe('Install result')]).describe('When dependency installation fails'),
   codeExecuted: z.tuple([z.object({
     code: z.string().describe('The Python code that was executed'),
-    variables: z.record(z.any()).describe('Variables passed to the execution'),
+    variables: z.record(z.string(), z.any()).describe('Variables passed to the execution'),
     result: z.object({
       stdout: z.string().describe('Standard output'),
       stderr: z.string().describe('Standard error'),
@@ -68,7 +68,7 @@ export const PythonEventsSchema = FeatureEventsSchema.extend({
   }).describe('Code execution details')]).describe('When Python code finishes executing'),
   fileExecuted: z.tuple([z.object({
     filePath: z.string().describe('Path to the executed Python file'),
-    variables: z.record(z.any()).describe('Variables passed as arguments'),
+    variables: z.record(z.string(), z.any()).describe('Variables passed as arguments'),
     result: z.object({
       stdout: z.string().describe('Standard output'),
       stderr: z.string().describe('Standard error'),
@@ -532,7 +532,7 @@ export class Python<
    */
   private _parsePythonCommand(extraArgs: string[]): { command: string, args: string[] } {
     const parts = this.pythonPath.split(/\s+/)
-    return { command: parts[0], args: [...parts.slice(1), ...extraArgs] }
+    return { command: parts[0] ?? 'python', args: [...parts.slice(1), ...extraArgs] }
   }
 
   /**

package/src/node/features/redis.ts

@@ -400,7 +400,7 @@ export class RedisFeature extends Feature<RedisState, RedisOptions> {
     )
 
     if (existing) {
-      if (existing.state !== 'running') {
+      if (existing.status !== 'running') {
         await docker.startContainer(name)
       }
       return existing.id

package/src/node/features/repl.ts

@@ -101,7 +101,7 @@ export class Repl<
 
     // Load existing history
     try {
-      const content = fs.readFile(this._historyPath, 'utf-8')
+      const content = this.container.fs.readFile(this._historyPath, 'utf-8') as string
       this._history = content.split('\n').filter(Boolean).reverse()
     } catch {}
 
@@ -204,7 +204,7 @@ export class Repl<
   private _saveHistory(line: string) {
     if (!this._historyPath || !line.trim()) return
     try {
-      fs.appendFileSync(this._historyPath, line + '\n')
+      this.container.fs.appendFile(this._historyPath, line + '\n')
     } catch {}
   }
 }

package/src/node/features/transpiler.ts

@@ -45,8 +45,8 @@ function esmToCjs(code: string): string {
     .replace(/^export\s+\{([^}]*)\}\s*;?$/gm, (_match, body: string) => {
       return body.split(',').map(s => {
         const parts = s.trim().split(/\s+as\s+/)
-        const local = parts[0].trim()
-        const exported = (parts[1] || parts[0]).trim()
+        const local = (parts[0] ?? '').trim()
+        const exported = (parts[1] ?? parts[0] ?? '').trim()
         return local ? `exports['${exported}'] = ${local};` : ''
       }).filter(Boolean).join(' ')
     })

package/src/node/features/ui.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { FeatureStateSchema } from '../../schemas/base.js'
 import { Feature } from "../feature.js";
 import colors from "chalk";
-import type { Fonts } from "figlet";
+import type { FontName as Fonts } from "figlet";
 import { figlet, fontNames } from "./figlet-fonts.js";
 import inquirer from "inquirer";
 import { marked } from 'marked';

package/src/node/features/vm.ts

@@ -219,9 +219,9 @@ export class VM<
 
     // Find the last non-empty line
     let lastIdx = lines.length - 1
-    while (lastIdx > 0 && !lines[lastIdx].trim()) lastIdx--
+    while (lastIdx > 0 && !(lines[lastIdx] ?? '').trim()) lastIdx--
 
-    let lastLine = lines[lastIdx]!
+    let lastLine = lines[lastIdx] ?? ''
 
     // For single-line code with semicolons (e.g. CLI eval), split the last line
     // into statements and only try to return the final statement.
@@ -390,7 +390,7 @@ export class VM<
     if (!fs.exists(filePath)) return {}
 
     const raw = fs.readFile(filePath)
-    const { code } = this.container.feature('transpiler').transformSync(raw, { format: 'cjs' })
+    const { code } = this.container.feature('transpiler').transformSync(String(raw), { format: 'cjs' })
 
     const sharedExports = {}
     const { context } = this.performSync(code, {

package/src/node/features/yaml-tree.ts

@@ -113,7 +113,7 @@ export class YamlTree<T extends YamlTreeState = YamlTreeState> extends Feature<T
     for (const file of yamlFiles.filter(Boolean)) {
       if(file?.relativePath) {
         const fileContent = fileSystem.readFile(file.relativePath);
-        const fileData = yamlFeature.parse(fileContent);
+        const fileData = yamlFeature.parse(String(fileContent));
         const path = file.relativePath.replace(/\.ya?ml$/, "").replace(basePath + "/", "").split("/").filter(v => v?.length).map(p => camelCase(p));
         set(tree, path, fileData)
       }

package/src/node.ts

@@ -65,6 +65,7 @@ export type { AvailableFeatures, FeatureOptions, FeatureState } from './feature'
 export type { NodeContainer, NodeFeatures } from './node/container'
 export type { AvailableServers, StartOptions, ServersInterface } from './server'
 export type { HelperState, HelperOptions } from './helper'
+export type { Entity } from './entity'
 export type { EventMap } from './bus'
 export type { SetStateValue, StateChangeType } from './state'
 

package/src/python/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated Python bridge script
-// Generated at: 2026-03-30T06:52:57.841Z
+// Generated at: 2026-04-03T01:24:54.795Z
 // Source: src/python/bridge.py
 //
 // Do not edit manually. Run: luca build-python-bridge

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-30T06:52:56.013Z
+// Generated at: 2026-04-03T01:24:53.146Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/src/selector.ts

@@ -135,17 +135,17 @@ export class Selector<
 		}
 
 		// Run the selector
-		this.state.set('running' as any, true)
+		this.state.set('running' as any, true as any)
 		this.emit('started' as any)
 
 		let data: any
 		try {
 			data = await this.run(parsed, this.context)
-			this.state.set('running' as any, false)
-			this.state.set('lastRanAt' as any, Date.now())
+			this.state.set('running' as any, false as any)
+			this.state.set('lastRanAt' as any, Date.now() as any)
 			this.emit('completed' as any, data)
 		} catch (err: any) {
-			this.state.set('running' as any, false)
+			this.state.set('running' as any, false as any)
 			this.emit('failed' as any, err)
 			throw err
 		}
@@ -197,6 +197,76 @@ export class SelectorsRegistry extends Registry<Selector<any>> {
 	override scope = 'selectors'
 	override baseClass = Selector as any
 
+	/**
+	 * Convert all registered selectors into a `{ schemas, handlers }` object
+	 * compatible with `assistant.use()`.
+	 *
+	 * Each selector becomes a tool whose parameters come from the selector's
+	 * `argsSchema` (with internal fields stripped) and whose handler dispatches
+	 * the selector and returns the data directly (cache metadata is not exposed).
+	 *
+	 * @param container - The container used to instantiate and run selectors
+	 * @param options - Optional filter/transform options
+	 * @param options.include - Only include these selector names (default: all)
+	 * @param options.exclude - Exclude these selector names (default: none)
+	 * @param options.prefix - Prefix tool names (e.g. 'sel_' → 'sel_packageInfo')
+	 */
+	toTools(
+		container: Container<any> & SelectorsInterface,
+		options?: { include?: string[], exclude?: string[], prefix?: string },
+	): { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } {
+		const schemas: Record<string, z.ZodType> = {}
+		const handlers: Record<string, Function> = {}
+		const prefix = options?.prefix ?? ''
+		const includeSet = options?.include ? new Set(options.include) : null
+		const excludeSet = new Set(options?.exclude ?? [])
+
+		// Internal fields from HelperOptionsSchema and SelectorOptionsSchema
+		const internalFields = ['name', '_cacheKey', 'dispatchSource']
+
+		for (const name of this.available) {
+			if (excludeSet.has(name)) continue
+			if (includeSet && !includeSet.has(name)) continue
+
+			const Sel = this.lookup(name) as typeof Selector
+			const rawSchema = Sel.argsSchema
+			const description = Sel.selectorDescription || Sel.description || name
+
+			let toolSchema: z.ZodType
+			try {
+				const shape = typeof (rawSchema as any)?._def?.shape === 'function'
+					? (rawSchema as any)._def.shape()
+					: (rawSchema as any)?._def?.shape
+
+				if (shape) {
+					const cleanShape: Record<string, z.ZodType> = {}
+					for (const [key, val] of Object.entries(shape)) {
+						if (internalFields.includes(key)) continue
+						cleanShape[key] = val as z.ZodType
+					}
+
+					toolSchema = Object.keys(cleanShape).length > 0
+						? z.object(cleanShape).describe(description)
+						: z.object({}).describe(description)
+				} else {
+					toolSchema = z.object({}).describe(description)
+				}
+			} catch {
+				toolSchema = z.object({}).describe(description)
+			}
+
+			const toolName = `${prefix}${name}`
+			schemas[toolName] = toolSchema
+			handlers[toolName] = async (args: Record<string, any>) => {
+				const sel = (container.select as any)(name)
+				const result = await sel.select(args ?? {})
+				return result.data
+			}
+		}
+
+		return { schemas, handlers }
+	}
+
 	/**
 	 * Discover and register selectors from a directory.
 	 * Detection order:

package/src/server.ts

@@ -30,7 +30,7 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
     static override eventsSchema = ServerEventsSchema
 
     /** Self-register a Server subclass from a static initialization block. */
-    static register: (SubClass: typeof Server, id?: string) => typeof Server
+    static register: (SubClass: abstract new (options: any, context: any) => Server, id?: string) => abstract new (options: any, context: any) => Server
 
     override get initialState() : T {
       return ({
@@ -203,7 +203,7 @@ export const helperCache = new Map()
  * ```
  */
 Server.register = function registerServer(
-  SubClass: typeof Server,
+  SubClass: abstract new (options: any, context: any) => Server,
   id?: string,
 ) {
   const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)

package/src/servers/mcp.ts

@@ -33,9 +33,9 @@ export type MCPContext = {
 export interface RegisteredTool {
   name: string
   description?: string
-  schema?: z.ZodObject<any>
+  schema?: z.ZodType
   jsonSchema?: Record<string, any>
-  handler: (args: any, ctx: MCPContext) => any
+  handler: Function
 }
 
 /** A registered MCP resource with its URI, metadata, and handler. */
@@ -61,9 +61,9 @@ export type PromptMessage = {
 }
 
 type ToolRegistrationOptions = {
-  schema?: z.ZodObject<any>
+  schema?: z.ZodType
   description?: string
-  handler: (args: any, ctx: MCPContext) => any
+  handler?: Function | ((args: any, ctx: any) => any)
 }
 
 type ResourceRegistrationOptions = {
@@ -340,7 +340,7 @@ export class MCPServer extends Server<MCPServerState, MCPServerOptions> {
    * @param name - Unique tool name
    * @param options - Tool schema, description, and handler
    */
-  tool(name: string, options: ToolRegistrationOptions): this {
+  override tool(name: string, options: ToolRegistrationOptions): this {
     let jsonSchema: Record<string, any> | undefined
 
     if (options.schema) {
@@ -357,7 +357,7 @@ export class MCPServer extends Server<MCPServerState, MCPServerOptions> {
       description: options.description,
       schema: options.schema,
       jsonSchema,
-      handler: options.handler,
+      handler: options.handler ?? (() => {}),
     }
 
     this._tools.set(name, registered)