+3

CHANGELOG.md

Reviewed

··· 2 2 3 3 ## Unreleased 4 4 5 5 + ### Send 6 6 + - Add `pty send --paste` (and `paste: true` on `SendOptions` / `SendDataOptions`) to wrap the entire payload in bracketed-paste markers (CSI 200 ~ … CSI 201 ~). The receiving TUI treats everything between the markers as one paste event rather than a sequence of keystrokes — intended for injecting multi-line prompts into agent sessions (claude, aider, etc.) without premature submission when the payload contains newlines. Works with positional text, `--seq` sequences, and composes with `--with-delay`. Flag position-independent. 7 7 + 5 8 ### Client API 6 9 - Add `env?: Record<string, string>` to `SpawnDaemonOptions` and `ServerOptions` — use this to spawn a session child with a verbatim environment (no inheritance from the daemon's `process.env`, no allow-list). `PTY_SESSION` is always injected on top so nesting detection and `pty exec` keep working. Mutually exclusive with `isolateEnv` / `extraEnv` (throws at daemon startup if both are passed). Requested by the pty-layout dev to spawn a launcher shell with a shim `tmux` on `PATH`, a custom `TMUX` marker, and a filter-tag env var. 7 10 - Add `PtyHandle.readWrappedFlags(scrollOffset?): boolean[]` — per-row flags aligned with `readCells`, where `true` means the row continues the previous row because xterm wrapped a long line (not because the child emitted `\n`). Intended for consumers reconstructing logical lines from a visually-multi-row text selection (e.g., copying a wrapped URL to the clipboard without a spurious newline). Passes through xterm.js's `IBufferLine.isWrapped`; works for both `createPty` embedded terminals and `attachPty` remote sessions since the serialize/replay path preserves wrap state.

+1

README.md

Reviewed

··· 84 84 pty send myserver $'hello\n' # send text with newline (shell syntax) 85 85 pty send myserver --seq "git status" --seq key:return # ordered sequence 86 86 pty send myserver --seq key:ctrl+c # send control keys 87 87 + pty send myserver --paste "$(cat prompt.md)" # wrap as bracketed paste 87 88 88 89 pty stats # live metrics for all sessions 89 90 pty stats myserver # stats for a specific session

+14 -1

src/cli.ts

Reviewed

··· 75 75 pty send <name> "text" Send text to a session 76 76 pty send <name> --seq "text" --seq key:return Send an ordered sequence 77 77 pty send <name> --with-delay 0.5 --seq ... Delay between each --seq item 78 78 + pty send <name> --paste "<big text>" Wrap payload in bracketed-paste markers 78 79 pty restart <name> Restart a session (prompts if running) 79 80 pty restart -y <name> Restart without confirmation 80 81 pty events <name> Follow events from a session ··· 410 411 } 411 412 412 413 let sendArgs = args.slice(2); 414 414 + // --paste can appear anywhere; pull it out before the rest of the 415 415 + // parsing so its position relative to --seq / text doesn't matter. 416 416 + let paste = false; 417 417 + sendArgs = sendArgs.filter((a) => { 418 418 + if (a === "--paste") { paste = true; return false; } 419 419 + return true; 420 420 + }); 413 421 let delaySecs: number | undefined; 414 422 if (sendArgs[0] === "--with-delay") { 415 423 sendArgs = sendArgs.slice(1); ··· 454 462 } 455 463 456 464 const resolvedSendName = await resolveRef(sendName); 457 457 - send({ name: resolvedSendName, data, delayMs: delaySecs != null ? delaySecs * 1000 : undefined }); 465 465 + send({ 466 466 + name: resolvedSendName, 467 467 + data, 468 468 + delayMs: delaySecs != null ? delaySecs * 1000 : undefined, 469 469 + ...(paste ? { paste: true } : {}), 470 470 + }); 458 471 break; 459 472 } 460 473

+15

src/client.ts

Reviewed

