mcp-ssh-terminal 0.2.0

package/dist/manager.js

@@ -0,0 +1,119 @@
+import { Session } from "./session.js";
+import { expandHome } from "./sshConfig.js";
+/** Reject values that would be parsed as ssh options (argument injection). */
+function assertNotOptionLike(value, name) {
+    if (value !== undefined && value.startsWith("-")) {
+        throw new Error(`\`${name}\` must not start with "-" (would be parsed as an ssh option): ${value}`);
+    }
+}
+/**
+ * Build the argv for the OpenSSH client from a connect spec. Everything the
+ * ssh client natively understands — ~/.ssh/config, known_hosts, ssh-agent,
+ * ProxyJump — is left to ssh; we only translate the explicit overrides.
+ */
+export function buildSshCommand(spec) {
+    assertNotOptionLike(spec.host, "host");
+    assertNotOptionLike(spec.user, "user");
+    assertNotOptionLike(spec.jump, "jump");
+    if (spec.user && spec.host.includes("@")) {
+        throw new Error(`\`user\` was given but \`host\` already contains "@": ${spec.host}`);
+    }
+    const args = [];
+    // Disable the ssh escape character. We drive stdin programmatically, so the
+    // interactive "~." disconnect sequence would otherwise be a footgun and
+    // would stop arbitrary control bytes from passing through verbatim.
+    args.push("-e", "none");
+    if (spec.forceTty !== false) {
+        args.push("-tt"); // force remote PTY even though stdin is already a tty
+    }
+    if (spec.port !== undefined)
+        args.push("-p", String(spec.port));
+    if (spec.identityFile)
+        args.push("-i", expandHome(spec.identityFile));
+    if (spec.jump)
+        args.push("-J", spec.jump);
+    if (spec.extraArgs)
+        args.push(...spec.extraArgs);
+    // Sessions are long-lived by design; keepalives stop NAT/conntrack from
+    // silently dropping idle connections, and ConnectTimeout bounds a dead
+    // host. OpenSSH uses the first occurrence of an -o option, so these come
+    // after extraArgs and act as overridable defaults.
+    // ConnectTimeout also caps the destination's banner exchange, and on a
+    // ProxyJump chain that clock keeps running while interactive prompts at
+    // the jump hop await answers — 30s gives an agent room to answer them.
+    args.push("-o", "ServerAliveInterval=30", "-o", "ServerAliveCountMax=3", "-o", "ConnectTimeout=30");
+    const destination = spec.user ? `${spec.user}@${spec.host}` : spec.host;
+    // "--" ends option parsing so a hostile destination can't inject options
+    // (e.g. host: "-oProxyCommand=...").
+    args.push("--", destination);
+    if (spec.remoteCommand)
+        args.push(spec.remoteCommand);
+    const label = spec.remoteCommand ? `${destination} :: ${spec.remoteCommand}` : destination;
+    return { file: "ssh", args, label };
+}
+/** Cap on concurrent sessions; oldest exited ones are evicted to make room. */
+const MAX_SESSIONS = 32;
+/** In-memory registry of live sessions. */
+export class SessionManager {
+    sessions = new Map();
+    counter = 0;
+    create(cmd, cols, rows) {
+        if (this.sessions.size >= MAX_SESSIONS) {
+            const oldestExited = [...this.sessions.values()]
+                .filter((s) => s.exited)
+                .sort((a, b) => a.startedAt - b.startedAt)[0];
+            if (!oldestExited) {
+                throw new Error(`Session limit (${MAX_SESSIONS}) reached and all are live; ssh_disconnect one first.`);
+            }
+            this.remove(oldestExited.id);
+        }
+        const id = `s${++this.counter}`;
+        const session = new Session(id, {
+            file: cmd.file,
+            args: cmd.args,
+            cols,
+            rows,
+            label: cmd.label,
+        });
+        this.sessions.set(id, session);
+        return session;
+    }
+    get(id) {
+        return this.sessions.get(id);
+    }
+    require(id) {
+        const s = this.sessions.get(id);
+        if (!s) {
+            const known = [...this.sessions.keys()].join(", ") || "none";
+            throw new Error(`Unknown session "${id}". Active sessions: ${known}.`);
+        }
+        return s;
+    }
+    list() {
+        return [...this.sessions.values()];
+    }
+    remove(id) {
+        const s = this.sessions.get(id);
+        if (!s)
+            return false;
+        s.close();
+        // Escalate like closeAll: a child that ignores SIGHUP (e.g. a wedged
+        // ProxyCommand) would otherwise leak past the registry.
+        setTimeout(() => s.kill(), 250).unref?.();
+        this.sessions.delete(id);
+        return true;
+    }
+    /**
+     * SIGHUP everything, escalating to SIGKILL after `escalateMs` for children
+     * that ignore it. Callers that exit afterwards must wait past `escalateMs`.
+     */
+    closeAll(escalateMs = 250) {
+        for (const s of this.sessions.values())
+            s.close();
+        setTimeout(() => {
+            for (const s of this.sessions.values())
+                s.kill();
+        }, escalateMs).unref?.();
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SessionManager } from "./manager.js";
+export declare function createServer(manager: SessionManager): McpServer;

package/dist/server.js

@@ -0,0 +1,348 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { buildSshCommand } from "./manager.js";
+import { resolveKeys } from "./keys.js";
+import { listConfigHosts } from "./sshConfig.js";
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 40;
+// Settle/timeout defaults (ms). Connecting allows more time for banners,
+// host-key prompts, and multi-hop ProxyJump handshakes.
+const CONNECT_SETTLE = 700;
+const CONNECT_TIMEOUT = 20000;
+const SEND_SETTLE = 500;
+const SEND_TIMEOUT = 12000;
+const DEFAULT_MAX_LINES = 200;
+function text(s) {
+    return { content: [{ type: "text", text: s }] };
+}
+function errorText(s) {
+    return { content: [{ type: "text", text: s }], isError: true };
+}
+/** Compose the standard status footer shown after a screen render. */
+function statusLine(session, wait, render) {
+    const parts = [];
+    parts.push(`session=${session.id}`);
+    if (session.exited) {
+        const code = session.exitCode;
+        const sig = session.exitSignal;
+        parts.push(`state=exited${code !== null ? ` code=${code}` : ""}${sig ? ` signal=${sig}` : ""}`);
+    }
+    else {
+        parts.push("state=live");
+    }
+    parts.push(`wait=${wait}`);
+    parts.push(`cursor=${render.cursorRow + 1},${render.cursorCol + 1}`);
+    parts.push(`screen=${render.rows}x${render.cols}`);
+    parts.push(`shown=${render.shownLines}/${render.totalLines}`);
+    return `[${parts.join(" | ")}]`;
+}
+function screenBlock(render, session, wait) {
+    const body = render.text.length > 0 ? render.text : "(no output yet)";
+    const hint = wait === "timeout" && !session.exited
+        ? "\n(output still arriving — call ssh_read again to see more, or wait longer)"
+        : wait === "quiet"
+            ? "\n(no new output arrived within waitMs — the program may be running quietly or awaiting input)"
+            : "";
+    return `${body}\n${statusLine(session, wait, render)}${hint}`;
+}
+// Zod bounds: generous enough for any real terminal, tight enough that a
+// bogus value can't allocate a gigantic emulator buffer or hang a call.
+const colsSchema = z.number().int().min(10).max(1000);
+const rowsSchema = z.number().int().min(4).max(500);
+const settleSchema = z.number().int().nonnegative().max(60_000);
+const timeoutSchema = z.number().int().positive().max(600_000);
+const maxLinesSchema = z.number().int().positive().max(5000);
+export function createServer(manager) {
+    const server = new McpServer({
+        name: "mcp-ssh-terminal",
+        version: "0.2.0",
+    }, {
+        instructions: [
+            "Persistent, interactive SSH sessions over the real OpenSSH client.",
+            "",
+            "How it works: each session is a live `ssh` process attached to a PTY, with",
+            "output rendered through a terminal emulator so you read the screen a human",
+            "would see. Sessions stay open across tool calls — connect once, then send",
+            "input and read output repeatedly.",
+            "",
+            "Config, keys, known_hosts, and ProxyJump are all handled by ssh itself, so",
+            "~/.ssh/config Host aliases, IdentityFile, and multi-hop jumps 'just work'.",
+            "",
+            "Typical flow:",
+            "  1. ssh_connect { host } -> returns a session id and the initial screen.",
+            "  2. If a password / passphrase / host-key prompt appears on the screen,",
+            "     answer it with ssh_send (e.g. type the password, or send 'yes').",
+            "  3. ssh_send { session, text: 'command', appendEnter: true } to run a command.",
+            "  4. ssh_read to poll long-running output; ssh_interrupt for Ctrl-C.",
+            "",
+            "Control characters & special keys: use the `keys` array on ssh_send, e.g.",
+            "['C-c'] for Ctrl-C, ['C-x'] for Ctrl-X, ['Up'], ['Tab'], ['Escape'], ['F5'].",
+            "",
+            "Works with non-Unix shells (e.g. Mikrotik RouterOS): it is a faithful",
+            "terminal, so interactive CLIs, tab-completion, and paging behave normally.",
+            "",
+            "Mikrotik RouterOS tips:",
+            "  - '?' and Tab are live hotkeys in the RouterOS console (inline help /",
+            "    completion) — they act immediately, so avoid them inside `text` unless",
+            "    intended. Prefer single-line commands; multi-line pastes get mangled",
+            "    by the console's auto-indent.",
+            "  - Long `print` output pauses on a pager line ('-- [Q quit|D dump|down]'):",
+            "    answer via ssh_send ('D' dumps all, 'Q' quits, Space pages), or run",
+            "    `print without-paging` in the first place.",
+            "  - Ctrl-X (keys: ['C-x']) toggles RouterOS Safe Mode: enter it before",
+            "    config changes so they auto-revert if the session drops; press it",
+            "    again to commit. Don't send it casually.",
+        ].join("\n"),
+    });
+    server.registerTool("ssh_connect", {
+        title: "Open SSH session",
+        description: "Open a persistent interactive SSH session to a host and return the initial screen. " +
+            "`host` may be an ~/.ssh/config Host alias, a hostname, or user@hostname. Config, " +
+            "key auth, known_hosts, and ProxyJump are delegated to the ssh client. If a password, " +
+            "passphrase, 2FA, or host-key prompt appears in the returned screen, respond with ssh_send.",
+        inputSchema: {
+            host: z.string().min(1).describe("Destination: ssh_config Host alias, hostname, or user@hostname"),
+            user: z.string().optional().describe("Username (prepended as user@host if host has no '@')"),
+            port: z.number().int().min(1).max(65535).optional().describe("Port (ssh -p); usually unnecessary if set in config"),
+            identityFile: z.string().optional().describe("Private key path (ssh -i); ~ is expanded"),
+            jump: z
+                .string()
+                .optional()
+                .describe("ProxyJump chain (ssh -J), e.g. 'bastion' or 'userA@a,userB@b' for A->B->C"),
+            remoteCommand: z
+                .string()
+                .optional()
+                .describe("Run this command instead of an interactive login shell (still on a PTY)"),
+            extraArgs: z.array(z.string()).optional().describe("Extra raw ssh arguments appended verbatim"),
+            forceTty: z.boolean().optional().describe("Force remote PTY allocation (ssh -tt). Default true"),
+            cols: colsSchema.optional().describe(`Terminal width (default ${DEFAULT_COLS})`),
+            rows: rowsSchema.optional().describe(`Terminal height (default ${DEFAULT_ROWS})`),
+            settleMs: settleSchema.optional().describe(`Idle-quiet threshold before reading (default ${CONNECT_SETTLE})`),
+            timeoutMs: timeoutSchema.optional().describe(`Max wait for initial screen (default ${CONNECT_TIMEOUT})`),
+            maxLines: maxLinesSchema.optional().describe(`Max screen lines to return (default ${DEFAULT_MAX_LINES})`),
+        },
+    }, async (a) => {
+        try {
+            const cols = a.cols ?? DEFAULT_COLS;
+            const rows = a.rows ?? DEFAULT_ROWS;
+            const cmd = buildSshCommand({
+                host: a.host,
+                user: a.user,
+                port: a.port,
+                identityFile: a.identityFile,
+                jump: a.jump,
+                remoteCommand: a.remoteCommand,
+                extraArgs: a.extraArgs,
+                forceTty: a.forceTty,
+            });
+            const session = manager.create(cmd, cols, rows);
+            // requireData: the settle clock starts at the first byte of output, so
+            // a slow DNS/TCP/kex phase isn't misread as an already-settled screen.
+            const wait = await session.waitForIdle(a.settleMs ?? CONNECT_SETTLE, a.timeoutMs ?? CONNECT_TIMEOUT, true);
+            const render = await session.render(a.maxLines ?? DEFAULT_MAX_LINES);
+            const header = `Connecting: ssh ${cmd.args.join(" ")}\n`;
+            const noOutputHint = session.exited && render.text.length === 0
+                ? "\n(ssh exited immediately with no output — is the OpenSSH client installed and on PATH?)"
+                : "";
+            return text(header + screenBlock(render, session, wait.reason) + noOutputHint);
+        }
+        catch (err) {
+            return errorText(`ssh_connect failed: ${err.message}`);
+        }
+    });
+    server.registerTool("ssh_send", {
+        title: "Send input to SSH session",
+        description: "Send text and/or special keys to a session, wait for the output to settle, and return the " +
+            "updated screen. Use `text` for literal typing, `keys` for control chars and special keys " +
+            "(e.g. ['C-c'], ['Up'], ['Tab'], ['Escape']), and `appendEnter` to press Enter after the text. " +
+            "Order sent: text, then keys, then (if set) Enter.",
+        inputSchema: {
+            session: z.string().min(1).describe("Session id from ssh_connect"),
+            text: z.string().optional().describe("Literal text to type (control chars are not interpreted here)"),
+            keys: z
+                .array(z.string())
+                .optional()
+                .describe("Ordered key tokens: 'Enter','Tab','Escape','Up','Down','F5','C-c'(Ctrl-C),'C-x','M-b'(Alt-b),'hex:1b', " +
+                "or a single literal character. Unknown multi-character tokens are rejected — literal text goes in `text`."),
+            appendEnter: z.boolean().optional().describe("Press Enter after text/keys (convenience for running a command)"),
+            settleMs: settleSchema.optional().describe(`Idle-quiet threshold (default ${SEND_SETTLE})`),
+            timeoutMs: timeoutSchema.optional().describe(`Max wait for output (default ${SEND_TIMEOUT})`),
+            maxLines: maxLinesSchema.optional().describe(`Max screen lines to return (default ${DEFAULT_MAX_LINES})`),
+        },
+    }, async (a) => {
+        try {
+            const session = manager.require(a.session);
+            if (session.exited)
+                return errorText(`Session ${session.id} has exited and cannot receive input.`);
+            let payload = "";
+            if (a.text !== undefined)
+                payload += a.text;
+            if (a.keys && a.keys.length > 0) {
+                payload += resolveKeys(a.keys, { applicationCursorKeys: session.applicationCursorKeys });
+            }
+            if (a.appendEnter)
+                payload += "\r";
+            if (payload.length === 0) {
+                return errorText("Nothing to send: provide `text`, `keys`, and/or `appendEnter`.");
+            }
+            session.write(payload);
+            const wait = await session.waitForIdle(a.settleMs ?? SEND_SETTLE, a.timeoutMs ?? SEND_TIMEOUT);
+            const render = await session.render(a.maxLines ?? DEFAULT_MAX_LINES);
+            return text(screenBlock(render, session, wait.reason));
+        }
+        catch (err) {
+            return errorText(`ssh_send failed: ${err.message}`);
+        }
+    });
+    server.registerTool("ssh_read", {
+        title: "Read SSH screen",
+        description: "Read the current session screen without sending input. Use this to poll output from a " +
+            "long-running command. Set `waitMs` to block until new output actually arrives (or the " +
+            "session exits, or `waitMs` elapses) before reading.",
+        inputSchema: {
+            session: z.string().min(1).describe("Session id"),
+            mode: z.enum(["screen", "raw"]).optional().describe("'screen' = rendered text (default); 'raw' = raw byte stream with escape codes"),
+            waitMs: z
+                .number()
+                .int()
+                .nonnegative()
+                .max(600_000)
+                .optional()
+                .describe("Block up to this long for NEW output before reading; footer shows wait=quiet if nothing arrived (default 0 = read immediately)"),
+            maxLines: maxLinesSchema.optional().describe(`Max screen lines (screen mode; default ${DEFAULT_MAX_LINES})`),
+            maxBytes: z.number().int().positive().max(524_288).optional().describe("Max bytes (raw mode; default 8192)"),
+        },
+    }, async (a) => {
+        try {
+            const session = manager.require(a.session);
+            let wait = "idle";
+            if (a.waitMs && a.waitMs > 0) {
+                // Block for genuinely new output, then let it settle briefly so the
+                // render isn't a half-written line. Reasons surfaced to the caller:
+                //   idle    — new output arrived and settled
+                //   timeout — new output arrived and is still streaming
+                //   quiet   — nothing new arrived within waitMs
+                //   exited  — the session ended while waiting
+                const first = await session.waitForData(a.waitMs);
+                if (first.reason === "data") {
+                    wait = (await session.waitForIdle(Math.min(300, a.waitMs), 1000)).reason;
+                }
+                else if (first.reason === "timeout") {
+                    wait = "quiet";
+                }
+                else {
+                    wait = first.reason;
+                }
+            }
+            if (a.mode === "raw") {
+                const raw = session.rawTail(a.maxBytes ?? 8192);
+                return text(`${JSON.stringify(raw)}\n[session=${session.id} | state=${session.exited ? "exited" : "live"} | rawBytes=${raw.length}]`);
+            }
+            const render = await session.render(a.maxLines ?? DEFAULT_MAX_LINES);
+            return text(screenBlock(render, session, wait));
+        }
+        catch (err) {
+            return errorText(`ssh_read failed: ${err.message}`);
+        }
+    });
+    server.registerTool("ssh_interrupt", {
+        title: "Send Ctrl-C",
+        description: "Send Ctrl-C (SIGINT) to the foreground program in a session, then return the updated screen.",
+        inputSchema: {
+            session: z.string().min(1).describe("Session id"),
+            settleMs: settleSchema.optional(),
+            timeoutMs: timeoutSchema.optional(),
+            maxLines: maxLinesSchema.optional(),
+        },
+    }, async (a) => {
+        try {
+            const session = manager.require(a.session);
+            if (session.exited)
+                return errorText(`Session ${session.id} has already exited.`);
+            session.write("\x03");
+            const wait = await session.waitForIdle(a.settleMs ?? SEND_SETTLE, a.timeoutMs ?? SEND_TIMEOUT);
+            const render = await session.render(a.maxLines ?? DEFAULT_MAX_LINES);
+            return text(screenBlock(render, session, wait.reason));
+        }
+        catch (err) {
+            return errorText(`ssh_interrupt failed: ${err.message}`);
+        }
+    });
+    server.registerTool("ssh_resize", {
+        title: "Resize terminal",
+        description: "Change the terminal dimensions of a session (affects line wrapping and full-screen apps).",
+        inputSchema: {
+            session: z.string().min(1).describe("Session id"),
+            cols: colsSchema.describe("New column count"),
+            rows: rowsSchema.describe("New row count"),
+        },
+    }, async (a) => {
+        try {
+            const session = manager.require(a.session);
+            session.resize(a.cols, a.rows);
+            return text(`Resized ${session.id} to ${a.cols}x${a.rows}.`);
+        }
+        catch (err) {
+            return errorText(`ssh_resize failed: ${err.message}`);
+        }
+    });
+    server.registerTool("ssh_list", {
+        title: "List SSH sessions",
+        description: "List all active SSH sessions with their destination, state, and age.",
+        inputSchema: {},
+    }, async () => {
+        const sessions = manager.list();
+        if (sessions.length === 0)
+            return text("No active sessions.");
+        const lines = sessions.map((s) => {
+            const ageSec = Math.round((Date.now() - s.startedAt) / 1000);
+            const state = s.exited ? `exited(code=${s.exitCode ?? "?"})` : "live";
+            const { cols, rows } = s.dimensions;
+            return `${s.id}\t${state}\t${cols}x${rows}\tpid=${s.pid}\tage=${ageSec}s\t${s.label}`;
+        });
+        return text(`Active sessions (${sessions.length}):\n${lines.join("\n")}`);
+    });
+    server.registerTool("ssh_disconnect", {
+        title: "Close SSH session",
+        description: "Close a session and terminate its ssh process.",
+        inputSchema: {
+            session: z.string().min(1).describe("Session id to close"),
+        },
+    }, async (a) => {
+        const ok = manager.remove(a.session);
+        return ok ? text(`Closed session ${a.session}.`) : errorText(`Unknown session "${a.session}".`);
+    });
+    server.registerTool("ssh_config_hosts", {
+        title: "List ssh_config hosts",
+        description: "List Host aliases from ~/.ssh/config (best-effort, follows Include) for discovery. " +
+            "Connection semantics are always resolved by the ssh client, not this listing.",
+        inputSchema: {
+            configPath: z.string().optional().describe("Alternate config path (default ~/.ssh/config)"),
+        },
+    }, async (a) => {
+        try {
+            const hosts = listConfigHosts(a.configPath);
+            if (hosts.length === 0)
+                return text("No Host entries found in ssh config.");
+            const lines = hosts.map((h) => {
+                const bits = [];
+                if (h.hostName)
+                    bits.push(`hostname=${h.hostName}`);
+                if (h.user)
+                    bits.push(`user=${h.user}`);
+                if (h.port)
+                    bits.push(`port=${h.port}`);
+                if (h.proxyJump)
+                    bits.push(`jump=${h.proxyJump}`);
+                const detail = bits.length ? `  (${bits.join(", ")})` : "";
+                return `${h.patterns.join(" ")}${detail}`;
+            });
+            return text(`Host aliases (${hosts.length}):\n${lines.join("\n")}`);
+        }
+        catch (err) {
+            return errorText(`ssh_config_hosts failed: ${err.message}`);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,YAAY,GAAG,GAAG,CAAC;AACzB,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,yEAAyE;AACzE,wDAAwD;AACxD,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,YAAY,GAAG,KAAK,CAAC;AAC3B,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAO9B,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,sEAAsE;AACtE,SAAS,UAAU,CAAC,OAAgB,EAAE,IAAgB,EAAE,MAAoB;IAC1E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC;QAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAClG,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,SAAS,GAAG,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,KAAK,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9D,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;AAClC,CAAC;AAED,SAAS,WAAW,CAAC,MAAoB,EAAE,OAAgB,EAAE,IAAgB;IAC3E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC;IACtE,MAAM,IAAI,GACR,IAAI,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,MAAM;QACnC,CAAC,CAAC,6EAA6E;QAC/E,CAAC,CAAC,IAAI,KAAK,OAAO;YAChB,CAAC,CAAC,gGAAgG;YAClG,CAAC,CAAC,EAAE,CAAC;IACX,OAAO,GAAG,IAAI,KAAK,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;AAChE,CAAC;AAED,yEAAyE;AACzE,wEAAwE;AACxE,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtD,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACpD,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAChE,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAC/D,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAE7D,MAAM,UAAU,YAAY,CAAC,OAAuB;IAClD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,OAAO;KACjB,EACD;QACE,YAAY,EAAE;YACZ,oEAAoE;YACpE,EAAE;YACF,4EAA4E;YAC5E,4EAA4E;YAC5E,2EAA2E;YAC3E,mCAAmC;YACnC,EAAE;YACF,4EAA4E;YAC5E,4EAA4E;YAC5E,EAAE;YACF,eAAe;YACf,2EAA2E;YAC3E,0EAA0E;YAC1E,uEAAuE;YACvE,iFAAiF;YACjF,sEAAsE;YACtE,EAAE;YACF,2EAA2E;YAC3E,8EAA8E;YAC9E,EAAE;YACF,uEAAuE;YACvE,4EAA4E;YAC5E,EAAE;YACF,yBAAyB;YACzB,yEAAyE;YACzE,4EAA4E;YAC5E,0EAA0E;YAC1E,mCAAmC;YACnC,6EAA6E;YAC7E,yEAAyE;YACzE,gDAAgD;YAChD,wEAAwE;YACxE,uEAAuE;YACvE,8CAA8C;SAC/C,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,qFAAqF;YACrF,mFAAmF;YACnF,uFAAuF;YACvF,4FAA4F;QAC9F,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,gEAAgE,CAAC;YAClG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;YAC5F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;YACnH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;YACxF,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,2EAA2E,CAAC;YACxF,aAAa,EAAE,CAAC;iBACb,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,yEAAyE,CAAC;YACtF,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;YAC/F,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qDAAqD,CAAC;YAChG,IAAI,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,YAAY,GAAG,CAAC;YAChF,IAAI,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,YAAY,GAAG,CAAC;YACjF,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,cAAc,GAAG,CAAC;YAC7G,SAAS,EAAE,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,eAAe,GAAG,CAAC;YACxG,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,iBAAiB,GAAG,CAAC;SAC1G;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,YAAY,CAAC;YACpC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,YAAY,CAAC;YACpC,MAAM,GAAG,GAAG,eAAe,CAAC;gBAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,YAAY,EAAE,CAAC,CAAC,YAAY;gBAC5B,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;aACrB,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAChD,uEAAuE;YACvE,uEAAuE;YACvE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAC,CAAC,SAAS,IAAI,eAAe,EAAE,IAAI,CAAC,CAAC;YAC3G,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;YACrE,MAAM,MAAM,GAAG,mBAAmB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YACzD,MAAM,YAAY,GAChB,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;gBACxC,CAAC,CAAC,0FAA0F;gBAC5F,CAAC,CAAC,EAAE,CAAC;YACT,OAAO,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC;QACjF,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,uBAAwB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,UAAU,EACV;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,4FAA4F;YAC5F,2FAA2F;YAC3F,gGAAgG;YAChG,mDAAmD;QACrD,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6BAA6B,CAAC;YAClE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+DAA+D,CAAC;YACrG,IAAI,EAAE,CAAC;iBACJ,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,EAAE;iBACV,QAAQ,CACP,yGAAyG;gBACvG,2GAA2G,CAC9G;YACH,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iEAAiE,CAAC;YAC/G,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,WAAW,GAAG,CAAC;YAC3F,SAAS,EAAE,aAAa,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,YAAY,GAAG,CAAC;YAC7F,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,iBAAiB,GAAG,CAAC;SAC1G;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,OAAO,CAAC,MAAM;gBAAE,OAAO,SAAS,CAAC,WAAW,OAAO,CAAC,EAAE,uCAAuC,CAAC,CAAC;YAEnG,IAAI,OAAO,GAAG,EAAE,CAAC;YACjB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC,CAAC,IAAI,CAAC;YAC5C,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,OAAO,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;YAC3F,CAAC;YACD,IAAI,CAAC,CAAC,WAAW;gBAAE,OAAO,IAAI,IAAI,CAAC;YACnC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,SAAS,CAAC,gEAAgE,CAAC,CAAC;YACrF,CAAC;YAED,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACvB,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC;YAC/F,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,oBAAqB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,UAAU,EACV;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EACT,wFAAwF;YACxF,wFAAwF;YACxF,qDAAqD;QACvD,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;YACjD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+EAA+E,CAAC;YACpI,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,WAAW,EAAE;iBACb,GAAG,CAAC,OAAO,CAAC;iBACZ,QAAQ,EAAE;iBACV,QAAQ,CAAC,gIAAgI,CAAC;YAC7I,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,iBAAiB,GAAG,CAAC;YAC5G,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;SAC7G;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,IAAI,GAAe,MAAM,CAAC;YAC9B,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7B,oEAAoE;gBACpE,oEAAoE;gBACpE,6CAA6C;gBAC7C,wDAAwD;gBACxD,gDAAgD;gBAChD,8CAA8C;gBAC9C,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBAClD,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;oBAC5B,IAAI,GAAG,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;gBAC3E,CAAC;qBAAM,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBACtC,IAAI,GAAG,OAAO,CAAC;gBACjB,CAAC;qBAAM,CAAC;oBACN,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC;gBACtB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;gBACrB,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;gBAChD,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,OAAO,CAAC,EAAE,YAAY,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YACxI,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,oBAAqB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE,8FAA8F;QAC3G,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;YACjD,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE;YACjC,SAAS,EAAE,aAAa,CAAC,QAAQ,EAAE;YACnC,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE;SACpC;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,OAAO,CAAC,MAAM;gBAAE,OAAO,SAAS,CAAC,WAAW,OAAO,CAAC,EAAE,sBAAsB,CAAC,CAAC;YAClF,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACtB,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC,CAAC,SAAS,IAAI,YAAY,CAAC,CAAC;YAC/F,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,yBAA0B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,2FAA2F;QACxG,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;YACjD,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,kBAAkB,CAAC;YAC7C,IAAI,EAAE,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAC;SAC3C;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC3C,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC,WAAW,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,sBAAuB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,UAAU,EACV;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,sEAAsE;QACnF,WAAW,EAAE,EAAE;KAChB,EACD,KAAK,IAAI,EAAE;QACT,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;YAC7D,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,QAAQ,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YACtE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,UAAU,CAAC;YACpC,OAAO,GAAG,CAAC,CAAC,EAAE,KAAK,KAAK,KAAK,IAAI,IAAI,IAAI,SAAS,CAAC,CAAC,GAAG,SAAS,MAAM,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;QACxF,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,oBAAoB,QAAQ,CAAC,MAAM,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,gDAAgD;QAC7D,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;SAC3D;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACrC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;IAClG,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,kBAAkB,EAClB;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,qFAAqF;YACrF,+EAA+E;QACjF,WAAW,EAAE;YACX,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;SAC5F;KACF,EACD,KAAK,EAAE,CAAC,EAAE,EAAE;QACV,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;YAC5C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC,sCAAsC,CAAC,CAAC;YAC5E,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC5B,MAAM,IAAI,GAAa,EAAE,CAAC;gBAC1B,IAAI,CAAC,CAAC,QAAQ;oBAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACpD,IAAI,CAAC,CAAC,IAAI;oBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACxC,IAAI,CAAC,CAAC,IAAI;oBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACxC,IAAI,CAAC,CAAC,SAAS;oBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;gBAClD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,OAAO,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC;YAC5C,CAAC,CAAC,CAAC;YACH,OAAO,IAAI,CAAC,iBAAiB,KAAK,CAAC,MAAM,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,SAAS,CAAC,4BAA6B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC,CACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,89 @@
+export interface SessionOptions {
+    /** The command to run (usually "ssh"). */
+    file: string;
+    /** Arguments for the command. */
+    args: string[];
+    cols: number;
+    rows: number;
+    /** Human-readable label describing the destination, for listings. */
+    label: string;
+    /** Lines of scrollback the emulator retains. */
+    scrollback?: number;
+}
+export interface RenderResult {
+    text: string;
+    cursorRow: number;
+    cursorCol: number;
+    rows: number;
+    cols: number;
+    totalLines: number;
+    shownLines: number;
+}
+export type WaitReason = "idle" | "timeout" | "exited" | "data" | "quiet";
+export interface WaitResult {
+    reason: WaitReason;
+}
+/**
+ * One persistent child process (typically the ssh client) attached to a PTY,
+ * with its output fed into a headless xterm emulator so callers can read a
+ * rendered screen instead of a raw escape-code stream.
+ */
+export declare class Session {
+    readonly id: string;
+    readonly label: string;
+    readonly startedAt: number;
+    private pty;
+    private term;
+    private raw;
+    private lastDataAt;
+    /** Bumped only by child output, never by our own writes. */
+    private dataEvents;
+    private _exited;
+    private _exitCode;
+    private _exitSignal;
+    constructor(id: string, opts: SessionOptions);
+    get exited(): boolean;
+    get exitCode(): number | null;
+    get exitSignal(): number | null;
+    get pid(): number;
+    get dimensions(): {
+        cols: number;
+        rows: number;
+    };
+    /** True while the remote app has DECCKM (application cursor keys) enabled. */
+    get applicationCursorKeys(): boolean;
+    /** Write raw bytes to the PTY. Marks activity so idle-waits behave. */
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    /**
+     * Wait until the output has been quiet for `settleMs`, or `timeoutMs`
+     * elapses, or the process exits — whichever comes first. This is how we
+     * decide a command's output has "settled" enough to read.
+     *
+     * With `requireData`, the settle clock only counts once the child has
+     * produced at least one byte of output — so a slow connection (DNS, TCP,
+     * key exchange) isn't mistaken for an already-settled screen.
+     */
+    waitForIdle(settleMs: number, timeoutMs: number, requireData?: boolean): Promise<WaitResult>;
+    /**
+     * Wait for *new* child output (any byte after this call), the process
+     * exiting, or `timeoutMs` — whichever comes first. Unlike waitForIdle, an
+     * already-quiet session blocks here until something actually arrives.
+     */
+    waitForData(timeoutMs: number): Promise<WaitResult>;
+    /** Flush the xterm write queue so a subsequent render sees all output. */
+    private flush;
+    /**
+     * Render the emulated screen as text. Returns the tail of the buffer down
+     * to the bottom of the viewport (not just the cursor line — full-screen
+     * apps often leave the cursor mid-screen with content below it), capped at
+     * `maxLines`. Trailing blank lines are trimmed. This collapses
+     * redraws/colors/cursor moves into the plain text a human would see.
+     */
+    render(maxLines: number): Promise<RenderResult>;
+    /** Return the tail of the raw PTY byte stream (escape codes included). */
+    rawTail(maxBytes: number): string;
+    /** Terminate the child. SIGHUP first; caller may escalate. */
+    close(signal?: string): void;
+    kill(): void;
+}