@syrin/cli 1.3.0

package/dist/constants/messages.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Message constants used throughout the application.
+ * Centralized for consistency and easy updates.
+ */
+export declare const Messages: {
+    readonly DOCTOR_SETUP_SUCCESS: "Everything is set up well!";
+    readonly DOCTOR_ISSUES_FOUND: "Some issues found. Please fix them before proceeding.";
+    readonly INIT_ALREADY_INITIALIZED: "Syrin project is already initialized!";
+    readonly INIT_CONFIG_FILE: (configPath: string) => string;
+    readonly INIT_SUCCESS: "Syrin project initialized successfully!";
+    readonly INIT_NEXT_STEPS_HEADER: "Next steps:";
+    readonly INIT_ALREADY_INIT_MSG: (configPath: string) => string;
+    readonly INIT_VERIFY_SETUP: (doctorCommand: string) => string;
+    readonly INIT_REINITIALIZE_TIP: "Want to re-initialize?";
+    readonly INIT_REINITIALIZE_INSTRUCTION: (initCommand: string) => string;
+    readonly INIT_REVIEW_CONFIG: (configPath: string) => string;
+    readonly INIT_SETUP_ENV_VARS: "Set up your environment variables (API keys, etc.)";
+    readonly INIT_RUN_DOCTOR: (doctorCommand: string) => string;
+    readonly INIT_RUN_DEV: (devCommand: string) => string;
+    readonly ERROR_UNEXPECTED: "An unexpected error occurred";
+    readonly ERROR_LOADING_CONFIG: "Failed to load configuration file";
+    readonly ERROR_VALIDATION_FAILED: "Configuration validation failed";
+    readonly ERROR_CONFIG_NOT_FOUND: (command: string) => string;
+    readonly ERROR_CONFIG_EMPTY_OR_INVALID: "Configuration file is empty or invalid";
+    readonly ERROR_GENERATE_CONFIG: "Failed to generate configuration file";
+    readonly ENV_FILE_NOT_PRESENT: (_varName: string) => string;
+    readonly ENV_KEY_NOT_FOUND: (varName: string) => string;
+    readonly ENV_KEY_EMPTY: (varName: string) => string;
+    readonly ENV_SET_INSTRUCTIONS: (varName: string) => string;
+    readonly CONFIG_ADD_MCP_URL: "Add `mcp_url` to your config.yaml file when using http transport";
+    readonly CONFIG_ADD_SCRIPTS: "Add `scripts` section to your config.yaml with `dev` and `start` commands. For stdio transport, `scripts.dev` is required.";
+    readonly CONFIG_ADD_SCRIPT_STDIO: "Add script to your config.yaml file when using stdio transport";
+    readonly TRANSPORT_URL_REQUIRED: "MCP URL is required for HTTP transport. Set it in config.yaml or use --url option.";
+    readonly TRANSPORT_SCRIPT_REQUIRED: "Script is required for stdio transport. Set it in config.yaml or use --script option.";
+    readonly TRANSPORT_SCRIPT_REQUIRED_RUN_FLAG: "script is required when using --run-script flag";
+    readonly TRANSPORT_URL_REQUIRED_CONFIG: "MCP URL is required for HTTP transport. Set it in config.yaml.";
+    readonly CONNECTION_FAILED: (mcpUrl: string, source: string, transportType?: string) => string;
+    readonly CONNECTION_TIMEOUT_HTTP: (mcpUrl: string) => string;
+    readonly CONNECTION_FAILED_STDIO: (mcpCommand: string) => string;
+    readonly CONNECTION_TIMEOUT_STDIO: string;
+    readonly DEV_WELCOME: "Welcome to Syrin Dev Mode!";
+    readonly DEV_VERSION_INFO: (version: string, llm: string, tools: number) => string;
+    readonly DEV_TRANSPORT_HTTP: (transport: string, url: string) => string;
+    readonly DEV_TRANSPORT_STDIO: (transport: string, command: string) => string;
+    readonly DEV_HELP_MESSAGE: "Type your message below or /help for commands.";
+    readonly DEV_TOOLS_HEADER: "Available Tools:";
+    readonly DEV_NO_TOOLS: "  No tools available";
+    readonly DEV_HISTORY_HEADER: "Command History (last 100 entries):";
+    readonly DEV_NO_HISTORY: "No command history yet.";
+    readonly DEV_ERROR_READING_HISTORY: (error: string) => string;
+    readonly DEV_TOOL_CALLING: (name: string) => string;
+    readonly DEV_TOOL_COMPLETED: (name: string, duration?: number) => string;
+    readonly DEV_ERROR_START: "Failed to start dev mode";
+    readonly DEV_GOODBYE: "\n\nGoodbye! 👋";
+    readonly DOCTOR_SCRIPT_MISSING: "script is missing";
+    readonly DOCTOR_COMMAND_NOT_FOUND: (command: string) => string;
+    readonly DOCTOR_COMMAND_INSTALL: (command: string) => string;
+    readonly DOCTOR_SCRIPT_WORKING: "working";
+    readonly DOCTOR_SCRIPT_INFO: (script: string) => string;
+    readonly DOCTOR_MCP_URL_INFO: (url: string) => string;
+    readonly LIST_INVALID_TYPE: (type: string) => string;
+    readonly LIST_VALID_TYPES: "Valid types are: tools, resources, prompts";
+    readonly LIST_ERROR_FAILED: (type: string) => string;
+    readonly LIST_SOURCE_CONFIG: " (from config.yaml)";
+    readonly LIST_SOURCE_CLI_URL: " (from --url)";
+    readonly PROMPT_PROJECT_NAME_REQUIRED: "Project name is required";
+    readonly PROMPT_PROJECT_NAME_INVALID: "Project name can only contain letters, numbers, and hyphens";
+    readonly PROMPT_AGENT_NAME_REQUIRED: "Agent name is required";
+    readonly PROMPT_MCP_URL_REQUIRED: "MCP server URL is required for http transport";
+    readonly PROMPT_URL_INVALID: "Invalid URL format";
+    readonly PROMPT_SCRIPT_REQUIRED: "Script command is required";
+    readonly PROMPT_LLM_PROVIDER_REQUIRED: "At least one LLM provider must be selected";
+    readonly PROMPT_OPENAI_API_KEY_REQUIRED: "OpenAI API key is required";
+    readonly PROMPT_OPENAI_MODEL_REQUIRED: "OpenAI model name is required";
+    readonly PROMPT_CLAUDE_API_KEY_REQUIRED: "Claude API key is required";
+    readonly PROMPT_CLAUDE_MODEL_REQUIRED: "Claude model name is required";
+    readonly PROMPT_OLLAMA_MODEL_REQUIRED: "Ollama model name is required";
+    readonly CLI_START_FAILED: "Failed to start CLI";
+    readonly UPDATE_CHECKING: "Checking for updates...";
+    readonly UPDATE_CURRENT_VERSION: (version: string) => string;
+    readonly UPDATE_LATEST_VERSION: (version: string) => string;
+    readonly UPDATE_ALREADY_LATEST: (version: string) => string;
+    readonly UPDATE_IN_PROGRESS: (packageName: string) => string;
+    readonly UPDATE_SUCCESS: (version: string) => string;
+    readonly UPDATE_FAILED: "Update failed";
+    readonly UPDATE_ERROR: (error: string) => string;
+    readonly UPDATE_PERMISSION_HINT: (command: string) => string;
+    readonly ROLLBACK_IN_PROGRESS: (version: string, packageName: string) => string;
+    readonly ROLLBACK_SUCCESS: (version: string) => string;
+    readonly ROLLBACK_FAILED: "Rollback failed";
+    readonly ROLLBACK_ERROR: (error: string) => string;
+    readonly ROLLBACK_INVALID_VERSION: (version: string) => string;
+    readonly ROLLBACK_VERSION_NOT_FOUND: (version: string) => string;
+    readonly ROLLBACK_CONFIRM: (currentVersion: string, targetVersion: string) => string;
+    readonly ANALYSE_CONNECTING: "Connecting to MCP server...";
+    readonly ANALYSE_LOADING_TOOLS: "Loading tools...";
+    readonly ANALYSE_ANALYZING: "Analyzing tools...";
+    readonly ANALYSE_ERROR_FAILED: "Failed to analyze MCP server";
+    readonly ANALYSE_NO_TOOLS: "No tools found in MCP server";
+    readonly ANALYSE_VERDICT_PASS: "Syrin analysis passed";
+    readonly ANALYSE_VERDICT_FAIL: (errors: number, warnings: number) => string;
+    readonly ANALYSE_VERDICT_PASS_WARNINGS: (warnings: number) => string;
+    readonly ANALYSE_ERRORS_HEADER: "Errors:";
+    readonly ANALYSE_WARNINGS_HEADER: "Warnings:";
+    readonly ANALYSE_SUGGESTIONS_HEADER: "Suggestions:";
+};
+//# sourceMappingURL=messages.d.ts.map

