@hydraharness/harness-terminal-bash 0.0.0-stage → 0.1.1-rc.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @hydraharness/harness-terminal-bash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Persistent shell backend for `ctx.terminals` over `ctx.subprocess.spawnTerminal`. It starts an interactive shell under the shared `ctx.sandboxPolicy`, retains bounded line-oriented output, and detects readiness while the subprocess provider owns PTY allocation, environment scrubbing, foreground process groups, signalling, and complete terminal-session cleanup. The same PTY backend therefore composes with local or remote execution-world providers.
+
+## Plugin (`terminal-bash`)
+
+The plugin injects `pty`, `sandboxPolicy`, and `subprocess`, then registers the configured backend type (`shell`). `danger-full-access` starts the shell directly without requiring a sandbox provider; confined modes require a same-world `ctx.sandbox` and wrap the exact shell argv through it, failing before spawn when none is mounted. At spawn, one `ctx.sandboxPolicy.resolve({ session })` call supplies both the effective mode and the session workspace root; the same root is the default shell cwd when the caller omits one. A change to a different effective mode is rejected before its `sandbox/mode` event commits while that owner has an open PTY or a spawn in progress; the fence is attached to the exact owner and therefore outlives a provider reload that retains existing sessions. Wait for creation to settle and close the sessions before changing modes, so a terminal opened with wider access cannot survive a downgrade.
+
+`shellDialect` selects the shell stack (`bash` default, `pwsh`): it picks the default `shellPath`/`shellArgs` (bash `--noprofile --norc -i`; pwsh `-NoLogo -NoProfile` through the shared `@hydraharness/harness-pwsh-local` resolver) and the startup contract. The bash dialect installs its prompt through the environment (`PS1` plus an OSC `133;D;`-terminated `PROMPT_COMMAND`). pwsh cannot install a prompt from the environment, so the backend writes a `prompt` function through the session and waits until the controlled prompt is actually visible — looping over follow-up sends because the pwsh banner-to-prompt gap can outlast the silence bound — while its environment drops the bash-only markers and adds `NO_COLOR`. That first send also prefixes the shared `@hydraharness/harness-pwsh-local` encoding preamble, pinning `[Console]::OutputEncoding` and `$OutputEncoding` to UTF-8 before anything runs: the session decode path reads PTY bytes as UTF-8, and an un-pinned console writes its host code page for non-ASCII output. Both dialects emit the same BEL-terminated OSC marker, so the readiness machinery and consumers are dialect-agnostic.
+
+The pwsh bootstrap is submitted once, including when the first read returns no output. On POSIX, PSReadLine's initial cursor-position query is answered before that first write, including queries split across output chunks. Cancellation, timeout, or closure while waiting prevents the bootstrap write. Startup requires the controlled prompt at the end of the viewport or retained scrollback; the prompt string inside an echoed setup command is insufficient.
+
+Readiness combines a foreground-verified private bash prompt marker, provider-reported foreground stdin-wait facts, silence fallback, and absolute timeout. A marker is not ready until the printable tail after the latest owned marker exactly equals the controlled `PS1`, including when the OSC marker and prompt are split across data callbacks; echoed input or output following an earlier prompt therefore cannot settle the current send. The controlled `PROMPT_COMMAND` re-asserts that `PS1` before every prompt, so an in-shell prompt override cannot degrade later sends to silence readiness. Prompt and silence evidence collected before the provider write, including while pre-write foreground inspection is pending, is discarded at the write boundary. When bash prints the marker before the terminal provider publishes its return to the foreground process group, polling retains the candidate for `handoffGraceMs` past the ordinary silence bound so a coincident handoff can win. An interactive child that inherits `PROMPT_COMMAND` therefore cannot suppress inferred-idle readiness until the absolute timeout. Unknown foreground state is never a positive exact-idle signal. A foreground group's stdin wait that existed before a send is likewise not post-write readiness: the same group must be observed outside that wait before a later wait can settle the send, while a changed foreground group is new evidence. During unpublished startup, a fallback requires observed output; zero-output silence cannot publish an empty session, and timeout rejects the spawn. Cancellation closes the unpublished shell and rejects with the caller's exact abort reason; `TerminalBackendCleanupError` separately preserves a cleanup failure. The caller's signal is forwarded for terminal allocation and readiness initialization; after publication the handle owns its lifetime. Incomplete terminal-control sequences are bounded by `maxReadBytes` and discarded through their terminator after crossing that limit; malformed UTF-8 terminal output uses replacement characters, and a trailing carriage return is carried across callbacks so split CRLF becomes one newline.
+
+Send cancellation marks queued input as canceled before asking the terminal handle to signal the current foreground process group with a real `SIGINT`; if asynchronous pre-write inspection later settles, it cannot execute that input. If a provider write is already in flight, signalling waits for it to settle; a rejected write sends no signal. The canceled send retains its slot until the write and foreground signalling settle, so a successor cannot receive either late bytes or that signal. A provider write or signal that never settles therefore retains the slot indefinitely; closing the session (`terminal_close`) is the recovery. The absolute deadline remains armed while cancellation waits. A signal failure is a terminal transport failure and rejects the active send. Cancellation never emulates interruption by writing `\x03`, so raw-mode programs remain cancellable. Close rejects new public signals, stops readiness polling, and awaits the handle's provider-owned complete-session termination before settling the active send as `session_exit`.
+
+## Model Experience
+
+### Current file policy and indirect consumer
+
+#### What the model sees
+
+The policy owner contributes capability-neutral `sandbox:policy` context. Through `@hydraharness/harness-tool-terminal` or another PTY consumer, the model may also receive bounded MOTD, send deltas, scrollback pages, readiness reasons, and cleanup errors.
+
+#### Token effect
+
+The current-policy clause is present while this backend is mounted. Retained PTY scrollback is not placed in model history until a consumer returns bounded output.
+
+#### KV Cache effect
+
+A standing-policy change appends an owner-rendered superseding runtime-context snapshot after retained history; consumer results remain append-only.
+
+## Known Limitations and Deferred Work
+
+- Line-oriented output is normalized; full-screen alternate-buffer interaction is unsupported.
+- Exact stdin-wait detection depends on the mounted subprocess provider; providers that cannot prove it use prompt-marker and silence/timeout readiness. Windows is such a provider: the shell pid is the pseudo foreground group and there is no exact stdin-wait tier, so a marker-less child settles on the silence bound.
+- The pwsh bootstrap writes through `[Console]::` (the UTF-8 encoding pin and the prompt function), which the Windows ACL sandbox's read-only mode (ConstrainedLanguage) may deny. The shell can still settle through the controlled printable prompt and silence tier, but marker readiness is unavailable and non-ASCII output may follow the host code page.
+- Cleanup guarantees are those of `SubprocessTerminalHandle`; provider-specific gaps belong to that implementation's contract rather than this PTY consumer.
+- Sessions do not survive harness process exit.

