@soederpop/luca 0.1.2 → 0.2.1

package/dist/web/features/speech.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+import { type ContainerContext } from "../container.js";
+export declare const SpeechOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    voice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SpeechStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    defaultVoice: z.ZodString;
+    voices: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+}, z.core.$loose>;
+export type SpeechOptions = z.infer<typeof SpeechOptionsSchema>;
+export type SpeechState = z.infer<typeof SpeechStateSchema>;
+type Voice = {
+    voiceURI: string;
+    name: string;
+    lang: string;
+    localService: boolean;
+    default: boolean;
+};
+/**
+ * Text-to-speech synthesis using the Web Speech API (SpeechSynthesis).
+ *
+ * Wraps the browser's built-in speech synthesis, providing voice selection,
+ * queue management, and state tracking. Voices are discovered on init and
+ * exposed via state for UI binding.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const speech = container.feature('speech')
+ * speech.say('Hello from the browser!')
+ *
+ * // Choose a specific voice
+ * const speech = container.feature('speech', { voice: 'Google UK English Female' })
+ * speech.say('Cheerio!')
+ * ```
+ */
+export declare class Speech<T extends SpeechState = SpeechState, K extends SpeechOptions = SpeechOptions> extends Feature<T, K> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        defaultVoice: z.ZodString;
+        voices: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        voice: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static shortcut: "features.speech";
+    constructor(options: K, context: ContainerContext);
+    /** Returns the array of available speech synthesis voices. */
+    get voices(): never[] | NonNullable<T["voices"]>;
+    /** Returns the Voice object matching the currently selected default voice name. */
+    get defaultVoice(): any;
+    loadVoices(): void;
+    setDefaultVoice(name: string): void;
+    cancel(): this;
+    say(text: string, options?: {
+        voice?: Voice;
+    }): void;
+}
+export default Speech;
+//# sourceMappingURL=speech.d.ts.map

package/dist/web/features/speech.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.d.ts","sourceRoot":"","sources":["../../../src/web/features/speech.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;;iBAE9B,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;iBAG5B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC/D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D,KAAK,KAAK,GAAG;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,MAAM,CACjB,CAAC,SAAS,WAAW,GAAG,WAAW,EACnC,CAAC,SAAS,aAAa,GAAG,aAAa,CACvC,SAAQ,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAErB,OAAgB,WAAW;;;;sBAAoB;IAC/C,OAAgB,aAAa;;;;;;sBAAsB;IACnD,OAAgB,QAAQ,EAAG,iBAAiB,CAAS;gBAIzC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB;IAUjD,8DAA8D;IAC9D,IAAI,MAAM,uCAET;IAED,mFAAmF;IACnF,IAAI,YAAY,QAEf;IAED,UAAU;IAUV,eAAe,CAAC,IAAI,EAAE,MAAM;IAK5B,MAAM;IAKN,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAO;CAMlD;AAED,eAAe,MAAM,CAAC"}

package/dist/web/features/vault.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const WebVaultStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    secret: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const WebVaultOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WebVaultState = z.infer<typeof WebVaultStateSchema>;
+export type WebVaultOptions = z.infer<typeof WebVaultOptionsSchema>;
+/**
+ * AES-256-GCM encryption and decryption for the browser using the Web Crypto API.
+ *
+ * Generates or accepts a secret key and provides `encrypt()` / `decrypt()` methods
+ * that work entirely client-side. Keys are stored as base64-encoded state so they
+ * can persist across sessions when needed.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const vault = container.feature('vault')
+ * const encrypted = await vault.encrypt('secret data')
+ * const decrypted = await vault.decrypt(encrypted)
+ * console.log(decrypted) // 'secret data'
+ * ```
+ */
+export declare class WebVault extends Feature<WebVaultState, WebVaultOptions> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    static shortcut: "features.vault";
+    secret({ refresh, set }?: {
+        refresh?: boolean | undefined;
+        set?: boolean | undefined;
+    }): Promise<ArrayBuffer>;
+    decrypt(payload: string): Promise<string>;
+    encrypt(payload: string): Promise<string>;
+    utils: {
+        arrayToString: typeof arrayBufferToBase64;
+        stringToArray: typeof base64ToArrayBuffer;
+        uintToString: typeof uint8ArrayToBase64;
+    };
+}
+export default WebVault;
+declare function arrayBufferToBase64(buffer: ArrayBuffer): string;
+declare function uint8ArrayToBase64(u: Uint8Array): string;
+declare function base64ToArrayBuffer(base64: string): ArrayBuffer;
+//# sourceMappingURL=vault.d.ts.map

