@reactive-skills/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reactive Skills Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @reactive-skills/runtime
+
+Reactive Skills Architecture (RSA) core runtime - FSM engine, event store, guard evaluator, projection engine, and MCP server.
+
+## Installation
+
+```bash
+npm install @reactive-skills/runtime
+```
+
+## Usage
+
+```ts
+import { FSMEngine, EventStore, LegacySkillAdapter, ProjectionEngine } from '@reactive-skills/runtime';
+```
+
+## Core Modules
+
+- `FSMEngine` - Hierarchical State Machine loader, state path resolver, and signal-driven transition engine
+- `EventStore` - Immutable append-only event ledger (JSONL + SQLite)
+- `GuardEvaluator` - Sandbox evaluator for transition guard expressions
+- `ProjectionEngine` - Handlebars deliverable generator for read-model projections
+- `LegacySkillAdapter` - Backward compatibility wrapper and converter for SKILL.md
+- `McpServer` - Stdio Model Context Protocol (MCP) server integration
+
+## Skill Manifest Schema
+
+Reactive skills use `skill.yaml` with `schema_version: "2.0.0"`:
+
+```yaml
+schema_version: "2.0.0"
+name: "my-skill"
+description: "Skill description"
+initial_state: "START"
+
+context_keys:
+  - "project_type"
+  - "mission"
+
+states:
+  START:
+    description: "Initial state"
+    prompt_template: "states/start.md"
+    on_enter:
+      - set_context:
+          active_phase: "start"
+    transitions:
+      DONE:
+        target: "DONE"
+        guard: "event.payload.completed === true"
+```
+
+## Integration Modes
+
+The runtime has no dependency on any specific integration mode:
+
+1. **Direct API** - Import and use `FSMEngine` directly in your application
+2. **MCP stdio** - Use the `McpServer` class to expose tools over stdio
+3. **Legacy hooks (removed)** - `runtime-hooks.ts` was removed in v2.0. Use `on_enter`/`on_exit` lifecycle hooks and explicit `engine.handleSignal()` calls instead
+
+## Event Store
+
+Dual-mode event sourcing:
+
+1. **JSONL** (`.reactive/skills/<skill>/events.jsonl`) - Human-readable append-only log
+2. **SQLite** (`.reactive/skills/<skill>/events.db`) - Indexed relational database
+
+## License
+
+MIT
+