package/dist/constants/messages.js

@@ -0,0 +1,138 @@
+/**
+ * Message constants used throughout the application.
+ * Centralized for consistency and easy updates.
+ */
+export const Messages = {
+    // Doctor Report Messages
+    DOCTOR_SETUP_SUCCESS: 'Everything is set up well!',
+    DOCTOR_ISSUES_FOUND: 'Some issues found. Please fix them before proceeding.',
+    // Init Command Messages
+    INIT_ALREADY_INITIALIZED: 'Syrin project is already initialized!',
+    INIT_CONFIG_FILE: (configPath) => `Configuration file: ${configPath}`,
+    INIT_SUCCESS: 'Syrin project initialized successfully!',
+    INIT_NEXT_STEPS_HEADER: 'Next steps:',
+    INIT_ALREADY_INIT_MSG: (configPath) => `Syrin is already initialized. Kindly go to ${configPath} to set up.`,
+    INIT_VERIFY_SETUP: (doctorCommand) => `After the setup, you can call \`${doctorCommand}\` to verify the setup process.`,
+    INIT_REINITIALIZE_TIP: 'Want to re-initialize?',
+    INIT_REINITIALIZE_INSTRUCTION: (initCommand) => `Delete the syrin.yaml file and run \`${initCommand}\` again.`,
+    INIT_REVIEW_CONFIG: (configPath) => `Review and edit ${configPath} if needed`,
+    INIT_SETUP_ENV_VARS: 'Set up your environment variables (API keys, etc.)',
+    INIT_RUN_DOCTOR: (doctorCommand) => `Run \`${doctorCommand}\` to verify your Syrin setup`,
+    INIT_RUN_DEV: (devCommand) => `Run \`${devCommand}\` to start development mode`,
+    // Error Messages
+    ERROR_UNEXPECTED: 'An unexpected error occurred',
+    ERROR_LOADING_CONFIG: 'Failed to load configuration file',
+    ERROR_VALIDATION_FAILED: 'Configuration validation failed',
+    ERROR_CONFIG_NOT_FOUND: (command) => `Configuration file not found. Run \`${command}\` to initialize the project.`,
+    ERROR_CONFIG_EMPTY_OR_INVALID: 'Configuration file is empty or invalid',
+    ERROR_GENERATE_CONFIG: 'Failed to generate configuration file',
+    // Environment Variable Messages
+    ENV_FILE_NOT_PRESENT: (_varName) => `.env file is not present in the project root`,
+    ENV_KEY_NOT_FOUND: (varName) => `.env file is present but key "${varName}" not found`,
+    ENV_KEY_EMPTY: (varName) => `Key "${varName}" found in .env file but the value is empty`,
+    ENV_SET_INSTRUCTIONS: (varName) => `Set ${varName} in your .env file or export it in your shell`,
+    // Config Fix Messages
+    CONFIG_ADD_MCP_URL: 'Add `mcp_url` to your config.yaml file when using http transport',
+    CONFIG_ADD_SCRIPTS: 'Add `scripts` section to your config.yaml with `dev` and `start` commands. For stdio transport, `scripts.dev` is required.',
+    CONFIG_ADD_SCRIPT_STDIO: 'Add script to your config.yaml file when using stdio transport',
+    // Transport/Connection Error Messages
+    TRANSPORT_URL_REQUIRED: 'MCP URL is required for HTTP transport. Set it in config.yaml or use --url option.',
+    TRANSPORT_SCRIPT_REQUIRED: 'Script is required for stdio transport. Set it in config.yaml or use --script option.',
+    TRANSPORT_SCRIPT_REQUIRED_RUN_FLAG: 'script is required when using --run-script flag',
+    TRANSPORT_URL_REQUIRED_CONFIG: 'MCP URL is required for HTTP transport. Set it in config.yaml.',
+    CONNECTION_FAILED: (mcpUrl, source, transportType = 'http') => `Cannot connect to MCP server using ${transportType.toUpperCase()} transport.\n` +
+        `\n` +
+        `MCP URL: ${mcpUrl}${source}\n` +
+        `Transport: ${transportType.toUpperCase()}\n` +
+        `\n` +
+        `The server appears to be not running or unreachable.\n` +
+        `\n` +
+        `To fix this:\n` +
+        `  1. Make sure the MCP server is running\n` +
+        `  2. Verify the URL is correct: ${mcpUrl}\n` +
+        `  3. Check if the server is listening on the expected port\n` +
+        (transportType === 'http' && source.includes('config')
+            ? `  4. If you intended to use stdio transport, use --script instead of --url\n`
+            : ''),
+    CONNECTION_TIMEOUT_HTTP: (mcpUrl) => `Connection to MCP server at ${mcpUrl} timed out.\n` +
+        `The server may be slow to respond or not running.`,
+    CONNECTION_FAILED_STDIO: (mcpCommand) => `Failed to start MCP server process: ${mcpCommand}\n` +
+        `\n` +
+        `The script may be incorrect or the executable not found.\n` +
+        `Verify the script path in config.yaml or use --script option.`,
+    CONNECTION_TIMEOUT_STDIO: `Connection to MCP server via stdio timed out.\n` +
+        `The server process may have failed to start or is not responding.`,
+    // Dev Command Messages
+    DEV_WELCOME: 'Welcome to Syrin Dev Mode!',
+    DEV_VERSION_INFO: (version, llm, tools) => `Version: ${version} | LLM: ${llm} | Tools: ${tools}`,
+    DEV_TRANSPORT_HTTP: (transport, url) => `Transport: ${transport} | MCP URL: ${url} ✅`,
+    DEV_TRANSPORT_STDIO: (transport, command) => `Transport: ${transport} | Command: ${command} ✅`,
+    DEV_HELP_MESSAGE: 'Type your message below or /help for commands.',
+    DEV_TOOLS_HEADER: 'Available Tools:',
+    DEV_NO_TOOLS: '  No tools available',
+    DEV_HISTORY_HEADER: 'Command History (last 100 entries):',
+    DEV_NO_HISTORY: 'No command history yet.',
+    DEV_ERROR_READING_HISTORY: (error) => `Error reading history: ${error}`,
+    DEV_TOOL_CALLING: (name) => `🔧 Calling tool: ${name}`,
+    DEV_TOOL_COMPLETED: (name, duration) => `✅ Tool ${name} completed${duration ? ` (${duration}ms)` : ''}`,
+    DEV_ERROR_START: 'Failed to start dev mode',
+    DEV_GOODBYE: '\n\nGoodbye! 👋',
+    // Doctor Command Messages
+    DOCTOR_SCRIPT_MISSING: 'script is missing',
+    DOCTOR_COMMAND_NOT_FOUND: (command) => `Command "${command}" not found in PATH`,
+    DOCTOR_COMMAND_INSTALL: (command) => `Make sure "${command}" is installed and available in your PATH`,
+    DOCTOR_SCRIPT_WORKING: 'working',
+    DOCTOR_SCRIPT_INFO: (script) => `Script: ${script}`,
+    DOCTOR_MCP_URL_INFO: (url) => `MCP URL: ${String(url)}`,
+    // List Command Messages
+    LIST_INVALID_TYPE: (type) => `Invalid list type: ${type}`,
+    LIST_VALID_TYPES: 'Valid types are: tools, resources, prompts',
+    LIST_ERROR_FAILED: (type) => `Failed to list ${type}`,
+    LIST_SOURCE_CONFIG: ' (from config.yaml)',
+    LIST_SOURCE_CLI_URL: ' (from --url)',
+    // Prompt Validation Messages
+    PROMPT_PROJECT_NAME_REQUIRED: 'Project name is required',
+    PROMPT_PROJECT_NAME_INVALID: 'Project name can only contain letters, numbers, and hyphens',
+    PROMPT_AGENT_NAME_REQUIRED: 'Agent name is required',
+    PROMPT_MCP_URL_REQUIRED: 'MCP server URL is required for http transport',
+    PROMPT_URL_INVALID: 'Invalid URL format',
+    PROMPT_SCRIPT_REQUIRED: 'Script command is required',
+    PROMPT_LLM_PROVIDER_REQUIRED: 'At least one LLM provider must be selected',
+    PROMPT_OPENAI_API_KEY_REQUIRED: 'OpenAI API key is required',
+    PROMPT_OPENAI_MODEL_REQUIRED: 'OpenAI model name is required',
+    PROMPT_CLAUDE_API_KEY_REQUIRED: 'Claude API key is required',
+    PROMPT_CLAUDE_MODEL_REQUIRED: 'Claude model name is required',
+    PROMPT_OLLAMA_MODEL_REQUIRED: 'Ollama model name is required',
+    // CLI Error Messages
+    CLI_START_FAILED: 'Failed to start CLI',
+    // Update/Rollback Messages
+    UPDATE_CHECKING: 'Checking for updates...',
+    UPDATE_CURRENT_VERSION: (version) => `Current version: ${version}`,
+    UPDATE_LATEST_VERSION: (version) => `Latest version: ${version}`,
+    UPDATE_ALREADY_LATEST: (version) => `Already on latest version: ${version}`,
+    UPDATE_IN_PROGRESS: (packageName) => `Updating ${packageName}...`,
+    UPDATE_SUCCESS: (version) => `Successfully updated to ${version}`,
+    UPDATE_FAILED: 'Update failed',
+    UPDATE_ERROR: (error) => `Error updating: ${error}`,
+    UPDATE_PERMISSION_HINT: (command) => `Permission denied. Try running: ${command}`,
+    ROLLBACK_IN_PROGRESS: (version, packageName) => `Rolling back ${packageName} to ${version}...`,
+    ROLLBACK_SUCCESS: (version) => `Successfully rolled back to ${version}`,
+    ROLLBACK_FAILED: 'Rollback failed',
+    ROLLBACK_ERROR: (error) => `Error rolling back: ${error}`,
+    ROLLBACK_INVALID_VERSION: (version) => `Invalid version format: ${version}. Expected format: 1.0.0 or v1.0.0`,
+    ROLLBACK_VERSION_NOT_FOUND: (version) => `Version ${version} not found on npm registry`,
+    ROLLBACK_CONFIRM: (currentVersion, targetVersion) => `Are you sure you want to rollback from ${currentVersion} to ${targetVersion}?`,
+    // Analyse Command Messages
+    ANALYSE_CONNECTING: 'Connecting to MCP server...',
+    ANALYSE_LOADING_TOOLS: 'Loading tools...',
+    ANALYSE_ANALYZING: 'Analyzing tools...',
+    ANALYSE_ERROR_FAILED: 'Failed to analyze MCP server',
+    ANALYSE_NO_TOOLS: 'No tools found in MCP server',
+    ANALYSE_VERDICT_PASS: 'Syrin analysis passed',
+    ANALYSE_VERDICT_FAIL: (errors, warnings) => `Syrin analysis failed (${errors} error${errors !== 1 ? 's' : ''}, ${warnings} warning${warnings !== 1 ? 's' : ''})`,
+    ANALYSE_VERDICT_PASS_WARNINGS: (warnings) => `Syrin analysis passed with ${warnings} warning${warnings !== 1 ? 's' : ''}`,
+    ANALYSE_ERRORS_HEADER: 'Errors:',
+    ANALYSE_WARNINGS_HEADER: 'Warnings:',
+    ANALYSE_SUGGESTIONS_HEADER: 'Suggestions:',
+};
+//# sourceMappingURL=messages.js.map

