@agi-fans/dsh-tui 0.16.0 → 0.17.0

package/lib/runtime/herdr-agent.js

@@ -0,0 +1,258 @@
+/**
+ * Custom Herdr lifecycle integration.
+ *
+ * Herdr (https://herdr.dev) detects a fixed set of agents and lets every other
+ * agent claim a pane's lifecycle authority itself over the local socket
+ * (`pane.report_agent` / `pane.release_agent`). This module implements that
+ * contract: it reports `idle`, `working`, and `blocked` for omdsh and is a
+ * complete no-op outside a Herdr pane.
+ *
+ * The status projection is a pure controller; the reporter adds the stable
+ * source identity, the strictly increasing sequence Herdr requires, the native
+ * session reference, and best-effort socket delivery.
+ * @module runtime/herdr-agent
+ */
+import { connect } from 'node:net';
+/** Stable, integration-unique source namespace Herdr requires for custom reports. */
+export const HERDR_REPORT_SOURCE = 'custom:omdsh';
+/** Agent label Herdr shows in its sidebar and agent list. */
+export const HERDR_AGENT_LABEL = 'omdsh';
+/**
+ * Pane-authoritative Herdr detection.
+ *
+ * `HERDR_ENV=1` is the canonical marker; the pane id and socket path are what
+ * the protocol needs. Client-side overrides (`HERDR_SOCKET_PATH`,
+ * `HERDR_BIN_PATH`, `HERDR_SESSION`) can be set outside a pane, so they are
+ * never detection evidence on their own.
+ */
+export function herdrEnvironment(env = process.env) {
+    if (env.HERDR_ENV !== '1')
+        return undefined;
+    const paneId = env.HERDR_PANE_ID?.trim();
+    const socketPath = env.HERDR_SOCKET_PATH?.trim();
+    if (paneId === undefined || paneId === '' || socketPath === undefined || socketPath === '')
+        return undefined;
+    return { paneId, socketPath };
+}
+const HERDR_MESSAGE_LIMIT = 240;
+function cleanHerdrMessage(value) {
+    if (value === undefined)
+        return undefined;
+    const cleaned = value
+        .replace(/[\x00-\x1f\x7f-\x9f]/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, HERDR_MESSAGE_LIMIT);
+    return cleaned === '' ? undefined : cleaned;
+}
+/**
+ * Pure state projection: an active driver plus the human prompts it is blocked
+ * on decide the single semantic state Herdr understands. `blocked` wins over
+ * `working` because a blocked pane must reject `herdr agent prompt` input.
+ */
+export class HerdrAgentStatusController {
+    #running = false;
+    #prompts = 0;
+    #promptMessage;
+    #last;
+    /** The initial report makes Herdr attach the agent to the pane before any turn. */
+    start() {
+        return this.#publish(true);
+    }
+    setRunning(running) {
+        this.#running = running;
+        return this.#publish();
+    }
+    prompt(message) {
+        this.#prompts += 1;
+        const cleaned = cleanHerdrMessage(message);
+        if (cleaned !== undefined)
+            this.#promptMessage = cleaned;
+        return this.#publish();
+    }
+    promptResolved() {
+        if (this.#prompts === 0)
+            return undefined;
+        this.#prompts -= 1;
+        if (this.#prompts === 0)
+            this.#promptMessage = undefined;
+        return this.#publish();
+    }
+    /**
+     * Forget the last projection without reporting. A replaced session makes
+     * the previous state meaningless, but only a fresh signal may publish,
+     * because a compaction or resume can swap sessions mid-driver.
+     */
+    reset() {
+        this.#running = false;
+        this.#prompts = 0;
+        this.#promptMessage = undefined;
+        this.#last = undefined;
+    }
+    #desired() {
+        if (this.#prompts > 0) {
+            return this.#promptMessage === undefined
+                ? { state: 'blocked' }
+                : { state: 'blocked', message: this.#promptMessage };
+        }
+        return this.#running ? { state: 'working' } : { state: 'idle' };
+    }
+    #publish(force = false) {
+        const next = this.#desired();
+        const signature = `${next.state}\u0000${next.message ?? ''}`;
+        if (!force && signature === this.#last)
+            return undefined;
+        this.#last = signature;
+        return next;
+    }
+}
+/**
+ * Report omdsh lifecycle state to the Herdr pane that owns this process.
+ *
+ * Reports are best-effort and silent, matching Herdr's own integrations: a
+ * missing or restarted server must never disturb the TUI.
+ */
+export class HerdrAgentReporter {
+    #environment;
+    #transport;
+    #controller = new HerdrAgentStatusController();
+    #now;
+    #seq;
+    #sessionId;
+    #released = false;
+    constructor(options = {}) {
+        this.#now = options.now ?? (() => Date.now());
+        this.#seq = this.#now() * 1000;
+        this.#environment = herdrEnvironment(options.env ?? process.env);
+        this.#transport = this.#environment === undefined
+            ? undefined
+            : (options.transport ?? defaultHerdrTransport)(this.#environment.socketPath);
+    }
+    /** Whether this process runs inside a Herdr pane with a usable socket. */
+    get active() {
+        return this.#transport !== undefined;
+    }
+    start() {
+        this.#report(this.#controller.start());
+    }
+    setRunning(running) {
+        this.#report(this.#controller.setRunning(running));
+    }
+    prompt(message) {
+        this.#report(this.#controller.prompt(message));
+    }
+    promptResolved() {
+        this.#report(this.#controller.promptResolved());
+    }
+    /** Attach the native session reference Herdr exposes on its agent records. */
+    setSession(sessionId) {
+        const trimmed = sessionId?.trim();
+        const next = trimmed === undefined || trimmed === '' ? undefined : trimmed;
+        if (next === this.#sessionId)
+            return;
+        this.#sessionId = next;
+        this.#controller.reset();
+    }
+    /** Release the pane's lifecycle authority; later reports are dropped. */
+    release() {
+        const environment = this.#environment;
+        const transport = this.#transport;
+        if (this.#released || environment === undefined || transport === undefined)
+            return;
+        this.#released = true;
+        this.#deliver(transport, {
+            id: `${HERDR_REPORT_SOURCE}:release:${this.#now()}`,
+            method: 'pane.release_agent',
+            params: {
+                pane_id: environment.paneId,
+                source: HERDR_REPORT_SOURCE,
+                agent: HERDR_AGENT_LABEL,
+                seq: this.#nextSeq(),
+            },
+        });
+    }
+    #report(status) {
+        const environment = this.#environment;
+        const transport = this.#transport;
+        if (status === undefined || this.#released || environment === undefined || transport === undefined)
+            return;
+        const params = {
+            pane_id: environment.paneId,
+            source: HERDR_REPORT_SOURCE,
+            agent: HERDR_AGENT_LABEL,
+            state: status.state,
+            seq: this.#nextSeq(),
+        };
+        if (status.message !== undefined)
+            params.message = status.message;
+        if (this.#sessionId !== undefined)
+            params.agent_session_id = this.#sessionId;
+        this.#deliver(transport, {
+            id: `${HERDR_REPORT_SOURCE}:${status.state}:${this.#now()}`,
+            method: 'pane.report_agent',
+            params,
+        });
+    }
+    /** A broken transport must never throw into the TUI's status or dispose path. */
+    #deliver(transport, request) {
+        try {
+            transport.send(request);
+        }
+        catch {
+            // Best-effort delivery, matching Herdr's own integrations.
+        }
+    }
+    /**
+     * Strictly increasing across reporter instances in one process: Herdr
+     * ignores a report whose sequence is not above the last accepted one for the
+     * same source, so a plugin reload must not restart below a used sequence.
+     */
+    #nextSeq() {
+        this.#seq = Math.max(this.#seq + 1, this.#now() * 1000);
+        return this.#seq;
+    }
+}
+const HERDR_REQUEST_TIMEOUT_MS = 500;
+/**
+ * One JSON line per request over a short-lived local connection. The server
+ * acknowledges every request, but delivery stays fire-and-forget: the pane
+ * must never wait on Herdr, and `unref()` keeps a pending write from holding
+ * the process open.
+ */
+function defaultHerdrTransport(socketPath) {
+    const target = herdrSocketTarget(socketPath);
+    return {
+        send(request) {
+            let socket;
+            try {
+                socket = connect(target);
+            }
+            catch {
+                return;
+            }
+            socket.unref();
+            let timer;
+            const finish = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                socket.destroy();
+            };
+            timer = setTimeout(finish, HERDR_REQUEST_TIMEOUT_MS);
+            timer.unref();
+            socket.on('error', finish);
+            socket.on('connect', () => { socket.write(`${JSON.stringify(request)}\n`); });
+            socket.on('data', finish);
+            socket.on('end', finish);
+            socket.on('close', finish);
+        },
+    };
+}
+/** Herdr exports Unix-style paths; Windows dials them as named pipes. */
+export function herdrSocketTarget(socketPath, platform = process.platform) {
+    const lowered = socketPath.toLowerCase();
+    if (platform !== 'win32' || lowered.startsWith('\\\\.\\pipe\\') || lowered.startsWith('\\\\?\\pipe\\')) {
+        return socketPath;
+    }
+    return `\\\\.\\pipe\\${socketPath}`;
+}
+//# sourceMappingURL=herdr-agent.js.map