··· 13 13 } from "./protocol.ts"; 14 14 import { getSocketPath } from "./sessions.ts"; 15 15 import { stripAnsi } from "./tui/colors.ts"; 16 16 + import { BRACKETED_PASTE_START, BRACKETED_PASTE_END } from "./paste.ts"; 16 17 17 18 const DETACH_KEY = 0x1c; // Ctrl+\ (legacy encoding) 18 19 const DETACH_KEY_KITTY = "\x1b[92;5u"; // Ctrl+\ (Kitty keyboard protocol) ··· 160 161 name: string; 161 162 data: string[]; 162 163 delayMs?: number; 164 164 + /** Wrap the entire payload (all `data` entries taken together) in 165 165 + * bracketed-paste markers (CSI 200 ~ … CSI 201 ~). The receiving TUI 166 166 + * treats everything between the markers as one paste event rather 167 167 + * than a sequence of keystrokes — useful for injecting multi-line 168 168 + * prompts into agent sessions without premature submission. Receiver 169 169 + * must have bracketed paste enabled (DECSET 2004); most modern 170 170 + * shells and TUIs do by default. */ 171 171 + paste?: boolean; 163 172 } 164 173 165 174 /** Send data to a session without attaching. Silent on success. */ ··· 168 177 const socket = net.createConnection(socketPath); 169 178 170 179 socket.on("connect", async () => { 180 180 + if (options.paste && options.data.length > 0) { 181 181 + socket.write(encodeData(BRACKETED_PASTE_START)); 182 182 + } 171 183 for (let i = 0; i < options.data.length; i++) { 172 184 if (i > 0 && options.delayMs) { 173 185 await new Promise((resolve) => setTimeout(resolve, options.delayMs)); 174 186 } 175 187 socket.write(encodeData(options.data[i])); 188 188 + } 189 189 + if (options.paste && options.data.length > 0) { 190 190 + socket.write(encodeData(BRACKETED_PASTE_END)); 176 191 } 177 192 socket.end(); 178 193 });

+15

src/connection.ts

Reviewed

