@soederpop/luca 0.1.2 → 0.1.3

package/src/container.ts

@@ -11,6 +11,7 @@ import { z } from 'zod'
 import { ContainerStateSchema, describeZodShape } from './schemas/base'
 import { getContainerBuildTimeData, type ContainerIntrospection, type RegistryIntrospection, type IntrospectionSection } from './introspection/index'
 import { ContainerDescriber } from './container-describer'
+import { createEntityObject, type Entity, type EventMap as EntityEventMap } from './entity'
 
 export { z }
 
@@ -23,7 +24,24 @@ export type { AvailableFeatures }
 // I want the InstanceType of each value of AvailableFeatures, AvailableClients, whatever
 export type AvailableInstanceTypes<T> = {
   [K in keyof T]: T[K] extends new (...args: any) => any ? InstanceType<T[K]> : never
-} 
+}
+
+/**
+ * Maps a feature registry to the INPUT type of each feature's optionsSchema.
+ * This allows feature() to accept partial/optional options (e.g. omitting fields
+ * that have .default() on them) rather than requiring the fully-parsed OUTPUT type.
+ *
+ * For any feature class that exposes a static `optionsSchema`, we use `z.input<S>` so
+ * that callers can omit fields that have `.default(...)` — Zod's output type marks
+ * defaulted fields as required, but the input type correctly makes them optional.
+ */
+export type FeatureInputOptions<Features> = {
+  [K in keyof Features]: Features[K] extends { optionsSchema: infer S extends z.ZodType }
+    ? z.input<S>
+    : Features[K] extends new (options: infer O, ...args: any[]) => any
+      ? O
+      : Record<string, unknown>
+}
 
 /**
  * You'll want to use module augmentation to add your own options to the ContainerArgv interface
@@ -53,6 +71,7 @@ export interface ContainerUtils {
 
 export interface ContainerContext<T extends AvailableFeatures = any> {
   container: Container<T>
+  [key: string]: unknown
 }
 
 /**
@@ -429,6 +448,7 @@ export class Container<Features extends AvailableFeatures = AvailableFeatures, C
 
     const instance = new (BaseClass as any)(helperOptions, context || this.context)
     cache.set(cacheKey, instance)
+    uuidCache.set(instance.uuid, instance)
     return instance
   }
 
@@ -445,7 +465,7 @@ export class Container<Features extends AvailableFeatures = AvailableFeatures, C
   */
   feature<T extends keyof Features>(
     id: T,
-    options?: ConstructorParameters<Features[T]>[0]
+    options?: FeatureInputOptions<Features>[T] | Record<string, unknown>
   ): InstanceType<Features[T]> {
     const BaseClass = this.features.lookup(id as string) as Features[T]
 
@@ -459,7 +479,75 @@ export class Container<Features extends AvailableFeatures = AvailableFeatures, C
       context: { container: this },
     }) as InstanceType<Features[T]>
   }
