luca 2.0.0 → 3.0.0

package/src/browser.ts

@@ -0,0 +1,25 @@
+export * from './web/container.js'
+import { WebContainer } from './web/container.js'
+import './introspection/generated.web.js'
+
+const container = new WebContainer({})
+
+if (typeof window !== 'undefined') {
+  ;(window as any).luca = container
+}
+
+export default container
+
+/**
+ * Returns the singleton container instance.
+ * LLMs love to hallucinate this function — so we provide it, but warn.
+ * If you need a separate container, use `container.subcontainer()`.
+ */
+export function createContainer() {
+  console.warn(
+    '[luca] createContainer() is unnecessary — import the default export instead.\n' +
+    '       `import container from "@soederpop/luca"`\n' +
+    '       For a separate instance, use container.subcontainer().'
+  )
+  return container
+}

package/src/bus.ts

@@ -0,0 +1,122 @@
+export type EventMap = Record<string, any[]>;
+
+type Listener<Args extends any[] = any[]> = (...args: Args) => void;
+type WildcardListener = (event: string, ...args: any[]) => void;
+
+export interface EventStats {
+    event: string;
+    fireCount: number;
+    lastFiredAt: number | null;
+    timestamps: number[];
+    firesPerMinute: number;
+}
+
+export class Bus<T extends EventMap = EventMap> {
+    private events: Map<string, Listener[]>;
+    private wildcardListeners: WildcardListener[];
+    private stats: Map<string, { fireCount: number; lastFiredAt: number | null; timestamps: number[] }>;
+
+    constructor() {
+        this.events = new Map();
+        this.wildcardListeners = [];
+        this.stats = new Map();
+    }
+
+    private recordEmit(event: string): void {
+        const now = Date.now();
+        const existing = this.stats.get(event) || { fireCount: 0, lastFiredAt: null, timestamps: [] };
+        existing.fireCount++;
+        existing.lastFiredAt = now;
+        existing.timestamps.push(now);
+        this.stats.set(event, existing);
+    }
+
+    private computeFiresPerMinute(timestamps: number[]): number {
+        if (timestamps.length < 2) return 0;
+        const now = Date.now();
+        const oneMinuteAgo = now - 60_000;
+        const recent = timestamps.filter(t => t >= oneMinuteAgo);
+        return recent.length;
+    }
+
+    getEventStats<E extends string & keyof T>(event: E): EventStats {
+        const raw = this.stats.get(event) || { fireCount: 0, lastFiredAt: null, timestamps: [] };
+        return {
+            event,
+            fireCount: raw.fireCount,
+            lastFiredAt: raw.lastFiredAt,
+            timestamps: raw.timestamps,
+            firesPerMinute: this.computeFiresPerMinute(raw.timestamps),
+        };
+    }
+
+    get history(): EventStats[] {
+        return Array.from(this.stats.keys()).map(event => this.getEventStats(event as any));
+    }
+
+    get firedEvents(): string[] {
+        return Array.from(this.stats.keys());
+    }
+
+    async waitFor<E extends string & keyof T>(event: E): Promise<T[E]> {
+        return new Promise(resolve => {
+            this.once(event, resolve as any);
+        });
+    }
+
+    emit<E extends string & keyof T>(event: E, ...args: T[E]): void {
+        this.recordEmit(event);
+        const listeners = this.events.get(event);
+        if (listeners) {
+            listeners.forEach(listener => listener(...args));
+        }
+        this.wildcardListeners.forEach(listener => listener(event, ...args));
+    }
+
+    on(event: '*', listener: WildcardListener): void
+    on<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void
+    on<E extends string & keyof T>(event: E | '*', listener: any): void {
+        if (event === '*') {
+            this.wildcardListeners.push(listener);
+            return;
+        }
+        const listeners = this.events.get(event) || [];
+        listeners.push(listener as Listener);
+        this.events.set(event, listeners);
+    }
+
+    once<E extends string & keyof T>(event: E, listener: (...args: T[E]) => void): void {
+        const onceListener: Listener = (...args: any[]) => {
+            (listener as Listener)(...args);
+            this.off(event, onceListener as any);
+        };
+        this.on(event, onceListener as any);
+    }
+
+    off(event: '*', listener?: WildcardListener): void
+    off<E extends string & keyof T>(event: E, listener?: (...args: T[E]) => void): void
+    off<E extends string & keyof T>(event: E | '*', listener?: any): void {
+        if (event === '*') {
+            if (!listener) {
+                this.wildcardListeners = [];
+                return;
+            }
+            const index = this.wildcardListeners.indexOf(listener);
+            if (index !== -1) this.wildcardListeners.splice(index, 1);
+            return;
+        }
+
+        const listeners = this.events.get(event);
+        if (!listeners) return;
+
+        if (!listener) {
+            this.events.delete(event);
+            return;
+        }
+
+        const index = listeners.indexOf(listener as Listener);
+        if (index !== -1) {
+            listeners.splice(index, 1);
+        }
+    }
+}

