@soederpop/luca 0.1.2 → 0.2.1

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-30T06:52:54.952Z
+// Generated at: 2026-04-05T06:58:06.158Z
 
 setBuildTimeData('features.googleDocs', {
   "id": "features.googleDocs",
@@ -8692,6 +8692,19 @@ setBuildTimeData('features.processManager', {
       ],
       "returns": "void"
     },
+    "setupToolsConsumer": {
+      "description": "When an assistant uses processManager, inject system prompt guidance about how to manage processes safely and effectively.",
+      "parameters": {
+        "consumer": {
+          "type": "Helper",
+          "description": "Parameter consumer"
+        }
+      },
+      "required": [
+        "consumer"
+      ],
+      "returns": "void"
+    },
     "spawn": {
       "description": "Spawn a long-running process and return a handle immediately. The returned SpawnHandler provides events for stdout/stderr streaming, exit/crash notifications, and methods to kill or await the process.",
       "parameters": {
@@ -11111,6 +11124,19 @@ setBuildTimeData('features.contentDb', {
   "shortcut": "features.contentDb",
   "className": "ContentDb",
   "methods": {
+    "setupToolsConsumer": {
+      "description": "When an assistant uses contentDb, inject system prompt guidance about progressive document exploration.",
+      "parameters": {
+        "consumer": {
+          "type": "Helper",
+          "description": "Parameter consumer"
+        }
+      },
+      "required": [
+        "consumer"
+      ],
+      "returns": "void"
+    },
     "renderTree": {
       "description": "Render a tree view of the collection directory structure. Built with container.fs so it works without the `tree` binary.",
       "parameters": {
@@ -12881,7 +12907,7 @@ setBuildTimeData('servers.mcp', {
           "description": "Tool schema, description, and handler",
           "properties": {
             "schema": {
-              "type": "z.ZodObject<any>",
+              "type": "z.ZodType",
               "description": ""
             },
             "description": {
@@ -12889,7 +12915,7 @@ setBuildTimeData('servers.mcp', {
               "description": ""
             },
             "handler": {
-              "type": "(args: any, ctx: MCPContext) => any",
+              "type": "Function | ((args: any, ctx: any) => any)",
               "description": ""
             }
           }
@@ -13031,7 +13057,7 @@ setBuildTimeData('servers.mcp', {
       "description": "",
       "properties": {
         "schema": {
-          "type": "z.ZodObject<any>",
+          "type": "z.ZodType",
           "description": "",
           "optional": true
         },
@@ -13041,17 +13067,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 +13097,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 +13499,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 +13508,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 +13860,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).",
@@ -22451,6 +22524,19 @@ export const introspectionData = [
         ],
         "returns": "void"
       },
+      "setupToolsConsumer": {
+        "description": "When an assistant uses processManager, inject system prompt guidance about how to manage processes safely and effectively.",
+        "parameters": {
+          "consumer": {
+            "type": "Helper",
+            "description": "Parameter consumer"
+          }
+        },
+        "required": [
+          "consumer"
+        ],
+        "returns": "void"
+      },
       "spawn": {
         "description": "Spawn a long-running process and return a handle immediately. The returned SpawnHandler provides events for stdout/stderr streaming, exit/crash notifications, and methods to kill or await the process.",
         "parameters": {
@@ -24863,6 +24949,19 @@ export const introspectionData = [
     "shortcut": "features.contentDb",
     "className": "ContentDb",
     "methods": {
+      "setupToolsConsumer": {
+        "description": "When an assistant uses contentDb, inject system prompt guidance about progressive document exploration.",
+        "parameters": {
+          "consumer": {
+            "type": "Helper",
+            "description": "Parameter consumer"
+          }
+        },
+        "required": [
+          "consumer"
+        ],
+        "returns": "void"
+      },
       "renderTree": {
         "description": "Render a tree view of the collection directory structure. Built with container.fs so it works without the `tree` binary.",
         "parameters": {
@@ -26625,7 +26724,7 @@ export const introspectionData = [
             "description": "Tool schema, description, and handler",
             "properties": {
               "schema": {
-                "type": "z.ZodObject<any>",
+                "type": "z.ZodType",
                 "description": ""
               },
               "description": {
@@ -26633,7 +26732,7 @@ export const introspectionData = [
                 "description": ""
               },
               "handler": {
-                "type": "(args: any, ctx: MCPContext) => any",
+                "type": "Function | ((args: any, ctx: any) => any)",
                 "description": ""
               }
             }
@@ -26775,7 +26874,7 @@ export const introspectionData = [
         "description": "",
         "properties": {
           "schema": {
-            "type": "z.ZodObject<any>",
+            "type": "z.ZodType",
             "description": "",
             "optional": true
           },
@@ -26785,17 +26884,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 +26914,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 +27315,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 +27324,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 +27675,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-30T06:52:54.962Z
+// Generated at: 2026-04-05T06:58:06.168Z
 
 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)
     }