package/lib/index.js

@@ -0,0 +1,901 @@
+import { TerminalBackendCleanupError, TerminalError } from "@hydraharness/harness-terminal";
+import { effectiveSandboxMode } from "@hydraharness/harness-sandbox-policy";
+import { ENCODING_PREAMBLE, resolvePwshPath } from "@hydraharness/harness-pwsh-local";
+import z from "@hydraharness/schemastery";
+import { Buffer } from "node:buffer";
+//#region lib/types/config.js
+/** Validated configuration for the local PTY backend. */
+/** Bash dialect default executable. */
+const DEFAULT_BASH_SHELL = "/bin/bash";
+/** Bash dialect default arguments (interactive, profile-free). */
+const DEFAULT_BASH_ARGS = [
+	"--noprofile",
+	"--norc",
+	"-i"
+];
+/** Pwsh dialect default arguments (interactive host, profile-free). */
+const DEFAULT_PWSH_ARGS = ["-NoLogo", "-NoProfile"];
+/**
+* Resolve the effective per-dialect shell specification. Defaulting is this
+* explicit step: an unset or empty `shellPath`/`shellArgs` selects the
+* dialect's defaults, while a non-empty explicit value always wins.
+* (Schemastery materializes an absent optional array as `[]`, so emptiness —
+* not just `undefined` — means "dialect default".)
+* @param config - Schemastery-resolved plugin configuration.
+* @returns the fully resolved configuration.
+*/
+function resolveConfig(config) {
+	const shellDialect = config.shellDialect ?? "bash";
+	return {
+		...config,
+		shellDialect,
+		shellPath: config.shellPath !== void 0 && config.shellPath.length > 0 ? config.shellPath : shellDialect === "pwsh" ? resolvePwshPath() : DEFAULT_BASH_SHELL,
+		shellArgs: config.shellArgs !== void 0 && config.shellArgs.length > 0 ? config.shellArgs : shellDialect === "pwsh" ? DEFAULT_PWSH_ARGS : DEFAULT_BASH_ARGS
+	};
+}
+/** Schemastery config exposed by the plugin. */
+const Config = z.object({
+	backendType: z.string().default("shell"),
+	shellDialect: z.union(["bash", "pwsh"]).default("bash"),
+	shellPath: z.string().required(false),
+	shellArgs: z.array(z.string()).required(false),
+	rows: z.number().default(40),
+	cols: z.number().default(160),
+	scrollbackLines: z.number().default(1e4),
+	scrollbackMaxBytes: z.number().default(4 * 1024 * 1024),
+	maxReadBytes: z.number().default(256 * 1024),
+	pollIntervalMs: z.number().default(50),
+	exactProbeAfterMs: z.number().default(150),
+	idleSilenceMs: z.number().default(3e3),
+	handoffGraceMs: z.number().default(500),
+	timeoutMs: z.number().default(3e4),
+	disposeGraceMs: z.number().default(3e3)
+});
+/**
+* Assert every effective numeric config field is a positive safe integer and bounds compose.
+* @param config - Schemastery-resolved plugin configuration.
+* @returns Narrows the input to the fully resolved configuration.
+*/
+function validateConfig(config) {
+	const resolved = config;
+	if (resolved.backendType.length === 0) throw new Error("terminal-bash: backendType must be non-empty");
+	if (resolved.shellPath.length === 0) throw new Error("terminal-bash: shellPath must be non-empty");
+	for (const [name, value] of Object.entries(resolved)) if (typeof value === "number" && (!Number.isSafeInteger(value) || value <= 0)) throw new Error(`terminal-bash: ${name} must be a positive safe integer`);
+	if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) throw new Error("terminal-bash: maxReadBytes must not exceed scrollbackMaxBytes");
+	if (resolved.handoffGraceMs < resolved.pollIntervalMs) throw new Error("terminal-bash: handoffGraceMs must be at least pollIntervalMs so one readiness poll runs inside the grace window");
+}
+/** Exact printable prompt emitted after the private marker. */
+const CONTROLLED_PROMPT = "hh> ";
+/**
+* Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+* Full terminal emulation is deliberately deferred; ordinary line output and
+* the private prompt marker are the supported contract.
+*/
+var TerminalSanitizer = class {
+	maxPendingBytes;
+	pending = "";
+	discardMode;
+	discardOscEscape = false;
+	trailingCarriageReturn = false;
+	trackingPromptTail = false;
+	constructor(maxPendingBytes) {
+		this.maxPendingBytes = maxPendingBytes;
+	}
+	/**
+	* Consume one decoded `node-pty` data chunk.
+	* @param chunk - decoded terminal data.
+	* @returns Printable text and whether the private prompt marker completed.
+	*/
+	push(chunk) {
+		this.pending += this.discardPrefix(chunk);
+		let text = "";
+		let prompt = false;
+		let includePromptTail = this.trackingPromptTail;
+		let promptTail = "";
+		let index = 0;
+		const appendText = (value) => {
+			text += value;
+			if (this.trackingPromptTail) promptTail += value;
+		};
+		while (index < this.pending.length) {
+			const escape = this.pending.indexOf("\x1B", index);
+			if (escape < 0) {
+				appendText(this.pending.slice(index));
+				index = this.pending.length;
+				break;
+			}
+			appendText(this.pending.slice(index, escape));
+			if (escape + 1 >= this.pending.length) {
+				index = escape;
+				break;
+			}
+			const kind = this.pending[escape + 1];
+			if (kind === "]") {
+				const bel = this.pending.indexOf("\x07", escape + 2);
+				const stringTerminator = this.pending.indexOf("\x1B\\", escape + 2);
+				let end = -1;
+				if (bel >= 0 && stringTerminator >= 0) end = Math.min(bel + 1, stringTerminator + 2);
+				else if (bel >= 0) end = bel + 1;
+				else if (stringTerminator >= 0) end = stringTerminator + 2;
+				if (end < 0) {
+					index = escape;
+					break;
+				}
+				const terminatorBytes = this.pending[end - 1] === "\x07" ? 1 : 2;
+				if (this.pending.slice(escape + 2, end - terminatorBytes).startsWith("133;D;")) {
+					prompt = true;
+					this.trackingPromptTail = true;
+					includePromptTail = true;
+					promptTail = "";
+				}
+				index = end;
+				continue;
+			}
+			if (kind === "[") {
+				let end = escape + 2;
+				while (end < this.pending.length) {
+					const code = this.pending.charCodeAt(end);
+					if (code >= 64 && code <= 126) break;
+					end += 1;
+				}
+				if (end >= this.pending.length) {
+					index = escape;
+					break;
+				}
+				index = end + 1;
+				continue;
+			}
+			index = escape + 2;
+		}
+		this.pending = this.pending.slice(index);
+		this.enforcePendingBound();
+		return {
+			text: this.normalizeText(text),
+			prompt,
+			...includePromptTail ? { promptTail } : {}
+		};
+	}
+	/**
+	* Flush a trailing printable fragment when the PTY exits.
+	* @returns Remaining printable text; incomplete escapes are discarded.
+	*/
+	flush() {
+		const text = this.pending.startsWith("\x1B") ? "" : this.pending;
+		this.pending = "";
+		this.discardMode = void 0;
+		this.discardOscEscape = false;
+		this.trackingPromptTail = false;
+		const normalized = this.normalizeText(text);
+		if (!this.trailingCarriageReturn) return normalized;
+		this.trailingCarriageReturn = false;
+		return `${normalized}\n`;
+	}
+	normalizeText(text) {
+		let complete = this.trailingCarriageReturn ? `\r${text}` : text;
+		this.trailingCarriageReturn = false;
+		if (complete.endsWith("\r")) {
+			complete = complete.slice(0, -1);
+			this.trailingCarriageReturn = true;
+		}
+		return normalizeTerminalText(complete);
+	}
+	enforcePendingBound() {
+		if (Buffer.byteLength(this.pending) <= this.maxPendingBytes) return;
+		this.discardMode = this.pending[1] === "]" ? "osc" : "csi";
+		this.pending = "";
+	}
+	discardPrefix(chunk) {
+		if (this.discardMode === void 0) return chunk;
+		if (this.discardMode === "csi") {
+			for (let index = 0; index < chunk.length; index += 1) {
+				const code = chunk.charCodeAt(index);
+				if (code >= 64 && code <= 126) {
+					this.discardMode = void 0;
+					return chunk.slice(index + 1);
+				}
+			}
+			return "";
+		}
+		let index = 0;
+		if (this.discardOscEscape) {
+			this.discardOscEscape = false;
+			if (chunk.startsWith("\\")) {
+				this.discardMode = void 0;
+				return chunk.slice(1);
+			}
+		}
+		while (index < chunk.length) {
+			if (chunk[index] === "\x07") {
+				this.discardMode = void 0;
+				return chunk.slice(index + 1);
+			}
+			if (chunk[index] === "\x1B") {
+				if (chunk[index + 1] === "\\") {
+					this.discardMode = void 0;
+					return chunk.slice(index + 2);
+				}
+				if (index + 1 === chunk.length) this.discardOscEscape = true;
+			}
+			index += 1;
+		}
+		return "";
+	}
+};
+/**
+* Normalize CRLF and standalone carriage returns for line-oriented rendering.
+* @param text - sanitized terminal text.
+* @returns Line-normalized text with BEL removed.
+*/
+function normalizeTerminalText(text) {
+	return text.replaceAll("\r\n", "\n").replaceAll("\r", "\n").replaceAll("\x07", "");
+}
+//#endregion
+//#region lib/types/session.js
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
+const CURSOR_POSITION_QUERY = "\x1B[6n";
+const CURSOR_POSITION_RESPONSE = "\x1B[1;1R";
+function utf8Tail(text, maxBytes) {
+	if (Buffer.byteLength(text) <= maxBytes) return {
+		text,
+		truncated: false
+	};
+	const chars = Array.from(text);
+	let bytes = 0;
+	let start = chars.length;
+	while (start > 0) {
+		const next = Buffer.byteLength(chars[start - 1]);
+		if (bytes + next > maxBytes) break;
+		bytes += next;
+		start -= 1;
+	}
+	return {
+		text: chars.slice(start).join(""),
+		truncated: true
+	};
+}
+var BoundedTextBuffer = class {
+	maxBytes;
+	maxLines;
+	value = "";
+	dropped = false;
+	constructor(maxBytes, maxLines) {
+		this.maxBytes = maxBytes;
+		this.maxLines = maxLines;
+	}
+	append(text) {
+		if (text.length === 0) return;
+		this.value += text;
+		if (this.maxLines !== void 0) {
+			const lines = this.value.split("\n");
+			if (lines.length > this.maxLines) {
+				this.value = lines.slice(lines.length - this.maxLines).join("\n");
+				this.dropped = true;
+			}
+		}
+		const tail = utf8Tail(this.value, this.maxBytes);
+		this.value = tail.text;
+		this.dropped ||= tail.truncated;
+	}
+	consume() {
+		const delta = this.value;
+		const truncated = this.dropped;
+		this.value = "";
+		this.dropped = false;
+		return {
+			delta,
+			truncated
+		};
+	}
+	snapshot() {
+		return {
+			text: this.value,
+			truncated: this.dropped
+		};
+	}
+};
+var LocalSendOperation = class {
+	startedAt;
+	onCancel;
+	output;
+	promise;
+	finished = false;
+	cancellationRequested = false;
+	initialForegroundLeftWait;
+	initialForegroundPgid;
+	constructor(maxBytes, startedAt, onCancel) {
+		this.startedAt = startedAt;
+		this.onCancel = onCancel;
+		this.output = new BoundedTextBuffer(maxBytes);
+		this.promise = Promise.withResolvers();
+		this.initialForegroundLeftWait = true;
+	}
+	get done() {
+		return this.promise.promise;
+	}
+	get settled() {
+		return this.finished;
+	}
+	get cancelRequested() {
+		return this.cancellationRequested;
+	}
+	append(text) {
+		if (!this.finished) this.output.append(text);
+	}
+	settle(waitReason, sessionStatus, inheritedTruncation) {
+		if (this.finished) return;
+		this.finished = true;
+		const read = this.output.snapshot();
+		this.promise.resolve({
+			viewport: read.text,
+			waitReason,
+			sessionStatus,
+			truncated: read.truncated || inheritedTruncation
+		});
+	}
+	fail(error) {
+		if (this.finished) return;
+		this.finished = true;
+		this.promise.reject(error);
+	}
+	readOutput() {
+		return this.output.consume();
+	}
+	setInitialForeground(foreground) {
+		this.initialForegroundPgid = foreground?.processGroupId;
+		this.initialForegroundLeftWait = foreground?.inputWaiting !== true;
+	}
+	acceptsStdinWait(pgid, waiting) {
+		if (pgid !== this.initialForegroundPgid) return waiting;
+		if (!waiting) this.initialForegroundLeftWait = true;
+		return waiting && this.initialForegroundLeftWait;
+	}
+	cancel() {
+		if (this.finished) return false;
+		this.cancellationRequested = true;
+		this.onCancel();
+		return true;
+	}
+};
+/** Backend session wrapping one provider-owned terminal process. */
+var LocalPtySession = class {
+	terminal;
+	config;
+	motd = "";
+	pid;
+	decoder = new TextDecoder();
+	sanitizer;
+	cursorQueryTail = "";
+	scrollback;
+	firstOutput = Promise.withResolvers();
+	firstWrite = true;
+	outputEnded = Promise.withResolvers();
+	completion;
+	statusValue = { kind: "running" };
+	active;
+	activeTimer;
+	activeDeadlineTimer;
+	activeAbort;
+	interrupting;
+	activeWrite;
+	pollingReady;
+	polling = false;
+	promptSeen = false;
+	promptTextSeen = false;
+	promptTail = "";
+	shellPgid;
+	initializing = false;
+	lastOutputAt = Date.now();
+	closing = false;
+	closePromise;
+	transportFailure;
+	constructor(terminal, config) {
+		this.terminal = terminal;
+		this.config = config;
+		this.pid = terminal.pid;
+		this.sanitizer = new TerminalSanitizer(config.maxReadBytes);
+		this.scrollback = new BoundedTextBuffer(config.scrollbackMaxBytes, config.scrollbackLines);
+		terminal.output.on("data", this.onTerminalData);
+		terminal.output.once("end", this.onTerminalEnd);
+		terminal.output.once("error", this.onTerminalError);
+		this.completion = terminal.done.then((outcome) => this.onExit(outcome), (error) => {
+			this.onTransportFailure(error);
+		});
+	}
+	/**
+	* Capture startup output through the same readiness contract as later sends.
+	* @param signal - optional cancellation while the shell reaches its first prompt.
+	* @returns Resolves after startup readiness; rejects on exit or readiness timeout.
+	*/
+	async initialize(signal) {
+		this.initializing = true;
+		try {
+			const result = await this.startSend({
+				text: "",
+				submit: false,
+				...signal !== void 0 ? { signal } : {}
+			}).done;
+			if (result.waitReason === "session_exit") throw new Error("PTY shell exited during startup");
+			if (result.waitReason === "timeout") throw new Error("PTY shell did not reach readiness before startup timeout");
+			this.motd = result.viewport;
+		} catch (error) {
+			signal?.throwIfAborted();
+			throw error;
+		} finally {
+			this.initializing = false;
+		}
+	}
+	startSend(request) {
+		if (this.closing) throw new Error("PTY session is closing");
+		if (this.statusValue.kind === "exited") throw new Error("PTY session has exited");
+		if (this.active !== void 0) throw new TerminalError(`PTY session already has an active send${this.activeWrite !== void 0 ? " or draining provider write" : this.interrupting !== void 0 ? " or draining foreground interrupt" : ""}`, "SEND_ACTIVE");
+		if (request.signal?.aborted === true) throw new Error("PTY send aborted before write");
+		const operation = new LocalSendOperation(this.config.maxReadBytes, Date.now(), () => {
+			this.interrupt(operation);
+		});
+		this.active = operation;
+		this.resetReadinessEvidence();
+		if (request.signal !== void 0) {
+			const onAbort = () => {
+				operation.cancel();
+			};
+			request.signal.addEventListener("abort", onAbort, { once: true });
+			this.activeAbort = () => request.signal?.removeEventListener("abort", onAbort);
+		}
+		this.activeDeadlineTimer = setTimeout(() => {
+			if (this.active === operation) this.settleActive("timeout", this.activeWrite !== void 0 || this.interrupting === operation);
+		}, this.config.timeoutMs);
+		this.beginSend(operation, request);
+		return operation;
+	}
+	async beginSend(operation, request) {
+		let foreground;
+		try {
+			foreground = await this.terminal.inspectForeground();
+		} catch (error) {
+			if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error);
+			return;
+		}
+		try {
+			if (this.config.shellDialect === "pwsh" && this.firstWrite && (request.text.length > 0 || request.submit)) await Promise.race([this.firstOutput.promise, operation.done]);
+			if (this.active !== operation || this.closing || this.interrupting === operation) return;
+			operation.setInitialForeground(foreground);
+			const input = `${request.text}${request.submit ? "\r" : ""}`;
+			if (input.length > 0 && !operation.cancelRequested) {
+				this.resetReadinessEvidence();
+				const write = this.terminal.write(input);
+				this.activeWrite = write.then(() => true, () => false);
+				try {
+					await write;
+				} finally {
+					this.activeWrite = void 0;
+				}
+				this.firstWrite = false;
+			}
+			if (operation.cancelRequested) return;
+			if (this.active === operation && operation.settled) {
+				this.clearActive();
+				return;
+			}
+			if (this.active === operation && !this.closing) {
+				this.pollingReady = operation;
+				this.schedulePoll(operation);
+			}
+		} catch (error) {
+			if (this.active === operation && !this.closing) if (operation.settled) this.clearActive();
+			else this.failActive(error);
+		}
+	}
+	resetReadinessEvidence() {
+		this.lastOutputAt = Date.now();
+		this.promptSeen = false;
+		this.promptTextSeen = false;
+		this.promptTail = "";
+	}
+	read(request) {
+		const snapshot = this.scrollback.snapshot();
+		const lines = snapshot.text.split("\n");
+		const totalLines = snapshot.text.length === 0 ? 0 : lines.length;
+		const offset = request.offset ?? 0;
+		const count = request.count ?? 500;
+		if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("PTY read offset must be a non-negative safe integer");
+		if (!Number.isSafeInteger(count) || count <= 0) throw new Error("PTY read count must be a positive safe integer");
+		if (offset >= totalLines) return {
+			text: "",
+			totalLines,
+			lineBegin: offset,
+			lineEnd: offset,
+			truncated: snapshot.truncated
+		};
+		const end = totalLines - offset;
+		const start = Math.max(0, end - count);
+		const bounded = utf8Tail(lines.slice(start, end).join("\n"), this.config.maxReadBytes);
+		const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split("\n").length;
+		return {
+			text: bounded.text,
+			totalLines,
+			lineBegin: offset,
+			lineEnd: offset + returnedLines,
+			truncated: snapshot.truncated || bounded.truncated
+		};
+	}
+	async signal(signal) {
+		if (this.closing) throw new Error("PTY session is closing");
+		return {
+			delivered: true,
+			targetPgid: await this.terminal.signalForeground(signal)
+		};
+	}
+	status() {
+		return this.statusValue;
+	}
+	close(reason) {
+		this.closing = true;
+		if (this.closePromise !== void 0) return this.closePromise;
+		const closing = this.closeOnce(reason).catch((error) => {
+			this.closePromise = void 0;
+			this.failActive(error);
+			throw error;
+		});
+		this.closePromise = closing;
+		return closing;
+	}
+	onTerminalData = (chunk) => {
+		const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+		this.onData(this.decoder.decode(bytes, { stream: true }));
+	};
+	onTerminalEnd = () => {
+		this.firstOutput.resolve();
+		this.onData(this.decoder.decode());
+		this.appendOutput(this.sanitizer.flush());
+		this.outputEnded.resolve();
+	};
+	onTerminalError = (error) => {
+		this.firstOutput.resolve();
+		this.onTransportFailure(error);
+		this.outputEnded.resolve();
+	};
+	onData(data) {
+		this.respondToCursorQueries(data);
+		if (this.cursorQueryTail.length === 0) this.firstOutput.resolve();
+		const sanitized = this.sanitizer.push(data);
+		this.appendOutput(sanitized.text);
+		if (sanitized.prompt) {
+			this.promptSeen = true;
+			this.promptTail = "";
+			this.lastOutputAt = Date.now();
+		}
+		if (this.promptSeen && sanitized.promptTail !== void 0) {
+			const remaining = Math.max(0, 5 - this.promptTail.length);
+			this.promptTail += sanitized.promptTail.slice(0, remaining);
+			if (sanitized.promptTail.length > remaining) this.promptTail = `${CONTROLLED_PROMPT}\0`;
+			this.promptTextSeen = this.promptTail === CONTROLLED_PROMPT;
+		}
+	}
+	respondToCursorQueries(data) {
+		const input = this.cursorQueryTail + data;
+		let offset = 0;
+		while (true) {
+			const query = input.indexOf(CURSOR_POSITION_QUERY, offset);
+			if (query < 0) break;
+			offset = query + 4;
+			if (!this.closing && this.statusValue.kind === "running") this.terminal.write(CURSOR_POSITION_RESPONSE).catch((error) => {
+				if (!this.closing) this.onTransportFailure(error);
+			});
+		}
+		this.cursorQueryTail = "";
+		for (let length = Math.min(3, input.length); length > 0; length -= 1) if (input.endsWith(CURSOR_POSITION_QUERY.slice(0, length))) {
+			this.cursorQueryTail = input.slice(-length);
+			break;
+		}
+	}
+	async onExit(outcome) {
+		await this.outputEnded.promise;
+		if (this.transportFailure !== void 0) return;
+		this.statusValue = {
+			kind: "exited",
+			exitCode: outcome.exitCode,
+			signal: outcome.signal
+		};
+		this.settleActive("session_exit");
+	}
+	onTransportFailure(error) {
+		this.firstOutput.resolve();
+		const failure = error instanceof Error ? error : new Error(String(error));
+		this.transportFailure ??= failure;
+		this.statusValue = {
+			kind: "exited",
+			exitCode: null,
+			signal: null
+		};
+		this.failActive(failure);
+		this.terminal.terminate().catch(() => {});
+	}
+	appendOutput(text) {
+		if (text.length === 0) return;
+		this.lastOutputAt = Date.now();
+		this.scrollback.append(text);
+		this.active?.append(text);
+	}
+	schedulePoll(operation, delayMs = this.config.pollIntervalMs) {
+		if (this.active !== operation || this.interrupting === operation || this.polling) return;
+		if (this.activeTimer !== void 0) clearTimeout(this.activeTimer);
+		this.activeTimer = setTimeout(() => {
+			this.activeTimer = void 0;
+			this.pollReadiness(operation);
+		}, delayMs);
+	}
+	async pollReadiness(operation) {
+		if (this.active !== operation || this.polling) return;
+		this.polling = true;
+		try {
+			if (this.statusValue.kind === "exited") {
+				this.settleActive("session_exit");
+				return;
+			}
+			const foreground = await this.terminal.inspectForeground();
+			if (this.active !== operation || this.closing || this.interrupting === operation) return;
+			const idleFor = Date.now() - this.lastOutputAt;
+			if (this.promptSeen && foreground !== void 0 && this.shellPgid === void 0) this.shellPgid = foreground.processGroupId;
+			if (this.promptSeen && this.promptTextSeen && idleFor >= this.config.pollIntervalMs && foreground?.processGroupId === this.shellPgid) {
+				this.settleActive("stdin_read");
+				return;
+			}
+			const elapsed = Date.now() - operation.startedAt;
+			const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0;
+			const acceptsStdinWait = startupHasOutput && foreground !== void 0 && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting);
+			if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
+				this.settleActive("stdin_read");
+				return;
+			}
+			const handoffGrace = this.promptSeen ? this.config.handoffGraceMs : 0;
+			if (startupHasOutput && idleFor >= this.config.idleSilenceMs + handoffGrace) this.settleActive("inferred_idle");
+		} catch (error) {
+			if (this.active === operation && !this.closing && this.interrupting !== operation) this.failActive(error);
+		} finally {
+			this.polling = false;
+			const active = this.active;
+			if (active !== void 0 && this.pollingReady === active) this.schedulePoll(active);
+		}
+	}
+	settleActive(waitReason, retainOwnership = false) {
+		const operation = this.active;
+		if (operation === void 0) return;
+		const scrollbackTruncated = this.scrollback.snapshot().truncated;
+		if (retainOwnership) {
+			this.stopPolling();
+			this.activeAbort?.();
+			this.activeAbort = void 0;
+		} else this.clearActive();
+		operation.settle(waitReason, this.statusValue, scrollbackTruncated);
+	}
+	stopPolling() {
+		this.stopReadinessPolling();
+		if (this.activeDeadlineTimer !== void 0) clearTimeout(this.activeDeadlineTimer);
+		this.activeDeadlineTimer = void 0;
+	}
+	stopReadinessPolling() {
+		if (this.activeTimer !== void 0) clearTimeout(this.activeTimer);
+		this.activeTimer = void 0;
+		this.pollingReady = void 0;
+	}
+	clearActive() {
+		const operation = this.active;
+		this.stopPolling();
+		this.activeAbort?.();
+		this.activeAbort = void 0;
+		if (this.interrupting === operation) this.interrupting = void 0;
+		this.pollingReady = void 0;
+		this.active = void 0;
+	}
+	failActive(error) {
+		const operation = this.active;
+		if (operation === void 0) return;
+		this.clearActive();
+		operation.fail(error);
+	}
+	interrupt(operation) {
+		if (this.active !== operation) return;
+		this.interrupting = operation;
+		this.stopReadinessPolling();
+		this.interruptOnce(operation);
+	}
+	async interruptOnce(operation) {
+		try {
+			const activeWrite = this.activeWrite;
+			if (activeWrite !== void 0 && !await activeWrite) return;
+			await this.terminal.signalForeground("SIGINT");
+		} catch (error) {
+			if (this.active === operation && !this.closing) this.onTransportFailure(error);
+			return;
+		} finally {
+			if (this.interrupting === operation) this.interrupting = void 0;
+		}
+		if (this.active === operation && operation.settled) this.clearActive();
+		else if (this.active === operation && !this.closing) {
+			this.pollingReady = operation;
+			this.schedulePoll(operation, 0);
+		}
+	}
+	async closeOnce(reason) {
+		this.stopPolling();
+		try {
+			await this.terminal.terminate();
+		} catch (error) {
+			throw new Error(`PTY cleanup failed (${reason})`, { cause: error });
+		}
+		this.settleActive("session_exit");
+		await this.completion;
+		this.terminal.output.off("data", this.onTerminalData);
+		this.terminal.output.off("end", this.onTerminalEnd);
+		this.terminal.output.off("error", this.onTerminalError);
+		if (this.transportFailure !== void 0) throw this.transportFailure;
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Persistent shell PTY backend over the subprocess terminal primitive, shared
+* sandbox policy, bounded output, and provider-owned session cleanup.
+* @module @hydraharness/harness-terminal-bash
+*/
+/** Cordis plugin name. */
+const name = "terminal-bash";
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+const inject = [
+	"terminals",
+	"sandboxPolicy",
+	"subprocess"
+];
+const sandboxModeFences = /* @__PURE__ */ new WeakMap();
+function ensureSandboxModeFence(ctx, owner) {
+	const existing = sandboxModeFences.get(owner);
+	if (existing !== void 0) {
+		existing.pty = ctx.terminals;
+		existing.sandboxPolicy = ctx.sandboxPolicy;
+		return;
+	}
+	const state = {
+		pty: ctx.terminals,
+		sandboxPolicy: ctx.sandboxPolicy
+	};
+	sandboxModeFences.set(owner, state);
+	owner.ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		if (session !== owner.session || event.type !== "sandbox/mode") return;
+		const currentMode = effectiveSandboxMode(session.events) ?? state.sandboxPolicy.defaultMode;
+		if (event.data.mode === currentMode || !state.pty.hasOwnerActivity(owner)) return;
+		throw new Error(`cannot change sandbox mode from "${currentMode}" to "${event.data.mode}" while persistent terminal sessions are open or being created; wait for creation to settle and close them first`);
+	}, { global: true });
+}
+function childEnvironment(spec, dialect) {
+	const common = {
+		TERM: "dumb",
+		PAGER: "cat",
+		GIT_PAGER: "cat",
+		HYDRA_SHELL: "1",
+		HYDRA_SESSION_ID: spec.owner.id,
+		HYDRA_PTY_SESSION_ID: spec.sessionId
+	};
+	if (dialect === "pwsh") return {
+		...common,
+		NO_COLOR: "1"
+	};
+	return {
+		...common,
+		PS1: CONTROLLED_PROMPT,
+		PROMPT_COMMAND: `printf "\\033]133;D;%s\\007" "$?"; PS1='${CONTROLLED_PROMPT}'`,
+		BASH_SILENCE_DEPRECATION_WARNING: "1"
+	};
+}
+/**
+* The pwsh prompt function that emits the shared OSC `133;D;` + BEL marker
+* before every prompt, mirroring bash's PROMPT_COMMAND. `[char]27`/`[char]7`
+* build the control bytes at runtime because raw ESC characters in submitted
+* input are unreliable under PSReadLine.
+*/
+const PWSH_PROMPT_SETUP = "function prompt { [Console]::Write([char]27 + ']133;D;' + [int]$LASTEXITCODE + [char]7); 'hh> ' }";
+function spawnArgv(ctx, config, policy) {
+	const argv = [config.shellPath, ...config.shellArgs];
+	if (policy.mode === "danger-full-access") return argv;
+	const sandbox = ctx.get("sandbox");
+	if (sandbox === void 0) throw new Error(`terminal-bash: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`);
+	return sandbox.confine(argv, {
+		...policy,
+		mode: policy.mode
+	}).argv;
+}
+async function startupSession(session, dialect, signal) {
+	const start = async () => {
+		if (dialect === "bash") {
+			await session.initialize(signal);
+			return;
+		}
+		let viewport = "";
+		let first = true;
+		for (;;) {
+			const operation = session.startSend({
+				text: first ? ENCODING_PREAMBLE + PWSH_PROMPT_SETUP : "",
+				submit: first,
+				...signal !== void 0 ? { signal } : {}
+			});
+			first = false;
+			const result = await operation.done;
+			if (result.waitReason === "session_exit") throw new Error("PTY shell exited during startup");
+			if (result.waitReason === "timeout") throw new Error("PTY shell did not reach readiness before startup timeout");
+			viewport = result.viewport;
+			const scrollback = session.read({
+				offset: 0,
+				count: 20
+			}).text;
+			if (viewport.endsWith("hh> ") || scrollback.endsWith("hh> ")) break;
+		}
+		session.motd = viewport;
+	};
+	if (signal === void 0) {
+		await start();
+		return;
+	}
+	const aborted = Promise.withResolvers();
+	const onAbort = () => {
+		aborted.reject(signal.reason);
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		signal.throwIfAborted();
+		await Promise.race([start(), aborted.promise]);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+/** Local shell backend registered under the configured type. */
+var BashTerminalBackend = class {
+	ctx;
+	config;
+	spawnTerminal;
+	createSession;
+	type;
+	constructor(ctx, config, spawnTerminal = (spec) => ctx.subprocess.spawnTerminal(spec), createSession = (terminal, config) => new LocalPtySession(terminal, config)) {
+		this.ctx = ctx;
+		this.config = config;
+		this.spawnTerminal = spawnTerminal;
+		this.createSession = createSession;
+		this.type = config.backendType;
+	}
+	async spawn(spec) {
+		spec.signal?.throwIfAborted();
+		ensureSandboxModeFence(this.ctx, spec.owner);
+		const policy = this.ctx.sandboxPolicy.resolve({ session: spec.owner.session });
+		const argv = spawnArgv(this.ctx, this.config, policy);
+		if (argv[0] === void 0) throw new Error("terminal-bash: sandbox returned empty argv");
+		const terminal = await this.spawnTerminal({
+			argv,
+			cwd: spec.cwd ?? policy.workspaceRoot,
+			env: childEnvironment(spec, this.config.shellDialect),
+			rows: this.config.rows,
+			cols: this.config.cols,
+			graceMs: this.config.disposeGraceMs,
+			signal: spec.signal
+		});
+		const session = this.createSession(terminal, this.config);
+		try {
+			await startupSession(session, this.config.shellDialect, spec.signal);
+			return session;
+		} catch (error) {
+			try {
+				await session.close("PTY startup failed");
+			} catch (closeError) {
+				throw new TerminalBackendCleanupError(error, closeError);
+			}
+			throw error;
+		}
+	}
+};
+/** Register the local PTY backend. */
+function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	validateConfig(resolved);
+	ctx.terminals.registerBackend(new BashTerminalBackend(ctx, resolved));
+}
+//#endregion
+export { BashTerminalBackend, Config, PWSH_PROMPT_SETUP, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-terminal-bash`.
+* @module @hydraharness/harness-terminal-bash/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-terminal-bash";
+/** Cordis companion plugin name. */
+const name = "terminal-bash-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: readiness, terminal buffers, and process-tree state are private per-session
+* implementation state, and the backend publishes no independent lifecycle stream or snapshot.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/config.d.ts

@@ -0,0 +1,71 @@
+/** Validated configuration for the local PTY backend. */
+import z from '@hydraharness/schemastery';
+/** One supported interactive shell dialect. */
+export type ShellDialect = 'bash' | 'pwsh';
+/** Public plugin configuration. */
+export interface Config {
+    /** Backend registry type (default: `shell`). */
+    backendType?: string;
+    /** Interactive shell dialect (default: `bash`); selects the argv/env/startup defaults. */
+    shellDialect?: ShellDialect;
+    /** Interactive shell executable (default per dialect: `/bin/bash`, or the resolved pwsh). */
+    shellPath?: string;
+    /** Shell arguments (default per dialect: bash `--noprofile --norc -i`, pwsh `-NoLogo -NoProfile`). */
+    shellArgs?: string[];
+    /** Terminal rows. */
+    rows?: number;
+    /** Terminal columns. */
+    cols?: number;
+    /** Maximum retained logical lines. */
+    scrollbackLines?: number;
+    /** Maximum retained UTF-8 bytes. */
+    scrollbackMaxBytes?: number;
+    /** Maximum bytes returned by one read or settled viewport. */
+    maxReadBytes?: number;
+    /** Readiness polling interval. */
+    pollIntervalMs?: number;
+    /** Delay before Linux exact syscall probes. */
+    exactProbeAfterMs?: number;
+    /** Silence duration that yields `inferred_idle`. */
+    idleSilenceMs?: number;
+    /**
+     * Extra wait beyond `idleSilenceMs`, once a prompt marker was seen, for the shell to
+     * regain the foreground before `inferred_idle` settles; at least one `pollIntervalMs`.
+     */
+    handoffGraceMs?: number;
+    /** Absolute send wait bound. */
+    timeoutMs?: number;
+    /** Grace before teardown escalates to `SIGKILL`. */
+    disposeGraceMs?: number;
+}
+/** Configuration after Schemastery defaults and dialect resolution. */
+export type ResolvedConfig = Omit<Required<Config>, 'shellDialect' | 'shellPath' | 'shellArgs'> & {
+    shellDialect: ShellDialect;
+    shellPath: string;
+    shellArgs: string[];
+};
+/** Bash dialect default executable. */
+export declare const DEFAULT_BASH_SHELL = "/bin/bash";
+/** Bash dialect default arguments (interactive, profile-free). */
+export declare const DEFAULT_BASH_ARGS: string[];
+/** Pwsh dialect default arguments (interactive host, profile-free). */
+export declare const DEFAULT_PWSH_ARGS: string[];
+/**
+ * Resolve the effective per-dialect shell specification. Defaulting is this
+ * explicit step: an unset or empty `shellPath`/`shellArgs` selects the
+ * dialect's defaults, while a non-empty explicit value always wins.
+ * (Schemastery materializes an absent optional array as `[]`, so emptiness —
+ * not just `undefined` — means "dialect default".)
+ * @param config - Schemastery-resolved plugin configuration.
+ * @returns the fully resolved configuration.
+ */
+export declare function resolveConfig(config: Config): ResolvedConfig;
+/** Schemastery config exposed by the plugin. */
+export declare const Config: z<Config>;
+/**
+ * Assert every effective numeric config field is a positive safe integer and bounds compose.
+ * @param config - Schemastery-resolved plugin configuration.
+ * @returns Narrows the input to the fully resolved configuration.
+ */
+export declare function validateConfig(config: Config): asserts config is ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Persistent shell PTY backend over the subprocess terminal primitive, shared
+ * sandbox policy, bounded output, and provider-owned session cleanup.
+ * @module @hydraharness/harness-terminal-bash
+ */
+import { Context } from '@hydraharness/cordis';
+import type { TerminalBackend, TerminalBackendSpawnSpec } from '@hydraharness/harness-terminal';
+import type { SubprocessTerminalHandle, SubprocessTerminalSpawnSpec } from '@hydraharness/harness-subprocess';
+import { type Config, type ResolvedConfig } from './config.ts';
+import { LocalPtySession } from './session.ts';
+export { Config } from './config.ts';
+export type { Config as TerminalLocalConfig } from './config.ts';
+/** Cordis plugin name. */
+export declare const name = "terminal-bash";
+/** Required services: PTY registry, shared confinement policy, and process substrate. */
+export declare const inject: string[];
+/**
+ * The pwsh prompt function that emits the shared OSC `133;D;` + BEL marker
+ * before every prompt, mirroring bash's PROMPT_COMMAND. `[char]27`/`[char]7`
+ * build the control bytes at runtime because raw ESC characters in submitted
+ * input are unreliable under PSReadLine.
+ */
+export declare const PWSH_PROMPT_SETUP: string;
+/** Local shell backend registered under the configured type. */
+export declare class BashTerminalBackend implements TerminalBackend {
+    private readonly ctx;
+    private readonly config;
+    private readonly spawnTerminal;
+    private readonly createSession;
+    readonly type: string;
+    constructor(ctx: Context, config: ResolvedConfig, spawnTerminal?: (spec: SubprocessTerminalSpawnSpec) => Promise<SubprocessTerminalHandle>, createSession?: (terminal: SubprocessTerminalHandle, config: ResolvedConfig) => LocalPtySession);
+    spawn(spec: TerminalBackendSpawnSpec): Promise<LocalPtySession>;
+}
+/** Register the local PTY backend. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-terminal-bash`.
+ * @module @hydraharness/harness-terminal-bash/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "terminal-bash-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/sanitize.d.ts

@@ -0,0 +1,47 @@
+/** Streaming terminal-control sanitizer for the line-oriented first release. */
+/** OSC marker emitted by the controlled bash before each prompt. */
+export declare const PROMPT_MARKER_PREFIX = "133;D;";
+/** Exact printable prompt emitted after the private marker. */
+export declare const CONTROLLED_PROMPT = "hh> ";
+/** One sanitized chunk plus whether it contained the owned prompt marker. */
+export interface SanitizedChunk {
+    text: string;
+    prompt: boolean;
+    /** Printable text after the latest owned marker in this chunk. */
+    promptTail?: string;
+}
+/**
+ * Remove CSI/OSC/short escape sequences while preserving split-sequence carry.
+ * Full terminal emulation is deliberately deferred; ordinary line output and
+ * the private prompt marker are the supported contract.
+ */
+export declare class TerminalSanitizer {
+    private readonly maxPendingBytes;
+    private pending;
+    private discardMode;
+    private discardOscEscape;
+    private trailingCarriageReturn;
+    private trackingPromptTail;
+    constructor(maxPendingBytes: number);
+    /**
+     * Consume one decoded `node-pty` data chunk.
+     * @param chunk - decoded terminal data.
+     * @returns Printable text and whether the private prompt marker completed.
+     */
+    push(chunk: string): SanitizedChunk;
+    /**
+     * Flush a trailing printable fragment when the PTY exits.
+     * @returns Remaining printable text; incomplete escapes are discarded.
+     */
+    flush(): string;
+    private normalizeText;
+    private enforcePendingBound;
+    private discardPrefix;
+}
+/**
+ * Normalize CRLF and standalone carriage returns for line-oriented rendering.
+ * @param text - sanitized terminal text.
+ * @returns Line-normalized text with BEL removed.
+ */
+export declare function normalizeTerminalText(text: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/lib/types/session.d.ts

@@ -0,0 +1,70 @@
+/** Persistent PTY session over the subprocess seam's terminal primitive. */
+import type { SubprocessTerminalHandle } from '@hydraharness/harness-subprocess';
+import type { TerminalBackendSession, TerminalReadRequest, TerminalReadResult, TerminalSendOperation, TerminalSendRequest, TerminalSessionStatus, TerminalSignal, TerminalSignalResult } from '@hydraharness/harness-terminal';
+import type { ResolvedConfig } from './config.ts';
+/** Backend session wrapping one provider-owned terminal process. */
+export declare class LocalPtySession implements TerminalBackendSession {
+    private readonly terminal;
+    private readonly config;
+    motd: string;
+    readonly pid: number;
+    private readonly decoder;
+    private readonly sanitizer;
+    private cursorQueryTail;
+    private readonly scrollback;
+    private readonly firstOutput;
+    private firstWrite;
+    private readonly outputEnded;
+    private readonly completion;
+    private statusValue;
+    private active;
+    private activeTimer;
+    private activeDeadlineTimer;
+    private activeAbort;
+    private interrupting;
+    private activeWrite;
+    private pollingReady;
+    private polling;
+    private promptSeen;
+    private promptTextSeen;
+    private promptTail;
+    private shellPgid;
+    private initializing;
+    private lastOutputAt;
+    private closing;
+    private closePromise;
+    private transportFailure;
+    constructor(terminal: SubprocessTerminalHandle, config: ResolvedConfig);
+    /**
+     * Capture startup output through the same readiness contract as later sends.
+     * @param signal - optional cancellation while the shell reaches its first prompt.
+     * @returns Resolves after startup readiness; rejects on exit or readiness timeout.
+     */
+    initialize(signal?: AbortSignal): Promise<void>;
+    startSend(request: TerminalSendRequest): TerminalSendOperation;
+    private beginSend;
+    private resetReadinessEvidence;
+    read(request: TerminalReadRequest): TerminalReadResult;
+    signal(signal: TerminalSignal): Promise<TerminalSignalResult>;
+    status(): TerminalSessionStatus;
+    close(reason: string): Promise<void>;
+    private readonly onTerminalData;
+    private readonly onTerminalEnd;
+    private readonly onTerminalError;
+    private onData;
+    private respondToCursorQueries;
+    private onExit;
+    private onTransportFailure;
+    private appendOutput;
+    private schedulePoll;
+    private pollReadiness;
+    private settleActive;
+    private stopPolling;
+    private stopReadinessPolling;
+    private clearActive;
+    private failActive;
+    private interrupt;
+    private interruptOnce;
+    private closeOnce;
+}
+//# sourceMappingURL=session.d.ts.map

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@hydraharness/harness-terminal-bash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Persistent shell PTY backend over the Hydra harness subprocess terminal primitive",
+  "hydra": {
+    "plugin": {
+      "application": "Provide a persistent shell terminal for commands that need an interactive process."
+    }
+  },
+  "version": "0.1.1-rc.7",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/terminal/terminal-bash"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-terminal": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.7",
+    "@hydraharness/harness-session": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.7",
+    "@hydraharness/harness-subprocess": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2",
+    "@hydraharness/harness-pwsh-local": "^0.1.1-rc.7"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-terminal": "^0.1.1-rc.7",
+    "@hydraharness/harness-agent": "^0.1.1-rc.7",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox": "^0.1.1-rc.7",
+    "@hydraharness/harness-sandbox-policy": "^0.1.1-rc.7",
+    "@hydraharness/harness-session": "^0.1.1-rc.7",
+    "@hydraharness/harness-subprocess": "^0.1.1-rc.7",
+    "@hydraharness/harness-subprocess-local": "^0.1.1-rc.7",
+    "@hydraharness/cordis": "^4.0.2"
+  }
 }