package/dist/web/features/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/web/features/vault.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC,eAAO,MAAM,mBAAmB;;;iBAE9B,CAAA;AAEF,eAAO,MAAM,qBAAqB;;;;;;iBAEhC,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,QAAS,SAAQ,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC;IACnE,OAAgB,WAAW;;;sBAAsB;IACjD,OAAgB,aAAa;;;;;;sBAAwB;IACrD,OAAgB,QAAQ,EAAG,gBAAgB,CAAS;IAI9C,MAAM,CAAC,EAAE,OAAe,EAAE,GAAU,EAAE;;;KAAK,GAAI,OAAO,CAAC,WAAW,CAAC;IAmBnE,OAAO,CAAC,OAAO,EAAE,MAAM;IAUvB,OAAO,CAAC,OAAO,EAAE,MAAM;IAW7B,KAAK;;;;MAIJ;CACF;AAED,eAAe,QAAQ,CAAA;AAiDvB,iBAAS,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAmBxD;AAED,iBAAS,kBAAkB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAkBjD;AAED,iBAAS,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAGxD"}

package/dist/web/features/vm.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { Feature } from "../feature.js";
+export declare const VMStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const VMOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    context: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+export type VMState = z.infer<typeof VMStateSchema>;
+export type VMOptions = z.infer<typeof VMOptionsSchema>;
+/**
+ * Sandboxed JavaScript execution environment for the browser.
+ *
+ * Automatically injects the container's context object into the global scope,
+ * so evaluated code can use anything provided by the container. Useful for
+ * live code playgrounds, plugin systems, and dynamic script evaluation.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const vm = container.feature('vm')
+ * const result = vm.run('1 + 2 + 3') // 6
+ * const greeting = vm.run('container.uuid') // accesses container globals
+ * ```
+ */
+export declare class VM<T extends VMState = VMState, K extends VMOptions = VMOptions> extends Feature<T, K> {
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        context: z.ZodOptional<z.ZodAny>;
+    }, z.core.$strip>;
+    static shortcut: "features.vm";
+    createScript(code: string): import("../shims/isomorphic-vm").VMScript;
+    createContext(ctx?: any): import("../shims/isomorphic-vm").VMContext;
+    run(code: string, ctx?: any, options?: any): Promise<any>;
+}
+export default VM;
+//# sourceMappingURL=vm.d.ts.map

package/dist/web/features/vm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vm.d.ts","sourceRoot":"","sources":["../../../src/web/features/vm.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,eAAO,MAAM,aAAa;;iBAAgC,CAAA;AAE1D,eAAO,MAAM,eAAe;;;;;;iBAE1B,CAAA;AAEF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AACnD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEvD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,EAAE,CACb,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3B,CAAC,SAAS,SAAS,GAAG,SAAS,CAC/B,SAAQ,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAErB,OAAgB,WAAW;;sBAAgB;IAC3C,OAAgB,aAAa;;;;;;sBAAkB;IAC/C,OAAgB,QAAQ,EAAG,aAAa,CAAS;IAIjD,YAAY,CAAC,IAAI,EAAE,MAAM;IAIzB,aAAa,CAAC,GAAG,GAAE,GAAQ;IAOrB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,GAAQ,EAAE,OAAO,GAAG,GAAQ;CA4B1D;AAED,eAAe,EAAE,CAAC"}

