@soederpop/luca 0.1.1 → 0.1.3

package/src/introspection/generated.node.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-28T06:19:48.227Z
+// Generated at: 2026-04-03T01:24:52.175Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -12881,7 +12881,7 @@ setBuildTimeData('servers.mcp', {
           "description": "Tool schema, description, and handler",
           "properties": {
             "schema": {
-              "type": "z.ZodObject<any>",
+              "type": "z.ZodType",
               "description": ""
             },
             "description": {
@@ -12889,7 +12889,7 @@ setBuildTimeData('servers.mcp', {
               "description": ""
             },
             "handler": {
-              "type": "(args: any, ctx: MCPContext) => any",
+              "type": "Function | ((args: any, ctx: any) => any)",
               "description": ""
             }
           }
@@ -13031,7 +13031,7 @@ setBuildTimeData('servers.mcp', {
       "description": "",
       "properties": {
         "schema": {
-          "type": "z.ZodObject<any>",
+          "type": "z.ZodType",
           "description": "",
           "optional": true
         },
@@ -13041,17 +13041,9 @@ setBuildTimeData('servers.mcp', {
           "optional": true
         },
         "handler": {
-          "type": "(args: any, ctx: MCPContext) => any",
-          "description": ""
-        }
-      }
-    },
-    "MCPContext": {
-      "description": "Context object passed to all MCP tool, resource, and prompt handlers.",
-      "properties": {
-        "container": {
-          "type": "NodeContainer",
-          "description": ""
+          "type": "Function | ((args: any, ctx: any) => any)",
+          "description": "",
+          "optional": true
         }
       }
     },
@@ -13079,6 +13071,15 @@ setBuildTimeData('servers.mcp', {
         }
       }
     },
+    "MCPContext": {
+      "description": "Context object passed to all MCP tool, resource, and prompt handlers.",
+      "properties": {
+        "container": {
+          "type": "NodeContainer",
+          "description": ""
+        }
+      }
+    },
     "PromptRegistrationOptions": {
       "description": "",
       "properties": {
@@ -13472,7 +13473,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."
         }
       },
@@ -13481,6 +13482,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": {},
@@ -13787,7 +13834,7 @@ setContainerBuildTimeData('NodeContainer', {
     },
     "urlUtils": {
       "description": "Returns URL utility functions for parsing URIs.",
-      "returns": "{ parse: (uri: string) => url.URL | null }"
+      "returns": "{ parse: (uri: string) => url.UrlWithStringQuery }"
     },
     "paths": {
       "description": "Returns path utility functions scoped to the current working directory (join, resolve, relative, dirname, parse).",
@@ -26625,7 +26672,7 @@ export const introspectionData = [
             "description": "Tool schema, description, and handler",
             "properties": {
               "schema": {
-                "type": "z.ZodObject<any>",
+                "type": "z.ZodType",
                 "description": ""
               },
               "description": {
@@ -26633,7 +26680,7 @@ export const introspectionData = [
                 "description": ""
               },
               "handler": {
-                "type": "(args: any, ctx: MCPContext) => any",
+                "type": "Function | ((args: any, ctx: any) => any)",
                 "description": ""
               }
             }
@@ -26775,7 +26822,7 @@ export const introspectionData = [
         "description": "",
         "properties": {
           "schema": {
-            "type": "z.ZodObject<any>",
+            "type": "z.ZodType",
             "description": "",
             "optional": true
           },
@@ -26785,17 +26832,9 @@ export const introspectionData = [
             "optional": true
           },
           "handler": {
-            "type": "(args: any, ctx: MCPContext) => any",
-            "description": ""
-          }
-        }
-      },
-      "MCPContext": {
-        "description": "Context object passed to all MCP tool, resource, and prompt handlers.",
-        "properties": {
-          "container": {
-            "type": "NodeContainer",
-            "description": ""
+            "type": "Function | ((args: any, ctx: any) => any)",
+            "description": "",
+            "optional": true
           }
         }
       },
@@ -26823,6 +26862,15 @@ export const introspectionData = [
           }
         }
       },
+      "MCPContext": {
+        "description": "Context object passed to all MCP tool, resource, and prompt handlers.",
+        "properties": {
+          "container": {
+            "type": "NodeContainer",
+            "description": ""
+          }
+        }
+      },
       "PromptRegistrationOptions": {
         "description": "",
         "properties": {
@@ -27215,7 +27263,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."
           }
         },
@@ -27224,6 +27272,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": {},
@@ -27529,7 +27623,7 @@ export const containerIntrospectionData = [
       },
       "urlUtils": {
         "description": "Returns URL utility functions for parsing URIs.",
-        "returns": "{ parse: (uri: string) => url.URL | null }"
+        "returns": "{ parse: (uri: string) => url.UrlWithStringQuery }"
       },
       "paths": {
         "description": "Returns path utility functions scoped to the current working directory (join, resolve, relative, dirname, parse).",

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-28T06:19:48.239Z
+// 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] }
   }
 
   /**