@reactive-skills/runtime 0.1.1 → 0.3.0

package/dist/core/types.d.ts

@@ -236,3 +236,37 @@ export declare const SkillManifestSchema: z.ZodObject<{
         trigger_on?: string[] | undefined;
     }[] | undefined;
 }>;
+export declare const JobStatusSchema: z.ZodEnum<["active", "completed", "failed", "archived"]>;
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+export declare const JobMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    skillId: z.ZodString;
+    status: z.ZodEnum<["active", "completed", "failed", "archived"]>;
+    currentState: z.ZodString;
+    parentRunId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    completedAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "completed" | "failed" | "active" | "archived";
+    name: string;
+    id: string;
+    skillId: string;
+    currentState: string;
+    createdAt: string;
+    updatedAt: string;
+    parentRunId?: string | undefined;
+    completedAt?: string | undefined;
+}, {
+    status: "completed" | "failed" | "active" | "archived";
+    name: string;
+    id: string;
+    skillId: string;
+    currentState: string;
+    createdAt: string;
+    updatedAt: string;
+    parentRunId?: string | undefined;
+    completedAt?: string | undefined;
+}>;
+export type JobMetadata = z.infer<typeof JobMetadataSchema>;

package/dist/core/types.js

@@ -53,3 +53,15 @@ export const SkillManifestSchema = z.object({
         trigger_on: z.array(z.string()).optional(),
     })).optional(),
 });
+export const JobStatusSchema = z.enum(['active', 'completed', 'failed', 'archived']);
+export const JobMetadataSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    skillId: z.string(),
+    status: JobStatusSchema,
+    currentState: z.string(),
+    parentRunId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    completedAt: z.string().optional(),
+});

package/dist/index.d.ts

@@ -6,7 +6,10 @@ 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 './core/job-manager.js';
 export * from './mcp/server.js';
 export * from './sync/types.js';
 export { runSync } from './sync/engine.js';
 export { syncEngineCommand } from './sync/cli.js';
+export * from './telemetry/types.js';
+export * from './telemetry/server.js';

package/dist/index.js

@@ -6,7 +6,10 @@ 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 './core/job-manager.js';
 export * from './mcp/server.js';
 export * from './sync/types.js';
 export { runSync } from './sync/engine.js';
 export { syncEngineCommand } from './sync/cli.js';
+export * from './telemetry/types.js';
+export * from './telemetry/server.js';

package/dist/mcp/server.js

@@ -7,6 +7,7 @@ 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 { JobManager } from '../core/job-manager.js';
 import { SkillManifestSchema } from '../core/types.js';
 export function createReactiveMcpServer(options = {}) {
     const workspaceDir = options.workspaceDir || process.cwd();
@@ -15,7 +16,7 @@ export function createReactiveMcpServer(options = {}) {
         name: 'reactive-skills-server',
         version: '1.0.0',
     });
-    // Cached active engine instance per skill
+    // Cached active engine instance per skill and job
     const engines = new Map();
     function normalizeDeliverableName(name) {
         const trimmed = String(name || '').trim();
@@ -27,13 +28,16 @@ export function createReactiveMcpServer(options = {}) {
         }
         return trimmed;
     }
