@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/keepers/terminal/input.js

@@ -0,0 +1,146 @@
+import { KeeperMethodError } from '../kit/protocol.js';
+import { TERMINAL_GRID_LIMITS } from './gridProtocol.js';
+const esc = '\x1b';
+const modifiers = (mask) => 1 + (mask & 1) + (mask & 2) + (mask & 4) + (mask & 8);
+const arrows = { 79: 'C', 80: 'D', 81: 'B', 82: 'A', 74: 'H', 77: 'F' };
+const tilde = { 73: 2, 76: 3, 75: 5, 78: 6, 62: 15, 63: 17, 64: 18, 65: 19, 66: 20, 67: 21, 68: 23, 69: 24 };
+const keypad = {
+    84: ['/', 'o'], 85: ['*', 'j'], 86: ['-', 'm'], 87: ['+', 'k'], 88: ['\r', 'M'],
+    89: ['1', 'q'], 90: ['2', 'r'], 91: ['3', 's'], 92: ['4', 't'], 93: ['5', 'u'], 94: ['6', 'v'],
+    95: ['7', 'w'], 96: ['8', 'x'], 97: ['9', 'y'], 98: ['0', 'p'], 99: ['.', 'n'], 103: ['=', 'X'],
+};
+/** One attachment's only held input is its mouse buttons; modifiers are explicit per event. */
+export class TerminalInputEncoder {
+    buttons = new Set();
+    release() { this.buttons.clear(); }
+    encode(event, screen) {
+        switch (event.kind) {
+            case 'release':
+                this.release();
+                return '';
+            case 'text': return event.text;
+            case 'paste': return screen.modes.bracketedPaste ? `${esc}[200~${event.text}${esc}[201~` : event.text;
+            case 'key': return event.down ? encodeKey(event.usage, event.modifiers, screen.modes) : '';
+            case 'button': {
+                if (event.down)
+                    this.buttons.add(event.button);
+                else
+                    this.buttons.delete(event.button);
+                if (screen.modes.mouseTracking === 'none' || (!event.down && screen.modes.mouseTracking === 'x10'))
+                    return '';
+                return mouse(event.button, event.x, event.y, event.modifiers, screen.modes, !event.down);
+            }
+            case 'pointer': {
+                const tracking = screen.modes.mouseTracking;
+                if (tracking !== 'any' && !(tracking === 'drag' && this.buttons.size))
+                    return '';
+                return mouse(32 + (this.buttons.values().next().value ?? 3), event.x, event.y, event.modifiers, screen.modes);
+            }
+        }
+    }
+}
+export function createTerminalInput(screen) {
+    const clients = new Map();
+    const encoder = (id) => { let value = clients.get(id); if (!value) {
+        value = new TerminalInputEncoder();
+        clients.set(id, value);
+    } return value; };
+    return {
+        input(event, clientId, context) { return encoder(clientId).encode(event, context); },
+        scroll(gesture, _clientId, context) {
+            if (!gesture.lines)
+                return '';
+            const state = screen.state();
+            if (context.modes.mouseTracking === 'x10')
+                return '';
+            if (context.modes.mouseTracking !== 'none')
+                return repeat(mouse(gesture.lines < 0 ? 64 : 65, gesture.x, gesture.y, gesture.modifiers, context.modes), Math.abs(gesture.lines));
+            if (state.buffer === 'normal')
+                return undefined;
+            if (!context.modes.alternateScroll)
+                return '';
+            return repeat(encodeKey(gesture.lines < 0 ? 82 : 81, gesture.modifiers, context.modes), Math.abs(gesture.lines));
+        },
+        release(clientId) { clients.get(clientId)?.release(); clients.delete(clientId); },
+        dispose() { clients.clear(); },
+    };
+}
+function repeat(bytes, count) {
+    if (!bytes)
+        return '';
+    if (count > Math.floor(TERMINAL_GRID_LIMITS.maxInputBytes / Buffer.byteLength(bytes)))
+        throw new KeeperMethodError('bad_request', 'Terminal input exceeds limit');
+    if (typeof bytes === 'string')
+        return bytes.repeat(count);
+    return Buffer.concat(Array.from({ length: count }, () => bytes));
+}
+function mouse(button, x, y, mask, modes, release = false) {
+    // The wire carries cells, so pixel encoding cannot be represented faithfully.
+    if (modes.mouseEncoding === 'sgr-pixels')
+        return '';
+    const mods = modes.mouseTracking === 'x10' ? 0 : (mask & 1 ? 4 : 0) + (mask & 2 ? 8 : 0) + (mask & 4 ? 16 : 0);
+    if (modes.mouseEncoding === 'sgr')
+        return `${esc}[<${button + mods};${x + 1};${y + 1}${release ? 'm' : 'M'}`;
+    const code = (release ? 3 : button) + mods + 32;
+    if (modes.mouseEncoding === 'urxvt')
+        return `${esc}[${code};${x + 1};${y + 1}M`;
+    if (modes.mouseEncoding === 'default' && (x > 222 || y > 222))
+        return '';
+    if (modes.mouseEncoding === 'default')
+        return Buffer.from([27, 91, 77, code, x + 33, y + 33]);
+    return `${esc}[M${String.fromCharCode(code, x + 33, y + 33)}`;
+}
+function encodeKey(usage, mask, modes) {
+    const mod = modifiers(mask);
+    if (arrows[usage])
+        return mod > 1 ? `${esc}[1;${mod}${arrows[usage]}` : `${esc}${modes.applicationCursor ? 'O' : '['}${arrows[usage]}`;
+    if (tilde[usage])
+        return `${esc}[${tilde[usage]}${mod > 1 ? `;${mod}` : ''}~`;
+    if (usage >= 58 && usage <= 61)
+        return mod > 1 ? `${esc}[1;${mod}${String.fromCharCode(80 + usage - 58)}` : `${esc}O${String.fromCharCode(80 + usage - 58)}`;
+    if (keypad[usage]) {
+        if (mask & 8 && usage !== 88)
+            return '';
+        return modes.applicationKeypad ? mod > 1 ? `${esc}[1;${mod}${keypad[usage][1]}` : `${esc}O${keypad[usage][1]}` : prefixed(keypad[usage][0], mask);
+    }
+    if (usage === 40)
+        return prefixed('\r', mask);
+    if (usage === 41)
+        return esc;
+    if (usage === 42)
+        return prefixed(mask & 4 ? '\b' : '\x7f', mask);
+    if (usage === 43)
+        return mask & 1 ? `${esc}[Z` : prefixed('\t', mask);
+    if (mask & 8)
+        return ''; // Native clients handle local Meta shortcuts.
+    let text = '';
+    if (usage >= 4 && usage <= 29)
+        text = String.fromCharCode((mask & 1 ? 65 : 97) + usage - 4);
+    else if (usage >= 30 && usage <= 39)
+        text = (mask & 1 ? '!@#$%^&*()' : '1234567890')[usage - 30];
+    else {
+        const punctuation = { 44: [' ', ' '], 45: ['-', '_'], 46: ['=', '+'], 47: ['[', '{'], 48: [']', '}'], 49: ['\\', '|'], 50: ['#', '~'], 51: [';', ':'], 52: ["'", '"'], 53: ['`', '~'], 54: [',', '<'], 55: ['.', '>'], 56: ['/', '?'] };
+        text = punctuation[usage]?.[mask & 1 ? 1 : 0] ?? '';
+    }
+    if (mask & 4) {
+        const upper = text.toUpperCase();
+        if (upper >= '@' && upper <= '_')
+            text = String.fromCharCode(upper.charCodeAt(0) - 64);
+        else if (text === ' ' || text === '2' || text === '`')
+            text = '\0';
+        else if (text === '3')
+            text = esc;
+        else if (text === '4')
+            text = '\x1c';
+        else if (text === '5')
+            text = '\x1d';
+        else if (text === '6')
+            text = '\x1e';
+        else if (text === '7' || text === '/')
+            text = '\x1f';
+        else if (text === '8' || text === '?')
+            text = '\x7f';
+    }
+    return prefixed(text, mask);
+}
+function prefixed(text, mask) { return text && mask & 2 ? esc + text : text; }

