@adhdev/daemon-core 0.9.82-rc.216 → 0.9.82-rc.218

package/src/providers/provider-loader.ts

@@ -1247,29 +1247,39 @@ export class ProviderLoader {
           // Hand the resolved spec path off to route.ts via a hidden field
           // so the routing layer doesn't have to repeat the candidate walk.
           (resolved as any)._resolvedSpecPath = specPath;
-          const r = loadSpec(specPath);
+          // Extract control_bar + native_history in a schema-agnostic way.
+          // v3 goes through loadSpec (validates/migrates); v4 (FSM) reads the
+          // header fields directly from JSON since loadSpec only knows v1/v3.
+          let specControls: any[] | undefined;
+          let nh: any | undefined;
+          try {
+            const rawSpec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+            if (rawSpec?.$schema === 'adhdev:cli/spec@4') {
+              specControls = rawSpec.control_bar;
+              nh = rawSpec.native_history;
+            } else {
+              const r = loadSpec(specPath);
+              if (r.ok) { specControls = r.spec.control_bar; nh = r.spec.native_history; }
+            }
+          } catch { /* unreadable spec — leave controls/native unavailable */ }
           // Stub each control_bar entry as a provider.scripts.<id>. The
           // upstream invoke_provider_script gate checks that the script
           // name exists on provider.scripts before calling adapter.invokeScript;
           // for spec providers the *actual* dispatch happens inside
           // SpecCliAdapter.invokeScript which maps the name to control_bar.
           // The stub is just a presence marker so the gate doesn't reject.
-          if (r.ok) {
-            const controls = r.spec.control_bar ?? [];
-            if (controls.length > 0) {
-              resolved.scripts = { ...(resolved.scripts || {}) };
-              for (const ctl of controls) {
-                if (!(resolved.scripts as any)[ctl.id]) {
-                  (resolved.scripts as any)[ctl.id] = (..._args: unknown[]) => ({
-                    __spec_control: true,
-                    controlId: ctl.id,
-                    actionType: ctl.action.type,
-                  });
-                }
+          if (specControls && specControls.length > 0) {
+            resolved.scripts = { ...(resolved.scripts || {}) };
+            for (const ctl of specControls) {
+              if (!(resolved.scripts as any)[ctl.id]) {
+                (resolved.scripts as any)[ctl.id] = (..._args: unknown[]) => ({
+                  __spec_control: true,
+                  controlId: ctl.id,
+                  actionType: ctl.action.type,
+                });
               }
             }
           }
-          const nh = r.ok ? r.spec.native_history : undefined;
           if (nh) {
             let reader: ((input: any) => any) | null = null;
             let format = 'spec';

package/src/providers/spec/cli-adapter.ts

@@ -18,11 +18,13 @@
  */
 'use strict';
 
-import { SpecDriver, type DashboardEvent } from './driver.js';
-import { evaluate } from './evaluator.js';
+import { SpecDriver, type DashboardEvent, type ISpecDriver } from './driver.js';
+import { FsmDriver } from './fsm-driver.js';
 import { executeNativeHistory } from './native-history-executor.js';
 import { loadSpec } from './loader.js';
+import * as fs from 'node:fs';
 import type { CliSpec } from './types.js';
+import type { NativeHistoryConfig, Control } from './types.js';
 import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
 import type { ChatMessage } from '../../types.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
@@ -37,6 +39,14 @@ import {
     type InteractivePromptResponse,
 } from '../types/interactive-prompt.js';
 
+/** Peek at the spec's $schema to choose the driver. Cheap header read. */
+function detectV4Schema(specPath: string): boolean {
+    try {
+        const raw = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+        return raw?.$schema === 'adhdev:cli/spec@4';
+    } catch { return false; }
+}
+
 function stripAnsi(text: string): string {
     // eslint-disable-next-line no-control-regex
     return String(text || '')
@@ -59,8 +69,14 @@ export class SpecCliAdapter implements CliAdapter {
      */
     readonly chatMessagesOwnedExternally = true as const;
 
-    private driver: SpecDriver;
-    private spec: CliSpec;
+    private driver: ISpecDriver;
+    /** Common spec fields the adapter reads, present in both v3 and v4. */
+    private spec: {
+        id: string;
+        name: string;
+        control_bar?: Control[];
+        native_history?: NativeHistoryConfig;
+    };
     private lastEvent: DashboardEvent | null = null;
     private latestState: { id: string; label: string; title: string | null } | null = null;
     private latestModal: { title: string | null; buttons: { index: number; label: string }[] } | null = null;
@@ -97,9 +113,30 @@ export class SpecCliAdapter implements CliAdapter {
         extraEnv: Record<string, string>,
         transportFactory?: PtyTransportFactory,
     ) {
-        const res = loadSpec(specPath);
-        if (!res.ok) throw new Error(`spec invalid (${specPath}): ${res.errors.join('; ')}`);
-        this.spec = res.spec;
+        // Detect the spec schema version up front. v4 (FSM) and v3 (debounce)
+        // use different drivers behind the same ISpecDriver interface.
+        const isV4 = detectV4Schema(specPath);
+
+        if (isV4) {
+            // v4 loader runs inside FsmDriver; read the common header fields
+            // we need here directly from the parsed JSON.
+            const raw = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+            this.spec = {
+                id: raw.id,
+                name: raw.name,
+                control_bar: raw.control_bar,
+                native_history: raw.native_history,
+            };
+        } else {
+            const res = loadSpec(specPath);
+            if (!res.ok) throw new Error(`spec invalid (${specPath}): ${res.errors.join('; ')}`);
+            this.spec = {
+                id: res.spec.id,
+                name: res.spec.name,
+                control_bar: res.spec.control_bar,
+                native_history: res.spec.native_history,
+            };
+        }
         this.cliType = this.spec.id;
         this.cliName = this.spec.name;
         this.workingDir = workingDir;
@@ -107,11 +144,11 @@ export class SpecCliAdapter implements CliAdapter {
 
         // cli-manager.ts allocates providerSessionId per launch and threads
         // it through resume.newSessionArgs as additional cliArgs (e.g.
-        // ["--session-id", "<uuid>"]). We must hand those to SpecDriver
+        // ["--session-id", "<uuid>"]). We must hand those to the driver
         // so the agent uses the daemon's id, otherwise (claude case) the
         // agent generates its own id and the chat-history pipeline can't
         // pair the on-disk transcript with the live session.
-        this.driver = new SpecDriver({
+        const driverOpts = {
             specPath,
             workingDir,
             extraEnv,
@@ -119,7 +156,8 @@ export class SpecCliAdapter implements CliAdapter {
             emitTrace: false,
             transportFactory,
             extraCliArgs: cliArgs,
-        });
+        };
+        this.driver = isV4 ? new FsmDriver(driverOpts) : new SpecDriver(driverOpts);
         this.driver.subscribe((ev) => this.handleEvent(ev));
     }
 
@@ -362,6 +400,10 @@ export class SpecCliAdapter implements CliAdapter {
             specPath: this.driver.getSpecPath(),
             cursorPosition: this.driver.getCursorPosition(),
             completionIdleDebounce: this.driver.getCompletionIdleDebounceState(),
+            // v4 FSM live transition table (null for v3 specs). Every outgoing
+            // transition from the current state with its per-condition match
+            // result + countdown — the canonical "why isn't it moving" answer.
+            fsm: this.driver.getFsmDebug?.() ?? null,
             // Extended fields
             name: this.cliName,
             status: this.getStatus().status,
@@ -445,10 +487,10 @@ export class SpecCliAdapter implements CliAdapter {
         }
     }
 
-    private readCurrentScreenSections(screenText: string): Record<string, string> {
+    private readCurrentScreenSections(_screenText: string): Record<string, string> {
         try {
-            const ev = evaluate(this.spec, screenText);
-            return Object.fromEntries(ev.sections.map(section => [section.id, section.text]));
+            const sections = this.driver.getSections() ?? [];
+            return Object.fromEntries(sections.map(section => [section.id, section.text]));
         } catch {
             return {};
         }
@@ -601,7 +643,13 @@ export class SpecCliAdapter implements CliAdapter {
             providerSessionId: this.providerSessionId ?? null,
             sections: this.driver.getSections?.() ?? null,
             stateHistory: history,
-            specPath: (this.driver as any).opts?.specPath ?? null,
+            specPath: this.driver.getSpecPath?.() ?? null,
+            // v4 FSM live transition table — present only for FsmDriver. Lets
+            // the panel (and the daemon API) show, for the current instant,
+            // every outgoing transition with its per-condition match result
+            // and countdown. This is the canonical "why isn't it transitioning"
+            // answer — no screenshots needed.
+            fsm: this.driver.getFsmDebug?.() ?? null,
             messages,
             committedMessages: messages,
         };

package/src/providers/spec/driver.ts

@@ -41,7 +41,7 @@ import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
 import { DEFAULT_SESSION_HOST_COLS, DEFAULT_SESSION_HOST_ROWS } from '@adhdev/session-host-core';
 import { evaluate, type SpecEvaluation, type TraceEntry } from './evaluator.js';
 import { loadSpec } from './loader.js';
-import type { CliSpec, Control, DelegateTrigger, SectionDef } from './types.js';
+import type { CliSpec, Condition, ChangedCondition, Control, DelegateTrigger, SectionDef } from './types.js';
 import { LOG } from '../../logging/logger.js';
 
 export type DashboardEvent =
@@ -65,6 +65,45 @@ export type DashboardCommand =
     | { kind: 'cancel' }
     | { kind: 'shutdown' };
 
+/** One state-history entry — the union of fields produced by the v3 SpecDriver
+ *  (debounce-based) and the v4 FsmDriver (transition-based). The cli-adapter
+ *  and debug panel read this shape from either driver. */
+export interface DriverHistoryEntry {
+    stateId: string;
+    label: string;
+    at: number;
+    durationMs: number;
+    reason: string;
+    matchedStateId?: string;
+    matchedRules?: string[];
+    debounceKind?: string;
+    idleHoldMs?: number;
+    busyHoldMs?: number;
+    /** v4: the transition that fired, e.g. "idle→busy". */
+    via?: string;
+}
+
+/** The surface the cli-adapter drives. Implemented by both SpecDriver (v3,
+ *  debounce) and FsmDriver (v4, FSM). Lets the adapter hold either without
+ *  branching on the concrete type. */
+export interface ISpecDriver {
+    subscribe(listener: (ev: DashboardEvent) => void): () => void;
+    start(): void;
+    dispatch(cmd: DashboardCommand): void;
+    snapshot(): string;
+    getCursorPosition(): { row: number; col: number };
+    getScreen(): string;
+    getSpecPath(): string;
+    shutdown(): void;
+    getStateHistory(): ReadonlyArray<DriverHistoryEntry>;
+    getSections(): Array<{ id: string; text: string }> | null;
+    getLastBusyAt(): number;
+    hasIdleHoldPending(): boolean;
+    getCompletionIdleDebounceState(): { active: boolean; ageMs: number; holdMs: number; forceAfterMs: number } | null;
+    /** v4 only — present on FsmDriver. Returns the live transition table. */
+    getFsmDebug?(): unknown;
+}
+
 export interface SpecDriverOpts {
     specPath: string;
     workingDir: string;
@@ -112,6 +151,14 @@ const BUSY_HOLD_MS = 6000;
  *  codex's explicit setting and is barely perceptible to a human caller. */
 const SUBMIT_DELAY_FLOOR_MS = 200;
 
+function collectChangedConditions(when: Condition | undefined): ChangedCondition[] {
+    if (!when) return [];
+    if ('cursor_above' in when && 'changed' in when) return [when as ChangedCondition];
+    if ('all' in when) return when.all.flatMap(c => collectChangedConditions(c));
+    if ('any' in when) return when.any.flatMap(c => collectChangedConditions(c));
+    return [];
+}
+
 function countNewlines(s: string): number {
     let n = 0;
     for (let i = 0; i < s.length; i += 1) if (s.charCodeAt(i) === 10) n += 1;
@@ -187,7 +234,7 @@ export function matchesCompletionIdleTargetState(
     }
 }
 
-export class SpecDriver {
+export class SpecDriver implements ISpecDriver {
     private spec!: CliSpec;
     private adapter!: TerminalAdapter;
     private listeners = new Set<(ev: DashboardEvent) => void>();
@@ -240,6 +287,9 @@ export class SpecDriver {
      *  Used by screen_active_hold_ms to suppress idle downshifts while
      *  the terminal is still actively updating. */
     private lastScreenChangedAt = 0;
+    /** Per-cursor_above region last-changed timestamps for stable_ms tracking.
+     *  Key: cursor_above value. Value: last time that region changed. */
+    private regionLastChangedAt = new Map<number, number>();
     /** Timer that re-runs evaluate() once the hold window expires. Needed
      *  because the PTY stops emitting once the agent finishes; without an
      *  explicit wake-up there's nothing to trigger the busy → idle
@@ -482,9 +532,24 @@ export class SpecDriver {
         const cursor = this.adapter.getCursorPosition();
         const currentLines = screen.split('\n').map(l => l.endsWith('\r') ? l.slice(0, -1) : l);
         const ev = evaluate(this.spec, screen, cursor, this.prevScreenLines.length > 0 ? this.prevScreenLines : undefined);
+        const now = Date.now();
         // Track when the screen last changed for screen_active_hold_ms.
         if (this.prevScreenLines.length > 0 && currentLines.join('\n') !== this.prevScreenLines.join('\n')) {
-            this.lastScreenChangedAt = Date.now();
+            this.lastScreenChangedAt = now;
+        }
+        // Track per-region last-changed timestamps for stable_ms conditions.
+        if (cursor && this.prevScreenLines.length > 0) {
+            for (const state of this.spec.states) {
+                const conditions = collectChangedConditions(state.when);
+                for (const cond of conditions) {
+                    if (cond.stable_ms == null) continue;
+                    const startRow = Math.max(0, cursor.row - cond.cursor_above);
+                    const endRow = cursor.row;
+                    const cur = currentLines.slice(startRow, endRow).join('\n');
+                    const prev = this.prevScreenLines.slice(startRow, endRow).join('\n');
+                    if (cur !== prev) this.regionLastChangedAt.set(cond.cursor_above, now);
+                }
+            }
         }
         // Update prevScreenLines for next evaluation's `changed` condition detection.
         this.prevScreenLines = currentLines;
@@ -500,7 +565,7 @@ export class SpecDriver {
         let evState = ev.state;
         const busyHoldMs = this.spec.debounce?.busy_hold_ms ?? BUSY_HOLD_MS;
         if (this.currentStateId === 'busy' && evState.id === 'idle') {
-            const ageMs = Date.now() - this.lastBusyAt;
+            const ageMs = now - this.lastBusyAt;
             if (ageMs < busyHoldMs) {
                 // Pin to the last seen busy state directly — currentEval can
                 // already be idle at this point (it tracks the previous tick,
@@ -509,6 +574,37 @@ export class SpecDriver {
                 evState = this.lastBusyState ?? evState;
             }
         }
+        // Startup grace: suppress idle→busy transitions during the banner-paint
+        // window. The spec author sets startup_grace_ms to cover the time the
+        // terminal spends drawing its initial screen; any busy signal during
+        // that window is noise (cursor_above:changed, layout reflow, etc.).
+        const graceMs = this.spec.debounce?.startup_grace_ms ?? STARTUP_GRACE_MS;
+        const sinceStartMs = now - this.startedAtMs;
+        // Startup grace: suppress all busy transitions during the banner-paint
+        // window regardless of current state.
+        if (sinceStartMs < graceMs && evState.id === 'busy') {
+            LOG.info('SpecDriver', `[${this.opts.specPath.split('/').slice(-3).join('/')}] startup grace suppressed busy (sinceStart=${sinceStartMs}ms grace=${graceMs}ms)`);
+            evState = { id: this.spec.default_state ?? 'idle', label: 'Ready', title: null };
+            this.scheduleBusyExpiry(graceMs - sinceStartMs + 50);
+        }
+        // stable_ms gate: if the matched idle state has a changed:false/stable_ms
+        // condition, verify the region has been stable long enough. If not, pin
+        // to busy and schedule a re-evaluation when the stable window expires.
+        if (evState.id === (this.spec.default_state ?? 'idle') && cursor) {
+            const stableConditions = collectChangedConditions(
+                this.spec.states.find(s => s.id === evState.id)?.when
+            ).filter(c => c.changed === false && c.stable_ms != null);
+            for (const cond of stableConditions) {
+                const lastChanged = this.regionLastChangedAt.get(cond.cursor_above) ?? 0;
+                const stableMs = cond.stable_ms!;
+                const stableAge = lastChanged > 0 ? now - lastChanged : Infinity;
+                if (stableAge < stableMs) {
+                    evState = this.lastBusyState ?? { id: 'busy', label: 'Generating', title: null };
+                    this.scheduleBusyExpiry(stableMs - stableAge + 50);
+                    break;
+                }
+            }
+        }
         // Modal hold: when in a modal state (approval, picker, etc.) a brief
         // busy reading should not interrupt the modal. Claude Code streams
         // body content while the approval modal is visible, causing a spinner
@@ -538,7 +634,6 @@ export class SpecDriver {
         //    approval appeared and its hold expires immediately after dismissal,
         //    causing a false-idle even though the agent is still generating.
         const postModalGraceMs = busyHoldMs;
-        const now = Date.now();
         const recentlyInModal = isModalState(this.currentStateId) || (this.lastModalAt > 0 && now - this.lastModalAt < postModalGraceMs);
         const recentlyLeftModal = !recentlyInModal && this.lastModalExitAt > 0 && now - this.lastModalExitAt < postModalGraceMs;
         // screen_active_hold_ms: suppress idle downshift while the screen is
@@ -555,7 +650,6 @@ export class SpecDriver {
         if (evState.id === 'busy' && completionIdleRule && !recentlyInModal && !recentlyLeftModal && !screenIsActive) {
             const completionKey = matchesCompletionIdleRule(this.spec, ev, screen);
             if (completionKey) {
-                const now = Date.now();
                 if (completionKey !== this.completionIdleKey) {
                     this.completionIdleKey = completionKey;
                     this.completionIdleFirstSeenAt = now;
@@ -741,8 +835,7 @@ export class SpecDriver {
         // reading during the banner paint as a real idle. After that,
         // the first non-busy observation is a real prompt-ready signal
         // and we drain any queued send_message calls.
-        const graceMs = this.spec.debounce?.startup_grace_ms ?? STARTUP_GRACE_MS;
-        const sinceStart = Date.now() - this.startedAtMs;
+        const sinceStart = now - this.startedAtMs;
         if (!this.idleSeenOnce && evState.id !== 'busy' && sinceStart >= graceMs) {
             this.idleSeenOnce = true;
             const queued = this.pendingSends.splice(0);
@@ -972,7 +1065,7 @@ function sectionTextFromSnapshot(spec: CliSpec, screen: string, sectionId: strin
     return ev.sections.find(s => s.id === sectionId)?.text ?? null;
 }
 
-function guessExt(mime: string): string {
+export function guessExt(mime: string): string {
     if (/png/i.test(mime)) return '.png';
     if (/jpe?g/i.test(mime)) return '.jpg';
     if (/gif/i.test(mime)) return '.gif';

package/src/providers/spec/evaluator.ts

@@ -81,7 +81,7 @@ function resolveSize(size: number | string | undefined, total: number): number {
  * Resolve v3 sections{} object into an ordered array of ResolvedSection.
  * Two-pass: first anchor/positional, then apply `until` cross-references.
  */
-function resolveSections(
+export function resolveSections(
     sectionsObj: Record<string, SectionDef>,
     lines: string[],
 ): ResolvedSection[] {
@@ -167,7 +167,7 @@ function resolveSections(
     return resolved;
 }
 
-function sectionText(sections: ResolvedSection[], sectionId: string | undefined, fullScreen: string): string {
+export function sectionText(sections: ResolvedSection[], sectionId: string | undefined, fullScreen: string): string {
     if (!sectionId) return fullScreen;
     const found = sections.find(s => s.id === sectionId);
     return found ? found.text : '';
@@ -193,7 +193,7 @@ function isAnyCondition(c: Condition): c is AnyCondition {
     return 'any' in c;
 }
 
-function evaluateCondition(
+export function evaluateCondition(
     cond: Condition,
     sections: ResolvedSection[],
     fullScreen: string,
@@ -227,8 +227,15 @@ function evaluateCondition(
         const endRow = cursor.row; // exclusive
         const currentSlice = curLines.slice(startRow, endRow).join('\n');
         const prevSlice = prevLines.slice(startRow, endRow).join('\n');
-        const result = currentSlice !== prevSlice;
-        trace.push({ kind: 'section', text: `state[${stateId}] changed cond cursor_above=${cond.cursor_above} rows[${startRow},${endRow}) changed=${result}` });
+        const didChange = currentSlice !== prevSlice;
+        // changed:false means "region is currently stable" — stable_ms duration
+        // is enforced by the driver, not here.
+        const result = cond.changed ? didChange : !didChange;
+        const stableSuffix = cond.stable_ms != null ? ` stable_ms=${cond.stable_ms}` : '';
+        trace.push({
+            kind: result ? 'state_match' : 'state_skip',
+            text: `state[${stateId}] changed cond cursor_above=${cond.cursor_above} rows[${startRow},${endRow}) changed=${didChange} expected=${cond.changed}${stableSuffix} result=${result}`,
+        });
         return result;
     }
 
@@ -314,7 +321,7 @@ function matchState(
     return { matched: true, title };
 }
 
-function extractTitle(
+export function extractTitle(
     rule: ExtractTitle,
     sections: ResolvedSection[],
     fullScreen: string,
@@ -355,7 +362,7 @@ function compileLinePattern(ref: { pattern: string; flags?: string }): RegExp {
     return new RegExp(ref.pattern, flags);
 }
 
-function extractButtonsFromRule(
+export function extractButtonsFromRule(
     rule: ExtractButtons,
     hay: string,
 ): { index: number; label: string; key: string }[] {