@reactive-skills/runtime 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,4 +1,20 @@
 
+## [0.4.3] - 2026-09-14
+
+- feat(telemetry): embed standalone live web dashboard at GET / (4ffb3a9)
+- docs: add comprehensive job management documentation across readmes (e1a626a)
+- docs: add practical telemetry inspection and metrics querying guide (ef37fb6)
+- chore: release v0.4.2 (28c16b9)
+- feat(runtime): add in-engine telemetry, template caching, and performance budget verification (7dfae37)
+
+## [0.4.2] - 2026-09-14
+
+- feat(runtime): add in-engine telemetry, template caching, and performance budget verification (7dfae37)
+- feat(telemetry): record real-time transition_duration_ms, slice_duration_ms, and slice_tokens_est in STATE_TRANSITION events
+- feat(fsm): L1 Handlebars compiled template delegate cache for sub-millisecond prompt slicing
+- feat(alarms): emit PERF_DEGRADATION event on slice (>10ms) or transition (>25ms) threshold breaches
+- test(perf): add automated Vitest test suite enforcing P0 (<5ms) and P1 (<25ms) latency budgets
+
 ## [0.4.1] - 2026-09-14
 
 - feat(runtime,axi): add mcp job tools, template jobId context, and flexible jobs cli arguments (2b31451)

package/README.md

@@ -2,7 +2,7 @@
 
 Reactive Skills Architecture (RSA) core runtime — FSM engine, event store, guard evaluator, projection engine, job manager, and MCP server.
 
-> 🚀 **What's New in v0.4.1:** MCP job management tools (`reactive_switch_job`, `reactive_archive_job`), template-level `jobId` context, and `PERFORMANCE-STANDARDS.md`. [Read Full Release Notes →](https://github.com/Reactive-Skills/reactive-skills/releases/tag/v0.4.1) · [View Changelog](https://github.com/Reactive-Skills/reactive-skills/blob/main/CHANGELOG.md)
+> 🚀 **What's New in v0.4.2:** In-engine telemetry, sub-millisecond Handlebars template caching, automated performance budget tests, and degradation detection alarms. [Read Full Release Notes →](https://github.com/Reactive-Skills/reactive-skills/releases/tag/v0.4.2) · [View Changelog](https://github.com/Reactive-Skills/reactive-skills/blob/main/CHANGELOG.md)
 
 ## Installation
 
@@ -69,7 +69,46 @@ 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
 
+## Job & Run Management
+
+The runtime isolates execution runs through `JobManager`:
+
+```ts
+import { JobManager, FSMEngine } from '@reactive-skills/runtime';
+
+// 1. Manage isolated runs:
+const jobManager = new JobManager();
+jobManager.createJob('my-skill', { id: 'sprint-1', name: 'Sprint 1 Run', setActive: true });
+
+// 2. Instantiate engine targeted to a specific run:
+const engine = new FSMEngine({
+  skillDir: './skills/my-skill',
+  jobId: 'sprint-1',
+});
+
+// Deliverables automatically mirror to .docs/my-skill/jobs/sprint-1/ and canonical .docs/
+```
+
+## Performance & Telemetry
+
+The runtime captures execution telemetry and token estimates with zero latency penalty:
+
+```ts
+// 1. In-turn prompt slice telemetry:
+const slice = engine.generatePromptSlice();
+console.log(slice.metrics);
+// => { slice_duration_ms: 0.23, slice_tokens_est: 282, allowed_tools_count: 4 }
+
+// 2. State transition telemetry:
+const res = await engine.handleSignal('TEST_RAN', { exit_code: 0 });
+console.log(res.metrics);
+// => { transition_duration_ms: 1.05, slice_duration_ms: 0.23, slice_tokens_est: 282 }
+```
+
+See [PERFORMANCE-STANDARDS.md](../../PERFORMANCE-STANDARDS.md) for full latency budgets and caching architecture.
+
 ## License
 
 MIT
 
+

package/dist/core/fsm-engine.d.ts

@@ -1,6 +1,5 @@
-import { SkillManifest, StateDefinition, SignalEvent, PromptSlice, EventContext, ChildRunSummary, DecisionRecord } from './types.js';
+import { SkillManifest, StateDefinition, SignalEvent, PromptSlice, ExecutionMetrics, EventContext, ChildRunSummary, DecisionRecord } from './types.js';
 import { EventStore } from './event-store.js';
