@reactive-skills/runtime 0.1.0

package/dist/core/projection-engine.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Handlebars from 'handlebars';
+/**
+ * Deliverable Projection Engine (Event-Sourced Read Models)
+ * Synthesizes persistent deliverables continuously from the event log.
+ */
+export class ProjectionEngine {
+    skillDir;
+    workspaceDir;
+    projections;
+    compiledTemplates = new Map();
+    eventCaches = new WeakMap();
+    constructor(skillDir, projections = [], workspaceDir = process.cwd()) {
+        this.skillDir = skillDir;
+        this.workspaceDir = path.resolve(workspaceDir);
+        this.projections = projections;
+        this.registerHelpers();
+        this.compileTemplates();
+    }
+    resolveOutputPath(output) {
+        if (path.isAbsolute(output)) {
+            throw new Error('Projection output must be relative to the workspace.');
+        }
+        const outputPath = path.resolve(this.workspaceDir, output);
+        const relativePath = path.relative(this.workspaceDir, outputPath);
+        if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+            throw new Error('Projection output escapes the workspace.');
+        }
+        const outputDir = path.dirname(outputPath);
+        const existingDir = fs.existsSync(outputDir) ? fs.realpathSync(outputDir) : outputDir;
+        const realWorkspace = fs.realpathSync(this.workspaceDir);
+        const realRelativePath = path.relative(realWorkspace, existingDir);
+        if (realRelativePath.startsWith('..') || path.isAbsolute(realRelativePath)) {
+            throw new Error('Projection output resolves outside the workspace.');
+        }
+        if (fs.existsSync(outputPath)) {
+            const realOutput = fs.realpathSync(outputPath);
+            const outputRelativePath = path.relative(realWorkspace, realOutput);
+            if (outputRelativePath.startsWith('..') || path.isAbsolute(outputRelativePath)) {
+                throw new Error('Projection output resolves outside the workspace.');
+            }
+        }
+        return outputPath;
+    }
+    getProjectionEvents(eventStore) {
+        const latestSeq = eventStore.getLatestSequence();
+        const cached = this.eventCaches.get(eventStore);
+        if (!cached) {
+            const events = eventStore.getAll();
+            this.eventCaches.set(eventStore, { lastSeq: latestSeq, events });
+            return events;
+        }
+        if (latestSeq <= cached.lastSeq)
+            return cached.events;
+        const events = [...cached.events, ...eventStore.getSince(cached.lastSeq)];
+        this.eventCaches.set(eventStore, { lastSeq: latestSeq, events });
+        return events;
+    }
+    matchesTrigger(proj, triggerSignal) {
+        if (!proj.trigger_on || proj.trigger_on.length === 0)
+            return true;
+        return proj.trigger_on.includes('*') ||
+            proj.trigger_on.includes('STATE_TRANSITION') ||
+            Boolean(triggerSignal && proj.trigger_on.includes(triggerSignal));
+    }
+    registerHelpers() {
+        Handlebars.registerHelper('json', (context) => {
+            return JSON.stringify(context, null, 2);
+        });
+        Handlebars.registerHelper('eq', (a, b) => a === b);
+        Handlebars.registerHelper('gt', (a, b) => a > b);
+        Handlebars.registerHelper('lt', (a, b) => a < b);
+        Handlebars.registerHelper('formatDate', (dateStr) => {
+            if (!dateStr)
+                return '';
+            return new Date(dateStr).toISOString();
+        });
+    }
+    compileTemplates() {
+        for (const proj of this.projections) {
+            try {
+                const templatePath = path.resolve(this.skillDir, proj.template);
+                if (fs.existsSync(templatePath)) {
+                    const raw = fs.readFileSync(templatePath, 'utf8');
+                    this.compiledTemplates.set(proj.template, Handlebars.compile(raw));
+                }
+            }
+            catch (err) {
+                // Will be caught and reported gracefully during project()
+            }
+        }
+    }
+    /**
+     * Render all deliverables matching the given event trigger safely with an error boundary
+     */
+    project(eventStore, currentState, skillName, context, triggerSignal) {
+        const writtenFiles = [];
+        const latestSeq = eventStore.getLatestSequence();
+        const eligibleProjections = this.projections.filter(proj => this.matchesTrigger(proj, triggerSignal));
+        const unchanged = eligibleProjections.length > 0 && eligibleProjections.every(proj => {
+            const watermark = eventStore.getProjectionWatermark(proj.template);
+            return watermark?.eventSeq === latestSeq && watermark.projectionVersion === `${this.skillDir}:${proj.template}`;
+        });
+        if (unchanged)
+            return writtenFiles;
+        const events = this.getProjectionEvents(eventStore);
+        // Extract state transitions for convenient template consumption
+        const transitions = events
+            .filter(e => e.type === 'STATE_TRANSITION')
+            .map(e => ({
+            from: e.payload.from,
+            to: e.payload.to,
+            timestamp: e.timestamp,
+            signal: e.payload.signal,
+        }));
+        const projContext = {
+            skillName,
+            currentState,
+            context,
+            events,
+            transitions,
+            lastUpdated: new Date().toISOString(),
+        };
+        for (const proj of this.projections) {
+            try {
+                // Check if trigger matches
+                if (!this.matchesTrigger(proj, triggerSignal))
+                    continue;
+                let templateFn = this.compiledTemplates.get(proj.template);
+                if (!templateFn) {
+                    const templatePath = path.resolve(this.skillDir, proj.template);
+                    if (fs.existsSync(templatePath)) {
+                        const raw = fs.readFileSync(templatePath, 'utf8');
+                        templateFn = Handlebars.compile(raw);
+                        this.compiledTemplates.set(proj.template, templateFn);
+                    }
+                }
+                if (templateFn) {
+                    const outputContent = templateFn(projContext);
+                    const outputPath = this.resolveOutputPath(proj.output);
+                    const outputDir = path.dirname(outputPath);
+                    if (!fs.existsSync(outputDir)) {
+                        fs.mkdirSync(outputDir, { recursive: true });
+                    }
+                    fs.writeFileSync(outputPath, outputContent, 'utf8');
+                    writtenFiles.push(outputPath);
+                    eventStore.saveProjectionWatermark(proj.template, eventStore.getLatestSequence(), `${this.skillDir}:${proj.template}`);
+                }
+            }
+            catch (err) {
+                // Error boundary: Record projection failure without tearing down the state machine transition
+                try {
+                    eventStore.append('PROJECTION_FAILED', {
+                        template: proj.template,
+                        output: proj.output,
+                        error: err.message,
+                    });
+                }
+                catch {
+                    // Swallow secondary logging error
+                }
+            }
+        }
+        return writtenFiles;
+    }
+}