-  
+
+  /**
+   * 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`.
+   *
+   * @param id         - Stable identifier for this entity (included in cache key)
+   * @param options    - Arbitrary options stored on `entity.options` (included in cache key)
+   * @param extensions - Optional object of functions/getters to graft onto the entity
+   *
+   * @example
+   * ```ts
+   * // Basic entity with typed state and events
+   * const counter = container.entity<{ count: number }>('counter')
+   * counter.setState({ count: 0 })
+   * counter.on('tick', () => counter.setState(s => ({ count: s.count + 1 })))
+   *
+   * // With options and auto-extension
+   * const user = container.entity('user:42', { name: 'Alice' }, {
+   *   greet() { return `Hello ${this.options.name}` },
+   *   get label() { return `User: ${this.options.name}` },
+   * })
+   * user.greet() // "Hello Alice"
+   * ```
+   */
+  entity<
+    TState extends Record<string, any> = Record<string, any>,
+    TOptions extends Record<string, any> = Record<string, any>,
+    TEvents extends EntityEventMap = EntityEventMap,
+    Ext extends Record<string, any> = {},
+  >(
+    id: string,
+    options?: TOptions,
+    extensions?: Ext & ThisType<Entity<TState, TOptions, TEvents> & Ext>
+  ): Entity<TState, TOptions, TEvents> & Ext {
+    const normalizedOptions = (options || {}) as TOptions
+    const cacheKey = this.buildHelperCacheKey('entity', id, normalizedOptions)
+
+    let base = entityCache.get(cacheKey)
+    if (!base) {
+      base = createEntityObject<TState, TOptions, TEvents>(id, this, normalizedOptions)
+      entityCache.set(cacheKey, base)
+    }
+
+    return extensions ? base.extend(extensions) : base
+  }
+
+  /**
+   * Look up any helper instance (feature, client, server) by its UUID.
+   * Returns undefined if the UUID is unknown or the instance was never created.
+   *
+   * @param uuid - The `instance.uuid` value assigned at construction time
+   * @returns The helper instance, or undefined
+   *
+   * @example
+   * ```ts
+   * const assistant = container.feature('assistant')
+   * const { uuid } = assistant
+   * // ... later ...
+   * const same = container.getHelperByUUID(uuid) // === assistant
+   * ```
+   */
+  getHelperByUUID(uuid: string): Helper | undefined {
+    return uuidCache.get(uuid)
+  }
+
   /**
    * Start the container. Emits the 'started' event and sets `state.started` to true.
    * Plugins and features can listen for this event to perform initialization.
@@ -822,6 +910,8 @@ export class Container<Features extends AvailableFeatures = AvailableFeatures, C
 }
 
 const helperCache = new Map()
+const entityCache = new Map()
+const uuidCache = new Map<string, Helper>()
 const featureIdToHelperCacheKeyMap= new Map()
 const contextMap = new WeakMap()
 

package/src/endpoint.ts

@@ -82,7 +82,7 @@ class RateLimiter {
     }
 
     // Prune timestamps outside the window
-    while (timestamps.length > 0 && timestamps[0] <= now - windowMs) {
+    while (timestamps.length > 0 && (timestamps[0] ?? 0) <= now - windowMs) {
       timestamps.shift()
     }
 

package/src/entity.ts

@@ -0,0 +1,173 @@
+import { Bus, type EventMap } from './bus.js'
+import { State, type SetStateValue } from './state.js'
+import type { Container } from './container.js'
+import uuid from 'node-uuid'
+import { z } from 'zod'
+
+/**
+ * An Entity is a lightweight, composable object with observable state, a typed event bus,
+ * and a reference to the container. Unlike Helpers, Entities are not class-based — they
+ * are plain objects created directly via `container.entity()` and extended via `.extend()`.
+ *
+ * Same id + options always returns the same underlying state/bus instance (cached).
+ *
+ * @template TState   - Shape of the entity's observable state
+ * @template TOptions - Shape of the options passed at construction
+ * @template TEvents  - Event map for the typed event bus
+ */
+export type Entity<
+  TState extends Record<string, any> = Record<string, any>,
+  TOptions extends Record<string, any> = Record<string, any>,
+  TEvents extends EventMap = EventMap,
+> = {
+  /** The id passed to container.entity() */
+  readonly id: string
+  /** Per-instance UUID */
+  readonly uuid: string
+  /** The options the entity was created with */
+  readonly options: TOptions
+  /** Observable state */
+  readonly state: State<TState>
+  /** The container this entity belongs to */
+  readonly container: Container<any>
+
+  on<E extends keyof TEvents>(event: E, listener: (...args: TEvents[E]) => void): void
+  off<E extends keyof TEvents>(event: E, listener?: (...args: TEvents[E]) => void): void
+  once<E extends keyof TEvents>(event: E, listener: (...args: TEvents[E]) => void): void
+  emit<E extends keyof TEvents>(event: E, ...args: TEvents[E]): void
+  waitFor<E extends keyof TEvents>(event: E): Promise<TEvents[E]>
+  setState(value: SetStateValue<TState>): void
+
+  /**
+   * Graft an object of functions and getters onto this entity, returning a new type-safe
+   * object. The base entity (state, events, container, options) is accessible via `this`
+   * in all grafted methods and getters. Chaining `.extend()` on the result works correctly —
+   * each layer has access to everything in the layers below it.
+   *
+   * @example
+   * ```ts
+   * const session = container.entity('session:abc', { userId: '42' })
+   * const rich = session.extend({
+   *   greet() { return `Hello user ${this.options.userId}` },
+   *   get label() { return `Session ${this.id}` },
+   * })
+   * rich.greet() // "Hello user 42"
+   * ```
+   */
+  extend<Ext extends Record<string, any>>(
+    extensions: Ext & ThisType<Entity<TState, TOptions, TEvents> & Ext>
+  ): Entity<TState, TOptions, TEvents> & Ext
+
+  /**
+   * Register a method on this entity as an AI tool with the given Zod schema.
+   * Chainable — returns `this` so you can stack multiple `.expose()` calls.
+   *
+   * @example
+   * ```ts
+   * const agent = container.entity('agent', {})
+   *   .extend({ search({ query }: { query: string }) { ... } })
+   *   .expose('search', z.object({ query: z.string() }))
+   *
+   * assistant.addTools(agent)
+   * ```
+   */
+  expose(functionName: string, schema: z.ZodType): this
+
+  /**
+   * Returns `{ schemas, handlers }` for all tools registered via `.expose()`.
+   * Compatible with `assistant.addTools()` and the standard `toTools` contract.
+   */
+  toTools(): { schemas: Record<string, z.ZodType>; handlers: Record<string, Function> }
+}
+
+/** @internal */
+export function createEntityObject<
+  TState extends Record<string, any> = Record<string, any>,
+  TOptions extends Record<string, any> = Record<string, any>,
+  TEvents extends EventMap = EventMap,
+>(
+  id: string,
+  container: Container<any>,
+  options: TOptions,
+): Entity<TState, TOptions, TEvents> {
+  const _events = new Bus<TEvents>()
+  const _state = new State<TState>()
+
+  const _exposed = new Map<string, z.ZodType>()
+
+  const entity: Entity<TState, TOptions, TEvents> = {
+    id,
+    uuid: (uuid as any).v4(),
+    options,
+    state: _state,
+    container,
+    on(event: any, listener: any) { _events.on(event, listener) },
+    off(event: any, listener?: any) { _events.off(event, listener) },
+    once(event: any, listener: any) { _events.once(event, listener) },
+    emit(event: any, ...args: any[]) { _events.emit(event, ...args) },
+    waitFor(event: any) { return _events.waitFor(event) },
+    setState(value: any) { _state.setState(value) },
+    extend(extensions: any) { return applyExtensions(this as any, extensions) },
+    expose(functionName: string, schema: z.ZodType) {
+      // Each prototype layer gets its own _exposed map (lazy-created on write)
+      if (!Object.prototype.hasOwnProperty.call(this, '_exposed')) {
+        ;(this as any)._exposed = new Map<string, z.ZodType>()
+      }
+      ;(this as any)._exposed.set(functionName, schema)
+      return this
+    },
+    toTools() {
+      const schemas: Record<string, z.ZodType> = {}
+      const handlers: Record<string, Function> = {}
+
+      // Walk the prototype chain collecting _exposed maps; shallower layers win
+      let obj: any = this
+      while (obj !== null) {
+        if (Object.prototype.hasOwnProperty.call(obj, '_exposed')) {
+          for (const [name, schema] of (obj._exposed as Map<string, z.ZodType>)) {
+            if (!(name in schemas)) {
+              schemas[name] = schema
+              handlers[name] = (args: any) => (this as any)[name](args)
+            }
+          }
+        }
+        obj = Object.getPrototypeOf(obj)
+      }
+
+      return { schemas, handlers }
+    },
+  }
+
+  ;(entity as any)._exposed = _exposed
+
+  return entity
+}
+
+/**
+ * Graft extensions onto an entity via prototype delegation.
+ *
+ * The extended object's prototype is `base`, so all base properties (state, container,
+ * on/off/emit, etc.) are reachable through `this` in any grafted method or getter.
+ * Calling `.extend()` on the result correctly uses the extended object as the new base.
+ */
+function applyExtensions<
+  TState extends Record<string, any>,
+  TOptions extends Record<string, any>,
+  TEvents extends EventMap,
+  Ext extends Record<string, any>,
+>(
+  base: Entity<TState, TOptions, TEvents>,
+  extensions: Ext,
+): Entity<TState, TOptions, TEvents> & Ext {
+  const extended = Object.create(base) as Entity<TState, TOptions, TEvents> & Ext
+
+  for (const key of Object.getOwnPropertyNames(extensions)) {
+    const descriptor = Object.getOwnPropertyDescriptor(extensions, key)!
+    Object.defineProperty(extended, key, {
+      ...descriptor,
+      configurable: true,
+    })
+  }
+
+  return extended
+}