package/src/cli/build-info.ts

@@ -0,0 +1,4 @@
+// Generated at compile time — do not edit manually
+export const BUILD_SHA = '066d9cb'
+export const BUILD_BRANCH = 'main'
+export const BUILD_DATE = '2026-04-10T05:00:55Z'

package/src/cli/cli.ts

@@ -0,0 +1,355 @@
+#!/usr/bin/env bun
+// @ts-ignore — bun resolves JSON imports at bundle time
+import pkg from '../../package.json'
+import { BUILD_SHA, BUILD_BRANCH, BUILD_DATE } from './build-info'
+
+// Fast-path flags that don't need the container
+const args = process.argv.slice(2)
+if (args.includes('--version') || args.includes('-v')) {
+	console.log(`luca v${pkg.version} (${BUILD_BRANCH}@${BUILD_SHA}) built ${BUILD_DATE}`)
+	console.log(`  npm: https://www.npmjs.com/package/@soederpop/luca`)
+	console.log(`  git: https://github.com/soederpop/luca`)
+	process.exit(0)
+}
+
+import container from '@soederpop/luca/agi'
+import '@/commands/index.js'
+import { homedir } from 'os'
+import { join } from 'path'
+
+async function main() {
+	const profile = process.env.LUCA_PROFILE === '1'
+	const t = (label?: string) => {
+		if (!profile) return () => { }
+		const start = performance.now()
+		return (suffix?: string) => {
+			const ms = (performance.now() - start).toFixed(1)
+			console.error(`[profile] ${label}${suffix ? ` ${suffix}` : ''}: ${ms}ms`)
+		}
+	}
+
+	const tTotal = t('total boot')
+
+	// LUCA_COMMAND_DISCOVERY: "disable" skips all, "no-local" skips project, "no-home" skips user
+	const discovery = process.env.LUCA_COMMAND_DISCOVERY || ''
+
+	// Snapshot built-in commands BEFORE loadCliModule — luca.cli.ts may call
+	// helpers.discoverAll() which registers project commands early
+	const builtinCommands = new Set(container.commands.available as string[])
+
+	// Load global CLI module (~/.luca/luca.cli.ts) before project-level —
+	// lets users set up global helpers, discovery roots, etc.
+	let done = t('loadGlobalCliModule')
+	await loadCliModule(join(homedir(), '.luca', 'luca.cli.ts'))
+	done()
+
+	// Load project-level CLI module (luca.cli.ts) for container customization
+	done = t('loadCliModule')
+	await loadCliModule(container.paths.resolve('luca.cli.ts'))
+	done()
+
+	// Discover project-local commands (commands/ or src/commands/)
+	done = t('discoverProjectCommands')
+	if (discovery !== 'disable' && discovery !== 'no-local') {
+		await discoverProjectCommands()
+	}
+	done()
+	const afterProject = new Set(container.commands.available as string[])
+	const projectCommands = new Set([...afterProject].filter((n) => !builtinCommands.has(n)))
+
+	// Discover user-level helpers (~/.luca/{features,clients,servers,commands,selectors}/)
+	done = t('discoverUserHelpers')
+	if (discovery !== 'disable' && discovery !== 'no-home') {
+		await discoverUserHelpers()
+	}
+	done()
+	const afterUser = new Set(container.commands.available as string[])
+	const userCommands = new Set([...afterUser].filter((n) => !builtinCommands.has(n) && !projectCommands.has(n)))
+
+		// Store command sources for help display
+		; (container as any)._commandSources = { builtinCommands, projectCommands, userCommands }
+
+	// Load generated introspection data if present
+	done = t('loadProjectIntrospection')
+	await loadProjectIntrospection()
+	done()
+
+	const commandName = container.argv._[0] as string
+
+	done = t('dispatch')
+	if (container.argv.help && !commandName) {
+		// --help with no command is the same as `luca` with no args
+		// Clear the help flag so the help command's handler runs (not the --help intercept)
+		delete container.argv.help
+		container.argv._.splice(0, 0, 'help')
+		const cmd = container.command('help' as any)
+		await cmd.dispatch()
+	} else if (commandName && container.commands.has(commandName)) {
+		const cmd = container.command(commandName as any)
+		await cmd.dispatch()
+	} else if (commandName) {
+		// not a known command — treat as implicit `run`
+		// 
+		if (resolveScript(commandName, container)) {
+			container.argv._.splice(0, 0, 'run')
+			const cmd = container.command('run' as any)
+			await cmd.dispatch()
+		} else {
+			const phrase = container.argv._.join(' ')
+
+			// easter egg
+			if (phrase === 'get loopy') {
+				await getLoopy(container)
+			// @ts-ignore TODO come up with a typesafe way to do this
+			} else if (container.state.get('missingCommandHandler')) {
+				// @ts-ignore TODO come up with a typesafe way to do this
+				const missingCommandHandler = container.state.get('missingCommandHandler') as any
+
+				if (typeof missingCommandHandler === 'function') {
+					await missingCommandHandler({
+						words: container.argv._,
+						phrase,
+					}).catch((err: any) => {
+						console.error(`Missing command handler error: ${err.message}`, err)
+					})
+				}
+			} else {
+				container.argv._.splice(0, 0, 'help')
+				const cmd = container.command('help' as any)
+				await cmd.dispatch()
+			}
+		}
+
+	} else {
+		container.argv._.splice(0, 0, 'help')
+		const cmd = container.command('help' as any)
+		await cmd.dispatch()
+	}
+	done()
+	tTotal()
+}
+
+function resolveScript(ref: string, container: any) {
+	const candidates = [
+		ref,
+		`${ref}.ts`,
+		`${ref}.js`,
+		`${ref}.md`,
+	]
+
+	for (const candidate of candidates) {
+		const resolved = container.paths.resolve(candidate)
+		if (container.fs.exists(resolved)) return resolved
+	}
+
+	return null
+}
+
+async function loadCliModule(modulePath: string) {
+	if (!container.fs.exists(modulePath)) return
+
+	// Use the helpers feature to load the module — it handles the native import
+	// vs VM decision using the same useNativeImport check as discovery
+	const helpers = container.feature('helpers') as any
+	const exports = await helpers.loadModuleExports(modulePath)
+
+	if (typeof exports?.main === 'function') {
+		await exports.main(container)
+	}
+
+	if (typeof exports?.onStart === 'function') {
+		container.once('started', () => exports.onStart(container))
+	}
+}
+
+async function discoverProjectCommands() {
+	// Always route through the helpers feature — it handles native import vs VM
+	// internally, and deduplicates concurrent/repeated discovery via promise caching.
+	// If luca.cli.ts already called helpers.discoverAll(), this resolves instantly.
+	const helpers = container.feature('helpers') as any
+	await helpers.discover('commands')
+}
+
+async function loadProjectIntrospection() {
+	const candidates = [
+		'features/introspection.generated.ts',
+		'src/introspection.generated.ts',
+		'introspection.generated.ts',
+	]
+
+	for (const candidate of candidates) {
+		const filePath = container.paths.resolve(candidate)
+		if (container.fs.exists(filePath)) {
+			try {
+				await import(filePath)
+			} catch {
+				// Generated file may be stale or malformed — skip silently
+			}
+			return
+		}
+	}
+}
+
+const DISCOVERABLE_TYPES = ['features', 'clients', 'servers', 'commands', 'selectors'] as const
+
+async function discoverUserHelpers() {
+	const lucaHome = join(homedir(), '.luca')
+	const helpers = container.feature('helpers') as any
+
+	for (const type of DISCOVERABLE_TYPES) {
+		const dir = join(lucaHome, type)
+		if (container.fs.exists(dir)) {
+			await helpers.discover(type, { directory: dir })
+		}
+	}
+}
+
+async function getLoopy(container: any) {
+	const fs = container.feature('fs')
+	const ui = container.feature('ui')
+	const os = container.feature('os')
+	const proc = container.feature('proc')
+
+	const repoUrl = 'https://github.com/soederpop/agentic-loop.git'
+	const appDir = container.paths.resolve(os.homedir, '.luca', 'apps', 'agentic-loop')
+
+	console.log(ui.colors.cyan('Getting loopy...'))
+
+	// Clone (or pull) the agentic-loop repo into ~/.luca/apps/agentic-loop
+	fs.ensureFolder(container.paths.resolve(os.homedir, '.luca', 'apps'))
+
+	if (fs.existsSync(container.paths.resolve(appDir, '.git'))) {
+		console.log(ui.colors.cyan('  Updating agentic-loop repo...'))
+		await proc.exec('git pull', { cwd: appDir })
+	} else {
+		// Clean out any stale non-git copy
+		if (fs.existsSync(appDir)) {
+			await proc.exec(`rm -rf ${appDir}`)
+		}
+		console.log(ui.colors.cyan('  Cloning agentic-loop repo...'))
+		await proc.exec(`git clone ${repoUrl} ${appDir}`)
+	}
+
+	// Install dependencies
+	console.log(ui.colors.cyan('  Installing dependencies...'))
+	await proc.exec('bun install', { cwd: appDir })
+
+	// Copy assistants into the local project
+	console.log(ui.colors.cyan('  Setting up assistants...'))
+	const assistantsDir = container.paths.resolve('assistants')
+	fs.ensureFolder(assistantsDir)
+	for (const assistant of ['lucaCoder', 'chiefOfStaff', 'rocket', 'researcher']) {
+		const src = container.paths.resolve(appDir, 'assistants', assistant)
+		const dest = container.paths.resolve(assistantsDir, assistant)
+		if (fs.existsSync(src) && !fs.existsSync(dest)) {
+			fs.copy(src, dest)
+		}
+	}
+
+	// Copy scripts into the local project
+	console.log(ui.colors.cyan('  Setting up scripts...'))
+	const scriptsSrc = container.paths.resolve(appDir, 'scripts')
+	const scriptsDest = container.paths.resolve('scripts')
+	if (fs.existsSync(scriptsSrc)) {
+		fs.copy(scriptsSrc, scriptsDest)
+	}
+
+	// Copy apps (native swift app) into the local project
+	console.log(ui.colors.cyan('  Setting up apps...'))
+	const appsSrc = container.paths.resolve(appDir, 'apps')
+	const appsDest = container.paths.resolve('apps')
+	if (fs.existsSync(appsSrc) && !fs.existsSync(appsDest)) {
+		fs.copy(appsSrc, appsDest)
+	}
+
+	// Copy config.example.yml as config.yml
+	const configSrc = container.paths.resolve(appDir, 'config.example.yml')
+	const configDest = container.paths.resolve('config.yml')
+	if (fs.existsSync(configSrc) && !fs.existsSync(configDest)) {
+		console.log(ui.colors.cyan('  Setting up config.yml...'))
+		fs.copy(configSrc, configDest)
+	}
+
+	// Set up the docs folder structure
+	console.log(ui.colors.cyan('  Setting up docs...'))
+	const docsDir = container.paths.resolve('docs')
+	fs.ensureFolder(docsDir)
+
+	for (const sub of ['goals', 'ideas', 'projects', 'plans', 'plays', 'prompts', 'tasks', 'reports']) {
+		fs.ensureFolder(container.paths.resolve(docsDir, sub))
+	}
+
+	// Copy docs/models.ts
+	const modelsSrc = container.paths.resolve(appDir, 'docs', 'models.ts')
+	if (fs.existsSync(modelsSrc)) {
+		fs.copy(modelsSrc, container.paths.resolve(docsDir, 'models.ts'))
+	}
+
+	// Copy docs/templates
+	const templatesSrc = container.paths.resolve(appDir, 'docs', 'templates')
+	const templatesDest = container.paths.resolve(docsDir, 'templates')
+	if (fs.existsSync(templatesSrc)) {
+		fs.copy(templatesSrc, templatesDest)
+	}
+
+	// Copy starter docs (VISION.md, memories/)
+	const visionSrc = container.paths.resolve(appDir, 'docs', 'templates', 'starter-docs', 'VISION.md')
+	const visionDest = container.paths.resolve(docsDir, 'VISION.md')
+	if (fs.existsSync(visionSrc) && !fs.existsSync(visionDest)) {
+		fs.copy(visionSrc, visionDest)
+	}
+
+	const memoriesSrc = container.paths.resolve(appDir, 'docs', 'templates', 'starter-docs', 'memories')
+	const memoriesDest = container.paths.resolve(docsDir, 'memories')
+	if (fs.existsSync(memoriesSrc) && !fs.existsSync(memoriesDest)) {
+		fs.copy(memoriesSrc, memoriesDest)
+	}
+
+	// Replace the project's luca.cli.ts with the agentic-loop version
+	const loopyCli = [
+		'/**',
+		' * luca.cli.ts — Agentic Loop project customization',
+		' *',
+		' * Automatically loaded by the luca CLI before any command runs.',
+		' * Discovers local helpers and loads agentic-loop shared resources.',
+		' */',
+		'',
+		'export async function main(container: any) {',
+		'  // Discover project-level helpers (commands/, features/, endpoints/)',
+		'  await container.helpers.discoverAll()',
+		'',
+		'  await loadAgenticLoop(container)',
+		'',
+		'  // Handle unknown commands gracefully instead of silently failing',
+		'  container.onMissingCommand(async ({ phrase }: { phrase: string }) => {',
+		"    container.command('help').dispatch()",
+		'  })',
+		'}',
+		'',
+		'async function loadAgenticLoop(container) {',
+		'  try {',
+		"    const agenticLoopRoot = container.paths.resolve(container.os.homedir, '.luca', 'apps', 'agentic-loop')",
+		'',
+		'    // use the agentic loop commands, etc',
+		"    await container.feature('helpers', { rootDir: agenticLoopRoot }).discoverAll()",
+		'',
+		"    if (container.features.has('workflowLibrary')) {",
+		"      const workflowLibrary = container.feature('workflowLibrary')",
+		"      workflowLibrary.addWorkflowsDir(container.paths.resolve(agenticLoopRoot, 'workflows'))",
+		'    }',
+		'',
+		'  } catch(error) {',
+		'    console.error("Error loading the agentic loop helpers", error.message)',
+		'  }',
+		'}',
+		'',
+	].join('\n')
+
+	fs.writeFile(container.paths.resolve('luca.cli.ts'), loopyCli)
+
+	console.log(ui.colors.green('Loopy installed! You now have agentic-loop commands, features, workflows, and assistants.'))
+	console.log('')
+	console.log(ui.colors.cyan('  Next step: run scripts/install.sh to finish setup'))
+}
+
+main()