package/dist/core/runtime-hooks.d.ts

@@ -0,0 +1,51 @@
+import { FSMEngine } from './fsm-engine.js';
+import { PromptSlice } from './types.js';
+export interface InterceptorHookResult {
+    injectedPrompt: string;
+    allowedTools: string[];
+    currentState: string;
+    slice: PromptSlice;
+}
+export interface ToolExecutionEventData {
+    tool: string;
+    args?: any;
+    result?: any;
+    exitCode?: number;
+}
+/**
+ * In-Harness Interceptor Hooks
+ * Plugs directly into the agent reasoning loop without requiring changes to base models.
+ */
+export declare class ReactiveRuntimeHooks {
+    /**
+     * Pre-Turn Hook: Prepares the active state prompt slice and scopes allowed tools
+     */
+    static onBeforeAgentTurn(engine: FSMEngine, baseSystemPrompt?: string): InterceptorHookResult;
+    static auditToolExecution(engine: FSMEngine, toolData: ToolExecutionEventData): {
+        bypassed: boolean;
+        reason?: string;
+    };
+    /**
+     * Post-Turn Tool Hook: Translates tool execution results into reactive signals
+     */
+    static onAfterToolExecution(engine: FSMEngine, toolData: ToolExecutionEventData): Promise<{
+        signalsEmitted: string[];
+        transitioned: boolean;
+        currentState: string;
+        deliverablesWritten: string[];
+    }>;
+    /**
+     * Human Ingress Hook: Directly ingests human input from UI, Lavish, or CLI
+     */
+    static onHumanResponse(engine: FSMEngine, responseData: {
+        choice?: string;
+        feedback?: string;
+        approved?: boolean;
+        data?: Record<string, any>;
+    }): Promise<{
+        signalsEmitted: string[];
+        transitioned: boolean;
+        currentState: string;
+        deliverablesWritten: string[];
+    }>;
+}

