@jabberwocky238/dsh-ssh 0.0.0-stage → 0.2.4

package/lib/protocol-CDhW_IHU.js

@@ -0,0 +1,276 @@
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+//#region lib/types/protocol.js
+/** Bounded, versioned requests between an SSH client and its private remote helper. */
+/** Wire version shared by the installed helper and client package. */
+const SSH_PROTOCOL_VERSION = 2;
+/** Maximum prepared or running process handles owned by one helper. */
+const SSH_MAX_PROCESS_HANDLES = 128;
+/** Maximum open text iterators owned by one helper. */
+const SSH_MAX_TEXT_STREAMS = 128;
+const managementLimits = {
+	heartbeat: 1,
+	close: 1,
+	"process.terminate": 128,
+	"fs.streamClose": 128
+};
+function requestClass(method) {
+	switch (method) {
+		case "heartbeat":
+		case "close":
+		case "process.terminate":
+		case "fs.streamClose": return method;
+		default: return "ordinary";
+	}
+}
+const errorSchema = z.object({
+	name: z.string(),
+	message: z.string(),
+	code: z.string().optional()
+}).strict();
+const requestIdSchema = z.string().transform((value) => value);
+const frameSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("request"),
+		id: requestIdSchema,
+		method: z.string(),
+		params: z.unknown()
+	}).strict(),
+	z.object({
+		type: z.literal("result"),
+		id: requestIdSchema,
+		value: z.unknown()
+	}).strict(),
+	z.object({
+		type: z.literal("error"),
+		id: requestIdSchema,
+		error: errorSchema
+	}).strict(),
+	z.object({
+		type: z.literal("cancel"),
+		id: requestIdSchema
+	}).strict()
+]);
+function operationError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+/** A remote error retains its typed filesystem or sandbox code. */
+var RemoteOperationError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "RemoteOperationError";
+	}
+};
+/** The peer owns pending calls and rejects ambiguous operations on connection loss; it never replays requests. */
+var SshRpcPeer = class extends EventEmitter {
+	input;
+	output;
+	maxFrameBytes;
+	maxPending;
+	handler;
+	pending = /* @__PURE__ */ new Map();
+	active = /* @__PURE__ */ new Map();
+	writeTail = Promise.resolve();
+	queuedBytes = 0;
+	failure;
+	constructor(input, output, maxFrameBytes, maxPending, handler) {
+		super();
+		this.input = input;
+		this.output = output;
+		this.maxFrameBytes = maxFrameBytes;
+		this.maxPending = maxPending;
+		this.handler = handler;
+		input.on("error", (error) => {
+			this.close(error);
+		});
+		output.on("error", (error) => {
+			this.close(error);
+		});
+		output.on("close", () => {
+			this.close();
+		});
+		this.readFrames().catch((error) => {
+			this.close(operationError(error));
+		});
+	}
+	/**
+	* Send one request and validate its response before exposing it to the caller.
+	* @param method - the private helper operation.
+	* @param params - JSON request fields.
+	* @param schema - validation for the remote response.
+	* @param signal - cancellation without rollback of remote effects.
+	* @returns the validated response or a transport/remote-operation rejection.
+	*/
+	async request(method, params, schema, signal) {
+		signal?.throwIfAborted();
+		if (this.failure !== void 0) throw this.failure;
+		const kind = requestClass(method);
+		if (this.atCapacity(kind, this.pending.values())) throw new Error("SSH helper pending request limit reached");
+		const id = randomUUID();
+		const result = Promise.withResolvers();
+		result.promise.catch(() => {});
+		this.pending.set(id, {
+			...result,
+			requestClass: kind
+		});
+		const abort = () => {
+			result.reject(/* @__PURE__ */ new Error("SSH operation cancelled; a completed remote mutation is not rolled back"));
+			this.send({
+				type: "cancel",
+				id
+			}).catch(() => {});
+		};
+		signal?.addEventListener("abort", abort, { once: true });
+		try {
+			this.send({
+				type: "request",
+				id,
+				method,
+				params
+			}).catch((error) => {
+				this.pending.delete(id);
+				result.reject(operationError(error));
+			});
+			return schema.parse(await result.promise);
+		} finally {
+			signal?.removeEventListener("abort", abort);
+		}
+	}
+	/**
+	* Fail pending operations and abort remote handlers without claiming rollback.
+	* @param error - the transport failure reported to all pending operations.
+	*/
+	close(error = /* @__PURE__ */ new Error("SSH connection lost; remote operation outcome and cleanup are unknown")) {
+		if (this.failure !== void 0) return;
+		this.failure = error;
+		for (const pending of this.pending.values()) pending.reject(error);
+		this.pending.clear();
+		for (const { controller } of this.active.values()) controller.abort(error);
+		this.active.clear();
+		this.input.destroy();
+		this.output.destroy();
+		this.emit("closed", error);
+	}
+	async send(frame) {
+		if (this.failure !== void 0) return Promise.reject(this.failure);
+		const body = Buffer.from(JSON.stringify(frame));
+		if (body.length > this.maxFrameBytes || this.queuedBytes + body.length + 4 > this.maxFrameBytes * 2) return Promise.reject(/* @__PURE__ */ new Error("SSH helper frame or write queue limit exceeded"));
+		const header = Buffer.alloc(4);
+		header.writeUInt32BE(body.length);
+		const bytes = Buffer.concat([header, body]);
+		this.queuedBytes += bytes.length;
+		const write = this.writeTail.then(async () => {
+			if (this.failure !== void 0) throw this.failure;
+			if (!this.output.write(bytes)) await new Promise((resolve, reject) => {
+				const cleanup = () => {
+					this.output.off("drain", drained);
+					this.off("closed", closed);
+				};
+				const drained = () => {
+					cleanup();
+					resolve();
+				};
+				const closed = (error) => {
+					cleanup();
+					reject(error);
+				};
+				this.output.once("drain", drained);
+				this.once("closed", closed);
+				if (this.failure !== void 0) closed(this.failure);
+			});
+		});
+		this.writeTail = write.catch((error) => {
+			this.close(operationError(error));
+		});
+		return write.finally(() => {
+			this.queuedBytes -= bytes.length;
+		});
+	}
+	async readFrames() {
+		const header = Buffer.alloc(4);
+		let headerBytes = 0;
+		let payload;
+		let payloadBytes = 0;
+		for await (const raw of this.input) {
+			const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+			let offset = 0;
+			while (offset < chunk.length) {
+				if (payload === void 0) {
+					const count = Math.min(4 - headerBytes, chunk.length - offset);
+					chunk.copy(header, headerBytes, offset, offset + count);
+					headerBytes += count;
+					offset += count;
+					if (headerBytes < 4) continue;
+					const size = header.readUInt32BE(0);
+					if (size === 0 || size > this.maxFrameBytes) throw new Error("SSH helper sent an invalid frame length");
+					payload = Buffer.alloc(size);
+					payloadBytes = 0;
+				}
+				const count = Math.min(payload.length - payloadBytes, chunk.length - offset);
+				chunk.copy(payload, payloadBytes, offset, offset + count);
+				payloadBytes += count;
+				offset += count;
+				if (payloadBytes === payload.length) {
+					const frame = frameSchema.parse(JSON.parse(payload.toString("utf8")));
+					payload = void 0;
+					headerBytes = 0;
+					this.receive(frame);
+				}
+			}
+		}
+		throw new Error(headerBytes > 0 || payload !== void 0 ? "SSH helper disconnected during a frame; outcome is unknown" : "SSH helper disconnected; outcome is unknown");
+	}
+	receive(frame) {
+		if (frame.type === "result" || frame.type === "error") {
+			const pending = this.pending.get(frame.id);
+			if (pending === void 0) return;
+			this.pending.delete(frame.id);
+			if (frame.type === "result") pending.resolve(frame.value);
+			else pending.reject(new RemoteOperationError(frame.error.message, frame.error.code));
+			return;
+		}
+		if (frame.type === "cancel") {
+			this.active.get(frame.id)?.controller.abort(/* @__PURE__ */ new Error("SSH caller cancelled the operation"));
+			return;
+		}
+		const kind = requestClass(frame.method);
+		if (this.handler === void 0 || this.active.has(frame.id) || this.atCapacity(kind, this.active.values())) throw new Error("SSH helper received an unexpected or excessive request");
+		const controller = new AbortController();
+		this.active.set(frame.id, {
+			controller,
+			requestClass: kind
+		});
+		this.handler(frame.method, frame.params, controller.signal).then((value) => this.send({
+			type: "result",
+			id: frame.id,
+			value: value ?? null
+		}), (error) => {
+			const detail = operationError(error);
+			const code = "code" in detail && typeof detail.code === "string" ? detail.code : void 0;
+			return this.send({
+				type: "error",
+				id: frame.id,
+				error: {
+					name: detail.name,
+					message: detail.message,
+					...code === void 0 ? {} : { code }
+				}
+			});
+		}).catch((error) => {
+			this.close(operationError(error));
+		}).finally(() => {
+			this.active.delete(frame.id);
+		});
+	}
+	atCapacity(kind, requests) {
+		const limit = kind === "ordinary" ? this.maxPending : managementLimits[kind];
+		let count = 0;
+		for (const request of requests) if (request.requestClass === kind) count++;
+		return count >= limit;
+	}
+};
+//#endregion
+export { SshRpcPeer as a, SSH_PROTOCOL_VERSION as i, SSH_MAX_PROCESS_HANDLES as n, SSH_MAX_TEXT_STREAMS as r, RemoteOperationError as t };

