@adhdev/daemon-core 0.9.82-rc.217 → 0.9.82-rc.219

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

@@ -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;
@@ -195,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>();
@@ -535,6 +574,19 @@ 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.
@@ -783,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);
@@ -1014,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,
@@ -231,7 +231,11 @@ function evaluateCondition(
         // changed:false means "region is currently stable" — stable_ms duration
         // is enforced by the driver, not here.
         const result = cond.changed ? didChange : !didChange;
-        trace.push({ kind: 'section', text: `state[${stateId}] changed cond cursor_above=${cond.cursor_above} rows[${startRow},${endRow}) changed=${didChange} expected=${cond.changed} result=${result}` });
+        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;
     }
 
@@ -317,7 +321,7 @@ function matchState(
     return { matched: true, title };
 }
 
-function extractTitle(
+export function extractTitle(
     rule: ExtractTitle,
     sections: ResolvedSection[],
     fullScreen: string,
@@ -358,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 }[] {