-    function getEngine(skillName = defaultSkill) {
-        if (engines.has(skillName)) {
-            const cached = engines.get(skillName);
+    function getEngine(skillName = defaultSkill, jobId) {
+        const jobManager = new JobManager(workspaceDir);
+        const resolvedJobId = jobId || jobManager.getActiveJobId(skillName);
+        const cacheKey = `${skillName}::${resolvedJobId}`;
+        if (engines.has(cacheKey)) {
+            const cached = engines.get(cacheKey);
             if (fs.existsSync(cached.getSkillDir())) {
                 return cached;
             }
-            engines.delete(skillName);
+            engines.delete(cacheKey);
         }
         const candidatePaths = [
             path.resolve(workspaceDir, 'skills', skillName),
@@ -74,18 +78,26 @@ export function createReactiveMcpServer(options = {}) {
         const eventStore = new EventStore({
             workspaceDir,
             skillId: skillName,
+            jobId: resolvedJobId,
+            runId: resolvedJobId,
             enableSqlite: true,
         });
-        const engine = new FSMEngine({ skillDir, workspaceDir, eventStore });
-        engines.set(skillName, engine);
+        const engine = new FSMEngine({
+            skillDir,
+            workspaceDir,
+            eventStore,
+            jobId: resolvedJobId,
+        });
+        engines.set(cacheKey, 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 }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             if (engine.isBypassDetected()) {
                 return {
                     content: [
@@ -114,6 +126,7 @@ export function createReactiveMcpServer(options = {}) {
                         type: 'text',
                         text: JSON.stringify({
                             skill: engine.getManifest().name,
+                            job_id: engine.getJobId(),
                             activeState,
                             isWaitingForHuman: isWaiting,
                             allowedTools: slice.allowedTools,
@@ -145,15 +158,18 @@ export function createReactiveMcpServer(options = {}) {
         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 }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ signal, payload = {}, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const result = await engine.handleSignal(signal, payload);
             return {
                 content: [
                     {
                         type: 'text',
                         text: JSON.stringify({
+                            skill: engine.getManifest().name,
+                            job_id: engine.getJobId(),
                             transitioned: result.transitioned,
                             previousState: result.previousState,
                             newState: result.newState,
@@ -175,9 +191,10 @@ export function createReactiveMcpServer(options = {}) {
     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 }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ sql, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const driver = engine.getEventStore().getSqliteDriver();
             if (!driver) {
                 throw new Error('SQLite storage driver is not active.');
@@ -206,9 +223,10 @@ export function createReactiveMcpServer(options = {}) {
         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 }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ type, state, sinceSeq, limit, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const rows = engine.getEventStore().query({ type, state, sinceSeq, limit });
             return {
                 content: [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
@@ -268,9 +286,10 @@ export function createReactiveMcpServer(options = {}) {
     // 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 }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const manifest = engine.getManifest();
             return {
                 content: [
@@ -319,15 +338,16 @@ export function createReactiveMcpServer(options = {}) {
             };
         }
     });
-    // 6. TOOL: reactive_respond_human
+    // 7. 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 }) => {
+        job_id: z.string().optional().describe('Optional job/run ID (defaults to active job)'),
+    }, async ({ choice, approved = true, feedback, skill, job_id }) => {
         try {
-            const engine = getEngine(skill || defaultSkill);
+            const engine = getEngine(skill || defaultSkill, job_id);
             const signalsEmitted = [];
             let transitioned = false;
             let deliverablesWritten = [];
@@ -427,6 +447,35 @@ export function createReactiveMcpServer(options = {}) {
             };
         }
     });
+    // 9. TOOL: reactive_list_jobs
+    server.tool('reactive_list_jobs', 'List all historical and active execution jobs for a skill with status metadata', {
+        skill: z.string().optional().describe('Skill name (defaults to active skill)'),
+    }, async ({ skill }) => {
+        try {
+            const targetSkill = skill || defaultSkill;
+            const jobManager = new JobManager(workspaceDir);
+            const activeJobId = jobManager.getActiveJobId(targetSkill);
+            const jobs = jobManager.listJobs(targetSkill);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            skill: targetSkill,
+                            activeJobId,
+                            jobs,
+                        }, 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 });

package/dist/telemetry/server.d.ts

@@ -0,0 +1,31 @@
+import { TelemetryServerOptions } from './types.js';
+export declare class TelemetryServer {
+    private server;
+    private eventStore;
+    private fsmEngine?;
+    private port;
+    private host;
+    private heartbeatIntervalMs;
+    private skillName?;
+    private startTime;
+    private activeClients;
+    private activeSockets;
+    private unsubscribeEventStore?;
+    constructor(options: TelemetryServerOptions);
+    getPort(): number;
+    getUrl(): string;
+    start(): Promise<{
+        port: number;
+        url: string;
+    }>;
+    stop(): Promise<void>;
+    private setCorsHeaders;
+    private handleRequest;
+    private handleHealth;
+    private handleState;
+    private handleEventsHistory;
+    private handleSseEvents;
+    private sendSseEvent;
+    private broadcastEvent;
+    private handleSignal;
+}

package/dist/telemetry/server.js

@@ -0,0 +1,275 @@
+import http from 'node:http';
+import { URL } from 'node:url';
+export class TelemetryServer {
+    server = null;
+    eventStore;
+    fsmEngine;
+    port;
+    host;
+    heartbeatIntervalMs;
+    skillName;
+    startTime = Date.now();
+    activeClients = new Set();
+    activeSockets = new Set();
+    unsubscribeEventStore;
+    constructor(options) {
+        this.eventStore = options.eventStore;
+        this.fsmEngine = options.fsmEngine;
+        this.port = options.port ?? 4242;
+        this.host = options.host ?? '127.0.0.1';
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15000;
+        this.skillName = options.skillName ?? (options.fsmEngine ? options.fsmEngine.getManifest().name : undefined);
+    }
+    getPort() {
+        if (!this.server)
+            return this.port;
+        const addr = this.server.address();
+        if (typeof addr === 'object' && addr !== null) {
+            return addr.port;
+        }
+        return this.port;
+    }
+    getUrl() {
+        return `http://${this.host}:${this.getPort()}`;
+    }
+    async start() {
+        if (this.server) {
+            return { port: this.getPort(), url: this.getUrl() };
+        }
+        this.server = http.createServer((req, res) => {
+            this.handleRequest(req, res);
+        });
+        this.server.on('connection', (socket) => {
+            this.activeSockets.add(socket);
+            socket.on('close', () => {
+                this.activeSockets.delete(socket);
+            });
+        });
+        // Subscribe to EventStore updates to broadcast to all connected SSE clients
+        this.unsubscribeEventStore = this.eventStore.subscribe((event) => {
+            this.broadcastEvent(event);
+        });
+        return new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(this.port, this.host, () => {
+                this.server.removeListener('error', reject);
+                const actualPort = this.getPort();
+                resolve({ port: actualPort, url: this.getUrl() });
+            });
+        });
+    }
+    async stop() {
+        if (this.unsubscribeEventStore) {
+            this.unsubscribeEventStore();
+            this.unsubscribeEventStore = undefined;
+        }
+        for (const client of this.activeClients) {
+            try {
+                client.end();
+            }
+            catch {
+                // ignore client close errors
+            }
+        }
+        this.activeClients.clear();
+        for (const socket of this.activeSockets) {
+            try {
+                socket.destroy();
+            }
+            catch {
+                // ignore socket destruction errors
+            }
+        }
+        this.activeSockets.clear();
+        if (this.server) {
+            const serverToClose = this.server;
+            this.server = null;
+            await new Promise((resolve, reject) => {
+                serverToClose.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+        }
+    }
+    setCorsHeaders(res) {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Private-Network', 'true');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Last-Event-ID, Cache-Control');
+    }
+    handleRequest(req, res) {
+        this.setCorsHeaders(res);
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const hostHeader = req.headers.host || `${this.host}:${this.port}`;
+        const parsedUrl = new URL(req.url || '/', `http://${hostHeader}`);
+        const pathname = parsedUrl.pathname;
+        if (req.method === 'GET' && (pathname === '/health' || pathname === '/status')) {
+            this.handleHealth(res);
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/state') {
+            this.handleState(res);
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/events/history') {
+            this.handleEventsHistory(parsedUrl, res);
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/events') {
+            this.handleSseEvents(req, parsedUrl, res);
+            return;
+        }
+        if (req.method === 'POST' && pathname === '/signal') {
+            this.handleSignal(req, res);
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `Not found: ${pathname}` }));
+    }
+    handleHealth(res) {
+        const payload = {
+            status: 'ok',
+            skillName: this.skillName,
+            latestSeq: this.eventStore.getLatestSequence(),
+            uptimeSeconds: Math.floor((Date.now() - this.startTime) / 1000),
+        };
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(payload));
+    }
+    handleState(res) {
+        const latestSeq = this.eventStore.getLatestSequence();
+        const snapshot = this.eventStore.getLatestSnapshot();
+        const activeState = this.fsmEngine ? this.fsmEngine.getCurrentState() : snapshot?.state;
+        const context = this.fsmEngine ? this.fsmEngine.getContext() : snapshot?.context;
+        const payload = {
+            skillName: this.skillName,
+            latestSeq,
+            activeState,
+            context,
+            snapshot,
+        };
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(payload));
+    }
+    handleEventsHistory(url, res) {
+        const sinceSeqParam = url.searchParams.get('sinceSeq');
+        const limitParam = url.searchParams.get('limit');
+        const sinceSeq = sinceSeqParam !== null ? parseInt(sinceSeqParam, 10) : undefined;
+        const limit = limitParam !== null ? parseInt(limitParam, 10) : undefined;
+        let events;
+        if (sinceSeq !== undefined && !isNaN(sinceSeq)) {
+            events = this.eventStore.getSince(sinceSeq);
+        }
+        else {
+            events = this.eventStore.getAll();
+        }
+        if (limit !== undefined && !isNaN(limit) && limit > 0) {
+            events = events.slice(-limit);
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ count: events.length, events }));
+    }
+    handleSseEvents(req, url, res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no',
+        });
+        this.activeClients.add(res);
+        // Initial greeting / connect event
+        res.write(`event: connected\ndata: ${JSON.stringify({ skillName: this.skillName, connectedAt: new Date().toISOString() })}\n\n`);
+        // Determine initial backlog sequence
+        const sinceSeqParam = url.searchParams.get('sinceSeq') || req.headers['last-event-id'];
+        if (sinceSeqParam) {
+            const sinceSeq = parseInt(sinceSeqParam, 10);
+            if (!isNaN(sinceSeq)) {
+                const backlog = this.eventStore.getSince(sinceSeq);
+                for (const event of backlog) {
+                    this.sendSseEvent(res, event);
+                }
+            }
+        }
+        // Keepalive heartbeat
+        const heartbeatTimer = setInterval(() => {
+            try {
+                res.write(': heartbeat\n\n');
+            }
+            catch {
+                clearInterval(heartbeatTimer);
+            }
+        }, this.heartbeatIntervalMs);
+        req.on('close', () => {
+            clearInterval(heartbeatTimer);
+            this.activeClients.delete(res);
+        });
+    }
+    sendSseEvent(client, event) {
+        try {
+            client.write(`id: ${event.seq}\n`);
+            client.write(`event: signal_event\n`);
+            client.write(`data: ${JSON.stringify(event)}\n\n`);
+        }
+        catch {
+            this.activeClients.delete(client);
+        }
+    }
+    broadcastEvent(event) {
+        for (const client of this.activeClients) {
+            this.sendSseEvent(client, event);
+        }
+    }
+    handleSignal(req, res) {
+        let rawBody = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => {
+            rawBody += chunk;
+            if (rawBody.length > 1024 * 1024) {
+                // 1MB safety guard
+                res.writeHead(413, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Payload too large' }));
+                req.destroy();
+            }
+        });
+        req.on('end', async () => {
+            try {
+                const parsed = JSON.parse(rawBody || '{}');
+                if (!parsed.signal) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Missing required field: signal' }));
+                    return;
+                }
+                if (this.fsmEngine) {
+                    const transition = await this.fsmEngine.handleSignal(parsed.signal, parsed.payload || {});
+                    const response = {
+                        success: true,
+                        transition,
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(response));
+                }
+                else {
+                    // If no FSM engine attached, append signal directly to event store
+                    const event = this.eventStore.append(parsed.signal, parsed.payload || {}, { source: 'telemetry_bridge' });
+                    const response = {
+                        success: true,
+                        event: event,
+                    };
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(response));
+                }
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: err.message || 'Signal dispatch failure' }));
+            }
+        });
+    }
+}

package/dist/telemetry/types.d.ts

@@ -0,0 +1,57 @@
+import { EventStore } from '../core/event-store.js';
+import { FSMEngine } from '../core/fsm-engine.js';
+import { SignalEvent } from '../core/types.js';
+export interface TelemetryServerOptions {
+    /**
+     * EventStore instance to observe
+     */
+    eventStore: EventStore;
+    /**
+     * Optional FSMEngine instance for executing state transitions on HITL signals
+     */
+    fsmEngine?: FSMEngine;
+    /**
+     * Port to listen on (0 for ephemeral port, default: 4242)
+     */
+    port?: number;
+    /**
+     * Host to bind to (default: '127.0.0.1')
+     */
+    host?: string;
+    /**
+     * Interval for SSE keep-alive heartbeats in ms (default: 15000)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Skill identifier for health/metadata reporting
+     */
+    skillName?: string;
+}
+export interface TelemetryHealthResponse {
+    status: 'ok';
+    skillName?: string;
+    latestSeq: number;
+    uptimeSeconds: number;
+}
+export interface TelemetryStateResponse {
+    skillName?: string;
+    latestSeq: number;
+    activeState?: string;
+    context?: Record<string, any>;
+    snapshot?: {
+        seq: number;
+        state: string;
+        context: Record<string, any>;
+    } | null;
+}
+export interface TelemetrySignalRequest {
+    signal: string;
+    payload?: Record<string, any>;
+    context?: Record<string, any>;
+}
+export interface TelemetrySignalResponse {
+    success: boolean;
+    event?: SignalEvent;
+    transition?: any;
+    error?: string;
+}

package/dist/telemetry/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reactive-skills/runtime",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Reactive Skills Architecture (RSA) core runtime — FSM engine, event store, guard evaluator, projection engine, MCP server",
   "type": "module",
   "main": "dist/index.js",