@roj-ai/sdk 0.1.3 → 0.1.5

package/dist/core/sessions/session.js

@@ -0,0 +1,675 @@
+/**
+ * Session - OOP wrapper for session management.
+ *
+ * Responsibilities:
+ * - Factory for agents
+ * - User output callback
+ * - Plugin method aggregation
+ */
+import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '../../core/agents/agent-roles.js';
+import { generateAgentId } from '../../core/agents/schema.js';
+import { agentEvents, getChildren } from '../../core/agents/state.js';
+import { AgentErrors, SessionErrors, ValidationErrors } from '../../core/errors.js';
+import { withSessionId } from '../../core/events/test-helpers.js';
+import { applyMiddleware } from '../../core/llm/middleware.js';
+import { AGENT_CALLER, DEFAULT_CALLER, buildPluginDeps } from '../../core/plugins/plugin-builder.js';
+import { getEntryAgentId, getNextAgentSeq, sessionEvents } from '../../core/sessions/state.js';
+import { Err, Ok } from '../../lib/utils/result.js';
+import { getNextMessageSeq, selectMailboxState } from '../../plugins/mailbox/query.js';
+import { generateMessageId } from '../../plugins/mailbox/schema.js';
+import { mailboxEvents } from '../../plugins/mailbox/state.js';
+import { Agent } from '../agents/agent.js';
+import { SessionFileStore } from '../file-store/file-store.js';
+// ============================================================================
+// Session
+// ============================================================================
+/**
+ * Session manages agents and delegates everything else to plugins.
+ */
+export class Session {
+    id;
+    store;
+    preset;
+    llmProvider;
+    llmProviders;
+    toolExecutor;
+    logger;
+    onUserOutput;
+    sessionDir;
+    plugins;
+    eventStore;
+    llmLogger;
+    platform;
+    agents = new Map();
+    /** Cached plugin contexts created by plugin.createContext() */
+    pluginContexts = new Map();
+    constructor(deps) {
+        this.id = deps.store.sessionId;
+        this.store = deps.store;
+        this.preset = deps.preset;
+        this.llmProvider = deps.llmProvider;
+        this.llmProviders = deps.llmProviders ?? new Map();
+        this.toolExecutor = deps.toolExecutor;
+        this.logger = deps.logger;
+        this.onUserOutput = deps.onUserOutput;
+        this.sessionDir = deps.sessionDir;
+        this.plugins = deps.plugins;
+        this.eventStore = deps.eventStore;
+        this.llmLogger = deps.llmLogger;
+        this.platform = deps.platform;
+        // Initialize agents from state
+        this.initializeAgents();
+        // React to events for agent scheduling
+        this.store.onEvent((event) => this.handleStoreEvent(event));
+    }
+    /**
+     * Get the current session state.
+     */
+    get state() {
+        return this.store.getState();
+    }
+    /**
+     * Get the preset configuration for this session.
+     */
+    getPreset() {
+        return this.preset;
+    }
+    /**
+     * Get the entry agent ID (communicator if present, otherwise orchestrator).
+     */
+    getEntryAgentId() {
+        return getEntryAgentId(this.state);
+    }
+    /**
+     * Initialize plugin contexts.
+     * Must be called before session hooks or plugin methods that need pluginContext.
+     */
+    async initPluginContexts() {
+        const sessionContext = this.buildSessionContext();
+        for (const plugin of this.plugins) {
+            if (plugin.createContext) {
+                const ctx = await plugin.createContext(sessionContext);
+                this.pluginContexts.set(plugin.name, ctx);
+            }
+        }
+    }
+    /**
+     * Call onSessionReady hooks for all plugins (with full context).
+     *
+     * Only errors are persisted as events — successful runs produce no event
+     * to keep the session log focused on state changes, not invocation noise.
+     */
+    async callSessionReadyHooks() {
+        for (const plugin of this.plugins) {
+            if (plugin.sessionHooks?.onSessionReady) {
+                const startTime = Date.now();
+                try {
+                    const ctx = this.buildSessionHookContext(plugin);
+                    await plugin.sessionHooks.onSessionReady(ctx);
+                }
+                catch (err) {
+                    await this.store.emit(withSessionId(this.id, sessionEvents.create('session_handler_completed', {
+                        handlerName: 'onSessionReady',
+                        pluginName: plugin.name,
+                        durationMs: Date.now() - startTime,
+                        error: err instanceof Error ? err.message : String(err),
+                    })));
+                    throw err;
+                }
+            }
+        }
+    }
+    /**
+     * Close the session.
+     * Emits session_closed event — hooks and agent shutdown are handled reactively by handleSessionClosed().
+     */
+    async close() {
+        if (this.store.isClosed()) {
+            return Err(SessionErrors.closed(String(this.id)));
+        }
+        await this.store.emit(withSessionId(this.id, sessionEvents.create('session_closed', {})));
+        return Ok(undefined);
+    }
+    /**
+     * Reopen a closed session.
+     */
+    async reopen() {
+        if (!this.store.isClosed()) {
+            return Err(ValidationErrors.invalid('Session is not closed'));
+        }
+        await this.store.emit(withSessionId(this.id, sessionEvents.create('session_reopened', {})));
+        return Ok(undefined);
+    }
+    /**
+     * Get an agent by ID.
+     */
+    getAgent(agentId) {
+        return this.agents.get(agentId) ?? null;
+    }
+    /**
+     * Get the entry agent (communicator or orchestrator).
+     */
+    getEntryAgent() {
+        const entryId = getEntryAgentId(this.state);
+        if (!entryId)
+            return null;
+        return this.agents.get(entryId) ?? null;
+    }
+    /**
+     * Schedule agent processing (with debounce).
+     */
+    scheduleAgent(agentId) {
+        const agent = this.agents.get(agentId);
+        if (agent) {
+            agent.scheduleProcessing();
+        }
+    }
+    /**
+     * Force process an agent (bypass debounce).
+     */
+    async forceProcessAgent(agentId) {
+        const agent = this.agents.get(agentId);
+        if (agent) {
+            await agent.continue();
+        }
+    }
+    /**
+     * Resume a paused agent so it can continue processing.
+     */
+    async resumeAgent(agentId) {
+        if (this.store.isClosed()) {
+            return Err(SessionErrors.closed(String(this.id)));
+        }
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            return Err(AgentErrors.notFound(String(agentId)));
+        }
+        const agentState = this.store.getAgentState(agentId);
+        if (!agentState || (agentState.status !== 'paused' && agentState.status !== 'errored')) {
+            return Err(ValidationErrors.invalid('Agent is not paused or errored'));
+        }
+        await this.store.emit(withSessionId(this.id, agentEvents.create('agent_resumed', {
+            agentId,
+        })));
+        agent.continue().catch((err) => {
+            this.logger.error('Unhandled error in agent.continue()', err instanceof Error ? err : undefined, { sessionId: this.id, agentId });
+        });
+        this.logger.info('Agent resumed', { sessionId: this.id, agentId });
+        return Ok(undefined);
+    }
+    /**
+     * Pause an agent manually via API.
+     */
+    async pauseAgent(agentId, message) {
+        if (this.store.isClosed()) {
+            return Err(SessionErrors.closed(String(this.id)));
+        }
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            return Err(AgentErrors.notFound(String(agentId)));
+        }
+        const agentState = this.store.getAgentState(agentId);
+        if (!agentState || agentState.status === 'paused') {
+            return Err(ValidationErrors.invalid('Agent is already paused'));
+        }
+        await this.store.emit(withSessionId(this.id, agentEvents.create('agent_paused', {
+            agentId,
+            reason: 'manual',
+            message,
+        })));
+        this.logger.info('Agent paused', { sessionId: this.id, agentId });
+        return Ok(undefined);
+    }
+    /**
+     * Manually spawn an agent under a given parent.
+     */
+    async spawnAgentManually(definitionName, parentId, message, typedInput) {
+        if (this.store.isClosed()) {
+            return Err(SessionErrors.closed(String(this.id)));
+        }
+        // Validate parent exists
+        if (!this.agents.has(parentId)) {
+            return Err(AgentErrors.notFound(String(parentId)));
+        }
+        // Validate definition exists in preset
+        const isOrchestrator = definitionName === ORCHESTRATOR_ROLE;
+        const isCommunicator = definitionName === COMMUNICATOR_ROLE && !!this.preset.communicator;
+        const isAgent = this.preset.agents.some((a) => a.name === definitionName);
+        if (!isOrchestrator && !isCommunicator && !isAgent) {
+            return Err(ValidationErrors.invalid(`Agent definition not found: ${definitionName}`));
+        }
+        // Validate parent is authorized to spawn this definition
+        const parentState = this.store.getAgentState(parentId);
+        if (parentState) {
+            const parentConfig = this.getAgentConfig(parentState.definitionName);
+            if (parentConfig.spawnableAgents.length > 0 && !parentConfig.spawnableAgents.includes(definitionName)) {
+                return Err(ValidationErrors.invalid(`Agent '${parentState.definitionName}' is not authorized to spawn '${definitionName}'`));
+            }
+            // Enforce max child agents per parent (default: 20)
+            const children = getChildren(this.state, parentId);
+            const maxChildren = 20;
+            if (children.length >= maxChildren) {
+                return Err(ValidationErrors.invalid(`Agent '${parentId}' has reached max child agent limit (${maxChildren})`));
+            }
+        }
+        const seq = getNextAgentSeq(this.state, definitionName);
+        const agentId = generateAgentId(definitionName, seq);
+        const now = Date.now();
+        const events = [
+            withSessionId(this.id, agentEvents.create('agent_spawned', {
+                agentId,
+                definitionName,
+                parentId,
+                ...(typedInput !== undefined ? { typedInput } : {}),
+            })),
+        ];
+        if (message) {
+            const messageId = generateMessageId(getNextMessageSeq(selectMailboxState(this.state)) + 1);
+            events.push(withSessionId(this.id, mailboxEvents.create('mailbox_message', {
+                toAgentId: agentId,
+                message: {
+                    id: messageId,
+                    from: parentId,
+                    content: message,
+                    timestamp: now,
+                    consumed: false,
+                },
+            })));
+        }
+        await this.store.emitBatch(events);
+        this.logger.debug('Agent spawned manually', {
+            sessionId: this.id,
+            agentId,
+            definitionName,
+            parentId,
+        });
+        return Ok(agentId);
+    }
+    /**
+     * Shutdown the session - stop all agent processing.
+     */
+    shutdown() {
+        for (const agent of this.agents.values()) {
+            try {
+                agent.shutdown();
+            }
+            catch {
+                // Suppress errors during shutdown
+            }
+        }
+    }
+    /**
+     * Check if a session has any agents that need processing.
+     */
+    checkPendingAgents() {
+        for (const agent of this.agents.values()) {
+            agent.continue().catch((err) => {
+                this.logger.error('Unhandled error in agent.continue()', err instanceof Error ? err : undefined, { sessionId: this.id, agentId: agent.id });
+            });
+        }
+    }
+    /**
+     * Aggregate methods from all plugins.
+     * Returns a map of "pluginName.methodName" → { input, output, handler }.
+     */
+    getPluginMethods() {
+        const methods = new Map();
+        for (const plugin of this.plugins) {
+            for (const [methodName, methodDef] of Object.entries(plugin.methods)) {
+                methods.set(`${plugin.name}.${methodName}`, methodDef);
+            }
+        }
+        return methods;
+    }
+    /**
+     * Call a plugin method with properly constructed MethodHandlerContext.
+     * The context includes pluginState, pluginConfig (bound in closure),
+     * pluginContext, and scheduleAgent.
+     */
+    async callPluginMethod(method, input, agentId, caller) {
+        // Find the plugin and method by parsing "pluginName.methodName"
+        const dotIndex = method.indexOf('.');
+        if (dotIndex === -1) {
+            return Err(ValidationErrors.invalid(`Invalid method format: ${method}`));
+        }
+        const pluginName = method.slice(0, dotIndex);
+        const methodName = method.slice(dotIndex + 1);
+        const plugin = this.plugins.find((p) => p.name === pluginName);
+        if (!plugin) {
+            return Err(ValidationErrors.invalid(`Unknown plugin: ${pluginName}`));
+        }
+        const methodDef = plugin.methods[methodName];
+        if (!methodDef) {
+            return Err(ValidationErrors.invalid(`Unknown method: ${method}`));
+        }
+        // Validate input
+        const parsed = methodDef.input.safeParse(input);
+        if (!parsed.success) {
+            return Err(ValidationErrors.invalid(`Invalid input for ${method}: ${parsed.error.message}`));
+        }
+        // Build MethodHandlerContext with plugin state, context, scheduleAgent, notify, and deps
+        const sessionContext = this.buildSessionContext();
+        const pluginState = plugin.slice ? plugin.slice.select(this.store.getState()) : undefined;
+        const pluginContext = this.pluginContexts.get(pluginName);
+        const deps = this.buildPluginDeps(plugin);
+        const ctx = {
+            ...sessionContext,
+            caller: caller ?? DEFAULT_CALLER,
+            logger: this.logger.child({ method, agentId }),
+            pluginConfig: undefined,
+            pluginContext,
+            pluginState,
+            scheduleAgent: (targetAgentId) => this.scheduleAgent(targetAgentId),
+            notify: this.createNotify(pluginName),
+            deps,
+        };
+        const result = await methodDef.handler(ctx, parsed.data);
+        return result;
+    }
+    // ============================================================================
+    // Private methods
+    // ============================================================================
+    /**
+     * Initialize agents from session state.
+     */
+    initializeAgents() {
+        for (const [agentId, agentState] of this.state.agents) {
+            const agent = this.createAgent(agentState);
+            this.agents.set(agentId, agent);
+        }
+    }
+    /**
+     * Create an Agent instance from state.
+     */
+    createAgent(agentState) {
+        const config = this.getAgentConfig(agentState.definitionName);
+        // Filter plugins by isEnabled for this specific agent
+        const agentPlugins = this.plugins.filter((plugin) => {
+            if (!plugin.isEnabled)
+                return true;
+            return plugin.isEnabled({
+                pluginConfig: undefined, // injected by plugin builder wrapper
+                pluginAgentConfig: config.plugins?.find(c => c.pluginName === plugin.name)?.config,
+                agentConfig: config,
+            });
+        });
+        const env = this.getSessionEnvironment();
+        const fileStore = new SessionFileStore(env.sessionDir, env.workspaceDir, env.sandboxed, this.platform.fs);
+        // Apply LLM middleware chain: preset-level → agent-level → base provider
+        const agentMiddleware = this.getAgentMiddleware(agentState.definitionName);
+        const middleware = [
+            ...(this.preset.llmMiddleware ?? []),
+            ...agentMiddleware,
+        ];
+        const llmProvider = applyMiddleware(this.llmProvider, middleware);
+        return new Agent({
+            id: agentState.id,
+            sessionContext: {
+                sessionId: this.id,
+                sessionState: this.store.getState(),
+                sessionInput: undefined,
+                environment: env,
+                llm: this.llmProvider,
+                files: fileStore,
+                eventStore: this.eventStore,
+                llmLogger: this.llmLogger,
+                platform: this.platform,
+                logger: this.logger,
+                emitEvent: async (event) => {
+                    await this.store.emit(withSessionId(this.id, event));
+                },
+                notify: (type, payload) => {
+                    this.onUserOutput?.({ pluginName: '_agent', type, payload });
+                },
+            },
+            store: this.store,
+            llmProvider,
+            llmProviders: this.llmProviders,
+            toolExecutor: this.toolExecutor,
+            logger: this.logger.child({ agentId: agentState.id }),
+            config,
+            plugins: agentPlugins,
+            environment: env,
+            fileStore,
+            pluginContexts: this.pluginContexts,
+            sendNotification: (n) => this.onUserOutput?.(n),
+            pluginMethodCaller: async (depPluginName, methodName, input) => {
+                return await this.callPluginMethod(`${depPluginName}.${methodName}`, input, agentState.id, AGENT_CALLER);
+            },
+            schedule: () => this.scheduleAgent(agentState.id),
+        });
+    }
+    /**
+     * Handle events emitted to the store — reactive scheduling.
+     */
+    handleStoreEvent(event) {
+        switch (event.type) {
+            case 'agent_spawned': {
+                const spawned = event;
+                this.handleAgentSpawned(spawned.agentId);
+                break;
+            }
+            case 'session_closed': {
+                this.handleSessionClosed().catch((err) => {
+                    this.logger.error('Unhandled error in handleSessionClosed()', err instanceof Error ? err : undefined, { sessionId: this.id });
+                });
+                break;
+            }
+        }
+    }
+    /**
+     * Handle session_closed event — call close hooks and shutdown agents.
+     *
+     * Unlike onSessionReady (which re-throws), onSessionClose intentionally
+     * swallows per-plugin errors so that all plugins get a chance to clean up
+     * and agents are always shut down, even if one plugin's close hook fails.
+     */
+    async handleSessionClosed() {
+        // Call onSessionClose for all plugins in REVERSE order (per-plugin isolation)
+        const reversedPlugins = [...this.plugins].reverse();
+        for (const plugin of reversedPlugins) {
+            if (plugin.sessionHooks?.onSessionClose) {
+                try {
+                    const ctx = this.buildSessionHookContext(plugin);
+                    await plugin.sessionHooks.onSessionClose(ctx);
+                }
+                catch (err) {
+                    this.logger.error(`Session plugin '${plugin.name}' onSessionClose failed`, err instanceof Error ? err : new Error(String(err)), {
+                        sessionId: this.id,
+                        pluginName: plugin.name,
+                    });
+                }
+            }
+        }
+        // Shutdown all agents
+        for (const agent of this.agents.values()) {
+            try {
+                agent.shutdown();
+            }
+            catch {
+                // Suppress errors during shutdown (e.g. AbortError from abort signal listeners)
+            }
+        }
+        // Clean up references to prevent memory leaks
+        this.agents.clear();
+        this.pluginContexts.clear();
+        this.store.clearListeners();
+        this.logger.info('Session closed', { sessionId: this.id });
+    }
+    /**
+     * Handle newly spawned agent.
+     */
+    handleAgentSpawned(agentId) {
+        // Guard: skip if agent already initialized (e.g., from initializeAgents)
+        if (this.agents.has(agentId))
+            return;
+        const agentState = this.store.getAgentState(agentId);
+        if (!agentState) {
+            this.logger.error('Spawned agent not found in state', undefined, {
+                sessionId: this.id,
+                agentId,
+            });
+            return;
+        }
+        // Create and register the new agent
+        const agent = this.createAgent(agentState);
+        this.agents.set(agentId, agent);
+        // Schedule processing (with debounce) for the new agent
+        agent.scheduleProcessing();
+    }
+    /**
+     * Handle user-facing output events.
+     */
+    /**
+     * Create a notify function bound to a specific plugin name.
+     */
+    createNotify(pluginName) {
+        return (type, payload) => {
+            this.onUserOutput?.({ pluginName, type, payload });
+        };
+    }
+    /**
+     * Build deps object for a plugin — delegates method calls to callPluginMethod.
+     */
+    buildPluginDeps(plugin) {
+        return buildPluginDeps(plugin.dependencyNames, this.plugins, async (depPluginName, methodName, input) => {
+            return await this.callPluginMethod(`${depPluginName}.${methodName}`, input);
+        });
+    }
+    /**
+     * Build a SessionContext from current session state.
+     */
+    buildSessionContext() {
+        const env = this.getSessionEnvironment();
+        const fileStore = new SessionFileStore(env.sessionDir, env.workspaceDir, env.sandboxed, this.platform.fs);
+        return {
+            sessionId: this.id,
+            sessionState: this.store.getState(),
+            sessionInput: undefined,
+            environment: env,
+            llm: this.llmProvider,
+            files: fileStore,
+            eventStore: this.eventStore,
+            llmLogger: this.llmLogger,
+            platform: this.platform,
+            logger: this.logger,
+            emitEvent: async (event) => {
+                await this.store.emit(withSessionId(this.id, event));
+            },
+            notify: (type, payload) => {
+                this.onUserOutput?.({ pluginName: '_session', type, payload });
+            },
+        };
+    }
+    /**
+     * Build context for a session-level hook (onSessionReady / onSessionClose).
+     * Provides pluginConfig (via closure), pluginContext, pluginState, self, and session fields.
+     */
+    buildSessionHookContext(plugin) {
+        const sessionContext = this.buildSessionContext();
+        const pluginState = plugin.slice ? plugin.slice.select(this.store.getState()) : undefined;
+        const pluginContext = this.pluginContexts.get(plugin.name);
+        // Build self — typed method callers (routed through callPluginMethod for proper context)
+        const self = {};
+        for (const [methodName] of Object.entries(plugin.methods)) {
+            self[methodName] = async (input) => {
+                const result = await this.callPluginMethod(`${plugin.name}.${methodName}`, input, undefined, AGENT_CALLER);
+                if (!result.ok) {
+                    throw new Error(`Plugin method failed: ${plugin.name}.${methodName}: ${result.error.type}`);
+                }
+                return result.value;
+            };
+        }
+        const deps = this.buildPluginDeps(plugin);
+        return {
+            ...sessionContext,
+            caller: AGENT_CALLER,
+            pluginConfig: undefined, // injected by plugin builder wrapper
+            pluginContext,
+            pluginState,
+            self,
+            scheduleAgent: (agentId) => this.scheduleAgent(agentId),
+            notify: this.createNotify(plugin.name),
+            deps,
+        };
+    }
+    /**
+     * Get session environment for tool context.
+     */
+    getSessionEnvironment() {
+        return {
+            sessionDir: this.sessionDir,
+            workspaceDir: this.state.workspaceDir,
+            sandboxed: this.preset.sandboxed ?? false,
+        };
+    }
+    /**
+     * Get LLM middleware from the agent/orchestrator/communicator definition.
+     */
+    getAgentMiddleware(definitionName) {
+        if (definitionName === ORCHESTRATOR_ROLE)
+            return this.preset.orchestrator.llmMiddleware ?? [];
+        if (definitionName === COMMUNICATOR_ROLE)
+            return this.preset.communicator?.llmMiddleware ?? [];
+        return this.preset.agents.find(a => a.name === definitionName)?.llmMiddleware ?? [];
+    }
+    /**
+     * Get agent config from preset definition.
+     * Tools are provided by plugins (Agent collects from plugins).
+     */
+    getAgentConfig(definitionName) {
+        const withServicePluginConfig = (config) => {
+            const base = config.plugins ?? [];
+            if (!config.services || config.services.length === 0)
+                return base.length > 0 ? base : undefined;
+            // Merge services config into plugins array (if not already present)
+            if (base.some(c => c.pluginName === 'services'))
+                return base;
+            return [...base, { pluginName: 'services', config: { services: config.services.map(s => s.type) } }];
+        };
+        if (definitionName === ORCHESTRATOR_ROLE) {
+            const orch = this.preset.orchestrator;
+            return {
+                systemPrompt: orch.system,
+                model: orch.model,
+                spawnableAgents: orch.agents ?? [],
+                tools: orch.tools,
+                debounceMs: orch.debounceMs,
+                debounceCallback: orch.debounceCallback,
+                checkIntervalMs: orch.checkIntervalMs,
+                input: orch.input,
+                plugins: withServicePluginConfig(orch),
+            };
+        }
+        if (definitionName === COMMUNICATOR_ROLE && this.preset.communicator) {
+            const comm = this.preset.communicator;
+            return {
+                systemPrompt: comm.system,
+                model: comm.model,
+                spawnableAgents: comm.agents ?? [],
+                tools: comm.tools,
+                debounceMs: comm.debounceMs,
+                debounceCallback: comm.debounceCallback,
+                checkIntervalMs: comm.checkIntervalMs,
+                input: comm.input,
+                plugins: withServicePluginConfig(comm),
+            };
+        }
+        const agentDef = this.preset.agents.find((a) => a.name === definitionName);
+        if (!agentDef) {
+            throw new Error(`Agent definition not found: ${definitionName}`);
+        }
+        return {
+            systemPrompt: agentDef.system,
+            model: agentDef.model,
+            spawnableAgents: agentDef.agents ?? [],
+            tools: agentDef.tools,
+            debounceMs: agentDef.debounceMs,
+            debounceCallback: agentDef.debounceCallback,
+            checkIntervalMs: agentDef.checkIntervalMs,
+            input: agentDef.input,
+            plugins: withServicePluginConfig(agentDef),
+        };
+    }
+}
+//# sourceMappingURL=session.js.map