package/src/feature.ts

@@ -23,9 +23,9 @@ export abstract class Feature<T extends FeatureState = FeatureState, K extends F
     static override eventsSchema = FeatureEventsSchema
 
     /** Self-register a Feature subclass from a static initialization block. */
-    static register: (SubClass: typeof Feature, id?: string) => typeof Feature
+    static register: (SubClass: abstract new (options: any, context: any) => Feature, id?: string) => abstract new (options: any, context: any) => Feature
 
-    get shortcut() {
+    override get shortcut() {
         return (this.constructor as any).shortcut as string
     }
 
@@ -92,7 +92,7 @@ export const features = new FeaturesRegistry()
  * ```
  */
 Feature.register = function registerFeature(
-  SubClass: typeof Feature,
+  SubClass: abstract new (options: any, context: any) => Feature,
   id?: string,
 ) {
   const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)

package/src/helper.ts

@@ -322,13 +322,17 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     return this
   }
 
-  on<Ev extends string & keyof E>(event: Ev, listener: (...args: E[Ev]) => void) {
-    this._events.on(event, listener)
+  on(event: '*', listener: (event: string, ...args: any[]) => void): this
+  on<Ev extends string & keyof E>(event: Ev, listener: (...args: E[Ev]) => void): this
+  on<Ev extends string & keyof E>(event: Ev | '*', listener: any) {
+    this._events.on(event as any, listener)
     return this
   }
 
-  off<Ev extends string & keyof E>(event: Ev, listener?: (...args: E[Ev]) => void) {
-    this._events.off(event, listener)
+  off(event: '*', listener?: (event: string, ...args: any[]) => void): this
+  off<Ev extends string & keyof E>(event: Ev, listener?: (...args: E[Ev]) => void): this
+  off<Ev extends string & keyof E>(event: Ev | '*', listener?: any) {
+    this._events.off(event as any, listener)
     return this
   }