package/lib/protocol.js

@@ -0,0 +1,2 @@
+import { a as SshRpcPeer, i as SSH_PROTOCOL_VERSION, n as SSH_MAX_PROCESS_HANDLES, r as SSH_MAX_TEXT_STREAMS, t as RemoteOperationError } from "./protocol-CDhW_IHU.js";
+export { RemoteOperationError, SSH_MAX_PROCESS_HANDLES, SSH_MAX_TEXT_STREAMS, SSH_PROTOCOL_VERSION, SshRpcPeer };

package/lib/schemas-BD3YbDxe.js

@@ -0,0 +1,189 @@
+import "./protocol-CDhW_IHU.js";
+import { z } from "zod";
+//#region lib/types/schemas.js
+/** Strict JSON validation for SSH helper requests and remote observations. */
+/** Admit a process identity from the private helper protocol. */
+const processIdSchema = z.uuid().transform((value) => value);
+/** Admit a text iterator identity from the private helper protocol. */
+const textStreamIdSchema = z.uuid().transform((value) => value);
+/** A remote POSIX absolute path; spelling is preserved until remote canonicalization. */
+const remotePath = z.string().min(1).refine((value) => value.startsWith("/") && !value.includes("\0"), "expected an absolute POSIX path");
+/** Filesystem identity returned by the remote filesystem provider. */
+const targetSchema = z.object({
+	targetKey: remotePath,
+	displayPath: z.string()
+}).strict();
+/** Remote metadata observation. */
+const infoSchema = z.object({
+	version: z.string(),
+	type: z.enum([
+		"file",
+		"directory",
+		"other"
+	]),
+	size: z.number().nonnegative().optional()
+}).strict();
+/** Metadata that preserves a final symlink. */
+const pathInfoSchema = infoSchema.extend({ type: z.enum([
+	"file",
+	"directory",
+	"symlink",
+	"other"
+]) });
+/** A resolved file-effect policy; the remote helper owns path canonicalization. */
+const policySchema = z.object({
+	mode: z.enum([
+		"read-only",
+		"workspace-write",
+		"danger-full-access"
+	]),
+	workspaceRoot: remotePath,
+	sessionId: z.string().optional()
+}).strict();
+/** Complete directory entries. */
+const entriesSchema = z.array(z.object({
+	name: z.string(),
+	type: z.enum([
+		"file",
+		"directory",
+		"other"
+	]),
+	target: targetSchema,
+	version: z.string().optional(),
+	size: z.number().nonnegative().optional()
+}).strict());
+/** Guarded write intent. */
+const intentSchema = z.discriminatedUnion("kind", [z.object({ kind: z.literal("createIfAbsent") }).strict(), z.object({
+	kind: z.literal("replaceIfVersion"),
+	version: z.string()
+}).strict()]);
+/** Literal text edit. */
+const editSchema = z.object({
+	oldString: z.string(),
+	newString: z.string(),
+	replaceAll: z.boolean()
+}).strict();
+/** Atomic write observation. */
+const writeResultSchema = z.object({
+	operation: z.enum(["create", "update"]),
+	version: z.string(),
+	before: z.string().nullable(),
+	after: z.string()
+}).strict();
+/** Atomic edit observation. */
+const editResultSchema = z.object({
+	version: z.string(),
+	before: z.string(),
+	after: z.string()
+}).strict();
+/** Explicit child environment; null encodes an environment tombstone. */
+const environmentSchema = z.record(z.string(), z.string().nullable());
+const collection = z.object({
+	maxBytes: z.number().int().positive(),
+	spill: z.object({ maxBytes: z.number().int().positive() }).strict().optional()
+}).strict();
+/** Ordinary or terminal process requested by a trusted SSH client. */
+const spawnSchema = z.object({
+	argv: z.array(z.string().refine((value) => !value.includes("\0"))).min(1),
+	cwd: remotePath,
+	env: environmentSchema.optional(),
+	graceMs: z.number().int().positive().max(2147483647),
+	stdio: z.object({
+		stdin: z.union([
+			z.literal("ignore"),
+			z.literal("pipe"),
+			z.object({ data: z.string() }).strict()
+		]),
+		stdout: z.union([
+			z.literal("pipe"),
+			z.literal("inherit"),
+			collection
+		]),
+		stderr: z.union([
+			z.literal("pipe"),
+			z.literal("inherit"),
+			collection
+		]),
+		control: z.literal("pipe").optional()
+	}).strict().optional(),
+	terminal: z.object({
+		terminalType: z.string().min(1),
+		rows: z.number().int().positive(),
+		cols: z.number().int().positive(),
+		shellActivity: z.boolean().optional()
+	}).strict().optional()
+}).strict().refine((value) => value.stdio === void 0 !== (value.terminal === void 0), "select ordinary or terminal execution");
+/** Connection handshake binds sockets and workspace to one helper process. */
+const helloSchema = z.object({
+	protocol: z.literal(2),
+	hash: z.string().regex(/^[0-9a-f]{64}$/),
+	kind: z.enum(["node-script", "executable"]),
+	platform: z.enum(["linux", "darwin"]),
+	nodeVersion: z.string(),
+	executable: remotePath,
+	root: remotePath,
+	workspace: remotePath,
+	bootstrapHash: z.string().regex(/^[0-9a-f]{64}$/).optional()
+}).strict();
+/** A prepared process publishes its sockets before target code may execute. */
+const streamEndpointSchema = z.object({
+	path: remotePath,
+	capability: z.string().regex(/^[0-9a-f]{64}$/)
+}).strict();
+/** Prepared process and its independently authenticated stream endpoints. */
+const preparedSchema = z.object({
+	id: processIdSchema,
+	streams: z.partialRecord(z.enum([
+		"stdin",
+		"stdout",
+		"stderr",
+		"control",
+		"terminal"
+	]), streamEndpointSchema)
+}).strict();
+/** Direct process exit facts. */
+const outcomeSchema = z.object({
+	exitCode: z.number().int().nullable(),
+	signal: z.string().nullable()
+}).strict();
+/** A bounded raw tail positioned in whole-stream byte coordinates. */
+const outputSnapshotSchema = z.object({
+	tail: z.base64(),
+	totalBytes: z.number().int().nonnegative()
+}).strict();
+/**
+* Bound one encoded tail and its RPC envelope by the declared collection budget.
+* @param maxBytes - the collector's retained raw-byte limit.
+* @returns the private snapshot frame limit, capped by the helper protocol ceiling.
+*/
+function outputSnapshotFrameLimit(maxBytes) {
+	return Math.min(64 * 1024 * 1024, maxBytes * 2 + 1024);
+}
+/** Direct exit, retained output snapshots, and optional complete spill locations. */
+const doneSchema = z.object({
+	outcome: outcomeSchema,
+	spills: z.object({
+		stdout: remotePath.optional(),
+		stderr: remotePath.optional()
+	}).strict(),
+	collected: z.object({
+		stdout: outputSnapshotSchema.optional(),
+		stderr: outputSnapshotSchema.optional()
+	}).strict()
+}).strict();
+/** Remote terminal foreground observation. */
+const foregroundSchema = z.object({
+	processGroupId: z.number().int().positive(),
+	inputWaiting: z.boolean()
+}).strict().nullable();
+/** Conservative shell lifecycle and process observation returned by the execution provider. */
+const terminalActivitySchema = z.object({
+	state: z.enum([
+		"idle",
+		"busy",
+		"unknown"
+	]),
+	revision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)
+}).strict();
+//#endregion
+export { writeResultSchema as C, textStreamIdSchema as S, remotePath as _, environmentSchema as a, targetSchema as b, infoSchema as c, outputSnapshotFrameLimit as d, outputSnapshotSchema as f, processIdSchema as g, preparedSchema as h, entriesSchema as i, intentSchema as l, policySchema as m, editResultSchema as n, foregroundSchema as o, pathInfoSchema as p, editSchema as r, helloSchema as s, doneSchema as t, outcomeSchema as u, spawnSchema as v, terminalActivitySchema as x, streamEndpointSchema as y };