package/dist/workstation/keepers/terminal/keeper.js

@@ -1,8 +1,9 @@
-// keeper-terminal's methods on the kit server: `pty.*` over PtySessions, `exec.*` over ExecHost, plus their activity samplers.
+// keeper-terminal's methods on the kit server: `pty.*` over NativePtySessions, `exec.*` over ExecHost, plus their activity samplers.
 // Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
 import { constants, promises as fs } from 'node:fs';
 import { absolutePath, badRequest as bad, environment } from './params.js';
-import { CREATE_KEYS, PtySessions } from './pty.js';
+import { createRequire } from 'node:module';
+import { NativePtySessions, NATIVE_PTY_OPERATIONS } from './sessions.js';
 import { KeeperMethodError } from '../kit/protocol.js';
 import { EXEC_CAPABILITY, ExecErrorCode, PTY_CAPABILITY, execStream } from './protocol.js';
 /**
@@ -21,18 +22,31 @@ async function launchOf(p) {
         bad('Terminal shell is not an executable file');
     return { cwd, shell, env };
 }
-export const KEEPER_CREATE_KEYS = [...CREATE_KEYS, 'shell', 'env'];
+export const KEEPER_CREATE_KEYS = ['id', 'cwd', 'shell', 'env', 'registrationId'];
 export function createTerminalKeeper(options = {}) {
-    const sessions = new PtySessions(options);
+    let available = false;
+    const sessions = new NativePtySessions({ ...options, loadPty: () => {
+            const module = (options.loadPty ?? (() => createRequire(import.meta.url)('node-pty')))();
+            available = true;
+            return module;
+        } });
     const exec = options.exec;
     return {
         sessions,
         exec,
-        capabilities: [...(sessions.available ? [PTY_CAPABILITY] : []), ...(exec ? [EXEC_CAPABILITY] : [])],
+        capabilities: [...(available ? [PTY_CAPABILITY] : []), ...(exec ? [EXEC_CAPABILITY] : [])],
         install(server) {
-            server.register('pty.create', (params) => sessions.create(params, KEEPER_CREATE_KEYS, () => launchOf(params)), { startsWork: true });
-            server.register('pty.list', (params) => sessions.list(params));
-            for (const op of ['attach', 'poll', 'write', 'resize', 'takeover', 'detach', 'close'])
+            server.register('pty.create', (params) => {
+                if (Object.keys(params).some(key => !KEEPER_CREATE_KEYS.includes(key)))
+                    bad('Unexpected tool parameter');
+                return sessions.create({ id: params.id, ...(params.cwd !== undefined ? { cwd: params.cwd } : {}), ...(params.registrationId !== undefined ? { registrationId: params.registrationId } : {}) }, () => launchOf(params));
+            }, { startsWork: true });
+            server.register('pty.list', (params) => {
+                if (Object.keys(params).length)
+                    bad('Unexpected tool parameter');
+                return sessions.list();
+            });
+            for (const op of NATIVE_PTY_OPERATIONS)
                 server.register(`pty.${op}`, (params) => sessions.operate(op, params));
             server.addActivitySampler(() => sessions.activity());
             if (!exec)

package/dist/workstation/keepers/terminal/main.js

@@ -8,7 +8,7 @@ import path, { sep } from 'node:path';
 import { runKeeperMain } from '../kit/bootstrap.js';
 import { ExecHost } from './exec.js';
 import { createTerminalKeeper } from './keeper.js';
-export const protocolVersion = 1;
+export const protocolVersion = 2;
 /**
  * node-pty from the bundle snapshot's own `node_modules` (copied next to keeper.mjs), never one found further up the
  * directory tree: the snapshot is what the build hashed. Missing or foreign → PTYs unavailable (`pty` capability absent).

package/dist/workstation/keepers/terminal/metadata.js

@@ -0,0 +1,138 @@
+import { execFile } from 'node:child_process';
+import { readlink } from 'node:fs/promises';
+import { hostname as localHostname } from 'node:os';
+import path from 'node:path';
+const clean = (value) => [...value.replace(/[\x00-\x1f\x7f-\x9f]/g, '').trim()].slice(0, 256).join('');
+const validCwd = (value) => value.startsWith('/') && !/[\x00-\x1f\x7f-\x9f]/.test(value);
+/** Resolved display metadata; native xterm hooks are the only OSC parser. */
+export class TerminalMetadata {
+    options;
+    cwd;
+    cwdSource = 'launch';
+    explicitTitle = '';
+    listeners;
+    now;
+    hostname;
+    lastLookup = -Infinity;
+    oscRevision = 0;
+    closed = false;
+    pending;
+    cancelLookup;
+    timer;
+    constructor(options) {
+        this.options = options;
+        this.cwd = options.cwd;
+        this.now = options.now ?? Date.now;
+        this.hostname = (options.hostname ?? localHostname()).toLowerCase();
+        this.listeners = [options.screen.onTitleChange(title => {
+                if (this.closed)
+                    return;
+                const previous = this.title;
+                this.explicitTitle = clean(title);
+                if (this.title !== previous)
+                    options.changed();
+            }), options.screen.onCwdChange(uri => this.osc7(uri))];
+    }
+    get title() { return this.explicitTitle || clean(path.posix.basename(this.cwd) || this.cwd) || 'Terminal'; }
+    read() { return { title: this.title, cwd: this.cwd, cwdSource: this.cwdSource }; }
+    /** Called once by the host factory, independently of output and attachments. */
+    start() {
+        if (this.closed || this.timer)
+            return;
+        void this.refresh();
+        this.timer = setInterval(() => { void this.refresh(); }, 2000);
+        this.timer.unref();
+    }
+    refresh() {
+        if (this.closed || this.options.live?.() === false)
+            return Promise.resolve();
+        if (this.pending)
+            return this.pending;
+        if (this.now() - this.lastLookup < 2000)
+            return Promise.resolve();
+        this.lastLookup = this.now();
+        const revision = this.oscRevision;
+        let timeout;
+        const bounded = new Promise(resolve => {
+            timeout = setTimeout(() => resolve(null), 1000);
+            this.cancelLookup = () => resolve(null);
+            // Normalize synchronous failures too; no failed lookup invalidates the last cwd.
+            try {
+                void (this.options.lookup ?? lookupProcessCwd)(this.options.pid).then(resolve, () => resolve(null));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        this.pending = bounded.then(cwd => {
+            if (!this.closed && this.options.live?.() !== false && revision === this.oscRevision && cwd && validCwd(cwd))
+                this.updateCwd(cwd, 'process');
+        }).finally(() => { clearTimeout(timeout); this.cancelLookup = undefined; this.pending = undefined; });
+        return this.pending;
+    }
+    dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        clearInterval(this.timer);
+        this.timer = undefined;
+        this.cancelLookup?.();
+        for (const listener of this.listeners)
+            listener.dispose();
+    }
+    osc7(uri) {
+        if (this.closed)
+            return;
+        try {
+            if (/[\x00-\x1f\x7f-\x9f]/.test(uri))
+                return;
+            const url = new URL(uri);
+            if (url.protocol !== 'file:' || url.username || url.password || url.port || uri.includes('?') || uri.includes('#'))
+                return;
+            const host = url.hostname.toLowerCase();
+            if (host && host !== 'localhost' && host !== this.hostname)
+                return;
+            const cwd = decodeURIComponent(url.pathname);
+            if (!validCwd(cwd))
+                return;
+            this.oscRevision++;
+            this.updateCwd(cwd, 'osc7');
+        }
+        catch { /* malformed/untrusted OSC payload is data, never executable */ }
+    }
+    updateCwd(cwd, source) {
+        if (cwd === this.cwd && source === this.cwdSource)
+            return;
+        this.cwd = cwd;
+        this.cwdSource = source;
+        this.options.changed();
+    }
+}
+/** No shell interpolation: lsof receives the shell pid only as an argv element. */
+export async function lookupProcessCwd(pid, platform = process.platform) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    if (platform === 'linux') {
+        try {
+            return await readlink(`/proc/${pid}/cwd`);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (platform !== 'darwin')
+        return null;
+    return new Promise(resolve => {
+        execFile('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { timeout: 1000, maxBuffer: 64 * 1024 }, (error, stdout) => {
+            resolve(error ? null : stdout.split('\n').find(line => line.startsWith('n/'))?.slice(1) ?? null);
+        });
+    });
+}
+export function createTerminalMetadata(context) {
+    // Capture initial values before installing metadata; read() must never call session().
+    const initial = context.session();
+    const metadata = new TerminalMetadata({ screen: context.screen, cwd: initial.cwd, pid: context.pty.pid,
+        changed: context.changed, live: () => !context.session().exited });
+    metadata.start();
+    return metadata;
+}

package/dist/workstation/keepers/terminal/protocol.js

@@ -1,32 +1,8 @@
-// keeper-terminal's wire vocabulary, shared by the keeper (`main.ts`, `pty.ts`) and the daemon (`client.ts`).
-// Keeper-side module: node builtins and kit siblings only (the import guard enforces it). Spec §4.1.
-/** The keeper protocol this code speaks. `main.ts` declares the same number for the bundler (a test keeps them equal). */
-export const TERMINAL_PROTOCOL_VERSION = 1;
-/** `keeper.hello` capability: node-pty loaded from the bundle snapshot, so `pty.*` works. Absent = PTYs unavailable. */
-export const PTY_CAPABILITY = 'pty';
-/** The legacy keeper's wording (tools/terminal.ts at the merge-base) when node-pty does not load; every `pty.*` call but `pty.list` answers it. */
+// Terminal transport is a direct native-grid protocol replacement. Durable exec vocabulary follows.
+export const TERMINAL_PROTOCOL_VERSION = 2;
+export const PTY_CAPABILITY = 'pty-grid-v1';
 export const PTY_UNAVAILABLE_ERROR = 'Terminal native dependency unavailable; reinstall CLI with optional node-pty support';
-/** Ring of rendered output kept per session, the largest poll delta, the scrollback serialised into a snapshot. */
-export const PTY_HISTORY_BYTES = 1024 * 1024;
-export const PTY_MAX_POLL_BYTES = 64 * 1024;
-export const PTY_SCROLLBACK = 1000;
-/** A snapshot must fit one tool result (2 MiB, the same as keeper-terminal's outbound frame cap). */
-export const PTY_RESULT_BYTES = 2 * 1024 * 1024;
-export const PTY_SESSION_LIMIT = 8;
-export const PTY_INPUT_BYTES = 64 * 1024;
-/** Longest activity label (the foreground process basename; never its arguments). */
-export const PTY_LABEL_CHARS = 64;
-export const PTY_METHODS = ['pty.create', 'pty.attach', 'pty.poll', 'pty.write', 'pty.resize', 'pty.takeover', 'pty.detach', 'pty.close', 'pty.list'];
-/** Typed error codes of `pty.*` (the message keeps today's `terminal.*` wording). */
-export const PtyErrorCode = {
-    unavailable: 'pty_unavailable',
-    badRequest: 'bad_request',
-    notFound: 'pty_not_found',
-    notController: 'pty_not_controller',
-    limit: 'pty_limit',
-    exited: 'pty_exited',
-    snapshotTooLarge: 'pty_snapshot_too_large',
-};
+export const PTY_METHODS = ['pty.list', 'pty.create', 'pty.attach', 'pty.poll', 'pty.resize', 'pty.input', 'pty.scroll', 'pty.detach', 'pty.close'];
 // ---- exec (spec §4.2): non-interactive commands with durable per-exec output logs ----------------------------------
 /** `keeper.hello` capability: `exec.*` is served. */
 export const EXEC_CAPABILITY = 'exec';