package/dist/web/features/voice-recognition.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { Feature } from "../../feature.js";
+import { type ContainerContext } from '../container.js';
+export declare const VoiceRecognitionOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+    continuous: z.ZodOptional<z.ZodBoolean>;
+    autoListen: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const VoiceRecognitionStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    listening: z.ZodBoolean;
+    transcript: z.ZodString;
+}, z.core.$loose>;
+export type VoiceRecognitionOptions = z.infer<typeof VoiceRecognitionOptionsSchema>;
+export type VoiceRecognitionState = z.infer<typeof VoiceRecognitionStateSchema>;
+export declare const VoiceRecognitionEventsSchema: z.ZodObject<{
+    stateChange: z.ZodTuple<[z.ZodAny], null>;
+    enabled: z.ZodTuple<[], null>;
+    result: z.ZodTuple<[z.ZodObject<{
+        finalTranscript: z.ZodString;
+        interimTranscript: z.ZodString;
+    }, z.core.$strip>], null>;
+    error: z.ZodTuple<[z.ZodString], null>;
+    end: z.ZodTuple<[], null>;
+    start: z.ZodTuple<[], null>;
+    stop: z.ZodTuple<[], null>;
+    abort: z.ZodTuple<[], null>;
+}, z.core.$strip>;
+/**
+ * Speech-to-text recognition using the Web Speech API (SpeechRecognition).
+ *
+ * Wraps the browser's built-in speech recognition, supporting continuous
+ * listening, interim results, and language selection. Recognized text is
+ * accumulated in state and emitted as events for real-time transcription UIs.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const voice = container.feature('voice', { continuous: true, autoListen: true })
+ *
+ * voice.on('transcript', ({ text }) => {
+ *   console.log('Heard:', text)
+ * })
+ *
+ * // Or start manually
+ * voice.start()
+ * ```
+ */
+export declare class VoiceRecognition<T extends VoiceRecognitionState = VoiceRecognitionState, K extends VoiceRecognitionOptions = VoiceRecognitionOptions> extends Feature<T, K> {
+    private recognition;
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        listening: z.ZodBoolean;
+        transcript: z.ZodString;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        language: z.ZodOptional<z.ZodString>;
+        continuous: z.ZodOptional<z.ZodBoolean>;
+        autoListen: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    static eventsSchema: z.ZodObject<{
+        stateChange: z.ZodTuple<[z.ZodAny], null>;
+        enabled: z.ZodTuple<[], null>;
+        result: z.ZodTuple<[z.ZodObject<{
+            finalTranscript: z.ZodString;
+            interimTranscript: z.ZodString;
+        }, z.core.$strip>], null>;
+        error: z.ZodTuple<[z.ZodString], null>;
+        end: z.ZodTuple<[], null>;
+        start: z.ZodTuple<[], null>;
+        stop: z.ZodTuple<[], null>;
+        abort: z.ZodTuple<[], null>;
+    }, z.core.$strip>;
+    static shortcut: "features.voice";
+    constructor(options: K, context: ContainerContext);
+    /** Whether the speech recognizer is currently listening for audio input. */
+    get listening(): boolean;
+    /** Returns the accumulated final transcript text from recognition results. */
+    get transcript(): "" | T["transcript"];
+    whenFinished(): Promise<"" | T["transcript"]>;
+    start(): void;
+    stop(): void;
+    abort(): void;
+    clearTranscript(): void;
+}
+export default VoiceRecognition;
+//# sourceMappingURL=voice-recognition.d.ts.map

package/dist/web/features/voice-recognition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-recognition.d.ts","sourceRoot":"","sources":["../../../src/web/features/voice-recognition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAEvD,eAAO,MAAM,6BAA6B;;;;;;;;iBAIxC,CAAA;AAEF,eAAO,MAAM,2BAA2B;;;;iBAGtC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAA;AACnF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAE/E,eAAO,MAAM,4BAA4B;;;;;;;;;;;;iBAYH,CAAA;AAEtC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB,CAAC,CAAC,SAAS,qBAAqB,GAAG,qBAAqB,EAAE,CAAC,SAAS,uBAAuB,GAAG,uBAAuB,CAAE,SAAQ,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvK,OAAO,CAAC,WAAW,CAAkC;IAErD,OAAgB,WAAW;;;;sBAA8B;IACzD,OAAgB,aAAa;;;;;;;;sBAAgC;IAC7D,OAAgB,YAAY;;;;;;;;;;;;sBAA+B;IAC3D,OAAgB,QAAQ,EAAG,gBAAgB,CAAS;gBAIxC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB;IA8CjD,4EAA4E;IAC5E,IAAI,SAAS,YAEZ;IAED,8EAA8E;IAC9E,IAAI,UAAU,yBAEb;IAEK,YAAY;IAQlB,KAAK;IAUL,IAAI;IAQJ,KAAK;IAQL,eAAe;CAGhB;AAED,eAAe,gBAAgB,CAAC"}

package/dist/web/shims/isomorphic-vm.d.ts