··· 12 12 } from "./protocol.ts"; 13 13 import { getSocketPath } from "./sessions.ts"; 14 14 import { resolveKey } from "./keys.ts"; 15 15 + import { BRACKETED_PASTE_START, BRACKETED_PASTE_END } from "./paste.ts"; 15 16 16 17 export interface SessionConnectionOptions { 17 18 name: string; ··· 23 24 name: string; 24 25 data: string[]; 25 26 delayMs?: number; 27 27 + /** Wrap the entire payload (all `data` entries taken together) in 28 28 + * bracketed-paste markers (CSI 200 ~ … CSI 201 ~). The receiving TUI 29 29 + * treats everything between the markers as one paste event rather 30 30 + * than a sequence of keystrokes — useful for injecting multi-line 31 31 + * prompts into agent sessions without premature submission. Receiver 32 32 + * must have bracketed paste enabled (DECSET 2004); most modern 33 33 + * shells and TUIs do by default. */ 34 34 + paste?: boolean; 26 35 } 27 36 28 37 export interface PeekScreenOptions { ··· 157 166 const socket = net.createConnection(socketPath); 158 167 159 168 socket.on("connect", async () => { 169 169 + if (options.paste && options.data.length > 0) { 170 170 + socket.write(encodeData(BRACKETED_PASTE_START)); 171 171 + } 160 172 for (let i = 0; i < options.data.length; i++) { 161 173 if (i > 0 && options.delayMs) { 162 174 await new Promise((r) => setTimeout(r, options.delayMs)); 163 175 } 164 176 socket.write(encodeData(options.data[i])); 177 177 + } 178 178 + if (options.paste && options.data.length > 0) { 179 179 + socket.write(encodeData(BRACKETED_PASTE_END)); 165 180 } 166 181 socket.end(); 167 182 });

+16

src/paste.ts

Reviewed

··· 1 1 + // Bracketed paste (DECSET 2004) helpers. 2 2 + // 3 3 + // When a receiving terminal has bracketed paste mode enabled, pasted 4 4 + // text is wrapped in these markers so applications can distinguish 5 5 + // "user typed this" from "user pasted this". Shells suppress 6 6 + // history/autocomplete during paste, vim enters paste mode, and TUI 7 7 + // agents (claude, aider) treat the block as one input event rather 8 8 + // than a sequence of keystrokes. 9 9 + // 10 10 + // `send --paste` wraps the entire payload in START…END so multi-line 11 11 + // prompts injected into agent sessions don't get submitted partway. 12 12 + 13 13 + /** Sent BEFORE pasted content. CSI 200 ~. */ 14 14 + export const BRACKETED_PASTE_START = "\x1b[200~"; 15 15 + /** Sent AFTER pasted content. CSI 201 ~. */ 16 16 + export const BRACKETED_PASTE_END = "\x1b[201~";

+88 -1

tests/connection.test.ts

Reviewed

··· 208 208 const dir = makeSessionDir(); 209 209 const name = uniqueName(); 210 210 process.env.PTY_SESSION_DIR = dir; 211 211 - await startDaemon(dir, name, "cat"); 211 211 + // `stty raw -echo` lets the ESC markers appear verbatim in the 212 212 + // buffer instead of being munged to `^[` by ECHOCTL. 213 213 + await startDaemon(dir, name, "sh", ["-c", "stty raw -echo; cat"]); 214 214 + await new Promise((r) => setTimeout(r, 150)); 212 215 213 216 await sendData({ name, data: ["hello-send"] }); 214 217 ··· 225 228 await expect( 226 229 sendData({ name: "nonexistent", data: ["test"] }) 227 230 ).rejects.toThrow("not found or not running"); 231 231 + }, 15000); 232 232 + 233 233 + // xterm-headless parses bracketed-paste START/END as valid CSI 234 234 + // sequences and absorbs them — they don't appear in the rendered 235 235 + // buffer. To verify the raw bytes that reach the child, we use a 236 236 + // child that dumps its stdin to a file and then read the file. 237 237 + // `stty raw -echo` keeps line discipline from munging control bytes. 238 238 + async function startDumper(dir: string, name: string, dumpFile: string) { 239 239 + await startDaemon(dir, name, "sh", [ 240 240 + "-c", 241 241 + `stty raw -echo; cat > ${JSON.stringify(dumpFile)}`, 242 242 + ]); 243 243 + await new Promise((r) => setTimeout(r, 150)); 244 244 + } 245 245 + 246 246 + async function waitForDump(dumpFile: string, minBytes: number, timeoutMs: number): Promise<Buffer> { 247 247 + const start = Date.now(); 248 248 + while (Date.now() - start < timeoutMs) { 249 249 + try { 250 250 + const buf = fs.readFileSync(dumpFile); 251 251 + if (buf.length >= minBytes) return buf; 252 252 + } catch {} 253 253 + await new Promise((r) => setTimeout(r, 50)); 254 254 + } 255 255 + return fs.existsSync(dumpFile) ? fs.readFileSync(dumpFile) : Buffer.alloc(0); 256 256 + } 257 257 + 258 258 + it("paste:true wraps the payload in bracketed-paste markers", async () => { 259 259 + const dir = makeSessionDir(); 260 260 + const name = uniqueName(); 261 261 + process.env.PTY_SESSION_DIR = dir; 262 262 + const dump = path.join(dir, "dump.bin"); 263 263 + await startDumper(dir, name, dump); 264 264 + 265 265 + await sendData({ name, data: ["hello-paste"], paste: true }); 266 266 + const received = await waitForDump(dump, "hello-paste".length + 12, 3000); 267 267 + const text = received.toString("utf-8"); 268 268 + expect(text).toBe("\x1b[200~hello-paste\x1b[201~"); 269 269 + }, 15000); 270 270 + 271 271 + it("paste:true wraps a multi-item payload as one bracket pair (not per item)", async () => { 272 272 + const dir = makeSessionDir(); 273 273 + const name = uniqueName(); 274 274 + process.env.PTY_SESSION_DIR = dir; 275 275 + const dump = path.join(dir, "dump.bin"); 276 276 + await startDumper(dir, name, dump); 277 277 + 278 278 + await sendData({ name, data: ["line1\n", "line2\n", "line3"], paste: true }); 279 279 + const expected = "\x1b[200~line1\nline2\nline3\x1b[201~"; 280 280 + const received = await waitForDump(dump, expected.length, 3000); 281 281 + const text = received.toString("utf-8"); 282 282 + expect((text.match(/\x1b\[200~/g) ?? []).length).toBe(1); 283 283 + expect((text.match(/\x1b\[201~/g) ?? []).length).toBe(1); 284 284 + expect(text).toBe(expected); 285 285 + }, 15000); 286 286 + 287 287 + it("paste:false (default) does not add bracketed-paste markers", async () => { 288 288 + const dir = makeSessionDir(); 289 289 + const name = uniqueName(); 290 290 + process.env.PTY_SESSION_DIR = dir; 291 291 + const dump = path.join(dir, "dump.bin"); 292 292 + await startDumper(dir, name, dump); 293 293 + 294 294 + await sendData({ name, data: ["no-paste"] }); 295 295 + const received = await waitForDump(dump, "no-paste".length, 3000); 296 296 + expect(received.toString("utf-8")).toBe("no-paste"); 297 297 + expect(received.toString("utf-8")).not.toContain("\x1b[200~"); 298 298 + expect(received.toString("utf-8")).not.toContain("\x1b[201~"); 299 299 + }, 15000); 300 300 + 301 301 + it("paste:true on an empty data array does not emit markers alone", async () => { 302 302 + const dir = makeSessionDir(); 303 303 + const name = uniqueName(); 304 304 + process.env.PTY_SESSION_DIR = dir; 305 305 + const dump = path.join(dir, "dump.bin"); 306 306 + await startDumper(dir, name, dump); 307 307 + 308 308 + // No content → no markers. (Sending nothing shouldn't write a bare 309 309 + // START/END pair to the session.) 310 310 + await sendData({ name, data: [], paste: true }); 311 311 + await new Promise((r) => setTimeout(r, 300)); 312 312 + 313 313 + const received = fs.existsSync(dump) ? fs.readFileSync(dump) : Buffer.alloc(0); 314 314 + expect(received.length).toBe(0); 228 315 }, 15000); 229 316 }); 230 317

+219

tests/send-paste.test.ts

Reviewed

··· 1 1 + // CLI-surface tests for `pty send --paste`. Exercises the binary via 2 2 + // spawnSync so the argv-parsing path is covered end-to-end, including 3 3 + // the `--paste` flag's position-independence (before/after --seq, with 4 4 + // --with-delay, etc.). 5 5 + 6 6 + import { describe, it, expect, afterEach, afterAll } from "vitest"; 7 7 + import * as fs from "node:fs"; 8 8 + import * as os from "node:os"; 9 9 + import * as path from "node:path"; 10 10 + import { fileURLToPath } from "node:url"; 11 11 + import { spawn, spawnSync } from "node:child_process"; 12 12 + 13 13 + const __dirname = path.dirname(fileURLToPath(import.meta.url)); 14 14 + const nodeBin = process.execPath; 15 15 + const cliPath = path.join(__dirname, "..", "dist", "cli.js"); 16 16 + const serverModule = path.join(__dirname, "..", "dist", "server.js"); 17 17 + 18 18 + const testRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pty-paste-")); 19 19 + afterAll(() => { 20 20 + fs.rmSync(testRoot, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); 21 21 + }); 22 22 + 23 23 + let bgPids: number[] = []; 24 24 + let sessionDirs: string[] = []; 25 25 + 26 26 + function makeSessionDir(): string { 27 27 + const dir = fs.mkdtempSync(path.join(testRoot, "d-")); 28 28 + sessionDirs.push(dir); 29 29 + return dir; 30 30 + } 31 31 + 32 32 + let nameCounter = 0; 33 33 + function uniqueName(): string { 34 34 + return `sp${++nameCounter}${Math.random().toString(36).slice(2, 5)}`; 35 35 + } 36 36 + 37 37 + async function startDaemon( 38 38 + sessionDir: string, 39 39 + name: string, 40 40 + command: string, 41 41 + args: string[] = [], 42 42 + ): Promise<number> { 43 43 + const config = JSON.stringify({ 44 44 + name, command, args, displayCommand: command, 45 45 + cwd: os.tmpdir(), rows: 24, cols: 80, 46 46 + }); 47 47 + const child = spawn(nodeBin, [serverModule], { 48 48 + detached: true, 49 49 + stdio: ["ignore", "ignore", "pipe"], 50 50 + env: { ...process.env, PTY_SERVER_CONFIG: config, PTY_SESSION_DIR: sessionDir }, 51 51 + }); 52 52 + let stderr = ""; 53 53 + child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); }); 54 54 + let exitCode: number | null = null; 55 55 + child.on("exit", (code) => { exitCode = code; }); 56 56 + (child.stderr as any)?.unref?.(); 57 57 + child.unref(); 58 58 + 59 59 + const socketPath = path.join(sessionDir, `${name}.sock`); 60 60 + const start = Date.now(); 61 61 + while (Date.now() - start < 5000) { 62 62 + if (exitCode !== null) throw new Error(`Daemon exited: ${stderr}`); 63 63 + try { 64 64 + fs.statSync(socketPath); 65 65 + await new Promise((r) => setTimeout(r, 100)); 66 66 + bgPids.push(child.pid!); 67 67 + return child.pid!; 68 68 + } catch {} 69 69 + await new Promise((r) => setTimeout(r, 50)); 70 70 + } 71 71 + throw new Error(`Timeout waiting for daemon`); 72 72 + } 73 73 + 74 74 + function runCli(sessionDir: string, ...args: string[]) { 75 75 + return spawnSync(nodeBin, [cliPath, ...args], { 76 76 + cwd: os.tmpdir(), 77 77 + env: { ...process.env, PTY_SESSION_DIR: sessionDir }, 78 78 + encoding: "utf-8", 79 79 + timeout: 10_000, 80 80 + }); 81 81 + } 82 82 + 83 83 + /** Run a dump-to-file child in the session so we can read the raw bytes 84 84 + * the `send` write produced — xterm-headless interprets bracketed-paste 85 85 + * START/END as valid CSI sequences and absorbs them, so peeking the 86 86 + * screen wouldn't show the markers. `stty raw -echo` keeps the PTY line 87 87 + * discipline from munging or echoing the ESC bytes. */ 88 88 + async function startDumpSession(sessionDir: string, name: string, dumpFile: string) { 89 89 + await startDaemon(sessionDir, name, "sh", [ 90 90 + "-c", 91 91 + `stty raw -echo; cat > ${JSON.stringify(dumpFile)}`, 92 92 + ]); 93 93 + await new Promise((r) => setTimeout(r, 150)); 94 94 + } 95 95 + 96 96 + async function waitForDump(dumpFile: string, minBytes: number, timeoutMs: number): Promise<string> { 97 97 + const start = Date.now(); 98 98 + while (Date.now() - start < timeoutMs) { 99 99 + try { 100 100 + const buf = fs.readFileSync(dumpFile); 101 101 + if (buf.length >= minBytes) return buf.toString("utf-8"); 102 102 + } catch {} 103 103 + await new Promise((r) => setTimeout(r, 50)); 104 104 + } 105 105 + return fs.existsSync(dumpFile) ? fs.readFileSync(dumpFile).toString("utf-8") : ""; 106 106 + } 107 107 + 108 108 + afterEach(() => { 109 109 + for (const pid of bgPids) { try { process.kill(pid, "SIGTERM"); } catch {} } 110 110 + bgPids = []; 111 111 + for (const dir of sessionDirs) { 112 112 + try { 113 113 + for (const e of fs.readdirSync(dir)) { try { fs.unlinkSync(path.join(dir, e)); } catch {} } 114 114 + } catch {} 115 115 + } 116 116 + sessionDirs = []; 117 117 + }); 118 118 + 119 119 + describe("pty send --paste", () => { 120 120 + it("wraps positional text in bracketed-paste markers", async () => { 121 121 + const dir = makeSessionDir(); 122 122 + const name = uniqueName(); 123 123 + const dump = path.join(dir, "dump.bin"); 124 124 + await startDumpSession(dir, name, dump); 125 125 + 126 126 + const r = runCli(dir, "send", name, "--paste", "hello-paste"); 127 127 + expect(r.status).toBe(0); 128 128 + 129 129 + const received = await waitForDump(dump, "hello-paste".length + 12, 3000); 130 130 + expect(received).toBe("\x1b[200~hello-paste\x1b[201~"); 131 131 + }, 15_000); 132 132 + 133 133 + it("works with --paste placed AFTER the text (filter extracts it regardless)", async () => { 134 134 + const dir = makeSessionDir(); 135 135 + const name = uniqueName(); 136 136 + const dump = path.join(dir, "dump.bin"); 137 137 + await startDumpSession(dir, name, dump); 138 138 + 139 139 + const r = runCli(dir, "send", name, "post-paste", "--paste"); 140 140 + expect(r.status).toBe(0); 141 141 + 142 142 + const received = await waitForDump(dump, "post-paste".length + 12, 3000); 143 143 + expect(received).toBe("\x1b[200~post-paste\x1b[201~"); 144 144 + }, 15_000); 145 145 + 146 146 + it("wraps an ordered --seq payload as a single paste", async () => { 147 147 + const dir = makeSessionDir(); 148 148 + const name = uniqueName(); 149 149 + const dump = path.join(dir, "dump.bin"); 150 150 + await startDumpSession(dir, name, dump); 151 151 + 152 152 + const r = runCli( 153 153 + dir, "send", name, "--paste", 154 154 + "--seq", "first ", 155 155 + "--seq", "second ", 156 156 + "--seq", "third", 157 157 + ); 158 158 + expect(r.status).toBe(0); 159 159 + 160 160 + const expected = "\x1b[200~first second third\x1b[201~"; 161 161 + const received = await waitForDump(dump, expected.length, 3000); 162 162 + expect((received.match(/\x1b\[200~/g) ?? []).length).toBe(1); 163 163 + expect((received.match(/\x1b\[201~/g) ?? []).length).toBe(1); 164 164 + expect(received).toBe(expected); 165 165 + }, 15_000); 166 166 + 167 167 + it("composes with --with-delay", async () => { 168 168 + const dir = makeSessionDir(); 169 169 + const name = uniqueName(); 170 170 + const dump = path.join(dir, "dump.bin"); 171 171 + await startDumpSession(dir, name, dump); 172 172 + 173 173 + const r = runCli( 174 174 + dir, "send", name, "--with-delay", "0.05", "--paste", 175 175 + "--seq", "A", 176 176 + "--seq", "B", 177 177 + ); 178 178 + expect(r.status).toBe(0); 179 179 + 180 180 + const expected = "\x1b[200~AB\x1b[201~"; 181 181 + const received = await waitForDump(dump, expected.length, 3000); 182 182 + expect((received.match(/\x1b\[200~/g) ?? []).length).toBe(1); 183 183 + expect((received.match(/\x1b\[201~/g) ?? []).length).toBe(1); 184 184 + expect(received).toBe(expected); 185 185 + }, 15_000); 186 186 + 187 187 + it("without --paste, no bracketed-paste markers are emitted (control)", async () => { 188 188 + const dir = makeSessionDir(); 189 189 + const name = uniqueName(); 190 190 + const dump = path.join(dir, "dump.bin"); 191 191 + await startDumpSession(dir, name, dump); 192 192 + 193 193 + const r = runCli(dir, "send", name, "plain-text"); 194 194 + expect(r.status).toBe(0); 195 195 + 196 196 + const received = await waitForDump(dump, "plain-text".length, 3000); 197 197 + expect(received).toBe("plain-text"); 198 198 + expect(received).not.toContain("\x1b[200~"); 199 199 + expect(received).not.toContain("\x1b[201~"); 200 200 + }, 15_000); 201 201 + 202 202 + it("handles multi-line payload inside one paste event", async () => { 203 203 + const dir = makeSessionDir(); 204 204 + const name = uniqueName(); 205 205 + const dump = path.join(dir, "dump.bin"); 206 206 + await startDumpSession(dir, name, dump); 207 207 + 208 208 + // A newline inside the paste is preserved as a literal byte between 209 209 + // the markers; the receiver treats the whole thing as one paste. 210 210 + const r = runCli(dir, "send", name, "--paste", "line-one\nline-two\n"); 211 211 + expect(r.status).toBe(0); 212 212 + 213 213 + const expected = "\x1b[200~line-one\nline-two\n\x1b[201~"; 214 214 + const received = await waitForDump(dump, expected.length, 3000); 215 215 + expect(received).toBe(expected); 216 216 + expect((received.match(/\x1b\[200~/g) ?? []).length).toBe(1); 217 217 + expect((received.match(/\x1b\[201~/g) ?? []).length).toBe(1); 218 218 + }, 15_000); 219 219 + });