package/dist/constants/paths.d.ts

@@ -0,0 +1,29 @@
+/**
+ * File and directory path constants.
+ * Centralized paths used throughout the application.
+ */
+export declare const Paths: {
+    /** Syrin configuration directory name */
+    readonly SYRIN_DIR: ".syrin";
+    /** Configuration file name */
+    readonly CONFIG_FILE: "syrin.yaml";
+    /** Environment file name */
+    readonly ENV_FILE: ".env";
+    /** Full path to config file (relative to project root) */
+    readonly CONFIG_PATH: "syrin.yaml";
+    /** Full path to env file (relative to project root) */
+    readonly ENV_PATH: ".env";
+    /** Events directory (relative to project root) */
+    readonly EVENTS_DIR: ".syrin/events";
+    /** Dev history file (relative to project root) */
+    readonly DEV_HISTORY_FILE: ".syrin/.dev-history";
+    /** Data directory for JSON exports (relative to project root) */
+    readonly DATA_DIR: ".syrin/data";
+};
+/**
+ * File extension constants.
+ */
+export declare const FileExtensions: {
+    readonly JSONL: ".jsonl";
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/constants/paths.js

@@ -0,0 +1,29 @@
+/**
+ * File and directory path constants.
+ * Centralized paths used throughout the application.
+ */
+export const Paths = {
+    /** Syrin configuration directory name */
+    SYRIN_DIR: '.syrin',
+    /** Configuration file name */
+    CONFIG_FILE: 'syrin.yaml',
+    /** Environment file name */
+    ENV_FILE: '.env',
+    /** Full path to config file (relative to project root) */
+    CONFIG_PATH: 'syrin.yaml',
+    /** Full path to env file (relative to project root) */
+    ENV_PATH: '.env',
+    /** Events directory (relative to project root) */
+    EVENTS_DIR: '.syrin/events',
+    /** Dev history file (relative to project root) */
+    DEV_HISTORY_FILE: '.syrin/.dev-history',
+    /** Data directory for JSON exports (relative to project root) */
+    DATA_DIR: '.syrin/data',
+};
+/**
+ * File extension constants.
+ */
+export const FileExtensions = {
+    JSONL: '.jsonl',
+};
+//# sourceMappingURL=paths.js.map

package/dist/constants/transport.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Transport type constants.
+ */
+export declare const TransportTypes: {
+    readonly HTTP: "http";
+    readonly STDIO: "stdio";
+};
+export type TransportType = (typeof TransportTypes)[keyof typeof TransportTypes];
+//# sourceMappingURL=transport.d.ts.map

package/dist/constants/transport.js

@@ -0,0 +1,8 @@
+/**
+ * Transport type constants.
+ */
+export const TransportTypes = {
+    HTTP: 'http',
+    STDIO: 'stdio',
+};
+//# sourceMappingURL=transport.js.map

package/dist/events/emitter.d.ts

@@ -0,0 +1,64 @@
+import type { EventEnvelope } from '../events/types.js';
+import type { EventType } from '../events/event-type.js';
+import type { EventStore } from '../events/store.js';
+import type { SessionID, WorkflowID, PromptID } from '../types/ids.js';
+/**
+ * Event subscriber callback type.
+ * Called when an event is emitted, after it's been persisted to the store.
+ */
+export type EventSubscriber = (event: EventEnvelope) => void | Promise<void>;
+/**
+ * Event emitter interface.
+ * Supports both sync and async event stores.
+ */
+export interface EventEmitter {
+    /**
+     * Emit an event and append it to the event store.
+     * Returns the event envelope.
+     * For async stores, the promise resolves after the event is persisted.
+     */
+    emit<TPayload>(eventType: EventType, payload: TPayload): EventEnvelope<TPayload> | Promise<EventEnvelope<TPayload>>;
+    /**
+     * Subscribe to events.
+     * The callback will be called for all events emitted after subscription.
+     * Returns an unsubscribe function.
+     */
+    subscribe?(subscriber: EventSubscriber): () => void;
+}
+/**
+ * Runtime event emitter implementation.
+ * Handles event creation, sequencing, and persistence.
+ * Supports event subscribers for real-time event notifications.
+ */
+export declare class RuntimeEventEmitter implements EventEmitter {
+    private readonly store;
+    private readonly sessionId;
+    private readonly workflowId;
+    private readonly promptId;
+    private sequence;
+    private subscribers;
+    constructor(store: EventStore, sessionId: SessionID, workflowId: WorkflowID | null, promptId: PromptID | null);
+    emit<TPayload>(eventType: EventType, payload: TPayload): EventEnvelope<TPayload> | Promise<EventEnvelope<TPayload>>;
+    /**
+     * Get the current sequence number.
+     */
+    getSequence(): number;
+    /**
+     * Get the session ID.
+     */
+    getSessionId(): SessionID;
+    /**
+     * Subscribe to events.
+     * The callback will be called for all events emitted after subscription.
+     * Returns an unsubscribe function.
+     */
+    subscribe(subscriber: EventSubscriber): () => void;
+    /**
+     * Notify all subscribers of a new event.
+     * Errors in subscribers are logged but don't affect event emission.
+     * Subscribers are called synchronously for real-time updates.
+     */
+    private notifySubscribers;
+    private generateEventID;
+}
+//# sourceMappingURL=emitter.d.ts.map

package/dist/events/emitter.js

@@ -0,0 +1,142 @@
+import { makeEventID, makeTimestamp } from '../types/factories.js';
+import { logger } from '../utils/logger.js';
+import { EventStoreError } from '../utils/errors.js';
+/**
+ * Runtime event emitter implementation.
+ * Handles event creation, sequencing, and persistence.
+ * Supports event subscribers for real-time event notifications.
+ */
+export class RuntimeEventEmitter {
+    store;
+    sessionId;
+    workflowId;
+    promptId;
+    sequence = 0;
+    subscribers = [];
+    constructor(store, sessionId, workflowId, promptId) {
+        this.store = store;
+        this.sessionId = sessionId;
+        this.workflowId = workflowId;
+        this.promptId = promptId;
+    }
+    emit(eventType, payload) {
+        const event = {
+            event_id: makeEventID(this.generateEventID()),
+            event_type: eventType,
+            session_id: this.sessionId,
+            workflow_id: this.workflowId,
+            prompt_id: this.promptId,
+            timestamp: makeTimestamp(new Date().toISOString()),
+            sequence: ++this.sequence,
+            source: 'runtime',
+            payload,
+        };
+        try {
+            const appendResult = this.store.append(event);
+            // Handle both sync and async stores
+            if (appendResult instanceof Promise) {
+                return appendResult
+                    .then(() => {
+                    logger.debug(`Event emitted: ${eventType}`, {
+                        event_id: event.event_id,
+                        sequence: event.sequence,
+                    });
+                    // Notify subscribers after event is persisted
+                    this.notifySubscribers(event);
+                    return event;
+                })
+                    .catch((error) => {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    logger.error('Failed to persist event', err, {
+                        event_id: event.event_id,
+                        event_type: eventType,
+                    });
+                    throw new EventStoreError('Failed to persist event', {
+                        event,
+                        context: { event_type: eventType },
+                        cause: err,
+                    });
+                });
+            }
+            // Sync store
+            logger.debug(`Event emitted: ${eventType}`, {
+                event_id: event.event_id,
+                sequence: event.sequence,
+            });
+            // Notify subscribers after event is persisted
+            this.notifySubscribers(event);
+            return event;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            logger.error('Failed to emit event', err, {
+                event_id: event.event_id,
+                event_type: eventType,
+            });
+            throw new EventStoreError('Failed to emit event', {
+                event,
+                context: { event_type: eventType },
+                cause: err,
+            });
+        }
+    }
+    /**
+     * Get the current sequence number.
+     */
+    getSequence() {
+        return this.sequence;
+    }
+    /**
+     * Get the session ID.
+     */
+    getSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Subscribe to events.
+     * The callback will be called for all events emitted after subscription.
+     * Returns an unsubscribe function.
+     */
+    subscribe(subscriber) {
+        this.subscribers.push(subscriber);
+        // Return unsubscribe function
+        return () => {
+            this.subscribers = this.subscribers.filter(sub => sub !== subscriber);
+        };
+    }
+    /**
+     * Notify all subscribers of a new event.
+     * Errors in subscribers are logged but don't affect event emission.
+     * Subscribers are called synchronously for real-time updates.
+     */
+    notifySubscribers(event) {
+        // Notify subscribers synchronously for real-time visibility
+        // Errors are caught to prevent breaking event emission
+        for (const subscriber of this.subscribers) {
+            try {
+                const result = subscriber(event);
+                // Handle async subscribers
+                if (result instanceof Promise) {
+                    result.catch((error) => {
+                        const err = error instanceof Error ? error : new Error(String(error));
+                        logger.error('Error in event subscriber', err, {
+                            event_id: event.event_id,
+                            event_type: event.event_type,
+                        });
+                    });
+                }
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger.error('Error in event subscriber', err, {
+                    event_id: event.event_id,
+                    event_type: event.event_type,
+                });
+            }
+        }
+    }
+    generateEventID() {
+        return `${this.sessionId}-${this.sequence + 1}`;
+    }
+}
+//# sourceMappingURL=emitter.js.map

package/dist/events/event-type.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Event types organized by category.
+ * Total: 36 event types across 10 categories.
+ */
+export declare enum SessionLifecycleEventType {
+    SESSION_STARTED = "SESSION_STARTED",
+    PROMPT_VARIANT_STARTED = "PROMPT_VARIANT_STARTED",
+    SESSION_COMPLETED = "SESSION_COMPLETED",
+    SESSION_HALTED = "SESSION_HALTED",
+    WORKFLOW_RUN_SUMMARY = "WORKFLOW_RUN_SUMMARY"
+}
+export declare enum WorkflowEventType {
+    WORKFLOW_DEFINED = "WORKFLOW_DEFINED",
+    STEP_STARTED = "STEP_STARTED",
+    STEP_COMPLETED = "STEP_COMPLETED",
+    STEP_BLOCKED = "STEP_BLOCKED",
+    STEP_SKIPPED = "STEP_SKIPPED"
+}
+export declare enum LLMContextEventType {
+    LLM_CONTEXT_BUILT = "LLM_CONTEXT_BUILT",
+    POST_TOOL_LLM_PROMPT_BUILT = "POST_TOOL_LLM_PROMPT_BUILT"
+}
+export declare enum LLMProposalEventType {
+    LLM_PROPOSED_ACTION = "LLM_PROPOSED_ACTION",
+    LLM_PROPOSED_TOOL_CALL = "LLM_PROPOSED_TOOL_CALL",
+    LLM_FINAL_RESPONSE_GENERATED = "LLM_FINAL_RESPONSE_GENERATED"
+}
+export declare enum ValidationEventType {
+    TOOL_CALL_VALIDATION_STARTED = "TOOL_CALL_VALIDATION_STARTED",
+    TOOL_CALL_VALIDATION_PASSED = "TOOL_CALL_VALIDATION_PASSED",
+    TOOL_CALL_VALIDATION_FAILED = "TOOL_CALL_VALIDATION_FAILED",
+    CALL_BUDGET_EXCEEDED = "CALL_BUDGET_EXCEEDED",
+    TOOL_LOOP_DETECTED = "TOOL_LOOP_DETECTED"
+}
+export declare enum ToolExecutionEventType {
+    TOOL_EXECUTION_STARTED = "TOOL_EXECUTION_STARTED",
+    TOOL_EXECUTION_COMPLETED = "TOOL_EXECUTION_COMPLETED",
+    TOOL_EXECUTION_FAILED = "TOOL_EXECUTION_FAILED"
+}
+export declare enum TransportEventType {
+    TRANSPORT_INITIALIZED = "TRANSPORT_INITIALIZED",
+    TRANSPORT_MESSAGE_SENT = "TRANSPORT_MESSAGE_SENT",
+    TRANSPORT_MESSAGE_RECEIVED = "TRANSPORT_MESSAGE_RECEIVED",
+    TRANSPORT_ERROR = "TRANSPORT_ERROR"
+}
+export declare enum ToolRegistryEventType {
+    TOOL_REGISTRY_LOADED = "TOOL_REGISTRY_LOADED",
+    TOOL_REGISTERED = "TOOL_REGISTERED",
+    TOOL_REGISTRATION_FAILED = "TOOL_REGISTRATION_FAILED",
+    TOOL_AVAILABILITY_CHECKED = "TOOL_AVAILABILITY_CHECKED"
+}
+export declare enum TestingEventType {
+    ASSERTION_PASSED = "ASSERTION_PASSED",
+    ASSERTION_FAILED = "ASSERTION_FAILED"
+}
+export declare enum DiagnosticEventType {
+    RUNTIME_ERROR = "RUNTIME_ERROR",
+    ADAPTER_ERROR = "ADAPTER_ERROR",
+    CONTEXT_MUTATION_APPLIED = "CONTEXT_MUTATION_APPLIED"
+}
+/**
+ * Union type of all event types.
+ * This is the canonical EventType used throughout the system.
+ */
+export type EventType = SessionLifecycleEventType | WorkflowEventType | LLMContextEventType | LLMProposalEventType | ValidationEventType | ToolExecutionEventType | TransportEventType | ToolRegistryEventType | TestingEventType | DiagnosticEventType;
+//# sourceMappingURL=event-type.d.ts.map