@@ -0,0 +1,22 @@
+export interface VMContext {
+    [name: string]: any;
+}
+export interface VMScript {
+    new (code: string): VMScript;
+    runInContext(context: VMContext): any;
+    runInNewContext(context?: any): any;
+    runInThisContext(): any;
+}
+export interface VM {
+    Script: VMScript;
+    createContext(context?: any): VMContext;
+    isContext(context: any): context is VMContext;
+    runInContext(code: string, context: VMContext): any;
+    runInDebugContext(code: string): any;
+    runInNewContext(code: string, context?: any): any;
+    runInThisContext(code: string): any;
+}
+export declare const shim: VM;
+declare const _default: VM;
+export default _default;
+//# sourceMappingURL=isomorphic-vm.d.ts.map

package/dist/web/shims/isomorphic-vm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isomorphic-vm.d.ts","sourceRoot":"","sources":["../../../src/web/shims/isomorphic-vm.ts"],"names":[],"mappings":"AAqHA,MAAM,WAAW,SAAS;IACxB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,IAAI,EAAE,MAAM,GAAI,QAAQ,CAAC;IAC9B,YAAY,CAAC,OAAO,EAAE,SAAS,GAAI,GAAG,CAAC;IACvC,eAAe,CAAC,OAAO,CAAC,EAAE,GAAG,GAAI,GAAG,CAAC;IACrC,gBAAgB,IAAK,GAAG,CAAC;CAC1B;AAED,MAAM,WAAW,EAAE;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,aAAa,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,SAAS,CAAC;IACxC,SAAS,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,IAAI,SAAS,CAAC;IAC9C,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,GAAG,CAAC;IACpD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC;IACrC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC;IAClD,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC;CACrC;AAED,eAAO,MAAM,IAAI,EAAE,EAQlB,CAAC;wBAEqB,EAAE;AAAzB,wBAAyB"}

package/docs/apis/features/agi/assistant.md

