@sagmans/dsh-tui 0.3.0 → 0.5.0

package/lib/herdr/reporter.js

@@ -0,0 +1,217 @@
+/**
+ * Telling a containing Herdr what this pane is doing.
+ *
+ * The reporter is inert unless Herdr started this process and exported its
+ * socket, so the surface behaves identically in a bare terminal and never
+ * depends on the multiplexer being there. Nothing here may reach the reader:
+ * a report is best-effort, its failures are dropped, and the alternate screen
+ * owns stdout.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHerdrClient } from "./client.js";
+import { EXIT_RELEASE_TIMEOUT_MS, HERDR_AGENT, HERDR_BIN_PATH_VAR, HERDR_ENV_FLAG, HERDR_ENV_VAR, HERDR_PANE_ID_VAR, HERDR_SOCKET_PATH_VAR, HERDR_SOURCE, METADATA_TOKENS, RETRY_BASE_MS, RETRY_MAX_MS, } from "./constants.js";
+import { boundedMessage, createReportSequence, isReportChange, lifecycleReport } from "./state.js";
+export function createHerdrReporter(options = {}) {
+    const env = options.env ?? process.env;
+    const client = options.client ?? createHerdrClient(env);
+    const nextSeq = createReportSequence(options.now ?? Date.now);
+    // A fresh sequence rides along: Herdr keeps the newest number per source and
+    // drops a release that cannot beat the reports this pane already sent.
+    const release = options.releaseSync ?? (() => releaseAgentSync(env, nextSeq()));
+    const retryBaseMs = Math.max(1, options.retryBaseMs ?? RETRY_BASE_MS);
+    let blockedCount = 0;
+    let blockedMessage;
+    let turnOpen = false;
+    let sessionId;
+    let wantedState;
+    let wantedSession;
+    let wantedMetadata;
+    let stateSent = false;
+    let sessionSent = false;
+    let metadataSent = false;
+    let released = false;
+    let retryTimer;
+    let retryAttempt = 0;
+    let releasing;
+    const owed = () => (wantedState !== undefined && !stateSent) ||
+        (wantedSession !== undefined && !sessionSent) ||
+        (wantedMetadata !== undefined && !metadataSent);
+    const cancelRetry = () => {
+        if (retryTimer !== undefined)
+            clearTimeout(retryTimer);
+        retryTimer = undefined;
+        retryAttempt = 0;
+    };
+    /**
+     * Try an unacknowledged report again, later.
+     *
+     * A report that failed leaves the pane reading as something it is not, and
+     * the surface may have nothing else to say: a turn that ended while the
+     * socket was down produces no further event, so the retry cannot wait for
+     * one. The wait backs off so a socket that stays down is not hammered, and it
+     * never holds the process open.
+     */
+    const scheduleRetry = () => {
+        if (released || retryTimer !== undefined)
+            return;
+        retryAttempt += 1;
+        const wait = Math.min(retryBaseMs * 2 ** (retryAttempt - 1), RETRY_MAX_MS);
+        retryTimer = setTimeout(() => {
+            retryTimer = undefined;
+            flush();
+        }, wait);
+        retryTimer.unref();
+    };
+    /**
+     * Send what Herdr has not acknowledged.
+     *
+     * A report that failed is still owed: a socket that was down while a turn ran
+     * would otherwise leave the pane reading as working forever, and a session
+     * whose identity never arrived is one a reader cannot return to. Each flag is
+     * set before the send and cleared only by a failure, so the next publish
+     * retries exactly what is missing and a delivered report is never repeated.
+     */
+    const flush = () => {
+        if (released)
+            return;
+        const afterDelivery = (delivered) => {
+            if (!delivered) {
+                scheduleRetry();
+                return;
+            }
+            if (!owed())
+                cancelRetry();
+        };
+        if (wantedSession !== undefined && !sessionSent) {
+            const report = wantedSession;
+            sessionSent = true;
+            void client.reportSession({ sessionId: report.sessionId, seq: nextSeq(), reason: report.reason })
+                .then(delivered => {
+                if (!delivered)
+                    sessionSent = false;
+                afterDelivery(delivered);
+            });
+        }
+        if (wantedMetadata !== undefined && !metadataSent) {
+            const tokens = wantedMetadata;
+            metadataSent = true;
+            void client.reportMetadata(tokens).then(delivered => {
+                if (!delivered)
+                    metadataSent = false;
+                afterDelivery(delivered);
+            });
+        }
+        if (wantedState !== undefined && !stateSent) {
+            const next = wantedState;
+            stateSent = true;
+            void client.reportState({ state: next.state, message: next.message, seq: nextSeq(), sessionId })
+                .then(delivered => {
+                if (!delivered)
+                    stateSent = false;
+                afterDelivery(delivered);
+            });
+        }
+    };
+    const reporter = {
+        enabled: client.enabled,
+        working() {
+            turnOpen = true;
+            reporter.publish();
+        },
+        idle() {
+            turnOpen = false;
+            reporter.publish();
+        },
+        block(message) {
+            blockedCount += 1;
+            blockedMessage = boundedMessage(message);
+            reporter.publish();
+        },
+        unblock() {
+            blockedCount = Math.max(0, blockedCount - 1);
+            // The last wait settled, so the message it was named by is stale; a later
+            // wait brings its own.
+            if (blockedCount === 0)
+                blockedMessage = undefined;
+            reporter.publish();
+        },
+        session(input) {
+            sessionId = input.id;
+            wantedSession = { sessionId: input.id, reason: input.reason };
+            sessionSent = false;
+            wantedMetadata = { [METADATA_TOKENS.session]: input.id, [METADATA_TOKENS.cwd]: input.cwd };
+            metadataSent = false;
+            // Forced: a switch can land on the state Herdr already shows, and the
+            // session identity is part of what the pane means.
+            reporter.publish(true);
+        },
+        publish(force = false) {
+            const next = lifecycleReport({ blockedCount, blockedMessage, turnOpen });
+            if (force || isReportChange(wantedState, next)) {
+                wantedState = next;
+                stateSent = false;
+            }
+            flush();
+        },
+        releaseSync() {
+            // One release is enough: both the exit path and the teardown path can ask,
+            // and a second spawn would only delay the process leaving.
+            if (released)
+                return;
+            released = true;
+            cancelRetry();
+            // Nothing may be reported after this: the pane is no longer an agent, and
+            // a report that landed later would claim the row back for a process that
+            // is on its way out.
+            client.stop();
+            release();
+        },
+        release() {
+            if (released)
+                return Promise.resolve();
+            // Reports already on the wire are waited for before the row goes back:
+            // Herdr ignores the release of a pane nothing has claimed, so a report
+            // that arrived after it would claim the row back with an older number.
+            // The synchronous release stays as the path an exit cannot skip. One
+            // promise is shared so two callers cannot release against each other.
+            releasing ??= (async () => {
+                client.stop();
+                await client.settle();
+                reporter.releaseSync();
+            })();
+            return releasing;
+        },
+        registerExitRelease() {
+            const listener = () => reporter.releaseSync();
+            process.once('exit', listener);
+            return () => {
+                process.off('exit', listener);
+            };
+        },
+    };
+    return reporter;
+}
+/**
+ * Release the pane's agent row synchronously.
+ *
+ * The process is leaving, so an awaited report would be dropped with the event
+ * loop and Herdr would keep showing a state nothing owns any more — a pane that
+ * reads as blocked forever is worse than one that reads as ordinary. The CLI is
+ * the only channel that still works at this point.
+ *
+ * `seq` is what makes the release land, so it is required rather than optional:
+ * Herdr sequences reports per source and treats a release that cannot beat them
+ * as stale, which would leave the row of a process that is already gone.
+ */
+export function releaseAgentSync(env, seq) {
+    const paneId = env[HERDR_PANE_ID_VAR];
+    if (env[HERDR_ENV_VAR] !== HERDR_ENV_FLAG || paneId === undefined || env[HERDR_SOCKET_PATH_VAR] === undefined)
+        return;
+    const argv = ['pane', 'release-agent', paneId, '--source', HERDR_SOURCE, '--agent', HERDR_AGENT, '--seq', String(seq)];
+    spawnSync(env[HERDR_BIN_PATH_VAR] ?? 'herdr', argv, {
+        env: { ...process.env, ...env },
+        stdio: 'ignore',
+        timeout: EXIT_RELEASE_TIMEOUT_MS,
+    });
+}
+//# sourceMappingURL=reporter.js.map