-import { JobManager } from './job-manager.js';
 export interface FSMEngineOptions {
     skillDir: string;
     workspaceDir?: string;
@@ -10,6 +9,10 @@ export interface FSMEngineOptions {
     runId?: string;
     initialContext?: Record<string, any>;
     autoRehydrate?: boolean;
+    perfThresholds?: {
+        maxSliceDurationMs?: number;
+        maxTransitionDurationMs?: number;
+    };
 }
 export declare class FSMEngine {
     private skillDir;
@@ -28,6 +31,10 @@ export declare class FSMEngine {
     private jobId?;
     private isActiveJob;
     private jobManager;
+    private templateCache;
+    private lastSliceMetrics?;
+    private maxSliceDurationMs;
+    private maxTransitionDurationMs;
     constructor(options: FSMEngineOptions);
     /**
      * Rehydrate state machine state and context from immutable event history,
@@ -86,6 +93,7 @@ export declare class FSMEngine {
         event: SignalEvent;
         handledAtDepth?: number;
         deliverablesWritten: string[];
+        metrics?: ExecutionMetrics;
     }>;
     /**
      * Transition between two hierarchical paths executing exit, transition, and entry hooks
@@ -99,6 +107,7 @@ export declare class FSMEngine {
     private executeExitHook;
     getJobId(): string | undefined;
     isJobActive(): boolean;
-    getJobManager(): JobManager;
+    getLastMetrics(): ExecutionMetrics | undefined;
+    clearTemplateCache(): void;
     close(): void;
 }

package/dist/core/fsm-engine.js

@@ -28,6 +28,10 @@ export class FSMEngine {
     jobId;
     isActiveJob;
     jobManager;
+    templateCache = new Map();
+    lastSliceMetrics;
+    maxSliceDurationMs = 10;
+    maxTransitionDurationMs = 25;
     constructor(options) {
         this.skillDir = path.resolve(options.skillDir);
         this.workspaceDir = options.workspaceDir || process.cwd();
@@ -35,6 +39,12 @@ export class FSMEngine {
         this.strictExecution = this.manifest.strict_execution === true;
         this.turnsSinceLastSignal = 0;
         this.inBypassState = false;
+        if (options.perfThresholds?.maxSliceDurationMs !== undefined) {
+            this.maxSliceDurationMs = options.perfThresholds.maxSliceDurationMs;
+        }
+        if (options.perfThresholds?.maxTransitionDurationMs !== undefined) {
+            this.maxTransitionDurationMs = options.perfThresholds.maxTransitionDurationMs;
+        }
         const effectiveJobId = options.jobId || options.runId;
         this.jobManager = new JobManager(this.workspaceDir);
         const activeJobId = this.jobManager.getActiveJobId(this.manifest.name);
@@ -357,6 +367,7 @@ export class FSMEngine {
      * Generates the prompt slice for the active state hierarchy
      */
     generatePromptSlice() {
+        const startTime = performance.now();
         const activeLeaf = this.getStateDefinition(this.activeStatePath);
         if (!activeLeaf) {
             throw new Error(`Active state definition not found: ${this.getCurrentState()}`);
@@ -392,8 +403,12 @@ export class FSMEngine {
         }
         let rawPrompt = '';
         if (templatePath && fs.existsSync(templatePath)) {
-            const templateContent = fs.readFileSync(templatePath, 'utf8');
-            const compiled = Handlebars.compile(templateContent);
+            let compiled = this.templateCache.get(templatePath);
+            if (!compiled) {
+                const templateContent = fs.readFileSync(templatePath, 'utf8');
+                compiled = Handlebars.compile(templateContent);
+                this.templateCache.set(templatePath, compiled);
+            }
             rawPrompt = compiled({
                 state: this.getCurrentState(),
                 activeStatePath: this.activeStatePath,
@@ -458,6 +473,22 @@ export class FSMEngine {
             `  </transition_contracts>`,
             `</reactive_skill_state>`,
         ].filter(Boolean).join('\n');
+        const durationMs = Number((performance.now() - startTime).toFixed(3));
+        const estTokens = Math.ceil(formattedXml.length / 4);
+        const metrics = {
+            slice_duration_ms: durationMs,
+            slice_tokens_est: estTokens,
+            allowed_tools_count: allowedTools.length,
+        };
+        this.lastSliceMetrics = metrics;
+        if (durationMs > this.maxSliceDurationMs) {
+            this.eventStore.append('PERF_DEGRADATION', {
+                operation: 'generatePromptSlice',
+                duration_ms: durationMs,
+                threshold_ms: this.maxSliceDurationMs,
+                state: this.getCurrentState(),
+            }, { state: this.getCurrentState() });
+        }
         return {
             state: this.getCurrentState(),
             rawPrompt,
@@ -465,6 +496,7 @@ export class FSMEngine {
             allowedTools,
             context: { ...this.context },
             exitConditions,
+            metrics,
         };
     }
     /**
@@ -478,6 +510,7 @@ export class FSMEngine {
      * Process an incoming signal event, evaluating transitions with HSM bubbling and draining queued signals
      */
     async handleSignal(signalName, payload = {}, metadata = {}) {
+        const startTime = performance.now();
         const previousState = this.getCurrentState();
         const prevPath = [...this.activeStatePath];
         const event = this.eventStore.append('SIGNAL_EMITTED', { signal: signalName, ...payload }, { source: metadata.source, causationId: metadata.causationId, state: previousState });
@@ -531,8 +564,24 @@ export class FSMEngine {
                     // Parse target path (supports dot notation, e.g. "REFACTOR.EXTRACT_METHOD" or "GREEN_CODE")
                     const targetSegments = transDef.target.split('.');
                     const fullTargetPath = this.resolveInitialPath(targetSegments);
+                    const transitionDurationMs = Number((performance.now() - startTime).toFixed(3));
+                    const metrics = {
+                        transition_duration_ms: transitionDurationMs,
+                        slice_duration_ms: this.lastSliceMetrics?.slice_duration_ms,
+                        slice_tokens_est: this.lastSliceMetrics?.slice_tokens_est,
+                    };
+                    if (transitionDurationMs > this.maxTransitionDurationMs) {
+                        this.eventStore.append('PERF_DEGRADATION', {
+                            operation: 'handleSignal',
+                            duration_ms: transitionDurationMs,
+                            threshold_ms: this.maxTransitionDurationMs,
+                            signal: signalName,
+                            from: previousState,
+                            to: fullTargetPath.join('.'),
+                        }, { state: fullTargetPath.join('.') });
+                    }
                     // Execute exit hooks and entry hooks along the transition path
-                    this.transitionBetweenPaths(prevPath, fullTargetPath, signalName, event.id, payload);
+                    this.transitionBetweenPaths(prevPath, fullTargetPath, signalName, event.id, payload, metrics);
                     // PERF-02 / INV-08: Persist state snapshot for fast cold-boot rehydration
                     this.eventStore.saveSnapshot(this.eventStore.getLatestSequence(), this.getCurrentState(), this.context);
                     // Render deliverables
@@ -576,6 +625,7 @@ export class FSMEngine {
                         event,
                         handledAtDepth: depth,
                         deliverablesWritten,
+                        metrics,
                     };
                 }
             }
@@ -591,7 +641,7 @@ export class FSMEngine {
     /**
      * Transition between two hierarchical paths executing exit, transition, and entry hooks
      */
-    transitionBetweenPaths(fromPath, toPath, signalName, causationId, payload) {
+    transitionBetweenPaths(fromPath, toPath, signalName, causationId, payload, metrics) {
         // 1. Find Lowest Common Ancestor (LCA)
         let lcaDepth = 0;
         const maxDepth = Math.min(fromPath.length, toPath.length);
@@ -609,6 +659,7 @@ export class FSMEngine {
             to: toPath.join('.'),
             signal: signalName,
             payload,
+            metrics,
         }, {
             state: toPath.join('.'),
             causationId,
@@ -692,8 +743,11 @@ export class FSMEngine {
     isJobActive() {
         return this.isActiveJob;
     }
-    getJobManager() {
-        return this.jobManager;
+    getLastMetrics() {
+        return this.lastSliceMetrics;
+    }
+    clearTemplateCache() {
+        this.templateCache.clear();
     }
     close() {
         this.eventStore.close();

package/dist/core/types.d.ts

@@ -116,6 +116,16 @@ export interface SkillManifest {
     states: Record<string, StateDefinition>;
     deliverable_projections?: DeliverableProjection[];
 }
+/**
+ * Real-time execution performance metrics
+ */
+export interface ExecutionMetrics {
+    slice_duration_ms?: number;
+    slice_tokens_est?: number;
+    transition_duration_ms?: number;
+    allowed_tools_count?: number;
+    [key: string]: any;
+}
 /**
  * Hydrated prompt slice generated for an active LLM turn
  */
@@ -126,6 +136,7 @@ export interface PromptSlice {
     allowedTools: string[];
     context: Record<string, any>;
     exitConditions: string[];
+    metrics?: ExecutionMetrics;
 }
 /**
  * Zod Schema for validation of skill.yaml

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export { runSync } from './sync/engine.js';
 export { syncEngineCommand } from './sync/cli.js';
 export * from './telemetry/types.js';
 export * from './telemetry/server.js';
+export * from './telemetry/dashboard.js';

package/dist/index.js

@@ -13,3 +13,4 @@ export { runSync } from './sync/engine.js';
 export { syncEngineCommand } from './sync/cli.js';
 export * from './telemetry/types.js';
 export * from './telemetry/server.js';
+export * from './telemetry/dashboard.js';

package/dist/telemetry/dashboard.d.ts

@@ -0,0 +1,10 @@
+export interface DashboardOptions {
+    skillName?: string;
+    port: number;
+    host: string;
+}
+/**
+ * Generates a self-contained, zero-dependency HTML dashboard for the TelemetryServer.
+ * Provides live SSE event streaming, state & context inspection, and signal dispatching.
+ */
+export declare function renderDashboardHtml(options: DashboardOptions): string;