package/lib/schemas.js

@@ -0,0 +1,2 @@
+import { C as writeResultSchema, S as textStreamIdSchema, _ as remotePath, a as environmentSchema, b as targetSchema, c as infoSchema, d as outputSnapshotFrameLimit, f as outputSnapshotSchema, g as processIdSchema, h as preparedSchema, i as entriesSchema, l as intentSchema, m as policySchema, n as editResultSchema, o as foregroundSchema, p as pathInfoSchema, r as editSchema, s as helloSchema, t as doneSchema, u as outcomeSchema, v as spawnSchema, x as terminalActivitySchema, y as streamEndpointSchema } from "./schemas-BD3YbDxe.js";
+export { doneSchema, editResultSchema, editSchema, entriesSchema, environmentSchema, foregroundSchema, helloSchema, infoSchema, intentSchema, outcomeSchema, outputSnapshotFrameLimit, outputSnapshotSchema, pathInfoSchema, policySchema, preparedSchema, processIdSchema, remotePath, spawnSchema, streamEndpointSchema, targetSchema, terminalActivitySchema, textStreamIdSchema, writeResultSchema };

package/lib/stream-security-DJlQsPG-.js

@@ -0,0 +1,75 @@
+import { connect } from "node:tls";
+//#region lib/types/stream-security.js
+/** TLS-PSK authenticates forwarded streams even when a remote pathname is replaced. */
+/** Certificate-free PSK authentication and AEAD records; no unauthenticated cipher fallback. */
+const SSH_STREAM_TLS_OPTIONS = {
+	ciphers: "PSK-AES256-GCM-SHA384",
+	minVersion: "TLSv1.2",
+	maxVersion: "TLSv1.2"
+};
+/**
+* Authenticate a forwarded socket with its private administrative-channel key.
+* @param socket - the connected OpenSSH forwarding socket.
+* @param capability - the per-stream 256-bit key encoded as hexadecimal.
+* @param timeoutMs - deadline for completing TLS authentication.
+* @param signal - cancellation of authentication and the resulting TLS stream.
+* @returns an authenticated paused stream; the key is never transmitted as data.
+*/
+async function authenticateStream(socket, capability, timeoutMs, signal) {
+	if (signal?.aborted) {
+		socket.destroy();
+		signal.throwIfAborted();
+	}
+	const stream = connect({
+		...SSH_STREAM_TLS_OPTIONS,
+		socket,
+		rejectUnauthorized: true,
+		pskCallback: () => ({
+			psk: Buffer.from(capability, "hex"),
+			identity: "dsh-stream"
+		}),
+		checkServerIdentity: () => void 0
+	});
+	const abort = () => {
+		stream.destroy(signal?.reason instanceof Error ? signal.reason : new Error(String(signal?.reason)));
+	};
+	signal?.addEventListener("abort", abort, { once: true });
+	stream.once("close", () => {
+		signal?.removeEventListener("abort", abort);
+	});
+	try {
+		await new Promise((resolve, reject) => {
+			const cleanup = () => {
+				stream.off("secureConnect", secured);
+				stream.off("error", failed);
+				stream.off("close", closed);
+				clearTimeout(timer);
+			};
+			const secured = () => {
+				cleanup();
+				stream.disableRenegotiation();
+				stream.pause();
+				resolve();
+			};
+			const failed = (error) => {
+				cleanup();
+				reject(error);
+			};
+			const closed = () => {
+				failed(/* @__PURE__ */ new Error("SSH stream closed during authentication"));
+			};
+			const timer = setTimeout(() => {
+				failed(/* @__PURE__ */ new Error("SSH stream authentication timed out"));
+			}, timeoutMs);
+			stream.once("secureConnect", secured);
+			stream.once("error", failed);
+			stream.once("close", closed);
+		});
+		return stream;
+	} catch (error) {
+		stream.destroy();
+		throw error;
+	}
+}
+//#endregion
+export { authenticateStream as n, SSH_STREAM_TLS_OPTIONS as t };