package/lib/herdr/reporter.js.map

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

package/lib/herdr/state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The state decision, without any transport.
+ *
+ * Keeping this apart from the socket is what makes the mapping testable: the
+ * surface knows facts about itself, Herdr wants one of three words, and the
+ * translation between them is the part worth pinning down.
+ */
+import { type HerdrState, type SessionStartReason } from './constants.ts';
+/** How the surface opened the session it is now showing. */
+export interface SessionStartFacts {
+    readonly forked: boolean;
+    readonly resumed: boolean;
+}
+/** What the surface knows about itself. */
+export interface LifecycleFacts {
+    /** How many decisions are waiting on the reader; they can stack. */
+    readonly blockedCount: number;
+    readonly blockedMessage: string | undefined;
+    readonly turnOpen: boolean;
+}
+export interface LifecycleReport {
+    readonly state: HerdrState;
+    readonly message: string | undefined;
+}
+/**
+ * The state Herdr should show.
+ *
+ * A wait outranks a running turn because a turn that is waiting on a human is
+ * not making progress, and the wait is the only thing a reader glancing at a
+ * wall of panes can still act on.
+ */
+export declare function lifecycleReport(facts: LifecycleFacts): LifecycleReport;
+/**
+ * The message that names a wait, bounded.
+ *
+ * A title long enough to be cut still tells the reader which decision is
+ * pending, which is the only job the message has.
+ */
+export declare function boundedMessage(message: string): string;
+/**
+ * The reason Herdr is told a session opened.
+ *
+ * A fork and a resume are different acts to a reader scanning panes later: one
+ * inherited a conversation, the other returned to it.
+ */
+export declare function sessionStartReason(input: SessionStartFacts): SessionStartReason;
+/** Whether a report would say something Herdr is not already showing. */
+export declare function isReportChange(last: LifecycleReport | undefined, next: LifecycleReport): boolean;
+/**
+ * Monotonic report sequence numbers.
+ *
+ * The clock is the base rather than zero because a restarted surface must not
+ * replay numbers this pane already used: Herdr would read them as stale and
+ * keep showing the state from before the restart.
+ */
+export declare function createReportSequence(now: () => number): () => number;
+//# sourceMappingURL=state.d.ts.map

