@reactive-skills/runtime 0.1.0

package/dist/core/types.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+/**
+ * Zod Schema for validation of skill.yaml
+ */
+export const TransitionSchema = z.union([
+    z.string(),
+    z.object({
+        target: z.string(),
+        guard: z.string().optional(),
+        guardFunction: z.string().optional(),
+        description: z.string().optional(),
+        invoke: z.string().optional(),
+    }),
+]);
+export const StateLifecycleActionSchema = z.object({
+    emit_signal: z.string().optional(),
+    set_context: z.record(z.any()).optional(),
+    action: z.string().optional(),
+});
+export const HumanGateSchema = z.object({
+    type: z.enum(['approval', 'choice', 'text', 'visual_review', 'form']),
+    tool: z.string().optional(),
+    prompt: z.string().optional(),
+    options: z.array(z.string()).optional(),
+    auto_stop: z.boolean().optional(),
+});
+export const StateSchema = z.lazy(() => z.object({
+    description: z.string().optional(),
+    prompt_template: z.string().optional(),
+    tools: z.array(z.string()).optional(),
+    human_gate: HumanGateSchema.optional(),
+    on_enter: z.array(StateLifecycleActionSchema).optional(),
+    on_exit: z.array(StateLifecycleActionSchema).optional(),
+    transitions: z.record(TransitionSchema).optional(),
+    substates: z.record(StateSchema).optional(),
+    initial_substate: z.string().optional(),
+    max_idle_turns: z.number().int().positive().optional(),
+    bypass_target: z.string().optional(),
+}));
+export const SkillManifestSchema = z.object({
+    schema_version: z.string(),
+    name: z.string(),
+    version: z.string().optional(),
+    description: z.string(),
+    initial_state: z.string(),
+    strict_execution: z.boolean().optional(),
+    context_keys: z.array(z.string()).optional(),
+    default_context: z.record(z.any()).optional(),
+    states: z.record(StateSchema),
+    deliverable_projections: z.array(z.object({
+        template: z.string(),
+        output: z.string(),
+        trigger_on: z.array(z.string()).optional(),
+    })).optional(),
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './core/types.js';
+export * from './core/event-store.js';
+export * from './core/guard-evaluator.js';
+export * from './core/projection-engine.js';
+export * from './core/fsm-engine.js';
+export * from './core/runtime-hooks.js';
+export * from './core/legacy-adapter.js';
+export * from './core/migration.js';
+export * from './mcp/server.js';
+export * from './sync/types.js';
+export { runSync } from './sync/engine.js';
+export { syncEngineCommand } from './sync/cli.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from './core/types.js';
+export * from './core/event-store.js';
+export * from './core/guard-evaluator.js';
+export * from './core/projection-engine.js';
+export * from './core/fsm-engine.js';
+export * from './core/runtime-hooks.js';
+export * from './core/legacy-adapter.js';
+export * from './core/migration.js';
+export * from './mcp/server.js';
+export * from './sync/types.js';
+export { runSync } from './sync/engine.js';
+export { syncEngineCommand } from './sync/cli.js';

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ReactiveMcpServerOptions {
+    workspaceDir?: string;
+    defaultSkill?: string;
+}
+export declare function createReactiveMcpServer(options?: ReactiveMcpServerOptions): McpServer;
+export declare function runMcpServer(options?: ReactiveMcpServerOptions): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,453 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import yaml from 'js-yaml';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { FSMEngine } from '../core/fsm-engine.js';
+import { EventStore } from '../core/event-store.js';
+import { SkillManifestSchema } from '../core/types.js';
+export function createReactiveMcpServer(options = {}) {
+    const workspaceDir = options.workspaceDir || process.cwd();
+    let defaultSkill = options.defaultSkill || 'synthesis';
+    const server = new McpServer({
+        name: 'reactive-skills-server',
+        version: '1.0.0',
+    });
+    // Cached active engine instance per skill
+    const engines = new Map();
+    function normalizeDeliverableName(name) {
+        const trimmed = String(name || '').trim();
+        if (!trimmed || trimmed.includes('..') || trimmed.includes('/') || trimmed.includes('\\')) {
+            return null;
+        }
+        if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) {
+            return null;
+        }
+        return trimmed;
+    }
+    function getEngine(skillName = defaultSkill) {
+        if (engines.has(skillName)) {
+            return engines.get(skillName);
+        }
+        const candidatePaths = [
+            path.resolve(workspaceDir, 'skills', skillName),
+            path.resolve(workspaceDir, skillName),
+            path.join(os.homedir(), '.agents', 'skills', skillName),
+            path.join(os.homedir(), '.gemini', 'config', 'skills', skillName),
+        ];
+        const skillDir = candidatePaths.find(p => fs.existsSync(p));
+        if (!skillDir) {
+            throw new Error(`Skill '${skillName}' not found in workspace or global registry.`);
+        }
+        const eventStore = new EventStore({
+            workspaceDir,
+            skillId: skillName,
+            enableSqlite: true,
+        });
+        const engine = new FSMEngine({ skillDir, workspaceDir, eventStore });
+        engines.set(skillName, engine);
+        return engine;
+    }
+    // 1. TOOL: reactive_state
+    server.tool('reactive_state', 'Get current state, prompt slice, and allowed tools for the active reactive skill', {
+        skill: z.string().optional().describe('Skill name (defaults to active skill)'),
+    }, async ({ skill }) => {
+        try {
+            const engine = getEngine(skill || defaultSkill);
+            if (engine.isBypassDetected()) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'BYPASS_DETECTED: The runtime has auto-aborted this skill. Agent exceeded idle turns without emitting a signal.',
+                                recovery: 'Run reactive-skills-axi reset ' + engine.getManifest().name + ' then re-invoke.',
+                                strict_execution: engine.isStrictExecution(),
+                                turns_since_last_signal: engine.getTurnsSinceLastSignal(),
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (engine.isStrictExecution()) {
+                engine.recordTurnStart();
+            }
+            const slice = engine.generatePromptSlice();
+            const activeState = engine.getCurrentState();
+            const isWaiting = engine.isWaitingForHuman();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            skill: engine.getManifest().name,
+                            activeState,
+                            isWaitingForHuman: isWaiting,
+                            allowedTools: slice.allowedTools,
+                            promptSlice: slice.rawPrompt,
+                            formattedXml: slice.formattedXml,
+                            context: engine.getContext(),
+                            strict_execution: engine.isStrictExecution(),
+                            turns_since_last_signal: engine.getTurnsSinceLastSignal(),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            if (err.message?.startsWith('BYPASS_DETECTED')) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: err.message, recovery: 'Run reactive-skills-axi reset ' + (err.message.split('reset ')[1]?.split(' ')[0] || 'skill') + ' then re-invoke.' }) }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // 2. TOOL: reactive_emit_signal
+    server.tool('reactive_emit_signal', 'Emit an event signal into the reactive bus, evaluating transition guards and updating deliverable projections', {
+        signal: z.string().describe('Signal name (e.g. CHECK_PASSED, CHARTER_DRAFTED)'),
+        payload: z.record(z.any()).optional().describe('Signal payload data (e.g. exit_code, file_path)'),
+        skill: z.string().optional().describe('Target skill name'),
+    }, async ({ signal, payload = {}, skill }) => {
+        try {
+            const engine = getEngine(skill || defaultSkill);
+            const result = await engine.handleSignal(signal, payload);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            transitioned: result.transitioned,
+                            previousState: result.previousState,
+                            newState: result.newState,
+                            isWaitingForHuman: engine.isWaitingForHuman(),
+                            projectionsWritten: result.deliverablesWritten,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // 3. TOOL: reactive_query (SQL on events.db)
+    server.tool('reactive_query', 'Execute a read-only SQL query against the SQLite event store (.reactive/events.db)', {
+        sql: z.string().describe('SQL query string (e.g. SELECT * FROM events ORDER BY seq DESC LIMIT 10)'),
+        skill: z.string().optional().describe('Skill context for event store'),
+    }, async ({ sql, skill }) => {
+        try {
+            const engine = getEngine(skill || defaultSkill);
+            const driver = engine.getEventStore().getSqliteDriver();
+            if (!driver) {
+                throw new Error('SQLite storage driver is not active.');
+            }
+            const rows = driver.querySql(sql);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(rows, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // Typed query surface for normal event inspection; raw SQL remains a legacy read-only escape hatch.
+    server.tool('reactive_query_events', 'Query events with bounded typed filters from the selected skill store', {
+        type: z.string().optional().describe('Event type filter'),
+        state: z.string().optional().describe('State filter'),
+        sinceSeq: z.number().int().nonnegative().optional().describe('Return events after this sequence'),
+        limit: z.number().int().positive().max(1000).optional().describe('Maximum number of events'),
+        skill: z.string().optional().describe('Skill context for event store'),
+    }, async ({ type, state, sinceSeq, limit, skill }) => {
+        try {
+            const engine = getEngine(skill || defaultSkill);
+            const rows = engine.getEventStore().query({ type, state, sinceSeq, limit });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // 4. TOOL: reactive_list_skills
+    server.tool('reactive_list_skills', 'List all available reactive skills in the workspace and global registry', {}, async () => {
+        const skillsFound = [];
+        const searchDirs = [
+            path.resolve(workspaceDir, 'skills'),
+            path.join(os.homedir(), '.agents', 'skills'),
+            path.join(os.homedir(), '.gemini', 'config', 'skills'),
+        ];
+        const seen = new Set();
+        for (const dir of searchDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || seen.has(entry.name))
+                    continue;
+                const skillYamlPath = path.join(dir, entry.name, 'skill.yaml');
+                if (fs.existsSync(skillYamlPath)) {
+                    try {
+                        const rawManifest = yaml.load(fs.readFileSync(skillYamlPath, 'utf8'));
+                        const manifest = SkillManifestSchema.parse(rawManifest);
+                        skillsFound.push({
+                            name: manifest.name,
+                            path: path.join(dir, entry.name),
+                            type: 'reactive',
+                            statesCount: Object.keys(manifest.states).length,
+                        });
+                        seen.add(entry.name);
+                    }
+                    catch {
+                        // Ignore invalid manifests
+                    }
+                }
+            }
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(skillsFound, null, 2),
+                },
+            ],
+        };
+    });
+    // 5. TOOL: reactive_inspect
+    server.tool('reactive_inspect', 'Inspect the full statechart, transitions, and guard criteria of a reactive skill', {
+        skill: z.string().optional().describe('Skill name to inspect'),
+    }, async ({ skill }) => {
+        try {
+            const engine = getEngine(skill || defaultSkill);
+            const manifest = engine.getManifest();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(manifest, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // 6. TOOL: reactive_invoke_skill
+    server.tool('reactive_invoke_skill', 'Invoke a child reactive skill or legacy SKILL.md, recording parent/child event provenance', {
+        skill: z.string().describe('Skill name or path to invoke'),
+    }, async ({ skill }) => {
+        try {
+            const engine = getEngine();
+            const result = await engine.invokeSkill(skill);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            invoked: true,
+                            skillId: result.skillId,
+                            currentState: result.currentState,
+                            promptSlice: result.promptSlice.rawPrompt,
+                            allowedTools: result.promptSlice.allowedTools,
+                            exitConditions: result.promptSlice.exitConditions,
+                            eventId: result.event.id,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // 6. TOOL: reactive_respond_human
+    server.tool('reactive_respond_human', 'Submit user approval or feedback to unpause a Human-in-the-Loop (HITL) gate', {
+        choice: z.string().describe('User selected choice (e.g. Approve Plan)'),
+        approved: z.boolean().optional().describe('Explicit approval boolean flag'),
+        feedback: z.string().optional().describe('Optional feedback text'),
+        skill: z.string().optional().describe('Target skill name'),
+    }, async ({ choice, approved = true, feedback, skill }) => {
+        try {
+            const engine = getEngine(skill || defaultSkill);
+            const signalsEmitted = [];
+            let transitioned = false;
+            let deliverablesWritten = [];
+            if (feedback) {
+                engine.updateContext({ user_feedback: feedback });
+            }
+            if (choice) {
+                engine.updateContext({ user_choice: choice });
+            }
+            if (choice || feedback) {
+                engine.recordDecision({
+                    choice: choice || '',
+                    feedback,
+                    approved,
+                });
+            }
+            const dispatch = async (signalName, payload) => {
+                signalsEmitted.push(signalName);
+                const res = await engine.handleSignal(signalName, payload, { source: 'human_ingress' });
+                if (res.transitioned)
+                    transitioned = true;
+                if (res.deliverablesWritten.length > 0)
+                    deliverablesWritten.push(...res.deliverablesWritten);
+            };
+            const responseData = { choice, approved, feedback };
+            await dispatch('USER_RESPONSE', responseData);
+            if (approved === true || (choice && /approve|yes|accept|confirm|proceed/i.test(choice))) {
+                await dispatch('USER_APPROVED', responseData);
+            }
+            else if (approved === false || (choice && /reject|no|abort|cancel/i.test(choice))) {
+                await dispatch('USER_REJECTED', responseData);
+            }
+            else if (choice && /revision|change|modify|fix/i.test(choice)) {
+                await dispatch('USER_REVISION_REQUESTED', responseData);
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            unpaused: true,
+                            transitioned,
+                            currentState: engine.getCurrentState(),
+                            projectionsWritten: deliverablesWritten,
+                            signalsEmitted,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // 7. TOOL: reactive_migrate
+    server.tool('reactive_migrate', 'Retroactively upgrade an existing project workspace to the latest Event Modeling and CQRS schema standards', {
+        targetDir: z.string().optional().describe('Project directory path (defaults to current workspace)'),
+    }, async ({ targetDir }) => {
+        try {
+            const resolved = targetDir ? path.resolve(workspaceDir, targetDir) : workspaceDir;
+            const relative = path.relative(workspaceDir, resolved);
+            if (relative.startsWith('..') || path.isAbsolute(relative)) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({ error: `targetDir escapes workspace directory: ${targetDir}` }) }],
+                    isError: true,
+                };
+            }
+            if (fs.existsSync(resolved)) {
+                const realWorkspace = fs.existsSync(workspaceDir) ? fs.realpathSync(workspaceDir) : workspaceDir;
+                const realResolved = fs.realpathSync(resolved);
+                const realRel = path.relative(realWorkspace, realResolved);
+                if (realRel.startsWith('..') || path.isAbsolute(realRel)) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ error: `targetDir escapes workspace directory: ${targetDir}` }) }],
+                        isError: true,
+                    };
+                }
+            }
+            const { ProjectMigrator } = await import('../core/migration.js');
+            const result = ProjectMigrator.migrate(resolved);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }],
+                isError: true,
+            };
+        }
+    });
+    // RESOURCE 1: reactive://events
+    server.resource('reactive-events', 'reactive://events', async (uri) => {
+        const store = new EventStore({ enableSqlite: true });
+        const events = store.getAll();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(events, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+    // RESOURCE 2: reactive://deliverables/{name}
+    server.resource('reactive-deliverable', new ResourceTemplate('reactive://deliverables/{name}', { list: undefined }), async (uri, { name }) => {
+        const rawName = Array.isArray(name) ? name[0] : name;
+        const safeName = normalizeDeliverableName(rawName || '');
+        if (!safeName) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: '# Invalid deliverable name',
+                        mimeType: 'text/markdown',
+                    },
+                ],
+            };
+        }
+        const docCandidates = [
+            path.resolve(workspaceDir, '.docs', 'synthesis', `${safeName}.md`),
+            path.resolve(workspaceDir, '.docs', `${safeName}.md`),
+            path.resolve(workspaceDir, `${safeName}.md`),
+        ];
+        const docPath = docCandidates.find(p => fs.existsSync(p));
+        const content = docPath ? fs.readFileSync(docPath, 'utf8') : `# Deliverable ${safeName} Not Found`;
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content,
+                    mimeType: 'text/markdown',
+                },
+            ],
+        };
+    });
+    return server;
+}
+export async function runMcpServer(options = {}) {
+    const server = createReactiveMcpServer(options);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stdio transport handles process.stdin/stdout directly
+}

package/dist/sync/cli.d.ts

@@ -0,0 +1 @@
+export declare function syncEngineCommand(args: string[]): Promise<string>;