package/lib/types/index.d.ts

@@ -0,0 +1,121 @@
+/** OpenSSH connection owner for version-matched POSIX helpers, one per login, and their independent forwarded streams. */
+import { type Socket } from 'node:net';
+import { Context, Service } from '@deepseek-ai/cordis';
+import schema from '@deepseek-ai/schemastery';
+import { z } from 'zod';
+import { helloSchema, type SshStreamEndpoint } from './schemas.ts';
+type Hello = z.infer<typeof helloSchema>;
+/** Installed helper invocation; script deployments may also install a PTC bootstrap. */
+export type HelperLaunch = {
+    /** Run the installed script with a separately installed Node executable. */
+    kind: 'node-script';
+    /** Absolute remote Node executable. */
+    node: string;
+    /** Absolute remote PTC bootstrap; requires bootstrapHash. */
+    bootstrapPath?: string;
+    /** Lowercase SHA-256 of bootstrapPath; requires that path. */
+    bootstrapHash?: string;
+} | {
+    /** Run the helper executable with its embedded Node and PTC worker. */
+    kind: 'executable';
+};
+/** Deployment-owned SSH identity and installed helper; no model argument selects these values. */
+export interface Config {
+    /** OpenSSH host alias, including its existing user, key and known-host configuration. */
+    host: string;
+    /** Explicit script or self-contained executable invocation. */
+    launch: HelperLaunch;
+    /** Absolute path to the installed, bundled helper entry. */
+    helper: string;
+    /** SHA-256 of that bundled helper; mismatches refuse the connection. */
+    helperHash: string;
+    /** Absolute remote default workspace. */
+    workspace: string;
+    /** Connection and administrative-request deadline, at most 2,147,483,647 milliseconds. */
+    requestTimeoutMs?: number;
+    /** Maximum JSON payload bytes per helper request or response. */
+    maxFrameBytes?: number;
+    /** Maximum ordinary requests; heartbeat and bounded resource cleanup have reserved capacity. */
+    maxPending?: number;
+    /** Remote helper lease; loss of heartbeats starts remote managed cleanup. */
+    leaseMs?: number;
+    /** Idle time after which a connection opened for a bound login closes; it reopens on the next request. */
+    loginIdleMs?: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        ssh: SshConnection;
+    }
+}
+/**
+ * The deployment's SSH service. Every operation runs on the alias's own login
+ * unless the Agent driving it was bound to another login with
+ * {@link SshConnection.bindLogin}; that Agent's operations then run on a
+ * connection authenticated as the bound login, opened on first use and closed
+ * after `loginIdleMs` without work. A process, terminal or text stream stays on
+ * the connection that created it, whoever later observes or cancels it.
+ */
+export declare class SshConnection extends Service {
+    static Config: schema<Config>;
+    /** Verified remote helper coordinates of the alias's own login; callers must await this before launch. */
+    readonly ready: Promise<Hello>;
+    private readonly config;
+    private readonly primary;
+    /** Login each bound Agent runs as. */
+    private readonly bindings;
+    private readonly logins;
+    private readonly idle;
+    /** Helper-issued handle ids and the channel whose helper issued them. */
+    private readonly handles;
+    private closed;
+    private disposal;
+    constructor(ctx: Context, config: Config);
+    /** Hold plugin readiness until the remote identity and helper digest are verified. */
+    [Service.init](): Promise<void>;
+    /** Verified remote PTC launch configuration; script deployments require a verified bootstrap. */
+    get ptcLaunch(): {
+        kind: 'embedded';
+        executable: string;
+    } | {
+        kind: 'node-script';
+        executable: string;
+        bootstrapPath: string;
+    };
+    /**
+     * Run every operation an Agent drives as `login` instead of the alias's own
+     * login. The remote host must accept the alias's key for that login. An
+     * Agent's operations are those made while it is the current initiator
+     * (`ctx.agents.currentInitiator()`); operations outside any initiator, or
+     * inside `ctx.agents.withoutInitiator()`, keep the alias's own login.
+     * @param agent - the Agent to bind; a child Agent it creates is not bound.
+     * @param login - remote login name.
+     * @returns a disposer that removes the binding; register it as an effect of the Agent's context.
+     * @throws when `login` is not a valid login name or the Agent is already bound.
+     */
+    bindLogin(agent: object, login: string): () => void;
+    /**
+     * Send a helper operation; cancellation never replays an ambiguous mutation.
+     * @param method - the private helper operation.
+     * @param params - JSON request fields validated by the helper.
+     * @param result - response validation before returning provider-visible data.
+     * @param signal - cancellation, which does not undo completed remote effects.
+     * @param wait - allow a process observation to outlast the administrative deadline.
+     * @returns the validated remote result.
+     */
+    request<T>(method: string, params: unknown, result: z.ZodType<T>, signal?: AbortSignal, wait?: boolean): Promise<T>;
+    /**
+     * Forward one authenticated stream through an independent SSH channel.
+     * @param endpoint - private coordinates issued by one of this service's helpers.
+     * @param signal - cancellation of allocation and the resulting socket.
+     * @returns a paused socket; attach a consumer before resuming it.
+     */
+    connectStream(endpoint: SshStreamEndpoint, signal?: AbortSignal): Promise<Socket>;
+    /** Tear down every helper's remote managed ranges before releasing their SSH masters when reachable. */
+    dispose(): Promise<void>;
+    /** The channel for the Agent driving the current operation. */
+    private channelForInitiator;
+    /** Close a login channel once it holds no work and no handles for `loginIdleMs`. */
+    private scheduleIdle;
+}
+export default SshConnection;
+//# sourceMappingURL=index.d.ts.map