@adhdev/daemon-core 0.9.82-rc.16 → 0.9.82-rc.161

package/src/providers/spec/adapter.ts

@@ -0,0 +1,153 @@
+/**
+ * Thin generic terminal adapter.
+ *
+ * Spawns a PTY, feeds bytes into a headless xterm so a visible screen
+ * snapshot is always available, and exposes a small hook surface
+ * (init / tick / on_screen_changed / on_exit). Nothing in this module
+ * knows about agents, modals, or specs — it's just a terminal host.
+ *
+ * The Spec Driver is built on top of this adapter and consumes the
+ * hooks to drive its declarative state machine.
+ *
+ * Inbound from driver:
+ *   send_keys(str)  — raw bytes to PTY
+ *   resize(c, r)    — resize the PTY and the xterm
+ *   kill()          — terminate the child
+ *
+ * Outbound to driver:
+ *   init({ pid })
+ *   on_pty_data(chunk)            — raw bytes for dashboard's terminal pane
+ *   on_screen_changed(snapshot)   — coalesced visible-screen change
+ *   tick()                        — periodic timer (configurable interval)
+ *   on_exit({ exitCode })
+ */
+'use strict';
+
+import { Terminal } from '@xterm/headless';
+import { NodePtyTransportFactory, type PtyRuntimeTransport, type PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+
+export interface TerminalAdapterOpts {
+    binary: string;
+    args?: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    /** Coalesce screen snapshots: emit on_screen_changed at most this often. */
+    screenChangeDebounceMs?: number;
+    /** tick() period. 0 disables ticks. */
+    tickIntervalMs?: number;
+    /**
+     * Optional PTY transport factory. When the daemon supplies a
+     * SessionHostPtyTransportFactory (standalone runs the PTY inside the
+     * session-host so the runtime/<sid>/snapshot endpoint can serve it),
+     * forward it here. Without it the PTY spawns locally inside the
+     * daemon process and the dashboard's terminal pane reports
+     * "Runtime terminal unavailable: Unknown session".
+     */
+    transportFactory?: PtyTransportFactory;
+}
+
+export interface TerminalAdapterHandlers {
+    init?(info: { pid: number }): void;
+    on_pty_data?(chunk: string): void;
+    on_screen_changed?(snapshot: string): void;
+    tick?(): void;
+    on_exit?(info: { exitCode: number }): void;
+}
+
+export class TerminalAdapter {
+    private term: Terminal;
+    private pty: PtyRuntimeTransport | null = null;
+    private factory: PtyTransportFactory;
+    private cols: number;
+    private rows: number;
+    private screenDebounceMs: number;
+    private tickIntervalMs: number;
+    private screenTimer: ReturnType<typeof setTimeout> | null = null;
+    private tickTimer: ReturnType<typeof setInterval> | null = null;
+    private lastScreen = '';
+
+    constructor(
+        private readonly opts: TerminalAdapterOpts,
+        private readonly handlers: TerminalAdapterHandlers,
+    ) {
+        this.cols = opts.cols ?? 100;
+        this.rows = opts.rows ?? 30;
+        this.screenDebounceMs = opts.screenChangeDebounceMs ?? 80;
+        this.tickIntervalMs = opts.tickIntervalMs ?? 0;
+        this.factory = opts.transportFactory ?? new NodePtyTransportFactory();
+        this.term = new Terminal({ cols: this.cols, rows: this.rows, allowProposedApi: true, scrollback: 1000 });
+    }
+
+    start(): void {
+        this.pty = this.factory.spawn(this.opts.binary, this.opts.args ?? [], {
+            cwd: this.opts.cwd,
+            env: { ...process.env, ...(this.opts.env ?? {}) } as Record<string, string>,
+            cols: this.cols,
+            rows: this.rows,
+        });
+        this.handlers.init?.({ pid: this.pty.pid });
+        this.pty.onData((chunk) => this.onChunk(chunk));
+        this.pty.onExit((info) => {
+            this.stopTimers();
+            this.handlers.on_exit?.({ exitCode: typeof info.exitCode === 'number' ? info.exitCode : 0 });
+            this.pty = null;
+        });
+        if (this.tickIntervalMs > 0) {
+            this.tickTimer = setInterval(() => this.handlers.tick?.(), this.tickIntervalMs);
+        }
+    }
+
+    send_keys(s: string): void {
+        this.pty?.write(s);
+    }
+
+    resize(cols: number, rows: number): void {
+        this.cols = cols; this.rows = rows;
+        this.pty?.resize(cols, rows);
+        this.term.resize(cols, rows);
+    }
+
+    snapshot(): string {
+        return this.lastScreen || this.computeScreen();
+    }
+
+    kill(): void {
+        this.stopTimers();
+        try { this.pty?.kill(); } catch { /* ignore */ }
+        this.pty = null;
+        this.term.dispose();
+    }
+
+    private onChunk(chunk: string): void {
+        try { this.handlers.on_pty_data?.(chunk); } catch { /* user side */ }
+        this.term.write(chunk);
+        // Coalesce snapshot emission — rapid bursts shouldn't fire 200x.
+        if (this.screenTimer) return;
+        this.screenTimer = setTimeout(() => {
+            this.screenTimer = null;
+            const snap = this.computeScreen();
+            if (snap === this.lastScreen) return;
+            this.lastScreen = snap;
+            try { this.handlers.on_screen_changed?.(snap); } catch { /* user side */ }
+        }, this.screenDebounceMs);
+    }
+
+    private computeScreen(): string {
+        const buf = this.term.buffer.active;
+        const out: string[] = [];
+        for (let y = 0; y < buf.length; y += 1) {
+            const line = buf.getLine(y);
+            if (!line) continue;
+            out.push(line.translateToString(true));
+        }
+        while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+        return out.join('\n');
+    }
+
+    private stopTimers(): void {
+        if (this.screenTimer) { clearTimeout(this.screenTimer); this.screenTimer = null; }
+        if (this.tickTimer)   { clearInterval(this.tickTimer); this.tickTimer = null; }
+    }
+}

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

@@ -0,0 +1,318 @@
+/**
+ * SpecCliAdapter — bridges SpecDriver into the daemon's CliAdapter
+ * interface so an existing CliProviderInstance can drive a spec-backed
+ * provider without rewriting the surrounding session machinery.
+ *
+ * Translation:
+ *   spec state.id 'approval' (with modal_buttons that produced a modal)
+ *     → CliAdapterStatus.status='waiting_approval', activeModal={...}
+ *   spec state.id 'busy' / any non-decision state with a 'busy' label
+ *     → status='generating'
+ *   spec state.id 'idle' or default
+ *     → status='idle'
+ *
+ * Methods that the round-3 spec model doesn't have an opinion on
+ * (transcript reading, slash commands, history, runtime metadata
+ * surfacing) are minimal stubs. They satisfy the daemon's call sites
+ * without pretending to implement anything.
+ */
+'use strict';
+
+import { SpecDriver, type DashboardEvent } from './driver.js';
+import { loadSpec } from './loader.js';
+import type { CliSpec } 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';
+import { LOG } from '../../logging/logger.js';
+
+export class SpecCliAdapter implements CliAdapter {
+    readonly cliType: string;
+    readonly cliName: string;
+    readonly workingDir: string;
+
+    private driver: SpecDriver;
+    private spec: CliSpec;
+    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;
+    private statusCallback: (() => void) | null = null;
+    private ptyDataCallback: ((data: string) => void) | null = null;
+    private partialResponse = '';
+    private exited = false;
+    private spawned = false;
+    private providerSessionId: string | undefined;
+    /** Wall clock at the moment spawn() ran. Used as the cutoff for
+     *  native-history file selection so a prior session's transcript
+     *  can't leak into this session before the agent has written its
+     *  own records. */
+    private spawnedAtMs = 0;
+    /** Env vars the daemon set on the spawned child. Mesh coordinator
+     *  points hermes at a per-coordinator HERMES_HOME so the dashboard's
+     *  native-history reader needs that override to find the right
+     *  state.db; without it the reader sees ~/.hermes/state.db which
+     *  the coordinator-launched hermes never writes to. The choice to
+     *  redirect HERMES_HOME is a workaround for an unresolved hermes
+     *  upstream feature gap (see hermes-agent#23130 — runtime-supplied
+     *  MCP config), so this routing keeps the dashboard honest until
+     *  hermes ships a runtime MCP override. */
+    private spawnedEnv: Record<string, string> = {};
+
+    constructor(
+        specPath: string,
+        workingDir: string,
+        cliArgs: string[],
+        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;
+        this.cliType = this.spec.id;
+        this.cliName = this.spec.name;
+        this.workingDir = workingDir;
+        this.spawnedEnv = { ...extraEnv };
+
+        // 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
+        // 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({
+            specPath,
+            workingDir,
+            extraEnv,
+            hotReload: true,
+            emitTrace: false,
+            transportFactory,
+            extraCliArgs: cliArgs,
+        });
+        this.driver.subscribe((ev) => this.handleEvent(ev));
+    }
+
+    async spawn(): Promise<void> {
+        if (this.spawned) return;
+        this.driver.start();
+        this.spawned = true;
+        this.spawnedAtMs = Date.now();
+    }
+
+    async sendMessage(text: string): Promise<void> {
+        // Content-free at info — the prompt body is user data.
+        LOG.info('SpecAdapter', `[${this.cliType}] sendMessage(len=${text.length})`);
+        LOG.debug('SpecAdapter', `[${this.cliType}] sendMessage body=${JSON.stringify(text.slice(0, 80))}${text.length > 80 ? '…' : ''}`);
+        this.driver.dispatch({ kind: 'send_message', text });
+    }
+
+    getStatus(): CliAdapterStatus {
+        if (this.exited) return { status: 'stopped', messages: [], activeModal: null };
+        if (!this.spawned) return { status: 'starting', messages: [], activeModal: null };
+
+        // Refresh native history lazily — the watch_path is cheap to stat,
+        // but parsing a full session.jsonl every call would be wasteful.
+        this.maybeRefreshNativeHistory();
+
+        const state = this.latestState;
+        if (!state) return { status: 'starting', messages: [], activeModal: null };
+
+        const modal = this.latestModal;
+        const lc = state.id.toLowerCase();
+        if (modal) {
+            return {
+                status: 'waiting_approval',
+                messages: [],
+                activeModal: {
+                    message: modal.title ?? state.label,
+                    buttons: modal.buttons.map(b => b.label),
+                },
+            };
+        }
+        if (/busy|generating|working|running|thinking/i.test(lc + ' ' + state.label)) {
+            return { status: 'generating', messages: [], activeModal: null };
+        }
+        return { status: 'idle', messages: [], activeModal: null };
+    }
+
+    private maybeRefreshNativeHistory(): void {
+        // Native history is now sourced by daemon's chat-history pipeline
+        // (which calls provider.scripts.readNativeHistory wired by
+        // provider-loader). SpecCliAdapter no longer polls or caches.
+    }
+
+    getScriptParsedStatus(): unknown {
+        return this.getStatus();
+    }
+
+    getPartialResponse(): string {
+        return this.partialResponse;
+    }
+
+    shutdown(): void {
+        try { this.driver.dispatch({ kind: 'shutdown' }); } catch { /* ignore */ }
+    }
+
+    cancel(): void {
+        try { this.driver.dispatch({ kind: 'cancel' }); } catch { /* ignore */ }
+    }
+
+    isProcessing(): boolean {
+        return this.getStatus().status === 'generating';
+    }
+
+    isReady(): boolean {
+        return this.spawned && !this.exited;
+    }
+
+    setOnStatusChange(cb: () => void): void {
+        this.statusCallback = cb;
+    }
+
+    setOnPtyData(cb: (data: string) => void): void {
+        this.ptyDataCallback = cb;
+    }
+
+    writeRaw(data: string): void {
+        // Raw pty input — typed characters, escape codes, arrow keys —
+        // goes straight to the underlying terminal. send_message would
+        // append submit_key after every chunk, which is why typing in
+        // the dashboard terminal felt like "enter on every keystroke".
+        this.driver.dispatch({ kind: 'pty_write', data });
+    }
+
+    resize(cols: number, rows: number): void {
+        this.driver.dispatch({ kind: 'resize', cols, rows });
+    }
+
+    resolveModal(buttonIndex: number): void {
+        // CliAdapter buttonIndex is 0-based; spec buttons are 1-based.
+        this.driver.dispatch({ kind: 'click_modal_button', index: buttonIndex + 1 });
+    }
+
+    async resolveAction(data: unknown): Promise<void> {
+        const args = (data && typeof data === 'object') ? (data as any) : {};
+        const explicitIndex = typeof args.buttonIndex === 'number' ? args.buttonIndex : -1;
+        if (explicitIndex >= 0) { this.resolveModal(explicitIndex); return; }
+        const action = typeof args.action === 'string' ? args.action : 'approve';
+        const buttons = this.latestModal?.buttons ?? [];
+        if (buttons.length === 0) return;
+        let target = -1;
+        if (action === 'reject' || action === 'deny') {
+            target = buttons.findIndex(b => /^(no|deny|reject|cancel)\b/i.test(b.label));
+            if (target < 0) target = buttons.length - 1;
+        } else {
+            target = buttons.findIndex(b => /^(yes|allow|approve|accept|continue|proceed|update)\b/i.test(b.label));
+            if (target < 0) target = 0;
+        }
+        this.resolveModal(target);
+    }
+
+    isApprovalRecentlyResolved(): boolean { return false; }
+    clearHistory(): void { /* no transcript buffer yet */ }
+    updateRuntimeSettings(): void { /* no runtime settings in spec model yet */ }
+    setServerConn(): void { /* server conn unused by SpecDriver */ }
+    /**
+     * Map an invokeScript(name, args) call onto a control_bar entry.
+     *
+     * scriptName is matched against control.id. The control's action.type
+     * drives the dispatch:
+     *
+     *   send_keys     → click_control                   (e.g. stop)
+     *   open_picker   → click_control then resolve when extract_choices
+     *                   surface; choice index comes from args.choiceIndex
+     *                   or args.choice (string label match), defaulting to 0
+     *   attach_image  → attach_image dispatch; expects args.blob (data url
+     *                   or base64) and args.mime
+     *
+     * Callers that pass an unknown control id get a { not_found } response.
+     * No control matched, no driver call — keeps the surface honest.
+     */
+    invokeScript(scriptName: string, args?: Record<string, unknown>): Promise<unknown> {
+        const controls = this.spec.control_bar ?? [];
+        const ctl = controls.find(c => c.id === scriptName);
+        if (!ctl) {
+            return Promise.resolve({ ok: false, error: `unknown control: ${scriptName}` });
+        }
+        // Args may arrive as either { blob, mime } (direct invocation) or
+        // { params: { blob, mime } } (when the dashboard wraps script args
+        // in a params bag). Look at both.
+        const flat: Record<string, unknown> = { ...(args || {}) };
+        if (args && typeof args.params === 'object' && args.params) {
+            Object.assign(flat, args.params as Record<string, unknown>);
+        }
+        const action = ctl.action;
+        if (action.type === 'attach_image') {
+            const blob = typeof flat.blob === 'string' ? flat.blob : '';
+            const mime = typeof flat.mime === 'string' ? flat.mime : 'image/png';
+            if (!blob) return Promise.resolve({ ok: false, error: 'attach_image requires args.blob (base64 or data URL)' });
+            this.driver.dispatch({ kind: 'attach_image', blob, mime });
+            return Promise.resolve({ ok: true, effects: [{ type: 'attached_image', controlId: ctl.id }] });
+        }
+        // send_keys + open_picker both route through click_control. For
+        // open_picker the dashboard sees the picker modal arrive via a
+        // state_changed event, then submits the choice using
+        // resolveModal/click_modal_button. invokeScript's synchronous
+        // return is just an acknowledgement that the trigger fired.
+        this.driver.dispatch({ kind: 'click_control', control_id: ctl.id, payload: flat });
+        const effects: { type: string; controlId: string }[] = [];
+        if (action.type === 'open_picker') effects.push({ type: 'opened_picker', controlId: ctl.id });
+        else if (action.type === 'send_keys') effects.push({ type: 'sent_keys', controlId: ctl.id });
+        return Promise.resolve({ ok: true, effects });
+    }
+    getDebugSnapshot(): unknown {
+        return {
+            cliType: this.cliType,
+            spec_id: this.spec.id,
+            current_state: this.latestState,
+            current_modal: this.latestModal,
+            exited: this.exited,
+        };
+    }
+    getRuntimeMetadata(): unknown {
+        return {
+            runtimeId: this.spec.id,
+            runtimeKey: this.spec.id,
+            displayName: this.spec.name,
+            spawnedAtMs: this.spawnedAtMs,
+            spawnedEnv: this.spawnedEnv,
+        };
+    }
+    updateRuntimeMeta(meta?: Record<string, unknown>): void {
+        if (meta && typeof meta.providerSessionId === 'string') {
+            this.providerSessionId = meta.providerSessionId;
+        }
+    }
+    refreshProviderDefinition(): void { /* hot reload handled by SpecDriver fs.watch */ }
+
+    private handleEvent(ev: DashboardEvent): void {
+        this.lastEvent = ev;
+        switch (ev.kind) {
+            case 'state_changed':
+                this.latestState = ev.state;
+                this.latestModal = ev.modal;
+                // info-level keeps only spec-defined identifiers (state.id /
+                // state.label / button count). The extracted title can carry
+                // user data — file paths, command text, ticket titles — so
+                // it stays at debug.
+                LOG.info('SpecAdapter', `[${this.cliType}] state=${ev.state.id} (${ev.state.label}) modal=${ev.modal ? `${ev.modal.buttons.length}-buttons` : 'none'}`);
+                if (ev.state.title) {
+                    LOG.debug('SpecAdapter', `[${this.cliType}] state.title=${JSON.stringify(ev.state.title)}`);
+                }
+                this.statusCallback?.();
+                return;
+            case 'pty_data':
+                try { this.ptyDataCallback?.(ev.chunk); } catch { /* ignore */ }
+                return;
+            case 'exit':
+                this.exited = true;
+                this.statusCallback?.();
+                return;
+            case 'spec_error':
+                LOG.warn('SpecAdapter', `[${this.cliType}] spec reload error: ${ev.errors.join('; ')}`);
+                return;
+            default:
+                return;
+        }
+    }
+}
+