package/lib/runtime/herdr-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-agent.js","sourceRoot":"","sources":["../../src/runtime/herdr-agent.ts"],"names":[],"mappings":"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"}

package/lib/runtime/plain-tui.d.ts

@@ -0,0 +1,34 @@
+/** Non-TTY line input and incremental transcript printing. */
+import type { TuiPrompt, TuiSubmission } from '../definition.ts';
+import type { Block } from '../views/event-views.ts';
+import type { TerminalLike } from './provider-local.ts';
+export type PendingRead = {
+    resolve: (submission: TuiSubmission | null) => void;
+    signal?: AbortSignal | null;
+    /** Detaches this read's abort listener once the read settles. */
+    offAbort?: () => void;
+};
+export interface PlainTuiDeps {
+    readonly term: TerminalLike;
+    /** Transcript blocks, read live so `print()` always flushes the newest tail. */
+    blocks(): readonly Block[];
+    /** The in-flight human prompt's request, if one is waiting on an answer. */
+    promptRequest(): TuiPrompt | undefined;
+    /** Resolve the in-flight prompt; the provider owns prompt bookkeeping. */
+    finishPrompt(answer: string | null): void;
+}
+/**
+ * Pipe-mode counterpart of the TTY reader: a readline queue that buffers lines
+ * until the runner asks for the next submission, plus incremental transcript
+ * printing that emits each settled block exactly once.
+ */
+export declare class PlainTui {
+    #private;
+    constructor(deps: PlainTuiDeps);
+    readline(signal?: AbortSignal): Promise<TuiSubmission | null>;
+    /** Print blocks that settled since the last flush. */
+    print(): void;
+    /** Forget the print cursor so a replaced transcript reprints in full. */
+    resetPrinted(): void;
+    dispose(): void;
+}