package/dist/cli/dev.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/dev.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+const args = process.argv.slice(2);
+const command = args[0];
+function printHelp() {
+    console.log(`
+reactive-skills-dev: Developer CLI for Reactive Skills Architecture
+
+Usage:
+  reactive-skills-dev init <name>         Scaffold new reactive skill in skills/<name>/
+  reactive-skills-dev upgrade <path>      Convert legacy SKILL.md to reactive format
+  reactive-skills-dev inspect <skill>     Print statechart, transitions, and guards
+  reactive-skills-dev migrate [path]      Retroactively migrate project to latest schema
+  reactive-skills-dev sync               Sync skills to all agent config directories
+  `);
+}
+async function main() {
+    if (!command || command === 'help' || command === '--help') {
+        printHelp();
+        return;
+    }
+    // INIT
+    if (command === 'init') {
+        const name = args[1];
+        if (!name) {
+            console.error(JSON.stringify({ error: 'Skill name required. Usage: reactive-skills-dev init <name>' }));
+            process.exit(1);
+        }
+        const skillDir = path.resolve(process.cwd(), 'skills', name);
+        fs.mkdirSync(path.join(skillDir, 'states'), { recursive: true });
+        fs.mkdirSync(path.join(skillDir, 'guards'), { recursive: true });
+        fs.mkdirSync(path.join(skillDir, 'templates'), { recursive: true });
+        const manifest = `name: ${name}\nversion: "1.0.0"\ndescription: "${name} reactive skill"\ninitial_state: INITIAL\nstates:\n  INITIAL:\n    description: "Starting state"\n    transitions: {}\n`;
+        fs.writeFileSync(path.join(skillDir, 'skill.yaml'), manifest, 'utf8');
+        fs.writeFileSync(path.join(skillDir, 'states', 'INITIAL.md'), `# State: INITIAL\n\nDescribe what the agent should do in this state.\n`, 'utf8');
+        console.log(`Scaffolded reactive skill '${name}' at skills/${name}/`);
+        return;
+    }
+    // UPGRADE
+    if (command === 'upgrade') {
+        const skillPath = args[1];
+        if (!skillPath) {
+            console.error(JSON.stringify({ error: 'Path required. Usage: reactive-skills-dev upgrade <path>' }));
+            process.exit(1);
+        }
+        const { LegacySkillAdapter } = await import('../core/legacy-adapter.js');
+        const targetDir = path.resolve(process.cwd(), skillPath);
+        const result = LegacySkillAdapter.upgradeToModular(targetDir);
+        console.log(`Upgraded legacy SKILL.md at ${targetDir}`);
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // INSPECT
+    if (command === 'inspect') {
+        const skillPath = args[1] && !args[1].startsWith('--') ? args[1] : 'skills/synthesis';
+        const targetDir = path.resolve(process.cwd(), skillPath);
+        const { FSMEngine } = await import('../core/fsm-engine.js');
+        const engine = new FSMEngine({ skillDir: targetDir });
+        const manifest = engine.getManifest();
+        const isJson = args.includes('--json');
+        if (isJson) {
+            console.log(JSON.stringify(manifest, null, 2));
+        }
+        else {
+            console.log(`\nReactive Skill: ${manifest.name} (v${manifest.version || '1.0.0'})`);
+            console.log(`Description: ${manifest.description}`);
+            console.log(`Initial State: ${manifest.initial_state}`);
+            console.log(`\nStates & Transitions:`);
+            for (const [sName, sDef] of Object.entries(manifest.states)) {
+                console.log(`  [${sName}]`);
+                if (sDef.transitions) {
+                    for (const [sig, trans] of Object.entries(sDef.transitions)) {
+                        const t = typeof trans === 'string' ? { target: trans } : trans;
+                        console.log(`    on '${sig}' -> ${t.target}${t.guard ? ` [guard: ${t.guard}]` : ''}`);
+                    }
+                }
+            }
+        }
+        return;
+    }
+    // MIGRATE
+    if (command === 'migrate') {
+        const targetPath = args[1] || process.cwd();
+        const { ProjectMigrator } = await import('../core/migration.js');
+        const result = ProjectMigrator.migrate(targetPath);
+        const isJson = args.includes('--json');
+        if (isJson) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`\nProject Migrated to ${result.schemaVersion}:`);
+            console.log(`Directory: ${result.projectDir}`);
+            for (const note of result.notes) {
+                console.log(`  - ${note}`);
+            }
+        }
+        return;
+    }
+    // SYNC (delegated to canonical sync engine)
+    if (command === 'sync') {
+        const { syncEngineCommand } = await import('../sync/cli.js');
+        const output = await syncEngineCommand(args.slice(1));
+        console.log(output);
+        return;
+    }
+    console.error(JSON.stringify({ error: `Unknown command: ${command}` }));
+    printHelp();
+    process.exit(1);
+}
+main().catch(err => {
+    console.error(JSON.stringify({ error: err.message }));
+    process.exit(1);
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { FSMEngine } from '../core/fsm-engine.js';
+import { EventStore } from '../core/event-store.js';
+const args = process.argv.slice(2);
+const command = args[0];
+const isJson = args.includes('--json');
+function printHelp() {
+    console.log(`
+⚡ reactive-skills: Agent Experience Interface for Reactive Skills
+
+Usage:
+  reactive-skills mcp                 Run the stdio Model Context Protocol (MCP) server
+  reactive-skills install <skill>     Install skill globally and sync
+  reactive-skills migrate [path]      Retroactively migrate project to latest schema
+  reactive-skills state [skill]       Get active state slice and prompt
+  reactive-skills emit <signal>       Emit signal and step state machine
+  reactive-skills query "<sql>"       Query SQLite event store
+  reactive-skills inspect <skill>     Inspect statechart and transitions
+  reactive-skills events [limit]      Tail event store ledger
+  reactive-skills sync                Sync skills across agent platforms
+  reactive-skills init <name>         Scaffold new reactive skill
+  reactive-skills upgrade <path>      Upgrade legacy SKILL.md
+  `);
+}
+async function main() {
+    if (!command || command === 'help' || command === '--help') {
+        printHelp();
+        return;
+    }
+    // 0. RUN MCP SERVER
+    if (command === 'mcp') {
+        const { runMcpServer } = await import('../mcp/server.js');
+        await runMcpServer();
+        return;
+    }
+    // 0.5 MIGRATE PROJECT RETROACTIVELY
+    if (command === 'migrate') {
+        const targetPath = args[1] || process.cwd();
+        const { ProjectMigrator } = await import('../core/migration.js');
+        const result = ProjectMigrator.migrate(targetPath);
+        if (isJson) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`\n🔄 Project Migrated to ${result.schemaVersion}:`);
+            console.log(`📁 Directory: ${result.projectDir}`);
+            for (const note of result.notes) {
+                console.log(`  • ${note}`);
+            }
+        }
+        return;
+    }
+    // 1. INSTALL SKILL GLOBALLY (delegated to sync engine for the sync step)
+    if (command === 'install') {
+        const skillName = args[1];
+        if (!skillName) {
+            console.error(JSON.stringify({ error: 'Skill name required. Usage: reactive-skills install <skill-name>' }));
+            process.exit(1);
+        }
+        const homeDir = os.homedir();
+        const sourceCandidates = [
+            path.resolve(process.cwd(), 'skills', skillName),
+            path.resolve(process.cwd(), skillName),
+            path.resolve(import.meta.dirname, '..', '..', 'skills', skillName),
+        ];
+        const sourceDir = sourceCandidates.find(d => fs.existsSync(d));
+        if (!sourceDir) {
+            console.error(JSON.stringify({ error: `Skill '${skillName}' not found in local workspace.` }));
+            process.exit(1);
+        }
+        const destAgent = path.join(homeDir, '.agents', 'skills', skillName);
+        fs.mkdirSync(path.dirname(destAgent), { recursive: true });
+        fs.mkdirSync(destAgent, { recursive: true });
+        // Copy skill using the canonical engine's copySkillDir (via runSync with single target)
+        const { runSync } = await import('../sync/engine.js');
+        const report = runSync({
+            sourceDir: path.dirname(sourceDir),
+            targetDirs: [path.join(homeDir, '.agents', 'skills')],
+            targetSkill: skillName,
+            dryRun: false,
+            backup: false,
+        });
+        if (report.errors.length > 0) {
+            console.error(JSON.stringify({ error: report.errors.join('; ') }));
+            process.exit(1);
+        }
+        if (isJson) {
+            console.log(JSON.stringify({ ok: true, skill: skillName, installedTo: [destAgent], synced: true }));
+        }
+        else {
+            console.log(`✅ Skill '${skillName}' installed to ${destAgent} and synced globally.`);
+        }
+        return;
+    }
+    // 2. GET ACTIVE STATE SLICE
+    if (command === 'state') {
+        const skillPath = args[1] && !args[1].startsWith('--') ? args[1] : path.resolve(process.cwd(), 'skills', 'synthesis');
+        const targetDir = path.resolve(process.cwd(), skillPath);
+        if (!fs.existsSync(targetDir)) {
+            console.error(JSON.stringify({ error: `Skill path not found: ${targetDir}` }));
+            process.exit(1);
+        }
+        const engine = new FSMEngine({ skillDir: targetDir });
+        if (engine.isStrictExecution()) {
+            engine.recordTurnStart();
+        }
+        const slice = engine.generatePromptSlice();
+        if (isJson) {
+            console.log(JSON.stringify(slice, null, 2));
+        }
+        else {
+            console.log(slice.formattedXml);
+        }
+        return;
+    }
+    // 3. EMIT SIGNAL
+    if (command === 'emit') {
+        const signalName = args[1];
+        if (!signalName) {
+            console.error(JSON.stringify({ error: 'Signal name required. Usage: reactive-skills emit <SIGNAL> [--payload JSON]' }));
+            process.exit(1);
+        }
+        let payload = {};
+        const payloadIdx = args.indexOf('--payload');
+        if (payloadIdx !== -1 && args[payloadIdx + 1]) {
+            try {
+                payload = JSON.parse(args[payloadIdx + 1]);
+            }
+            catch {
+                payload = { raw: args[payloadIdx + 1] };
+            }
+        }
+        const skillPath = path.resolve(process.cwd(), 'skills', 'synthesis');
+        const store = new EventStore({ enableSqlite: true, skillId: 'synthesis' });
+        const engine = new FSMEngine({ skillDir: skillPath, eventStore: store });
+        const result = await engine.handleSignal(signalName, payload);
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // 4. SQL QUERY ON EVENTS.DB
+    if (command === 'query') {
+        const sql = args[1];
+        if (!sql) {
+            console.error(JSON.stringify({ error: 'SQL query required. Usage: reactive-skills query "SELECT * FROM events"' }));
+            process.exit(1);
+        }
+        const store = new EventStore({ enableSqlite: true });
+        const driver = store.getSqliteDriver();
+        if (!driver) {
+            console.error(JSON.stringify({ error: 'SQLite driver not enabled in active event store.' }));
+            process.exit(1);
+        }
+        const rows = driver.querySql(sql);
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    // 5. INSPECT SKILL
+    if (command === 'inspect') {
+        const skillPath = args[1] && !args[1].startsWith('--') ? args[1] : 'skills/synthesis';
+        const targetDir = path.resolve(process.cwd(), skillPath);
+        const engine = new FSMEngine({ skillDir: targetDir });
+        const manifest = engine.getManifest();
+        if (isJson) {
+            console.log(JSON.stringify(manifest, null, 2));
+        }
+        else {
+            console.log(`\n⚡ Reactive Skill: ${manifest.name} (v${manifest.version || '1.0.0'})`);
+            console.log(`📖 Description: ${manifest.description}`);
+            console.log(`🏁 Initial State: ${manifest.initial_state}`);
+            console.log(`\n📋 States & Transitions:`);
+            for (const [sName, sDef] of Object.entries(manifest.states)) {
+                console.log(`  [State: ${sName}]`);
+                if (sDef.transitions) {
+                    for (const [sig, trans] of Object.entries(sDef.transitions)) {
+                        const t = typeof trans === 'string' ? { target: trans } : trans;
+                        console.log(`    • on '${sig}' -> ${t.target}${t.guard ? ` [guard: ${t.guard}]` : ''}`);
+                    }
+                }
+            }
+        }
+        return;
+    }
+    // 6. SYNC SKILLS (delegated to canonical sync engine)
+    if (command === 'sync') {
+        const { syncEngineCommand } = await import('../sync/cli.js');
+        const output = await syncEngineCommand(args.slice(1));
+        console.log(output);
+        return;
+    }
+    // 7. EVENTS
+    if (command === 'events') {
+        const limit = parseInt(args[1] || '20', 10);
+        const store = new EventStore();
+        const events = store.getAll();
+        const slice = events.slice(-limit);
+        if (isJson) {
+            console.log(JSON.stringify(slice, null, 2));
+        }
+        else {
+            console.log(`\n📜 Event Store Ledger (.reactive/events.jsonl) - Showing last ${slice.length} events:`);
+            for (const e of slice) {
+                console.log(`[#${e.seq}] ${e.timestamp} | ${e.type.padEnd(18)} | State: ${(e.state || '-').padEnd(14)} | ${JSON.stringify(e.payload)}`);
+            }
+        }
+        return;
+    }
+    printHelp();
+}
+main().catch(err => {
+    console.error('Error running reactive-skills:', err);
+    process.exit(1);
+});

package/dist/core/event-store.d.ts

@@ -0,0 +1,182 @@
+import { EventContext, SignalEvent } from './types.js';
+export declare const EVENT_STORE_SCHEMA_VERSION = 2;
+export type EventListener = (event: SignalEvent) => void;
+export declare function createSortableId(): string;
+export interface EventStoreOptions {
+    storagePath?: string;
+    sqlitePath?: string;
+    workspaceDir?: string;
+    skillId?: string;
+    runId?: string;
+    run_id?: string;
+    correlationId?: string;
+    correlation_id?: string;
+    requestId?: string;
+    request_id?: string;
+    traceParent?: string;
+    trace_parent?: string;
+    parentRunId?: string;
+    parent_run_id?: string;
+    schemaVersion?: string;
+    schema_version?: string;
+    inMemory?: boolean;
+    enableSqlite?: boolean;
+    maxInMemoryEvents?: number;
+    maxJsonlBytes?: number;
+}
+export interface EventQueryOptions {
+    type?: string;
+    state?: string;
+    sinceSeq?: number;
+    limit?: number;
+}
+/**
+ * SQLite Storage Driver for EventStore
+ * Provides ACID relational storage, indexing, and direct SQL querying
+ */
+export declare class SQLiteStorageDriver {
+    private db;
+    constructor(dbPath: string);
+    private initTables;
+    private ensureSchemaVersion;
+    private runMigrations;
+    insertEvent(event: SignalEvent): void;
+    beginTransaction(): void;
+    commitTransaction(): void;
+    queryEvents(options?: EventQueryOptions): SignalEvent[];
+    getLatestSequence(): number;
+    nextSequence(): number;
+    getRecentEvents(limit: number): SignalEvent[];
+    querySql(sql: string, params?: any[]): any[];
+    saveSnapshot(seq: number, state: string, context: Record<string, any>): void;
+    getLatestSnapshot(): {
+        seq: number;
+        state: string;
+        context: Record<string, any>;
+    } | null;
+    saveProjectionWatermark(name: string, eventSeq: number, projectionVersion: string): void;
+    getProjectionWatermark(name: string): {
+        eventSeq: number;
+        projectionVersion: string;
+    } | null;
+    saveProjection(name: string, content: string): void;
+    getProjection(name: string): string | null;
+    close(): void;
+    static getSchemaVersion(dbPath: string): number;
+    private rowToEvent;
+    clear(): void;
+    /**
+     * Purge every table including seq_counter so a rebuilt store starts from a
+     * clean slate. Used by EventStore.rebuildFromJsonl().
+     */
+    clearAll(): void;
+    /**
+     * Replace the entire events table with the supplied ordered list.
+     * Preserves caller-supplied seq numbers (JSONL heritage). seq_counter is
+     * reset to the max seq so future appends continue from the correct point.
+     */
+    rebuildEvents(orderedEvents: SignalEvent[]): void;
+}
+/**
+ * Immutable Append-Only Event Store
+ * All signals, tool results, guard evaluations, and state transitions are recorded here.
+ */
+export declare class EventStore {
+    private events;
+    private listeners;
+    private storagePath;
+    private sqliteDriver;
+    private sqlitePath;
+    private seqCounter;
+    private maxInMemoryEvents;
+    private eventContext;
+    private projectionWatermarks;
+    private latestSnapshot;
+    private maxJsonlBytes;
+    constructor(options?: EventStoreOptions);
+    private initializeStorage;
+    /**
+     * Scan all JSONL files for the authoritative max seq and event count.
+     * Returns { count: 0, maxSeq: 0 } when no JSONL is present.
+     */
+    private readJsonlStats;
+    /**
+     * Rebuild SQLite from JSONL. Reads every JSONL file, deduplicates by event
+     * id (keeping the highest seq on conflict), clears SQLite, and re-inserts
+     * in seq order preserving original seq numbers. seq_counter is reset to the
+     * max seq. In-memory state is left untouched; callers must refresh it.
+     */
+    rebuildFromJsonl(): number;
+    /**
+     * Read every event from every JSONL file (active + archived segments).
+     */
+    private readAllJsonlEvents;
+    /**
+     * Deduplicate events by id, keeping the entry with the highest seq.
+     */
+    private deduplicateById;
+    /**
+     * Backfill JSONL with events SQLite has that JSONL is missing. SQLite is
+     * authoritative; this keeps the audit log complete when a JSONL write
+     * failed mid-write. Best-effort: failures are logged, not thrown.
+     */
+    syncJsonlToSqlite(): number;
+    private getJsonlPaths;
+    private rotateJsonlIfNeeded;
+    /**
+       * Append a new event to the immutable log.
+       *
+       * SQLite is the authoritative store when enabled; JSONL is an append-only
+       * audit mirror that can optionally be checked into git. If JSONL mirroring
+       * fails the run stays live because SQLite already persisted the event.
+       */
+    append<T = Record<string, any>>(type: string, payload: T, metadata?: {
+        source?: string;
+        causationId?: string;
+        correlationId?: string;
+        requestId?: string;
+        traceParent?: string;
+        parentRunId?: string;
+        skillId?: string;
+        runId?: string;
+        state?: string;
+    }): SignalEvent<T>;
+    /**
+     * Subscribe to new events
+     */
+    subscribe(listener: EventListener): () => void;
+    /**
+     * Get all recorded events (delegates to SQLite if available, otherwise in-memory buffer)
+     */
+    getAll(): SignalEvent[];
+    getSince(seq: number): SignalEvent[];
+    getLatestSequence(): number;
+    getEventContext(): EventContext;
+    saveProjectionWatermark(name: string, eventSeq: number, projectionVersion: string): void;
+    getProjectionWatermark(name: string): {
+        eventSeq: number;
+        projectionVersion: string;
+    } | null;
+    saveSnapshot(seq: number, state: string, context: Record<string, any>): void;
+    getLatestSnapshot(): {
+        seq: number;
+        state: string;
+        context: Record<string, any>;
+    } | null;
+    /**
+     * Query recorded events (relational index in SQLite, or in-memory filter)
+     */
+    query(filter?: EventQueryOptions): SignalEvent[];
+    /**
+     * Close storage drivers and release file handles
+     */
+    close(): void;
+    /**
+     * Get SQLite driver instance if enabled
+     */
+    getSqliteDriver(): SQLiteStorageDriver | null;
+    /**
+     * Clear in-memory and file events (for test isolation)
+     */
+    clear(): void;
+}