@@ -369,6 +369,7 @@ const answer = await researcher.ask('Find all usages of container.feature("fs")'
 | `effectiveSystemPrompt` | `string` | The system prompt with all extensions appended. This is the value passed to the conversation. |
 | `tools` | `Record<string, ConversationTool>` | The tools registered with this assistant. |
 | `meta` | `Record<string, any>` | Parsed YAML frontmatter from CORE.md, or empty object if none. |
+| `effectiveOptions` | `AssistantOptions & Record<string, any>` | Merged options where CORE.md frontmatter provides defaults and constructor options take precedence. Prefer this over `this.options` anywhere model parameters or runtime config is consumed. |
 | `paths` | `any` | Provides a helper for creating paths off of the assistant's base folder |
 | `assistantName` | `string` | The assistant name derived from the folder basename. |
 | `cwdHash` | `string` | An 8-char hash of the container cwd for per-project thread isolation. |

package/docs/apis/features/agi/assistants-manager.md

@@ -10,9 +10,48 @@ container.feature('assistantsManager')
 
 ## Methods
 
-### discover
+### intercept
+
+Registers a pipeline interceptor that is applied to every assistant created by this manager. Interceptors are applied at the given interception point on each assistant at creation time. This mirrors the per-assistant `assistant.intercept(point, fn)` API, but scopes it globally across all assistants managed here — useful for cross-cutting concerns like logging, tracing, or policy enforcement.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `point` | `K` | ✓ | The interception point (beforeAsk, beforeTurn, beforeToolCall, afterToolCall, beforeResponse) |
+| `fn` | `InterceptorFn<InterceptorPoints[K]>` | ✓ | Middleware function receiving (ctx, next) |
+
+**Returns:** `this`
+
+```ts
+manager.intercept('beforeAsk', async (ctx, next) => {
+ console.log(`[${ctx.assistant.name}] asking: ${ctx.message}`)
+ await next()
+})
+```
+
 
-Discovers assistants by listing subdirectories in ~/.luca/assistants/ and cwd/assistants/. Each subdirectory containing a CORE.md is an assistant.
+
+### addDiscoveryFolder
+
+Registers an additional folder to scan during assistant discovery and immediately triggers a new discovery pass.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `folderPath` | `string` | ✓ | Absolute path to a folder containing assistant subdirectories |
+
+**Returns:** `Promise<this>`
+
+```ts
+await manager.addDiscoveryFolder('/path/to/more/assistants')
+console.log(manager.available) // includes assistants from the new folder
+```
+
+
+
+### discover
 
 **Returns:** `Promise<this>`
 
@@ -174,6 +213,7 @@ Emitted when a new assistant instance is created
 | `entries` | `object` | Discovered assistant entries keyed by name |
 | `instances` | `object` | Active assistant instances keyed by name |
 | `factories` | `object` | Registered factory functions keyed by name |
+| `extraFolders` | `array` | Additional folders to scan during discovery |
 
 ## Examples
 
@@ -189,6 +229,26 @@ const answer = await assistant.ask('Hello!')
 
 
 
+**intercept**
+
+```ts
+manager.intercept('beforeAsk', async (ctx, next) => {
+ console.log(`[${ctx.assistant.name}] asking: ${ctx.message}`)
+ await next()
+})
+```
+
+
+
+**addDiscoveryFolder**
+
+```ts
+await manager.addDiscoveryFolder('/path/to/more/assistants')
+console.log(manager.available) // includes assistants from the new folder
+```
+
+
+
 **downloadLucaCoreAssistants**
 
 ```ts

package/docs/apis/features/agi/auto-assistant.md

@@ -5,36 +5,9 @@ An autonomous assistant that owns a lower-level Assistant instance and gates all
 ## Usage
 
 ```ts
-container.feature('autoAssistant', {
-  // Tool bundles to register on the inner assistant
-  tools,
-  // Permission level per tool name
-  permissions,
-  // Default permission level for unconfigured tools
-  defaultPermission,
-  // System prompt for the inner assistant
-  systemPrompt,
-  // OpenAI model override
-  model,
-  // Conversation history persistence mode
-  historyMode,
-  // Assistant folder for disk-based definitions
-  folder,
-})
+container.feature('autoAssistant')
 ```
 
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `tools` | `array` | Tool bundles to register on the inner assistant |
-| `permissions` | `object` | Permission level per tool name |
-| `defaultPermission` | `string` | Default permission level for unconfigured tools |
-| `systemPrompt` | `string` | System prompt for the inner assistant |
-| `model` | `string` | OpenAI model override |
-| `historyMode` | `string` | Conversation history persistence mode |
-| `folder` | `string` | Assistant folder for disk-based definitions |
-
 ## Methods
 
 ### getPermission
@@ -219,134 +192,63 @@ Add a tool bundle after initialization. Useful for dynamically extending the ass
 
 ### permissionGranted
 
-Emitted when a pending tool call is approved
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Approval ID |
+Event emitted by AutonomousAssistant
 
 
 
 ### permissionDenied
 
-Emitted when a pending tool call is denied
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Approval ID |
+Event emitted by AutonomousAssistant
 
 
 
 ### toolBlocked
 
-Emitted when a tool call is blocked by deny policy
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `string` | Reason |
+Event emitted by AutonomousAssistant
 
 
 
 ### chunk
 
-Forwarded: streamed token chunk from the inner assistant
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | A chunk of streamed text |
+Event emitted by AutonomousAssistant
 
 
 
 ### response
 
-Forwarded: complete response from the inner assistant
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | The final response text |
+Event emitted by AutonomousAssistant
 
 
 
 ### toolCall
 
-Forwarded: a tool was called
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Tool arguments |
+Event emitted by AutonomousAssistant
 
 
 
 ### toolResult
 
-Forwarded: a tool returned a result
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Result value |
+Event emitted by AutonomousAssistant
 
 
 
 ### toolError
 
-Forwarded: a tool call failed
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | Tool name |
-| `arg1` | `any` | Error |
+Event emitted by AutonomousAssistant
 
 
 
 ### started
 
-Emitted when the autonomous assistant has been initialized
+Event emitted by AutonomousAssistant
 
 
 
 ### permissionRequest
 
-Emitted when a tool call requires user approval
+Event emitted by AutonomousAssistant
 
-**Event Arguments:**
 
-| Name | Type | Description |
-|------|------|-------------|
-| `id` | `string` | Unique approval ID |
-| `toolName` | `string` | The tool requesting permission |
-| `args` | `object` | The arguments the tool was called with |
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `started` | `boolean` | Whether the assistant has been initialized |
-| `permissions` | `object` | Permission level per tool name |
-| `defaultPermission` | `string` | Permission level for tools not explicitly configured |
-| `pendingApprovals` | `array` | Tool calls currently awaiting user approval |
-| `approvalHistory` | `array` | Recent approval decisions |
 
 ## Examples