package/lib/runtime/plain-tui.js

@@ -0,0 +1,119 @@
+/** Non-TTY line input and incremental transcript printing. */
+import { createInterface } from 'node:readline';
+import { blockLines } from "../views/event-views.js";
+import { createTheme } from "../chrome/theme.js";
+/**
+ * Pipe-mode counterpart of the TTY reader: a readline queue that buffers lines
+ * until the runner asks for the next submission, plus incremental transcript
+ * printing that emits each settled block exactly once.
+ */
+export class PlainTui {
+    #deps;
+    #lineReader = null;
+    #pending = null;
+    #queue = [];
+    #closed = false;
+    #printed = 0;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    readline(signal) {
+        return new Promise((resolve) => {
+            if (this.#lineReader === null) {
+                this.#lineReader = createInterface({ input: this.#deps.term.input });
+                // Permanent listeners: once() handlers would auto-pause the input
+                // stream after one line and miss the EOF close.
+                this.#lineReader.on('line', (line) => { this.#resolveLine(line); });
+                this.#lineReader.on('close', () => {
+                    this.#closed = true;
+                    this.#resolveLine(null);
+                });
+            }
+            const pending = { resolve, signal: signal ?? null };
+            this.#pending = pending;
+            if (signal !== undefined) {
+                const onAbort = () => {
+                    if (this.#pending !== pending)
+                        return;
+                    this.#pending = null;
+                    resolve(null);
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                pending.offAbort = () => { signal.removeEventListener('abort', onAbort); };
+            }
+            this.#pump();
+        });
+    }
+    /**
+     * Queue one readline delivery, then drain. A single stream chunk can carry
+     * several lines; every line is buffered until the runner asks for the next
+     * read, and EOF waits for the queue before closing the reader.
+     */
+    #resolveLine(line) {
+        const request = this.#deps.promptRequest();
+        if (request !== undefined && line !== null) {
+            const value = line.trim();
+            if (value === '') {
+                this.#deps.finishPrompt(null);
+            }
+            else if (request.allowCustom === false) {
+                const options = request.options ?? [];
+                const numeric = /^\d+$/u.test(value) ? Number(value) - 1 : -1;
+                const option = numeric >= 0
+                    ? options[numeric]
+                    : options.find(item => item.label.toLowerCase() === value.toLowerCase());
+                this.#deps.finishPrompt(option?.value ?? option?.label ?? null);
+            }
+            else {
+                this.#deps.finishPrompt(value);
+            }
+            return;
+        }
+        if (request !== undefined)
+            this.#deps.finishPrompt(null);
+        if (line !== null)
+            this.#queue.push(line);
+        this.#pump();
+    }
+    /** Resolve the pending read from the queue, or close it after EOF drained. */
+    #pump() {
+        const pending = this.#pending;
+        if (pending === null)
+            return;
+        const line = this.#queue.shift();
+        if (line !== undefined) {
+            pending.offAbort?.();
+            this.#pending = null;
+            pending.resolve({ text: line, images: [] });
+            return;
+        }
+        if (this.#closed) {
+            pending.offAbort?.();
+            this.#pending = null;
+            pending.resolve(null);
+        }
+    }
+    /** Print blocks that settled since the last flush. */
+    print() {
+        const theme = createTheme(false, false);
+        const width = this.#deps.term.width();
+        const blocks = this.#deps.blocks();
+        let out = '';
+        for (const block of blocks.slice(this.#printed)) {
+            // Pipe / CI output is not a viewport: print the full tool body.
+            for (const line of blockLines(block, theme, width, 0, true))
+                out += line + '\n';
+        }
+        this.#printed = blocks.length;
+        if (out !== '')
+            this.#deps.term.output.write(out);
+    }
+    /** Forget the print cursor so a replaced transcript reprints in full. */
+    resetPrinted() {
+        this.#printed = 0;
+    }
+    dispose() {
+        this.#lineReader?.close();
+    }
+}
+//# sourceMappingURL=plain-tui.js.map

