@junwu168/openshell 0.1.0

package/dist/core/orchestrator.js

@@ -0,0 +1,825 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { applyUnifiedPatch } from "./patch";
+import { classifyRemoteExec } from "./policy";
+import { errorResult, okResult, partialFailureResult } from "./result";
+const quoteShell = (value) => `'${value.replaceAll("'", `'\"'\"'`)}'`;
+const authError = (tool, server, code, message) => errorResult({
+    tool,
+    server: server.id,
+    code,
+    message,
+    execution: { attempted: false, completed: false },
+    audit: { logWritten: false, snapshotStatus: "not-applicable" },
+});
+const resolveAuthPath = (server, pathValue) => {
+    if (isAbsolute(pathValue)) {
+        return { path: pathValue };
+    }
+    if (server.scope !== "workspace" || !server.workspaceRoot) {
+        return {
+            code: "AUTH_PATH_INVALID",
+            message: `Relative auth paths are only allowed for workspace-scoped records: ${pathValue}`,
+        };
+    }
+    return {
+        path: resolve(server.workspaceRoot, pathValue),
+    };
+};
+const readAuthFile = (server, tool, pathValue, missingCode) => {
+    const resolved = resolveAuthPath(server, pathValue);
+    if ("code" in resolved) {
+        return authError(tool, server, resolved.code, resolved.message);
+    }
+    try {
+        return { content: readFileSync(resolved.path, "utf8") };
+    }
+    catch (error) {
+        const errno = error.code;
+        if (errno === "ENOENT") {
+            return authError(tool, server, missingCode, `Auth file not found: ${resolved.path}`);
+        }
+        return authError(tool, server, "AUTH_PATH_UNREADABLE", `Auth file is unreadable: ${resolved.path}`);
+    }
+};
+const toConnectConfig = (tool, server) => {
+    const base = {
+        host: server.host,
+        port: server.port,
+        username: server.username,
+    };
+    switch (server.auth.kind) {
+        case "password":
+            return {
+                ...base,
+                password: server.auth.secret,
+            };
+        case "privateKey": {
+            const privateKey = readAuthFile(server, tool, server.auth.privateKeyPath, "KEY_PATH_NOT_FOUND");
+            if ("status" in privateKey) {
+                return privateKey;
+            }
+            return {
+                ...base,
+                privateKey: privateKey.content,
+                ...(server.auth.passphrase ? { passphrase: server.auth.passphrase } : {}),
+            };
+        }
+        case "certificate": {
+            const certificate = readAuthFile(server, tool, server.auth.certificatePath, "CERTIFICATE_PATH_NOT_FOUND");
+            if ("status" in certificate) {
+                return certificate;
+            }
+            const privateKey = readAuthFile(server, tool, server.auth.privateKeyPath, "KEY_PATH_NOT_FOUND");
+            if ("status" in privateKey) {
+                return privateKey;
+            }
+            return {
+                ...base,
+                privateKey: privateKey.content,
+                ...(server.auth.passphrase ? { passphrase: server.auth.passphrase } : {}),
+            };
+        }
+    }
+};
+const withAuditFlag = (status, payload, logWritten) => {
+    const next = {
+        ...payload,
+        audit: {
+            logWritten,
+            snapshotStatus: payload.audit?.snapshotStatus ?? "not-applicable",
+        },
+    };
+    if (status === "ok") {
+        return okResult(next);
+    }
+    if (status === "partial_failure") {
+        return partialFailureResult(next);
+    }
+    return errorResult(next);
+};
+const byteLength = (value) => Buffer.byteLength(value);
+const clampLimit = (value, fallback) => Math.max(1, Math.trunc(value ?? fallback));
+export const createOrchestrator = ({ registry, ssh, audit, policy = { classifyRemoteExec } }) => {
+    const appendLogSafe = async (entry) => {
+        try {
+            await audit.appendLog(entry);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const isRegistryValidationError = (error) => typeof error === "object" &&
+        error !== null &&
+        error.code === "REGISTRY_RECORD_INVALID" &&
+        typeof error.message === "string";
+    const preflightLog = async (tool, server) => {
+        try {
+            await audit.preflightLog();
+            return null;
+        }
+        catch (error) {
+            return errorResult({
+                tool,
+                server,
+                code: "AUDIT_LOG_PREFLIGHT_FAILED",
+                message: error.message,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            });
+        }
+    };
+    const logAuthFailure = async (tool, approvalStatus, logEntry, result) => {
+        const logWritten = await appendLogSafe({
+            ...logEntry,
+            tool,
+            server: result.server,
+            approvalStatus,
+            code: result.code,
+            message: result.message,
+        });
+        return withAuditFlag("error", result, logWritten);
+    };
+    const resolveServer = async (tool, serverId, logEntry, approvalStatus) => {
+        let server;
+        try {
+            server = await registry.resolve(serverId);
+        }
+        catch (error) {
+            if (isRegistryValidationError(error)) {
+                const payload = {
+                    tool,
+                    server: serverId,
+                    code: error.code,
+                    message: error.message,
+                    execution: { attempted: false, completed: false },
+                    audit: { logWritten: false, snapshotStatus: "not-applicable" },
+                };
+                const logWritten = await appendLogSafe({
+                    ...logEntry,
+                    tool,
+                    server: serverId,
+                    approvalStatus,
+                    code: error.code,
+                    message: error.message,
+                });
+                return {
+                    result: withAuditFlag("error", payload, logWritten),
+                    server: null,
+                };
+            }
+            const payload = {
+                tool,
+                server: serverId,
+                code: "SERVER_RESOLVE_FAILED",
+                message: error.message,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                ...logEntry,
+                tool,
+                server: serverId,
+                approvalStatus,
+                code: "SERVER_RESOLVE_FAILED",
+                message: payload.message,
+            });
+            return {
+                result: withAuditFlag("error", payload, logWritten),
+                server: null,
+            };
+        }
+        if (!server) {
+            const payload = {
+                tool,
+                server: serverId,
+                code: "SERVER_NOT_FOUND",
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                ...logEntry,
+                tool,
+                server: serverId,
+                approvalStatus,
+                code: "SERVER_NOT_FOUND",
+            });
+            return {
+                result: withAuditFlag("error", payload, logWritten),
+                server: null,
+            };
+        }
+        return {
+            result: null,
+            server,
+        };
+    };
+    const listServers = async () => {
+        const logReady = await preflightLog("list_servers");
+        if (logReady) {
+            return logReady;
+        }
+        try {
+            const servers = await registry.list();
+            const data = servers.map(({ auth: _auth, workspaceRoot: _workspaceRoot, ...server }) => server);
+            const payload = {
+                tool: "list_servers",
+                data,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "list_servers",
+                approvalStatus: "not-required",
+                count: data.length,
+            });
+            return withAuditFlag("ok", payload, logWritten);
+        }
+        catch (error) {
+            if (isRegistryValidationError(error)) {
+                const payload = {
+                    tool: "list_servers",
+                    code: error.code,
+                    message: error.message,
+                    execution: { attempted: false, completed: false },
+                    audit: { logWritten: false, snapshotStatus: "not-applicable" },
+                };
+                const logWritten = await appendLogSafe({
+                    tool: "list_servers",
+                    approvalStatus: "not-required",
+                    code: error.code,
+                    message: payload.message,
+                });
+                return withAuditFlag("error", payload, logWritten);
+            }
+            const payload = {
+                tool: "list_servers",
+                code: "REGISTRY_LIST_FAILED",
+                message: error.message,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "list_servers",
+                approvalStatus: "not-required",
+                code: "REGISTRY_LIST_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+    };
+    const remoteExec = async (input) => {
+        const logReady = await preflightLog("remote_exec", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const classification = policy.classifyRemoteExec(input.command);
+        const approvalStatus = classification.decision === "approval-required" ? "host-managed-required" : "not-required";
+        const resolved = await resolveServer("remote_exec", input.server, { command: input.command, cwd: input.cwd, timeout: input.timeout }, "unknown");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        if (classification.decision === "reject") {
+            const payload = {
+                tool: "remote_exec",
+                server: input.server,
+                code: "POLICY_REJECTED",
+                message: classification.reason,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_exec",
+                server: input.server,
+                command: input.command,
+                cwd: input.cwd,
+                timeout: input.timeout,
+                approvalStatus: "not-required",
+                code: "POLICY_REJECTED",
+                message: classification.reason,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        try {
+            const connection = toConnectConfig("remote_exec", resolved.server);
+            if ("status" in connection) {
+                return logAuthFailure("remote_exec", approvalStatus, { command: input.command, cwd: input.cwd, timeout: input.timeout }, connection);
+            }
+            const executed = await ssh.exec(connection, input.command, {
+                cwd: input.cwd,
+                timeout: input.timeout,
+            });
+            const payload = {
+                tool: "remote_exec",
+                server: input.server,
+                data: executed,
+                execution: {
+                    attempted: true,
+                    completed: true,
+                    exitCode: executed.exitCode,
+                    stdoutBytes: byteLength(executed.stdout),
+                    stderrBytes: byteLength(executed.stderr),
+                },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_exec",
+                server: input.server,
+                command: input.command,
+                cwd: input.cwd,
+                timeout: input.timeout,
+                approvalStatus,
+                policyDecision: classification.decision,
+                approvalRequired: classification.decision === "approval-required",
+                ...executed,
+            });
+            return withAuditFlag("ok", payload, logWritten);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_exec",
+                server: input.server,
+                code: "SSH_EXEC_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_exec",
+                server: input.server,
+                command: input.command,
+                cwd: input.cwd,
+                timeout: input.timeout,
+                approvalStatus,
+                code: "SSH_EXEC_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+    };
+    const remoteReadFile = async (input) => {
+        const logReady = await preflightLog("remote_read_file", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const resolved = await resolveServer("remote_read_file", input.server, { path: input.path, offset: input.offset, length: input.length }, "not-required");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        try {
+            const connection = toConnectConfig("remote_read_file", resolved.server);
+            if ("status" in connection) {
+                return logAuthFailure("remote_read_file", "not-required", { path: input.path, offset: input.offset, length: input.length }, connection);
+            }
+            const body = await ssh.readFile(connection, input.path);
+            const offset = input.offset ?? 0;
+            const content = body.slice(offset, input.length ? offset + input.length : undefined);
+            const payload = {
+                tool: "remote_read_file",
+                server: input.server,
+                data: { content },
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_read_file",
+                server: input.server,
+                path: input.path,
+                offset: input.offset,
+                length: input.length,
+                approvalStatus: "not-required",
+            });
+            return withAuditFlag("ok", payload, logWritten);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_read_file",
+                server: input.server,
+                code: "SSH_READ_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_read_file",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "not-required",
+                code: "SSH_READ_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+    };
+    const remoteWriteFile = async (input) => {
+        const logReady = await preflightLog("remote_write_file", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const resolved = await resolveServer("remote_write_file", input.server, { path: input.path, mode: input.mode }, "host-managed-required");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        const connection = toConnectConfig("remote_write_file", resolved.server);
+        if ("status" in connection) {
+            return logAuthFailure("remote_write_file", "host-managed-required", { path: input.path, mode: input.mode }, connection);
+        }
+        try {
+            await (audit.preflightSnapshots?.() ?? Promise.resolve());
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_write_file",
+                server: input.server,
+                code: "AUDIT_SNAPSHOT_PREFLIGHT_FAILED",
+                message: error.message,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_write_file",
+                server: input.server,
+                path: input.path,
+                mode: input.mode,
+                approvalStatus: "host-managed-required",
+                code: "AUDIT_SNAPSHOT_PREFLIGHT_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        const before = await ssh.readFile(connection, input.path).catch(() => "");
+        try {
+            await ssh.writeFile(connection, input.path, input.content, input.mode);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_write_file",
+                server: input.server,
+                code: "SSH_WRITE_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_write_file",
+                server: input.server,
+                path: input.path,
+                mode: input.mode,
+                approvalStatus: "host-managed-required",
+                approvalRequired: true,
+                code: "SSH_WRITE_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        const after = await ssh.readFile(connection, input.path).catch(() => input.content);
+        const logWritten = await appendLogSafe({
+            tool: "remote_write_file",
+            server: input.server,
+            path: input.path,
+            mode: input.mode,
+            changedPath: input.path,
+            approvalStatus: "host-managed-required",
+            approvalRequired: true,
+        });
+        try {
+            await (audit.captureSnapshots?.({ server: input.server, path: input.path, before, after }) ?? Promise.resolve());
+            const payload = {
+                tool: "remote_write_file",
+                server: input.server,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "written" },
+            };
+            if (!logWritten) {
+                return withAuditFlag("partial_failure", {
+                    ...payload,
+                    message: "remote write succeeded but audit log write failed",
+                    audit: { logWritten: false, snapshotStatus: "written" },
+                }, false);
+            }
+            return withAuditFlag("ok", payload, true);
+        }
+        catch (error) {
+            return withAuditFlag("partial_failure", {
+                tool: "remote_write_file",
+                server: input.server,
+                message: `remote write succeeded but audit finalization failed: ${error.message}`,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "partial-failure" },
+            }, logWritten);
+        }
+    };
+    const remotePatchFile = async (input) => {
+        const logReady = await preflightLog("remote_patch_file", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const resolved = await resolveServer("remote_patch_file", input.server, { path: input.path }, "host-managed-required");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        const connection = toConnectConfig("remote_patch_file", resolved.server);
+        if ("status" in connection) {
+            return logAuthFailure("remote_patch_file", "host-managed-required", { path: input.path }, connection);
+        }
+        let before;
+        try {
+            before = await ssh.readFile(connection, input.path);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_patch_file",
+                server: input.server,
+                code: "SSH_READ_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_patch_file",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "host-managed-required",
+                code: "SSH_READ_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        let after;
+        try {
+            after = applyUnifiedPatch(before, input.patch);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_patch_file",
+                server: input.server,
+                code: "PATCH_APPLY_FAILED",
+                message: error.message,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_patch_file",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "host-managed-required",
+                code: "PATCH_APPLY_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        try {
+            await (audit.preflightSnapshots?.() ?? Promise.resolve());
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_patch_file",
+                server: input.server,
+                code: "AUDIT_SNAPSHOT_PREFLIGHT_FAILED",
+                message: error.message,
+                execution: { attempted: false, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_patch_file",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "host-managed-required",
+                code: "AUDIT_SNAPSHOT_PREFLIGHT_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        try {
+            await ssh.writeFile(connection, input.path, after);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_patch_file",
+                server: input.server,
+                code: "SSH_WRITE_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_patch_file",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "host-managed-required",
+                approvalRequired: true,
+                code: "SSH_WRITE_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+        const logWritten = await appendLogSafe({
+            tool: "remote_patch_file",
+            server: input.server,
+            path: input.path,
+            changedPath: input.path,
+            approvalStatus: "host-managed-required",
+            approvalRequired: true,
+        });
+        try {
+            await (audit.captureSnapshots?.({ server: input.server, path: input.path, before, after }) ?? Promise.resolve());
+            const payload = {
+                tool: "remote_patch_file",
+                server: input.server,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "written" },
+            };
+            if (!logWritten) {
+                return withAuditFlag("partial_failure", {
+                    ...payload,
+                    message: "remote patch succeeded but audit log write failed",
+                    audit: { logWritten: false, snapshotStatus: "written" },
+                }, false);
+            }
+            return withAuditFlag("ok", payload, true);
+        }
+        catch (error) {
+            return withAuditFlag("partial_failure", {
+                tool: "remote_patch_file",
+                server: input.server,
+                message: `remote patch succeeded but audit finalization failed: ${error.message}`,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "partial-failure" },
+            }, logWritten);
+        }
+    };
+    const remoteListDir = async (input) => {
+        const logReady = await preflightLog("remote_list_dir", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const resolved = await resolveServer("remote_list_dir", input.server, { path: input.path, recursive: input.recursive, limit: input.limit }, "not-required");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        try {
+            const connection = toConnectConfig("remote_list_dir", resolved.server);
+            if ("status" in connection) {
+                return logAuthFailure("remote_list_dir", "not-required", { path: input.path, recursive: input.recursive ?? false, limit: input.limit ?? 200 }, connection);
+            }
+            const entries = await ssh.listDir(connection, input.path, input.recursive ?? false, input.limit ?? 200);
+            const payload = {
+                tool: "remote_list_dir",
+                server: input.server,
+                data: entries,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_list_dir",
+                server: input.server,
+                path: input.path,
+                recursive: input.recursive ?? false,
+                limit: input.limit ?? 200,
+                approvalStatus: "not-required",
+            });
+            return withAuditFlag("ok", payload, logWritten);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_list_dir",
+                server: input.server,
+                code: "SSH_LIST_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_list_dir",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "not-required",
+                code: "SSH_LIST_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+    };
+    const remoteStat = async (input) => {
+        const logReady = await preflightLog("remote_stat", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const resolved = await resolveServer("remote_stat", input.server, { path: input.path }, "not-required");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        try {
+            const connection = toConnectConfig("remote_stat", resolved.server);
+            if ("status" in connection) {
+                return logAuthFailure("remote_stat", "not-required", { path: input.path }, connection);
+            }
+            const stat = await ssh.stat(connection, input.path);
+            const payload = {
+                tool: "remote_stat",
+                server: input.server,
+                data: stat,
+                execution: { attempted: true, completed: true },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_stat",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "not-required",
+            });
+            return withAuditFlag("ok", payload, logWritten);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_stat",
+                server: input.server,
+                code: "SSH_STAT_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_stat",
+                server: input.server,
+                path: input.path,
+                approvalStatus: "not-required",
+                code: "SSH_STAT_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+    };
+    const remoteFind = async (input) => {
+        const logReady = await preflightLog("remote_find", input.server);
+        if (logReady) {
+            return logReady;
+        }
+        const resolved = await resolveServer("remote_find", input.server, { path: input.path, pattern: input.pattern, glob: input.glob, limit: input.limit }, "not-required");
+        if (resolved.result) {
+            return resolved.result;
+        }
+        const limit = clampLimit(input.limit, 200);
+        const command = input.glob
+            ? `find ${quoteShell(input.path)} -name ${quoteShell(input.glob)} | head -n ${limit}`
+            : `grep -R -n ${quoteShell(input.pattern)} ${quoteShell(input.path)} | head -n ${limit}`;
+        try {
+            const connection = toConnectConfig("remote_find", resolved.server);
+            if ("status" in connection) {
+                return logAuthFailure("remote_find", "not-required", { path: input.path, pattern: input.pattern, glob: input.glob, limit: input.limit }, connection);
+            }
+            const executed = await ssh.exec(connection, command);
+            const payload = {
+                tool: "remote_find",
+                server: input.server,
+                data: executed,
+                execution: {
+                    attempted: true,
+                    completed: true,
+                    exitCode: executed.exitCode,
+                    stdoutBytes: byteLength(executed.stdout),
+                    stderrBytes: byteLength(executed.stderr),
+                },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_find",
+                server: input.server,
+                command,
+                approvalStatus: "not-required",
+                ...executed,
+            });
+            return withAuditFlag("ok", payload, logWritten);
+        }
+        catch (error) {
+            const payload = {
+                tool: "remote_find",
+                server: input.server,
+                code: "SSH_FIND_FAILED",
+                message: error.message,
+                execution: { attempted: true, completed: false },
+                audit: { logWritten: false, snapshotStatus: "not-applicable" },
+            };
+            const logWritten = await appendLogSafe({
+                tool: "remote_find",
+                server: input.server,
+                command,
+                approvalStatus: "not-required",
+                code: "SSH_FIND_FAILED",
+                message: payload.message,
+            });
+            return withAuditFlag("error", payload, logWritten);
+        }
+    };
+    return {
+        listServers,
+        remoteExec,
+        remoteReadFile,
+        remoteWriteFile,
+        remotePatchFile,
+        remoteListDir,
+        remoteStat,
+        remoteFind,
+    };
+};