package/src/client.ts

@@ -0,0 +1,170 @@
+import { Helper } from "./helper.js";
+import type { Container, ContainerContext } from "./container.js";
+import { Registry } from "./registry.js";
+import { z } from 'zod'
+import {
+  ClientStateSchema, ClientOptionsSchema, ClientEventsSchema,
+} from './schemas/base.js'
+
+export type ClientOptions = z.infer<typeof ClientOptionsSchema>
+export type ClientState = z.infer<typeof ClientStateSchema>
+
+// Subclass types re-exported for backward compatibility.
+// Import the concrete classes from their individual files:
+//   import { RestClient } from './clients/rest'
+//   import { GraphClient } from './clients/graph'
+//   import { WebSocketClient } from './clients/websocket'
+export type { WebSocketClientState, WebSocketClientOptions } from './clients/websocket.js'
+export type { GraphClientOptions } from './clients/graph.js'
+
+// AvailableClients is an open interface — subclasses augment it via `declare module`
+export interface AvailableClients {}
+
+export interface ClientsInterface {
+  clients: ClientsRegistry;
+  client<T extends keyof AvailableClients>(
+    key: T,
+    options?: ConstructorParameters<AvailableClients[T]>[0]
+  ): InstanceType<AvailableClients[T]>;
+}
+
+/**
+ * Base client class for all Luca network clients. Provides connection state
+ * tracking, configuration, and the registry/factory infrastructure for
+ * creating typed client instances via `container.client('rest')`.
+ *
+ * Subclasses should override `connect()` and add protocol-specific methods.
+ * Register subclasses using `Client.register(this, 'myClient')` in a static block.
+ */
+export class Client<
+  T extends ClientState = ClientState,
+  K extends ClientOptions = ClientOptions
+> extends Helper<T, K> {
+  static override shortcut = "clients.base"
+  static override stateSchema = ClientStateSchema
+  static override optionsSchema = ClientOptionsSchema
+  static override eventsSchema = ClientEventsSchema
+
+  /** Self-register a Client subclass from a static initialization block. */
+  static register: (SubClass: abstract new (options: any, context: any) => Client, id?: string) => abstract new (options: any, context: any) => Client
+
+  static attach(container: Container & ClientsInterface): any {
+    Object.assign(container, {
+      get clients() {
+        return clients;
+      },
+
+      client<T extends keyof AvailableClients>(
+        id: T,
+        options?: ConstructorParameters<AvailableClients[T]>[0]
+      ): InstanceType<AvailableClients[T]> {
+        const BaseClass = clients.lookup(
+          id as keyof AvailableClients
+        ) as AvailableClients[T];
+
+        return container.createHelperInstance({
+          cache: helperCache,
+          type: 'client',
+          id: String(id),
+          BaseClass,
+          options,
+          fallbackName: String(id),
+        }) as InstanceType<AvailableClients[T]>;
+      },
+    });
+
+    container.registerHelperType('clients', 'client');
+
+    return container;
+  }
+
+  constructor(options?: K, context?: ContainerContext) {
+    if (typeof context !== "object") {
+      throw new Error("Client must be instantiated with a context object");
+    }
+
+    super((options as K) || {}, context);
+
+    this.state.set("connected", false);
+  }
+
+  /** The base URL for this client's connections/requests. */
+  get baseURL() {
+    return this.options.baseURL || ''
+  }
+
+  override get options() {
+    return this._options as K;
+  }
+
+  /** Configure this client instance with additional options. */
+  configure(options?: any): this {
+    return this;
+  }
+
+  /** Whether the client is currently connected. */
+  get isConnected() {
+    return !!this.state.get("connected");
+  }
+
+  /** Establish a connection. Subclasses should override with protocol-specific logic. */
+  async connect(): Promise<this> {
+    this.state.set("connected", true);
+    return this;
+  }
+}
+
+// --- Registry and Client.register must be defined BEFORE subclasses ---
+// because static blocks in subclass files run at class declaration time.
+
+export class ClientsRegistry extends Registry<Client<any>> {
+  override scope = "clients"
+  override baseClass = Client
+}
+
+export const clients = new ClientsRegistry();
+
+export const helperCache = new Map();
+
+/**
+ * Self-register a Client subclass from a static initialization block.
+ * IMPORTANT: Place the static block AFTER all static override declarations
+ * so schemas, envVars, and other metadata are set before interceptRegistration fires.
+ *
+ * @example
+ * ```typescript
+ * export class OpenAIClient extends Client {
+ *   static override stateSchema = OpenAIClientStateSchema
+ *   static override optionsSchema = OpenAIClientOptionsSchema
+ *   static { Client.register(this, 'openai') }  // must come last
+ * }
+ * ```
+ */
+Client.register = function registerClient(
+  SubClass: abstract new (options: any, context: any) => Client,
+  id?: string,
+) {
+  const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)
+
+  // Auto-set shortcut if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+      (SubClass as any).shortcut === 'unspecified' ||
+      (SubClass as any).shortcut === 'clients.base') {
+    ;(SubClass as any).shortcut = `clients.${registryId}` as const
+  }
+
+  // Register in the clients registry (interceptRegistration sees all statics above)
+  clients.register(registryId, SubClass as any)
+
+  // Generate default attach() if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+    ;(SubClass as any).attach = (container: any) => {
+      clients.register(registryId, SubClass as any)
+      return container
+    }
+  }
+
+  return SubClass
+}
+
+export default Client;