package/dist/core/runtime-hooks.js

@@ -0,0 +1,195 @@
+const RUNTIME_TOOLS = new Set([
+    'reactive_state',
+    'reactive_emit_signal',
+    'reactive_query',
+    'reactive_query_events',
+    'reactive_list_skills',
+    'reactive_inspect',
+    'reactive_invoke_skill',
+    'reactive_respond_human',
+    'reactive_migrate',
+]);
+/**
+ * In-Harness Interceptor Hooks
+ * Plugs directly into the agent reasoning loop without requiring changes to base models.
+ */
+export class ReactiveRuntimeHooks {
+    /**
+     * Pre-Turn Hook: Prepares the active state prompt slice and scopes allowed tools
+     */
+    static onBeforeAgentTurn(engine, baseSystemPrompt = '') {
+        const slice = engine.generatePromptSlice();
+        let bypassWarning = '';
+        if (engine.isStrictExecution() && engine.getTurnsSinceLastSignal() > 0) {
+            bypassWarning = `<!-- BYPASS_WARNING: This turn will count against the idle budget. You have ${engine.getTurnsSinceLastSignal()} turn(s) since your last signal. Emit a signal via reactive_emit_signal to reset the counter. -->\n`;
+        }
+        const injectedPrompt = [
+            bypassWarning,
+            baseSystemPrompt,
+            '',
+            '<!-- REACTIVE SKILL CONTROL SLICE -->',
+            slice.formattedXml,
+            '<!-- END REACTIVE SKILL CONTROL SLICE -->',
+        ].filter(Boolean).join('\n');
+        return {
+            injectedPrompt,
+            allowedTools: slice.allowedTools,
+            currentState: slice.state,
+            slice,
+        };
+    }
+    static auditToolExecution(engine, toolData) {
+        const allowedTools = engine.generatePromptSlice().allowedTools;
+        const isRuntimeTool = RUNTIME_TOOLS.has(toolData.tool);
+        const isAllowedTool = allowedTools.includes(toolData.tool);
+        if (!isAllowedTool && !isRuntimeTool) {
+            const eventType = 'BYPASS_DETECTED';
+            engine.getEventStore().append(eventType, {
+                tool: toolData.tool,
+                reason: 'Tool not in allowed_tools and not a runtime tool',
+                allowed_tools: allowedTools,
+            }, { state: engine.getCurrentState() });
+            if (engine.isStrictExecution()) {
+                throw new Error(`BYPASS_DETECTED: Tool '${toolData.tool}' is not in the allowed tools list. ` +
+                    `Allowed tools: ${allowedTools.join(', ')}. ` +
+                    `To recover, run: reactive-skills-axi reset ${engine.getManifest().name} then re-invoke.`);
+            }
+            return { bypassed: true, reason: `Tool '${toolData.tool}' not in allowed_tools` };
+        }
+        return { bypassed: false };
+    }
+    /**
+     * Post-Turn Tool Hook: Translates tool execution results into reactive signals
+     */
+    static async onAfterToolExecution(engine, toolData) {
+        const signalsEmitted = [];
+        let transitioned = false;
+        let deliverablesWritten = [];
+        // Helper to dispatch and aggregate results
+        const dispatch = async (signalName, payload) => {
+            signalsEmitted.push(signalName);
+            const res = await engine.handleSignal(signalName, payload, { source: `tool:${toolData.tool}` });
+            if (res.transitioned) {
+                transitioned = true;
+            }
+            if (res.deliverablesWritten.length > 0) {
+                deliverablesWritten.push(...res.deliverablesWritten);
+            }
+        };
+        // Audit tool execution before dispatching auto-mapped signal
+        const auditResult = ReactiveRuntimeHooks.auditToolExecution(engine, toolData);
+        if (auditResult.bypassed) {
+            return {
+                signalsEmitted: [],
+                transitioned: false,
+                currentState: engine.getCurrentState(),
+                deliverablesWritten: [],
+            };
+        }
+        // Auto-map common tool outputs to signals
+        if (toolData.tool === 'run_command') {
+            const cmd = String(toolData.args?.CommandLine || toolData.args || '');
+            const output = String(toolData.result?.output || toolData.result || '');
+            const exitCode = typeof toolData.exitCode === 'number'
+                ? toolData.exitCode
+                : (output.includes('FAIL') || output.includes('Error') || output.includes('failed') ? 1 : 0);
+            // Check if this was a test run
+            if (cmd.includes('test') || cmd.includes('vitest') || cmd.includes('jest') || cmd.includes('pytest')) {
+                await dispatch('TEST_RAN', {
+                    command: cmd,
+                    exit_code: exitCode,
+                    output,
+                });
+            }
+            else {
+                await dispatch('COMMAND_RAN', {
+                    command: cmd,
+                    exit_code: exitCode,
+                    output,
+                });
+            }
+        }
+        else if (toolData.tool === 'write_to_file' || toolData.tool === 'replace_file_content') {
+            await dispatch('FILE_MODIFIED', {
+                tool: toolData.tool,
+                path: toolData.args?.TargetFile || toolData.args?.path,
+            });
+        }
+        else if (toolData.tool === 'ask_question') {
+            const choice = toolData.result?.choice || toolData.result?.selected || toolData.result?.answer || String(toolData.result || '');
+            engine.recordDecision({ choice, result: toolData.result }, `tool:${toolData.tool}`);
+            await dispatch('USER_DECISION', {
+                choice,
+                result: toolData.result,
+            });
+            if (/approve|yes|accept|confirm|proceed/i.test(choice)) {
+                await dispatch('USER_APPROVED', { choice, result: toolData.result });
+            }
+            else if (/reject|no|abort|cancel/i.test(choice)) {
+                await dispatch('USER_REJECTED', { choice, result: toolData.result });
+            }
+            else if (/revision|change|modify|fix/i.test(choice)) {
+                await dispatch('USER_REVISION_REQUESTED', { choice, result: toolData.result });
+            }
+        }
+        else {
+            await dispatch('TOOL_EXECUTED', {
+                tool: toolData.tool,
+                args: toolData.args,
+            });
+        }
+        return {
+            signalsEmitted,
+            transitioned,
+            currentState: engine.getCurrentState(),
+            deliverablesWritten,
+        };
+    }
+    /**
+     * Human Ingress Hook: Directly ingests human input from UI, Lavish, or CLI
+     */
+    static async onHumanResponse(engine, responseData) {
+        const signalsEmitted = [];
+        let transitioned = false;
+        let deliverablesWritten = [];
+        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);
+        };
+        // Update context if feedback or decision provided
+        if (responseData.feedback) {
+            engine.updateContext({ user_feedback: responseData.feedback });
+        }
+        if (responseData.choice) {
+            engine.updateContext({ user_choice: responseData.choice });
+        }
+        if (responseData.choice || responseData.feedback) {
+            engine.recordDecision({
+                choice: responseData.choice || '',
+                feedback: responseData.feedback,
+                approved: responseData.approved,
+                result: responseData.data,
+            });
+        }
+        await dispatch('USER_RESPONSE', responseData);
+        if (responseData.approved === true || (responseData.choice && /approve|yes|accept|confirm|proceed/i.test(responseData.choice))) {
+            await dispatch('USER_APPROVED', responseData);
+        }
+        else if (responseData.approved === false || (responseData.choice && /reject|no|abort|cancel/i.test(responseData.choice))) {
+            await dispatch('USER_REJECTED', responseData);
+        }
+        else if (responseData.choice && /revision|change|modify|fix/i.test(responseData.choice)) {
+            await dispatch('USER_REVISION_REQUESTED', responseData);
+        }
+        return {
+            signalsEmitted,
+            transitioned,
+            currentState: engine.getCurrentState(),
+            deliverablesWritten,
+        };
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+/**
+ * Signal Event Schema: Immutable envelope for all events in the reactive skill bus
+ */
+export interface SignalEvent<T = Record<string, any>> {
+    id: string;
+    event_id?: string;
+    seq: number;
+    timestamp: string;
+    occurred_at?: string;
+    type: string;
+    event_type?: string;
+    source?: string;
+    causationId?: string;
+    causation_id?: string;
+    correlation_id?: string;
+    request_id?: string;
+    trace_parent?: string;
+    skill_id?: string;
+    run_id?: string;
+    parent_run_id?: string;
+    schema_version?: string;
+    payload: T;
+    state?: string;
+}
+export interface EventContext {
+    skill_id?: string;
+    run_id?: string;
+    runId?: string;
+    correlation_id?: string;
+    correlationId?: string;
+    request_id?: string;
+    requestId?: string;
+    trace_parent?: string;
+    traceParent?: string;
+    parent_run_id?: string;
+    parentRunId?: string;
+    schema_version?: string;
+    schemaVersion?: string;
+}
+export interface ChildRunSummary {
+    child_skill_id: string;
+    child_run_id: string;
+    outcome: 'completed' | 'failed';
+    failed_state?: string;
+    error_code?: string;
+    summary?: string;
+    last_command?: string;
+    evidence_ref?: string;
+    suggested_action?: string;
+}
+export interface DecisionRecord {
+    choice: string;
+    approved?: boolean;
+    feedback?: string;
+    result?: Record<string, any>;
+}
+/**
+ * Transition Guard definition
+ */
+export interface TransitionDefinition {
+    target: string;
+    guard?: string;
+    guardFunction?: string;
+    description?: string;
+    invoke?: string;
+}
+export interface StateLifecycleAction {
+    emit_signal?: string;
+    set_context?: Record<string, any>;
+    action?: string;
+}
+export interface HumanGateDefinition {
+    type: 'approval' | 'choice' | 'text' | 'visual_review' | 'form';
+    tool?: 'ask_question' | 'lavish' | 'chat' | string;
+    prompt?: string;
+    options?: string[];
+    auto_stop?: boolean;
+}
+/**
+ * State Definition in a Reactive Skill
+ */
+export interface StateDefinition {
+    description?: string;
+    prompt_template?: string;
+    tools?: string[];
+    human_gate?: HumanGateDefinition;
+    on_enter?: StateLifecycleAction[];
+    on_exit?: StateLifecycleAction[];
+    transitions?: Record<string, TransitionDefinition | string>;
+    substates?: Record<string, StateDefinition>;
+    initial_substate?: string;
+    max_idle_turns?: number;
+    bypass_target?: string;
+}
+/**
+ * Deliverable Projection definition (Event-Sourced Read Models)
+ */
+export interface DeliverableProjection {
+    template: string;
+    output: string;
+    trigger_on?: string[];
+}
+/**
+ * Reactive Skill Manifest (skill.yaml)
+ */
+export interface SkillManifest {
+    schema_version: string;
+    name: string;
+    version?: string;
+    description: string;
+    initial_state: string;
+    strict_execution?: boolean;
+    context_keys?: string[];
+    default_context?: Record<string, any>;
+    states: Record<string, StateDefinition>;
+    deliverable_projections?: DeliverableProjection[];
+}
+/**
+ * Hydrated prompt slice generated for an active LLM turn
+ */
+export interface PromptSlice {
+    state: string;
+    rawPrompt: string;
+    formattedXml: string;
+    allowedTools: string[];
+    context: Record<string, any>;
+    exitConditions: string[];
+}
+/**
+ * Zod Schema for validation of skill.yaml
+ */
+export declare const TransitionSchema: z.ZodUnion<[z.ZodString, z.ZodObject<{
+    target: z.ZodString;
+    guard: z.ZodOptional<z.ZodString>;
+    guardFunction: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    invoke: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    target: string;
+    guard?: string | undefined;
+    guardFunction?: string | undefined;
+    description?: string | undefined;
+    invoke?: string | undefined;
+}, {
+    target: string;
+    guard?: string | undefined;
+    guardFunction?: string | undefined;
+    description?: string | undefined;
+    invoke?: string | undefined;
+}>]>;
+export declare const StateLifecycleActionSchema: z.ZodObject<{
+    emit_signal: z.ZodOptional<z.ZodString>;
+    set_context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    action: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    emit_signal?: string | undefined;
+    set_context?: Record<string, any> | undefined;
+    action?: string | undefined;
+}, {
+    emit_signal?: string | undefined;
+    set_context?: Record<string, any> | undefined;
+    action?: string | undefined;
+}>;
+export declare const HumanGateSchema: z.ZodObject<{
+    type: z.ZodEnum<["approval", "choice", "text", "visual_review", "form"]>;
+    tool: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    auto_stop: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    type: "approval" | "choice" | "text" | "visual_review" | "form";
+    options?: string[] | undefined;
+    tool?: string | undefined;
+    prompt?: string | undefined;
+    auto_stop?: boolean | undefined;
+}, {
+    type: "approval" | "choice" | "text" | "visual_review" | "form";
+    options?: string[] | undefined;
+    tool?: string | undefined;
+    prompt?: string | undefined;
+    auto_stop?: boolean | undefined;
+}>;
+export declare const StateSchema: z.ZodType<StateDefinition>;
+export declare const SkillManifestSchema: z.ZodObject<{
+    schema_version: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    initial_state: z.ZodString;
+    strict_execution: z.ZodOptional<z.ZodBoolean>;
+    context_keys: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    default_context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    states: z.ZodRecord<z.ZodString, z.ZodType<StateDefinition, z.ZodTypeDef, StateDefinition>>;
+    deliverable_projections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        template: z.ZodString;
+        output: z.ZodString;
+        trigger_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        template: string;
+        output: string;
+        trigger_on?: string[] | undefined;
+    }, {
+        template: string;
+        output: string;
+        trigger_on?: string[] | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    schema_version: string;
+    name: string;
+    initial_state: string;
+    states: Record<string, StateDefinition>;
+    version?: string | undefined;
+    strict_execution?: boolean | undefined;
+    context_keys?: string[] | undefined;
+    default_context?: Record<string, any> | undefined;
+    deliverable_projections?: {
+        template: string;
+        output: string;
+        trigger_on?: string[] | undefined;
+    }[] | undefined;
+}, {
+    description: string;
+    schema_version: string;
+    name: string;
+    initial_state: string;
+    states: Record<string, StateDefinition>;
+    version?: string | undefined;
+    strict_execution?: boolean | undefined;
+    context_keys?: string[] | undefined;
+    default_context?: Record<string, any> | undefined;
+    deliverable_projections?: {
+        template: string;
+        output: string;
+        trigger_on?: string[] | undefined;
+    }[] | undefined;
+}>;