mcp-for-i 0.1.13 → 0.2.0

package/dist/ibmi/sqlParse.js

@@ -0,0 +1,317 @@
+/**
+ * Small lexical SQL analyser for the text sent to QZDFMDB2.
+ *
+ * It does not parse SQL grammar. It splits the text into segments (code,
+ * string literals, delimited identifiers, comments and `@` CL lines) so that
+ * callers can split statements, find embedded CL commands and decide whether
+ * a request is read-only without being fooled by quotes or comments.
+ */
+const READ_ONLY_FIRST_KEYWORDS = new Set(["SELECT", "WITH", "VALUES"]);
+const DATA_CHANGE_TABLE_KEYWORDS = new Set(["FINAL", "NEW", "OLD"]);
+const DATA_CHANGE_STATEMENTS = new Set(["INSERT", "UPDATE", "DELETE", "MERGE"]);
+/**
+ * Splits SQL text into lexical segments. A line whose first character is `@`
+ * while the lexer is not inside a literal or block comment is a CL line; this
+ * matches what Tools.fixSQL converts into a QCMDEXC call.
+ */
+export function lexSqlSegments(sql) {
+    const segments = [];
+    const n = sql.length;
+    let i = 0;
+    let codeStart = 0;
+    const flushCode = (end) => {
+        if (end > codeStart) {
+            segments.push({ kind: "code", start: codeStart, end, text: sql.slice(codeStart, end) });
+        }
+    };
+    while (i < n) {
+        const ch = sql[i];
+        const atLineStart = i === 0 || sql[i - 1] === "\n";
+        if (atLineStart && ch === "@") {
+            flushCode(i);
+            let end = sql.indexOf("\n", i);
+            if (end === -1)
+                end = n;
+            const text = sql.slice(i, end);
+            let command = text.slice(1).replace(/\r$/, "");
+            if (command.endsWith(";"))
+                command = command.slice(0, -1);
+            segments.push({ kind: "cl", start: i, end, text, value: command });
+            i = end;
+            codeStart = i;
+            continue;
+        }
+        if (ch === "'" || ch === "\"") {
+            flushCode(i);
+            const quote = ch;
+            let j = i + 1;
+            let value = "";
+            let terminated = false;
+            while (j < n) {
+                if (sql[j] === quote) {
+                    if (sql[j + 1] === quote) {
+                        value += quote;
+                        j += 2;
+                        continue;
+                    }
+                    terminated = true;
+                    j++;
+                    break;
+                }
+                value += sql[j];
+                j++;
+            }
+            segments.push({
+                kind: quote === "'" ? "string" : "qident",
+                start: i,
+                end: j,
+                text: sql.slice(i, j),
+                value,
+                ...(terminated ? {} : { unterminated: true })
+            });
+            i = j;
+            codeStart = i;
+            continue;
+        }
+        if (ch === "-" && sql[i + 1] === "-") {
+            flushCode(i);
+            let end = sql.indexOf("\n", i);
+            if (end === -1)
+                end = n;
+            segments.push({ kind: "line", start: i, end, text: sql.slice(i, end) });
+            i = end;
+            codeStart = i;
+            continue;
+        }
+        if (ch === "/" && sql[i + 1] === "*") {
+            flushCode(i);
+            // Block comments are treated as non-nested: the comment ends at the first */.
+            // If Db2 nests them it sees more text as comment, never less.
+            const close = sql.indexOf("*/", i + 2);
+            const end = close === -1 ? n : close + 2;
+            segments.push({
+                kind: "block",
+                start: i,
+                end,
+                text: sql.slice(i, end),
+                ...(close === -1 ? { unterminated: true } : {})
+            });
+            i = end;
+            codeStart = i;
+            continue;
+        }
+        i++;
+    }
+    flushCode(n);
+    return segments;
+}
+/** Converts segments into significant tokens (comments dropped). */
+export function tokenizeSql(sql) {
+    return segmentsToTokens(lexSqlSegments(sql));
+}
+function segmentsToTokens(segments) {
+    const tokens = [];
+    for (const seg of segments) {
+        switch (seg.kind) {
+            case "string":
+            case "qident":
+                tokens.push({ type: seg.kind, value: seg.value ?? "", start: seg.start, end: seg.end });
+                break;
+            case "cl":
+                tokens.push({ type: "cl", value: seg.value ?? "", start: seg.start, end: seg.end });
+                break;
+            case "code": {
+                const re = /([A-Za-z_#$@][A-Za-z0-9_#$@]*)|(\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?)|(\S)/g;
+                let m;
+                while ((m = re.exec(seg.text))) {
+                    const start = seg.start + m.index;
+                    const end = start + m[0].length;
+                    if (m[1])
+                        tokens.push({ type: "word", value: m[1].toUpperCase(), start, end });
+                    else if (m[2])
+                        tokens.push({ type: "number", value: m[2], start, end });
+                    else
+                        tokens.push({ type: "punct", value: m[3], start, end });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return tokens;
+}
+/**
+ * Splits SQL into statements on `;`, ignoring semicolons inside literals,
+ * delimited identifiers and comments. Each `@` CL line is its own statement.
+ * Statements with no significant tokens are dropped.
+ */
+export function splitSqlStatements(sql) {
+    const tokens = tokenizeSql(sql);
+    const statements = [];
+    let current = [];
+    const flush = () => {
+        if (current.length > 0) {
+            const start = current[0].start;
+            const end = current[current.length - 1].end;
+            statements.push({ text: sql.slice(start, end), start, end, tokens: current });
+        }
+        current = [];
+    };
+    for (const token of tokens) {
+        if (token.type === "cl") {
+            flush();
+            current.push(token);
+            flush();
+            continue;
+        }
+        if (token.type === "punct" && token.value === ";") {
+            flush();
+            continue;
+        }
+        current.push(token);
+    }
+    flush();
+    return statements;
+}
+/**
+ * The statement type of the first statement: its first keyword, upper-cased
+ * ("SELECT", "INSERT", ...), "CL" for an `@` line, or "UNKNOWN".
+ */
+export function getSqlStatementType(sql) {
+    const first = splitSqlStatements(sql)[0];
+    if (!first)
+        return "UNKNOWN";
+    const token = first.tokens.find(t => !(t.type === "punct" && t.value === "("));
+    if (!token)
+        return "UNKNOWN";
+    if (token.type === "cl")
+        return "CL";
+    if (token.type === "word")
+        return token.value;
+    return "UNKNOWN";
+}
+/**
+ * Lists the CL commands embedded in SQL text: `@` lines (which Tools.fixSQL
+ * turns into QCMDEXC calls) and calls to QCMDEXC (procedure or scalar
+ * function, qualified or not). For QCMDEXC the first argument is returned when
+ * it is a single string literal; otherwise `command` is null because the
+ * command is built at run time and cannot be checked statically.
+ */
+export function extractEmbeddedClCommands(sql) {
+    const tokens = tokenizeSql(sql);
+    const result = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === "cl") {
+            result.push({ source: "at-line", command: token.value, offset: token.start });
+            continue;
+        }
+        if (!isQcmdexcName(token))
+            continue;
+        const open = tokens[i + 1];
+        const arg = tokens[i + 2];
+        const after = tokens[i + 3];
+        let command = null;
+        if (open?.type === "punct" && open.value === "(" &&
+            arg?.type === "string" &&
+            after?.type === "punct" && (after.value === "," || after.value === ")")) {
+            command = arg.value;
+        }
+        result.push({ source: "qcmdexc", command, offset: token.start });
+    }
+    return result;
+}
+function isQcmdexcName(token) {
+    return (token.type === "word" || token.type === "qident") && token.value.toUpperCase() === "QCMDEXC";
+}
+/**
+ * Decides whether SQL may run through the read-only `ibmi.sql.query` tool.
+ *
+ * Allowed: exactly one SELECT, WITH or VALUES statement (optionally wrapped
+ * in parentheses, optionally ending with one `;`). Rejected:
+ * - more than one statement;
+ * - any line starting with `@` (a CL command);
+ * - any reference to QCMDEXC;
+ * - data-change table references such as FINAL TABLE (INSERT ...);
+ * - unterminated literals or comments;
+ * - a `;` inside a literal or comment, because QZDFMDB2 (-t) splits
+ *   statements itself and is not known to respect quotes.
+ */
+export function checkReadOnlySql(sql) {
+    if (/^\s*@/m.test(sql)) {
+        return { readOnly: false, reason: "lines starting with @ run CL commands" };
+    }
+    const segments = lexSqlSegments(sql);
+    for (const seg of segments) {
+        if (seg.kind === "cl") {
+            return { readOnly: false, reason: "lines starting with @ run CL commands" };
+        }
+        if (seg.unterminated) {
+            return { readOnly: false, reason: "unterminated string, identifier or comment" };
+        }
+        if (seg.kind !== "code" && seg.text.includes(";")) {
+            return { readOnly: false, reason: "a semicolon inside a string, identifier or comment is not allowed in read-only SQL" };
+        }
+    }
+    const tokens = segmentsToTokens(segments);
+    const significant = tokens.filter(t => !(t.type === "punct" && t.value === ";"));
+    if (significant.length === 0) {
+        return { readOnly: false, reason: "no SQL statement" };
+    }
+    // Only one statement: every ';' must come after the last significant token.
+    const lastSignificant = significant[significant.length - 1];
+    const semicolons = tokens.filter(t => t.type === "punct" && t.value === ";");
+    if (semicolons.some(t => t.start < lastSignificant.start)) {
+        return { readOnly: false, reason: "multiple statements are not allowed" };
+    }
+    if (semicolons.length > 1) {
+        return { readOnly: false, reason: "multiple statements are not allowed" };
+    }
+    const first = significant.find(t => !(t.type === "punct" && t.value === "("));
+    if (!first || first.type !== "word" || !READ_ONLY_FIRST_KEYWORDS.has(first.value)) {
+        return { readOnly: false, reason: "only SELECT, WITH and VALUES statements are read-only" };
+    }
+    for (let i = 0; i < significant.length; i++) {
+        const t = significant[i];
+        if (isQcmdexcName(t)) {
+            return { readOnly: false, reason: "QCMDEXC runs CL commands" };
+        }
+        if (t.type === "word" && DATA_CHANGE_TABLE_KEYWORDS.has(t.value)) {
+            const next = significant[i + 1];
+            const open = significant[i + 2];
+            const stmt = significant[i + 3];
+            if (next?.type === "word" && next.value === "TABLE" &&
+                open?.type === "punct" && open.value === "(" &&
+                stmt?.type === "word" && DATA_CHANGE_STATEMENTS.has(stmt.value)) {
+                return { readOnly: false, reason: `${t.value} TABLE (${stmt.value} ...) changes data` };
+            }
+        }
+    }
+    return { readOnly: true };
+}
+export function isReadOnlySql(sql) {
+    return checkReadOnlySql(sql).readOnly;
+}
+/**
+ * Rewrites SQL for QZDFMDB2: `@` lines become QCMDEXC calls and, when
+ * removeComments is set, `--` comments are removed. Literals, delimited
+ * identifiers and block comments are left untouched, so `--` inside a string
+ * is kept.
+ */
+export function rewriteSqlForQzdfmdb2(sql, removeComments = false) {
+    let out = "";
+    for (const seg of lexSqlSegments(sql)) {
+        switch (seg.kind) {
+            case "cl":
+                out += `Call QSYS2.QCMDEXC('${(seg.value ?? "").replaceAll("'", "''")}');`;
+                break;
+            case "line":
+                out += removeComments ? "" : `\n${seg.text}`;
+                break;
+            default:
+                out += seg.text;
+        }
+    }
+    return out;
+}

package/dist/ibmi/tn5250/certTrust.js

@@ -0,0 +1,59 @@
+import path from "path";
+import { getConfigDir } from "../../config/store.js";
+import { hostKeyFingerprint, isNewHostKeyAccepted, knownHostId, readKnownHosts, writeKnownHosts } from "../knownHosts.js";
+/**
+ * Trust for TN5250 TLS server certificates.
+ *
+ * A certificate that chains to a trusted CA and matches the host name is
+ * accepted as is. Any other certificate (typically self-signed on IBM i) is
+ * trusted on first use: its SHA-256 fingerprint is pinned per host:port in
+ * known_tls_certs.json, and a different certificate later is refused unless
+ * explicitly accepted.
+ */
+export const ACCEPT_NEW_TLS_CERT_ENV = "MCP_FOR_I_ACCEPT_NEW_TLSCERT";
+export class TlsCertificateMismatchError extends Error {
+    hostKey;
+    expected;
+    presented;
+    filePath;
+    constructor(hostKey, expected, presented, filePath) {
+        super(`TLS certificate for ${hostKey} has changed. Stored ${expected}, server presented ${presented}. ` +
+            `This can mean a man-in-the-middle attack, so the connection was refused. ` +
+            `If the change is expected (for example the certificate was renewed), ` +
+            `set ${ACCEPT_NEW_TLS_CERT_ENV}=${hostKey} (or =${presented}) and connect again, ` +
+            `or remove the "${hostKey}" entry from ${filePath}.`);
+        this.hostKey = hostKey;
+        this.expected = expected;
+        this.presented = presented;
+        this.filePath = filePath;
+        this.name = "TlsCertificateMismatchError";
+    }
+}
+export function getKnownTlsCertsPath() {
+    return path.join(getConfigDir(), "known_tls_certs.json");
+}
+let queue = Promise.resolve();
+export function checkTlsCertificate(options) {
+    const fingerprint = hostKeyFingerprint(options.certificate);
+    if (options.authorized)
+        return Promise.resolve({ status: "ca-verified", fingerprint });
+    const run = async () => {
+        const filePath = options.filePath || getKnownTlsCertsPath();
+        const acceptNew = options.acceptNew ?? process.env[ACCEPT_NEW_TLS_CERT_ENV];
+        const id = knownHostId(options.host, options.port);
+        const data = await readKnownHosts(filePath);
+        const existing = data.hosts[id];
+        const now = new Date().toISOString();
+        if (existing && existing.fingerprint === fingerprint)
+            return { status: "trusted", fingerprint };
+        if (existing && !isNewHostKeyAccepted(acceptNew, options.host, options.port, fingerprint)) {
+            throw new TlsCertificateMismatchError(id, existing.fingerprint, fingerprint, filePath);
+        }
+        data.hosts[id] = { fingerprint, keyType: "x509", addedAt: existing ? existing.addedAt : now, updatedAt: now };
+        await writeKnownHosts(filePath, data);
+        return { status: existing ? "replaced" : "added", fingerprint };
+    };
+    const result = queue.then(run, run);
+    queue = result.catch(() => undefined);
+    return result;
+}

package/dist/ibmi/tn5250/client.js

@@ -0,0 +1,310 @@
+import { EventEmitter } from "events";
+import net from "net";
+import tls from "tls";
+import { AID, FLAG_ATN, FLAG_SRQ, OP_NO_OP, buildGdsRecord, parseGdsRecord } from "./datastream.js";
+import { Screen } from "./screen.js";
+import { DO, DONT, ENV_SEND, OPT_BINARY, OPT_EOR, OPT_NEW_ENVIRON, OPT_TERMINAL_TYPE, TT_SEND, TelnetParser, WILL, WONT, envIs, frameRecord, parseEnvSend, telnetCommand, terminalTypeIs } from "./telnet.js";
+const AID_ALIASES = {
+    ENTER: AID.ENTER,
+    RETURN: AID.ENTER,
+    HELP: AID.HELP,
+    PAGEUP: AID.ROLLDOWN,
+    ROLLDOWN: AID.ROLLDOWN,
+    PGUP: AID.ROLLDOWN,
+    PAGEDOWN: AID.ROLLUP,
+    ROLLUP: AID.ROLLUP,
+    PGDN: AID.ROLLUP,
+    PRINT: AID.PRINT,
+    CLEAR: AID.CLEAR,
+    RECORDBACKSPACE: AID.RECORD_BACKSPACE
+};
+/** AID byte for a key name, or undefined when it is not an AID key. */
+export function aidForKey(name) {
+    const key = name.toUpperCase().replace(/[\s_-]/g, "");
+    if (key in AID_ALIASES)
+        return AID_ALIASES[key];
+    const f = /^F([1-9]|1[0-9]|2[0-4])$/.exec(key);
+    if (f)
+        return AID[`F${f[1]}`];
+    return undefined;
+}
+const SUPPORTED_DO = new Set([OPT_BINARY, OPT_TERMINAL_TYPE, OPT_EOR, OPT_NEW_ENVIRON]);
+const SUPPORTED_WILL = new Set([OPT_BINARY, OPT_EOR]);
+export class Tn5250Client extends EventEmitter {
+    options;
+    screen;
+    closed = false;
+    closeReason;
+    secure = false;
+    certificateStatus;
+    autoSignOnOffered = false;
+    negotiated = { binary: false, eor: false, terminalType: false, newEnviron: false };
+    socket;
+    parser = new TelnetParser();
+    willSent = new Set();
+    doSent = new Set();
+    lastUpdateAt = 0;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.setMaxListeners(50);
+        const terminalType = options.terminalType || "IBM-3179-2";
+        this.screen = new Screen({ ccsid: options.ccsid, deviceType: terminalType === "IBM-3477-FC" ? "3477" : "3179" });
+    }
+    get terminalType() {
+        return this.options.terminalType || "IBM-3179-2";
+    }
+    /** Open the connection. Resolves once TCP (and TLS, if used) is established and trusted. */
+    connect() {
+        const { host, port } = this.options;
+        const timeoutMs = this.options.connectTimeoutMs ?? 15000;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const fail = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.markClosed(err.message);
+                socket.destroy();
+                reject(err);
+            };
+            const timer = setTimeout(() => fail(new Error(`TN5250 connection to ${host}:${port} timed out after ${timeoutMs} ms`)), timeoutMs);
+            const ready = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve();
+            };
+            let socket;
+            if (this.options.tls) {
+                const tlsSocket = tls.connect({
+                    host,
+                    port,
+                    servername: net.isIP(host) ? undefined : host,
+                    // Verification is done below so self-signed IBM i certificates can be pinned.
+                    rejectUnauthorized: false
+                });
+                socket = tlsSocket;
+                tlsSocket.once("secureConnect", async () => {
+                    try {
+                        const cert = tlsSocket.getPeerCertificate(false);
+                        if (!cert || !cert.raw)
+                            throw new Error("TLS server did not present a certificate");
+                        this.certificateStatus = await (this.options.checkCertificate
+                            ? this.options.checkCertificate({
+                                host,
+                                port,
+                                certificate: cert.raw,
+                                authorized: tlsSocket.authorized,
+                                authorizationError: tlsSocket.authorizationError ? String(tlsSocket.authorizationError) : undefined
+                            })
+                            : Promise.reject(new Error("No TLS certificate check configured")));
+                        this.secure = true;
+                        this.attach(socket);
+                        ready();
+                    }
+                    catch (err) {
+                        fail(err instanceof Error ? err : new Error(String(err)));
+                    }
+                });
+            }
+            else {
+                socket = net.connect({ host, port });
+                socket.once("connect", () => {
+                    this.attach(socket);
+                    ready();
+                });
+            }
+            socket.on("error", err => {
+                if (!settled)
+                    fail(err);
+                else
+                    this.markClosed(err.message);
+            });
+            socket.on("close", () => this.markClosed(this.closeReason || "connection closed by host"));
+            this.socket = socket;
+        });
+    }
+    attach(socket) {
+        socket.setNoDelay(true);
+        socket.on("data", (chunk) => this.onData(typeof chunk === "string" ? Buffer.from(chunk, "latin1") : chunk));
+    }
+    markClosed(reason) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.closeReason = reason;
+        this.emit("update");
+        this.emit("close", reason);
+    }
+    close() {
+        this.markClosed("disconnected");
+        this.socket?.destroy();
+    }
+    write(bytes) {
+        if (this.closed || !this.socket)
+            throw new Error(`TN5250 session is closed (${this.closeReason || "not connected"})`);
+        this.socket.write(bytes);
+    }
+    /** Feed raw bytes (used by the socket handler and by tests). */
+    onData(chunk) {
+        let events;
+        try {
+            events = this.parser.push(chunk);
+        }
+        catch (err) {
+            this.screen.warnings.push(`telnet parse error: ${err?.message || err}`);
+            return;
+        }
+        for (const event of events) {
+            if (event.type === "command")
+                this.onCommand(event.command, event.option);
+            else if (event.type === "subnegotiation")
+                this.onSubnegotiation(event.option, event.data);
+            else
+                this.onRecord(event.data);
+        }
+    }
+    onCommand(command, option) {
+        if (command === DO) {
+            if (SUPPORTED_DO.has(option)) {
+                if (!this.willSent.has(option)) {
+                    this.willSent.add(option);
+                    this.write(telnetCommand(WILL, option));
+                }
+                if (option === OPT_BINARY)
+                    this.negotiated.binary = true;
+                if (option === OPT_EOR)
+                    this.negotiated.eor = true;
+            }
+            else {
+                this.write(telnetCommand(WONT, option));
+            }
+        }
+        else if (command === WILL) {
+            if (SUPPORTED_WILL.has(option)) {
+                if (!this.doSent.has(option)) {
+                    this.doSent.add(option);
+                    this.write(telnetCommand(DO, option));
+                }
+            }
+            else {
+                this.write(telnetCommand(DONT, option));
+            }
+        }
+        else if (command === DONT) {
+            if (this.willSent.delete(option))
+                this.write(telnetCommand(WONT, option));
+        }
+    }
+    onSubnegotiation(option, data) {
+        if (option === OPT_TERMINAL_TYPE && data[0] === TT_SEND) {
+            this.negotiated.terminalType = true;
+            this.write(terminalTypeIs(this.terminalType));
+        }
+        else if (option === OPT_NEW_ENVIRON && data[0] === ENV_SEND) {
+            this.negotiated.newEnviron = true;
+            parseEnvSend(data.subarray(1));
+            this.write(envIs(this.environment()));
+        }
+    }
+    /** NEW-ENVIRON values sent to the server. */
+    environment() {
+        const ascii = (text) => Buffer.from(text, "ascii");
+        const values = [];
+        if (this.options.deviceName)
+            values.push({ kind: "uservar", name: "DEVNAME", value: ascii(this.options.deviceName) });
+        values.push({ kind: "uservar", name: "KBDTYPE", value: ascii("USB") });
+        values.push({ kind: "uservar", name: "CODEPAGE", value: ascii("37") });
+        values.push({ kind: "uservar", name: "CHARSET", value: ascii("697") });
+        const signOn = this.options.autoSignOn;
+        if (signOn) {
+            // RFC 4777: an empty IBMRSEED means IBMSUBSPW carries the password unencrypted.
+            values.push({ kind: "var", name: "USER", value: ascii(signOn.user) });
+            values.push({ kind: "uservar", name: "IBMRSEED", value: Buffer.alloc(0) });
+            values.push({ kind: "uservar", name: "IBMSUBSPW", value: ascii(signOn.password) });
+            this.autoSignOnOffered = true;
+        }
+        return values;
+    }
+    onRecord(record) {
+        try {
+            const responses = this.screen.process(parseGdsRecord(record));
+            for (const response of responses)
+                this.write(frameRecord(response));
+        }
+        catch (err) {
+            this.screen.warnings.push(err?.message || String(err));
+        }
+        this.lastUpdateAt = Date.now();
+        this.emit("update");
+    }
+    /** Send an AID key (Enter, F1-F24, PageUp, ...) or Attn / SysReq. */
+    sendKey(name) {
+        const key = name.toUpperCase().replace(/[\s_-]/g, "");
+        if (key === "ATTN") {
+            this.write(frameRecord(buildGdsRecord(OP_NO_OP, new Uint8Array(0), FLAG_ATN)));
+            this.screen.keyboardLocked = true;
+            return;
+        }
+        if (key === "SYSREQ") {
+            this.write(frameRecord(buildGdsRecord(OP_NO_OP, new Uint8Array(0), FLAG_SRQ)));
+            this.screen.keyboardLocked = true;
+            return;
+        }
+        const aid = aidForKey(key);
+        if (aid === undefined)
+            throw new Error(`Unknown AID key: ${name}`);
+        this.lastUpdateAt = Date.now();
+        this.write(frameRecord(this.screen.buildAidResponse(aid)));
+    }
+    /** True once the host has handed control back to the operator. */
+    isReady() {
+        return !this.screen.keyboardLocked || this.screen.inputInhibited;
+    }
+    /**
+     * Wait until the predicate holds. Re-checks on every screen update.
+     * Resolves false on timeout or when the connection closes first.
+     */
+    waitFor(predicate, timeoutMs) {
+        if (predicate())
+            return Promise.resolve(true);
+        if (this.closed)
+            return Promise.resolve(false);
+        return new Promise(resolve => {
+            const done = (value) => {
+                clearTimeout(timer);
+                this.off("update", check);
+                resolve(value);
+            };
+            const check = () => {
+                if (predicate())
+                    done(true);
+                else if (this.closed)
+                    done(false);
+            };
+            const timer = setTimeout(() => done(predicate()), timeoutMs);
+            this.on("update", check);
+        });
+    }
+    /** Wait for the keyboard to unlock, then for a short quiet period with no more records. */
+    async waitForSettled(timeoutMs, quietMs = 150) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return this.isReady();
+            const ready = await this.waitFor(() => this.isReady(), remaining);
+            if (!ready)
+                return false;
+            const sinceUpdate = Date.now() - this.lastUpdateAt;
+            if (sinceUpdate >= quietMs)
+                return true;
+            await new Promise(resolve => setTimeout(resolve, Math.min(quietMs - sinceUpdate, Math.max(0, deadline - Date.now()))));
+            if (Date.now() - this.lastUpdateAt >= quietMs && this.isReady())
+                return true;
+        }
+    }
+}