@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/src/providers/spec/fsm-evaluator.ts

@@ -0,0 +1,290 @@
+/**
+ * FSM evaluator — pure transition evaluation for adhdev:cli/spec@4.
+ *
+ * Given the current state, the screen, and a clock context (when the current
+ * state was entered, when each cursor_above region last changed), decides
+ * which outgoing transition fires — and records WHY every transition did or
+ * did not fire. That "why" trace is the whole point: it is what makes the FSM
+ * debuggable from the daemon API without guessing.
+ *
+ * Screen-content leaves (regex / changed) are delegated to the shared v3
+ * condition evaluator. Time leaves (elapsed_ms / stable_ms) are evaluated here
+ * against the clock context the driver passes in. No wall-clock reads happen
+ * in this file — the driver owns `now` so the function stays pure & testable.
+ */
+'use strict';
+
+import type { Condition, SectionDef } from './types.js';
+import {
+    resolveSections, evaluateCondition, sectionText, type ResolvedSection, type TraceEntry,
+} from './evaluator.js';
+import {
+    type CliSpecV4, type FsmCondition, type FsmTransition,
+    outgoingTransitions, stateById,
+} from './fsm-types.js';
+
+export interface FsmClock {
+    /** Wall-clock now (ms). Passed in so the evaluator stays pure. */
+    now: number;
+    /** When the current state was entered (ms). */
+    stateEnteredAt: number;
+    /** Last-changed timestamp per stable region. Numeric key = cursor_above
+     *  value (0 / undefined → whole-screen, keyed as -1). String key =
+     *  `section:<id>` for a section-scoped stable region. Missing key means
+     *  "never observed changing" → treated as stable since stateEnteredAt. */
+    regionLastChangedAt: Map<number | string, number>;
+}
+
+/** Per-condition evaluation detail — the debugging payload. */
+export interface CondResult {
+    kind: 'regex' | 'changed' | 'elapsed' | 'stable' | 'all' | 'any' | 'not';
+    result: boolean;
+    detail: string;
+    /** Remaining ms until a time-based condition would flip to true. 0 if
+     *  already true or not applicable. Lets the UI show a countdown. */
+    remainingMs?: number;
+    /** Debug-only: the actual substring a TRUE regex condition matched, so the
+     *  snapshot shows WHAT text the rule fired on — not just which regex. Never
+     *  read by the FSM; purely for the Spec Debug Snapshot. */
+    matchedText?: string;
+    children?: CondResult[];
+}
+
+/** One evaluated transition with its full reasoning. */
+export interface TransitionEval {
+    to: string;
+    label: string;
+    /** Did the `from` clause include the current state? (Always true for the
+     *  transitions we return — kept for completeness.) */
+    eligible: boolean;
+    /** min_hold_ms guard satisfied? */
+    holdSatisfied: boolean;
+    holdRemainingMs: number;
+    /** Guard condition result (true if no `when`). */
+    condResult: boolean;
+    cond?: CondResult;
+    /** Overall: would this transition fire? */
+    fires: boolean;
+    priority: number;
+}
+
+export interface FsmEvaluation {
+    /** Sections resolved from the screen (shared with v3 shape). */
+    sections: ResolvedSection[];
+    /** Every outgoing transition from the current state, priority-ordered,
+     *  each annotated with why it fired or didn't. */
+    transitions: TransitionEval[];
+    /** The transition that fires (first in priority order with fires===true),
+     *  or null to stay in the current state. */
+    fired: TransitionEval | null;
+    /** v3-compatible trace lines for the legacy inspector. */
+    trace: TraceEntry[];
+}
+
+const WHOLE_SCREEN = -1;
+
+/** The `regionLastChangedAt` key for a stable condition. The key must capture
+ *  everything that makes two stable clauses watch a DIFFERENT change signal:
+ *  the geometric region (`section` wins over `cursor_above`, else whole-screen)
+ *  AND the `ignore_lines` filter (two clauses on the same region but different
+ *  ignore patterns see different "did it change" answers). Kept in one place so
+ *  the driver (which populates the map) and the evaluator (which reads it)
+ *  agree on the key.
+ *
+ *  Bare whole-screen with no ignore filter keeps its historical numeric key -1
+ *  so existing callers/tests that seed `regionLastChangedAt` with [-1, ...]
+ *  keep working unchanged. */
+export function stableRegionKey(cond: { section?: string; cursor_above?: number; ignore_lines?: string }): number | string {
+    const region = cond.section
+        ? `section:${cond.section}`
+        : (cond.cursor_above && cond.cursor_above > 0 ? cond.cursor_above : WHOLE_SCREEN);
+    if (!cond.ignore_lines) return region;
+    return `${region}#ignore:${cond.ignore_lines}`;
+}
+
+function isRegex(c: FsmCondition): c is import('./types.js').RegexCondition {
+    return 'matches' in c;
+}
+function isChanged(c: FsmCondition): c is import('./types.js').ChangedCondition {
+    return 'cursor_above' in c && 'changed' in c;
+}
+function isElapsed(c: FsmCondition): c is import('./fsm-types.js').ElapsedCondition {
+    return 'elapsed_ms' in c;
+}
+function isStable(c: FsmCondition): c is import('./fsm-types.js').StableCondition {
+    return 'stable_ms' in c;
+}
+function isAll(c: FsmCondition): c is import('./fsm-types.js').FsmAllCondition {
+    return 'all' in c;
+}
+function isAny(c: FsmCondition): c is import('./fsm-types.js').FsmAnyCondition {
+    return 'any' in c;
+}
+function isNot(c: FsmCondition): c is import('./fsm-types.js').FsmNotCondition {
+    return 'not' in c;
+}
+
+/**
+ * Evaluate a single FSM condition into a {result, detail, remainingMs, children}.
+ * Recurses through all/any/not; defers regex/changed to the shared evaluator;
+ * handles elapsed_ms/stable_ms against the clock.
+ */
+function evalCond(
+    cond: FsmCondition,
+    sections: ResolvedSection[],
+    fullScreen: string,
+    cursor: { row: number; col: number } | undefined,
+    prevLines: string[] | undefined,
+    clock: FsmClock,
+    legacyTrace: TraceEntry[],
+    stateId: string,
+): CondResult {
+    if (isAll(cond)) {
+        const children = cond.all.map(c =>
+            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+        const result = children.every(c => c.result);
+        const remainingMs = result ? 0 : Math.max(0, ...children.filter(c => !c.result).map(c => c.remainingMs ?? 0));
+        return { kind: 'all', result, detail: `all(${children.length})`, remainingMs, children };
+    }
+    if (isAny(cond)) {
+        const children = cond.any.map(c =>
+            evalCond(c, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId));
+        const result = children.some(c => c.result);
+        // remaining = the soonest child that could flip true
+        const pending = children.filter(c => !c.result).map(c => c.remainingMs ?? Infinity);
+        const remainingMs = result ? 0 : (pending.length ? Math.min(...pending) : 0);
+        return { kind: 'any', result, detail: `any(${children.length})`, remainingMs: Number.isFinite(remainingMs) ? remainingMs : 0, children };
+    }
+    if (isNot(cond)) {
+        const child = evalCond(cond.not, sections, fullScreen, cursor, prevLines, clock, legacyTrace, stateId);
+        return { kind: 'not', result: !child.result, detail: `not`, remainingMs: 0, children: [child] };
+    }
+    if (isElapsed(cond)) {
+        const age = clock.now - clock.stateEnteredAt;
+        const result = age >= cond.elapsed_ms;
+        const remainingMs = result ? 0 : cond.elapsed_ms - age;
+        return { kind: 'elapsed', result, detail: `elapsed ${age}ms / ${cond.elapsed_ms}ms`, remainingMs };
+    }
+    if (isStable(cond)) {
+        const key = stableRegionKey(cond);
+        // If we never saw the region change, treat it as stable since the
+        // state was entered (conservative — avoids a premature "stable" on
+        // the very first frame).
+        const lastChanged = clock.regionLastChangedAt.get(key) ?? clock.stateEnteredAt;
+        const stableFor = clock.now - lastChanged;
+        const result = stableFor >= cond.stable_ms;
+        const remainingMs = result ? 0 : cond.stable_ms - stableFor;
+        const where = cond.section ? `section=${cond.section}`
+            : cond.cursor_above && cond.cursor_above > 0 ? `cursor_above=${cond.cursor_above}` : 'screen';
+        const ign = cond.ignore_lines ? ' (ignore_lines)' : '';
+        return { kind: 'stable', result, detail: `stable ${where}${ign} ${stableFor}ms / ${cond.stable_ms}ms`, remainingMs };
+    }
+    // regex / changed → shared evaluator (operates on v3 Condition shape)
+    if (isRegex(cond) || isChanged(cond)) {
+        const result = evaluateCondition(cond as Condition, sections, fullScreen, cursor, prevLines, legacyTrace, stateId);
+        const kind = isRegex(cond) ? 'regex' : 'changed';
+        const detail = isRegex(cond)
+            ? `${(cond as any).section ?? '*'}~/${(cond as any).matches}/`
+            : `cursor_above=${(cond as any).cursor_above} changed=${(cond as any).changed}`;
+        // Debug-only: when a regex condition is TRUE, also capture the substring
+        // it matched so the snapshot can show the exact text the rule fired on.
+        // This re-runs the regex (read-only) and CANNOT change `result` above —
+        // the FSM decision is still entirely owned by evaluateCondition().
+        let matchedText: string | undefined;
+        if (result && isRegex(cond)) {
+            try {
+                const hay = sectionText(sections, (cond as any).section, fullScreen);
+                const re = new RegExp((cond as any).matches, (cond as any).flags ?? 'i');
+                const m = re.exec(hay);
+                if (m && m[0]) matchedText = m[0].replace(/\s+/g, ' ').trim().slice(0, 160);
+            } catch { /* capture is best-effort; never affects result */ }
+        }
+        return matchedText ? { kind, result, detail, matchedText } : { kind, result, detail };
+    }
+    return { kind: 'all', result: false, detail: 'unknown condition' };
+}
+
+function fromLabel(t: FsmTransition): string {
+    const from = Array.isArray(t.from) ? t.from.join('|') : t.from;
+    return t.label ?? `${from}→${t.to}`;
+}
+
+/**
+ * Evaluate the FSM: given the current state id and screen, return every
+ * outgoing transition annotated with why it fires/doesn't, plus the one that
+ * fires (if any).
+ */
+export function evaluateFsm(
+    spec: CliSpecV4,
+    currentStateId: string,
+    screenText: string,
+    cursor: { row: number; col: number } | undefined,
+    prevLines: string[] | undefined,
+    clock: FsmClock,
+): FsmEvaluation {
+    const legacyTrace: TraceEntry[] = [];
+    const lines = screenText.split('\n').map(l => l.endsWith('\r') ? l.slice(0, -1) : l);
+    const cleanScreen = lines.join('\n');
+    const sections = resolveSections(spec.sections ?? {}, lines);
+
+    const outgoing = outgoingTransitions(spec, currentStateId);
+    const transitions: TransitionEval[] = [];
+    let fired: TransitionEval | null = null;
+
+    for (const t of outgoing) {
+        const holdMs = t.min_hold_ms ?? 0;
+        const heldFor = clock.now - clock.stateEnteredAt;
+        const holdSatisfied = heldFor >= holdMs;
+        const holdRemainingMs = holdSatisfied ? 0 : holdMs - heldFor;
+
+        let cond: CondResult | undefined;
+        let condResult = true;
+        if (t.when) {
+            cond = evalCond(t.when, sections, cleanScreen, cursor, prevLines, clock, legacyTrace, `${currentStateId}→${t.to}`);
+            condResult = cond.result;
+        }
+
+        const fires = holdSatisfied && condResult;
+        const te: TransitionEval = {
+            to: t.to,
+            label: fromLabel(t),
+            eligible: true,
+            holdSatisfied,
+            holdRemainingMs,
+            condResult,
+            cond,
+            fires,
+            priority: t.priority ?? 0,
+        };
+        transitions.push(te);
+        if (fires && !fired) fired = te;
+    }
+
+    // Validate destination exists (defensive — loader should catch this).
+    if (fired && !stateById(spec, fired.to)) {
+        legacyTrace.push({ kind: 'state_skip', text: `transition target ${fired.to} not found` });
+        fired = null;
+    }
+
+    return { sections, transitions, fired, trace: legacyTrace };
+}
+
+/**
+ * Evaluate a single condition against a screen + section map — for the spec
+ * editor's live preview ("does this regex match the current screen right
+ * now?"). Time leaves (elapsed_ms/stable_ms) are evaluated against a synthetic
+ * clock where the state was just entered, so they report their countdown
+ * rather than firing; the preview is about screen-content match, not timing.
+ */
+export function evaluateConditionPreview(
+    cond: FsmCondition,
+    sections: Record<string, SectionDef> | undefined,
+    screenText: string,
+    cursor?: { row: number; col: number },
+): CondResult {
+    const lines = screenText.split('\n').map(l => l.endsWith('\r') ? l.slice(0, -1) : l);
+    const cleanScreen = lines.join('\n');
+    const resolved = resolveSections(sections ?? {}, lines);
+    const clock: FsmClock = { now: 0, stateEnteredAt: 0, regionLastChangedAt: new Map() };
+    return evalCond(cond, resolved, cleanScreen, cursor, undefined, clock, [], 'preview');
+}

package/src/providers/spec/fsm-loader.ts

@@ -0,0 +1,128 @@
+/**
+ * FSM spec (adhdev:cli/spec@4) loader + validator.
+ *
+ * Validation is intentionally code-based (not AJV) so a spec authored live in
+ * the debug panel gets precise, human-readable errors ("transition[2].to
+ * references unknown state 'budy'") instead of a JSON-schema path. Every error
+ * is something a spec author can act on without reading the engine.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import { type CliSpecV4, type FsmCondition, isV4Spec } from './fsm-types.js';
+
+export interface FsmLoadOk { ok: true; spec: CliSpecV4; sourcePath: string; }
+export interface FsmLoadErr { ok: false; errors: string[]; sourcePath: string; }
+
+export function loadFsmSpec(sourcePath: string): FsmLoadOk | FsmLoadErr {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+    } catch (err) {
+        return { ok: false, errors: [`Failed to read/parse spec: ${(err as Error).message}`], sourcePath };
+    }
+    const errors = validateFsmSpec(raw);
+    if (errors.length) return { ok: false, errors, sourcePath };
+    return { ok: true, spec: raw as CliSpecV4, sourcePath };
+}
+
+/** Pure validator — usable from a "validate before save" API in the panel. */
+export function validateFsmSpec(raw: unknown): string[] {
+    const errs: string[] = [];
+    if (!isV4Spec(raw)) return ['$schema must be "adhdev:cli/spec@4"'];
+    const spec = raw as CliSpecV4;
+
+    if (!spec.id) errs.push('id is required');
+    if (!spec.binary) errs.push('binary is required');
+    if (!spec.send_message?.submit_key) errs.push('send_message.submit_key is required');
+
+    if (spec.pre_launch_trust !== undefined) {
+        const t = spec.pre_launch_trust as { settings_path?: unknown; key?: unknown };
+        if (!t || typeof t !== 'object' || Array.isArray(t)) {
+            errs.push('pre_launch_trust must be an object');
+        } else {
+            if (typeof t.settings_path !== 'string' || !t.settings_path) errs.push('pre_launch_trust.settings_path is required');
+            if (typeof t.key !== 'string' || !t.key) errs.push('pre_launch_trust.key is required');
+        }
+    }
+
+    if (spec.refocus_when_stalled_ms !== undefined) {
+        if (typeof spec.refocus_when_stalled_ms !== 'number' || !(spec.refocus_when_stalled_ms > 0)) {
+            errs.push('refocus_when_stalled_ms must be a positive number');
+        } else if (!Array.isArray(spec.send_on_spawn) || spec.send_on_spawn.length === 0) {
+            errs.push('refocus_when_stalled_ms requires send_on_spawn (the wake sequence to re-inject)');
+        }
+    }
+
+    if (!Array.isArray(spec.states) || spec.states.length === 0) {
+        errs.push('states[] must be a non-empty array');
+        return errs;
+    }
+    if (!Array.isArray(spec.transitions)) {
+        errs.push('transitions[] must be an array');
+        return errs;
+    }
+
+    const ids = new Set<string>();
+    let initialCount = 0;
+    for (const [i, s] of spec.states.entries()) {
+        if (!s.id) { errs.push(`states[${i}].id is required`); continue; }
+        if (ids.has(s.id)) errs.push(`states[${i}].id "${s.id}" is duplicated`);
+        ids.add(s.id);
+        if (!s.label) errs.push(`states[${i}].label is required`);
+        if (s.initial) initialCount += 1;
+        if (s.status && !['idle', 'generating', 'approval'].includes(s.status)) {
+            errs.push(`states[${i}].status "${s.status}" must be idle|generating|approval`);
+        }
+    }
+    if (initialCount === 0) errs.push('exactly one state must have initial:true (none found)');
+    if (initialCount > 1) errs.push(`exactly one state must have initial:true (${initialCount} found)`);
+
+    const sectionIds = new Set(Object.keys(spec.sections ?? {}));
+    for (const [i, t] of spec.transitions.entries()) {
+        const froms = t.from === '*' ? [] : (Array.isArray(t.from) ? t.from : [t.from]);
+        for (const f of froms) {
+            if (!ids.has(f)) errs.push(`transitions[${i}].from references unknown state "${f}"`);
+        }
+        if (t.from !== '*' && froms.length === 0) errs.push(`transitions[${i}].from is required`);
+        if (!t.to) errs.push(`transitions[${i}].to is required`);
+        else if (!ids.has(t.to)) errs.push(`transitions[${i}].to references unknown state "${t.to}"`);
+        if (t.when) errs.push(...validateCondition(t.when, sectionIds, `transitions[${i}].when`));
+    }
+
+    // Section refs in state.extract
+    for (const [i, s] of spec.states.entries()) {
+        const sec = s.extract?.title?.section;
+        if (sec && !sectionIds.has(sec)) errs.push(`states[${i}].extract.title.section "${sec}" unknown`);
+        const bsec = s.extract?.buttons?.section;
+        if (bsec && !sectionIds.has(bsec)) errs.push(`states[${i}].extract.buttons.section "${bsec}" unknown`);
+    }
+
+    return errs;
+}
+
+function validateCondition(c: FsmCondition, sectionIds: Set<string>, path: string): string[] {
+    const errs: string[] = [];
+    const w = c as any;
+    if ('all' in w) { w.all.forEach((x: FsmCondition, i: number) => errs.push(...validateCondition(x, sectionIds, `${path}.all[${i}]`))); return errs; }
+    if ('any' in w) { w.any.forEach((x: FsmCondition, i: number) => errs.push(...validateCondition(x, sectionIds, `${path}.any[${i}]`))); return errs; }
+    if ('not' in w) { errs.push(...validateCondition(w.not, sectionIds, `${path}.not`)); return errs; }
+    if ('matches' in w) {
+        if (w.section && !sectionIds.has(w.section)) errs.push(`${path}.section "${w.section}" unknown`);
+        try { new RegExp(w.matches, w.flags ?? 'i'); } catch (e) { errs.push(`${path}.matches invalid regex: ${(e as Error).message}`); }
+        return errs;
+    }
+    if ('cursor_above' in w && 'changed' in w) return errs;
+    if ('elapsed_ms' in w) { if (typeof w.elapsed_ms !== 'number') errs.push(`${path}.elapsed_ms must be a number`); return errs; }
+    if ('stable_ms' in w) {
+        if (typeof w.stable_ms !== 'number') errs.push(`${path}.stable_ms must be a number`);
+        if (w.section && !sectionIds.has(w.section)) errs.push(`${path}.section "${w.section}" unknown`);
+        if (w.ignore_lines !== undefined) {
+            if (typeof w.ignore_lines !== 'string') errs.push(`${path}.ignore_lines must be a string`);
+            else try { new RegExp(w.ignore_lines, 'm'); } catch (e) { errs.push(`${path}.ignore_lines invalid regex: ${(e as Error).message}`); }
+        }
+        return errs;
+    }
+    errs.push(`${path} is not a recognized condition`);
+    return errs;
+}