package/lib/runtime/plain-tui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plain-tui.js","sourceRoot":"","sources":["../../src/runtime/plain-tui.ts"],"names":[],"mappings":"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"}

package/lib/runtime/provider-local.d.ts

@@ -10,6 +10,7 @@
  * printing of settled blocks.
  * @module @agi-fans/dsh-tui
  */
+import { HerdrAgentReporter } from './herdr-agent.ts';
 import type { Context } from '@deepseek-ai/cordis';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
 import { type TuiAgentBehaviorSettingsBinding, type TuiCommand, type TuiPrompt, type TuiNoticeOptions, type TuiRecentSession, type TuiService, type TuiSessionControls, type TuiSessionStats, type TuiStatus, type TuiInputImage, type TuiInspectedSubagent, type TuiLoopStatus, type TuiSubagentRoster, type TuiSubmission } from '../definition.ts';
@@ -85,6 +86,8 @@ export declare class LocalTui implements TuiService {
         alternateScreenOverlays?: boolean;
         resizeDebounceMs?: number;
         streamRenderMs?: number;
+        /** Herdr lifecycle reporter; production injects an environment-aware one. */
+        herdrReporter?: HerdrAgentReporter;
     });
     event(event: SessionEvent, presentation?: TuiToolPresentation): void;
     /**