package/lib/herdr/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/herdr/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAA;AAEvB,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AACD,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CAItE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAG/E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAEhG;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,MAAM,GAAG,MAAM,MAAM,CAMpE"}

package/lib/herdr/state.js

@@ -0,0 +1,62 @@
+/**
+ * The state decision, without any transport.
+ *
+ * Keeping this apart from the socket is what makes the mapping testable: the
+ * surface knows facts about itself, Herdr wants one of three words, and the
+ * translation between them is the part worth pinning down.
+ */
+import { HERDR_STATES, MAX_BLOCKED_MESSAGE_CHARS, SEQ_TIME_SCALE, SESSION_START_REASONS, } from "./constants.js";
+/**
+ * The state Herdr should show.
+ *
+ * A wait outranks a running turn because a turn that is waiting on a human is
+ * not making progress, and the wait is the only thing a reader glancing at a
+ * wall of panes can still act on.
+ */
+export function lifecycleReport(facts) {
+    if (facts.blockedCount > 0)
+        return { state: HERDR_STATES.blocked, message: facts.blockedMessage };
+    if (facts.turnOpen)
+        return { state: HERDR_STATES.working, message: undefined };
+    return { state: HERDR_STATES.idle, message: undefined };
+}
+/**
+ * The message that names a wait, bounded.
+ *
+ * A title long enough to be cut still tells the reader which decision is
+ * pending, which is the only job the message has.
+ */
+export function boundedMessage(message) {
+    const trimmed = message.replace(/\s+/gu, ' ').trim();
+    return trimmed.length <= MAX_BLOCKED_MESSAGE_CHARS ? trimmed : `${trimmed.slice(0, MAX_BLOCKED_MESSAGE_CHARS - 1)}…`;
+}
+/**
+ * The reason Herdr is told a session opened.
+ *
+ * A fork and a resume are different acts to a reader scanning panes later: one
+ * inherited a conversation, the other returned to it.
+ */
+export function sessionStartReason(input) {
+    if (input.forked)
+        return SESSION_START_REASONS.fork;
+    return input.resumed ? SESSION_START_REASONS.resume : SESSION_START_REASONS.startup;
+}
+/** Whether a report would say something Herdr is not already showing. */
+export function isReportChange(last, next) {
+    return last === undefined || last.state !== next.state || last.message !== next.message;
+}
+/**
+ * Monotonic report sequence numbers.
+ *
+ * The clock is the base rather than zero because a restarted surface must not
+ * replay numbers this pane already used: Herdr would read them as stale and
+ * keep showing the state from before the restart.
+ */
+export function createReportSequence(now) {
+    let sequence = now() * SEQ_TIME_SCALE;
+    return () => {
+        sequence += 1;
+        return sequence;
+    };
+}
+//# sourceMappingURL=state.js.map

package/lib/herdr/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/herdr/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,cAAc,EACd,qBAAqB,GAGtB,MAAM,gBAAgB,CAAA;AAoBvB;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAqB;IACnD,IAAI,KAAK,CAAC,YAAY,GAAG,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,cAAc,EAAE,CAAA;IACjG,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;IAC9E,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;IACpD,OAAO,OAAO,CAAC,MAAM,IAAI,yBAAyB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,yBAAyB,GAAG,CAAC,CAAC,GAAG,CAAA;AACtH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IACzD,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,qBAAqB,CAAC,IAAI,CAAA;IACnD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAA;AACrF,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,IAAiC,EAAE,IAAqB;IACrF,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO,CAAA;AACzF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAiB;IACpD,IAAI,QAAQ,GAAG,GAAG,EAAE,GAAG,cAAc,CAAA;IACrC,OAAO,GAAG,EAAE;QACV,QAAQ,IAAI,CAAC,CAAA;QACb,OAAO,QAAQ,CAAA;IACjB,CAAC,CAAA;AACH,CAAC"}

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAkFlD,eAAO,MAAM,IAAI,QAAQ,CAAA;AAEzB;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,UAAsB,CAAA;AAwCzC;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,GAAE;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC1B,GAAG,IAAI,CAMZ;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAupDzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAoGlD,eAAO,MAAM,IAAI,QAAQ,CAAA;AAEzB;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,UAAsB,CAAA;AA2CzC;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,GAAE;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC1B,GAAG,IAAI,CAMZ;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CA2wEzD"}