@agentick/core 0.0.1

package/dist/agentick-instance.js

@@ -0,0 +1,700 @@
+/**
+ * Agentick Configuration Instance
+ *
+ * `Agentick` is the default global instance. Users interact with instances, never the class directly.
+ *
+ * ```typescript
+ * import { Agentick, createApp } from 'agentick';
+ *
+ * // Configure global instance
+ * Agentick.use('*', loggingMiddleware);
+ * Agentick.use('tool:*', authMiddleware);
+ *
+ * // createApp uses Agentick by default
+ * const app = createApp(MyAgent, { model });
+ *
+ * // Create a scoped instance (inherits from Agentick)
+ * const scoped = Agentick.create();
+ * scoped.use('model:generate', rateLimitMiddleware);
+ * const scopedApp = scoped.createApp(MyAgent, { model });
+ *
+ * // Create isolated instance (no inheritance)
+ * const isolated = Agentick.create({ inheritDefaults: false });
+ * ```
+ *
+ * @module agentick/@agentick/instance
+ */
+import { createProcedure, } from "@agentick/kernel";
+import { SessionImpl } from "./app/session";
+import { createSessionStore } from "./app/sqlite-session-store";
+class SessionRegistry {
+    options;
+    sessions = new Map();
+    lastActivity = new Map();
+    sweepTimer;
+    // Resolved options
+    store;
+    idleTimeout;
+    maxActive;
+    autoHibernate;
+    constructor(options) {
+        this.options = options;
+        // Resolve options with backwards compatibility
+        const sessionsConfig = options.sessions ?? {};
+        // Resolve store configuration (string path, config object, or SessionStore instance)
+        this.store = createSessionStore(sessionsConfig.store);
+        this.idleTimeout = sessionsConfig.idleTimeout ?? 0;
+        this.maxActive = sessionsConfig.maxActive ?? 0;
+        this.autoHibernate = sessionsConfig.autoHibernate ?? !!this.store;
+        // Start sweep timer if we have an idle timeout
+        if (this.idleTimeout > 0) {
+            const interval = Math.max(1000, Math.min(this.idleTimeout, 30000));
+            this.sweepTimer = setInterval(() => this.sweep(), interval);
+        }
+    }
+    get(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            this.touch(sessionId);
+        }
+        return session;
+    }
+    /**
+     * Try to get a session, hydrating from store if necessary.
+     * Returns undefined if session doesn't exist anywhere.
+     */
+    async getOrHydrate(sessionId, createSession) {
+        // Check in-memory first
+        const existing = this.get(sessionId);
+        if (existing) {
+            return existing;
+        }
+        // Try to hydrate from store
+        if (!this.store) {
+            return undefined;
+        }
+        const snapshot = await this.store.load(sessionId);
+        if (!snapshot) {
+            return undefined;
+        }
+        // Call onBeforeHydrate hook
+        if (this.options.onBeforeHydrate) {
+            const result = await this.options.onBeforeHydrate(sessionId, snapshot);
+            if (result === false) {
+                return undefined; // Hydration cancelled
+            }
+            if (result && typeof result === "object" && "version" in result) {
+                // Use modified snapshot
+                const session = createSession(result);
+                this.register(session.id, session);
+                // Call onAfterHydrate
+                await this.options.onAfterHydrate?.(session, result);
+                // Delete from store since it's now in memory
+                await this.store.delete(sessionId);
+                return session;
+            }
+        }
+        // Create session from snapshot
+        const session = createSession(snapshot);
+        this.register(session.id, session);
+        // Call onAfterHydrate
+        await this.options.onAfterHydrate?.(session, snapshot);
+        // Delete from store since it's now in memory
+        await this.store.delete(sessionId);
+        return session;
+    }
+    register(sessionId, session) {
+        this.sessions.set(sessionId, session);
+        this.touch(sessionId);
+        this.enforceMaxActive();
+    }
+    has(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    async isHibernated(sessionId) {
+        if (!this.store) {
+            return false;
+        }
+        if (this.store.has) {
+            return this.store.has(sessionId);
+        }
+        // Fallback: try to load
+        const snapshot = await this.store.load(sessionId);
+        return snapshot !== null;
+    }
+    list() {
+        return Array.from(this.sessions.keys());
+    }
+    async listHibernated() {
+        if (!this.store?.list) {
+            return [];
+        }
+        return this.store.list();
+    }
+    /**
+     * Hibernate a session (save to store and remove from memory).
+     * Returns the snapshot if successful, null if cancelled or no store.
+     */
+    async hibernate(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return null;
+        }
+        if (!this.store) {
+            // No store configured - just close the session
+            this.remove(sessionId, true);
+            return null;
+        }
+        // Get snapshot
+        const snapshot = session.snapshot();
+        // Call onBeforeHibernate hook
+        if (this.options.onBeforeHibernate) {
+            const result = await this.options.onBeforeHibernate(session, snapshot);
+            if (result === false) {
+                return null; // Hibernation cancelled
+            }
+            if (result && typeof result === "object" && "version" in result) {
+                // Use modified snapshot
+                await this.store.save(sessionId, result);
+                this.remove(sessionId, true);
+                await this.options.onAfterHibernate?.(sessionId, result);
+                return result;
+            }
+        }
+        // Save to store
+        await this.store.save(sessionId, snapshot);
+        // Remove from memory (close session)
+        this.remove(sessionId, true);
+        // Call onAfterHibernate
+        await this.options.onAfterHibernate?.(sessionId, snapshot);
+        return snapshot;
+    }
+    remove(sessionId, closeSession = true) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        this.sessions.delete(sessionId);
+        this.lastActivity.delete(sessionId);
+        if (closeSession) {
+            session.close();
+        }
+        this.options.onSessionClose?.(sessionId);
+    }
+    /**
+     * Permanently delete a session from both memory and store.
+     */
+    async delete(sessionId) {
+        this.remove(sessionId, true);
+        if (this.store) {
+            await this.store.delete(sessionId);
+        }
+    }
+    destroy() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = undefined;
+        }
+        for (const sessionId of this.sessions.keys()) {
+            this.remove(sessionId, true);
+        }
+    }
+    touch(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        this.lastActivity.set(sessionId, Date.now());
+        // Maintain LRU order by re-inserting
+        this.sessions.delete(sessionId);
+        this.sessions.set(sessionId, session);
+    }
+    markActive(sessionId) {
+        this.touch(sessionId);
+    }
+    async sweep() {
+        if (this.idleTimeout <= 0)
+            return;
+        const now = Date.now();
+        const toHibernate = [];
+        for (const [sessionId, last] of this.lastActivity.entries()) {
+            if (now - last >= this.idleTimeout) {
+                toHibernate.push(sessionId);
+            }
+        }
+        // Hibernate idle sessions
+        for (const sessionId of toHibernate) {
+            if (this.autoHibernate && this.store) {
+                await this.hibernate(sessionId);
+            }
+            else {
+                this.remove(sessionId, true);
+            }
+        }
+    }
+    async enforceMaxActive() {
+        if (this.maxActive <= 0)
+            return;
+        while (this.sessions.size > this.maxActive) {
+            const oldestId = this.sessions.keys().next().value;
+            if (!oldestId)
+                break;
+            if (this.autoHibernate && this.store) {
+                await this.hibernate(oldestId);
+            }
+            else {
+                this.remove(oldestId, true);
+            }
+        }
+    }
+}
+// ============================================================================
+// App Implementation
+// ============================================================================
+class AppImpl {
+    Component;
+    options;
+    run;
+    registry;
+    sessionCreateHandlers = new Set();
+    sessionCloseHandlers = new Set();
+    constructor(Component, options) {
+        this.Component = Component;
+        this.options = options;
+        this.registry = new SessionRegistry({
+            sessions: options.sessions,
+            // Callbacks
+            onSessionClose: (sessionId) => {
+                this.options.onSessionClose?.(sessionId);
+                for (const handler of this.sessionCloseHandlers) {
+                    handler(sessionId);
+                }
+            },
+            onBeforeHibernate: options.onBeforeHibernate,
+            onAfterHibernate: options.onAfterHibernate,
+            onBeforeHydrate: options.onBeforeHydrate,
+            onAfterHydrate: options.onAfterHydrate,
+        });
+        this.run = createProcedure({
+            name: "app:run",
+            handleFactory: false,
+        }, async (input) => {
+            const { props = {}, messages = [], history = [], maxTicks, signal, devTools, recording, } = input;
+            const sessionOptions = {
+                initialTimeline: history.length > 0 ? history : undefined,
+                devTools: devTools ?? this.options.devTools,
+                recording,
+            };
+            const executionOptions = {
+                maxTicks,
+                signal,
+            };
+            const session = this.createSession(undefined, sessionOptions);
+            for (const message of messages) {
+                session.queue.exec(message);
+            }
+            const handle = await session.render(props, executionOptions);
+            handle.result
+                .finally(() => session.close())
+                .catch(() => {
+                // Prevent unhandled rejection - errors are captured in handle
+            });
+            return handle;
+        });
+    }
+    async send(input, options) {
+        const sessionId = options?.sessionId;
+        if (!sessionId) {
+            const session = this.createSession(undefined, {});
+            const handle = await session.send(input);
+            handle.result
+                .finally(() => session.close())
+                .catch(() => {
+                // Prevent unhandled rejection - errors are captured in handle
+            });
+            return handle;
+        }
+        const session = await this.session(sessionId);
+        const maybeModified = this.options.onBeforeSend?.(session, input) ?? input;
+        const handle = await session.send(maybeModified);
+        handle.result
+            .then((result) => {
+            this.options.onAfterSend?.(session, result);
+        })
+            .catch(() => {
+            // Errors are already surfaced via lifecycle callbacks
+        });
+        return handle;
+    }
+    async session(idOrOptions) {
+        // Parse arguments: string is ID, object is options
+        let sessionId;
+        let options = {};
+        if (typeof idOrOptions === "string") {
+            sessionId = idOrOptions;
+        }
+        else if (idOrOptions !== undefined) {
+            options = idOrOptions;
+            sessionId = options.sessionId;
+        }
+        // If we have an ID, try to get existing or hydrate from store
+        if (sessionId) {
+            const existing = await this.registry.getOrHydrate(sessionId, (snapshot) => this.createSessionFromSnapshot(snapshot, options));
+            if (existing)
+                return existing;
+        }
+        // Create new session (ID will be generated if undefined)
+        return this.createSession(sessionId, options);
+    }
+    async close(sessionId) {
+        this.registry.remove(sessionId, true);
+    }
+    get sessions() {
+        return this.registry.list();
+    }
+    has(sessionId) {
+        return this.registry.has(sessionId);
+    }
+    async isHibernated(sessionId) {
+        return this.registry.isHibernated(sessionId);
+    }
+    async hibernate(sessionId) {
+        return this.registry.hibernate(sessionId);
+    }
+    async hibernatedSessions() {
+        return this.registry.listHibernated();
+    }
+    onSessionCreate(handler) {
+        this.sessionCreateHandlers.add(handler);
+        return () => {
+            this.sessionCreateHandlers.delete(handler);
+        };
+    }
+    onSessionClose(handler) {
+        this.sessionCloseHandlers.add(handler);
+        return () => {
+            this.sessionCloseHandlers.delete(handler);
+        };
+    }
+    createSession(sessionId, options) {
+        const sessionOptions = {
+            ...options,
+            sessionId,
+            devTools: options.devTools ?? this.options.devTools,
+        };
+        const session = new SessionImpl(this.Component, this.options, sessionOptions);
+        this.initializeSession(session);
+        this.registry.register(session.id, session);
+        return session;
+    }
+    /**
+     * Create a session from a hibernation snapshot.
+     * Used by registry.getOrHydrate() - does NOT register (getOrHydrate handles that).
+     */
+    createSessionFromSnapshot(snapshot, options) {
+        const sessionOptions = {
+            ...options,
+            sessionId: snapshot.sessionId,
+            snapshot,
+            devTools: options.devTools ?? this.options.devTools,
+        };
+        const session = new SessionImpl(this.Component, this.options, sessionOptions);
+        this.initializeSession(session);
+        return session;
+    }
+    /**
+     * Initialize session with callbacks and listeners.
+     * Shared by createSession and createSessionFromSnapshot.
+     */
+    initializeSession(session) {
+        // Set hibernate callback so session.hibernate() delegates to the registry
+        session.setHibernateCallback(() => this.registry.hibernate(session.id));
+        session.on("event", () => {
+            this.registry.markActive(session.id);
+        });
+        session.once("close", () => {
+            this.registry.remove(session.id, false);
+        });
+        this.options.onSessionCreate?.(session);
+        for (const handler of this.sessionCreateHandlers) {
+            handler(session);
+        }
+    }
+}
+/**
+ * Agentick configuration instance.
+ *
+ * Users interact with instances, never the class directly.
+ * `Agentick` is the default global instance.
+ */
+export class AgentickInstance {
+    middlewareRegistry = new Map();
+    _telemetryProvider;
+    /**
+     * One-shot execution of a JSX component.
+     *
+     * Accepts a JSX element and optional RunInput. Creates a temporary app and session,
+     * runs to completion, then cleans up.
+     *
+     * **Prop merging:** Element props are defaults, `input.props` override them.
+     * `{ ...element.props, ...input.props }` — so `<Agent query="default" />` with
+     * `{ props: { query: "override" } }` uses `"override"`.
+     *
+     * Returns SessionExecutionHandle (AsyncIterable, not PromiseLike):
+     * - `await run(...).result` → SendResult
+     * - `for await (const event of await run(...))` → StreamEvent
+     *
+     * @example Get result
+     * ```typescript
+     * const result = await Agentick.run(
+     *   <MyAgent />,
+     *   { messages: [{ role: "user", content: [...] }], model }
+     * ).result;
+     * ```
+     *
+     * @example Stream events
+     * ```typescript
+     * const handle = await Agentick.run(<MyAgent />, { messages, model });
+     * for await (const event of handle) {
+     *   if (event.type === 'content_delta') {
+     *     process.stdout.write(event.delta);
+     *   }
+     * }
+     * ```
+     *
+     * @example Add middleware to run
+     * ```typescript
+     * const loggedRun = Agentick.run.use(loggingMiddleware);
+     * const result = await loggedRun(<MyAgent />, { messages, model }).result;
+     * ```
+     */
+    run;
+    /**
+     * @internal
+     */
+    constructor(options) {
+        this._telemetryProvider = options?.telemetryProvider;
+        // Create the run procedure bound to this instance
+        const instance = this;
+        this.run = createProcedure({ name: "agentick:run", handleFactory: false }, async (element, input = {}) => {
+            const { model, props, ...runInput } = input;
+            // Extract component and element props, input props override element props
+            const Component = element.type;
+            const mergedProps = { ...element.props, ...props };
+            // Create app options
+            const appOptions = {};
+            if (model)
+                appOptions.model = model;
+            // Create app and run using this instance
+            const app = instance.createApp(Component, appOptions);
+            return app.run({
+                ...runInput,
+                props: mergedProps,
+            });
+        });
+    }
+    /**
+     * Register middleware for a procedure pattern.
+     *
+     * Keys can be:
+     * - `'*'` - all procedures
+     * - `'tool:*'` - all tool procedures (tool:run, etc.)
+     * - `'model:*'` - all model procedures (model:generate, model:stream)
+     * - `'tool:run'` - specific procedure name
+     * - `'model:generate'` - specific procedure name
+     *
+     * Middleware is executed in order: global → category → specific
+     *
+     * @param key - Procedure pattern to match
+     * @param middleware - Middleware functions to register
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * Agentick
+     *   .use('*', loggingMiddleware)
+     *   .use('tool:*', authMiddleware)
+     *   .use('model:generate', rateLimitMiddleware);
+     * ```
+     */
+    use(key, ...middleware) {
+        const existing = this.middlewareRegistry.get(key) || [];
+        this.middlewareRegistry.set(key, [...existing, ...middleware]);
+        return this;
+    }
+    /**
+     * Get middleware matching a procedure name.
+     *
+     * Resolution order:
+     * 1. Global ('*')
+     * 2. Category wildcard (e.g., 'tool:*' matches 'tool:run')
+     * 3. Exact match (e.g., 'tool:run')
+     *
+     * @param procedureName - The procedure name to match (e.g., 'tool:run', 'model:generate')
+     * @returns Array of middleware functions in execution order
+     */
+    getMiddlewareFor(procedureName) {
+        const result = [];
+        // 1. Global middleware ('*')
+        const global = this.middlewareRegistry.get("*");
+        if (global)
+            result.push(...global);
+        // 2. Category wildcard (e.g., 'tool:*' matches 'tool:run')
+        const colonIndex = procedureName.indexOf(":");
+        if (colonIndex > 0) {
+            const category = procedureName.slice(0, colonIndex);
+            const categoryWildcard = this.middlewareRegistry.get(`${category}:*`);
+            if (categoryWildcard)
+                result.push(...categoryWildcard);
+        }
+        // 3. Exact match
+        const exact = this.middlewareRegistry.get(procedureName);
+        if (exact)
+            result.push(...exact);
+        return result;
+    }
+    /**
+     * Clear all registered middleware.
+     * Useful for testing or resetting state.
+     */
+    clear() {
+        this.middlewareRegistry.clear();
+        return this;
+    }
+    /**
+     * Get the telemetry provider.
+     */
+    get telemetryProvider() {
+        return this._telemetryProvider;
+    }
+    /**
+     * Set the telemetry provider.
+     */
+    set telemetryProvider(provider) {
+        this._telemetryProvider = provider;
+    }
+    /**
+     * Create a child instance.
+     *
+     * By default, the child inherits all middleware from this instance.
+     * Use `inheritDefaults: false` for a completely isolated instance.
+     *
+     * @param options - Instance options
+     * @returns A new AgentickInstance
+     *
+     * @example
+     * ```typescript
+     * // Create scoped instance that inherits global middleware
+     * const scoped = Agentick.create();
+     * scoped.use('model:generate', rateLimitMiddleware);
+     * const app = scoped.createApp(MyAgent);
+     *
+     * // Create isolated instance (no inheritance)
+     * const isolated = Agentick.create({ inheritDefaults: false });
+     * ```
+     */
+    create(options = {}) {
+        const child = new AgentickInstance({
+            telemetryProvider: options.telemetryProvider ?? this._telemetryProvider,
+        });
+        // Copy middleware from parent unless inheritDefaults: false
+        if (options.inheritDefaults !== false) {
+            for (const [key, mws] of this.middlewareRegistry) {
+                child.middlewareRegistry.set(key, [...mws]);
+            }
+        }
+        return child;
+    }
+    /**
+     * Create an app from a component function.
+     *
+     * The app inherits middleware from this Agentick instance.
+     *
+     * @param Component - The component function that defines the Model Interface
+     * @param options - App configuration options
+     * @returns An App instance with run, send, and session methods
+     *
+     * @example
+     * ```typescript
+     * const MyAgent = ({ query }) => (
+     *   <>
+     *     <System>You are helpful.</System>
+     *     <Timeline />
+     *     <User>{query}</User>
+     *   </>
+     * );
+     *
+     * // Use global Agentick
+     * const app = createApp(MyAgent, { model });
+     *
+     * // Use scoped instance
+     * const scoped = Agentick.create();
+     * scoped.use('tool:*', authMiddleware);
+     * const scopedApp = scoped.createApp(MyAgent, { model });
+     * ```
+     */
+    createApp(Component, options = {}) {
+        const optionsWithInstance = { ...options, _agentickInstance: this };
+        return new AppImpl(Component, optionsWithInstance);
+    }
+}
+/**
+ * The default global Agentick instance.
+ *
+ * All configuration and middleware registration starts here.
+ * The exported `createApp` and `run` are bound to this instance.
+ *
+ * @example
+ * ```typescript
+ * import { Agentick, createApp, run } from 'agentick';
+ *
+ * // Configure global middleware
+ * Agentick.use('*', loggingMiddleware);
+ * Agentick.telemetryProvider = myProvider;
+ *
+ * // createApp and run use Agentick
+ * const app = createApp(MyAgent, { model });
+ * const result = await run(<MyAgent />, { messages, model });
+ *
+ * // Create scoped instance with its own middleware
+ * const scoped = Agentick.create();
+ * scoped.use('model:generate', specialMiddleware);
+ * const scopedResult = await scoped.run(<MyAgent />, { messages, model });
+ * ```
+ */
+export const Agentick = new AgentickInstance();
+/**
+ * Create an app from a component function.
+ *
+ * This is `Agentick.createApp` - apps inherit middleware from the global Agentick instance.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from 'agentick';
+ *
+ * const app = createApp(MyAgent, { model });
+ * const result = await app.run({ props: { query: "Hello!" } });
+ * ```
+ */
+export const createApp = Agentick.createApp.bind(Agentick);
+/**
+ * One-shot execution of a JSX component.
+ *
+ * This is `Agentick.run` - the simplest way to run an agent.
+ * Returns SessionExecutionHandle (AsyncIterable, not PromiseLike).
+ *
+ * @example
+ * ```typescript
+ * import { run } from 'agentick';
+ *
+ * // Get result
+ * const result = await run(<MyAgent />, { messages, model }).result;
+ *
+ * // Stream events
+ * const handle = await run(<MyAgent />, { messages, model });
+ * for await (const event of handle) {
+ *   console.log(event);
+ * }
+ * ```
+ */
+export const run = Agentick.run.bind(Agentick);
+// RunInput is now defined in ./app/types and exported from the package index.
+//# sourceMappingURL=agentick-instance.js.map