@sagmans/dsh-tui 0.2.0 → 0.4.0

package/lib/herdr/client.js

@@ -0,0 +1,218 @@
+/**
+ * The Herdr socket.
+ *
+ * Every method resolves rather than throws: a multiplexer that is absent, busy,
+ * or restarting is not a failure this surface may surface to its reader, whose
+ * conversation is the thing on screen. The same reasoning keeps the transport
+ * off stdout and stderr — the alternate screen owns both.
+ */
+import { createConnection } from 'node:net';
+import { DEFAULT_ATTEMPTS, DEFAULT_TIMEOUT_MS, HERDR_AGENT, HERDR_ENV_FLAG, HERDR_ENV_VAR, HERDR_PANE_ID_VAR, HERDR_SOCKET_PATH_VAR, HERDR_SOURCE, MAX_METADATA_VALUE_CHARS, MAX_RESPONSE_BYTES, RESPONSE_DELIMITER, } from "./constants.js";
+/**
+ * Create the client for one pane.
+ *
+ * Requests are serialized instead of racing: state reports are sequenced
+ * server-side, and a queue keeps a session's identity arriving before the state
+ * that names it. The queue is bounded in practice because states change a
+ * handful of times a turn and each attempt is spent against one deadline.
+ */
+export function createHerdrClient(env = process.env, options = {}) {
+    const paneId = env[HERDR_PANE_ID_VAR];
+    const socketPath = env[HERDR_SOCKET_PATH_VAR];
+    // Herdr exports all three together; requiring each keeps a half-configured
+    // environment from producing reports that name no pane.
+    const enabled = env[HERDR_ENV_VAR] === HERDR_ENV_FLAG && paneId !== undefined && socketPath !== undefined;
+    const attempts = Math.max(1, options.attempts ?? DEFAULT_ATTEMPTS);
+    const timeoutMs = Math.max(1, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let requestNumber = 0;
+    let queued = [];
+    let pumping = false;
+    let closed = false;
+    let waiters = [];
+    const wake = () => {
+        const waiting = waiters;
+        waiters = [];
+        for (const resolve of waiting)
+            resolve();
+    };
+    const deliver = async (request) => socketPath === undefined
+        ? true
+        : sendWithRetry(socketPath, request, attempts, timeoutMs, () => closed);
+    const pump = async () => {
+        if (pumping)
+            return;
+        pumping = true;
+        try {
+            while (!closed && queued.length > 0) {
+                const next = queued.shift();
+                if (next === undefined)
+                    break;
+                next.settle(await deliver(next.request));
+            }
+        }
+        finally {
+            pumping = false;
+            wake();
+        }
+    };
+    const enqueue = (method, params, coalescing) => new Promise(resolve => {
+        if (closed || !enabled || paneId === undefined || socketPath === undefined) {
+            resolve(true);
+            return;
+        }
+        const request = {
+            id: `${HERDR_SOURCE}:${String(process.pid)}:${String(++requestNumber)}`,
+            method,
+            params: { pane_id: paneId, source: HERDR_SOURCE, agent: HERDR_AGENT, ...params },
+        };
+        if (coalescing && queued.some(entry => entry.coalescing)) {
+            const superseded = queued.filter(entry => entry.coalescing);
+            queued = queued.filter(entry => !entry.coalescing);
+            // Superseded, not lost: the report that replaced it says what this one
+            // said and more, so nothing is left owed to Herdr.
+            for (const entry of superseded)
+                entry.settle(true);
+        }
+        queued.push({ request, coalescing, settle: resolve });
+        void pump();
+    });
+    return {
+        enabled,
+        reportState(report) {
+            return enqueue('pane.report_agent', {
+                state: report.state,
+                seq: report.seq,
+                ...(report.message === undefined ? {} : { message: report.message }),
+                ...(report.sessionId === undefined ? {} : { agent_session_id: report.sessionId }),
+            }, true);
+        },
+        reportSession(report) {
+            return enqueue('pane.report_agent_session', {
+                agent_session_id: report.sessionId,
+                seq: report.seq,
+                session_start_source: report.reason,
+            }, false);
+        },
+        reportMetadata(tokens) {
+            return enqueue('pane.report_metadata', {
+                applies_to_source: HERDR_SOURCE,
+                tokens: acceptedTokens(tokens),
+            }, false);
+        },
+        stop() {
+            // Nothing still waiting is sent once the pane stops being an agent: Herdr
+            // ignores the release of a pane nothing has claimed, so a report that
+            // landed after the release would claim the row back for a process on its
+            // way out. What is already on the wire is left to finish — the waiters
+            // hear about it when it does, not before.
+            closed = true;
+            const discarded = queued;
+            queued = [];
+            for (const entry of discarded)
+                entry.settle(false);
+        },
+        async settle() {
+            // The wait ends when the transport itself is done, not when a timer says
+            // so: a report whose first attempt failed still has its retries to spend,
+            // and a release that ran between them would be answered as a pane with
+            // nothing to clear, leaving the row for that report to claim back. A
+            // report's own budget is what bounds this.
+            if (!pumping)
+                return;
+            await new Promise(resolve => {
+                waiters.push(resolve);
+            });
+        },
+    };
+}
+/**
+ * The tokens Herdr will accept, with the ones it cannot hold cleared.
+ *
+ * An over-long value is not refused: Herdr cuts it at the limit, so a path that
+ * was too long would come back shortened and read as another directory. A null
+ * is the one value that tells Herdr to forget the token, which is the honest
+ * answer for a fact that cannot be represented.
+ */
+export function acceptedTokens(tokens) {
+    const accepted = {};
+    for (const [key, value] of Object.entries(tokens)) {
+        accepted[key] = value === undefined || value.length > MAX_METADATA_VALUE_CHARS ? null : value;
+    }
+    return accepted;
+}
+/** Herdr's socket is a named pipe on Windows. */
+export function socketEndpoint(path) {
+    return process.platform === 'win32' ? `\\\\.\\pipe\\${path}` : path;
+}
+/**
+ * Spend one report's budget, not one per attempt.
+ *
+ * The deadline covers the whole report: a server that accepts a connection and
+ * answers slowly, but always within the idle timeout, would otherwise hold the
+ * queue open packet by packet for as long as it liked.
+ */
+async function sendWithRetry(path, request, attempts, timeoutMs, stopped) {
+    const deadline = Date.now() + timeoutMs;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        // A stopped transport does not try again: the pane is no longer an agent,
+        // and an attempt that landed after the release would claim the row back.
+        if (stopped())
+            return false;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        if (await sendAttempt(path, request, remaining))
+            return true;
+    }
+    return false;
+}
+function sendAttempt(path, request, timeoutMs) {
+    return new Promise(resolve => {
+        const socket = createConnection(socketEndpoint(path));
+        const chunks = [];
+        let received = 0;
+        let settled = false;
+        const finish = (delivered) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(expiry);
+            socket.destroy();
+            resolve(delivered);
+        };
+        // Idle time is the fast signal; the hard deadline is what a peer that keeps
+        // the socket busy cannot postpone.
+        const expiry = setTimeout(() => finish(false), timeoutMs);
+        socket.setTimeout(timeoutMs, () => finish(false));
+        socket.once('error', () => finish(false));
+        socket.once('end', () => finish(false));
+        socket.once('connect', () => socket.write(`${JSON.stringify(request)}${RESPONSE_DELIMITER}`));
+        socket.on('data', (chunk) => {
+            received += chunk.byteLength;
+            if (received > MAX_RESPONSE_BYTES) {
+                finish(false);
+                return;
+            }
+            chunks.push(chunk);
+            const response = Buffer.concat(chunks, received).toString('utf8');
+            const end = response.indexOf(RESPONSE_DELIMITER);
+            // A report is only delivered when Herdr says so: a write into a socket
+            // that closed on the far side would otherwise look like success.
+            if (end >= 0)
+                finish(isSuccess(response.slice(0, end), request.id));
+        });
+    });
+}
+function isSuccess(response, requestId) {
+    try {
+        const parsed = JSON.parse(response);
+        return isRecord(parsed) && parsed.id === requestId && 'result' in parsed && !('error' in parsed);
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=client.js.map

package/lib/herdr/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/herdr/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,GAGnB,MAAM,gBAAgB,CAAA;AAsDvB;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAwB,OAAO,CAAC,GAAG,EAAE,UAA8B,EAAE;IACrG,MAAM,MAAM,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAA;IACrC,MAAM,UAAU,GAAG,GAAG,CAAC,qBAAqB,CAAC,CAAA;IAC7C,2EAA2E;IAC3E,wDAAwD;IACxD,MAAM,OAAO,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,cAAc,IAAI,MAAM,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,CAAA;IACzG,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAC,CAAA;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAA;IACtE,IAAI,aAAa,GAAG,CAAC,CAAA;IACrB,IAAI,MAAM,GAAmB,EAAE,CAAA;IAC/B,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,MAAM,GAAG,KAAK,CAAA;IAClB,IAAI,OAAO,GAAsB,EAAE,CAAA;IAEnC,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,MAAM,OAAO,GAAG,OAAO,CAAA;QACvB,OAAO,GAAG,EAAE,CAAA;QACZ,KAAK,MAAM,OAAO,IAAI,OAAO;YAAE,OAAO,EAAE,CAAA;IAC1C,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,KAAK,EAAE,OAAoB,EAAoB,EAAE,CAC/D,UAAU,KAAK,SAAS;QACtB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAA;IAE3E,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;QACrC,IAAI,OAAO;YAAE,OAAM;QACnB,OAAO,GAAG,IAAI,CAAA;QACd,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,CAAA;gBAC3B,IAAI,IAAI,KAAK,SAAS;oBAAE,MAAK;gBAC7B,IAAI,CAAC,MAAM,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAA;YAC1C,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,OAAO,GAAG,KAAK,CAAA;YACf,IAAI,EAAE,CAAA;QACR,CAAC;IACH,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,MAA+B,EAAE,UAAmB,EAAoB,EAAE,CACzG,IAAI,OAAO,CAAU,OAAO,CAAC,EAAE;QAC7B,IAAI,MAAM,IAAI,CAAC,OAAO,IAAI,MAAM,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3E,OAAO,CAAC,IAAI,CAAC,CAAA;YACb,OAAM;QACR,CAAC;QACD,MAAM,OAAO,GAAgB;YAC3B,EAAE,EAAE,GAAG,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,EAAE,aAAa,CAAC,EAAE;YACvE,MAAM;YACN,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE;SACjF,CAAA;QACD,IAAI,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YACzD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;YAC3D,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;YAClD,uEAAuE;YACvE,mDAAmD;YACnD,KAAK,MAAM,KAAK,IAAI,UAAU;gBAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACpD,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;QACrD,KAAK,IAAI,EAAE,CAAA;IACb,CAAC,CAAC,CAAA;IAEJ,OAAO;QACL,OAAO;QACP,WAAW,CAAC,MAAM;YAChB,OAAO,OAAO,CAAC,mBAAmB,EAAE;gBAClC,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;aAClF,EAAE,IAAI,CAAC,CAAA;QACV,CAAC;QACD,aAAa,CAAC,MAAM;YAClB,OAAO,OAAO,CAAC,2BAA2B,EAAE;gBAC1C,gBAAgB,EAAE,MAAM,CAAC,SAAS;gBAClC,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,oBAAoB,EAAE,MAAM,CAAC,MAAM;aACpC,EAAE,KAAK,CAAC,CAAA;QACX,CAAC;QACD,cAAc,CAAC,MAAM;YACnB,OAAO,OAAO,CAAC,sBAAsB,EAAE;gBACrC,iBAAiB,EAAE,YAAY;gBAC/B,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;aAC/B,EAAE,KAAK,CAAC,CAAA;QACX,CAAC;QACD,IAAI;YACF,0EAA0E;YAC1E,sEAAsE;YACtE,yEAAyE;YACzE,uEAAuE;YACvE,0CAA0C;YAC1C,MAAM,GAAG,IAAI,CAAA;YACb,MAAM,SAAS,GAAG,MAAM,CAAA;YACxB,MAAM,GAAG,EAAE,CAAA;YACX,KAAK,MAAM,KAAK,IAAI,SAAS;gBAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACpD,CAAC;QACD,KAAK,CAAC,MAAM;YACV,yEAAyE;YACzE,0EAA0E;YAC1E,uEAAuE;YACvE,qEAAqE;YACrE,2CAA2C;YAC3C,IAAI,CAAC,OAAO;gBAAE,OAAM;YACpB,MAAM,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;gBAChC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACvB,CAAC,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoD;IACjF,MAAM,QAAQ,GAAkC,EAAE,CAAA;IAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,wBAAwB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAA;IAC/F,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;AACrE,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,aAAa,CAC1B,IAAY,EACZ,OAAoB,EACpB,QAAgB,EAChB,SAAiB,EACjB,OAAsB;IAEtB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;IACvC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QACvD,0EAA0E;QAC1E,yEAAyE;QACzE,IAAI,OAAO,EAAE;YAAE,OAAO,KAAK,CAAA;QAC3B,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACvC,IAAI,SAAS,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;QAChC,IAAI,MAAM,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC;YAAE,OAAO,IAAI,CAAA;IAC9D,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,OAAoB,EAAE,SAAiB;IACxE,OAAO,IAAI,OAAO,CAAU,OAAO,CAAC,EAAE;QACpC,MAAM,MAAM,GAAG,gBAAgB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAA;QACrD,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,IAAI,QAAQ,GAAG,CAAC,CAAA;QAChB,IAAI,OAAO,GAAG,KAAK,CAAA;QAEnB,MAAM,MAAM,GAAG,CAAC,SAAkB,EAAQ,EAAE;YAC1C,IAAI,OAAO;gBAAE,OAAM;YACnB,OAAO,GAAG,IAAI,CAAA;YACd,YAAY,CAAC,MAAM,CAAC,CAAA;YACpB,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,OAAO,CAAC,SAAS,CAAC,CAAA;QACpB,CAAC,CAAA;QAED,4EAA4E;QAC5E,mCAAmC;QACnC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAA;QACzD,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QACjD,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QACzC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;QACvC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,kBAAkB,EAAE,CAAC,CAAC,CAAA;QAC7F,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAA;YAC5B,IAAI,QAAQ,GAAG,kBAAkB,EAAE,CAAC;gBAClC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACb,OAAM;YACR,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAClB,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;YACjE,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAA;YAChD,uEAAuE;YACvE,iEAAiE;YACjE,IAAI,GAAG,IAAI,CAAC;gBAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAA;QACrE,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,QAAgB,EAAE,SAAiB;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAY,CAAA;QAC9C,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,KAAK,SAAS,IAAI,QAAQ,IAAI,MAAM,IAAI,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,CAAA;IAClG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC"}

package/lib/herdr/constants.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The Herdr side of this surface.
+ *
+ * Herdr is a terminal multiplexer for coding agents: when it starts a pane it
+ * exports its own coordinates plus a socket, and anything running in that pane
+ * may claim the pane's agent row. These are the names both ends of the claim
+ * have to agree on, so they are fixed here rather than at the call sites.
+ */
+/** The value `HERDR_ENV` carries inside a pane Herdr itself started. */
+export declare const HERDR_ENV_FLAG = "1";
+export declare const HERDR_ENV_VAR = "HERDR_ENV";
+export declare const HERDR_PANE_ID_VAR = "HERDR_PANE_ID";
+export declare const HERDR_SOCKET_PATH_VAR = "HERDR_SOCKET_PATH";
+export declare const HERDR_BIN_PATH_VAR = "HERDR_BIN_PATH";
+/** The agent label Herdr shows, and the label its pickers and waits match on. */
+export declare const HERDR_AGENT = "dsh";
+/**
+ * This reporter's identity.
+ *
+ * Herdr scopes lifecycle state, report sequencing, and releases by
+ * (source, agent), so a second tool reporting the same pane under its own
+ * source cannot be mistaken for this one — and clearing this source's
+ * authority leaves the other's alone.
+ */
+export declare const HERDR_SOURCE = "custom:dsh-tui";
+/** The three states a pane report may carry. */
+export declare const HERDR_STATES: {
+    readonly idle: "idle";
+    readonly working: "working";
+    readonly blocked: "blocked";
+};
+export type HerdrState = (typeof HERDR_STATES)[keyof typeof HERDR_STATES];
+/**
+ * Why a session opened, in the words Herdr accepts.
+ *
+ * A reason outside this set is dropped server-side, so the surface reports the
+ * nearest one it recognizes instead of inventing a label.
+ */
+export declare const SESSION_START_REASONS: {
+    readonly startup: "startup";
+    readonly resume: "resume";
+    readonly fork: "fork";
+    readonly select: "select";
+};
+export type SessionStartReason = (typeof SESSION_START_REASONS)[keyof typeof SESSION_START_REASONS];
+/**
+ * Pane metadata keys.
+ *
+ * Herdr persists a session reference only for its own built-in integrations, so
+ * the identity is published as tokens as well: those are readable back off the
+ * pane by any script or plugin, which is what makes an exact resume possible
+ * from outside this process.
+ */
+export declare const METADATA_TOKENS: {
+    readonly session: "dsh_session";
+    readonly cwd: "dsh_cwd";
+};
+/** A report is best-effort, so its budget is short and it retries once. */
+export declare const DEFAULT_ATTEMPTS = 2;
+export declare const DEFAULT_TIMEOUT_MS = 500;
+/** A release on the way out cannot outlive the process that owes it. */
+export declare const EXIT_RELEASE_TIMEOUT_MS = 250;
+/** The first wait before a report Herdr did not acknowledge is sent again. */
+export declare const RETRY_BASE_MS = 250;
+/** The longest that wait can grow to, so a down socket is still noticed. */
+export declare const RETRY_MAX_MS = 8000;
+/** Beyond this a response is a surprise, not an answer. */
+export declare const MAX_RESPONSE_BYTES: number;
+export declare const RESPONSE_DELIMITER = "\n";
+/**
+ * The longest metadata value Herdr can hold whole.
+ *
+ * A longer value is shortened rather than refused, so a path past the limit
+ * would come back reading as a different directory: a value this long is the
+ * most the pane can say about itself, and anything longer has to be cleared.
+ */
+export declare const MAX_METADATA_VALUE_CHARS = 80;
+/**
+ * How much of a wait's title is reported.
+ *
+ * The text names a tool the model chose, so it crosses a trust boundary into
+ * another process's user interface: it is bounded here rather than handed over
+ * whole.
+ */
+export declare const MAX_BLOCKED_MESSAGE_CHARS = 120;
+/**
+ * Reports are sequenced in microseconds.
+ *
+ * Herdr keeps the newest sequence per source and ignores an older one, so a
+ * delivery that arrives late cannot undo a state the surface already left.
+ */
+export declare const SEQ_TIME_SCALE = 1000;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/herdr/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wEAAwE;AACxE,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC,eAAO,MAAM,aAAa,cAAc,CAAA;AACxC,eAAO,MAAM,iBAAiB,kBAAkB,CAAA;AAChD,eAAO,MAAM,qBAAqB,sBAAsB,CAAA;AACxD,eAAO,MAAM,kBAAkB,mBAAmB,CAAA;AAElD,iFAAiF;AACjF,eAAO,MAAM,WAAW,QAAQ,CAAA;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,mBAAmB,CAAA;AAE5C,gDAAgD;AAChD,eAAO,MAAM,YAAY;;;;CAAoE,CAAA;AAC7F,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAA;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;CAAoF,CAAA;AACtH,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,OAAO,qBAAqB,CAAC,CAAA;AAEnG;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;CAAsD,CAAA;AAElF,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,IAAI,CAAA;AACjC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C,8EAA8E;AAC9E,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC,4EAA4E;AAC5E,eAAO,MAAM,YAAY,OAAQ,CAAA;AAEjC,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,QAAY,CAAA;AAC3C,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,OAAO,CAAA"}

package/lib/herdr/constants.js

@@ -0,0 +1,79 @@
+/**
+ * The Herdr side of this surface.
+ *
+ * Herdr is a terminal multiplexer for coding agents: when it starts a pane it
+ * exports its own coordinates plus a socket, and anything running in that pane
+ * may claim the pane's agent row. These are the names both ends of the claim
+ * have to agree on, so they are fixed here rather than at the call sites.
+ */
+/** The value `HERDR_ENV` carries inside a pane Herdr itself started. */
+export const HERDR_ENV_FLAG = '1';
+export const HERDR_ENV_VAR = 'HERDR_ENV';
+export const HERDR_PANE_ID_VAR = 'HERDR_PANE_ID';
+export const HERDR_SOCKET_PATH_VAR = 'HERDR_SOCKET_PATH';
+export const HERDR_BIN_PATH_VAR = 'HERDR_BIN_PATH';
+/** The agent label Herdr shows, and the label its pickers and waits match on. */
+export const HERDR_AGENT = 'dsh';
+/**
+ * This reporter's identity.
+ *
+ * Herdr scopes lifecycle state, report sequencing, and releases by
+ * (source, agent), so a second tool reporting the same pane under its own
+ * source cannot be mistaken for this one — and clearing this source's
+ * authority leaves the other's alone.
+ */
+export const HERDR_SOURCE = 'custom:dsh-tui';
+/** The three states a pane report may carry. */
+export const HERDR_STATES = { idle: 'idle', working: 'working', blocked: 'blocked' };
+/**
+ * Why a session opened, in the words Herdr accepts.
+ *
+ * A reason outside this set is dropped server-side, so the surface reports the
+ * nearest one it recognizes instead of inventing a label.
+ */
+export const SESSION_START_REASONS = { startup: 'startup', resume: 'resume', fork: 'fork', select: 'select' };
+/**
+ * Pane metadata keys.
+ *
+ * Herdr persists a session reference only for its own built-in integrations, so
+ * the identity is published as tokens as well: those are readable back off the
+ * pane by any script or plugin, which is what makes an exact resume possible
+ * from outside this process.
+ */
+export const METADATA_TOKENS = { session: 'dsh_session', cwd: 'dsh_cwd' };
+/** A report is best-effort, so its budget is short and it retries once. */
+export const DEFAULT_ATTEMPTS = 2;
+export const DEFAULT_TIMEOUT_MS = 500;
+/** A release on the way out cannot outlive the process that owes it. */
+export const EXIT_RELEASE_TIMEOUT_MS = 250;
+/** The first wait before a report Herdr did not acknowledge is sent again. */
+export const RETRY_BASE_MS = 250;
+/** The longest that wait can grow to, so a down socket is still noticed. */
+export const RETRY_MAX_MS = 8_000;
+/** Beyond this a response is a surprise, not an answer. */
+export const MAX_RESPONSE_BYTES = 64 * 1024;
+export const RESPONSE_DELIMITER = '\n';
+/**
+ * The longest metadata value Herdr can hold whole.
+ *
+ * A longer value is shortened rather than refused, so a path past the limit
+ * would come back reading as a different directory: a value this long is the
+ * most the pane can say about itself, and anything longer has to be cleared.
+ */
+export const MAX_METADATA_VALUE_CHARS = 80;
+/**
+ * How much of a wait's title is reported.
+ *
+ * The text names a tool the model chose, so it crosses a trust boundary into
+ * another process's user interface: it is bounded here rather than handed over
+ * whole.
+ */
+export const MAX_BLOCKED_MESSAGE_CHARS = 120;
+/**
+ * Reports are sequenced in microseconds.
+ *
+ * Herdr keeps the newest sequence per source and ignores an older one, so a
+ * delivery that arrives late cannot undo a state the surface already left.
+ */
+export const SEQ_TIME_SCALE = 1000;
+//# sourceMappingURL=constants.js.map

package/lib/herdr/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/herdr/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;AAEjC,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAA;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAA;AAChD,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAA;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAA;AAElD,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,CAAA;AAEhC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAA;AAE5C,gDAAgD;AAChD,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAW,CAAA;AAG7F;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAW,CAAA;AAGtH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,EAAW,CAAA;AAElF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA;AACjC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAErC,wEAAwE;AACxE,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAE1C,8EAA8E;AAC9E,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAEhC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAA;AAEjC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAA;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA"}

package/lib/herdr/reporter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 { type HerdrClient, type HerdrEnvironment } from './client.ts';
+import { type SessionStartReason } from './constants.ts';
+export interface HerdrSessionInput {
+    readonly id: string;
+    readonly cwd: string;
+    readonly reason: SessionStartReason;
+}
+export interface HerdrReporterOptions {
+    readonly client?: HerdrClient;
+    readonly env?: HerdrEnvironment;
+    readonly now?: () => number;
+    readonly releaseSync?: () => void;
+    /** The first retry wait; a test cannot wait a socket out. */
+    readonly retryBaseMs?: number | undefined;
+}
+export interface HerdrReporter {
+    readonly enabled: boolean;
+    /** A turn started. */
+    working(): void;
+    /** A turn ended. */
+    idle(): void;
+    /** A decision is waiting on the reader; waits stack, so they are counted. */
+    block(message: string): void;
+    /** One waiting decision was settled, answered, or abandoned. */
+    unblock(): void;
+    /** The pane opened, resumed, forked, or switched to a session. */
+    session(input: HerdrSessionInput): void;
+    /** Send the current facts, or resend them with `force`. */
+    publish(force?: boolean): void;
+    /** Hand the pane's agent row back before the process leaves. */
+    releaseSync(): void;
+    /** Hand the row back with the reports already on the wire settled. */
+    release(): Promise<void>;
+    /** Release on process exit; returns the unregister function. */
+    registerExitRelease(): () => void;
+}
+export declare function createHerdrReporter(options?: HerdrReporterOptions): HerdrReporter;
+/**
+ * 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 declare function releaseAgentSync(env: HerdrEnvironment, seq: number): void;
+//# sourceMappingURL=reporter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/herdr/reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACxF,OAAO,EAYL,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAA;AAGvB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sBAAsB;IACtB,OAAO,IAAI,IAAI,CAAA;IACf,oBAAoB;IACpB,IAAI,IAAI,IAAI,CAAA;IACZ,6EAA6E;IAC7E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gEAAgE;IAChE,OAAO,IAAI,IAAI,CAAA;IACf,kEAAkE;IAClE,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACvC,2DAA2D;IAC3D,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAC9B,gEAAgE;IAChE,WAAW,IAAI,IAAI,CAAA;IACnB,sEAAsE;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,gEAAgE;IAChE,mBAAmB,IAAI,MAAM,IAAI,CAAA;CAClC;AAED,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAgLrF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CASzE"}